@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

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-telemetry.ts

@@ -1,48 +1,107 @@
 import type {
 	ProxyAttemptTelemetryEvent,
 	ProxyCacheStatus,
+	ProxyProtocol,
 	ProxyResolutionTelemetryEvent,
 	ProxyTelemetrySink,
+	ProxyUserAgentSource,
+	ProxyVendorFailoverTelemetryEvent,
+	ProxyVendorName,
 	SmartproxyAllocatorBodyClass,
 } from "../config/loader.js";
 
 export const PROVIDER_TELEMETRY_HEADER = "X-ApiFuse-Provider-Telemetry";
 
-type ProviderTelemetryHeader = {
-	v: 1;
-	proxy?: {
-		provider: "smartproxy";
-		cacheStatus: ProxyCacheStatus;
-		cacheHit: boolean;
-		resolutionMs: number;
-		allocatorMs?: number;
-		allocatorStatus?: number;
-		allocatorBodyClass?: SmartproxyAllocatorBodyClass;
-		allocatorAttempts?: number;
-		lockWaitMs?: number;
-		redisReadMs?: number;
-		redisWriteMs?: number;
-		poolAgeMs?: number;
-		poolExpiresInMs?: number;
-		attempts: number;
-		refreshes?: number;
-		attemptSamples?: CompactProxyAttemptSample[];
-	};
+export type ProxyTelemetryResolvedPayload = {
+	kind: "resolved";
+	provider: ProxyVendorName;
+	userAgentSource?: ProxyUserAgentSource;
+	protocol?: ProxyProtocol;
+	cacheStatus: ProxyCacheStatus;
+	cacheHit: boolean;
+	resolutionMs: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts: number;
+	refreshes?: number;
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: string;
+		o: ProxyAttemptTelemetryEvent["outcome"];
+		c?: string;
+		s?: number;
+		d?: number;
+	}[];
+	/** Distinct vendors attempted across the resolution chain, in order seen. */
+	vendors?: ProxyVendorName[];
+	/** Cross-vendor failover events (bounded). */
+	failovers?: {
+		v: ProxyVendorName;
+		nx?: ProxyVendorName;
+		p: ProxyVendorFailoverTelemetryEvent["phase"];
+		r: ProxyVendorFailoverTelemetryEvent["reason"];
+		a?: number;
+	}[];
+};
+
+export type ProxyTelemetryUnresolvedPayload = {
+	kind: "unresolved";
+	/** Distinct vendors that failed resolution or recorded a failover, in order seen. */
+	vendors: ProxyVendorName[];
+	cacheStatus?: ProxyCacheStatus;
+	cacheHit?: boolean;
+	resolutionMs?: number;
+	allocatorMs?: number;
+	allocatorStatus?: number;
+	allocatorBodyClass?: SmartproxyAllocatorBodyClass;
+	allocatorAttempts?: number;
+	lockWaitMs?: number;
+	redisReadMs?: number;
+	redisWriteMs?: number;
+	poolAgeMs?: number;
+	poolExpiresInMs?: number;
+	attempts?: number;
+	refreshes?: number;
+	failovers?: {
+		v: ProxyVendorName;
+		nx?: ProxyVendorName;
+		p: ProxyVendorFailoverTelemetryEvent["phase"];
+		r: ProxyVendorFailoverTelemetryEvent["reason"];
+		a?: number;
+	}[];
+	attemptSamples?: {
+		n: number;
+		a: number;
+		i?: number;
+		h?: string;
+		o: ProxyAttemptTelemetryEvent["outcome"];
+		c?: string;
+		s?: number;
+		d?: number;
+	}[];
 };
 
-type CompactProxyAttemptSample = {
-	n: number;
-	a: number;
-	i?: number;
-	h?: string;
-	o: "ok" | "error";
-	c?: string;
-	s?: number;
-	d?: number;
+export type ProxyTelemetryLogPayload =
+	| ProxyTelemetryResolvedPayload
+	| ProxyTelemetryUnresolvedPayload;
+
+type ProviderTelemetryHeader = {
+	v: 1;
+	proxy?: ProxyTelemetryLogPayload;
 };
 
 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 +135,16 @@ function encodeBase64Url(value: string): string {
 export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 	#events: ProxyResolutionTelemetryEvent[] = [];
 	#attempts: ProxyAttemptTelemetryEvent[] = [];
+	#failovers: ProxyVendorFailoverTelemetryEvent[] = [];
+	#unresolvedVendors: ProxyVendorName[] = [];
 
 	recordProxyResolution(event: ProxyResolutionTelemetryEvent): void {
+		const outcome = event.outcome === "error" ? "error" : "ok";
 		this.#events.push({
-			provider: "smartproxy",
+			provider: event.provider,
+			outcome,
+			...(event.userAgentSource ? { userAgentSource: event.userAgentSource } : {}),
+			...(event.protocol ? { protocol: event.protocol } : {}),
 			cacheStatus: event.cacheStatus,
 			cacheHit: event.cacheHit,
 			resolutionMs: Math.max(0, Math.floor(event.resolutionMs)),
@@ -110,12 +175,29 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			refreshes:
 				event.refreshes === undefined ? undefined : Math.max(0, Math.floor(event.refreshes)),
 		});
+		if (outcome === "error" && !this.#unresolvedVendors.includes(event.provider)) {
+			this.#unresolvedVendors.push(event.provider);
+		}
+	}
+
+	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)) }),
+		});
+		if (!this.#unresolvedVendors.includes(event.vendor)) {
+			this.#unresolvedVendors.push(event.vendor);
+		}
 	}
 
 	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
 				? {}
@@ -130,13 +212,105 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 		});
 	}
 
