@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.9

package/src/runtime/proxy-telemetry.ts

@@ -1,8 +1,11 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyVendorFailoverTelemetryEvent,
+	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
 
@@ -11,7 +14,8 @@ 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,
@@ -76,10 +93,12 @@ 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)),
@@ -112,10 +131,21 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		});
 	}
 
+	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
 				? {}
@@ -134,9 +164,17 @@ 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,
@@ -157,7 +195,8 @@ 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,
@@ -194,6 +233,18 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 							})),
 						}
 					: {}),
+				...(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/state.ts

@@ -115,7 +115,17 @@ function envelopeFromJson(
 	// biome-ignore lint/suspicious/noExplicitAny: state envelopes deserialize caller-owned generic values.
 ): StateValue<any> | null {
 	if (!raw) return null;
-	const parsed: unknown = 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: unknown;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return null;
+	}
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 		return null;
 	}

package/src/runtime/stealth.ts

@@ -2,13 +2,16 @@ import { createHash } from "node:crypto";
 import type { Browser, ImpitOptions, ImpitResponse, RequestInit } from "impit";
 import { Impit } from "impit";
 
-import type { ProxyResolutionOptions } from "../config/loader.js";
+import type { ProxyResolutionOptions, ProxyVendorName } from "../config/loader.js";
 import {
 	DEFAULT_SMARTPROXY_POOL_SIZE,
 	invalidateProxyResolutionCacheAsync,
+	policyResolvesRegistryVendorChain,
 	ProxyResolutionError,
+	resolvePolicyProxyPoolSpan,
+	resolvePolicyTransportAttemptCap,
 	resolveProxyConfigAsync,
-	SMARTPROXY_MAX_POOL_SIZE,
+	vendorFromResolvedSource,
 } from "../config/loader.js";
 import { SDKError, TransportError } from "../errors.js";
 import { getStealthProfile } from "../stealth/profiles.js";
@@ -51,7 +54,6 @@ const DEFAULT_PROFILE = "chrome-146";
 const MISSING_PROXY_WARNING =
 	"[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.";
 
-const MAX_POLICY_PROXY_RETRY_ATTEMPTS = SMARTPROXY_MAX_POOL_SIZE;
 const MAX_POLICY_PROXY_POOL_REFRESHES = 1;
 const PROXY_CONNECT_FAILURE_CODE = "proxy_connect_failed";
 const PROXY_CONNECT_FAILURE_BODY_PATTERN =
@@ -426,6 +428,7 @@ type ResolvedAttemptProxy = {
 	url?: string;
 	poolIndex?: number;
 	proxyHash?: string;
+	vendor?: ProxyVendorName;
 };
 
 function proxyPoolIndexFromDiagnostics(
@@ -615,6 +618,7 @@ function createSessionFetcher(
 	async function resolveRequestProxy(
 		options?: StealthFetchOptions,
 		proxyAttempt?: number,
+		refreshEpoch?: number,
 	): Promise<ResolvedAttemptProxy> {
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
@@ -626,6 +630,10 @@ function createSessionFetcher(
 				proxyAttemptOffset: options?.proxyAttemptOffset,
 				retryAttemptOffset: proxyAttempt,
 			}),
+			// The impit stealth transport tunnels both HTTP CONNECT and SOCKS5,
+			// preserving the client TLS fingerprint end-to-end.
+			transportProtocols: ["http", "socks5"],
+			...(refreshEpoch === undefined ? {} : { proxyRefreshEpoch: refreshEpoch }),
 			telemetry: clientOptions.telemetry,
 		});
 
@@ -638,6 +646,7 @@ function createSessionFetcher(
 			url: resolvedProxy.url,
 			poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
 			proxyHash: proxyEndpointHash(resolvedProxy.url),
+			vendor: vendorFromResolvedSource(resolvedProxy.source),
 		};
 	}
 
