raffel 0.1.2

package/dist/middleware/interceptors/cache.js

@@ -0,0 +1,505 @@
+/**
+ * Cache Interceptor
+ *
+ * Protocol-agnostic response caching for procedures.
+ * Reduces latency and load on downstream services by caching responses.
+ *
+ * Features:
+ * - Pluggable driver system (memory, file, redis, s3db)
+ * - In-memory LRU cache with TTL (default)
+ * - Container-aware memory limits (Docker/K8s)
+ * - Procedure pattern matching
+ * - Custom key generation
+ * - Stale-while-revalidate support
+ * - Cache statistics and callbacks
+ */
+/**
+ * Create an in-memory LRU cache store
+ */
+export function createMemoryCacheStore(maxEntries = 1000) {
+    const cache = new Map();
+    const accessOrder = [];
+    function updateAccessOrder(key) {
+        const idx = accessOrder.indexOf(key);
+        if (idx > -1) {
+            accessOrder.splice(idx, 1);
+        }
+        accessOrder.push(key);
+    }
+    function evictIfNeeded() {
+        while (cache.size >= maxEntries && accessOrder.length > 0) {
+            const oldest = accessOrder.shift();
+            if (oldest) {
+                cache.delete(oldest);
+            }
+        }
+    }
+    return {
+        async get(key) {
+            const entry = cache.get(key);
+            if (!entry) {
+                return undefined;
+            }
+            // Check if expired
+            if (Date.now() > entry.expiresAt) {
+                cache.delete(key);
+                const idx = accessOrder.indexOf(key);
+                if (idx > -1) {
+                    accessOrder.splice(idx, 1);
+                }
+                return undefined;
+            }
+            updateAccessOrder(key);
+            return { value: entry.value, expiresAt: entry.expiresAt };
+        },
+        async set(key, value, ttlMs) {
+            evictIfNeeded();
+            const entry = {
+                value,
+                expiresAt: Date.now() + ttlMs,
+            };
+            cache.set(key, entry);
+            updateAccessOrder(key);
+        },
+        async delete(key) {
+            cache.delete(key);
+            const idx = accessOrder.indexOf(key);
+            if (idx > -1) {
+                accessOrder.splice(idx, 1);
+            }
+        },
+        async clear() {
+            cache.clear();
+            accessOrder.length = 0;
+        },
+        stats() {
+            return {
+                size: cache.size,
+                maxEntries,
+            };
+        },
+    };
+}
+/**
+ * Simple hash function for payload
+ */
+function hashPayload(payload) {
+    if (payload === undefined || payload === null) {
+        return 'null';
+    }
+    try {
+        const str = JSON.stringify(payload);
+        // Simple djb2 hash
+        let hash = 5381;
+        for (let i = 0; i < str.length; i++) {
+            hash = ((hash << 5) + hash) ^ str.charCodeAt(i);
+        }
+        return (hash >>> 0).toString(36);
+    }
+    catch {
+        // If payload can't be stringified, return unique key (no cache)
+        return Math.random().toString(36).slice(2);
+    }
+}
+/**
+ * Default key generator: procedure + payload hash
+ */
+function defaultKeyGenerator(envelope) {
+    return `cache:${envelope.procedure}:${hashPayload(envelope.payload)}`;
+}
+/**
+ * Match a procedure name against glob patterns
+ */
+function matchProcedure(patterns, procedure) {
+    return patterns.some((pattern) => {
+        const regex = pattern
+            .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+            .replace(/\*\*/g, '{{DOUBLE_STAR}}')
+            .replace(/\*/g, '[^.]*')
+            .replace(/{{DOUBLE_STAR}}/g, '.*');
+        return new RegExp(`^${regex}$`).test(procedure);
+    });
+}
+/**
+ * Clone a result to prevent mutation of cached data
+ */
+function cloneResult(result) {
+    if (result === null || result === undefined) {
+        return result;
+    }
+    if (typeof result !== 'object') {
+        return result;
+    }
+    // Handle arrays
+    if (Array.isArray(result)) {
+        return result.map(cloneResult);
+    }
+    // Handle plain objects
+    try {
+        return JSON.parse(JSON.stringify(result));
+    }
+    catch {
+        return result;
+    }
+}
+// Track pending revalidations to prevent thundering herd
+const pendingRevalidations = new Map();
+/**
+ * Adapter to use a CacheDriver as a CacheStore
+ * This allows the interceptor to work with both old and new APIs
+ */
+function createDriverAdapter(driver) {
+    return {
+        async get(key) {
+            const result = await driver.get(key);
+            if (!result)
+                return undefined;
+            return {
+                value: result.entry.value,
+                expiresAt: result.entry.expiresAt,
+            };
+        },
+        async set(key, value, ttlMs) {
+            await driver.set(key, value, ttlMs);
+        },
+        async delete(key) {
+            await driver.delete(key);
+        },
+        async clear() {
+            await driver.clear();
+        },
+    };
+}
+/**
+ * Create a cache store from driver config
+ */
+function createStoreFromConfig(config) {
+    // Priority 1: Explicit driver instance
+    if (config.driver) {
+        return createDriverAdapter(config.driver);
+    }
+    // Priority 2: Explicit store instance (legacy API)
+    if (config.store) {
+        return config.store;
+    }
+    // Priority 3: Driver type with options (creates memory driver)
+    if (config.driverType === 'memory' || !config.driverType) {
+        // Use the advanced memory driver from cache module if options are provided
+        if (config.driverOptions) {
+            // Lazy load to avoid circular dependency
+            const { MemoryDriver } = require('../../cache/drivers/memory.js');
+            const driver = new MemoryDriver(config.driverOptions);
+            return createDriverAdapter(driver);
+        }
+    }
+    // Default: Simple in-memory store
+    return createMemoryCacheStore(config.maxEntries ?? 1000);
+}
+/**
+ * Create a cache interceptor
+ *
+ * Caches procedure responses to reduce latency and downstream load.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - cache everything for 1 minute
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ * })
+ *
+ * // Cache specific procedures
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   procedures: ['users.get', 'products.list', 'config.**'],
+ * })
+ *
+ * // With custom key generation (e.g., per-user caching)
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   keyGenerator: (envelope) => {
+ *     const userId = envelope.metadata['x-user-id'] ?? 'anonymous'
+ *     return `${userId}:${envelope.procedure}:${JSON.stringify(envelope.payload)}`
+ *   },
+ * })
+ *
+ * // With stale-while-revalidate
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   staleWhileRevalidate: true,
+ *   staleGraceMs: 30000, // Serve stale data for 30s while revalidating
+ * })
+ *
+ * // With Redis driver (new API)
+ * import { createDriver } from 'raffel/cache'
+ * const redisDriver = await createDriver('redis', { client: redisClient })
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driver: redisDriver,
+ * })
+ *
+ * // With advanced memory driver
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   driverOptions: {
+ *     maxSize: 5000,
+ *     maxMemoryPercent: 0.1,  // 10% of system RAM
+ *     evictionPolicy: 'lru',
+ *     compression: true,
+ *   },
+ * })
+ *
+ * // With metrics
+ * const cache = createCacheInterceptor({
+ *   ttlMs: 60000,
+ *   onAccess: ({ hit, procedure }) => {
+ *     metrics.increment(hit ? 'cache.hit' : 'cache.miss', { procedure })
+ *   },
+ * })
+ *
+ * server.use(cache)
+ * ```
+ */
+export function createCacheInterceptor(config = {}) {
+    const { ttlMs = 60000, procedures, excludeProcedures = [], keyGenerator = defaultKeyGenerator, staleWhileRevalidate = false, staleGraceMs, onAccess, cacheSuccessOnly = true, } = config;
+    // Create cache store (supports both legacy store API and new driver API)
+    const cacheStore = createStoreFromConfig(config);
+    // Calculate stale grace period
+    const effectiveStaleGraceMs = staleGraceMs ?? Math.floor(ttlMs / 2);
+    return async (envelope, ctx, next) => {
+        // Check procedure patterns
+        if (procedures && procedures.length > 0) {
+            if (!matchProcedure(procedures, envelope.procedure)) {
+                return next();
+            }
+        }
+        // Check exclusions
+        if (excludeProcedures.length > 0) {
+            if (matchProcedure(excludeProcedures, envelope.procedure)) {
+                return next();
+            }
+        }
+        // Generate cache key
+        const key = keyGenerator(envelope);
+        // Try to get from cache
+        const cached = await cacheStore.get(key);
+        if (cached) {
+            const now = Date.now();
+            const isExpired = now > cached.expiresAt;
+            // If not expired, return cached value
+            if (!isExpired) {
+                if (onAccess) {
+                    onAccess({
+                        key,
+                        procedure: envelope.procedure,
+                        requestId: ctx.requestId,
+                        hit: true,
+                        stale: false,
+                    });
+                }
+                return cloneResult(cached.value);
+            }
+            // Stale-while-revalidate logic
+            if (staleWhileRevalidate && now < cached.expiresAt + effectiveStaleGraceMs) {
+                if (onAccess) {
+                    onAccess({
+                        key,
+                        procedure: envelope.procedure,
+                        requestId: ctx.requestId,
+                        hit: true,
+                        stale: true,
+                    });
+                }
+                // Check if revalidation is already in progress
+                if (!pendingRevalidations.has(key)) {
+                    // Start background revalidation
+                    const revalidationPromise = next()
+                        .then(async (result) => {
+                        // Only cache successful results
+                        await cacheStore.set(key, result, ttlMs);
+                        return result;
+                    })
+                        .catch((error) => {
+                        // On error, keep the stale value
+                        console.error(`Cache revalidation failed for ${key}:`, error);
+                    })
+                        .finally(() => {
+                        pendingRevalidations.delete(key);
+                    });
+                    pendingRevalidations.set(key, revalidationPromise);
+                }
+                // Return stale value immediately
+                return cloneResult(cached.value);
+            }
+        }
+        // Cache miss - execute handler
+        if (onAccess) {
+            onAccess({
+                key,
+                procedure: envelope.procedure,
+                requestId: ctx.requestId,
+                hit: false,
+            });
+        }
+        try {
+            const result = await next();
+            // Cache the result (clone to prevent mutation)
+            if (!cacheSuccessOnly || isSuccessfulResult(result)) {
+                await cacheStore.set(key, cloneResult(result), ttlMs);
+            }
+            return result;
+        }
+        catch (error) {
+            // Don't cache errors
+            throw error;
+        }
+    };
+}
+/**
+ * Check if a result is successful (not an error envelope)
+ */
+function isSuccessfulResult(result) {
+    if (result === null || result === undefined) {
+        return true;
+    }
+    if (typeof result === 'object' && 'type' in result) {
+        return result.type !== 'error';
+    }
+    return true;
+}
+/**
+ * Create a read-through cache interceptor
+ *
+ * Convenience wrapper that only caches read operations
+ * (procedures matching common read patterns).
+ *
+ * @example
+ * ```typescript
+ * const cache = createReadThroughCacheInterceptor({
+ *   ttlMs: 60000,
+ * })
+ * server.use(cache)
+ * ```
+ */
+export function createReadThroughCacheInterceptor(config = {}) {
+    return createCacheInterceptor({
+        ...config,
+        procedures: [
+            '*.get',
+            '*.get*',
+            '*.find',
+            '*.find*',
+            '*.list',
+            '*.list*',
+            '*.search',
+            '*.search*',
+            '*.count',
+            '*.count*',
+            '*.exists',
+            '*.check*',
+            'read.**',
+            'query.**',
+            'fetch.**',
+        ],
+        // Exclude mutations
+        excludeProcedures: [
+            '*.create*',
+            '*.update*',
+            '*.delete*',
+            '*.remove*',
+            '*.save*',
+            '*.set*',
+            '*.put*',
+            '*.post*',
+            '*.patch*',
+            'write.**',
+            'mutation.**',
+        ],
+    });
+}
+/**
+ * Create cache presets for common use cases
+ */
+export const CachePresets = {
+    /**
+     * Short-lived cache (5 seconds) for frequently changing data
+     */
+    short: {
+        ttlMs: 5000,
+        staleWhileRevalidate: true,
+        staleGraceMs: 2000,
+    },
+    /**
+     * Standard cache (1 minute) for general purpose
+     */
+    standard: {
+        ttlMs: 60000,
+        staleWhileRevalidate: true,
+        staleGraceMs: 30000,
+    },
+    /**
+     * Long-lived cache (5 minutes) for stable data
+     */
+    long: {
+        ttlMs: 300000,
+        staleWhileRevalidate: true,
+        staleGraceMs: 120000,
+    },
+    /**
+     * Aggressive cache (1 hour) for rarely changing data
+     */
+    aggressive: {
+        ttlMs: 3600000,
+        staleWhileRevalidate: true,
+        staleGraceMs: 1800000,
+    },
+    /**
+     * No stale - strict TTL without SWR
+     */
+    strict: {
+        ttlMs: 60000,
+        staleWhileRevalidate: false,
+        maxEntries: 500,
+    },
+};
+/**
+ * Cache invalidation helper
+ *
+ * Use this to manually invalidate cache entries.
+ *
+ * @example
+ * ```typescript
+ * const store = createMemoryCacheStore(1000)
+ * const cache = createCacheInterceptor({ store })
+ * const invalidator = createCacheInvalidator(store)
+ *
+ * // In a mutation handler:
+ * async function updateUser(input, ctx) {
+ *   await db.users.update(input)
+ *   // Invalidate related cache entries
+ *   await invalidator.invalidatePattern('cache:users.get:*')
+ *   return { success: true }
+ * }
+ * ```
+ */
+export function createCacheInvalidator(store) {
+    return {
+        /**
+         * Invalidate a specific cache key
+         */
+        async invalidate(key) {
+            await store.delete(key);
+        },
+        /**
+         * Clear all cache entries
+         */
+        async invalidateAll() {
+            await store.clear();
+        },
+        /**
+         * Note: Pattern-based invalidation requires store support
+         * The default memory store doesn't support patterns.
+         * Use Redis or similar for pattern-based invalidation.
+         */
+    };
+}
+//# sourceMappingURL=cache.js.map

