@apifuse/provider-sdk 2.2.0-beta.3 → 2.2.0-beta.30

package/src/runtime/proxy-errors.ts

@@ -1,4 +1,4 @@
-import { TransportError } from "../errors";
+import { TransportError } from "../errors.js";
 
 export const PROXY_AUTH_IP_DENIED_CODE = "PROXY_AUTH_IP_DENIED";
 export const PROXY_AUTH_IP_DENIED_MESSAGE =
@@ -19,10 +19,18 @@ const PROXY_AUTH_IP_DENIED_PATTERN =
 	/\b(?:source|egress|client)\s+ip\b.{0,120}\b(?:deny|denied|unauthori[sz]ed|not\s+authori[sz]ed|white\s*list|allow\s*list)\b|\b(?:white\s*list|allow\s*list)\b.{0,120}\b(?:source|egress|client)\s+ip\b/i;
 const PROXY_EDGE_AUTH_REJECTED_PATTERN =
 	/\bauth\s+ip\s+err\b|\bproxy\b.{0,120}\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b|\bauth(?:entication)?\b.{0,120}\b(?:reject(?:ed)?|fail(?:ed)?|invalid|den(?:y|ied)|unauthori[sz]ed)\b.{0,120}\bproxy\b/i;
-const PROXY_POOL_STALE_MESSAGE_PATTERN =
-	/\bproxy\b.{0,120}\b(?:pool|lease|expired|unavailable|exhausted|non[\s-]?200\s+code:\s*(?:509|512))\b|\bnon[\s-]?200\s+code:\s*(?:509|512)\b.{0,120}\bproxy\b|\bsmartproxy\b.{0,120}\b(?:509|512)\b/i;
-const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN =
-	/\b(?:smartproxy|proxy)\b.{0,160}\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b|\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\s-]?200)\b.{0,160}\b(?:smartproxy|proxy)\b/i;
+// Vendor host tokens that can appear in upstream error strings. Adding a proxy
+// vendor updates every classifier below in one place. `proxy` is the generic
+// fallback so vendor-agnostic messages still classify.
+const PROXY_VENDOR_ALTERNATION = "smartproxy|nodemaven|proxy";
+const PROXY_POOL_STALE_MESSAGE_PATTERN = new RegExp(
+	`\\bproxy\\b.{0,120}\\b(?:pool|lease|expired|unavailable|exhausted|non[\\s-]?200\\s+code:\\s*(?:509|512))\\b|\\bnon[\\s-]?200\\s+code:\\s*(?:509|512)\\b.{0,120}\\bproxy\\b|\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,120}\\b(?:509|512)\\b`,
+	"i",
+);
+const PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN = new RegExp(
+	`\\b(?:${PROXY_VENDOR_ALTERNATION})\\b.{0,160}\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b|\\b(?:495|ssl|tls|cert(?:ificate)?|handshake|edge|connect|non[\\s-]?200)\\b.{0,160}\\b(?:${PROXY_VENDOR_ALTERNATION})\\b`,
+	"i",
+);
 
 export function isProxyAuthIpDeniedMessage(message: string): boolean {
 	return PROXY_AUTH_IP_DENIED_PATTERN.test(message);
@@ -39,9 +47,7 @@ export function isProxyEdgeAuthRejectedMessage(message: string): boolean {
 	return PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message);
 }
 
