@apifuse/provider-sdk 2.2.0-beta.1 → 2.2.0-beta.10

package/dist/runtime/proxy-retry-policy.js

@@ -0,0 +1,326 @@
+import { ProviderError, TransportError } from "../errors.js";
+import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types.js";
+export const DEFAULT_PROXY_TRANSPORT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
+export const DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES = [
+    "transport_network_error",
+    "transport_timeout",
+];
+const SAFE_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
+const RATE_LIMIT_RETRY_STATUS_CODES = [429, 503];
+const RATE_LIMIT_RETRY_ERROR_CODES = ["transport_timeout"];
+const KNOWN_RETRY_METHODS = new Set([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "DELETE",
+    "OPTIONS",
+    "TRACE",
+    "PATCH",
+]);
+const UNSAFE_RETRY_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE", "TRACE"]);
+export const MAX_PROXY_TRANSPORT_RETRY_ATTEMPTS = 8;
+const MAX_RETRY_DELAY_MS = 30_000;
+function hasOwnValue(values, value) {
+    if (typeof value !== "string")
+        return false;
+    return Object.values(values).some((candidate) => candidate === value);
+}
+function createInvalidRetryPolicyError(message, label) {
+    return new ProviderError(message.replace("{{label}}", label), {
+        code: "retry_invalid_policy",
+    });
+}
+function retryErrorCode(error) {
+    if (error instanceof TransportError) {
+        return error.code;
+    }
+    if (error && typeof error === "object" && "code" in error) {
+        const code = Reflect.get(error, "code");
+        return typeof code === "string" ? code : undefined;
+    }
+    return undefined;
+}
+function retryErrorStatus(error) {
+    if (error instanceof TransportError) {
+        return error.status ?? error.upstreamStatus;
+    }
+    return undefined;
+}
+export function proxyTransportRetryErrorCode(error) {
+    return retryErrorCode(error);
+}
+export function proxyTransportRetryErrorStatus(error) {
+    return retryErrorStatus(error);
+}
+function createRetryOptions(preset, extraErrorCodes, label) {
+    const defaultErrorCodes = [...DEFAULT_PROXY_TRANSPORT_RETRY_ERROR_CODES, ...extraErrorCodes];
+    switch (preset) {
+        case HttpRetryPreset.Off:
+            return {
+                preset,
+                attempts: 1,
+                methods: DEFAULT_PROXY_TRANSPORT_RETRY_METHODS,
+                statusCodes: [],
+                errorCodes: defaultErrorCodes,
+                delayStrategy: HttpRetryDelayStrategy.Exponential,
+                baseDelayMs: 100,
+                maxDelayMs: 1_000,
+                jitter: HttpRetryJitter.Full,
+                retryAfter: HttpRetryAfterPolicy.Ignore,
+                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
+            };
+        case HttpRetryPreset.SafeRead:
+            return {
+                preset,
+                attempts: 3,
+                methods: DEFAULT_PROXY_TRANSPORT_RETRY_METHODS,
+                statusCodes: SAFE_RETRY_STATUS_CODES,
+                errorCodes: defaultErrorCodes,
+                delayStrategy: HttpRetryDelayStrategy.Exponential,
+                baseDelayMs: 100,
+                maxDelayMs: 2_000,
+                jitter: HttpRetryJitter.Full,
+                retryAfter: HttpRetryAfterPolicy.Cap,
+                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
+            };
+        case HttpRetryPreset.AggressiveRead:
+            return {
+                preset,
+                attempts: 4,
+                methods: DEFAULT_PROXY_TRANSPORT_RETRY_METHODS,
+                statusCodes: SAFE_RETRY_STATUS_CODES,
+                errorCodes: defaultErrorCodes,
+                delayStrategy: HttpRetryDelayStrategy.Exponential,
+                baseDelayMs: 150,
+                maxDelayMs: 5_000,
+                jitter: HttpRetryJitter.Full,
+                retryAfter: HttpRetryAfterPolicy.Cap,
+                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
+            };
+        case HttpRetryPreset.RateLimitAware:
+            return {
+                preset,
+                attempts: 3,
+                methods: DEFAULT_PROXY_TRANSPORT_RETRY_METHODS,
+                statusCodes: RATE_LIMIT_RETRY_STATUS_CODES,
+                errorCodes: RATE_LIMIT_RETRY_ERROR_CODES,
+                delayStrategy: HttpRetryDelayStrategy.Exponential,
+                baseDelayMs: 250,
+                maxDelayMs: 5_000,
+                jitter: HttpRetryJitter.Equal,
+                retryAfter: HttpRetryAfterPolicy.Respect,
+                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
+            };
+        case HttpRetryPreset.TransportTransient:
+            return {
+                preset,
+                attempts: 3,
+                methods: DEFAULT_PROXY_TRANSPORT_RETRY_METHODS,
+                statusCodes: [],
+                errorCodes: defaultErrorCodes,
+                delayStrategy: HttpRetryDelayStrategy.Exponential,
+                baseDelayMs: 100,
+                maxDelayMs: 1_000,
+                jitter: HttpRetryJitter.Full,
+                retryAfter: HttpRetryAfterPolicy.Ignore,
+                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
+            };
+    }
+    throw createInvalidRetryPolicyError(`Unknown ${label} retry preset: ${preset}`, label);
+}
+function clampPositiveInteger(value, fallback, max) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 1)
+        return fallback;
+    return Math.min(Math.floor(value), max);
+}
+function clampDelay(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 0)
+        return fallback;
+    return Math.min(Math.floor(value), MAX_RETRY_DELAY_MS);
+}
+export function createDefaultProxyTransportRetryOptions(options = {}) {
+    return createRetryOptions(HttpRetryPreset.TransportTransient, options.extraErrorCodes ?? [], options.label ?? "Proxy transport");
+}
+export function normalizeProxyTransportRetryOptions(retry, options = {}) {
+    const label = options.label ?? "Proxy transport";
+    const extraErrorCodes = options.extraErrorCodes ?? [];
+    if (retry === undefined || retry === false) {
+        return undefined;
+    }
+    if (retry === true) {
+        return createRetryOptions(HttpRetryPreset.TransportTransient, extraErrorCodes, label);
+    }
+    if (typeof retry === "string") {
+        if (!hasOwnValue(HttpRetryPreset, retry)) {
+            throw createInvalidRetryPolicyError(`Unknown ${label} retry preset: ${retry}`, label);
+        }
+        return createRetryOptions(retry, extraErrorCodes, label);
+    }
+    if (typeof retry !== "object" || retry === null) {
+        throw createInvalidRetryPolicyError(`${label} retry policy must be an object`, label);
+    }
+    if (Array.isArray(retry)) {
+        throw createInvalidRetryPolicyError(`${label} retry policy must be a plain object`, label);
+    }
+    validateRetryOptionsShape(retry, label);
+    const base = createRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient, extraErrorCodes, label);
+    const maxDelayMs = clampDelay(retry.maxDelayMs, base.maxDelayMs);
+    return {
+        preset: retry.preset ?? base.preset,
+        attempts: clampPositiveInteger(retry.attempts, base.attempts, MAX_PROXY_TRANSPORT_RETRY_ATTEMPTS),
+        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
+        statusCodes: retry.statusCodes?.filter((status) => Number.isInteger(status)) ?? base.statusCodes,
+        errorCodes: retry.errorCodes ?? base.errorCodes,
+        delayStrategy: retry.delayStrategy ?? base.delayStrategy,
+        baseDelayMs: clampDelay(retry.baseDelayMs, base.baseDelayMs),
+        maxDelayMs,
+        jitter: retry.jitter ?? base.jitter,
+        retryAfter: retry.retryAfter ?? base.retryAfter,
+        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
+    };
+}
+function validateRetryOptionsShape(retry, label) {
+    if (retry.preset !== undefined && !hasOwnValue(HttpRetryPreset, retry.preset)) {
+        throw createInvalidRetryPolicyError(`Unknown ${label} retry preset: ${String(retry.preset)}`, label);
+    }
+    if (retry.delayStrategy !== undefined &&
+        !hasOwnValue(HttpRetryDelayStrategy, retry.delayStrategy)) {
+        throw createInvalidRetryPolicyError(`Unknown ${label} retry delay strategy: ${String(retry.delayStrategy)}`, label);
+    }
+    if (retry.jitter !== undefined && !hasOwnValue(HttpRetryJitter, retry.jitter)) {
+        throw createInvalidRetryPolicyError(`Unknown ${label} retry jitter policy: ${String(retry.jitter)}`, label);
+    }
+    if (retry.retryAfter !== undefined && !hasOwnValue(HttpRetryAfterPolicy, retry.retryAfter)) {
+        throw createInvalidRetryPolicyError(`Unknown ${label} retry-after policy: ${String(retry.retryAfter)}`, label);
+    }
+    if (retry.unsafeMethodPolicy !== undefined &&
+        !hasOwnValue(HttpRetryUnsafeMethodPolicy, retry.unsafeMethodPolicy)) {
+        throw createInvalidRetryPolicyError(`Unknown ${label} retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`, label);
+    }
+    if (retry.methods !== undefined) {
+        if (!Array.isArray(retry.methods)) {
+            throw createInvalidRetryPolicyError(`${label} retry methods must be an array`, label);
+        }
+        const nonStringMethods = retry.methods.filter((method) => typeof method !== "string");
+        if (nonStringMethods.length > 0) {
+            throw createInvalidRetryPolicyError(`${label} retry methods must contain only strings`, label);
+        }
+        const unknownMethods = retry.methods
+            .map((method) => method.toUpperCase())
+            .filter((method) => !KNOWN_RETRY_METHODS.has(method));
+        if (unknownMethods.length > 0) {
+            throw createInvalidRetryPolicyError(`Unknown ${label} retry method(s): ${unknownMethods.join(", ")}`, label);
+        }
+    }
+    if (retry.statusCodes !== undefined) {
+        if (!Array.isArray(retry.statusCodes)) {
+            throw createInvalidRetryPolicyError(`${label} retry statusCodes must be an array`, label);
+        }
+        const invalidStatusCodes = retry.statusCodes.filter((status) => !Number.isInteger(status) || Number(status) < 100 || Number(status) > 599);
+        if (invalidStatusCodes.length > 0) {
+            throw createInvalidRetryPolicyError(`${label} retry statusCodes must contain HTTP status integers in [100, 599]`, label);
+        }
+    }
+    if (retry.errorCodes !== undefined) {
+        if (!Array.isArray(retry.errorCodes)) {
+            throw createInvalidRetryPolicyError(`${label} retry errorCodes must be an array`, label);
+        }
+        const nonStringErrorCodes = retry.errorCodes.filter((errorCode) => typeof errorCode !== "string");
+        if (nonStringErrorCodes.length > 0) {
+            throw createInvalidRetryPolicyError(`${label} retry errorCodes must contain only strings`, label);
+        }
+    }
+    if (retry.preset === HttpRetryPreset.Off &&
+        ((retry.attempts !== undefined && retry.attempts > 1) ||
+            (retry.statusCodes !== undefined && retry.statusCodes.length > 0))) {
+        throw createInvalidRetryPolicyError(`${label} retry preset off cannot be combined with retry-enabling overrides`, label);
+    }
+}
+export function validateUnsafeProxyTransportRetryMethods(options, label = "Proxy transport") {
+    if (options.unsafeMethodPolicy === HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
+        return;
+    }
+    const unsafeMethods = options.methods.filter((method) => UNSAFE_RETRY_METHODS.has(method.toUpperCase()));
+    if (unsafeMethods.length === 0)
+        return;
+    throw new ProviderError(`${label} retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
+}
+export function isProxyTransportRetryMethod(method, options) {
+    return options.methods
+        .map((allowedMethod) => allowedMethod.toUpperCase())
+        .includes(method.toUpperCase());
+}
+export function shouldRetryProxyTransportError(error, options) {
+    const code = retryErrorCode(error);
+    return Boolean(code && options.errorCodes.includes(code));
+}
+export function shouldRetryProxyTransportAttempt(input) {
+    const { error, explicitRetry, method, options, proxyUsed } = input;
+    if (!options || options.attempts <= 1)
+        return false;
+    if (!explicitRetry && !proxyUsed)
+        return false;
+    return (isProxyTransportRetryMethod(method, options) && shouldRetryProxyTransportError(error, options));
+}
+function retryAfterHeader(headers) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (name.toLowerCase() === "retry-after")
+            return value;
+    }
+    return undefined;
+}
+function parseRetryAfterMs(headers, now = Date.now()) {
+    const value = retryAfterHeader(headers);
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds)) {
+        return Math.max(0, Math.floor(seconds * 1_000));
+    }
+    const dateMs = Date.parse(value);
+    if (!Number.isNaN(dateMs)) {
+        return Math.max(0, dateMs - now);
+    }
+    return undefined;
+}
+export function computeProxyTransportRetryDelayMs(options, attemptIndex, headers) {
+    const multiplier = options.delayStrategy === HttpRetryDelayStrategy.Exponential
+        ? 2 ** Math.max(0, attemptIndex - 1)
+        : 1;
+    const configuredDelay = Math.min(options.baseDelayMs * multiplier, options.maxDelayMs);
+    const retryAfterMs = options.retryAfter === HttpRetryAfterPolicy.Ignore
+        ? undefined
+        : headers
+            ? parseRetryAfterMs(headers)
+            : undefined;
+    if (retryAfterMs !== undefined) {
+        const boundedRetryAfterMs = Math.min(retryAfterMs, options.maxDelayMs);
+        if (options.retryAfter === HttpRetryAfterPolicy.Cap) {
+            return Math.min(boundedRetryAfterMs, configuredDelay);
+        }
+        return boundedRetryAfterMs;
+    }
+    switch (options.jitter) {
+        case HttpRetryJitter.None:
+            return configuredDelay;
+        case HttpRetryJitter.Equal:
+            return Math.floor(configuredDelay / 2 + Math.random() * (configuredDelay / 2));
+        case HttpRetryJitter.Full:
+            return Math.floor(Math.random() * configuredDelay);
+    }
+}
+export function normalizeProxyAttemptIndex(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.floor(value));
+}
+export function computeProxyAttemptIndex(options) {
+    return (normalizeProxyAttemptIndex(options.baseProxyAttempt) +
+        normalizeProxyAttemptIndex(options.proxyAttemptOffset) +
+        normalizeProxyAttemptIndex(options.retryAttemptOffset));
+}

package/dist/runtime/proxy-telemetry.d.ts

@@ -1,8 +1,9 @@
-import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink } from "../config/loader";
+import type { ProxyAttemptTelemetryEvent, ProxyResolutionTelemetryEvent, ProxyTelemetrySink, ProxyVendorFailoverTelemetryEvent } from "../config/loader.js";
 export declare const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 export declare class ProxyTelemetryCollector implements ProxyTelemetrySink {
     #private;
     recordProxyResolution(event: ProxyResolutionTelemetryEvent): void;
+    recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void;
     recordProxyAttempt(event: ProxyAttemptTelemetryEvent): void;
     toHeaderValue(): string | undefined;
 }

package/dist/runtime/proxy-telemetry.js

@@ -1,6 +1,7 @@
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 const CACHE_STATUS_SEVERITY = {
     disabled: 0,
     memory_hit: 1,
@@ -20,9 +21,7 @@ function maxOptional(left, right) {
     return values.length > 0 ? Math.max(...values) : undefined;
 }
 function worseStatus(left, right) {
-    return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left]
-        ? right
-        : left;
+    return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
 function encodeBase64Url(value) {
     return Buffer.from(value, "utf8").toString("base64url");
@@ -30,15 +29,15 @@ function encodeBase64Url(value) {
 export class ProxyTelemetryCollector {
     #events = [];
     #attempts = [];
+    #failovers = [];
     recordProxyResolution(event) {
         this.#events.push({
-            provider: "smartproxy",
+            provider: event.provider,
+            ...(event.protocol ? { protocol: event.protocol } : {}),
             cacheStatus: event.cacheStatus,
             cacheHit: event.cacheHit,
             resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
-            allocatorMs: event.allocatorMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.allocatorMs)),
+            allocatorMs: event.allocatorMs === undefined ? undefined : Math.max(0, Math.floor(event.allocatorMs)),
             allocatorStatus: event.allocatorStatus === undefined
                 ? undefined
                 : Math.max(0, Math.floor(event.allocatorStatus)),
@@ -46,32 +45,33 @@ export class ProxyTelemetryCollector {
             allocatorAttempts: event.allocatorAttempts === undefined
                 ? undefined
                 : Math.max(1, Math.floor(event.allocatorAttempts)),
-            lockWaitMs: event.lockWaitMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.lockWaitMs)),
-            redisReadMs: event.redisReadMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.redisReadMs)),
-            redisWriteMs: event.redisWriteMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.redisWriteMs)),
-            poolAgeMs: event.poolAgeMs === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.poolAgeMs)),
+            lockWaitMs: event.lockWaitMs === undefined ? undefined : Math.max(0, Math.floor(event.lockWaitMs)),
+            redisReadMs: event.redisReadMs === undefined ? undefined : Math.max(0, Math.floor(event.redisReadMs)),
+            redisWriteMs: event.redisWriteMs === undefined ? undefined : Math.max(0, Math.floor(event.redisWriteMs)),
+            poolAgeMs: event.poolAgeMs === undefined ? undefined : Math.max(0, Math.floor(event.poolAgeMs)),
             poolExpiresInMs: event.poolExpiresInMs === undefined
                 ? undefined
                 : Math.max(0, Math.floor(event.poolExpiresInMs)),
             attempts: Math.max(1, Math.floor(event.attempts || 1)),
-            refreshes: event.refreshes === undefined
-                ? undefined
-                : Math.max(0, Math.floor(event.refreshes)),
+            refreshes: event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
+        });
+    }
+    recordProxyVendorFailover(event) {
+        if (this.#failovers.length >= MAX_PROXY_FAILOVER_SAMPLES)
+            return;
+        this.#failovers.push({
+            vendor: event.vendor,
+            ...(event.nextVendor ? { nextVendor: event.nextVendor } : {}),
+            phase: event.phase,
+            reason: event.reason,
+            ...(event.attempt === undefined ? {} : { attempt: Math.max(0, Math.floor(event.attempt)) }),
         });
     }
     recordProxyAttempt(event) {
         if (this.#attempts.length >= MAX_PROXY_ATTEMPT_SAMPLES)
             return;
         this.#attempts.push({
-            provider: "smartproxy",
+            provider: event.provider,
             attempt: Math.max(1, Math.floor(event.attempt || 1)),
             ...(event.poolIndex === undefined
                 ? {}
@@ -79,9 +79,7 @@ export class ProxyTelemetryCollector {
             ...(event.proxyHash ? { proxyHash: event.proxyHash.slice(0, 16) } : {}),
             outcome: event.outcome === "ok" ? "ok" : "error",
             ...(event.errorCode ? { errorCode: event.errorCode.slice(0, 80) } : {}),
-            ...(event.status === undefined
-                ? {}
-                : { status: Math.max(0, Math.floor(event.status)) }),
+            ...(event.status === undefined ? {} : { status: Math.max(0, Math.floor(event.status)) }),
             ...(event.durationMs === undefined
                 ? {}
                 : { durationMs: Math.max(0, Math.floor(event.durationMs)) }),
@@ -91,8 +89,16 @@ export class ProxyTelemetryCollector {
         const [first, ...rest] = this.#events;
         if (!first)
             return undefined;
+        // The serving vendor/protocol is the last recorded resolution (a failed
+        // vendor records first, the vendor that served records last).
+        const serving = this.#events[this.#events.length - 1] ?? first;
+        const vendors = [];
+        for (const event of this.#events) {
+            if (!vendors.includes(event.provider))
+                vendors.push(event.provider);
+        }
         const aggregate = rest.reduce((acc, event) => ({
-            provider: "smartproxy",
+            provider: event.provider,
             cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
             cacheHit: acc.cacheHit && event.cacheHit,
             resolutionMs: acc.resolutionMs + event.resolutionMs,
@@ -111,13 +117,12 @@ export class ProxyTelemetryCollector {
         const payload = {
             v: 1,
             proxy: {
-                provider: "smartproxy",
+                provider: serving.provider,
+                ...(serving.protocol ? { protocol: serving.protocol } : {}),
                 cacheStatus: aggregate.cacheStatus,
                 cacheHit: aggregate.cacheHit,
                 resolutionMs: aggregate.resolutionMs,
-                ...(aggregate.allocatorMs !== undefined
-                    ? { allocatorMs: aggregate.allocatorMs }
-                    : {}),
+                ...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
                 ...(aggregate.allocatorStatus !== undefined
                     ? { allocatorStatus: aggregate.allocatorStatus }
                     : {}),
@@ -127,40 +132,38 @@ export class ProxyTelemetryCollector {
                 ...(aggregate.allocatorAttempts !== undefined
                     ? { allocatorAttempts: aggregate.allocatorAttempts }
                     : {}),
-                ...(aggregate.lockWaitMs !== undefined
-                    ? { lockWaitMs: aggregate.lockWaitMs }
-                    : {}),
-                ...(aggregate.redisReadMs !== undefined
-                    ? { redisReadMs: aggregate.redisReadMs }
-                    : {}),
-                ...(aggregate.redisWriteMs !== undefined
-                    ? { redisWriteMs: aggregate.redisWriteMs }
-                    : {}),
-                ...(aggregate.poolAgeMs !== undefined
-                    ? { poolAgeMs: aggregate.poolAgeMs }
-                    : {}),
+                ...(aggregate.lockWaitMs !== undefined ? { lockWaitMs: aggregate.lockWaitMs } : {}),
+                ...(aggregate.redisReadMs !== undefined ? { redisReadMs: aggregate.redisReadMs } : {}),
+                ...(aggregate.redisWriteMs !== undefined ? { redisWriteMs: aggregate.redisWriteMs } : {}),
+                ...(aggregate.poolAgeMs !== undefined ? { poolAgeMs: aggregate.poolAgeMs } : {}),
                 ...(aggregate.poolExpiresInMs !== undefined
                     ? { poolExpiresInMs: aggregate.poolExpiresInMs }
                     : {}),
                 attempts: aggregate.attempts,
-                ...(aggregate.refreshes !== undefined
-                    ? { refreshes: aggregate.refreshes }
-                    : {}),
+                ...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
                 ...(this.#attempts.length > 0
                     ? {
                         attemptSamples: this.#attempts.map((attempt, index) => ({
                             n: index + 1,
                             a: attempt.attempt,
-                            ...(attempt.poolIndex === undefined
-                                ? {}
-                                : { i: attempt.poolIndex }),
+                            ...(attempt.poolIndex === undefined ? {} : { i: attempt.poolIndex }),
                             ...(attempt.proxyHash ? { h: attempt.proxyHash } : {}),
                             o: attempt.outcome,
                             ...(attempt.errorCode ? { c: attempt.errorCode } : {}),
                             ...(attempt.status === undefined ? {} : { s: attempt.status }),
-                            ...(attempt.durationMs === undefined
-                                ? {}
-                                : { d: attempt.durationMs }),
+                            ...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
+                        })),
+                    }
+                    : {}),
+                ...(vendors.length > 1 ? { vendors } : {}),
+                ...(this.#failovers.length > 0
+                    ? {
+                        failovers: this.#failovers.map((failover) => ({
+                            v: failover.vendor,
+                            ...(failover.nextVendor ? { nx: failover.nextVendor } : {}),
+                            p: failover.phase,
+                            r: failover.reason,
+                            ...(failover.attempt === undefined ? {} : { a: failover.attempt }),
                         })),
                     }
                     : {}),

package/dist/runtime/redis.d.ts

@@ -1,4 +1,4 @@
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 export type ProviderRedisClient = Redis;
 export type ProviderRedisClientOptions = {
     readonly redisUrl: string;

package/dist/runtime/redis.js

@@ -1,4 +1,4 @@
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 export function createProviderRedisClient(options) {
     const redis = new Redis(options.redisUrl, {
         connectTimeout: options.timeoutMs,
@@ -23,9 +23,7 @@ export async function withRedisTimeout(operation, options) {
                 }
             }, options.timeoutMs);
         });
-        const operationResult = options.onError
-            ? operation().catch(options.onError)
-            : operation();
+        const operationResult = options.onError ? operation().catch(options.onError) : operation();
         return await Promise.race([operationResult, timeout]);
     }
     finally {

package/dist/runtime/request-options.d.ts

@@ -1,3 +1,3 @@
-import type { RequestParams } from "../types";
+import type { RequestParams } from "../types.js";
 export declare function appendQueryParams(url: string, params?: RequestParams): string;
 export declare function normalizeHttpRequestBody(body: unknown): string | Buffer | undefined;

package/dist/runtime/secrets.d.ts

@@ -0,0 +1,27 @@
+import type { EnvContext, ProviderDefinition } from "../types.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 declare 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 declare function listMissingRequiredSecrets(provider: ProviderDefinition, env: EnvContext): string[];
+/**
+ * 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 declare function assertRequiredSecretsPresent(provider: ProviderDefinition, env: EnvContext): void;

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;