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

package/src/runtime/proxy-telemetry.ts

@@ -1,17 +1,21 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyVendorFailoverTelemetryEvent,
+	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
-} from "../config/loader";
+} from "../config/loader.js";
 
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 
 type ProviderTelemetryHeader = {
 	v: 1;
 	proxy?: {
-		provider: "smartproxy";
+		provider: ProxyVendorName;
+		protocol?: ProxyProtocol;
 		cacheStatus: ProxyCacheStatus;
 		cacheHit: boolean;
 		resolutionMs: number;
@@ -27,6 +31,10 @@ type ProviderTelemetryHeader = {
 		attempts: number;
 		refreshes?: number;
 		attemptSamples?: CompactProxyAttemptSample[];
+		/** Distinct vendors attempted across the resolution chain, in order seen. */
+		vendors?: ProxyVendorName[];
+		/** Cross-vendor failover events (bounded). */
+		failovers?: CompactVendorFailoverSample[];
 	};
 };
 
@@ -41,8 +49,17 @@ type CompactProxyAttemptSample = {
 	d?: number;
 };
 
+type CompactVendorFailoverSample = {
+	v: ProxyVendorName;
+	nx?: ProxyVendorName;
+	p: "resolution" | "transport";
+	r: ProxyVendorFailoverTelemetryEvent["reason"];
+	a?: number;
+};
+
 const MAX_HEADER_BYTES = 4_096;
 const MAX_PROXY_ATTEMPT_SAMPLES = 24;
+const MAX_PROXY_FAILOVER_SAMPLES = 12;
 
 const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
 	disabled: 0,
@@ -55,31 +72,18 @@ const CACHE_STATUS_SEVERITY: Record<ProxyCacheStatus, number> = {
 	allocator: 7,
 };
 
-function sumOptional(
-	left: number | undefined,
-	right: number | undefined,
-): number | undefined {
+function sumOptional(left: number | undefined, right: number | undefined): number | undefined {
 	const total = (left ?? 0) + (right ?? 0);
 	return total > 0 ? total : undefined;
 }
 
-function maxOptional(
-	left: number | undefined,
-	right: number | undefined,
-): number | undefined {
-	const values = [left, right].filter(
-		(value): value is number => typeof value === "number",
-	);
+function maxOptional(left: number | undefined, right: number | undefined): number | undefined {
+	const values = [left, right].filter((value): value is number => typeof value === "number");
 	return values.length > 0 ? Math.max(...values) : undefined;
 }
 
-function worseStatus(
-	left: ProxyCacheStatus,
-	right: ProxyCacheStatus,
-): ProxyCacheStatus {
-	return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left]
-		? right
-		: left;
+function worseStatus(left: ProxyCacheStatus, right: ProxyCacheStatus): ProxyCacheStatus {
+	return CACHE_STATUS_SEVERITY[right] > CACHE_STATUS_SEVERITY[left] ? right : left;
 }
 
 function encodeBase64Url(value: string): string {
@@ -89,17 +93,17 @@ function encodeBase64Url(value: string): string {
 export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	#events: ProxyResolutionTelemetryEvent[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
+	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
 		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)),
+				event.allocatorMs === undefined ? undefined : Math.max(0, Math.floor(event.allocatorMs)),
 			allocatorStatus:
 				event.allocatorStatus === undefined
 					? undefined
@@ -110,37 +114,38 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 					? undefined
 					: Math.max(1, Math.floor(event.allocatorAttempts)),
 			lockWaitMs:
-				event.lockWaitMs === undefined
-					? undefined
-					: Math.max(0, Math.floor(event.lockWaitMs)),
+				event.lockWaitMs === undefined ? undefined : Math.max(0, Math.floor(event.lockWaitMs)),
 			redisReadMs:
-				event.redisReadMs === undefined
-					? undefined
-					: Math.max(0, Math.floor(event.redisReadMs)),
+				event.redisReadMs === undefined ? undefined : Math.max(0, Math.floor(event.redisReadMs)),
 			redisWriteMs:
-				event.redisWriteMs === undefined
-					? undefined
-					: Math.max(0, Math.floor(event.redisWriteMs)),
+				event.redisWriteMs === undefined ? undefined : Math.max(0, Math.floor(event.redisWriteMs)),
 			poolAgeMs:
-				event.poolAgeMs === undefined
-					? undefined
-					: Math.max(0, Math.floor(event.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)),
+				event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
+		});
+	}
+
+	recordProxyVendorFailover(event: ProxyVendorFailoverTelemetryEvent): void {
+		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: ProxyAttemptTelemetryEvent): void {
 		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
 				? {}
@@ -148,9 +153,7 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			...(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)) }),
@@ -161,27 +164,29 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		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: ProxyVendorName[] = [];
+		for (const event of this.#events) {
+			if (!vendors.includes(event.provider)) vendors.push(event.provider);
+		}
+
 		const aggregate = rest.reduce<ProxyResolutionTelemetryEvent>(
 			(acc, event) => ({
-				provider: "smartproxy",
+				provider: event.provider,
 				cacheStatus: worseStatus(acc.cacheStatus, event.cacheStatus),
 				cacheHit: acc.cacheHit && event.cacheHit,
 				resolutionMs: acc.resolutionMs + event.resolutionMs,
 				allocatorMs: sumOptional(acc.allocatorMs, event.allocatorMs),
 				allocatorStatus: event.allocatorStatus ?? acc.allocatorStatus,
 				allocatorBodyClass: event.allocatorBodyClass ?? acc.allocatorBodyClass,
-				allocatorAttempts: sumOptional(
-					acc.allocatorAttempts,
-					event.allocatorAttempts,
-				),
+				allocatorAttempts: sumOptional(acc.allocatorAttempts, event.allocatorAttempts),
 				lockWaitMs: sumOptional(acc.lockWaitMs, event.lockWaitMs),
 				redisReadMs: sumOptional(acc.redisReadMs, event.redisReadMs),
 				redisWriteMs: sumOptional(acc.redisWriteMs, event.redisWriteMs),
 				poolAgeMs: maxOptional(acc.poolAgeMs, event.poolAgeMs),
-				poolExpiresInMs: maxOptional(
-					acc.poolExpiresInMs,
-					event.poolExpiresInMs,
-				),
+				poolExpiresInMs: maxOptional(acc.poolExpiresInMs, event.poolExpiresInMs),
 				attempts: acc.attempts + event.attempts,
 				refreshes: sumOptional(acc.refreshes, event.refreshes),
 			}),
@@ -190,13 +195,12 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		const payload: ProviderTelemetryHeader = {
 			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 }
 					: {}),
