@apifuse/provider-sdk 2.1.0-beta.9 → 2.2.0-beta.10

package/src/runtime/stealth.ts

@@ -2,26 +2,28 @@ import { createHash } from "node:crypto";
 import type { Browser, ImpitOptions, ImpitResponse, RequestInit } from "impit";
 import { Impit } from "impit";
 
-import type { ProxyResolutionOptions } from "../config/loader";
+import type { ProxyResolutionOptions, ProxyVendorName } from "../config/loader.js";
 import {
 	DEFAULT_SMARTPROXY_POOL_SIZE,
 	invalidateProxyResolutionCacheAsync,
+	policyResolvesRegistryVendorChain,
 	ProxyResolutionError,
+	resolvePolicyProxyPoolSpan,
+	resolvePolicyTransportAttemptCap,
 	resolveProxyConfigAsync,
-	SMARTPROXY_MAX_POOL_SIZE,
-} from "../config/loader";
-import { ProviderError, SDKError, TransportError } from "../errors";
-import { getStealthProfile } from "../stealth/profiles";
+	vendorFromResolvedSource,
+} from "../config/loader.js";
+import { SDKError, TransportError } from "../errors.js";
+import { getStealthProfile } from "../stealth/profiles.js";
 import type {
 	CookieJar,
 	HttpMethod,
-	HttpRetryOptions,
 	StealthClient,
 	StealthFetchOptions,
+	StealthRedirectHop,
 	StealthResponse,
 	StealthSession,
-} from "../types";
-import { HttpRetryPreset, HttpRetryUnsafeMethodPolicy } from "../types";
+} from "../types.js";
 import {
 	createProxyAuthIpDeniedError,
 	createProxyEdgeAuthRejectedError,
@@ -34,49 +36,31 @@ import {
 	isProxyPoolRefreshableError,
 	isProxyPoolStaleMessage,
 	isProxyPoolStaleStatus,
-	PROXY_AUTH_IP_DENIED_CODE,
 	PROXY_EDGE_AUTH_REJECTED_CODE,
 	PROXY_POOL_STALE_CODE,
-} from "./proxy-errors";
-import { appendQueryParams } from "./request-options";
+} from "./proxy-errors.js";
+import {
+	computeProxyAttemptIndex,
+	computeProxyTransportRetryDelayMs,
+	createDefaultProxyTransportRetryOptions,
+	normalizeProxyTransportRetryOptions,
+	shouldRetryProxyTransportAttempt,
+	validateUnsafeProxyTransportRetryMethods,
+} from "./proxy-retry-policy.js";
+import { appendQueryParams } from "./request-options.js";
 
 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 =
 	/\bproxy\b.*\b(non[\s-]?200|connect|tunnel)|\bconnect\b.*\bproxy\b|\btunnel\b/i;
 const PROXY_AUTH_DIAGNOSTIC_URL = "http://example.com/";
 const PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS = 5_000;
-const DEFAULT_STEALTH_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"] as const;
-const DEFAULT_STEALTH_RETRY_ERROR_CODES = [
-	PROXY_CONNECT_FAILURE_CODE,
-	"transport_network_error",
-	"transport_timeout",
-] as const;
-const RATE_LIMIT_STEALTH_RETRY_ERROR_CODES = ["transport_timeout"] as const;
-const KNOWN_STEALTH_RETRY_METHODS = new Set([
-	"GET",
-	"HEAD",
-	"POST",
-	"PUT",
-	"DELETE",
-	"OPTIONS",
-	"TRACE",
-	"PATCH",
-]);
-const UNSAFE_STEALTH_RETRY_METHODS = new Set([
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE",
-	"TRACE",
-]);
-const MAX_STEALTH_RETRY_ATTEMPTS = 8;
+const STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES = [PROXY_CONNECT_FAILURE_CODE] as const;
 
 export type StealthClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
