veryfront 0.1.1185 → 0.1.1189

package/esm/src/proxy/cache/resilient-cache.js

@@ -1,160 +1,390 @@
 import { proxyLogger } from "../logger.js";
 import { withSpan } from "../tracing.js";
-const CIRCUIT_OPEN_DURATION_MS = 30_000;
-const FAILURE_THRESHOLD = 3;
+import { getErrorMessage } from "../../errors/index.js";
+import { assertCacheOptionsObject, requireTokenCacheKey, snapshotTokenCacheEntry, snapshotTokenCacheOperations, snapshotTokenCacheStats, } from "./validation.js";
+const DEFAULT_CIRCUIT_OPEN_DURATION_MS = 30_000;
+const DEFAULT_FAILURE_THRESHOLD = 3;
+const MAX_CIRCUIT_OPEN_DURATION_MS = 60 * 60 * 1_000;
+const MAX_FAILURE_THRESHOLD = 100;
+const MAX_PENDING_MUTATIONS = 10_000;
+const MAX_QUEUED_MUTATIONS = 10_000;
+const RECOVERY_PROBE_KEY = "__veryfront_cache_recovery_probe__";
+const monotonicNow = () => performance.now();
 const logger = proxyLogger.child({ module: "cache" });
+function readOwnOption(options, key) {
+    const descriptor = Object.getOwnPropertyDescriptor(options, key);
+    if (!descriptor)
+        return undefined;
+    if (!("value" in descriptor)) {
+        throw new TypeError(`Resilient cache option ${key} must be a data property`);
+    }
+    return descriptor.value;
+}
+function resolveIntegerOption(value, fallback, label, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" ||
+        !Number.isSafeInteger(value) ||
+        value < minimum ||
+        value > maximum) {
+        throw new RangeError(`${label} must be an integer between ${minimum} and ${maximum}`);
+    }
+    return value;
+}
 export class ResilientCache {
     primary;
     fallback;
-    usingFallback = false;
+    failureThreshold;
+    openDurationMs;
+    now;
+    state = "closed";
     failureCount = 0;
     circuitOpenedAt = null;
-    constructor(primary, fallback) {
-        this.primary = primary;
-        this.fallback = fallback;
-    }
-    shouldTryPrimary() {
-        if (!this.usingFallback)
-            return true;
-        const openedAt = this.circuitOpenedAt;
-        if (openedAt == null)
-            return false;
-        const elapsed = Date.now() - openedAt;
-        if (elapsed < CIRCUIT_OPEN_DURATION_MS)
-            return false;
-        logger.debug("[ResilientCache] Circuit half-open, trying primary again");
-        return true;
-    }
-    recordSuccess() {
-        if (!this.usingFallback)
-            return;
-        logger.debug("[ResilientCache] Primary recovered, switching back from fallback");
-        this.usingFallback = false;
-        this.failureCount = 0;
-        this.circuitOpenedAt = null;
-    }
-    recordFailure(error) {
-        this.failureCount++;
-        logger.warn(`[ResilientCache] Primary cache error (${this.failureCount}/${FAILURE_THRESHOLD}):`, { error: error instanceof Error ? error.message : error });
-        if (this.usingFallback)
-            return;
-        if (this.failureCount < FAILURE_THRESHOLD)
-            return;
-        logger.warn("[ResilientCache] Opening circuit, switching to fallback cache");
-        this.usingFallback = true;
-        this.circuitOpenedAt = Date.now();
+    recoveryPromise = null;
+    recoveryOwner = null;
+    pendingMutations = new Map();
+    pendingClear = false;
+    mutationTail = Promise.resolve();
+    queuedMutations = 0;
+    closed = false;
+    closePromise = null;
+    constructor(primary, fallback, options = {}) {
+        if (primary === fallback) {
+            throw new TypeError("Resilient cache primary and fallback must be distinct");
+        }
+        assertCacheOptionsObject(options, "Resilient cache options", ["failureThreshold", "openDurationMs", "now"]);
+        this.primary = snapshotTokenCacheOperations(primary, "Resilient cache primary");
+        this.fallback = snapshotTokenCacheOperations(fallback, "Resilient cache fallback");
+        this.failureThreshold = resolveIntegerOption(readOwnOption(options, "failureThreshold"), DEFAULT_FAILURE_THRESHOLD, "Resilient cache failureThreshold", 1, MAX_FAILURE_THRESHOLD);
+        this.openDurationMs = resolveIntegerOption(readOwnOption(options, "openDurationMs"), DEFAULT_CIRCUIT_OPEN_DURATION_MS, "Resilient cache openDurationMs", 0, MAX_CIRCUIT_OPEN_DURATION_MS);
+        const now = readOwnOption(options, "now");
+        if (now !== undefined && typeof now !== "function") {
+            throw new TypeError("Resilient cache now must be a function");
+        }
+        this.now = now ?? monotonicNow;
+        this.readClock();
     }
     async get(key) {
-        return withSpan("cache.resilient.get", async () => {
-            if (this.shouldTryPrimary()) {
+        return await withSpan("cache.resilient.get", async () => {
+            this.assertOpen();
+            const cacheKey = requireTokenCacheKey(key);
+            if (await this.canUsePrimary()) {
                 try {
-                    const result = await this.primary.get(key);
-                    this.recordSuccess();
-                    return result;
+                    const result = await this.primary.get(cacheKey);
+                    this.recordReadSuccess();
+                    return result === null ? null : snapshotTokenCacheEntry(result);
                 }
                 catch (error) {
-                    this.recordFailure(error);
+                    this.recordReadFailure(error);
                 }
             }
-            return this.fallback.get(key);
-        }, { "cache.key": key, "cache.usingFallback": this.usingFallback });
+            const fallbackResult = await this.fallback.get(cacheKey);
+            return fallbackResult === null ? null : snapshotTokenCacheEntry(fallbackResult);
+        }, { "cache.circuit_state": this.state });
     }
     async set(key, entry) {
-        return withSpan("cache.resilient.set", async () => {
-            await this.fallback.set(key, entry);
-            if (!this.shouldTryPrimary())
-                return;
-            try {
-                await this.primary.set(key, entry);
-                this.recordSuccess();
-            }
-            catch (error) {
-                this.recordFailure(error);
-            }
-        }, { "cache.key": key, "cache.usingFallback": this.usingFallback });
+        return await withSpan("cache.resilient.set", async () => {
+            this.assertOpen();
+            const cacheKey = requireTokenCacheKey(key);
+            const cachedEntry = snapshotTokenCacheEntry(entry);
+            await this.enqueueMutation(async () => {
+                if (Date.now() >= cachedEntry.expiresAt) {
+                    await this.deleteFromBackends(cacheKey);
+                    return;
+                }
+                await this.fallback.set(cacheKey, cachedEntry);
+                if (!(await this.canUsePrimary())) {
+                    this.rememberSet(cacheKey, cachedEntry);
+                    return;
+                }
+                try {
+                    await this.primary.set(cacheKey, cachedEntry);
+                    this.recordMutationSuccess(cacheKey);
+                }
+                catch (error) {
+                    this.rememberSet(cacheKey, cachedEntry);
+                    this.recordMutationFailure(error);
+                }
+            });
+        }, { "cache.circuit_state": this.state });
     }
     async delete(key) {
-        return withSpan("cache.resilient.delete", async () => {
-            await this.fallback.delete(key);
-            if (!this.shouldTryPrimary())
-                return;
-            try {
-                await this.primary.delete(key);
-                this.recordSuccess();
-            }
-            catch (error) {
-                this.recordFailure(error);
-            }
-        }, { "cache.key": key });
+        return await withSpan("cache.resilient.delete", async () => {
+            this.assertOpen();
+            const cacheKey = requireTokenCacheKey(key);
+            await this.enqueueMutation(() => this.deleteFromBackends(cacheKey));
+        }, { "cache.circuit_state": this.state });
     }
     async clear() {
-        return withSpan("cache.resilient.clear", async () => {
-            await this.fallback.clear();
-            if (!this.shouldTryPrimary())
-                return;
-            try {
-                await this.primary.clear();
-                this.recordSuccess();
-            }
-            catch (error) {
-                this.recordFailure(error);
-            }
-        });
+        return await withSpan("cache.resilient.clear", async () => {
+            this.assertOpen();
+            await this.enqueueMutation(async () => {
+                await this.fallback.clear();
+                if (!(await this.canUsePrimary())) {
+                    this.rememberClear();
+                    return;
+                }
+                try {
+                    await this.primary.clear();
+                    this.pendingClear = false;
+                    this.pendingMutations.clear();
+                    this.recordReadSuccess();
+                }
+                catch (error) {
+                    this.rememberClear();
+                    this.recordMutationFailure(error);
+                }
+            });
+        }, { "cache.circuit_state": this.state });
     }
     async has(key) {
-        return withSpan("cache.resilient.has", async () => {
-            if (this.shouldTryPrimary()) {
+        return await withSpan("cache.resilient.has", async () => {
+            this.assertOpen();
+            const cacheKey = requireTokenCacheKey(key);
+            if (await this.canUsePrimary()) {
                 try {
-                    const result = await this.primary.has(key);
-                    this.recordSuccess();
+                    const result = await this.primary.has(cacheKey);
+                    if (typeof result !== "boolean") {
+                        throw new TypeError("Primary token cache returned an invalid has result");
+                    }
+                    this.recordReadSuccess();
                     return result;
                 }
                 catch (error) {
-                    this.recordFailure(error);
+                    this.recordReadFailure(error);
                 }
             }
-            return this.fallback.has(key);
-        }, { "cache.key": key });
+            const fallbackResult = await this.fallback.has(cacheKey);
+            if (typeof fallbackResult !== "boolean") {
+                throw new TypeError("Fallback token cache returned an invalid has result");
+            }
+            return fallbackResult;
+        }, { "cache.circuit_state": this.state });
     }
     async stats() {
-        return withSpan("cache.resilient.stats", async () => {
-            const fallbackStats = await this.fallback.stats();
-            if (this.shouldTryPrimary()) {
+        return await withSpan("cache.resilient.stats", async () => {
+            this.assertOpen();
+            if (await this.canUsePrimary()) {
                 try {
-                    const primaryStats = await this.primary.stats();
-                    this.recordSuccess();
-                    return {
-                        ...primaryStats,
-                        type: this.usingFallback ? "memory" : "redis",
-                    };
+                    return snapshotTokenCacheStats(await this.primary.stats());
                 }
                 catch (error) {
-                    this.recordFailure(error);
+                    this.recordReadFailure(error);
                 }
             }
-            return { ...fallbackStats, type: "memory" };
-        }, { "cache.usingFallback": this.usingFallback });
+            return snapshotTokenCacheStats(await this.fallback.stats());
+        }, { "cache.circuit_state": this.state });
     }
-    async close() {
-        return withSpan("cache.resilient.close", async () => {
+    close() {
+        if (this.closePromise)
+            return this.closePromise;
+        this.closed = true;
+        const close = (async () => {
+            const failures = [];
+            await this.mutationTail;
+            if (this.recoveryPromise) {
+                try {
+                    await this.recoveryPromise;
+                }
+                catch (error) {
+                    failures.push(error);
+                }
+            }
             const results = await Promise.allSettled([
-                this.primary.close(),
-                this.fallback.close(),
+                Promise.resolve().then(() => this.primary.close()),
+                Promise.resolve().then(() => this.fallback.close()),
             ]);
             for (const result of results) {
-                if (result.status === "rejected") {
-                    logger.warn("[ResilientCache] Error closing cache:", {
-                        error: result.reason instanceof Error ? result.reason.message : result.reason,
-                    });
-                }
+                if (result.status === "rejected")
+                    failures.push(result.reason);
             }
-        });
+            this.pendingMutations.clear();
+            this.pendingClear = false;
+            if (failures.length > 0) {
+                throw new AggregateError(failures, "Failed to close resilient cache backends");
+            }
+        })();
+        this.closePromise = withSpan("cache.resilient.close", () => close);
+        return this.closePromise;
     }
     getStatus() {
-        return {
-            usingFallback: this.usingFallback,
+        return Object.freeze({
+            state: this.state,
+            usingFallback: this.state !== "closed",
             failureCount: this.failureCount,
             circuitOpenedAt: this.circuitOpenedAt,
-        };
+            pendingMutations: this.pendingMutations.size,
+            pendingClear: this.pendingClear,
+            queuedMutations: this.queuedMutations,
+        });
+    }
+    async canUsePrimary() {
+        if (this.state === "closed")
+            return true;
+        if (this.recoveryPromise)
+            return await this.recoveryPromise;
+        const currentTime = this.readClock();
+        // The injected clock is application code and can synchronously re-enter
+        // this cache. Join any recovery it started before claiming ownership.
+        if (this.recoveryPromise)
+            return await this.recoveryPromise;
+        if (this.state === "open" &&
+            currentTime - (this.circuitOpenedAt ?? currentTime) < this.openDurationMs) {
+            return false;
+        }
+        const recovery = Promise.withResolvers();
+        const owner = Object.freeze({});
+        this.recoveryOwner = owner;
+        this.recoveryPromise = recovery.promise;
+        // Install the shared promise before invoking the extension-owned cache.
+        // A synchronous callback into this cache must join this recovery instead
+        // of starting a competing probe before performRecovery reaches its await.
+        void this.performRecovery().then(recovery.resolve, recovery.reject);
+        try {
+            return await recovery.promise;
+        }
+        finally {
+            if (this.recoveryOwner === owner) {
+                this.recoveryOwner = null;
+                this.recoveryPromise = null;
+            }
+        }
+    }
+    async performRecovery() {
+        this.state = "half-open";
+        logger.debug("[ResilientCache] Circuit half-open; probing primary");
+        try {
+            const probeResult = await this.primary.has(RECOVERY_PROBE_KEY);
+            if (typeof probeResult !== "boolean") {
+                throw new TypeError("Primary token cache returned an invalid recovery probe result");
+            }
+            await this.replayPendingMutations();
+            this.state = "closed";
+            this.failureCount = 0;
+            this.circuitOpenedAt = null;
+            logger.debug("[ResilientCache] Primary recovered; circuit closed");
+            return true;
+        }
+        catch (error) {
+            this.state = "open";
+            this.failureCount = Math.max(this.failureCount, this.failureThreshold);
+            this.circuitOpenedAt = this.readClock();
+            logger.warn("[ResilientCache] Primary recovery probe failed", {
+                error: getErrorMessage(error),
+            });
+            return false;
+        }
+    }
+    async replayPendingMutations() {
+        if (this.pendingClear) {
+            await this.primary.clear();
+        }
+        for (const [key, mutation] of this.pendingMutations) {
+            if (mutation.kind === "set") {
+                if (Date.now() >= mutation.entry.expiresAt) {
+                    await this.primary.delete(key);
+                }
+                else {
+                    await this.primary.set(key, mutation.entry);
+                }
+            }
+            else {
+                await this.primary.delete(key);
+            }
+        }
+        this.pendingClear = false;
+        this.pendingMutations.clear();
+    }
+    recordReadSuccess() {
+        if (this.state !== "closed")
+            return;
+        this.failureCount = 0;
+    }
+    recordReadFailure(error) {
+        this.failureCount++;
+        logger.warn(`[ResilientCache] Primary cache error (${this.failureCount}/${this.failureThreshold})`, { error: getErrorMessage(error) });
+        if (this.failureCount >= this.failureThreshold)
+            this.openCircuit();
+    }
+    recordMutationSuccess(key) {
+        this.pendingMutations.delete(key);
+        this.recordReadSuccess();
+    }
+    recordMutationFailure(error) {
+        logger.warn("[ResilientCache] Primary cache mutation failed; opening circuit", {
+            error: getErrorMessage(error),
+        });
+        this.failureCount = Math.max(this.failureCount + 1, this.failureThreshold);
+        this.openCircuit();
+    }
+    openCircuit() {
+        const wasOpen = this.state === "open";
+        this.state = "open";
+        this.circuitOpenedAt = this.readClock();
+        if (!wasOpen) {
+            logger.warn("[ResilientCache] Circuit opened; using fallback cache");
+        }
+    }
+    rememberSet(key, entry) {
+        this.rememberMutation(key, {
+            kind: "set",
+            entry: snapshotTokenCacheEntry(entry),
+        });
+    }
+    rememberDelete(key) {
+        this.rememberMutation(key, { kind: "delete" });
+    }
+    rememberMutation(key, mutation) {
+        if (!this.pendingMutations.has(key) &&
+            this.pendingMutations.size >= MAX_PENDING_MUTATIONS) {
+            this.pendingClear = true;
+            this.pendingMutations.clear();
+        }
+        this.pendingMutations.delete(key);
+        this.pendingMutations.set(key, mutation);
+    }
+    rememberClear() {
+        this.pendingClear = true;
+        this.pendingMutations.clear();
+    }
+    assertOpen() {
+        if (this.closed)
+            throw new Error("Resilient cache is closed");
+    }
+    readClock() {
+        const value = this.now();
+        if (typeof value !== "number" ||
+            !Number.isFinite(value) ||
+            value < 0) {
+            throw new TypeError("Resilient cache clock returned an invalid time");
+        }
+        return value;
+    }
+    async deleteFromBackends(key) {
+        await this.fallback.delete(key);
+        if (!(await this.canUsePrimary())) {
+            this.rememberDelete(key);
+            return;
+        }
+        try {
+            await this.primary.delete(key);
+            this.recordMutationSuccess(key);
+        }
+        catch (error) {
+            this.rememberDelete(key);
+            this.recordMutationFailure(error);
+        }
+    }
+    enqueueMutation(operation) {
+        if (this.queuedMutations >= MAX_QUEUED_MUTATIONS) {
+            throw new Error("Resilient cache mutation queue is full");
+        }
+        this.queuedMutations++;
+        const scheduled = this.mutationTail.then(operation);
+        const result = scheduled.finally(() => {
+            this.queuedMutations--;
+        });
+        this.mutationTail = result.then(() => undefined, () => undefined);
+        return result;
     }
 }

package/esm/src/proxy/cache/tracing-cache.d.ts

@@ -2,23 +2,23 @@
  * TracingTokenCache
  *
  * Wraps a {@link TokenCache} implementation and emits an OpenTelemetry span
- * around each public method. This keeps extension-provided caches (such as
- * `@veryfront/ext-cache-redis`) tracer-agnostic: the extension implements the
- * contract only, and the proxy applies observability at the factory boundary.
- *
- * Span names default to `cache.redis.<op>` to preserve the pre-extraction
- * behavior of the in-tree RedisCache. Callers may override via
- * {@link TracingTokenCacheOptions.spanPrefix} when wrapping a different
- * backend.
+ * around each public method. The wrapped operation set is snapshotted at
+ * construction so later property replacement or accessor behavior cannot
+ * change the cache boundary underneath the proxy.
  */
 import type { CacheStats, TokenCache, TokenCacheEntry } from "./types.js";
 export interface TracingTokenCacheOptions {
-    /** Span name prefix, e.g. "cache.redis" produces "cache.redis.get". */
+    /** Span name prefix, e.g. "cache.extension" produces "cache.extension.get". */
     spanPrefix?: string;
+    /** Whether closing this wrapper also closes the wrapped cache. */
+    closeInner?: boolean;
 }
 export declare class TracingTokenCache implements TokenCache {
-    private readonly inner;
+    private readonly operations;
     private readonly prefix;
+    private readonly closeInner;
+    private closed;
+    private closePromise;
     constructor(inner: TokenCache, options?: TracingTokenCacheOptions);
     get(key: string): Promise<TokenCacheEntry | null>;
     set(key: string, entry: TokenCacheEntry): Promise<void>;
@@ -27,5 +27,6 @@ export declare class TracingTokenCache implements TokenCache {
     has(key: string): Promise<boolean>;
     stats(): Promise<CacheStats>;
     close(): Promise<void>;
+    private assertOpen;
 }
 //# sourceMappingURL=tracing-cache.d.ts.map

package/esm/src/proxy/cache/tracing-cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tracing-cache.d.ts","sourceRoot":"","sources":["../../../../src/src/proxy/cache/tracing-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAG1E,MAAM,WAAW,wBAAwB;IACvC,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B;IAKrE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQlC,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAI5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}
+{"version":3,"file":"tracing-cache.d.ts","sourceRoot":"","sources":["../../../../src/src/proxy/cache/tracing-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAW1E,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAoCD,qBAAa,iBAAkB,YAAW,UAAU;IAClD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;IAClD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IACrC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,YAAY,CAA8B;gBAEtC,KAAK,EAAE,UAAU,EAAE,OAAO,GAAE,wBAA6B;IAcrE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAQjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBvD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWlC,KAAK,IAAI,OAAO,CAAC,UAAU,CAAC;IAO5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB,OAAO,CAAC,UAAU;CAGnB"}