@apifuse/provider-sdk 2.2.0-beta.2 → 2.2.0-beta.21

package/dist/runtime/secrets.js

@@ -0,0 +1,51 @@
+import { ProviderSecretError } from "../errors.js";
+/**
+ * Canonical error code for a declared-but-unprovisioned provider secret.
+ *
+ * The SDK is the single source of truth for env/secret presence validation:
+ * providers declare secrets in `defineProvider({ secrets: [...] })` and the
+ * runtime enforces presence before any handler or auth-flow code runs.
+ * Provider-local presence guards (requireServiceKey/requireApiKey style) are a
+ * deprecated antipattern — see the `sdk-owned-secret-presence` submit-check
+ * rule.
+ */
+export const MISSING_SECRET_CODE = "MISSING_SECRET";
+/**
+ * Names of declared `required: true` secrets whose env values are unset or
+ * whitespace-only. Whitespace-only values count as missing for parity with the
+ * `.trim()` guards well-built providers used before the SDK owned this check —
+ * a blank value provisioned by a broken secret pipeline must not pass the gate.
+ */
+export function listMissingRequiredSecrets(provider, env) {
+    const missing = [];
+    for (const secret of provider.secrets ?? []) {
+        if (secret.required !== true) {
+            continue;
+        }
+        const value = env.get(secret.name);
+        if (value === undefined || value.trim() === "") {
+            missing.push(secret.name);
+        }
+    }
+    return missing;
+}
+/**
+ * Throws the canonical structured missing-secret error when any declared
+ * `required: true` secret is absent. All missing names are reported in a
+ * single error so operators can provision the full set in one pass instead of
+ * discovering them one deploy at a time (the 2026-07-22 unprovisioned-secret
+ * incident failure mode).
+ */
+export function assertRequiredSecretsPresent(provider, env) {
+    const missing = listMissingRequiredSecrets(provider, env);
+    if (missing.length === 0) {
+        return;
+    }
+    const names = missing.join(", ");
+    throw new ProviderSecretError(`Missing required provider secret${missing.length > 1 ? "s" : ""}: ${names}`, {
+        code: MISSING_SECRET_CODE,
+        category: "credential_unavailable",
+        retryable: false,
+        fix: `Provision ${names} in the provider environment (e.g. Doppler). Declared in defineProvider({ secrets: [...] }).`,
+    });
+}

package/dist/runtime/state.d.ts