@@ -128,15 +112,15 @@ const FIREFOX_IMPIT_BY_MAJOR: Record<number, ImpitBrowser> = {
 
 type StealthTransportResponse = Pick<
 	ImpitResponse,
-	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text" | "url"
->;
+	"arrayBuffer" | "headers" | "json" | "ok" | "status" | "text"
+> & {
+	url?: string;
+	redirected?: boolean;
+};
 
 type StealthMethod = NonNullable<ImpitRequestInit["method"]>;
-type NormalizedStealthRetryOptions = {
-	attempts: number;
-	methods: readonly string[];
-	errorCodes: readonly string[];
-	unsafeMethodPolicy: HttpRetryOptions["unsafeMethodPolicy"];
+type StealthRequestInit = ImpitRequestInit & {
+	redirect?: NonNullable<StealthFetchOptions["redirect"]>;
 };
 
 function isRecord(value: unknown): value is Record<PropertyKey, unknown> {
@@ -177,12 +161,37 @@ class CookieJarImpl implements CookieJar {
 		return { ...this.cookies };
 	}
 
+	has(name: string): boolean {
+		return Object.hasOwn(this.cookies, name);
+	}
+
 	toString(): string {
 		return Object.entries(this.cookies)
 			.map(([name, value]) => `${name}=${value}`)
 			.join("; ");
 	}
 
+	toHeader(): string {
+		return this.toString();
+	}
+
+	snapshot(): Record<string, string> {
+		return this.getAll();
+	}
+
+	restore(cookies: Record<string, string>): void {
+		this.clear();
+		for (const [name, value] of Object.entries(cookies)) {
+			if (name) this.cookies[name] = value;
+		}
+	}
+
+	clear(): void {
+		for (const name of Object.keys(this.cookies)) {
+			delete this.cookies[name];
+		}
+	}
+
 	find(predicate: (cookie: string) => boolean): string | undefined {
 		for (const [name, value] of Object.entries(this.cookies)) {
 			const cookie = `${name}=${value}`;
@@ -271,9 +280,7 @@ function normalizeHeaders(
 function hasOwn(object: object, key: string): boolean {
 	return Object.hasOwn(object, key);
 }
-function toImpitCookieJar(
-	cookieJar: CookieJarImpl,
-): NonNullable<ImpitOptions["cookieJar"]> {
+function toImpitCookieJar(cookieJar: CookieJarImpl): NonNullable<ImpitOptions["cookieJar"]> {
 	return {
 		setCookie(cookie: string, _url: string, cb?: (error?: unknown) => void) {
 			cookieJar.setFromCookieStrings([cookie]);
@@ -290,10 +297,8 @@ function assertNoUnsupportedFingerprintOverrides(options: unknown): void {
 	const unsupported: string[] = [];
 	if (hasOwn(options, "headerOrder")) unsupported.push("headerOrder");
 	const stealth = options.stealth;
-	if (isRecord(stealth) && hasOwn(stealth, "ja3"))
-		unsupported.push("stealth.ja3");
-	if (isRecord(stealth) && hasOwn(stealth, "h2"))
-		unsupported.push("stealth.h2");
+	if (isRecord(stealth) && hasOwn(stealth, "ja3")) unsupported.push("stealth.ja3");
+	if (isRecord(stealth) && hasOwn(stealth, "h2")) unsupported.push("stealth.h2");
 	if (unsupported.length === 0) return;
 
 	throw new SDKError(
@@ -301,9 +306,7 @@ function assertNoUnsupportedFingerprintOverrides(options: unknown): void {
 	);
 }
 
-function responseHeadersToRecord(
-	headers: Headers,
-): Record<string, string | string[] | undefined> {
+function responseHeadersToRecord(headers: Headers): Record<string, string | string[] | undefined> {
 	const record: Record<string, string> = {};
 	for (const [name, value] of headers.entries()) record[name] = value;
 	return record;
@@ -335,17 +338,22 @@ function splitCombinedSetCookieHeader(headerValue: string): string[] {
 
 export async function normalizeResponse(
 	response: StealthTransportResponse,
+	requestUrl?: string,
 ): Promise<StealthResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
-	const cookies = new CookieJarImpl(
-		setCookieHeadersFromResponse(response.headers),
-	);
+	const cookies = new CookieJarImpl(setCookieHeadersFromResponse(response.headers));
 	const bodyBytes = await response.arrayBuffer();
 	const body = new TextDecoder().decode(bodyBytes);
 
 	return {
 		status: response.status,
 		ok: response.status >= 200 && response.status < 300,
+		...(response.url ? { url: response.url } : {}),
+		...(response.redirected !== undefined
+			? { redirected: response.redirected }
+			: requestUrl && response.url
+				? { redirected: response.url !== requestUrl }
+				: {}),
 		headers,
 		rawHeaders: headerEntriesFromHeaders(response.headers),
 		body,
@@ -383,189 +391,11 @@ function isPolicyManagedProxy(options: StealthClientOptions): boolean {
 	return Boolean(policy && typeof policy === "object");
 }
 
-function isRetrySafeStealthMethod(method: StealthMethod): boolean {
-	return method === "GET" || method === "HEAD" || method === "OPTIONS";
-}
-
-function createStealthRetryOptions(
-	preset: HttpRetryPreset,
-): NormalizedStealthRetryOptions {
-	switch (preset) {
-		case HttpRetryPreset.Off:
-			return {
-				attempts: 1,
-				methods: DEFAULT_STEALTH_RETRY_METHODS,
-				errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.AggressiveRead:
-			return {
-				attempts: 4,
-				methods: DEFAULT_STEALTH_RETRY_METHODS,
-				errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.RateLimitAware:
-			return {
-				attempts: 3,
-				methods: DEFAULT_STEALTH_RETRY_METHODS,
-				errorCodes: RATE_LIMIT_STEALTH_RETRY_ERROR_CODES,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.SafeRead:
-		case HttpRetryPreset.TransportTransient:
-			return {
-				attempts: 3,
-				methods: DEFAULT_STEALTH_RETRY_METHODS,
-				errorCodes: DEFAULT_STEALTH_RETRY_ERROR_CODES,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-	}
-	throw new ProviderError(`Unknown stealth retry preset: ${preset}`, {
-		code: "retry_invalid_policy",
-	});
-}
-
-function normalizeStealthRetryOptions(
-	retry: StealthFetchOptions["retry"],
-): NormalizedStealthRetryOptions | undefined {
-	if (retry === undefined) return undefined;
-	if (retry === false) return createStealthRetryOptions(HttpRetryPreset.Off);
-	if (retry === true)
-		return createStealthRetryOptions(HttpRetryPreset.TransportTransient);
-	if (typeof retry === "string") {
-		if (!Object.values(HttpRetryPreset).includes(retry)) {
-			throw new ProviderError(`Unknown stealth retry preset: ${retry}`, {
-				code: "retry_invalid_policy",
-			});
-		}
-		return createStealthRetryOptions(retry);
-	}
-	if (typeof retry !== "object" || retry === null || Array.isArray(retry)) {
-		throw new ProviderError("Stealth retry policy must be a plain object", {
-			code: "retry_invalid_policy",
-		});
-	}
-	if (
-		retry.unsafeMethodPolicy !== undefined &&
-		!Object.values(HttpRetryUnsafeMethodPolicy).includes(
-			retry.unsafeMethodPolicy,
-		)
-	) {
-		throw new ProviderError(
-			`Unknown stealth retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`,
-			{ code: "retry_invalid_policy" },
-		);
-	}
-	if (retry.methods !== undefined) {
-		if (!Array.isArray(retry.methods)) {
-			throw new ProviderError("Stealth retry methods must be an array", {
-				code: "retry_invalid_policy",
-			});
-		}
-		const unknownMethods = retry.methods
-			.map((method) => (typeof method === "string" ? method.toUpperCase() : ""))
-			.filter((method) => !KNOWN_STEALTH_RETRY_METHODS.has(method));
-		if (unknownMethods.length > 0) {
-			throw new ProviderError(
-				`Unknown stealth retry method(s): ${unknownMethods.join(", ")}`,
-				{ code: "retry_invalid_policy" },
-			);
-		}
-	}
-	if (retry.errorCodes !== undefined) {
-		if (
-			!Array.isArray(retry.errorCodes) ||
-			retry.errorCodes.some((errorCode) => typeof errorCode !== "string")
-		) {
-			throw new ProviderError(
-				"Stealth retry errorCodes must contain only strings",
-				{ code: "retry_invalid_policy" },
-			);
-		}
-	}
-
-	const base = createStealthRetryOptions(
-		retry.preset ?? HttpRetryPreset.TransportTransient,
-	);
-	const attempts =
-		retry.attempts === undefined || !Number.isFinite(retry.attempts)
-			? base.attempts
-			: Math.max(
-					1,
-					Math.min(MAX_STEALTH_RETRY_ATTEMPTS, Math.floor(retry.attempts)),
-				);
-	const normalized: NormalizedStealthRetryOptions = {
-		attempts,
-		methods:
-			retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-		errorCodes: retry.errorCodes ?? base.errorCodes,
-		unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-	};
-
-	if (
-		normalized.unsafeMethodPolicy !==
-		HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe
-	) {
-		const unsafeMethods = normalized.methods.filter((method) =>
-			UNSAFE_STEALTH_RETRY_METHODS.has(method.toUpperCase()),
-		);
-		if (unsafeMethods.length > 0) {
-			throw new ProviderError(
-				`Stealth retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`,
-				{ code: "retry_unsafe_method" },
-			);
-		}
-	}
-
-	return normalized;
-}
-
-function isExplicitStealthRetryAllowed(
-	method: StealthMethod,
-	error: TransportError,
-	retryOptions: NormalizedStealthRetryOptions | undefined,
-): boolean {
-	if (!retryOptions || retryOptions.attempts <= 1) return false;
-	return (
-		retryOptions.methods.includes(method.toUpperCase()) &&
-		retryOptions.errorCodes.includes(proxyAttemptErrorCode(error))
-	);
-}
-
-function isRetryableProxyTransportError(error: unknown): boolean {
-	if (error instanceof TransportError) {
-		if (error.code === PROXY_AUTH_IP_DENIED_CODE) {
-			return false;
-		}
-		return (
-			error.code === PROXY_CONNECT_FAILURE_CODE ||
-			error.code === "transport_network_error" ||
-			error.code === "transport_timeout"
-		);
-	}
-
-	if (error instanceof SDKError) {
-		return false;
-	}
-
-	const message = error instanceof Error ? error.message : String(error);
-	return /\bproxy\b|\bnon[\s-]?200\b|\bconnect\b|\btunnel\b/i.test(message);
-}
-
-function isProxyConnectFailureResponse(
-	response: StealthTransportResponse,
-	body: string,
-): boolean {
-	return (
-		response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? "")
-	);
+function isProxyConnectFailureResponse(response: StealthTransportResponse, body: string): boolean {
+	return response.status === 0 && PROXY_CONNECT_FAILURE_BODY_PATTERN.test(body ?? "");
 }
 
-function createProxyConnectFailureError(
-	body: string,
-	cause?: Error,
-): TransportError {
+function createProxyConnectFailureError(body: string, cause?: Error): TransportError {
 	const bodyExcerpt = (body ?? "").trim().slice(0, 1_000);
 	if (isProxyAuthIpDeniedMessage(bodyExcerpt)) {
 		return createProxyAuthIpDeniedError(cause);
@@ -574,10 +404,7 @@ function createProxyConnectFailureError(
 		return createProxyEdgeAuthRejectedError(cause);
 	}
 	if (isProxyPoolStaleMessage(bodyExcerpt)) {
-		return createProxyPoolStaleError(
-			bodyExcerpt.includes("512") ? 512 : 509,
-			cause,
-		);
+		return createProxyPoolStaleError(bodyExcerpt.includes("512") ? 512 : 509, cause);
 	}
 	return new TransportError(bodyExcerpt || "Proxy CONNECT failed", {
 		code: PROXY_CONNECT_FAILURE_CODE,
@@ -601,6 +428,7 @@ type ResolvedAttemptProxy = {
 	url?: string;
 	poolIndex?: number;
 	proxyHash?: string;
+	vendor?: ProxyVendorName;
 };
 
 function proxyPoolIndexFromDiagnostics(
@@ -684,33 +512,20 @@ function normalizeStealthTransportError(error: unknown): TransportError {
 	}
 
 	if (isProxyAuthIpDeniedMessage(message)) {
-		return createProxyAuthIpDeniedError(
-			error instanceof Error ? error : undefined,
-		);
+		return createProxyAuthIpDeniedError(error instanceof Error ? error : undefined);
 	}
 
 	if (isProxyEdgeAuthRejectedMessage(message)) {
-		return createProxyEdgeAuthRejectedError(
-			error instanceof Error ? error : undefined,
-		);
+		return createProxyEdgeAuthRejectedError(error instanceof Error ? error : undefined);
 	}
 
 	const proxyTunnelStatus = getProxyTunnelStatus(error);
-	if (
-		proxyTunnelStatus !== undefined &&
-		isProxyPoolStaleStatus(proxyTunnelStatus)
-	) {
-		return createProxyPoolStaleError(
-			proxyTunnelStatus,
-			error instanceof Error ? error : undefined,
-		);
+	if (proxyTunnelStatus !== undefined && isProxyPoolStaleStatus(proxyTunnelStatus)) {
+		return createProxyPoolStaleError(proxyTunnelStatus, error instanceof Error ? error : undefined);
 	}
 
 	if (PROXY_CONNECT_FAILURE_BODY_PATTERN.test(message)) {
-		return createProxyConnectFailureError(
-			message,
-			error instanceof Error ? error : undefined,
-		);
+		return createProxyConnectFailureError(message, error instanceof Error ? error : undefined);
 	}
 
 	return new TransportError("Network error", {
@@ -720,6 +535,10 @@ function normalizeStealthTransportError(error: unknown): TransportError {
 	});
 }
 
+function sleep(ms: number): Promise<void> {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
 function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	switch (method.toUpperCase()) {
 		case "HEAD":
@@ -743,6 +562,23 @@ function normalizeMethod(method: HttpMethod | string): StealthMethod {
 	}
 }
 
+function isRedirectStatus(status: number): boolean {
+	return [301, 302, 303, 307, 308].includes(status);
+}
+
+function nextRedirectMethod(status: number, method: StealthMethod): StealthMethod {
+	if (status === 303 && method !== "HEAD") return "GET";
+	if ((status === 301 || status === 302) && method === "POST") return "GET";
+	return method;
+}
+
+function locationHeader(headers: Record<string, string>): string | undefined {
+	for (const [name, value] of Object.entries(headers)) {
+		if (name.toLowerCase() === "location") return value;
+	}
+	return undefined;
+}
+
 function createSessionFetcher(
 	baseUrl: string,
 	defaultProfile: string,
@@ -782,20 +618,22 @@ function createSessionFetcher(
 	async function resolveRequestProxy(
 		options?: StealthFetchOptions,
 		proxyAttempt?: number,
+		refreshEpoch?: number,
 	): Promise<ResolvedAttemptProxy> {
-		const rawProxyAttemptOffset = options?.proxyAttemptOffset ?? 0;
-		const proxyAttemptOffset = Number.isFinite(rawProxyAttemptOffset)
-			? Math.max(0, Math.floor(rawProxyAttemptOffset))
-			: 0;
 		const resolvedProxy = await resolveProxyConfigAsync({
 			proxy: options?.proxy ?? clientOptions.proxy,
 			upstream: clientOptions.upstream,
 			apifuseConfig: clientOptions.apifuseConfig,
 			affinityKey: clientOptions.affinityKey,
-			proxyAttempt:
-				proxyAttempt === undefined
-					? proxyAttemptOffset
-					: proxyAttemptOffset + proxyAttempt,
+			proxyAttempt: computeProxyAttemptIndex({
+				baseProxyAttempt: clientOptions.proxyAttempt,
+				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,
 		});
 
@@ -808,30 +646,58 @@ function createSessionFetcher(
 			url: resolvedProxy.url,
 			poolIndex: proxyPoolIndexFromDiagnostics(resolvedProxy.diagnostics),
 			proxyHash: proxyEndpointHash(resolvedProxy.url),
+			vendor: vendorFromResolvedSource(resolvedProxy.source),
 		};
 	}
 
-	return {
+	const session: StealthSession = {
 		async fetch(url, options: StealthFetchOptions = {}) {
 			const method = normalizeMethod(options.method ?? "GET");
 			const hasExplicitRetryPolicy = options.retry !== undefined;
-			const stealthRetryOptions = normalizeStealthRetryOptions(options.retry);
+			const stealthRetryOptions =
+				normalizeProxyTransportRetryOptions(options.retry, {
+					extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+					label: "Stealth",
+				}) ??
+				(hasExplicitRetryPolicy
+					? undefined
+					: createDefaultProxyTransportRetryOptions({
+							extraErrorCodes: STEALTH_PROXY_TRANSPORT_RETRY_ERROR_CODES,
+							label: "Stealth",
+						}));
+			if (stealthRetryOptions) {
+				validateUnsafeProxyTransportRetryMethods(stealthRetryOptions, "Stealth");
+			}
 			const hasPolicyProxy = isPolicyManagedProxy(clientOptions);
-			const usesPolicyAllocator =
-				hasPolicyProxy && !options.proxy && !clientOptions.proxy;
-			const maxAttempts = usesPolicyAllocator
-				? 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,
-						),
-					)
-				: 1;
+			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,
+				policyProxy ? resolvePolicyProxyPoolSpan(policyProxy) : DEFAULT_SMARTPROXY_POOL_SIZE,
+			);
+			// 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 (
@@ -856,14 +722,12 @@ function createSessionFetcher(
 						if (attemptRecorded || !proxy) return;
 						attemptRecorded = true;
 						clientOptions.telemetry?.recordProxyAttempt?.({
-							provider: "smartproxy",
+							provider: attemptProxy?.vendor ?? "smartproxy",
 							attempt: attempt + 1,
 							...(attemptProxy?.poolIndex === undefined
 								? {}
 								: { poolIndex: attemptProxy.poolIndex }),
-							...(attemptProxy?.proxyHash
-								? { proxyHash: attemptProxy.proxyHash }
-								: {}),
+							...(attemptProxy?.proxyHash ? { proxyHash: attemptProxy.proxyHash } : {}),
 							outcome,
 							...(errorCode ? { errorCode } : {}),
 							...(status === undefined ? {} : { status }),
@@ -872,52 +736,47 @@ function createSessionFetcher(
 					};
 					try {
 						assertNoUnsupportedFingerprintOverrides(options);
-						attemptProxy = await resolveRequestProxy(options, attempt);
+						attemptProxy = await resolveRequestProxy(options, attempt, refreshAttempt);
 						proxy = attemptProxy.url;
-						if (proxy) {
+						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);
 						}
 						const ignoreTlsErrors = Boolean(
 							options.stealth?.insecureSkipVerify ??
-								(!hasPolicyProxy &&
-									proxy &&
-									clientOptions.proxyStealth?.insecureSkipVerify),
+								(!hasPolicyProxy && proxy && clientOptions.proxyStealth?.insecureSkipVerify),
 						);
 						const profileName = options.profile ?? defaultProfile;
-						const requestUrl = appendQueryParams(
-							resolveUrl(baseUrl, url),
-							options.params,
-						);
+						const requestUrl = appendQueryParams(resolveUrl(baseUrl, url), options.params);
 						const headers = { ...(options.headers ?? {}) };
 						if (!hasHeader(headers, "Cookie")) {
 							const cookieHeader = cookieJar.toString();
 							if (cookieHeader) headers.Cookie = cookieHeader;
 						}
-						const requestInit: ImpitRequestInit = {
+						const requestInit: StealthRequestInit = {
 							headers: normalizeHeaders(headers),
 							method,
+							...(options.redirect ? { redirect: options.redirect } : {}),
 							...(options.timeout ? { timeout: options.timeout } : {}),
 						};
 						if (options.body !== undefined) {
 							requestInit.body = normalizeBody(options.body);
 						}
-						const response = await getClient(
-							profileName,
-							proxy,
-							ignoreTlsErrors,
-						).fetch(requestUrl, requestInit);
-						const normalized = await normalizeResponse(response);
-						cookieJar.setFromCookieStrings(
-							setCookieHeadersFromResponse(response.headers),
+						const response = await getClient(profileName, proxy, ignoreTlsErrors).fetch(
+							requestUrl,
+							requestInit,
 						);
+						const normalized = await normalizeResponse(response, requestUrl);
+						cookieJar.setFromCookieStrings(setCookieHeadersFromResponse(response.headers));
 
-						if (
-							proxy &&
-							isProxyConnectFailureResponse(response, normalized.body)
-						) {
+						if (proxy && isProxyConnectFailureResponse(response, normalized.body)) {
 							throw createProxyConnectFailureError(normalized.body);
 						}
 
@@ -927,10 +786,9 @@ function createSessionFetcher(
 								usesPolicyAllocator &&
 								isProxyEdgeTlsRejectedResponse(
 									response.status,
-									[
-										JSON.stringify(responseHeadersToRecord(response.headers)),
-										normalized.body,
-									].join("\n"),
+									[JSON.stringify(responseHeadersToRecord(response.headers)), normalized.body].join(
+										"\n",
+									),
 								)
 							) {
 								throw createProxyEdgeTlsRejectedError(response.status);
@@ -951,13 +809,10 @@ function createSessionFetcher(
 						}
 
 						if (response.status >= 400 && options.throwOnHttpError !== false) {
-							throw new TransportError(
-								`Upstream request failed with status ${response.status}`,
-								{
-									code: "upstream_http_error",
-									status: response.status,
-								},
-							);
+							throw new TransportError(`Upstream request failed with status ${response.status}`, {
+								code: "upstream_http_error",
+								status: response.status,
+							});
 						}
 
 						recordProxyAttempt("ok", undefined, response.status);
@@ -970,11 +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;
@@ -984,21 +835,39 @@ 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 (
-							proxy &&
-							attempt + 1 <
-								(stealthRetryOptions
-									? Math.min(maxAttempts, stealthRetryOptions.attempts)
-									: maxAttempts) &&
-							(!hasExplicitRetryPolicy
-								? isRetrySafeStealthMethod(method)
-								: isExplicitStealthRetryAllowed(
-										method,
-										normalizedError,
-										stealthRetryOptions,
-									)) &&
-							isRetryableProxyTransportError(normalizedError)
+							attempt + 1 < transportRetryCap &&
+							shouldRetryProxyTransportAttempt({
+								error: normalizedError,
+								explicitRetry: hasExplicitRetryPolicy,
+								method,
+								options: stealthRetryOptions,
+								proxyUsed: Boolean(proxy),
+							})
 						) {
+							if (stealthRetryOptions) {
+								await sleep(computeProxyTransportRetryDelayMs(stealthRetryOptions!, attempt + 1));
+							}
 							continue;
 						}
 						throw normalizedError;
@@ -1006,7 +875,7 @@ function createSessionFetcher(
 				}
 
 				if (
-					usesPolicyAllocator &&
+					rotatesRegistryChain &&
 					stalePoolError &&
 					refreshAttempt < MAX_POLICY_PROXY_POOL_REFRESHES
 				) {
@@ -1052,33 +921,138 @@ function createSessionFetcher(
 
 			throw normalizeStealthTransportError(lastError);
 		},
+		cookies: cookieJar,
+		redirects: {
+			async run(options) {
+				const maxHops =
+					options.maxHops === undefined || !Number.isFinite(options.maxHops)
+						? 10
+						: Math.max(0, Math.floor(options.maxHops));
+				const hops: StealthRedirectHop[] = [];
+				let currentUrl = resolveUrl(baseUrl, options.url);
+				let method = normalizeMethod(options.method ?? "GET");
+				let body = options.body;
+				let response: StealthResponse | undefined;
+				const visitedRequests = new Set<string>();
+
+				const { url: _url, maxHops: _maxHops, stopWhen, params, ...fetchOptions } = options;
+
+				for (let hopIndex = 0; hopIndex <= maxHops; hopIndex += 1) {
+					visitedRequests.add(`${method} ${currentUrl}`);
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(hopIndex === 0 && params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+
+					if (!isRedirectStatus(response.status)) {
+						return {
+							final: response,
+							hops,
+							reason: "completed",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const location = locationHeader(response.headers);
+					const nextUrl = location
+						? new URL(location, response.url ?? currentUrl).toString()
+						: undefined;
+					const hop: StealthRedirectHop = {
+						url: response.url ?? currentUrl,
+						status: response.status,
+						method,
+						...(location ? { location } : {}),
+						...(nextUrl ? { nextUrl } : {}),
+					};
+					hops.push(hop);
+
+					if (stopWhen && (await stopWhen(hop))) {
+						return {
+							final: response,
+							hops,
+							reason: "stopped",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (!nextUrl) {
+						return {
+							final: response,
+							hops,
+							reason: "missing_location",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					if (hops.length > maxHops) {
+						return {
+							final: response,
+							hops,
+							reason: "max_hops",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+
+					const nextMethod = nextRedirectMethod(response.status, method);
+					if (nextMethod !== method) {
+						body = undefined;
+					}
+					if (visitedRequests.has(`${nextMethod} ${nextUrl}`)) {
+						return {
+							final: response,
+							hops,
+							reason: "loop",
+							cookies: cookieJar.snapshot(),
+						};
+					}
+					method = nextMethod;
+					currentUrl = nextUrl;
+				}
+
+				if (!response) {
+					response = await session.fetch(currentUrl, {
+						...fetchOptions,
+						body,
+						method,
+						...(params ? { params } : {}),
+						redirect: "manual",
+						throwOnHttpError: false,
+					});
+				}
+				return {
+					final: response,
+					hops,
+					reason: "max_hops",
+					cookies: cookieJar.snapshot(),
+				};
+			},
+		},
 		close() {
 			closed = true;
 			clients.clear();
 		},
 	};
+	return session;
 
 	async function classifyProxyAuthDiagnostic(
 		profileName: string,
 		proxy: string,
 	): Promise<"source_ip_denied" | "edge_auth_rejected" | undefined> {
 		try {
-			const response = await getClient(profileName, proxy, false).fetch(
-				PROXY_AUTH_DIAGNOSTIC_URL,
-				{
-					method: "GET",
-					timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
-				},
-			);
+			const response = await getClient(profileName, proxy, false).fetch(PROXY_AUTH_DIAGNOSTIC_URL, {
+				method: "GET",
+				timeout: PROXY_AUTH_DIAGNOSTIC_TIMEOUT_MS,
+			});
 			const normalized = await normalizeResponse(response);
 			return classifyProxyAuthDiagnosticMessage(normalized.body);
 		} catch (error) {
 			const message =
 				error instanceof Error
-					? [
-							error.message,
-							error.cause instanceof Error ? error.cause.message : "",
-						]
+					? [error.message, error.cause instanceof Error ? error.cause.message : ""]
 							.filter(Boolean)
 							.join(" ")
 					: String(error);
@@ -1118,22 +1092,14 @@ export function createStealthClient(
 	clientOptions: StealthClientOptions = {},
 ): StealthClient {
 	const defaultProfile =
-		typeof defaultProfileOrOptions === "string"
-			? defaultProfileOrOptions
-			: DEFAULT_PROFILE;
+		typeof defaultProfileOrOptions === "string" ? defaultProfileOrOptions : DEFAULT_PROFILE;
 	const resolvedClientOptions =
-		typeof defaultProfileOrOptions === "string"
-			? clientOptions
-			: defaultProfileOrOptions;
+		typeof defaultProfileOrOptions === "string" ? clientOptions : defaultProfileOrOptions;
 	let sharedSession: StealthSession | null = null;
 
 	function getSharedSession(): StealthSession {
 		if (!sharedSession) {
-			sharedSession = createSessionFetcher(
-				baseUrl,
-				defaultProfile,
-				resolvedClientOptions,
-			);
+			sharedSession = createSessionFetcher(baseUrl, defaultProfile, resolvedClientOptions);
 		}
 
 		return sharedSession;
@@ -1145,11 +1111,7 @@ export function createStealthClient(
 		},
 		createSession(opts?: { profile?: string }) {
 			const sessionProfile = opts?.profile ?? defaultProfile;
-			return createSessionFetcher(
-				baseUrl,
-				sessionProfile,
-				resolvedClientOptions,
-			);
+			return createSessionFetcher(baseUrl, sessionProfile, resolvedClientOptions);
 		},
 		close() {
 			sharedSession?.close();