-export function createProxyEdgeAuthRejectedError(
-	cause?: Error,
-): TransportError {
+export function createProxyEdgeAuthRejectedError(cause?: Error): TransportError {
 	return new TransportError(PROXY_EDGE_AUTH_REJECTED_MESSAGE, {
 		code: PROXY_EDGE_AUTH_REJECTED_CODE,
 		cause,
@@ -52,10 +58,7 @@ export function isProxyPoolStaleStatus(status: number): boolean {
 	return PROXY_POOL_STALE_STATUS_CODES.has(status);
 }
 
-export function isProxyEdgeTlsRejectedResponse(
-	status: number,
-	evidence: string,
-): boolean {
+export function isProxyEdgeTlsRejectedResponse(status: number, evidence: string): boolean {
 	return (
 		PROXY_EDGE_TLS_REJECTED_STATUS_CODES.has(status) &&
 		PROXY_EDGE_TLS_REJECTED_MESSAGE_PATTERN.test(evidence)
@@ -67,10 +70,7 @@ export function isProxyPoolStaleMessage(message: string): boolean {
 }
 
 export function isProxyPoolRefreshableError(error: unknown): boolean {
-	if (
-		error instanceof TransportError &&
-		error.code === PROXY_AUTH_IP_DENIED_CODE
-	) {
+	if (error instanceof TransportError && error.code === PROXY_AUTH_IP_DENIED_CODE) {
 		return false;
 	}
 
@@ -89,39 +89,26 @@ export function isProxyPoolRefreshableError(error: unknown): boolean {
 		cause instanceof Error ? cause.message : "",
 	].join(" ");
 	return (
-		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) ||
-		PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
+		PROXY_POOL_STALE_MESSAGE_PATTERN.test(message) || PROXY_EDGE_AUTH_REJECTED_PATTERN.test(message)
 	);
 }
 
 export const isProxyPoolStaleError = isProxyPoolRefreshableError;
 
-export function createProxyPoolStaleError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy provider pool failed with status ${status}`,
-		{
-			code: PROXY_POOL_STALE_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyPoolStaleError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy provider pool failed with status ${status}`, {
+		code: PROXY_POOL_STALE_CODE,
+		status,
+		cause,
+	});
 }
 
-export function createProxyEdgeTlsRejectedError(
-	status: number,
-	cause?: Error,
-): TransportError {
-	return new TransportError(
-		`Proxy edge TLS request was rejected with status ${status}`,
-		{
-			code: PROXY_EDGE_TLS_REJECTED_CODE,
-			status,
-			cause,
-		},
-	);
+export function createProxyEdgeTlsRejectedError(status: number, cause?: Error): TransportError {
+	return new TransportError(`Proxy edge TLS request was rejected with status ${status}`, {
+		code: PROXY_EDGE_TLS_REJECTED_CODE,
+		status,
+		cause,
+	});
 }
 
 export function createProxyPoolExhaustedError(cause?: Error): TransportError {

package/src/runtime/proxy-nodemaven.ts

@@ -0,0 +1,221 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { ProviderProxyPolicy } from "../types.js";
+
+export const NODEMAVEN_USERNAME_ENV = "APIFUSE__PROXY__NODEMAVEN_USERNAME";
+export const NODEMAVEN_PASSWORD_ENV = "APIFUSE__PROXY__NODEMAVEN_PASSWORD";
+export const NODEMAVEN_FILTER_ENV = "APIFUSE__PROXY__NODEMAVEN_FILTER";
+
+export const NODEMAVEN_GATEWAY_HOST = "gate.nodemaven.com";
+
+export type NodemavenCredentials = {
+	readonly username: string;
+	readonly password: string;
+	readonly filter?: string;
+};
+
+/** Both schemes tunnel bytes end-to-end, preserving the client TLS handshake. */
+export type ProxyProtocol = "http" | "socks5";
+
+/**
+ * NodeMaven's fastest protocol: HTTP CONNECT. Benchmarks (KR, cold + warm)
+ * showed socks5 through the gateway adds ~500ms per request over http, so
+ * NodeMaven never defaults to socks5.
+ */
+export const NODEMAVEN_DEFAULT_PROTOCOL: ProxyProtocol = "http";
+
+/** NodeMaven gateway port ranges per protocol (docs: HTTP 8080-9080, SOCKS5 1080-2080). */
+const NODEMAVEN_PORTS: Record<ProxyProtocol, { min: number; max: number }> = {
+	http: { min: 8080, max: 9080 },
+	socks5: { min: 1080, max: 2080 },
+};
+
+const NODEMAVEN_FILTERS = new Set(["medium", "high"]);
+const DEFAULT_NODEMAVEN_FILTER = "medium";
+const DEFAULT_NODEMAVEN_POOL_SIZE = 20;
+export const NODEMAVEN_MAX_POOL_SIZE = 50;
+/** NodeMaven sticky sessions persist up to 24h server-side, keyed by the sid. */
+const NODEMAVEN_MAX_LIFETIME_MINUTES = 1440;
+const SID_LENGTH = 10;
+
+export function hasNodemavenCredentials(): boolean {
+	return Boolean(readNodemavenUsername() && readNodemavenPassword());
+}
+
+function readNodemavenUsername(): string | undefined {
+	return process.env[NODEMAVEN_USERNAME_ENV]?.trim() || undefined;
+}
+
+function readNodemavenPassword(): string | undefined {
+	return process.env[NODEMAVEN_PASSWORD_ENV]?.trim() || undefined;
+}
+
+function resolveNodemavenFilter(value: string | undefined): string {
+	const raw = value?.trim().toLowerCase();
+	if (!raw) return DEFAULT_NODEMAVEN_FILTER;
+	if (!NODEMAVEN_FILTERS.has(raw)) {
+		throw new Error(`${NODEMAVEN_FILTER_ENV} must be "medium" or "high"`);
+	}
+	return raw;
+}
+
+export function nodemavenPoolSize(policy: ProviderProxyPolicy): number {
+	return Math.min(
+		NODEMAVEN_MAX_POOL_SIZE,
+		Math.max(1, Math.floor(policy.session?.poolSize ?? DEFAULT_NODEMAVEN_POOL_SIZE)),
+	);
+}
+
+export function nodemavenLifetimeMinutes(policy: ProviderProxyPolicy): number {
+	const configured = policy.session?.lifetimeMinutes;
+	if (typeof configured !== "number" || !Number.isFinite(configured) || configured <= 0) {
+		return NODEMAVEN_MAX_LIFETIME_MINUTES;
+	}
+	return Math.min(NODEMAVEN_MAX_LIFETIME_MINUTES, Math.max(1, Math.floor(configured)));
+}
+
+export type NodemavenSessionWindow = {
+	refreshEpoch: number;
+	expiresAt: string;
+};
+
+/** Stable wall-clock window shared by every process deriving the same sticky sid. */
+export function nodemavenSessionWindow(
+	policy: ProviderProxyPolicy,
+	now = Date.now(),
+): NodemavenSessionWindow {
+	const lifetimeMs = nodemavenLifetimeMinutes(policy) * 60_000;
+	const refreshEpoch = Math.floor(now / lifetimeMs);
+	return {
+		refreshEpoch,
+		expiresAt: new Date((refreshEpoch + 1) * lifetimeMs).toISOString(),
+	};
+}
+
+/** NodeMaven username tokens accept `[a-z0-9]`; slugify geo values to that set. */
+function slugifyGeo(value: string | undefined): string | undefined {
+	if (!value) return undefined;
+	const slug = value
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "");
+	return slug || undefined;
+}
+
+function isStickyAffinity(policy: ProviderProxyPolicy): boolean {
+	return (policy.session?.affinity ?? "request") !== "request";
+}
+
+/**
+ * A sticky sid is deterministic from the affinity key so every process serving
+ * the same connection derives the same egress IP without shared storage. A
+ * rotating sid is random per call (a fresh egress IP per request).
+ */
+function deriveSid(
+	policy: ProviderProxyPolicy,
+	affinityKey: string | undefined,
+	poolIndex: number,
+	refreshEpoch: number,
+): string {
+	if (!isStickyAffinity(policy) || !affinityKey) {
+		return randomBytes(SID_LENGTH).toString("hex").slice(0, SID_LENGTH);
+	}
+	const digest = createHash("sha256")
+		.update(`${affinityKey}:${refreshEpoch}:${poolIndex}`)
+		.digest("hex");
+	// hex digits are a subset of the allowed [a-z0-9] sid charset.
+	return digest.slice(0, SID_LENGTH);
+}
+
+function selectPort(protocol: ProxyProtocol, sid: string, poolIndex: number): number {
+	const { min, max } = NODEMAVEN_PORTS[protocol];
+	const span = max - min + 1;
+	const hashInt = Number.parseInt(
+		createHash("sha256").update(`${sid}:${poolIndex}`).digest("hex").slice(0, 8),
+		16,
+	);
+	return min + (hashInt % span);
+}
+
+export type NodemavenSynthesisInput = {
+	policy: ProviderProxyPolicy;
+	/** Explicit credentials; synthesis never reads process-global state. */
+	credentials: NodemavenCredentials;
+	affinityKey: string | undefined;
+	protocol: ProxyProtocol;
+	poolIndex: number;
+	refreshEpoch: number;
+	/** ISO 3166-1 alpha-2, already resolved by the caller (falls back to env). */
+	country?: string;
+	/** Clock injection used by native sticky-expiry lifecycle tests. */
+	now?: number;
+	/** Stable caller-owned hard expiry when the refresh epoch is wall-clock-derived. */
+	expiresAt?: string;
+};
+
+export type NodemavenSynthesis = {
+	url: string;
+	protocol: ProxyProtocol;
+	sticky: boolean;
+	sessionId: string;
+	expiresAt?: string;
+	diagnostics: Record<string, string | number | boolean>;
+};
+
+/**
+ * Synthesize a NodeMaven gateway proxy URL locally from static credentials.
+ * There is no allocation API — geo/session are encoded in the username.
+ */
+export function synthesizeNodemavenProxy(input: NodemavenSynthesisInput): NodemavenSynthesis {
+	const username = input.credentials.username.trim();
+	const password = input.credentials.password.trim();
+	if (!username || !password) {
+		throw new Error(
+			`NodeMaven credentials missing: set ${NODEMAVEN_USERNAME_ENV} and ${NODEMAVEN_PASSWORD_ENV}.`,
+		);
+	}
+
+	const filter = resolveNodemavenFilter(input.credentials.filter);
+	const sid = deriveSid(input.policy, input.affinityKey, input.poolIndex, input.refreshEpoch);
+	const port = selectPort(input.protocol, sid, input.poolIndex);
+	const lifetimeMinutes = nodemavenLifetimeMinutes(input.policy);
+	const sticky = isStickyAffinity(input.policy);
+
+	const country = slugifyGeo(input.country ?? input.policy.geo?.country);
+	const region = slugifyGeo(input.policy.geo?.subdivision);
+	const city = slugifyGeo(input.policy.geo?.city);
+
+	const tokens = [username];
+	if (country) tokens.push("country", country);
+	if (region) tokens.push("region", region);
+	if (city) tokens.push("city", city);
+	tokens.push("sid", sid);
+	tokens.push("filter", filter);
+	tokens.push("ipv4", "true");
+	const proxyUsername = tokens.join("-");
+
+	// Username tokens are [a-z0-9-] only, which survive URL encoding unchanged.
+	const url = `${input.protocol}://${proxyUsername}:${encodeURIComponent(password)}@${NODEMAVEN_GATEWAY_HOST}:${port}`;
+
+	return {
+		url,
+		protocol: input.protocol,
+		sticky,
+		sessionId: sid,
+		...(sticky
+			? {
+					expiresAt:
+						input.expiresAt ??
+						new Date((input.now ?? Date.now()) + lifetimeMinutes * 60_000).toISOString(),
+				}
+			: {}),
+		diagnostics: {
+			vendor: "nodemaven",
+			protocol: input.protocol,
+			sticky,
+			filter,
+			lifetimeMinutes,
+			...(country ? { country } : {}),
+		},
+	};
+}

package/src/runtime/proxy-retry-policy.ts

@@ -1,12 +1,12 @@
-import { ProviderError, TransportError } from "../errors";
-import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types";
+import { ProviderError, TransportError } from "../errors.js";
+import type { HttpMethod, HttpRetryOptions, RequestOptions } from "../types.js";
 import {
 	HttpRetryAfterPolicy,
 	HttpRetryDelayStrategy,
 	HttpRetryJitter,
 	HttpRetryPreset,
 	HttpRetryUnsafeMethodPolicy,
-} from "../types";
+} from "../types.js";
 
 export type NormalizedProxyTransportRetryOptions = Required<
 	Pick<

package/src/runtime/proxy-telemetry.ts

@@ -1,17 +1,23 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyUserAgentSource,
+	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;
+		userAgentSource?: ProxyUserAgentSource;
+		protocol?: ProxyProtocol;
 		cacheStatus: ProxyCacheStatus;
 		cacheHit: boolean;
 		resolutionMs: number;
@@ -27,6 +33,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 +51,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 +74,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 +95,18 @@ 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.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
+			...(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 +117,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 +156,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 +167,30 @@ 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,
+				userAgentSource: event.userAgentSource ?? acc.userAgentSource,
 				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 +199,13 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		const payload: ProviderTelemetryHeader = {
 			v: 1,
 			proxy: {
-				provider: "smartproxy",
+				provider: serving.provider,
+				...(aggregate.userAgentSource ? { userAgentSource: aggregate.userAgentSource } : {}),
+				...(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 +215,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 }),
 							})),
 						}
 					: {}),