@@ -1,5 +1,5 @@
-import { ProviderError } from "../errors";
-import type { ProviderRuntimeState } from "../types";
+import { ProviderError } from "../errors.js";
+import type { ProviderRuntimeState } from "../types.js";
 type RedisProviderRuntimeStateOptions = {
     readonly redisUrl: string;
     readonly providerId?: string;

package/dist/runtime/state.js

@@ -1,8 +1,92 @@
-import { providerStateRedisUrlFromEnv } from "../config/loader";
-import { ProviderError } from "../errors";
-import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis";
+import { providerStateRedisUrlFromEnv } from "../config/loader.js";
+import { ProviderError } from "../errors.js";
+import { createProviderRedisClient, ensureRedisReady, withRedisTimeout, } from "./redis.js";
 const DEFAULT_REDIS_TIMEOUT_MS = 250;
 const REDIS_STATE_PREFIX = "apifuse:provider-state:v1";
+const LEGACY_INDEX_SCAN_COUNT = 256;
+const LEGACY_INDEX_SCAN_MAX_PAGES = 8;
+const SET_WITH_QUOTA_SCRIPT = `
+local now = tonumber(ARGV[1])
+local max_entries = tonumber(ARGV[2])
+local expires_at = tonumber(ARGV[3])
+local index_ttl = tonumber(ARGV[4])
+local envelope = ARGV[5]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = redis.call("EXISTS", KEYS[1])
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const COMPARE_AND_SET_WITH_QUOTA_SCRIPT = `
+local current = redis.call("GET", KEYS[1])
+local current_version = 0
+if current then
+	local ok, decoded = pcall(cjson.decode, current)
+	if not ok or type(decoded) ~= "table" or type(decoded.version) ~= "number" then
+		return {-2, current}
+	end
+	current_version = decoded.version
+end
+if current_version ~= tonumber(ARGV[1]) then
+	return {-1, current or false}
+end
+
+local now = tonumber(ARGV[2])
+local max_entries = tonumber(ARGV[3])
+local expires_at = tonumber(ARGV[4])
+local index_ttl = tonumber(ARGV[5])
+local envelope = ARGV[6]
+redis.call("ZREMRANGEBYSCORE", KEYS[2], "-inf", now)
+local exists = current and 1 or 0
+local indexed = redis.call("ZSCORE", KEYS[2], KEYS[1])
+if exists == 0 and not indexed and redis.call("ZCARD", KEYS[2]) >= max_entries then
+	return {0, false}
+end
+
+redis.call("SET", KEYS[1], envelope, "PXAT", expires_at)
+redis.call("ZADD", KEYS[2], expires_at, KEYS[1])
+redis.call("PEXPIRE", KEYS[2], index_ttl)
+return {1, envelope}
+`;
+const DELETE_WITH_INDEX_SCRIPT = `
+redis.call("DEL", KEYS[1])
+redis.call("ZREM", KEYS[2], KEYS[1])
+return 1
+`;
+// Older SDKs wrote only the value key. Every operation that depends on the
+// namespace index advances a bounded SCAN cursor and lazily imports active
+// legacy envelopes into the new ZSET. The cursor is
+// deliberately cyclic rather than permanently "complete": an old pod may
+// still write an unindexed key during a rolling deploy. Each list/write call
+// does a fixed amount of migration work; Redis KEYS and unbounded scans remain
+// forbidden.
+const BACKFILL_LEGACY_INDEX_SCRIPT = `
+local now = tonumber(ARGV[1])
+local index_ttl = tonumber(ARGV[2])
+local next_cursor = ARGV[3]
+
+redis.call("ZREMRANGEBYSCORE", KEYS[1], "-inf", now)
+for i = 4, #ARGV, 3 do
+	local key = ARGV[i]
+	local expected = ARGV[i + 1]
+	local expires_at = tonumber(ARGV[i + 2])
+	if redis.call("GET", key) == expected then
+		redis.call("ZADD", KEYS[1], "NX", expires_at, key)
+	end
+end
+if redis.call("EXISTS", KEYS[1]) == 1 then
+	redis.call("PEXPIRE", KEYS[1], index_ttl)
+end
+redis.call("SET", KEYS[2], next_cursor, "PX", index_ttl)
+return redis.call("ZCARD", KEYS[1])
+`;
 const redisBackends = new Map();
 function getRedisBackend(redisUrl) {
     const existing = redisBackends.get(redisUrl);
@@ -46,6 +130,9 @@ function publicStateKey(providerId, namespace, redisKey) {
     const prefix = `${providerStatePrefix(providerId, namespace)}:`;
     return redisKey.startsWith(prefix) ? redisKey.slice(prefix.length) : redisKey;
 }
+function redisGlobLiteral(value) {
+    return value.replace(/[\\*?\[\]]/g, "\\$&");
+}
 function parseStateDurationMs(ttl) {
     const match = /^(\d+)(ms|s|m|h|d)$/.exec(ttl ?? "1h");
     if (!match)
@@ -69,7 +156,18 @@ function resolveExpiresAt(ttl) {
 function envelopeFromJson(key, raw) {
     if (!raw)
         return null;
-    const parsed = JSON.parse(raw);
+    // A corrupt/undecodable persisted envelope must be treated as absent rather
+    // than throwing a raw JSON.parse SyntaxError: an uncaught SyntaxError escapes
+    // the provider error taxonomy, is masked as internal_error 500, and is then
+    // retried by the hub (2026-07-22 catchtable reserve RCA, candidate A). Returning
+    // null also keeps list() from aborting the whole scan on a single bad entry.
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
         return null;
     }
@@ -108,12 +206,55 @@ class RedisProviderStateNamespace {
     redisKey(key) {
         return providerStateKey(this.providerId, this.namespaceName, key);
     }
-    prefix() {
+    indexKey() {
+        // Keep bookkeeping outside the caller-owned keyspace. A provider may use
+        // any state key (including "__index"), so a suffix inside the namespace
+        // could turn the ZSET into a string and break every subsequent write.
+        const namespaceIdentity = Buffer.from(providerStatePrefix(this.providerId, this.namespaceName), "utf8").toString("base64url");
+        return `${REDIS_STATE_PREFIX}:index:${namespaceIdentity}`;
+    }
+    legacyScanCursorKey() {
+        return `${this.indexKey()}:legacy-scan-cursor`;
+    }
+    legacyPrefix() {
         return `${providerStatePrefix(this.providerId, this.namespaceName)}:`;
     }
-    async activeKeys() {
+    async backfillLegacyIndex() {
+        await requireRedisReady(this.backend.redis);
+        const cursorKey = this.legacyScanCursorKey();
+        let cursor = (await withRequiredRedis(() => this.backend.redis.get(cursorKey))) ?? "0";
+        const pattern = `${redisGlobLiteral(this.legacyPrefix())}*`;
+        const indexTtlMs = parseStateDurationMs(this.options.maxTtl);
+        for (let page = 0; page < LEGACY_INDEX_SCAN_MAX_PAGES; page += 1) {
+            const [nextCursor, keys] = await withRequiredRedis(() => this.backend.redis.scan(cursor, "MATCH", pattern, "COUNT", LEGACY_INDEX_SCAN_COUNT));
+            const rawValues = keys.length > 0
+                ? await withRequiredRedis(() => this.backend.redis.mget(keys))
+                : [];
+            const now = Date.now();
+            const activeLegacyArgs = [];
+            for (const [index, raw] of rawValues.entries()) {
+                const key = keys[index];
+                if (!key || !raw)
+                    continue;
+                const envelope = envelopeFromJson(publicStateKey(this.providerId, this.namespaceName, key), raw);
+                const expiresAtMs = envelope ? Date.parse(envelope.expiresAt) : Number.NaN;
+                if (!Number.isFinite(expiresAtMs) || expiresAtMs <= now)
+                    continue;
+                activeLegacyArgs.push(key, raw, String(expiresAtMs));
+            }
+            await withRequiredRedis(() => this.backend.redis.eval(BACKFILL_LEGACY_INDEX_SCRIPT, 2, this.indexKey(), cursorKey, String(now), String(indexTtlMs), nextCursor, ...activeLegacyArgs));
+            cursor = nextCursor;
+            if (cursor === "0")
+                break;
+        }
+    }
+    async indexedKeys(limit) {
         await requireRedisReady(this.backend.redis);
-        return await withRequiredRedis(() => this.backend.redis.keys(`${this.prefix()}*`));
+        const now = Date.now();
+        return await withRequiredRedis(async () => {
+            await this.backend.redis.zremrangebyscore(this.indexKey(), "-inf", now);
+            return await this.backend.redis.zrangebyscore(this.indexKey(), now + 1, "+inf", "LIMIT", 0, limit);
+        });
     }
     enforceValueSize(value) {
         const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
@@ -121,20 +262,32 @@ class RedisProviderStateNamespace {
             throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
         }
     }
-    async enforceMaxEntries(key) {
-        const keys = await this.activeKeys();
-        const redisKey = this.redisKey(key);
-        const otherKeys = keys.filter((candidate) => candidate !== redisKey);
-        if (otherKeys.length >= this.options.maxEntries) {
-            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${otherKeys.length + 1} > ${this.options.maxEntries})`);
+    quotaExceeded() {
+        return new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+    }
+    writeTiming(ttl) {
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
         }