@@ -206,40 +210,38 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 				...(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/src/runtime/redis.ts

@@ -1,4 +1,4 @@
-import Redis from "ioredis";
+import { Redis } from "ioredis";
 
 export type ProviderRedisClient = Redis;
 
@@ -43,9 +43,7 @@ export async function withRedisTimeout<T>(
 				}
 			}, 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 {
 		if (timeoutId) clearTimeout(timeoutId);
@@ -56,10 +54,7 @@ export function redisStatus(redis: ProviderRedisClient): string {
 	return redis.status;
 }
 
-async function waitForRedisReady(
-	redis: ProviderRedisClient,
-	timeoutMs: number,
-): Promise<boolean> {
+async function waitForRedisReady(redis: ProviderRedisClient, timeoutMs: number): Promise<boolean> {
 	let timeoutId: ReturnType<typeof setTimeout> | undefined;
 	let settled = false;
 
@@ -80,10 +75,7 @@ async function waitForRedisReady(
 		const onReady = () => finish(true);
 		const onUnavailable = () => finish(false);
 
-		timeoutId = setTimeout(
-			() => finish(redisStatus(redis) === "ready"),
-			timeoutMs,
-		);
+		timeoutId = setTimeout(() => finish(redisStatus(redis) === "ready"), timeoutMs);
 		redis.once("ready", onReady);
 		redis.once("close", onUnavailable);
 		redis.once("end", onUnavailable);

package/src/runtime/request-options.ts

@@ -1,12 +1,6 @@
-import type {
-	RequestParamPrimitive,
-	RequestParams,
-	RequestParamValue,
-} from "../types";
+import type { RequestParamPrimitive, RequestParams, RequestParamValue } from "../types.js";
 
-function isParamArray(
-	value: RequestParamValue,
-): value is readonly RequestParamPrimitive[] {
+function isParamArray(value: RequestParamValue): value is readonly RequestParamPrimitive[] {
 	return Array.isArray(value);
 }
 
@@ -29,8 +23,7 @@ export function appendQueryParams(url: string, params?: RequestParams): string {
 	const parsed = new URL(url);
 	for (const [key, value] of Object.entries(params)) {
 		if (isParamArray(value)) {
-			for (const item of value)
-				appendQueryValue(parsed.searchParams, key, item);
+			for (const item of value) appendQueryValue(parsed.searchParams, key, item);
 			continue;
 		}
 		appendQueryValue(parsed.searchParams, key, value);
@@ -39,9 +32,7 @@ export function appendQueryParams(url: string, params?: RequestParams): string {
 	return parsed.toString();
 }
 
-export function normalizeHttpRequestBody(
-	body: unknown,
-): string | Buffer | undefined {
+export function normalizeHttpRequestBody(body: unknown): string | Buffer | undefined {
 	if (body === undefined) {
 		return undefined;
 	}

package/src/runtime/secrets.ts

@@ -0,0 +1,64 @@
+import { ProviderSecretError } from "../errors.js";
+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 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: ProviderDefinition,
+	env: EnvContext,
+): string[] {
+	const missing: string[] = [];
+	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: ProviderDefinition,
+	env: EnvContext,
+): void {
+	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: [...] }).`,
+		},
+	);
+}