@apifuse/provider-sdk 2.1.0-beta.5 → 2.1.0-beta.8

package/dist/runtime/cache.d.ts

@@ -0,0 +1,10 @@
+import type { ProviderCache } from "../types";
+export type ProviderCacheOptions = {
+    providerId: string;
+    redisUrl?: string;
+    memoryMaxEntries?: number;
+    now?: () => number;
+};
+export declare function createProviderCache(options: ProviderCacheOptions): ProviderCache;
+export declare function createBypassProviderCache(options: Pick<ProviderCacheOptions, "providerId">): ProviderCache;
+export declare function resetProviderCacheForTests(): void;

package/dist/runtime/cache.js

@@ -0,0 +1,372 @@
+import { createHash } from "node:crypto";
+import { providerCacheRedisUrlFromEnv } from "../config/loader";
+import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis";
+const DEFAULT_PREFIX = "apifuse:provider-cache:v1";
+const DEFAULT_MEMORY_MAX_ENTRIES = 1_000;
+const DEFAULT_REDIS_TIMEOUT_MS = 150;
+const SECRET_FIELD_NAMES = new Set([
+    "authorization",
+    "cookie",
+    "password",
+    "secret",
+    "servicekey",
+    "service_key",
+    "token",
+    "apikey",
+    "api_key",
+    "access_token",
+    "refresh_token",
+]);
+const sharedBackends = new Map();
+function backendKey(redisUrl) {
+    return redisUrl ?? "memory";
+}
+function getSharedBackend(redisUrl) {
+    const key = backendKey(redisUrl);
+    const existing = sharedBackends.get(key);
+    if (existing)
+        return existing;
+    const backend = {
+        memory: new Map(),
+        inflight: new Map(),
+    };
+    if (redisUrl) {
+        const redis = createProviderRedisClient({
+            redisUrl,
+            timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
+            onError: () => {
+                // Fail-open: cache connectivity must never fail provider execution.
+            },
+        });
+        backend.redis = redis;
+    }
+    sharedBackends.set(key, backend);
+    return backend;
+}
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function shouldRedactField(name, extra) {
+    const normalized = name.toLowerCase();
+    return (SECRET_FIELD_NAMES.has(normalized) ||
+        extra.has(normalized) ||
+        normalized.includes("authorization") ||
+        normalized.includes("cookie") ||
+        normalized.includes("password") ||
+        normalized.includes("secret"));
+}
+function normalizeKeyPart(value, extra) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeKeyPart(entry, extra));
+    }
+    if (isRecord(value)) {
+        const normalized = {};
+        for (const key of Object.keys(value).sort()) {
+            if (shouldRedactField(key, extra))
+                continue;
+            normalized[key] = normalizeKeyPart(value[key], extra);
+        }
+        return normalized;
+    }
+    return value;
+}
+function stableHash(value) {
+    return createHash("sha256")
+        .update(JSON.stringify(value))
+        .digest("hex")
+        .slice(0, 32);
+}
+function jitteredTtlMs(ttlMs, jitterPct) {
+    if (!jitterPct || jitterPct <= 0)
+        return ttlMs;
+    const bounded = Math.min(jitterPct, 0.5);
+    const delta = ttlMs * bounded;
+    const multiplier = 1 - bounded + (Math.random() * delta * 2) / ttlMs;
+    return Math.max(1, Math.round(ttlMs * multiplier));
+}
+function safeParseEnvelope(raw) {
+    if (!raw)
+        return null;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed) ||
+            typeof parsed.writtenAt !== "number" ||
+            typeof parsed.freshUntil !== "number" ||
+            typeof parsed.staleUntil !== "number" ||
+            !("value" in parsed)) {
+            return null;
+        }
+        return {
+            value: parsed.value,
+            writtenAt: parsed.writtenAt,
+            freshUntil: parsed.freshUntil,
+            staleUntil: parsed.staleUntil,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function resultWithValue(value, meta) {
+    return {
+        value: value,
+        meta,
+    };
+}
+function resultFromEnvelope(key, envelope, now, source) {
+    if (now > envelope.staleUntil)
+        return null;
+    return resultWithValue(envelope.value, {
+        key,
+        hit: true,
+        stale: now > envelope.freshUntil,
+        ageMs: Math.max(0, now - envelope.writtenAt),
+        source,
+    });
+}
+function sourceSummary(events) {
+    const sources = new Set(events.map((event) => event.source));
+    if (sources.size === 0)
+        return undefined;
+    if (sources.size === 1)
+        return events[0]?.source;
+    return "mixed";
+}
+async function withRedisFallback(operation) {
+    return await withRedisTimeout(operation, {
+        timeoutMs: DEFAULT_REDIS_TIMEOUT_MS,
+        onTimeout: () => undefined,
+        onError: () => undefined,
+    });
+}
+export function createProviderCache(options) {
+    const redisUrl = options.redisUrl ?? providerCacheRedisUrlFromEnv();
+    const backend = getSharedBackend(redisUrl);
+    const memoryMaxEntries = Math.max(1, options.memoryMaxEntries ?? DEFAULT_MEMORY_MAX_ENTRIES);
+    const now = options.now ?? Date.now;
+    const events = [];
+    function record(meta) {
+        events.push(meta);
+    }
+    function sweepMemory(currentTime) {
+        for (const [entryKey, entry] of backend.memory) {
+            if (entry.expiresAt <= currentTime) {
+                backend.memory.delete(entryKey);
+            }
+        }
+    }
+    function enforceMemoryLimit() {
+        while (backend.memory.size > memoryMaxEntries) {
+            const oldestKey = backend.memory.keys().next().value;
+            if (typeof oldestKey !== "string")
+                return;
+            backend.memory.delete(oldestKey);
+        }
+    }
+    function rememberEnvelope(key, envelope, currentTime) {
+        sweepMemory(currentTime);
+        backend.memory.delete(key);
+        backend.memory.set(key, {
+            ...envelope,
+            expiresAt: envelope.staleUntil,
+            lastAccessedAt: currentTime,
+        });
+        enforceMemoryLimit();
+    }
+    function touchMemory(key, entry, currentTime) {
+        backend.memory.delete(key);
+        backend.memory.set(key, { ...entry, lastAccessedAt: currentTime });
+    }
+    async function readRedis(key, currentTime) {
+        const redis = backend.redis;
+        if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+            return null;
+        }
+        const raw = await withRedisFallback(async () => {
+            return await redis.get(key);
+        });
+        if (typeof raw !== "string" && raw !== null)
+            return null;
+        const envelope = safeParseEnvelope(raw);
+        if (!envelope)
+            return null;
+        const result = resultFromEnvelope(key, envelope, currentTime, "redis");
+        if (!result)
+            return null;
+        rememberEnvelope(key, envelope, currentTime);
+        return { envelope, result };
+    }
+    async function read(key) {
+        const currentTime = now();
+        const memoryEntry = backend.memory.get(key);
+        let staleMemoryResult = null;
+        let staleMemoryWrittenAt;
+        if (memoryEntry) {
+            if (memoryEntry.expiresAt <= currentTime) {
+                backend.memory.delete(key);
+            }
+            else {
+                const memoryResult = resultFromEnvelope(key, memoryEntry, currentTime, "memory");
+                if (memoryResult && !memoryResult.meta.stale) {
+                    touchMemory(key, memoryEntry, currentTime);
+                    return memoryResult;
+                }
+                staleMemoryResult = memoryResult;
+                staleMemoryWrittenAt = memoryEntry.writtenAt;
+                touchMemory(key, memoryEntry, currentTime);
+            }
+        }
+        const redisResult = await readRedis(key, currentTime);
+        if (redisResult) {
+            if (!staleMemoryResult)
+                return redisResult.result;
+            if (!redisResult.result.meta.stale ||
+                redisResult.envelope.writtenAt >= (staleMemoryWrittenAt ?? 0)) {
+                return redisResult.result;
+            }
+        }
+        return staleMemoryResult;
+    }
+    async function write(key, value, cacheOptions) {
+        const currentTime = now();
+        const freshTtlMs = jitteredTtlMs(cacheOptions.ttlMs, cacheOptions.jitterPct);
+        const staleIfErrorMs = cacheOptions.staleIfErrorMs ?? 0;
+        const staleTtlMs = freshTtlMs + staleIfErrorMs;
+        const envelope = {
+            value,
+            writtenAt: currentTime,
+            freshUntil: currentTime + freshTtlMs,
+            staleUntil: currentTime + staleTtlMs,
+        };
+        rememberEnvelope(key, envelope, currentTime);
+        const redis = backend.redis;
+        if (!redis || !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+            return;
+        }
+        await withRedisFallback(() => redis.set(key, JSON.stringify(envelope), "PX", staleTtlMs));
+    }
+    async function loadAndStore(key, loader, cacheOptions, staleCandidate) {
+        try {
+            const value = await loader();
+            await write(key, value, cacheOptions);
+            return {
+                value,
+                meta: {
+                    key,
+                    hit: false,
+                    stale: false,
+                    source: "loader",
+                },
+            };
+        }
+        catch (error) {
+            if (staleCandidate?.meta.stale) {
+                return staleCandidate;
+            }
+            throw error;
+        }
+    }
+    return {
+        key(namespace, parts, keyOptions) {
+            const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
+            const normalized = normalizeKeyPart(parts, extra);
+            return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+        },
+        async get(key) {
+            const result = await read(key);
+            if (result)
+                record(result.meta);
+            return result;
+        },
+        set: write,
+        async delete(key) {
+            backend.memory.delete(key);
+            const redis = backend.redis;
+            if (!redis ||
+                !(await ensureRedisReady(redis, DEFAULT_REDIS_TIMEOUT_MS))) {
+                return;
+            }
+            await withRedisFallback(() => redis.del(key));
+        },
+        async getOrSet(key, loader, cacheOptions) {
+            const existing = await read(key);
+            if (existing && !existing.meta.stale) {
+                record(existing.meta);
+                return existing;
+            }
+            const existingInflight = backend.inflight.get(key);
+            if (existingInflight) {
+                const inflightResult = await existingInflight;
+                const result = resultWithValue(inflightResult.value, inflightResult.meta);
+                record(result.meta);
+                return result;
+            }
+            const promise = loadAndStore(key, loader, cacheOptions, existing).finally(() => {
+                backend.inflight.delete(key);
+            });
+            backend.inflight.set(key, promise);
+            const loaded = await promise;
+            const result = resultWithValue(loaded.value, loaded.meta);
+            record(result.meta);
+            return result;
+        },
+        responseMeta() {
+            if (events.length === 0)
+                return undefined;
+            return {
+                hit: events.some((event) => event.hit),
+                stale: events.some((event) => event.stale),
+                keys: Array.from(new Set(events.map((event) => event.key))),
+                source: sourceSummary(events),
+            };
+        },
+    };
+}
+export function createBypassProviderCache(options) {
+    const events = [];
+    return {
+        key(namespace, parts, keyOptions) {
+            const extra = new Set((keyOptions?.redactFields ?? []).map((field) => field.toLowerCase()));
+            const normalized = normalizeKeyPart(parts, extra);
+            return `${DEFAULT_PREFIX}:${options.providerId}:${namespace}:${stableHash(normalized)}`;
+        },
+        async get(_key) {
+            return null;
+        },
+        async set() {
+            // Intentionally disabled for SDK tools that must hit upstream directly.
+        },
+        async delete() {
+            // Intentionally disabled for SDK tools that must hit upstream directly.
+        },
+        async getOrSet(key, loader) {
+            const value = await loader();
+            const meta = {
+                key,
+                hit: false,
+                stale: false,
+                source: "loader",
+            };
+            events.push(meta);
+            return { value, meta };
+        },
+        responseMeta() {
+            if (events.length === 0)
+                return undefined;
+            return {
+                hit: false,
+                stale: false,
+                keys: Array.from(new Set(events.map((event) => event.key))),
+                source: sourceSummary(events),
+            };
+        },
+    };
+}
+export function resetProviderCacheForTests() {
+    for (const backend of sharedBackends.values()) {
+        backend.memory.clear();
+        backend.inflight.clear();
+        backend.redis?.disconnect();
+    }
+    sharedBackends.clear();
+}

package/dist/runtime/choice.d.ts

@@ -0,0 +1,15 @@
+import type { CredentialContext, EnvContext, ProviderChoiceContext, ProviderRequestContext, ProviderRuntimeState } from "../types";
+export declare const PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV = "APIFUSE__PROVIDER_RUNTIME__CHOICE_TOKEN_MASTER_SECRET";
+export type CreateProviderChoiceContextOptions = {
+    readonly providerId: string;
+    readonly env?: EnvContext;
+    readonly request?: ProviderRequestContext;
+    readonly credential?: CredentialContext;
+    readonly state?: ProviderRuntimeState;
+    readonly masterSecret?: string;
+    readonly kid?: string;
+};
+export declare function createProviderChoiceContext(options: CreateProviderChoiceContextOptions): ProviderChoiceContext;
+export declare function createTestProviderChoiceContext(options: Omit<CreateProviderChoiceContextOptions, "masterSecret"> & {
+    readonly masterSecret?: string;
+}): ProviderChoiceContext;