+        const expiresAtMs = Date.now() + ttlMs;
+        return {
+            expiresAt: new Date(expiresAtMs).toISOString(),
+            expiresAtMs,
+            indexTtlMs: maxTtlMs,
+        };
     }
     async list(options) {
-        const keys = (await this.activeKeys()).filter((key) => {
+        const requestedLimit = Math.max(0, options?.limit ?? this.options.maxEntries);
+        if (requestedLimit === 0)
+            return [];
+        await this.backfillLegacyIndex();
+        const keys = (await this.indexedKeys(this.options.maxEntries)).filter((key) => {
             const publicKey = publicStateKey(this.providerId, this.namespaceName, key);
             return options?.prefix ? publicKey.startsWith(options.prefix) : true;
         });
-        const limited = keys.slice(0, Math.max(0, options?.limit ?? keys.length));
+        const limited = keys.slice(0, requestedLimit);
         if (limited.length === 0)
             return [];
         const values = await withRequiredRedis(() => this.backend.redis.mget(limited));
@@ -153,20 +306,22 @@ class RedisProviderStateNamespace {
     }
     async set(key, value, options) {
         this.enforceValueSize(value);
-        await this.enforceMaxEntries(key);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         const createdAt = current?.createdAt ?? new Date().toISOString();
         const version = (current?.version ?? 0) + 1;
-        const ttl = options?.ttl ?? this.options.defaultTtl;
-        const ttlMs = parseStateDurationMs(ttl);
-        const expiresAt = resolveExpiresAt(ttl);
-        const envelope = redisEnvelope(value, version, createdAt, expiresAt);
-        await withRequiredRedis(() => this.backend.redis.set(this.redisKey(key), JSON.stringify(envelope), "PX", ttlMs));
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, version, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            throw this.quotaExceeded();
+        }
         return {
             key,
             value,
             version,
-            expiresAt,
+            expiresAt: timing.expiresAt,
             createdAt,
             updatedAt: envelope.updatedAt,
         };
@@ -179,15 +334,38 @@ class RedisProviderStateNamespace {
     }
     async compareAndSet(key, expectedVersion, value, options) {
         this.enforceValueSize(value);
+        await this.backfillLegacyIndex();
         const current = await this.get(key);
         if ((current?.version ?? 0) !== expectedVersion) {
             return { ok: false, current };
         }
-        return { ok: true, value: await this.set(key, value, options) };
+        const createdAt = current?.createdAt ?? new Date().toISOString();
+        const timing = this.writeTiming(options?.ttl);
+        const envelope = redisEnvelope(value, expectedVersion + 1, createdAt, timing.expiresAt);
+        await requireRedisReady(this.backend.redis);
+        const result = await withRequiredRedis(() => this.backend.redis.eval(COMPARE_AND_SET_WITH_QUOTA_SCRIPT, 2, this.redisKey(key), this.indexKey(), String(expectedVersion), String(Date.now()), String(this.options.maxEntries), String(timing.expiresAtMs), String(timing.indexTtlMs), JSON.stringify(envelope)));
+        if (Array.isArray(result) && Number(result[0]) === 0) {
+            throw this.quotaExceeded();
+        }
+        if (!Array.isArray(result) || Number(result[0]) !== 1) {
+            const rawCurrent = Array.isArray(result) && typeof result[1] === "string" ? result[1] : null;
+            return { ok: false, current: envelopeFromJson(key, rawCurrent) };
+        }
+        return {
+            ok: true,
+            value: {
+                key,
+                value,
+                version: envelope.version,
+                expiresAt: timing.expiresAt,
+                createdAt,
+                updatedAt: envelope.updatedAt,
+            },
+        };
     }
     async delete(key) {
         await requireRedisReady(this.backend.redis);
-        await withRequiredRedis(() => this.backend.redis.del(this.redisKey(key)));
+        await withRequiredRedis(() => this.backend.redis.eval(DELETE_WITH_INDEX_SCRIPT, 2, this.redisKey(key), this.indexKey()));
     }
     async increment(key, field, delta = 1, options) {
         const current = (await this.get(key))?.value ?? {};
@@ -247,6 +425,23 @@ class MemoryProviderStateNamespace {
     constructor(options) {
         this.options = options;
     }
+    enforceValueSize(value) {
+        const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+        if (bytes > this.options.maxValueBytes) {
+            throw new UnsupportedProviderStateError(`Provider runtime state value exceeds maxValueBytes (${bytes} > ${this.options.maxValueBytes})`);
+        }
+    }
+    enforceWritePolicy(key, value, ttl) {
+        this.enforceValueSize(value);
+        const ttlMs = parseStateDurationMs(ttl ?? this.options.defaultTtl);
+        const maxTtlMs = parseStateDurationMs(this.options.maxTtl);
+        if (ttlMs > maxTtlMs) {
+            throw new UnsupportedProviderStateError(`Provider runtime state ttl exceeds maxTtl (${ttlMs} > ${maxTtlMs})`);
+        }
+        if (!this.values.has(key) && this.values.size >= this.options.maxEntries) {
+            throw new UnsupportedProviderStateError(`Provider runtime state namespace quota exceeded (${this.options.maxEntries + 1} > ${this.options.maxEntries})`);
+        }
+    }
     pruneExpired(nowMs = Date.now()) {
         for (const [key, row] of this.values.entries()) {
             if (row.expiresAt && Date.parse(row.expiresAt) <= nowMs) {
@@ -265,6 +460,7 @@ class MemoryProviderStateNamespace {
     }
     async set(key, value, options) {
         this.pruneExpired();
+        this.enforceWritePolicy(key, value, options?.ttl);
         const now = new Date().toISOString();
         const current = this.values.get(key);
         const expiresAt = resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl);
@@ -282,8 +478,24 @@ class MemoryProviderStateNamespace {
     async patch(_key, _partial, _options) {
         throw new UnsupportedProviderStateError("In-memory provider runtime state does not support patch");
     }
-    async compareAndSet(_key, _expectedVersion, _value, _options) {
-        throw new UnsupportedProviderStateError("In-memory provider runtime state does not support compareAndSet");
+    async compareAndSet(key, expectedVersion, value, options) {
+        this.pruneExpired();
+        const current = this.values.get(key);
+        if ((current?.version ?? 0) !== expectedVersion) {
+            return { ok: false, current: current ?? null };
+        }
+        this.enforceWritePolicy(key, value, options?.ttl);
+        const now = new Date().toISOString();
+        const stored = {
+            key,
+            value,
+            version: expectedVersion + 1,
+            expiresAt: resolveMemoryStateExpiresAt(options?.ttl ?? this.options.defaultTtl),
+            createdAt: current?.createdAt ?? now,
+            updatedAt: now,
+        };
+        this.values.set(key, stored);
+        return { ok: true, value: stored };
     }
     async delete(key) {
         this.values.delete(key);

package/dist/runtime/stealth.d.ts

@@ -1,6 +1,6 @@
 import type { ImpitResponse } from "impit";
-import type { ProxyResolutionOptions } from "../config/loader";
-import type { StealthClient, StealthResponse } from "../types";
+import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { StealthClient, StealthResponse } from "../types.js";
 export type StealthClientOptions = ProxyResolutionOptions & {
     warn?: (message: string) => void;
     /**
@@ -13,9 +13,11 @@ export type StealthClientOptions = ProxyResolutionOptions & {
     };
 };
 type StealthTransportResponse = Pick<ImpitResponse, "arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"> & {
+    body?: ReadableStream<Uint8Array>;
+    abort?: () => void;
     url?: string;
     redirected?: boolean;
 };
-export declare function normalizeResponse(response: StealthTransportResponse, requestUrl?: string): Promise<StealthResponse>;
+export declare function normalizeResponse(response: StealthTransportResponse, requestUrl?: string, maxBodyBytes?: number): Promise<StealthResponse>;
 export declare function createStealthClient(baseUrl: string, defaultProfileOrOptions?: string | StealthClientOptions, clientOptions?: StealthClientOptions): StealthClient;
 export {};