@dollhousemcp/mcp-server/dist/collection/CollectionIndexManager.d.ts

DollhouseMCP - A Model Context Protocol (MCP) server that enables dynamic AI persona management from markdown files, allowing Claude and other compatible AI assistants to activate and switch between different behavioral personas.

/**
 * Collection Index Manager with Background Refresh and Robust Caching
 *
 * This manager implements:
 * - 1-hour TTL with local file caching
 * - Background refresh without blocking operations
 * - Exponential backoff retry logic
 * - Configurable timeouts via environment variables
 * - Return stale cache while refreshing in background
 * - Comprehensive error handling for production use
 */
import { CollectionIndex } from '../types/collection';
import { IFileOperationsService } from '../services/FileOperationsService.js';
export interface CollectionIndexCacheEntry {
    data: CollectionIndex;
    timestamp: number;
    etag?: string;
    lastModified?: string;
    version: string;
    checksum: string;
}
export interface CollectionIndexManagerConfig {
    ttlMs?: number;
    fetchTimeoutMs?: number;
    maxRetries?: number;
    baseRetryDelayMs?: number;
    maxRetryDelayMs?: number;
    cacheDir?: string;
    fileOperations: IFileOperationsService;
}
export declare class CollectionIndexManager {
    private readonly INDEX_URL;
    private readonly TTL_MS;
    private readonly FETCH_TIMEOUT_MS;
    private readonly MAX_RETRIES;
    private readonly BASE_RETRY_DELAY_MS;
    private readonly MAX_RETRY_DELAY_MS;
    private readonly CACHE_FILE;
    private cachedIndex;
    private backgroundRefreshPromise;
    private isRefreshing;
    private circuitBreakerFailures;
    private circuitBreakerLastFailure;
    private readonly CIRCUIT_BREAKER_THRESHOLD;
    private readonly CIRCUIT_BREAKER_TIMEOUT_MS;
    private readonly REFRESH_THRESHOLD;
    private readonly JITTER_FACTOR;
    private readonly fileOperations;
    private readonly DEFAULT_TTL_MS;
    private readonly DEFAULT_MAX_RETRIES;
    private readonly DEFAULT_BASE_RETRY_DELAY_MS;
    private readonly DEFAULT_MAX_RETRY_DELAY_MS;
    private readonly DEFAULT_FETCH_TIMEOUT_MS;
    private readonly CHECKSUM_LENGTH;
    private readonly JSON_INDENT;
    constructor(config: CollectionIndexManagerConfig);
    /**
     * Parse fetch timeout from config or environment variable
     */
    private parseFetchTimeout;
    /**
     * Get collection index with stale-while-revalidate pattern
     * Returns cached data immediately if available, refreshes in background
     */
    getIndex(): Promise<CollectionIndex>;
    /**
     * Force refresh the collection index
     */
    forceRefresh(): Promise<CollectionIndex>;
    /**
     * Check if cache should be refreshed (within TTL but getting close to expiry)
     */
    private shouldRefreshCache;
    /**
     * Check if cache is expired
     */
    private isCacheExpired;
    /**
     * Start background refresh without blocking
     */
    private startBackgroundRefresh;
    /**
     * Perform background refresh
     */
    private performBackgroundRefresh;
    /**
     * Fetch collection index with retry logic and exponential backoff
     */
    private fetchWithRetry;
    /**
     * Calculate retry delay with exponential backoff and jitter
     */
    private calculateRetryDelay;
    /**
     * Add jitter (±25% randomness) to a delay to prevent thundering herd problems
     */
    private addJitter;
    /**
     * Fetch collection index from GitHub
     */
    private fetchCollectionIndex;
    /**
     * Validate collection index structure
     */
    private validateIndexStructure;
    /**
     * Update cache with new data
     */
    private updateCache;
    /**
     * Calculate checksum for data integrity verification
     */
    private calculateChecksum;
    /**
     * Load cache from disk
     */
    private loadFromDisk;
    /**
     * Save cache to disk
     */
    private saveToDisk;
    /**
     * Circuit breaker logic
     */
    private isCircuitBreakerOpen;
    private recordCircuitBreakerFailure;
    /**
     * Utility methods
     */
    private sleep;
    private getErrorMessage;
    /**
     * Get cache statistics for monitoring
     */
    getCacheStats(): {
        isValid: boolean;
        age: number;
        hasCache: boolean;
        version?: string;
        totalElements?: number;
        isRefreshing: boolean;
        circuitBreakerFailures: number;
        circuitBreakerOpen: boolean;
    };
    /**
     * Clear all cache data
     */
    clearCache(): Promise<void>;
    /**
     * Wait for any ongoing background refresh to complete
     */
    waitForBackgroundRefresh(): Promise<void>;
}
//# sourceMappingURL=CollectionIndexManager.d.ts.map