immortal-js 1.0.0

package/packages/core/src/recovery/FallbackCache.ts

@@ -0,0 +1,328 @@
+/**
+ * @file FallbackCache.ts
+ * @description LRU + TTL cache for emergency fallback responses
+ *
+ * When a circuit is open or a service is unavailable, this cache returns
+ * the last known-good response instead of a cold error.
+ *
+ * Key design decisions:
+ * 1. Always marks cached responses with X-Immortal-Fallback: true header
+ * 2. TTL prevents stale data from being served indefinitely
+ * 3. LRU eviction prevents unbounded memory growth
+ * 4. Per-key TTL allows different expiry times per route/service
+ * 5. Cache is NOT a source of truth — it's a safety net
+ */
+
+import { getEventBus } from "../event-bus.js";
+import { getLogger } from "../logger.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TYPES
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CacheEntry<T> {
+  value: T;
+  createdAt: number;
+  expiresAt: number;
+  hits: number;
+  key: string;
+}
+
+export interface CacheStats {
+  size: number;
+  maxSize: number;
+  hits: number;
+  misses: number;
+  hitRate: number;
+  evictions: number;
+  totalEntries: number;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// LRU CACHE IMPLEMENTATION
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class FallbackCache<T = unknown> {
+  private readonly cache = new Map<string, CacheEntry<T>>();
+  private readonly maxSize: number;
+  private readonly defaultTtlMs: number;
+  private hits = 0;
+  private misses = 0;
+  private evictions = 0;
+
+  constructor(options: { maxSize?: number; defaultTtlMs?: number } = {}) {
+    this.maxSize = options.maxSize ?? 500;
+    this.defaultTtlMs = options.defaultTtlMs ?? 5 * 60 * 1000; // 5 minutes default
+  }
+
+  /**
+   * Store a value in the cache.
+   * @param key - Cache key (typically route path + params hash)
+   * @param value - Value to cache
+   * @param ttlMs - Time-to-live in ms (overrides default)
+   */
+  set(key: string, value: T, ttlMs?: number): void {
+    const now = Date.now();
+    const ttl = ttlMs ?? this.defaultTtlMs;
+
+    // If key exists, update in place (preserves LRU order by re-inserting)
+    if (this.cache.has(key)) {
+      this.cache.delete(key);
+    }
+
+    // Evict LRU entry if at capacity
+    if (this.cache.size >= this.maxSize) {
+      const lruKey = this.cache.keys().next().value;
+      if (lruKey !== undefined) {
+        this.cache.delete(lruKey);
+        this.evictions++;
+      }
+    }
+
+    // Insert at end (most recently used position in Map)
+    this.cache.set(key, {
+      value,
+      createdAt: now,
+      expiresAt: now + ttl,
+      hits: 0,
+      key,
+    });
+  }
+
+  /**
+   * Retrieve a value from the cache.
+   * Returns undefined if not found or expired.
+   * Moves hit entry to MRU position (LRU promotion).
+   */
+  get(key: string): T | undefined {
+    const entry = this.cache.get(key);
+
+    if (!entry) {
+      this.misses++;
+      return undefined;
+    }
+
+    // Check TTL
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      this.misses++;
+      return undefined;
+    }
+
+    // LRU promotion: move to end
+    this.cache.delete(key);
+    entry.hits++;
+    this.cache.set(key, entry);
+    this.hits++;
+
+    return entry.value;
+  }
+
+  /**
+   * Check if a key exists and is not expired
+   */
+  has(key: string): boolean {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Invalidate a specific cache entry
+   */
+  invalidate(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Invalidate all entries matching a prefix pattern
+   */
+  invalidatePattern(prefix: string): number {
+    let count = 0;
+    for (const key of this.cache.keys()) {
+      if (key.startsWith(prefix)) {
+        this.cache.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): CacheStats {
+    const total = this.hits + this.misses;
+    return {
+      size: this.cache.size,
+      maxSize: this.maxSize,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? this.hits / total : 0,
+      evictions: this.evictions,
+      totalEntries: this.cache.size,
+    };
+  }
+
+  /**
+   * Remove all expired entries (run periodically to prevent memory leaks)
+   */
+  purgeExpired(): number {
+    const now = Date.now();
+    let purged = 0;
+    for (const [key, entry] of this.cache) {
+      if (now > entry.expiresAt) {
+        this.cache.delete(key);
+        purged++;
+      }
+    }
+    return purged;
+  }
+
+  /**
+   * Clear all entries
+   */
+  clear(): void {
+    this.cache.clear();
+    this.hits = 0;
+    this.misses = 0;
+    this.evictions = 0;
+  }
+
+  /**
+   * Get the number of cached entries
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ROUTE FALLBACK CACHE — HTTP-aware wrapper
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CachedResponse {
+  body: unknown;
+  statusCode: number;
+  headers: Record<string, string>;
+  cachedAt: number;
+}
+
+export class RouteFallbackCache {
+  private readonly cache: FallbackCache<CachedResponse>;
+  private readonly purgeIntervalMs: number;
+  private purgeInterval?: ReturnType<typeof setInterval>;
+
+  constructor(options: {
+    maxSize?: number;
+    defaultTtlMs?: number;
+    purgeIntervalMs?: number;
+  } = {}) {
+    this.cache = new FallbackCache({
+      maxSize: options.maxSize ?? 200,
+      defaultTtlMs: options.defaultTtlMs ?? 5 * 60 * 1000,
+    });
+    this.purgeIntervalMs = options.purgeIntervalMs ?? 60_000;
+  }
+
+  /**
+   * Start automatic cache purging
+   */
+  start(): void {
+    this.purgeInterval = setInterval(() => {
+      const purged = this.cache.purgeExpired();
+      if (purged > 0) {
+        getLogger().debug(`RouteFallbackCache: purged ${purged} expired entries`);
+      }
+    }, this.purgeIntervalMs).unref();
+  }
+
+  /**
+   * Stop automatic purging
+   */
+  stop(): void {
+    if (this.purgeInterval) {
+      clearInterval(this.purgeInterval);
+      delete this.purgeInterval;
+    }
+  }
+
+  /**
+   * Cache a successful HTTP response
+   */
+  cacheResponse(
+    route: string,
+    method: string,
+    response: { body: unknown; statusCode?: number; headers?: Record<string, string> },
+    ttlMs?: number
+  ): void {
+    const key = this.buildKey(route, method);
+    this.cache.set(key, {
+      body: response.body,
+      statusCode: response.statusCode ?? 200,
+      headers: {
+        ...response.headers,
+        "Content-Type": "application/json",
+      },
+      cachedAt: Date.now(),
+    }, ttlMs);
+  }
+
+  /**
+   * Get a cached fallback response for a route
+   * Returns undefined if no cache entry or expired
+   */
+  getFallback(
+    route: string,
+    method: string
+  ): (CachedResponse & { isFallback: true; ageMs: number }) | undefined {
+    const key = this.buildKey(route, method);
+    const entry = this.cache.get(key);
+
+    if (!entry) return undefined;
+
+    getEventBus().emit("fallback:cache-hit", {
+      route,
+      data: { method, ageMs: Date.now() - entry.cachedAt, key },
+    });
+
+    return {
+      ...entry,
+      isFallback: true,
+      ageMs: Date.now() - entry.cachedAt,
+    };
+  }
+
+  /**
+   * Create a cache middleware for automatic request/response caching
+   */
+  createCacheMiddleware(options: {
+    ttlMs?: number;
+    shouldCache?: (route: string, method: string) => boolean;
+  } = {}): {
+    cacheResponse: (route: string, method: string, body: unknown, status?: number) => void;
+    getFallback: (route: string, method: string) => (CachedResponse & { isFallback: true; ageMs: number }) | undefined;
+  } {
+    return {
+      cacheResponse: (route, method, body, status = 200) => {
+        const shouldCache = options.shouldCache?.(route, method) ?? true;
+        if (shouldCache && status < 400) {
+          this.cacheResponse(route, method, { body, statusCode: status }, options.ttlMs);
+        }
+      },
+      getFallback: (route, method) => this.getFallback(route, method),
+    };
+  }
+
+  getStats(): CacheStats {
+    return this.cache.getStats();
+  }
+
+  private buildKey(route: string, method: string): string {
+    return `${method.toUpperCase()}:${route}`;
+  }
+}

package/packages/core/src/recovery/RetryEngine.ts

@@ -0,0 +1,225 @@
+/**
+ * @file RetryEngine.ts
+ * @description Retry engine with Exponential Backoff + Jitter + Retry Budget
+ *
+ * Key engineering decisions:
+ * 1. Exponential backoff with full jitter (not equal jitter) to prevent thundering herd
+ * 2. Retry budget prevents global retry storms — max N retries/second across ALL operations
+ * 3. isRetryable() classification prevents retrying non-retryable errors (e.g. 400 Bad Request)
+ * 4. RetryExhaustedError wraps the last error for full context preservation
+ */
+
+import type { RetryConfig } from "../types.js";
+import { RetryExhaustedError } from "../types.js";
+import { DEFAULT_RETRY } from "../config/defaults.js";
+import { getEventBus } from "../event-bus.js";
+import { getLogger } from "../logger.js";
+import { AsyncBoundary } from "../safe-zone/AsyncBoundary.js";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RETRY BUDGET (Global rate limiter for retries)
+// ─────────────────────────────────────────────────────────────────────────────
+
+class RetryBudget {
+  private tokens: number;
+  private readonly maxTokens: number;
+  private lastRefill: number;
+
+  constructor(maxPerSecond: number) {
+    this.maxTokens = maxPerSecond;
+    this.tokens = maxPerSecond;
+    this.lastRefill = Date.now();
+  }
+
+  tryConsume(): boolean {
+    this.refill();
+    if (this.tokens >= 1) {
+      this.tokens -= 1;
+      return true;
+    }
+    return false;
+  }
+
+  private refill(): void {
+    const now = Date.now();
+    const elapsed = (now - this.lastRefill) / 1000;
+    this.tokens = Math.min(this.maxTokens, this.tokens + elapsed * this.maxTokens);
+    this.lastRefill = now;
+  }
+
+  getAvailable(): number {
+    this.refill();
+    return Math.floor(this.tokens);
+  }
+}
+
+// Global budget shared across all RetryEngine instances
+let _globalBudget: RetryBudget | null = null;
+
+function getGlobalBudget(maxPerSecond: number): RetryBudget {
+  if (!_globalBudget) {
+    _globalBudget = new RetryBudget(maxPerSecond);
+  }
+  return _globalBudget;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// RETRY ENGINE CLASS
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class RetryEngine {
+  private readonly config: Required<RetryConfig>;
+
+  constructor(config: RetryConfig = {}) {
+    this.config = { ...DEFAULT_RETRY, ...config };
+  }
+
+  /**
+   * Execute a function with retry logic.
+   *
+   * @param fn - The async function to execute
+   * @param operationName - Name for logging/telemetry
+   * @returns Result of fn on success
+   * @throws RetryExhaustedError if all attempts fail
+   */
+  async execute<T>(fn: () => Promise<T>, operationName = "anonymous"): Promise<T> {
+    const bus = getEventBus();
+    const logger = getLogger();
+    const budget = getGlobalBudget(this.config.retryBudget);
+    const requestId = AsyncBoundary.getRequestId();
+
+    let lastError: unknown;
+    let attempt = 0;
+
+    while (true) {
+      try {
+        const result = await fn();
+
+        if (attempt > 0) {
+          bus.emit("retry:success", {
+            requestId,
+            data: { operationName, successAfterAttempts: attempt + 1 },
+          });
+          logger.info(`Retry succeeded after ${attempt + 1} attempts`, { operationName });
+        }
+
+        return result;
+      } catch (err) {
+        lastError = err;
+        attempt++;
+
+        // Check if retryable
+        if (!this.config.isRetryable(err)) {
+          logger.debug(`Error not retryable — failing immediately`, {
+            operationName,
+            attempt,
+            error: (err as Error).message,
+          });
+          throw err;
+        }
+
+        // Check attempt limit
+        if (attempt >= this.config.maxAttempts) {
+          bus.emit("retry:exhausted", {
+            requestId,
+            data: { operationName, attempts: attempt },
+            error: { name: "RetryExhausted", message: `Failed after ${attempt} attempts` },
+          });
+          throw new RetryExhaustedError(attempt, lastError);
+        }
+
+        // Check global retry budget
+        if (!budget.tryConsume()) {
+          logger.warn(`Retry budget exhausted — failing immediately to protect system`, {
+            operationName,
+            attempt,
+            budgetAvailable: budget.getAvailable(),
+          });
+          throw new RetryExhaustedError(attempt, lastError);
+        }
+
+        // Calculate backoff with full jitter
+        const delay = this.calculateDelay(attempt);
+
+        bus.emit("retry:attempt", {
+          requestId,
+          data: {
+            operationName,
+            attempt,
+            maxAttempts: this.config.maxAttempts,
+            nextRetryMs: delay,
+            error: (err as Error).message,
+          },
+        });
+
+        logger.debug(`Retry attempt ${attempt}/${this.config.maxAttempts} in ${delay}ms`, {
+          operationName,
+          error: (err as Error).message,
+        });
+
+        await sleep(delay);
+      }
+    }
+  }
+
+  private calculateDelay(attempt: number): number {
+    // Exponential backoff: baseDelay * 2^attempt
+    const exponential = this.config.baseDelayMs * Math.pow(2, attempt - 1);
+    // Cap at maxDelayMs
+    const capped = Math.min(exponential, this.config.maxDelayMs);
+    // Full jitter: random between 0 and capped
+    const jitter = Math.random() * capped * this.config.jitterFactor;
+    return Math.floor(capped - jitter + jitter * Math.random());
+  }
+
+  /** Reset the global retry budget (for testing) */
+  static resetBudget(): void {
+    _globalBudget = null;
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// FUNCTIONAL API
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Execute a function with retry logic.
+ * Functional alternative to RetryEngine class.
+ *
+ * @example
+ * const data = await withRetry(
+ *   () => fetchFromDatabase(id),
+ *   { maxAttempts: 3, baseDelayMs: 100 }
+ * );
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  config?: RetryConfig,
+  operationName?: string
+): Promise<T> {
+  const engine = new RetryEngine(config);
+  return engine.execute(fn, operationName);
+}
+
+/**
+ * Utility: exponential backoff delay calculator (exported for use in other modules)
+ */
+export function calculateBackoff(
+  attempt: number,
+  baseMs: number,
+  maxMs: number,
+  jitterFactor = 0.3
+): number {
+  const exponential = baseMs * Math.pow(2, attempt - 1);
+  const capped = Math.min(exponential, maxMs);
+  const jitter = Math.random() * capped * jitterFactor;
+  return Math.floor(capped - jitter + jitter * Math.random());
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// UTILITIES
+// ─────────────────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms).unref());
+}

package/packages/core/src/recovery/Timeout.ts

@@ -0,0 +1,97 @@
+/**
+ * @file Timeout.ts
+ * @description AbortController-based operation timeout wrapper
+ * Ensures no operation can hang indefinitely, blocking resources
+ */
+
+import { TimeoutError } from "../types.js";
+
+/**
+ * Wrap any async operation with a timeout.
+ * Uses AbortController for clean cancellation signal propagation.
+ *
+ * @param fn - Async function that optionally accepts an AbortSignal
+ * @param timeoutMs - Timeout in milliseconds
+ * @param operationName - Name for error messages
+ * @returns Result of fn or throws TimeoutError
+ */
+export async function withTimeout<T>(
+  fn: (signal: AbortSignal) => Promise<T>,
+  timeoutMs: number,
+  operationName = "operation"
+): Promise<T> {
+  const controller = new AbortController();
+  const { signal } = controller;
+
+  const timeoutId = setTimeout(() => {
+    controller.abort(new TimeoutError(operationName, timeoutMs));
+  }, timeoutMs);
+
+  try {
+    const result = await Promise.race([
+      fn(signal),
+      new Promise<never>((_, reject) => {
+        signal.addEventListener("abort", () => {
+          reject(signal.reason instanceof TimeoutError
+            ? signal.reason
+            : new TimeoutError(operationName, timeoutMs)
+          );
+        }, { once: true });
+      }),
+    ]);
+
+    clearTimeout(timeoutId);
+    return result;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    controller.abort(); // Ensure abort propagates even on non-timeout errors
+
+    if (error instanceof TimeoutError) throw error;
+
+    // If operation was aborted by timeout but threw a different error, wrap it
+    if (signal.aborted) {
+      throw new TimeoutError(operationName, timeoutMs);
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Create a reusable timeout wrapper for a specific timeout value
+ */
+export function createTimeoutWrapper(timeoutMs: number) {
+  return function <T>(
+    fn: (signal: AbortSignal) => Promise<T>,
+    operationName?: string
+  ): Promise<T> {
+    return withTimeout(fn, timeoutMs, operationName);
+  };
+}
+
+/**
+ * Simple timeout without AbortSignal (for legacy code compatibility)
+ * Less clean but works with functions that don't accept AbortSignal
+ */
+export async function withSimpleTimeout<T>(
+  fn: () => Promise<T>,
+  timeoutMs: number,
+  operationName = "operation"
+): Promise<T> {
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+
+  const timeoutPromise = new Promise<never>((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new TimeoutError(operationName, timeoutMs));
+    }, timeoutMs);
+  });
+
+  try {
+    const result = await Promise.race([fn(), timeoutPromise]);
+    clearTimeout(timeoutId);
+    return result;
+  } catch (error) {
+    clearTimeout(timeoutId);
+    throw error;
+  }
+}

package/packages/core/src/recovery/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @file recovery/index.ts
+ * @description Recovery layer public exports
+ */
+
+export { withTimeout, withSimpleTimeout, createTimeoutWrapper } from "./Timeout.js";
+export { RetryEngine, withRetry, calculateBackoff } from "./RetryEngine.js";
+export { CircuitBreaker, CircuitBreakerRegistry } from "./CircuitBreaker.js";
+export type { CircuitState } from "./CircuitBreaker.js";
+export { FallbackCache, RouteFallbackCache } from "./FallbackCache.js";
+export type { CacheEntry, CacheStats, CachedResponse } from "./FallbackCache.js";