package/dist/middleware/interceptors/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/middleware/interceptors/cache.ts"],"names":[],"mappings":"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"}

package/dist/middleware/interceptors/circuit-breaker.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Circuit Breaker Interceptor
+ *
+ * Protocol-agnostic circuit breaker pattern implementation.
+ * Prevents cascading failures by failing fast when a service is unhealthy.
+ */
+import type { Interceptor } from '../../types/index.js';
+import type { CircuitBreakerConfig, CircuitState } from '../types.js';
+/**
+ * Create a circuit breaker interceptor
+ *
+ * The circuit breaker has three states:
+ * - CLOSED: Normal operation, requests pass through
+ * - OPEN: Circuit is tripped, requests fail fast
+ * - HALF-OPEN: Testing if service recovered, limited requests allowed
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const circuitBreaker = createCircuitBreakerInterceptor()
+ *
+ * // Custom configuration
+ * const circuitBreaker = createCircuitBreakerInterceptor({
+ *   failureThreshold: 5,      // Open after 5 failures
+ *   successThreshold: 3,      // Close after 3 successes in half-open
+ *   resetTimeoutMs: 30000,    // Try to recover after 30s
+ * })
+ *
+ * // With state change callback
+ * const circuitBreaker = createCircuitBreakerInterceptor({
+ *   onStateChange: (state, procedure) => {
+ *     metrics.gauge('circuit_breaker', state === 'open' ? 1 : 0, { procedure })
+ *   }
+ * })
+ *
+ * server.use(circuitBreaker)
+ * ```
+ */
+export declare function createCircuitBreakerInterceptor(config?: CircuitBreakerConfig): Interceptor;
+/**
+ * Create a circuit breaker with procedure-specific configurations
+ *
+ * @example
+ * ```typescript
+ * const circuitBreaker = createProcedureCircuitBreaker({
+ *   default: { failureThreshold: 5 },
+ *   procedures: {
+ *     'external.payment': { failureThreshold: 3, resetTimeoutMs: 60000 },
+ *     'external.email': { failureThreshold: 10 },
+ *   }
+ * })
+ * ```
+ */
+export declare function createProcedureCircuitBreaker(config: {
+    default?: CircuitBreakerConfig;
+    procedures: Record<string, CircuitBreakerConfig>;
+}): Interceptor;
+/**
+ * Create a circuit breaker manager for monitoring and control
+ */
+export interface CircuitBreakerManager {
+    /** Get the current state of all circuits */
+    getStates(): Map<string, CircuitState>;
+    /** Force a circuit to a specific state */
+    forceState(procedure: string, state: CircuitState): void;
+    /** Reset all circuits to closed */
+    resetAll(): void;
+    /** Get the interceptor */
+    interceptor: Interceptor;
+}
+export declare function createCircuitBreakerManager(config?: CircuitBreakerConfig): CircuitBreakerManager;
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/middleware/interceptors/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../../../src/middleware/interceptors/circuit-breaker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAqB,MAAM,sBAAsB,CAAA;AAC1E,OAAO,KAAK,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAwBrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,+BAA+B,CAAC,MAAM,GAAE,oBAAyB,GAAG,WAAW,CAkK9F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE;IACpD,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAA;CACjD,GAAG,WAAW,CAiDd;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,SAAS,IAAI,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IAEtC,0CAA0C;IAC1C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;IAExD,mCAAmC;IACnC,QAAQ,IAAI,IAAI,CAAA;IAEhB,0BAA0B;IAC1B,WAAW,EAAE,WAAW,CAAA;CACzB;AAED,wBAAgB,2BAA2B,CACzC,MAAM,GAAE,oBAAyB,GAChC,qBAAqB,CAkCvB"}

package/dist/middleware/interceptors/circuit-breaker.int.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Circuit Breaker Interceptor Tests
+ */
+export {};
+//# sourceMappingURL=circuit-breaker.int.test.d.ts.map

package/dist/middleware/interceptors/circuit-breaker.int.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.int.test.d.ts","sourceRoot":"","sources":["../../../src/middleware/interceptors/circuit-breaker.int.test.ts"],"names":[],"mappings":"AAAA;;GAEG"}