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

package/src/runtime/http.ts

@@ -1,31 +1,34 @@
-import type { ProxyResolutionOptions } from "../config/loader";
-import { resolveProxyConfigAsync } from "../config/loader";
-import { ProviderError, TransportError } from "../errors";
+import type { ProxyResolutionOptions } from "../config/loader.js";
 import {
-	parseSseStream,
-	readableBytes,
-	readableLines,
-	readableTextChunks,
-} from "../stream";
+	policyRotatesTransportVendorChain,
+	resolvePolicyTransportAttemptCap,
+	resolveProxyConfigAsync,
+} from "../config/loader.js";
+import { ProviderError, TransportError } from "../errors.js";
+import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
 	HttpClient,
 	HttpMethod,
 	HttpResponse,
-	HttpRetryOptions,
 	HttpRetrySummary,
 	HttpStreamResponse,
+	ProviderProxyPolicy,
 	RequestOptions,
 	RequestWithMethodOptions,
 	SseMessage,
-} from "../types";
+} from "../types.js";
 import {
-	HttpRetryAfterPolicy,
-	HttpRetryDelayStrategy,
-	HttpRetryJitter,
-	HttpRetryPreset,
-	HttpRetryUnsafeMethodPolicy,
-} from "../types";
-import { appendQueryParams, normalizeHttpRequestBody } from "./request-options";
+	computeProxyAttemptIndex,
+	computeProxyTransportRetryDelayMs,
+	createDefaultProxyTransportRetryOptions,
+	isProxyTransportRetryMethod,
+	normalizeProxyTransportRetryOptions,
+	proxyTransportRetryErrorCode,
+	proxyTransportRetryErrorStatus,
+	shouldRetryProxyTransportAttempt,
+	validateUnsafeProxyTransportRetryMethods,
+} from "./proxy-retry-policy.js";
+import { appendQueryParams, normalizeHttpRequestBody } from "./request-options.js";
 
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
 
@@ -35,445 +38,34 @@ export type HttpClientOptions = ProxyResolutionOptions & {
 	onRetrySummary?: (summary: HttpRetrySummary) => void;
 };
 
-type NormalizedRetryOptions = Required<
-	Pick<
-		HttpRetryOptions,
-		| "attempts"
-		| "delayStrategy"
-		| "baseDelayMs"
-		| "maxDelayMs"
-		| "jitter"
-		| "retryAfter"
-		| "unsafeMethodPolicy"
-	>
-> & {
-	preset?: HttpRetryPreset;
-	methods: readonly string[];
-	statusCodes: readonly number[];
-	errorCodes: readonly string[];
-};
-
 type HttpStatusOutcome = {
 	kind: "http-status";
 	status: number;
 	headers: Record<string, string>;
 	retryable: boolean;
+	proxyUsed: boolean;
 };
 
