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

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/redirects.ts

@@ -0,0 +1,66 @@
+import type { HttpRedirectFailureReason } from "../types.js";
+
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+export type RedirectHopDecision<TMethod extends string> =
+	| {
+			kind: "follow";
+			nextMethod: TMethod | "GET";
+			nextUrl: string;
+	  }
+	| {
+			kind: "stop";
+			reason: HttpRedirectFailureReason;
+			nextUrl?: string;
+	  };
+
+export function isRedirectStatus(status: number): boolean {
+	return REDIRECT_STATUSES.has(status);
+}
+
+/** Shared fetch-compatible redirect method rewriting for stealth and ctx.http. */
+export function nextRedirectMethod<TMethod extends string>(
+	status: number,
+	method: TMethod,
+): TMethod | "GET" {
+	if (status === 303 && method !== "HEAD") return "GET";
+	if ((status === 301 || status === 302) && method === "POST") return "GET";
+	return method;
+}
+
+/** Resolves a Location value against the response URL without issuing a request. */
+export function resolveRedirectUrl(
+	location: string | undefined,
+	responseUrl: string,
+): string | undefined {
+	return location ? new URL(location, responseUrl).toString() : undefined;
+}
+
+/**
+ * Shared post-response decision ordering for both redirect walkers. The
+ * caller-owned stop hook is checked first, matching stealth's pre-follow
+ * contract, then structural termination and loop checks run before follow.
+ */
+export function evaluateRedirectHop<TMethod extends string>(input: {
+	status: number;
+	method: TMethod;
+	nextUrl: string | undefined;
+	shouldStop: boolean;
+	redirectCount: number;
+	maxHops: number;
+	visitedRequests: ReadonlySet<string>;
+}): RedirectHopDecision<TMethod> {
+	if (input.shouldStop) {
+		return { kind: "stop", reason: "stopped", ...(input.nextUrl ? { nextUrl: input.nextUrl } : {}) };
+	}
+	if (!input.nextUrl) return { kind: "stop", reason: "missing_location" };
+	if (input.redirectCount > input.maxHops) {
+		return { kind: "stop", reason: "max_hops", nextUrl: input.nextUrl };
+	}
+
+	const nextMethod = nextRedirectMethod(input.status, input.method);
+	if (input.visitedRequests.has(`${nextMethod} ${input.nextUrl}`)) {
+		return { kind: "stop", reason: "loop", nextUrl: input.nextUrl };
+	}
+	return { kind: "follow", nextMethod, nextUrl: input.nextUrl };
+}

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);