@push.rocks/smartregistry 2.2.3 → 2.4.0

package/dist_ts/upstream/classes.circuitbreaker.js

@@ -0,0 +1,192 @@
+import { DEFAULT_RESILIENCE_CONFIG } from './interfaces.upstream.js';
+/**
+ * Circuit breaker implementation for upstream resilience.
+ *
+ * States:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit is tripped, requests fail fast
+ * - HALF_OPEN: Testing if upstream has recovered
+ *
+ * Transitions:
+ * - CLOSED → OPEN: When failure count exceeds threshold
+ * - OPEN → HALF_OPEN: After reset timeout expires
+ * - HALF_OPEN → CLOSED: On successful request
+ * - HALF_OPEN → OPEN: On failed request
+ */
+export class CircuitBreaker {
+    /** Unique identifier for logging and metrics */
+    id;
+    /** Current circuit state */
+    state = 'CLOSED';
+    /** Count of consecutive failures */
+    failureCount = 0;
+    /** Timestamp when circuit was opened */
+    openedAt = 0;
+    /** Number of successful requests in half-open state */
+    halfOpenSuccesses = 0;
+    /** Configuration */
+    config;
+    /** Number of successes required to close circuit from half-open */
+    halfOpenThreshold = 2;
+    constructor(id, config) {
+        this.id = id;
+        this.config = { ...DEFAULT_RESILIENCE_CONFIG, ...config };
+    }
+    /**
+     * Get current circuit state.
+     */
+    getState() {
+        // Check if we should transition from OPEN to HALF_OPEN
+        if (this.state === 'OPEN') {
+            const elapsed = Date.now() - this.openedAt;
+            if (elapsed >= this.config.circuitBreakerResetMs) {
+                this.transitionTo('HALF_OPEN');
+            }
+        }
+        return this.state;
+    }
+    /**
+     * Check if circuit allows requests.
+     * Returns true if requests should be allowed.
+     */
+    canRequest() {
+        const currentState = this.getState();
+        return currentState !== 'OPEN';
+    }
+    /**
+     * Record a successful request.
+     * May transition circuit from HALF_OPEN to CLOSED.
+     */
+    recordSuccess() {
+        if (this.state === 'HALF_OPEN') {
+            this.halfOpenSuccesses++;
+            if (this.halfOpenSuccesses >= this.halfOpenThreshold) {
+                this.transitionTo('CLOSED');
+            }
+        }
+        else if (this.state === 'CLOSED') {
+            // Reset failure count on success
+            this.failureCount = 0;
+        }
+    }
+    /**
+     * Record a failed request.
+     * May transition circuit from CLOSED/HALF_OPEN to OPEN.
+     */
+    recordFailure() {
+        if (this.state === 'HALF_OPEN') {
+            // Any failure in half-open immediately opens circuit
+            this.transitionTo('OPEN');
+        }
+        else if (this.state === 'CLOSED') {
+            this.failureCount++;
+            if (this.failureCount >= this.config.circuitBreakerThreshold) {
+                this.transitionTo('OPEN');
+            }
+        }
+    }
+    /**
+     * Force circuit to open state.
+     * Useful for manual intervention or external health checks.
+     */
+    forceOpen() {
+        this.transitionTo('OPEN');
+    }
+    /**
+     * Force circuit to closed state.
+     * Useful for manual intervention after fixing upstream issues.
+     */
+    forceClose() {
+        this.transitionTo('CLOSED');
+    }
+    /**
+     * Reset circuit to initial state.
+     */
+    reset() {
+        this.state = 'CLOSED';
+        this.failureCount = 0;
+        this.openedAt = 0;
+        this.halfOpenSuccesses = 0;
+    }
+    /**
+     * Get circuit metrics for monitoring.
+     */
+    getMetrics() {
+        return {
+            id: this.id,
+            state: this.getState(),
+            failureCount: this.failureCount,
+            openedAt: this.openedAt > 0 ? new Date(this.openedAt) : null,
+            timeUntilHalfOpen: this.state === 'OPEN'
+                ? Math.max(0, this.config.circuitBreakerResetMs - (Date.now() - this.openedAt))
+                : 0,
+            halfOpenSuccesses: this.halfOpenSuccesses,
+            threshold: this.config.circuitBreakerThreshold,
+            resetMs: this.config.circuitBreakerResetMs,
+        };
+    }
+    /**
+     * Transition to a new state with proper cleanup.
+     */
+    transitionTo(newState) {
+        const previousState = this.state;
+        this.state = newState;
+        switch (newState) {
+            case 'OPEN':
+                this.openedAt = Date.now();
+                this.halfOpenSuccesses = 0;
+                break;
+            case 'HALF_OPEN':
+                this.halfOpenSuccesses = 0;
+                break;
+            case 'CLOSED':
+                this.failureCount = 0;
+                this.openedAt = 0;
+                this.halfOpenSuccesses = 0;
+                break;
+        }
+        // Log state transition (useful for debugging and monitoring)
+        // In production, this would emit events or metrics
+        if (previousState !== newState) {
+            // State changed - could emit event here
+        }
+    }
+}
+/**
+ * Execute a function with circuit breaker protection.
+ *
+ * @param breaker The circuit breaker to use
+ * @param fn The async function to execute
+ * @param fallback Optional fallback function when circuit is open
+ * @returns The result of fn or fallback
+ * @throws CircuitOpenError if circuit is open and no fallback provided
+ */
+export async function withCircuitBreaker(breaker, fn, fallback) {
+    if (!breaker.canRequest()) {
+        if (fallback) {
+            return fallback();
+        }
+        throw new CircuitOpenError(breaker.id);
+    }
+    try {
+        const result = await fn();
+        breaker.recordSuccess();
+        return result;
+    }
+    catch (error) {
+        breaker.recordFailure();
+        throw error;
+    }
+}
+/**
+ * Error thrown when circuit is open and no fallback is provided.
+ */
+export class CircuitOpenError extends Error {
+    circuitId;
+    constructor(circuitId) {
+        super(`Circuit breaker '${circuitId}' is open`);
+        this.name = 'CircuitOpenError';
+        this.circuitId = circuitId;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5jaXJjdWl0YnJlYWtlci5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3Vwc3RyZWFtL2NsYXNzZXMuY2lyY3VpdGJyZWFrZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQ0EsT0FBTyxFQUFFLHlCQUF5QixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFFckU7Ozs7Ozs7Ozs7Ozs7R0FhRztBQUNILE1BQU0sT0FBTyxjQUFjO0lBQ3pCLGdEQUFnRDtJQUNoQyxFQUFFLENBQVM7SUFFM0IsNEJBQTRCO0lBQ3BCLEtBQUssR0FBa0IsUUFBUSxDQUFDO0lBRXhDLG9DQUFvQztJQUM1QixZQUFZLEdBQVcsQ0FBQyxDQUFDO0lBRWpDLHdDQUF3QztJQUNoQyxRQUFRLEdBQVcsQ0FBQyxDQUFDO0lBRTdCLHVEQUF1RDtJQUMvQyxpQkFBaUIsR0FBVyxDQUFDLENBQUM7SUFFdEMsb0JBQW9CO0lBQ0gsTUFBTSxDQUE0QjtJQUVuRCxtRUFBbUU7SUFDbEQsaUJBQWlCLEdBQVcsQ0FBQyxDQUFDO0lBRS9DLFlBQVksRUFBVSxFQUFFLE1BQTJDO1FBQ2pFLElBQUksQ0FBQyxFQUFFLEdBQUcsRUFBRSxDQUFDO1FBQ2IsSUFBSSxDQUFDLE1BQU0sR0FBRyxFQUFFLEdBQUcseUJBQXlCLEVBQUUsR0FBRyxNQUFNLEVBQUUsQ0FBQztJQUM1RCxDQUFDO0lBRUQ7O09BRUc7SUFDSSxRQUFRO1FBQ2IsdURBQXVEO1FBQ3ZELElBQUksSUFBSSxDQUFDLEtBQUssS0FBSyxNQUFNLEVBQUUsQ0FBQztZQUMxQixNQUFNLE9BQU8sR0FBRyxJQUFJLENBQUMsR0FBRyxFQUFFLEdBQUcsSUFBSSxDQUFDLFFBQVEsQ0FBQztZQUMzQyxJQUFJLE9BQU8sSUFBSSxJQUFJLENBQUMsTUFBTSxDQUFDLHFCQUFxQixFQUFFLENBQUM7Z0JBQ2pELElBQUksQ0FBQyxZQUFZLENBQUMsV0FBVyxDQUFDLENBQUM7WUFDakMsQ0FBQztRQUNILENBQUM7UUFD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

package/dist_ts/upstream/classes.upstreamcache.d.ts

@@ -0,0 +1,170 @@
+import type { ICacheEntry, IUpstreamCacheConfig, IUpstreamFetchContext } from './interfaces.upstream.js';
+import type { IStorageBackend } from '../core/interfaces.core.js';
+/**
+ * S3-backed upstream cache with in-memory hot layer.
+ *
+ * Features:
+ * - TTL-based expiration
+ * - Stale-while-revalidate support
+ * - Negative caching (404s)
+ * - Content-type aware caching
+ * - ETag support for conditional requests
+ * - Multi-upstream support via URL-based cache paths
+ * - Persistent S3 storage with in-memory hot layer
+ *
+ * Cache paths are structured as:
+ *   cache/{escaped-upstream-url}/{protocol}:{method}:{path}
+ *
+ * @example
+ * ```typescript
+ * // In-memory only (default)
+ * const cache = new UpstreamCache(config);
+ *
+ * // With S3 persistence
+ * const cache = new UpstreamCache(config, 10000, storage);
+ * ```
+ */
+export declare class UpstreamCache {
+    /** In-memory hot cache */
+    private readonly memoryCache;
+    /** Configuration */
+    private readonly config;
+    /** Maximum in-memory cache entries */
+    private readonly maxMemoryEntries;
+    /** S3 storage backend (optional) */
+    private readonly storage?;
+    /** Cleanup interval handle */
+    private cleanupInterval;
+    constructor(config?: Partial<IUpstreamCacheConfig>, maxMemoryEntries?: number, storage?: IStorageBackend);
+    /**
+     * Check if caching is enabled.
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if S3 storage is configured.
+     */
+    hasStorage(): boolean;
+    /**
+     * Get cached entry for a request context.
+     * Checks memory first, then falls back to S3.
+     * Returns null if not found or expired (unless stale-while-revalidate).
+     */
+    get(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<ICacheEntry | null>;
+    /**
+     * Store a response in the cache (memory and optionally S3).
+     */
+    set(context: IUpstreamFetchContext, data: Buffer, contentType: string, headers: Record<string, string>, upstreamId: string, upstreamUrl: string, options?: ICacheSetOptions): Promise<void>;
+    /**
+     * Store a negative cache entry (404 response).
+     */
+    setNegative(context: IUpstreamFetchContext, upstreamId: string, upstreamUrl: string): Promise<void>;
+    /**
+     * Check if there's a negative cache entry for this context.
+     */
+    hasNegative(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<boolean>;
+    /**
+     * Invalidate a specific cache entry.
+     */
+    invalidate(context: IUpstreamFetchContext, upstreamUrl?: string): Promise<boolean>;
+    /**
+     * Invalidate all entries matching a pattern.
+     * Useful for invalidating all versions of a package.
+     */
+    invalidatePattern(pattern: RegExp): Promise<number>;
+    /**
+     * Invalidate all entries from a specific upstream.
+     */
+    invalidateUpstream(upstreamId: string): Promise<number>;
+    /**
+     * Clear all cache entries (memory and S3).
+     */
+    clear(): Promise<void>;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): ICacheStats;
+    /**
+     * Stop the cache and cleanup.
+     */
+    stop(): void;
+    /**
+     * Build storage path for a cache key.
+     * Escapes upstream URL for safe use in S3 paths.
+     */
+    private buildStoragePath;
+    /**
+     * Build storage path for cache metadata.
+     */
+    private buildMetadataPath;
+    /**
+     * Load a cache entry from S3 storage.
+     */
+    private loadFromStorage;
+    /**
+     * Save a cache entry to S3 storage.
+     */
+    private saveToStorage;
+    /**
+     * Delete a cache entry from S3 storage.
+     */
+    private deleteFromStorage;
+    /**
+     * Escape a URL for safe use in storage paths.
+     */
+    private escapeUrl;
+    /**
+     * Build a unique cache key for a request context.
+     * Includes escaped upstream URL for multi-upstream support.
+     */
+    private buildCacheKey;
+    /**
+     * Determine TTL based on content characteristics.
+     */
+    private determineTtl;
+    /**
+     * Check if content is immutable (content-addressable).
+     */
+    private isImmutableContent;
+    /**
+     * Evict oldest entries to make room for new ones.
+     */
+    private evictOldest;
+    /**
+     * Start periodic cleanup of expired entries.
+     */
+    private startCleanup;
+    /**
+     * Remove all expired entries from memory cache.
+     */
+    private cleanup;
+}
+/**
+ * Options for cache set operation.
+ */
+export interface ICacheSetOptions {
+    /** Override TTL in seconds */
+    ttlSeconds?: number;
+    /** ETag for conditional requests */
+    etag?: string;
+}
+/**
+ * Cache statistics.
+ */
+export interface ICacheStats {
+    /** Total number of cached entries in memory */
+    totalEntries: number;
+    /** Number of fresh (non-expired) entries */
+    freshEntries: number;
+    /** Number of stale entries (expired but still usable) */
+    staleEntries: number;
+    /** Number of negative cache entries */
+    negativeEntries: number;
+    /** Total size of cached data in bytes (memory only) */
+    totalSizeBytes: number;
+    /** Maximum allowed memory entries */
+    maxEntries: number;
+    /** Whether caching is enabled */
+    enabled: boolean;
+    /** Whether S3 storage is configured */
+    hasStorage: boolean;
+}