@@ -662,18 +671,33 @@ function createSessionFetcher(
 			const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
 			const usesPolicyAllocator = hasPolicyProxy && !options.proxy && !clientOptions.proxy;
 			const retryAttemptCap = Math.max(1, stealthRetryOptions?.attempts ?? 1);
+			// Span the whole vendor chain: successive attempts rotate one vendor's
+			// pool, then fail over to the next vendor via the flat attempt index.
+			const policyProxy =
+				clientOptions.proxyPolicy ??
+				(typeof clientOptions.upstream?.proxy === "object"
+					? clientOptions.upstream.proxy
+					: undefined);
+			// The pool span is already bounded by each vendor's max pool size
+			// (smartproxy ≤20, nodemaven ≤50), so the configured span never exceeds
+			// the chain's true maximum — a large NodeMaven pool stays fully
+			// reachable rather than being truncated at an arbitrary ceiling.
 			const policyProxyAttemptCap = Math.max(
 				1,
-				Math.min(
-					MAX_POLICY_PROXY_RETRY_ATTEMPTS,
-					clientOptions.proxyPolicy?.session?.poolSize ??
-						(typeof clientOptions.upstream?.proxy === "object"
-							? clientOptions.upstream.proxy.session?.poolSize
-							: undefined) ??
-						DEFAULT_SMARTPROXY_POOL_SIZE,
-				),
+				policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE,
 			);
-			const maxAttempts = usesPolicyAllocator ? policyProxyAttemptCap : retryAttemptCap;
+			// A registry vendor chain (smartproxy/nodemaven) is the only policy whose
+			// successive attempts resolve a *different* endpoint, so it is the only one
+			// that may widen the attempt cap to the pool span, de-duplicate endpoints,
+			// and drive allocator stale-pool refresh. A static custom/decodo policy
+			// resolves the same URL every attempt: widening/refreshing it would resend
+			// the request dozens of times (up to maxAttempts × refreshes) and bypass
+			// retry:false and unsafe-method controls. Static policies therefore follow
+			// the ordinary transport-retry budget instead.
+			const rotatesRegistryChain =
+				usesPolicyAllocator && policyResolvesRegistryVendorChain(policyProxy);
+			const maxAttempts = rotatesRegistryChain ? policyProxyAttemptCap : retryAttemptCap;
+			const dedupeAllocatorEndpoints = rotatesRegistryChain;
 			let lastError: unknown;
 
 			for (
@@ -698,7 +722,7 @@ function createSessionFetcher(
 						if (attemptRecorded || !proxy) return;
 						attemptRecorded = true;
 						clientOptions.telemetry?.recordProxyAttempt?.({
-							provider: "smartproxy",
+							provider: attemptProxy?.vendor ?? "smartproxy",
 							attempt: attempt + 1,
 							...(attemptProxy?.poolIndex === undefined
 								? {}
@@ -712,11 +736,16 @@ function createSessionFetcher(
 					};
 					try {
 						assertNoUnsupportedFingerprintOverrides(options);
-						attemptProxy = await resolveRequestProxy(options, attempt);
+						attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
 						proxy = attemptProxy.url;
-						if (proxy && usesPolicyAllocator) {
+						if (proxy && dedupeAllocatorEndpoints) {
+							// An under-filled allocation repeats endpoints (via the modulo
+							// pool mapping) before the flat offset crosses into the next
+							// vendor. Skip an already-tried endpoint and advance the offset
+							// rather than breaking — breaking here would strand the request on
+							// the primary vendor and never reach the fallback leg.
 							if (attemptedProxies.has(proxy)) {
-								break;
+								continue;
 							}
 							attemptedProxies.add(proxy);
 						}
@@ -796,7 +825,7 @@ function createSessionFetcher(
 							proxyAttemptStatus(normalizedError),
 						);
 						lastError = normalizedError;
-						if (proxy && usesPolicyAllocator && isProxyPoolRefreshableError(normalizedError)) {
+						if (proxy && rotatesRegistryChain && isProxyPoolRefreshableError(normalizedError)) {
 							stalePoolError = normalizedError;
 							if (shouldRunProxyAuthDiagnostic(normalizedError)) {
 								stalePoolDiagnosticProxy = proxy;
@@ -806,11 +835,28 @@ function createSessionFetcher(
 							}
 							break;
 						}
+						// Cap the number of transport retries. For a policy-allocator chain,
+						// every attempt resolves a *different* endpoint/vendor (poolIndex
+						// rotates across the concatenated vendor pool spans), so a transport
+						// failure is a signal to advance to the next endpoint — potentially
+						// crossing into the fallback vendor — not to retry the same endpoint.
+						// Truncating that rotation at the per-endpoint retry budget would
+						// strand the request on the primary vendor and never reach the
+						// fallback, since the crossover only happens once the flat attempt
+						// index exceeds the primary vendor's pool size (~10-20).
+						// resolvePolicyTransportAttemptCap widens to the full chain span only
+						// for implicit, safe-method allocator requests; explicit retry
+						// policies (their documented `attempts` ceiling), unsafe methods, and
+						// static/non-registry vendors keep the per-endpoint retry budget.
+						const transportRetryCap = resolvePolicyTransportAttemptCap({
+							policy: policyProxy,
+							usesPolicyAllocator,
+							retryAttempts: stealthRetryOptions?.attempts ?? 1,
+							explicitRetry: hasExplicitRetryPolicy,
+							method,
+						});
 						if (
-							attempt + 1 <
-								(stealthRetryOptions
-									? Math.min(maxAttempts, stealthRetryOptions.attempts)
-									: maxAttempts) &&
+							attempt + 1 < transportRetryCap &&
 							shouldRetryProxyTransportAttempt({
 								error: normalizedError,
 								explicitRetry: hasExplicitRetryPolicy,
@@ -829,7 +875,7 @@ function createSessionFetcher(
 				}
 
 				if (
-					usesPolicyAllocator &&
+					rotatesRegistryChain &&
 					stalePoolError &&
 					refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES
 				) {

package/src/server/serve.ts

@@ -512,11 +512,22 @@ function toErrorResponse(error: unknown, requestId?: string): OperationErrorResp
 		};
 	}
 
+	// A masked internal error MUST NOT be advertised as retryable: without an
+	// explicit retryable:false the hub (bori provider-backed engine) defaults 5xx
+	// to retryable:true, which turns a deterministic pre-upstream crash into an
+	// infinite START->CONTINUE->restart loop (2026-07-22 catchtable reserve RCA).
+	// We still refuse to leak message/stack — only the error class name (or the
+	// primitive type for non-Error throwables) is surfaced for ops triage.
 	return {
 		error: {
 			code: "internal_error",
 			message: "Internal error",
 			...(requestId ? { requestId } : {}),
+			details: {
+				retryable: false,
+				category: "internal_error",
+				errorClass: error instanceof Error ? error.name : typeof error,
+			},
 		},
 	};
 }

package/src/types.ts

@@ -769,7 +769,25 @@ export type ProviderAccessVisibility = "public" | "early_access";
 
 export type ProviderProxyMode = "disabled" | "optional" | "required";
 
-export type ProviderProxyProvider = "smartproxy" | "decodo" | "custom";
+/**
+ * Proxy egress vendors. These are FOUR DISTINCT services — do not conflate them
+ * (a common mistake because the names collide with a well-known rebrand):
+ *
+ * - `smartproxy` — **api.smartproxy.org**, a residential proxy with an IP
+ *   *extraction/allocation* API (app_key → a pool of raw `ip:port` CONNECT
+ *   endpoints). This is our own vendor. It is NOT the company formerly named
+ *   "Smartproxy". Credentials: `APIFUSE__PROXY__SMARTPROXY_APP_KEY`.
+ * - `nodemaven` — **gate.nodemaven.com**, a *gateway* proxy with static
+ *   credentials; geo/session encoded in the username, no allocation API.
+ * - `decodo` — **decodo.com**, the *gateway* proxy that was named "Smartproxy"
+ *   (smartproxy.com) before its 2025 rebrand to Decodo. Sticky sessions via
+ *   username params. A different company from `smartproxy` above.
+ *   **@deprecated** — unused; no managed adapter. Use `smartproxy`/`nodemaven`,
+ *   or the `APIFUSE__PROXY__URL` bring-your-own escape hatch.
+ * - `custom` — **@deprecated** bring-your-own static proxy URL marker. The
+ *   `APIFUSE__PROXY__URL` env still works without declaring this value.
+ */
+export type ProviderProxyProvider = "smartproxy" | "nodemaven" | "decodo" | "custom";
 
 export type ProviderProxySessionAffinity =
 	| "request"
@@ -783,7 +801,18 @@ export interface ProviderProxyPolicy {
 	 * certificate verification, and vendor allocator endpoints are SDK-owned.
 	 */
 	mode: ProviderProxyMode;
+	/**
+	 * @deprecated Use `providers: [...]` to declare an ordered vendor fallback
+	 * chain. A single-element `providers` list is equivalent to this field.
+	 */
 	provider?: ProviderProxyProvider;
+	/**
+	 * Ordered proxy-vendor fallback chain. The SDK tries each vendor in order and
+	 * fails over to the next when a vendor lacks credentials or its allocation /
+	 * transport is exhausted. When omitted, `provider` (or the platform default)
+	 * is used as a single-vendor chain.
+	 */
+	providers?: ProviderProxyProvider[];
 	geo?: {
 		/** ISO 3166-1 alpha-2 country code, for example KR or US. */
 		country?: Iso3166Alpha2CountryCode;