-function isHttpStatusOutcome(
-	outcome: HttpResponse | HttpStatusOutcome,
-): outcome is HttpStatusOutcome {
-	return "kind" in outcome && outcome.kind === "http-status";
-}
-
-const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"] as const;
-const DEFAULT_RETRY_ERROR_CODES = [
-	"transport_network_error",
-	"transport_timeout",
-] as const;
-const SAFE_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504] as const;
-const RATE_LIMIT_RETRY_STATUS_CODES = [429, 503] as const;
-const KNOWN_RETRY_METHODS = new Set([
-	"GET",
-	"HEAD",
-	"POST",
-	"PUT",
-	"DELETE",
-	"OPTIONS",
-	"TRACE",
-	"PATCH",
-]);
-const UNSAFE_RETRY_METHODS = new Set([
-	"POST",
-	"PUT",
-	"PATCH",
-	"DELETE",
-	"TRACE",
-]);
-const MAX_RETRY_ATTEMPTS = 8;
-const MAX_RETRY_DELAY_MS = 30_000;
-
-function hasOwnValue<T extends string>(
-	values: Record<string, T>,
-	value: unknown,
-): value is T {
-	if (typeof value !== "string") return false;
-	return Object.values(values).some((candidate) => candidate === value);
-}
-
-function createInvalidRetryPolicyError(message: string): ProviderError {
-	return new ProviderError(message, { code: "retry_invalid_policy" });
-}
-
-function createRetryOptions(preset: HttpRetryPreset): NormalizedRetryOptions {
-	switch (preset) {
-		case HttpRetryPreset.Off:
-			return {
-				preset,
-				attempts: 1,
-				methods: DEFAULT_RETRY_METHODS,
-				statusCodes: [],
-				errorCodes: DEFAULT_RETRY_ERROR_CODES,
-				delayStrategy: HttpRetryDelayStrategy.Exponential,
-				baseDelayMs: 100,
-				maxDelayMs: 1_000,
-				jitter: HttpRetryJitter.Full,
-				retryAfter: HttpRetryAfterPolicy.Ignore,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.SafeRead:
-			return {
-				preset,
-				attempts: 3,
-				methods: DEFAULT_RETRY_METHODS,
-				statusCodes: SAFE_RETRY_STATUS_CODES,
-				errorCodes: DEFAULT_RETRY_ERROR_CODES,
-				delayStrategy: HttpRetryDelayStrategy.Exponential,
-				baseDelayMs: 100,
-				maxDelayMs: 2_000,
-				jitter: HttpRetryJitter.Full,
-				retryAfter: HttpRetryAfterPolicy.Cap,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.AggressiveRead:
-			return {
-				preset,
-				attempts: 4,
-				methods: DEFAULT_RETRY_METHODS,
-				statusCodes: SAFE_RETRY_STATUS_CODES,
-				errorCodes: DEFAULT_RETRY_ERROR_CODES,
-				delayStrategy: HttpRetryDelayStrategy.Exponential,
-				baseDelayMs: 150,
-				maxDelayMs: 5_000,
-				jitter: HttpRetryJitter.Full,
-				retryAfter: HttpRetryAfterPolicy.Cap,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.RateLimitAware:
-			return {
-				preset,
-				attempts: 3,
-				methods: DEFAULT_RETRY_METHODS,
-				statusCodes: RATE_LIMIT_RETRY_STATUS_CODES,
-				errorCodes: ["transport_timeout"],
-				delayStrategy: HttpRetryDelayStrategy.Exponential,
-				baseDelayMs: 250,
-				maxDelayMs: 5_000,
-				jitter: HttpRetryJitter.Equal,
-				retryAfter: HttpRetryAfterPolicy.Respect,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-		case HttpRetryPreset.TransportTransient:
-			return {
-				preset,
-				attempts: 3,
-				methods: DEFAULT_RETRY_METHODS,
-				statusCodes: [],
-				errorCodes: DEFAULT_RETRY_ERROR_CODES,
-				delayStrategy: HttpRetryDelayStrategy.Exponential,
-				baseDelayMs: 100,
-				maxDelayMs: 1_000,
-				jitter: HttpRetryJitter.Full,
-				retryAfter: HttpRetryAfterPolicy.Ignore,
-				unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-			};
-	}
-	throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${preset}`);
-}
-
-function clampPositiveInteger(
-	value: number | undefined,
-	fallback: number,
-	max: number,
-): number {
-	if (value === undefined) return fallback;
-	if (!Number.isFinite(value) || value < 1) return fallback;
-	return Math.min(Math.floor(value), max);
-}
-
-function clampDelay(value: number | undefined, fallback: number): number {
-	if (value === undefined) return fallback;
-	if (!Number.isFinite(value) || value < 0) return fallback;
-	return Math.min(Math.floor(value), MAX_RETRY_DELAY_MS);
-}
-
-function normalizeRetryOptions(
-	retry: RequestOptions["retry"],
-): NormalizedRetryOptions | undefined {
-	if (retry === undefined || retry === false) {
-		return undefined;
-	}
-	if (retry === true) {
-		return createRetryOptions(HttpRetryPreset.TransportTransient);
-	}
-	if (typeof retry === "string") {
-		if (!hasOwnValue(HttpRetryPreset, retry)) {
-			throw createInvalidRetryPolicyError(
-				`Unknown HTTP retry preset: ${retry}`,
-			);
-		}
-		return createRetryOptions(retry);
-	}
-	if (typeof retry !== "object" || retry === null) {
-		throw createInvalidRetryPolicyError("HTTP retry policy must be an object");
-	}
-	if (Array.isArray(retry)) {
-		throw createInvalidRetryPolicyError(
-			"HTTP retry policy must be a plain object",
-		);
-	}
-
-	validateRetryOptionsShape(retry);
-	const base = createRetryOptions(
-		retry.preset ?? HttpRetryPreset.TransportTransient,
-	);
-	const maxDelayMs = clampDelay(retry.maxDelayMs, base.maxDelayMs);
-	const normalized: NormalizedRetryOptions = {
-		preset: retry.preset ?? base.preset,
-		attempts: clampPositiveInteger(
-			retry.attempts,
-			base.attempts,
-			MAX_RETRY_ATTEMPTS,
-		),
-		methods:
-			retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-		statusCodes:
-			retry.statusCodes?.filter((status) => Number.isInteger(status)) ??
-			base.statusCodes,
-		errorCodes: retry.errorCodes ?? base.errorCodes,
-		delayStrategy: retry.delayStrategy ?? base.delayStrategy,
-		baseDelayMs: clampDelay(retry.baseDelayMs, base.baseDelayMs),
-		maxDelayMs,
-		jitter: retry.jitter ?? base.jitter,
-		retryAfter: retry.retryAfter ?? base.retryAfter,
-		unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-	};
-
-	return normalized;
-}
-
-function validateRetryOptionsShape(retry: HttpRetryOptions): void {
-	if (
-		retry.preset !== undefined &&
-		!hasOwnValue(HttpRetryPreset, retry.preset)
-	) {
-		throw createInvalidRetryPolicyError(
-			`Unknown HTTP retry preset: ${String(retry.preset)}`,
-		);
-	}
-	if (
-		retry.delayStrategy !== undefined &&
-		!hasOwnValue(HttpRetryDelayStrategy, retry.delayStrategy)
-	) {
-		throw createInvalidRetryPolicyError(
-			`Unknown HTTP retry delay strategy: ${String(retry.delayStrategy)}`,
-		);
-	}
-	if (
-		retry.jitter !== undefined &&
-		!hasOwnValue(HttpRetryJitter, retry.jitter)
-	) {
-		throw createInvalidRetryPolicyError(
-			`Unknown HTTP retry jitter policy: ${String(retry.jitter)}`,
-		);
-	}
-	if (
-		retry.retryAfter !== undefined &&
-		!hasOwnValue(HttpRetryAfterPolicy, retry.retryAfter)
-	) {
-		throw createInvalidRetryPolicyError(
-			`Unknown HTTP retry-after policy: ${String(retry.retryAfter)}`,
-		);
-	}
-	if (
-		retry.unsafeMethodPolicy !== undefined &&
-		!hasOwnValue(HttpRetryUnsafeMethodPolicy, retry.unsafeMethodPolicy)
-	) {
-		throw createInvalidRetryPolicyError(
-			`Unknown HTTP retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`,
-		);
-	}
-	if (retry.methods !== undefined) {
-		if (!Array.isArray(retry.methods)) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry methods must be an array",
-			);
-		}
-		const nonStringMethods = retry.methods.filter(
-			(method) => typeof method !== "string",
-		);
-		if (nonStringMethods.length > 0) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry methods must contain only strings",
-			);
-		}
-		const unknownMethods = retry.methods
-			.map((method) => method.toUpperCase())
-			.filter((method) => !KNOWN_RETRY_METHODS.has(method));
-		if (unknownMethods.length > 0) {
-			throw createInvalidRetryPolicyError(
-				`Unknown HTTP retry method(s): ${unknownMethods.join(", ")}`,
-			);
-		}
-	}
-	if (retry.statusCodes !== undefined) {
-		if (!Array.isArray(retry.statusCodes)) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry statusCodes must be an array",
-			);
-		}
-		const invalidStatusCodes = retry.statusCodes.filter(
-			(status) =>
-				!Number.isInteger(status) ||
-				Number(status) < 100 ||
-				Number(status) > 599,
-		);
-		if (invalidStatusCodes.length > 0) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry statusCodes must contain HTTP status integers in [100, 599]",
-			);
-		}
-	}
-	if (retry.errorCodes !== undefined) {
-		if (!Array.isArray(retry.errorCodes)) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry errorCodes must be an array",
-			);
-		}
-		const nonStringErrorCodes = retry.errorCodes.filter(
-			(errorCode) => typeof errorCode !== "string",
-		);
-		if (nonStringErrorCodes.length > 0) {
-			throw createInvalidRetryPolicyError(
-				"HTTP retry errorCodes must contain only strings",
-			);
-		}
-	}
-	if (
-		retry.preset === HttpRetryPreset.Off &&
-		((retry.attempts !== undefined && retry.attempts > 1) ||
-			(retry.statusCodes !== undefined && retry.statusCodes.length > 0))
-	) {
-		throw createInvalidRetryPolicyError(
-			"HTTP retry preset off cannot be combined with retry-enabling overrides",
-		);
-	}
-}
-
-function validateUnsafeRetryMethods(options: NormalizedRetryOptions): void {
-	if (
-		options.unsafeMethodPolicy ===
-		HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe
-	) {
-		return;
-	}
-	const unsafeMethods = options.methods.filter((method) =>
-		UNSAFE_RETRY_METHODS.has(method.toUpperCase()),
-	);
-	if (unsafeMethods.length === 0) return;
-
-	throw new ProviderError(
-		`HTTP retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`,
-		{ code: "retry_unsafe_method" },
-	);
-}
-
-function isMethodRetryable(
-	method: HttpMethod,
-	options: NormalizedRetryOptions,
-): boolean {
-	return options.methods
-		.map((allowedMethod) => allowedMethod.toUpperCase())
-		.includes(method.toUpperCase());
-}
-
-function retryErrorCode(error: unknown): string | undefined {
-	if (error instanceof TransportError) {
-		return error.code;
-	}
-	if (error && typeof error === "object" && "code" in error) {
-		const code = Reflect.get(error, "code");
-		return typeof code === "string" ? code : undefined;
-	}
-	return undefined;
-}
+/**
+ * Sentinel returned when a policy-allocator attempt resolved an endpoint that a
+ * prior attempt already tried (an under-filled pool repeats endpoints via the
+ * modulo mapping before the flat offset crosses into the next vendor). The retry
+ * loop advances to the next offset rather than re-issuing the request — but does
+ * NOT treat it as chain exhaustion, so the offset still walks into the fallback
+ * vendor's span.
+ */
+type NativeHttpSkipOutcome = { kind: "dedupe-skip" };
 
-function retryErrorStatus(error: unknown): number | undefined {
-	if (error instanceof TransportError) {
-		return error.status ?? error.upstreamStatus;
-	}
-	return undefined;
-}
+type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome | NativeHttpSkipOutcome;
 
-function shouldRetryTransportError(
-	error: unknown,
-	options: NormalizedRetryOptions,
-): boolean {
-	const code = retryErrorCode(error);
-	return Boolean(code && options.errorCodes.includes(code));
-}
+type NativeHttpAttemptError = TransportError & { proxyUsed?: boolean };
 
-function retryAfterHeader(headers: Record<string, string>): string | undefined {
-	for (const [name, value] of Object.entries(headers)) {
-		if (name.toLowerCase() === "retry-after") return value;
-	}
-	return undefined;
+function isHttpStatusOutcome(outcome: NativeHttpAttemptOutcome): outcome is HttpStatusOutcome {
+	return "kind" in outcome && outcome.kind === "http-status";
 }
 
-function parseRetryAfterMs(
-	headers: Record<string, string>,
-	now: number = Date.now(),
-): number | undefined {
-	const value = retryAfterHeader(headers);
-	if (!value) return undefined;
-	const seconds = Number(value);
-	if (Number.isFinite(seconds)) {
-		return Math.max(0, Math.floor(seconds * 1_000));
-	}
-	const dateMs = Date.parse(value);
-	if (!Number.isNaN(dateMs)) {
-		return Math.max(0, dateMs - now);
-	}
-	return undefined;
-}
-
-function computeRetryDelayMs(
-	options: NormalizedRetryOptions,
-	attemptIndex: number,
-	headers?: Record<string, string>,
-): number {
-	const multiplier =
-		options.delayStrategy === HttpRetryDelayStrategy.Exponential
-			? 2 ** Math.max(0, attemptIndex - 1)
-			: 1;
-	const configuredDelay = Math.min(
-		options.baseDelayMs * multiplier,
-		options.maxDelayMs,
-	);
-	const retryAfterMs =
-		options.retryAfter === HttpRetryAfterPolicy.Ignore
-			? undefined
-			: headers
-				? parseRetryAfterMs(headers)
-				: undefined;
-	if (retryAfterMs !== undefined) {
-		const boundedRetryAfterMs = Math.min(retryAfterMs, options.maxDelayMs);
-		if (options.retryAfter === HttpRetryAfterPolicy.Cap) {
-			return Math.min(boundedRetryAfterMs, configuredDelay);
-		}
-		return boundedRetryAfterMs;
-	}
-
-	switch (options.jitter) {
-		case HttpRetryJitter.None:
-			return configuredDelay;
-		case HttpRetryJitter.Equal:
-			return Math.floor(
-				configuredDelay / 2 + Math.random() * (configuredDelay / 2),
-			);
-		case HttpRetryJitter.Full:
-			return Math.floor(Math.random() * configuredDelay);
-	}
+function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is NativeHttpSkipOutcome {
+	return "kind" in outcome && outcome.kind === "dedupe-skip";
 }
 
 async function sleep(ms: number): Promise<void> {
@@ -500,9 +92,7 @@ function withClientHeaders(
 	body: unknown,
 ): RequestOptions {
 	const headers: Record<string, string> = {
-		...(clientOptions.userAgent
-			? { "User-Agent": clientOptions.userAgent }
-			: {}),
+		...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
 		...options?.headers,
 	};
 
@@ -517,10 +107,7 @@ function withClientHeaders(
 }
 
 function parseHttpData(body: string, headers: Record<string, string>): unknown {
-	const contentType =
-		headers["content-type"] ??
-		headers["Content-Type"] ??
-		headers["CONTENT-TYPE"];
+	const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
 
 	if (contentType?.includes("application/json")) {
 		return body ? JSON.parse(body) : null;
@@ -582,7 +169,8 @@ function toHttpTransportError(error: unknown): TransportError {
 
 async function toNativeHttpResponse(response: Response): Promise<HttpResponse> {
 	const headers = Object.fromEntries(response.headers.entries());
-	const rawText = await response.text();
+	const bodyBytes = new Uint8Array(await response.arrayBuffer());
+	const rawText = new TextDecoder().decode(bodyBytes);
 	const data = parseHttpData(rawText, headers);
 
 	return {
@@ -590,18 +178,15 @@ async function toNativeHttpResponse(response: Response): Promise<HttpResponse> {
 		headers,
 		json: async <T = unknown>() => {
 			const contentType =
-				headers["content-type"] ??
-				headers["Content-Type"] ??
-				headers["CONTENT-TYPE"];
-			return parseJson<T>(
-				contentType?.includes("application/json") && !rawText
-					? "null"
-					: rawText,
-			);
+				headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
+			return parseJson<T>(contentType?.includes("application/json") && !rawText ? "null" : rawText);
 		},
 		ok: response.status >= 200 && response.status < 300,
 		status: response.status,
 		text: async () => rawText,
+		arrayBuffer: async () =>
+			bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength),
+		bytes: async () => bodyBytes.slice(0),
 	};
 }
 
@@ -613,9 +198,7 @@ async function drainNativeResponseBody(response: Response): Promise<void> {
 	}
 }
 
-function requireNativeResponseBody(
-	response: Response,
-): ReadableStream<Uint8Array> {
+function requireNativeResponseBody(response: Response): ReadableStream<Uint8Array> {
 	if (!response.body) {
 		throw new TransportError("Response body stream is unavailable", {
 			code: "transport_stream_unavailable",
@@ -678,12 +261,21 @@ async function resolveNativeProxy(
 	options: RequestOptions,
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
+	proxyAttemptOffset = 0,
 ): Promise<string | undefined> {
 	const resolvedProxy = await resolveProxyConfigAsync({
 		proxy: options.proxy ?? clientOptions.proxy,
 		upstream: clientOptions.upstream,
 		apifuseConfig: clientOptions.apifuseConfig,
+		proxyPolicy: clientOptions.proxyPolicy,
 		affinityKey: clientOptions.affinityKey,
+		proxyAttempt: computeProxyAttemptIndex({
+			baseProxyAttempt: clientOptions.proxyAttempt,
+			retryAttemptOffset: proxyAttemptOffset,
+		}),
+		// Bun's native fetch proxy option tunnels HTTP CONNECT only; SOCKS5 is not
+		// supported here, so a socks5 policy fails loudly rather than downgrading.
+		transportProtocols: ["http"],
 		telemetry: clientOptions.telemetry,
 	});
 	if (resolvedProxy.shouldWarn) {
@@ -703,9 +295,7 @@ function assertNoHttpTransportOverrides(options: RequestOptions): void {
 	}
 }
 
-function normalizeNativeFetchBody(
-	body: unknown,
-): string | ArrayBuffer | undefined {
+function normalizeNativeFetchBody(body: unknown): string | ArrayBuffer | undefined {
 	const normalized = normalizeHttpRequestBody(body);
 	if (!Buffer.isBuffer(normalized)) {
 		return normalized;
@@ -723,18 +313,31 @@ async function fetchNativeHttp(
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
 	statusRetryCodes?: readonly number[],
-): Promise<HttpResponse | HttpStatusOutcome> {
-	const requestUrl = appendQueryParams(
-		resolveHttpUrl(baseUrl, url),
-		options.params,
-	);
+	proxyAttemptOffset = 0,
+	dedupe?: { attempted: Set<string> },
+): Promise<NativeHttpAttemptOutcome> {
+	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
 	const controller = options.timeout ? new AbortController() : undefined;
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
+	let proxy: string | undefined;
 	try {
-		const proxy = await resolveNativeProxy(options, clientOptions, warn);
+		// Resolve inside the try (and after the timeout is armed) so allocator
+		// failures are branded as TransportErrors and count against the request
+		// deadline, exactly as an inline resolve would.
+		proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+		// For a registry allocator chain, skip an endpoint a prior attempt already
+		// tried rather than re-issuing the same request. Returning the sentinel
+		// (instead of breaking) lets the loop keep advancing the flat offset until
+		// it crosses into the fallback vendor's pool span.
+		if (dedupe && proxy) {
+			if (dedupe.attempted.has(proxy)) {
+				return { kind: "dedupe-skip" };
+			}
+			dedupe.attempted.add(proxy);
+		}
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
@@ -756,18 +359,16 @@ async function fetchNativeHttp(
 				status: response.status,
 				headers,
 				retryable: statusRetryCodes.includes(response.status),
+				proxyUsed: Boolean(proxy),
 			};
 		}
 
 		if (response.status >= 400 && options.throwOnHttpError !== false) {
 			await drainNativeResponseBody(response);
-			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,
+			});
 		}
 
 		return toNativeHttpResponse(response);
@@ -775,7 +376,9 @@ async function fetchNativeHttp(
 		if (error instanceof SyntaxError) {
 			throw error;
 		}
-		throw toHttpTransportError(error);
+		const transportError = toHttpTransportError(error) as NativeHttpAttemptError;
+		transportError.proxyUsed = Boolean(proxy);
+		throw transportError;
 	} finally {
 		if (timeoutHandle) clearTimeout(timeoutHandle);
 	}
@@ -789,10 +392,7 @@ async function fetchNativeHttpStream(
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
 ): Promise<HttpStreamResponse> {
-	const requestUrl = appendQueryParams(
-		resolveHttpUrl(baseUrl, url),
-		options.params,
-	);
+	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
 	const controller = options.timeout ? new AbortController() : undefined;
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
@@ -815,13 +415,10 @@ async function fetchNativeHttpStream(
 
 		if (response.status >= 400 && options.throwOnHttpError !== false) {
 			await drainNativeResponseBody(response);
-			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,
+			});
 		}
 
 		return toNativeHttpStreamResponse(response);
@@ -861,31 +458,84 @@ export function createHttpClient(
 			);
 		}
 		assertNoHttpTransportOverrides(options);
-		const headersOptions = withClientHeaders(
-			options,
-			clientOptions,
-			options.body,
-		);
+		const headersOptions = withClientHeaders(options, clientOptions, options.body);
 		const methodName = normalizeHttpMethod(method);
-		const retryOptions = normalizeRetryOptions(headersOptions.retry);
-		if (retryOptions) validateUnsafeRetryMethods(retryOptions);
+		const explicitRetry = headersOptions.retry !== undefined;
+		const retryOptions =
+			normalizeProxyTransportRetryOptions(headersOptions.retry, {
+				label: "HTTP",
+			}) ??
+			(explicitRetry ? undefined : createDefaultProxyTransportRetryOptions({ label: "HTTP" }));
+		if (retryOptions) validateUnsafeProxyTransportRetryMethods(retryOptions, "HTTP");
 		const retryEnabled = Boolean(
 			retryOptions &&
 				retryOptions.attempts > 1 &&
-				isMethodRetryable(methodName, retryOptions),
+				isProxyTransportRetryMethod(methodName, retryOptions),
 		);
 		const statusRetryEnabled = Boolean(
 			retryEnabled &&
+				explicitRetry &&
 				retryOptions &&
 				retryOptions.statusCodes.length > 0 &&
 				headersOptions.throwOnHttpError !== false,
 		);
-		const attemptOptions: RequestOptions & { body?: unknown } =
-			statusRetryEnabled
-				? { ...headersOptions, throwOnHttpError: false }
-				: headersOptions;
+		const attemptOptions: RequestOptions & { body?: unknown } = statusRetryEnabled
+			? { ...headersOptions, throwOnHttpError: false }
+			: headersOptions;
+
+		// Span the whole vendor chain on transport failures. Like ctx.stealth, a
+		// policy-managed proxy resolves a *different* endpoint/vendor per attempt
+		// (the flat proxyAttemptOffset rotates across the concatenated vendor pool
+		// spans), so a transport failure should advance to the next endpoint —
+		// potentially crossing into the fallback vendor — rather than stopping at
+		// the per-endpoint retry budget and stranding the request on the primary
+		// vendor. resolvePolicyTransportAttemptCap widens the cap to the 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 retry budget. Status-code retries
+		// stay bounded by the retry budget regardless; only transport rotation gets
+		// the full span.
+		const policyProxy: ProviderProxyPolicy | undefined = (() => {
+			const policy = clientOptions.proxyPolicy ?? clientOptions.upstream?.proxy;
+			return policy && typeof policy === "object" ? policy : undefined;
+		})();
+		const usesPolicyAllocator = Boolean(policyProxy) && !options.proxy && !clientOptions.proxy;
+		const transportAttemptCap = retryOptions
+			? resolvePolicyTransportAttemptCap({
+					policy: policyProxy,
+					usesPolicyAllocator,
+					retryAttempts: retryOptions.attempts,
+					explicitRetry,
+					method: methodName,
+				})
+			: 1;
 
-		const executeOnce = (): Promise<HttpResponse | HttpStatusOutcome> =>
+		// Track resolved endpoints across a policy-allocator chain. Successive
+		// attempts rotate the flat offset across the concatenated vendor pool
+		// spans, but an under-filled allocation (fewer live endpoints than the
+		// configured pool size) makes the modulo mapping repeat endpoints before
+		// the offset reaches the next vendor. Rather than re-hammering an
+		// already-tried endpoint under backoff, fetchNativeHttp returns a skip
+		// sentinel for a duplicate; the loop then advances the flat offset without
+		// issuing the request, so it keeps walking toward — and into — the fallback
+		// vendor's pool span instead of stalling on the primary vendor.
+		// De-duplication is gated on the SAME predicate that widens the attempt cap
+		// (implicit, safe-method, registry-chain rotation). It must NOT engage for
+		// an explicit retry policy: there the caller's `attempts` count is the
+		// contract and each attempt must issue against whatever endpoint it resolves
+		// — even a repeat — instead of being silently skipped (which would collapse
+		// a `poolSize: 1` + `attempts: 3` request to a single fetch).
+		const dedupeAllocatorEndpoints = policyRotatesTransportVendorChain({
+			policy: policyProxy,
+			usesPolicyAllocator,
+			explicitRetry,
+			method: methodName,
+		});
+		const dedupeContext = dedupeAllocatorEndpoints
+			? { attempted: new Set<string>() }
+			: undefined;
+
+		const executeOnce = (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> =>
 			fetchNativeHttp(
 				baseUrl,
 				url,
@@ -894,44 +544,68 @@ export function createHttpClient(
 				clientOptions,
 				warnOnce,
 				statusRetryEnabled ? retryOptions?.statusCodes : undefined,
+				proxyAttemptOffset,
+				dedupeContext,
 			);
 
 		if (!retryEnabled || !retryOptions) {
 			const outcome = await executeOnce();
+			if (isDedupeSkipOutcome(outcome)) {
+				// Single-shot path never de-duplicates (dedupeContext is undefined),
+				// but keep the union total.
+				throw new TransportError("HTTP request produced no terminal result", {
+					code: "retry_exhausted",
+				});
+			}
 			if (isHttpStatusOutcome(outcome)) {
 				throw toUpstreamHttpError(outcome.status);
 			}
 			return outcome;
 		}
 
+		let lastError: unknown;
 		let lastErrorCode: string | undefined;
 		let lastStatus: number | undefined;
-		for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+		// `attempt` walks the flat proxy offset across the full chain span; `issued`
+		// counts requests that were actually sent (skipped duplicate offsets do not
+		// increment it). Retry summaries and the status-retry budget must reflect
+		// issued requests, not the raw offset, so they stay accurate when partial
+		// allocations skip offsets.
+		let issued = 0;
+		for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+			// Whether this offset actually issued a request (vs. a skipped duplicate),
+			// so the catch counts a thrown *transport* failure once without
+			// double-counting a status outcome that already incremented before it
+			// re-threw as an upstream HTTP error.
+			let issuedThisAttempt = false;
 			try {
-				const outcome = await executeOnce();
+				const outcome = await executeOnce(attempt - 1);
+				if (isDedupeSkipOutcome(outcome)) {
+					// Duplicate endpoint from a partial allocation: advance the flat
+					// offset without issuing the request (no backoff, not a failure) so
+					// the loop keeps rotating toward the fallback vendor.
+					continue;
+				}
+				issued += 1;
+				issuedThisAttempt = true;
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
-					if (outcome.retryable && attempt < retryOptions.attempts) {
-						await sleep(
-							computeRetryDelayMs(retryOptions, attempt, outcome.headers),
-						);
+					if (outcome.retryable && issued < retryOptions.attempts) {
+						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
 						continue;
 					}
 					throw toUpstreamHttpError(outcome.status);
 				}
 
 				const response = outcome;
-				if (
-					response.status >= 400 &&
-					headersOptions.throwOnHttpError !== false
-				) {
+				if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
 					throw toUpstreamHttpError(response.status);
 				}
 
-				if (attempt > 1) {
+				if (issued > 1) {
 					const summary: HttpRetrySummary = {
-						attempts: attempt,
-						retries: attempt - 1,
+						attempts: issued,
+						retries: issued - 1,
 						...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
 						transport: "native",
 						...(lastErrorCode ? { lastErrorCode } : {}),
@@ -941,19 +615,35 @@ export function createHttpClient(
 				}
 				return response;
 			} catch (error) {
-				lastErrorCode = retryErrorCode(error);
-				lastStatus = retryErrorStatus(error);
+				if (!issuedThisAttempt) issued += 1;
+				lastError = error;
+				lastErrorCode = proxyTransportRetryErrorCode(error);
+				lastStatus = proxyTransportRetryErrorStatus(error);
+				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
 				if (
-					attempt < retryOptions.attempts &&
-					shouldRetryTransportError(error, retryOptions)
+					attempt < transportAttemptCap &&
+					shouldRetryProxyTransportAttempt({
+						error,
+						explicitRetry,
+						method: methodName,
+						options: retryOptions,
+						proxyUsed,
+					})
 				) {
-					await sleep(computeRetryDelayMs(retryOptions, attempt));
+					await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt));
 					continue;
 				}
 				throw error;
 			}
 		}
 
+		// Reached when the attempt cap is consumed without a terminal outcome —
+		// e.g. the final offsets of a partial allocation all resolved to
+		// already-tried endpoints and were skipped. Surface the last real transport
+		// failure rather than a synthetic exhaustion error.
+		if (lastError !== undefined) {
+			throw lastError;
+		}
 		throw new TransportError("HTTP retry exhausted without a terminal result", {
 			code: "retry_exhausted",
 		});
@@ -971,30 +661,17 @@ export function createHttpClient(
 			);
 		}
 		assertNoHttpTransportOverrides(options);
-		const headersOptions = withClientHeaders(
-			options,
-			clientOptions,
-			options.body,
-		);
+		const headersOptions = withClientHeaders(options, clientOptions, options.body);
 		const methodName = normalizeHttpMethod(method);
-		return fetchNativeHttpStream(
-			baseUrl,
-			url,
-			methodName,
-			headersOptions,
-			clientOptions,
-			warnOnce,
-		);
+		return fetchNativeHttpStream(baseUrl, url, methodName, headersOptions, clientOptions, warnOnce);
 	}
 
 	return {
 		request: async (url, options: RequestWithMethodOptions = {}) =>
 			request(url, options.method ?? "GET", options),
 		get: async (url, options) => request(url, "GET", options),
-		post: async (url, body, options) =>
-			request(url, "POST", { ...options, body }),
-		put: async (url, body, options) =>
-			request(url, "PUT", { ...options, body }),
+		post: async (url, body, options) => request(url, "POST", { ...options, body }),
+		put: async (url, body, options) => request(url, "PUT", { ...options, body }),
 		delete: async (url, options) => request(url, "DELETE", options),
 		stream: async (url, options: RequestWithMethodOptions = {}) =>
 			streamRequest(url, options.method ?? "GET", options),