-	toHeaderValue(): string | undefined {
+	toLogPayload(): ProxyTelemetryLogPayload | undefined {
 		const [first, ...rest] = this.#events;
-		if (!first) return undefined;
+		const okEvents = this.#events.filter((event) => event.outcome !== "error");
+		const attemptSamples = this.#attempts.map((attempt, index) => ({
+			n: index + 1,
+			a: attempt.attempt,
+			...(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 }),
+		}));
+		const 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 }),
+		}));
+
+		if (okEvents.length === 0) {
+			if (!first && failovers.length === 0) return undefined;
+			const failureEvents = this.#events.filter((event) => event.outcome === "error");
+			const [firstFailure, ...remainingFailures] = failureEvents;
+			const aggregate = firstFailure
+				? remainingFailures.reduce<ProxyResolutionTelemetryEvent>(
+						(acc, event) => ({
+							provider: event.provider,
+							outcome: "error",
+							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),
+							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),
+							attempts: acc.attempts + event.attempts,
+							refreshes: sumOptional(acc.refreshes, event.refreshes),
+						}),
+						firstFailure,
+					)
+				: undefined;
+			return {
+				kind: "unresolved",
+				vendors: [...this.#unresolvedVendors],
+				...(aggregate
+					? {
+							cacheStatus: aggregate.cacheStatus,
+							cacheHit: aggregate.cacheHit,
+							resolutionMs: aggregate.resolutionMs,
+							...(aggregate.allocatorMs !== undefined
+								? { allocatorMs: aggregate.allocatorMs }
+								: {}),
+							...(aggregate.allocatorStatus !== undefined
+								? { allocatorStatus: aggregate.allocatorStatus }
+								: {}),
+							...(aggregate.allocatorBodyClass !== undefined
+								? { allocatorBodyClass: aggregate.allocatorBodyClass }
+								: {}),
+							...(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.poolExpiresInMs !== undefined
+								? { poolExpiresInMs: aggregate.poolExpiresInMs }
+								: {}),
+							attempts: aggregate.attempts,
+							...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+						}
+					: {}),
+				...(failovers.length > 0 ? { failovers } : {}),
+				...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+			};
+		}
+
+		// The serving vendor/protocol is the last successful resolution.
+		const serving = okEvents[okEvents.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,
@@ -154,48 +328,43 @@ export class ProxyTelemetryCollector implements ProxyTelemetrySink {
 			}),
 			first,
 		);
-		const payload: ProviderTelemetryHeader = {
-			v: 1,
-			proxy: {
-				provider: "smartproxy",
-				cacheStatus: aggregate.cacheStatus,
-				cacheHit: aggregate.cacheHit,
-				resolutionMs: aggregate.resolutionMs,
-				...(aggregate.allocatorMs !== undefined ? { allocatorMs: aggregate.allocatorMs } : {}),
-				...(aggregate.allocatorStatus !== undefined
-					? { allocatorStatus: aggregate.allocatorStatus }
-					: {}),
-				...(aggregate.allocatorBodyClass !== undefined
-					? { allocatorBodyClass: aggregate.allocatorBodyClass }
-					: {}),
-				...(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.poolExpiresInMs !== undefined
-					? { poolExpiresInMs: aggregate.poolExpiresInMs }
-					: {}),
-				attempts: aggregate.attempts,
-				...(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.proxyHash ? { h: attempt.proxyHash } : {}),
-								o: attempt.outcome,
-								...(attempt.errorCode ? { c: attempt.errorCode } : {}),
-								...(attempt.status === undefined ? {} : { s: attempt.status }),
-								...(attempt.durationMs === undefined ? {} : { d: attempt.durationMs }),
-							})),
-						}
-					: {}),
-			},
+		return {
+			kind: "resolved",
+			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.allocatorStatus !== undefined
+				? { allocatorStatus: aggregate.allocatorStatus }
+				: {}),
+			...(aggregate.allocatorBodyClass !== undefined
+				? { allocatorBodyClass: aggregate.allocatorBodyClass }
+				: {}),
+			...(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.poolExpiresInMs !== undefined
+				? { poolExpiresInMs: aggregate.poolExpiresInMs }
+				: {}),
+			attempts: aggregate.attempts,
+			...(aggregate.refreshes !== undefined ? { refreshes: aggregate.refreshes } : {}),
+			...(attemptSamples.length > 0 ? { attemptSamples } : {}),
+			...(vendors.length > 1 ? { vendors } : {}),
+			...(failovers.length > 0 ? { failovers } : {}),
 		};
+	}
+
+	toHeaderValue(): string | undefined {
+		const proxy = this.toLogPayload();
+		if (!proxy) return undefined;
+		const payload: ProviderTelemetryHeader = { v: 1, proxy };
 
 		const encoded = encodeBase64Url(JSON.stringify(payload));
 		if (encoded.length > MAX_HEADER_BYTES) return undefined;

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,8 @@
-import { Redis } from "ioredis";
+import { createRequire } from "node:module";
+
+import type { Redis } from "ioredis";
+
+const require = createRequire(import.meta.url);
 
 export type ProviderRedisClient = Redis;
 
@@ -17,7 +21,8 @@ type RedisTimeoutOptions<T> = {
 export function createProviderRedisClient(
 	options: ProviderRedisClientOptions,
 ): ProviderRedisClient {
-	const redis = new Redis(options.redisUrl, {
+	const { Redis: RedisClient } = require("ioredis") as typeof import("ioredis");
+	const redis = new RedisClient(options.redisUrl, {
 		connectTimeout: options.timeoutMs,
 		enableOfflineQueue: false,
 		lazyConnect: true,