@apifuse/provider-sdk 2.2.0-beta.7 → 2.2.0-beta.70

package/src/runtime/http.ts

@@ -1,13 +1,21 @@
 import type { ProxyResolutionOptions } from "../config/loader.js";
-import { resolveProxyConfigAsync } from "../config/loader.js";
+import {
+	policyRotatesTransportVendorChain,
+	resolvePolicyTransportAttemptCap,
+	resolveProxyConfigAsync,
+} from "../config/loader.js";
 import { ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
+	HttpAttemptContext,
 	HttpClient,
+	HttpHeadersFactory,
 	HttpMethod,
+	HttpRedirectPolicy,
 	HttpResponse,
 	HttpRetrySummary,
 	HttpStreamResponse,
+	ProviderProxyPolicy,
 	RequestOptions,
 	RequestWithMethodOptions,
 	SseMessage,
@@ -23,14 +31,91 @@ import {
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
 } from "./proxy-retry-policy.js";
-import { appendQueryParams, normalizeHttpRequestBody } from "./request-options.js";
+import {
+	httpTelemetryErrorCode,
+	type HttpTelemetrySink,
+	type HttpAttemptTelemetryEvent,
+} from "./http-telemetry.js";
+import {
+	invalidRedirectPolicy,
+	isRedirectStatus,
+	nextSameOriginRedirectHop,
+	normalizeRedirectPolicy,
+	type RedirectPolicyTransport,
+} from "./redirects.js";
+import {
+	normalizeHttpRequestBody,
+	redactSensitiveError,
+	redactSensitiveRequestError,
+	type SerializedRequestUrl,
+	serializeRequestUrl,
+} from "./request-options.js";
+
+import { startHttpTelemetry } from "./http-telemetry-guard.js";
+import { scopedHttpTelemetry } from "./http-telemetry-binding.js";
 
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
 
+function httpAttemptFailure(
+	error: unknown,
+	status?: number,
+): Omit<HttpAttemptTelemetryEvent, "ms" | "proxyUsed"> {
+	try {
+		return {
+			e: httpTelemetryErrorCode(proxyTransportRetryErrorCode(error)),
+			status: proxyTransportRetryErrorStatus(error) ?? status,
+			...(error instanceof Error
+				? {
+						diagnostics: {
+							name: error.name,
+							message: error.message,
+							...(error.cause instanceof Error
+								? { cause: { name: error.cause.name, message: error.cause.message } }
+								: {}),
+						},
+					}
+				: {}),
+		};
+	} catch {
+		return { e: "other" };
+	}
+}
+
 export type HttpClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
 	userAgent?: string;
 	onRetrySummary?: (summary: HttpRetrySummary) => void;
+	/**
+	 * Synchronous observer for HTTP attempts, retries, timeouts, status, duration,
+	 * and observed proxy use. Observer failures never change transport behavior.
+	 * All hooks and their property reads are guarded, including `onRetrySummary`
+	 * and the failure reporter. Invalid asynchronous results are ignored and never
+	 * awaited. Observer failures set the log-only `telemetryFailed` marker; the
+	 * marker and redacted error diagnostics are excluded from headers and tenant
+	 * metadata. Tenant `meta.retry` retains its existing response shape.
+	 *
+	 * After `ProviderEngine.attach`, the server wraps supported host HTTP bindings
+	 * with the request collector. The adapter preserves arguments, direct-call,
+	 * explicit `.call`/`.apply`, and unbound receivers, plus the original returned
+	 * promise, response, stream, and error. Streams and SSE are observed at headers
+	 * without consuming their bodies. SDK clients report every observed attempt
+	 * and keep any observer configured here; routing is scoped to each call.
+	 *
+	 * Binding an existing adapter reuses its identity and replaces its collector:
+	 * the latest bind receives subsequent calls, the earlier collector receives no
+	 * further calls, and in-flight calls keep the collector captured at invocation.
+	 * An opaque host invocation is one observed attempt with zero observed retries;
+	 * its undisclosed retries and proxy settings cannot be inferred, and tenant
+	 * `meta.retry` is omitted. Status, duration, and error class remain available
+	 * in logs and telemetry headers.
+	 *
+	 * Non-object bindings and objects without a callable `request`, `get`, `post`,
+	 * `put`, `delete`, `stream`, or `sse` method are left untouched, with no `http`
+	 * telemetry sibling and one process-wide warning for this reason:
+	 * `[apifuse] http telemetry not attached; reason=unsupported_binding_shape`.
+	 */
+	httpTelemetry?: HttpTelemetrySink;
+	signal?: AbortSignal;
 };
 
 type HttpStatusOutcome = {
@@ -41,19 +126,67 @@ type HttpStatusOutcome = {
 	proxyUsed: boolean;
 };
 
-type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome;
+/**
+ * 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" };
+
+type NativeHttpAttemptOutcome = HttpResponse | HttpStatusOutcome | NativeHttpSkipOutcome;
 
 type NativeHttpAttemptError = TransportError & { proxyUsed?: boolean };
 
-function isHttpStatusOutcome(
-	outcome: HttpResponse | HttpStatusOutcome,
-): outcome is HttpStatusOutcome {
+function isHttpStatusOutcome(outcome: NativeHttpAttemptOutcome): outcome is HttpStatusOutcome {
 	return "kind" in outcome && outcome.kind === "http-status";
 }
 
-async function sleep(ms: number): Promise<void> {
+function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is NativeHttpSkipOutcome {
+	return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
+
+function toAmbientCancellationError(
+	signal: AbortSignal,
+	error: unknown = signal.reason,
+): TransportError {
+	if (error instanceof TransportError && error.code === "transport_cancelled") {
+		return error;
+	}
+	return new TransportError("Request cancelled", {
+		code: "transport_cancelled",
+		status: 0,
+		retryable: false,
+		...(error !== undefined
+			? { cause: error instanceof Error ? error : new Error(String(error)) }
+			: {}),
+	});
+}
+
+function throwIfAmbientAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw toAmbientCancellationError(signal);
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	throwIfAmbientAborted(signal);
 	if (ms <= 0) return;
-	await new Promise((resolve) => setTimeout(resolve, ms));
+	if (!signal) {
+		await new Promise((resolve) => setTimeout(resolve, ms));
+		return;
+	}
+	await new Promise<void>((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(toAmbientCancellationError(signal));
+		};
+		const timer = setTimeout(() => {
+			signal.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
 }
 
 function toUpstreamHttpError(status: number): TransportError {
@@ -69,26 +202,108 @@ function hasHeader(headers: Record<string, string>, name: string): boolean {
 	return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
 
-function withClientHeaders(
-	options: RequestOptions | undefined,
+function withClientHeaderDefaults(
+	headers: Record<string, string> | undefined,
 	clientOptions: HttpClientOptions,
 	body: unknown,
-): RequestOptions {
-	const headers: Record<string, string> = {
+): Record<string, string> {
+	const merged: Record<string, string> = {
 		...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
-		...options?.headers,
+		...headers,
 	};
 
-	if (body !== undefined && !hasHeader(headers, "Content-Type")) {
-		headers["Content-Type"] = "application/json";
+	if (body !== undefined && !hasHeader(merged, "Content-Type")) {
+		merged["Content-Type"] = "application/json";
 	}
 
+	return merged;
+}
+
+function withClientHeaders(
+	options: RequestOptions | undefined,
+	clientOptions: HttpClientOptions,
+	body: unknown,
+): RequestOptions {
+	// The ambient client signal is merged into the per-request one here so every
+	// downstream read (retry loop, sleep, body consumption) sees a single signal.
+	// The header-factory branch needs it too, otherwise factory-header requests
+	// would lose ambient cancellation entirely.
+	const signal = mergeAbortSignals(clientOptions.signal, options?.signal);
+	// A header factory is resolved per issued attempt (resolveAttemptHeaders);
+	// the client defaults are applied to its output at that point.
+	if (typeof options?.headers === "function") return { ...options, signal };
 	return {
 		...options,
-		headers,
+		headers: withClientHeaderDefaults(options?.headers, clientOptions, body),
+		signal,
 	};
 }
 
+function headerFactoryFailure(message: string, cause?: unknown): TransportError {
+	// A dedicated code keeps a broken proof minter out of the retry predicate:
+	// toHttpTransportError would otherwise brand a plain throw as
+	// transport_network_error, which the default retry policy re-issues.
+	// retryable:false is explicit so the served error envelope does not
+	// advertise a deterministic signing failure as retryable, and
+	// category:provider_error keeps a provider-local minting bug out of the
+	// upstream-failure signal (status 0 would otherwise fall through the
+	// observability ladder to upstream_http / source upstream_failure).
+	return new TransportError(message, {
+		code: "http_header_factory_failed",
+		status: 0,
+		retryable: false,
+		category: "provider_error",
+		...(cause instanceof Error ? { cause } : {}),
+	});
+}
+
+function isHeaderRecord(value: unknown): value is Record<string, string> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Settle `promise`, or reject with the signal's reason as soon as it aborts, so
+// a pending header factory cannot outlive the request deadline or an ambient
+// cancellation (native fetch has not started yet, so nothing else observes them).
+function settleBeforeAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+	if (!signal) return promise;
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		// Always attach handlers: a late rejection after the abort must settle
+		// here (a no-op on the already-rejected promise), never go unhandled.
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+
+async function resolveAttemptHeaders(
+	options: RequestOptions & { body?: unknown },
+	clientOptions: HttpClientOptions,
+	attempt: () => HttpAttemptContext,
+	signal: AbortSignal | undefined,
+): Promise<Record<string, string> | undefined> {
+	const { headers } = options;
+	if (typeof headers !== "function") return headers;
+	// The per-call timeout may have fired during proxy resolution: do not start
+	// the factory at all once the request is already aborted.
+	if (signal?.aborted) throw signal.reason;
+	let minted: unknown;
+	try {
+		minted = await settleBeforeAbort(
+			Promise.resolve().then(() => headers(attempt())),
+			signal,
+		);
+	} catch (error) {
+		// An abort is classified by toHttpTransportError (cancelled / timed out).
+		if (signal?.aborted) throw error;
+		throw headerFactoryFailure("Request header factory failed", error);
+	}
+	if (!isHeaderRecord(minted)) {
+		throw headerFactoryFailure("Request header factory must return a header record");
+	}
+	return withClientHeaderDefaults(minted, clientOptions, options.body);
+}
+
 function parseHttpData(body: string, headers: Record<string, string>): unknown {
 	const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
 
@@ -107,7 +322,21 @@ function isTimeoutMessage(message: string): boolean {
 	return /\b(timed out|timeout|deadline exceeded)\b/i.test(message);
 }
 
-function toHttpTransportError(error: unknown): TransportError {
+function toHttpTransportError(
+	error: unknown,
+	ambientSignal?: AbortSignal,
+	timeoutSignal?: AbortSignal,
+): TransportError {
+	if (ambientSignal?.aborted) {
+		return toAmbientCancellationError(ambientSignal, error);
+	}
+	if (timeoutSignal?.aborted) {
+		return new TransportError("Request timed out", {
+			code: "transport_timeout",
+			status: 0,
+			...(error instanceof Error ? { cause: error } : {}),
+		});
+	}
 	if (error instanceof TransportError) {
 		if (error.code) {
 			return error;
@@ -191,9 +420,134 @@ function requireNativeResponseBody(response: Response): ReadableStream<Uint8Arra
 	return response.body;
 }
 
-function toNativeHttpStreamResponse(response: Response): HttpStreamResponse {
+function mergeAbortSignals(
+	...signals: Array<AbortSignal | null | undefined>
+): AbortSignal | undefined {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => signal != null);
+	if (activeSignals.length === 0) return undefined;
+	if (activeSignals.length === 1) return activeSignals[0];
+	return AbortSignal.any(activeSignals);
+}
+
+function cancelStreamOnAbort(
+	body: ReadableStream<Uint8Array>,
+	signal: AbortSignal | undefined,
+): ReadableStream<Uint8Array> {
+	if (!signal) return body;
+
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	let finished = false;
+	let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+	const cleanup = () => signal.removeEventListener("abort", onAbort);
+	const onAbort = () => {
+		if (finished) return;
+		finished = true;
+		cleanup();
+		const reason = toAmbientCancellationError(signal);
+		streamController?.error(reason);
+		const cancellation = reader ? reader.cancel(reason) : body.cancel(reason);
+		void cancellation.catch(() => undefined).finally(() => reader?.releaseLock());
+	};
+
+	return new ReadableStream<Uint8Array>(
+		{
+			start(controller) {
+				streamController = controller;
+				signal.addEventListener("abort", onAbort, { once: true });
+				if (signal.aborted) onAbort();
+			},
+			async pull(controller) {
+				try {
+					reader ??= body.getReader();
+					const chunk = await reader.read();
+					if (finished) return;
+					if (chunk.done) {
+						finished = true;
+						cleanup();
+						controller.close();
+						reader.releaseLock();
+						return;
+					}
+					controller.enqueue(chunk.value);
+				} catch (error) {
+					if (finished) return;
+					finished = true;
+					cleanup();
+					controller.error(error);
+					reader?.releaseLock();
+				}
+			},
+			async cancel(reason) {
+				if (finished) return;
+				finished = true;
+				cleanup();
+				try {
+					await (reader ? reader.cancel(reason) : body.cancel(reason));
+				} finally {
+					reader?.releaseLock();
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+}
+
+function sanitizeStreamErrors(
+	body: ReadableStream<Uint8Array>,
+	serializedUrl: SerializedRequestUrl,
+): ReadableStream<Uint8Array> {
+	if (serializedUrl.sensitiveValues.length === 0) return body;
+
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	return new ReadableStream<Uint8Array>(
+		{
+			async pull(controller) {
+				try {
+					reader ??= body.getReader();
+					const chunk = await reader.read();
+					if (chunk.done) {
+						controller.close();
+						return;
+					}
+					controller.enqueue(chunk.value);
+				} catch (error) {
+					controller.error(
+						redactSensitiveError(
+							error,
+							serializedUrl.sensitiveValues,
+							serializedUrl.requestUrl,
+							serializedUrl.redactedUrl,
+						),
+					);
+				}
+			},
+			async cancel(reason) {
+				try {
+					await (reader ? reader.cancel(reason) : body.cancel(reason));
+				} catch (error) {
+					throw redactSensitiveError(
+						error,
+						serializedUrl.sensitiveValues,
+						serializedUrl.requestUrl,
+						serializedUrl.redactedUrl,
+					);
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+}
+
+function toNativeHttpStreamResponse(
+	response: Response,
+	serializedUrl: SerializedRequestUrl,
+	signal?: AbortSignal,
+): HttpStreamResponse {
 	const headers = Object.fromEntries(response.headers.entries());
-	const body = requireNativeResponseBody(response);
+	const body = sanitizeStreamErrors(
+		cancelStreamOnAbort(requireNativeResponseBody(response), signal),
+		serializedUrl,
+	);
 	return {
 		body,
 		headers,
@@ -205,7 +559,7 @@ function toNativeHttpStreamResponse(response: Response): HttpStreamResponse {
 	};
 }
 
-function normalizeHttpMethod(method: string): HttpMethod {
+function normalizeHttpMethod(method: string): Uppercase<HttpMethod> {
 	switch (method.toUpperCase()) {
 		case "HEAD":
 			return "HEAD";
@@ -230,7 +584,8 @@ function normalizeHttpMethod(method: string): HttpMethod {
 	}
 }
 
-function isAbsoluteUrl(url: string): boolean {
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export function isAbsoluteUrl(url: string): boolean {
 	return /^[a-z][a-z\d+\-.]*:/i.test(url);
 }
 
@@ -240,6 +595,105 @@ function resolveHttpUrl(baseUrl: string | undefined, url: string): string {
 
 type NativeFetchInit = RequestInit & { proxy?: string };
 
+const MAX_HTTP_REDIRECT_HOPS = 20;
+const HTTP_REDIRECT_POLICY_TRANSPORT: RedirectPolicyTransport = {
+	label: "ctx.http",
+	maxHops: MAX_HTTP_REDIRECT_HOPS,
+};
+const REDIRECT_BODY_HEADERS = new Set([
+	"content-encoding",
+	"content-language",
+	"content-location",
+	"content-type",
+]);
+
+function snapshotHttpRedirectPolicy(options: RequestOptions): HttpRedirectPolicy | undefined {
+	try {
+		return normalizeRedirectPolicy(options.redirectPolicy, HTTP_REDIRECT_POLICY_TRANSPORT);
+	} catch (error) {
+		if (error instanceof TransportError) throw error;
+		throw invalidRedirectPolicy(
+			HTTP_REDIRECT_POLICY_TRANSPORT,
+			"could not be read safely",
+			error instanceof Error ? error : undefined,
+		);
+	}
+}
+
+function withoutRedirectBodyHeaders(headers: HeadersInit | undefined): Headers {
+	const nextHeaders = new Headers(headers);
+	for (const name of REDIRECT_BODY_HEADERS) nextHeaders.delete(name);
+	return nextHeaders;
+}
+
+function discardRedirectResponseBody(response: Response): void {
+	try {
+		const cancellation = response.body?.cancel();
+		if (cancellation) void cancellation.catch(() => undefined);
+	} catch {
+		// The redirect decision is security-significant and must not be replaced
+		// or delayed by an upstream body's cancellation failure. Cancellation was
+		// attempted; redirect evaluation continues without awaiting its completion.
+	}
+}
+
+async function fetchWithHttpRedirectPolicy(
+	requestUrl: string,
+	requestInit: NativeFetchInit,
+	policy: HttpRedirectPolicy | undefined,
+): Promise<Response> {
+	if (!policy) return fetch(requestUrl, requestInit);
+
+	const initialUrl = new URL(requestUrl);
+	if (initialUrl.protocol !== "http:" && initialUrl.protocol !== "https:") {
+		throw new TransportError("ctx.http redirectPolicy requires an HTTP(S) origin", {
+			code: "transport_invalid_url",
+		});
+	}
+
+	const initialOrigin = initialUrl.origin;
+	let currentUrl = requestUrl;
+	let method = normalizeHttpMethod(requestInit.method ?? "GET");
+	let body = requestInit.body;
+	let headers = requestInit.headers;
+	let followedHops = 0;
+	const visitedRequests = new Set([`${method} ${currentUrl}`]);
+
+	while (true) {
+		const response = await fetch(currentUrl, {
+			...requestInit,
+			body,
+			headers,
+			method,
+			redirect: "manual",
+		});
+		if (!isRedirectStatus(response.status)) return response;
+
+		const location = response.headers.get("location");
+		discardRedirectResponseBody(response);
+		const decision = nextSameOriginRedirectHop({
+			policy,
+			initialOrigin,
+			currentUrl,
+			responseUrl: currentUrl,
+			status: response.status,
+			method,
+			location: location ?? undefined,
+			followedHops,
+			visitedRequests,
+		});
+		if (decision.nextMethod !== method) {
+			body = undefined;
+			headers = withoutRedirectBodyHeaders(headers);
+		}
+
+		method = decision.nextMethod;
+		currentUrl = decision.nextUrl;
+		followedHops += 1;
+		visitedRequests.add(`${method} ${currentUrl}`);
+	}
+}
+
 async function resolveNativeProxy(
 	options: RequestOptions,
 	clientOptions: HttpClientOptions,
@@ -249,14 +703,17 @@ async function resolveNativeProxy(
 	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,
+		engineCredentials: clientOptions.engineCredentials,
 	});
 	if (resolvedProxy.shouldWarn) {
 		warn(
@@ -285,37 +742,91 @@ function normalizeNativeFetchBody(body: unknown): string | ArrayBuffer | undefin
 	return copied.buffer;
 }
 
+function serializeHttpRequestUrl(
+	baseUrl: string | undefined,
+	url: string,
+	options: RequestOptions,
+): SerializedRequestUrl {
+	try {
+		return serializeRequestUrl(
+			resolveHttpUrl(baseUrl, url),
+			options.params,
+			options.sensitiveParams,
+		);
+	} catch (error) {
+		throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+	}
+}
+
 async function fetchNativeHttp(
 	baseUrl: string | undefined,
 	url: string,
-	method: HttpMethod,
+	method: Uppercase<HttpMethod>,
 	options: RequestOptions & { body?: unknown },
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
 	statusRetryCodes?: readonly number[],
 	proxyAttemptOffset = 0,
+	dedupe?: { attempted: Set<string> },
+	observeProxy?: (used: boolean, status?: number) => void,
+	nextHeaderAttempt: () => number = () => 1,
 ): Promise<NativeHttpAttemptOutcome> {
-	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
+	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
+	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
-	const timeoutHandle = options.timeout
+	const signal = mergeAbortSignals(options.signal, controller?.signal);
+	let timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
+	const disarmTimeout = () => {
+		if (!timeoutHandle) return;
+		clearTimeout(timeoutHandle);
+		timeoutHandle = undefined;
+	};
 
 	let proxy: string | undefined;
 	try {
+		throwIfAmbientAborted(options.signal);
+		// 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);
+		observeProxy?.(Boolean(proxy));
+		throwIfAmbientAborted(options.signal);
+		// 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);
+		}
+		// Resolve after the dedupe check so a skipped duplicate offset never burns
+		// a single-use proof, and with the serialized URL so URL-bound proofs
+		// match what is actually issued.
+		const requestHeaders = await resolveAttemptHeaders(
+			options,
+			clientOptions,
+			() => ({ attempt: nextHeaderAttempt(), url: requestUrl, method }),
+			signal,
+		);
 		const requestInit: NativeFetchInit = {
-			headers: options.headers,
+			headers: requestHeaders,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
 		}
-		const response = await fetch(requestUrl, {
-			...requestInit,
-		});
+		const response = await fetchWithHttpRedirectPolicy(
+			requestUrl,
+			requestInit,
+			options.redirectPolicy,
+		);
+		observeProxy?.(Boolean(proxy), response.status);
 		const headers = Object.fromEntries(response.headers.entries());
 
 		if (statusRetryCodes && response.status >= 400) {
@@ -337,47 +848,80 @@ async function fetchNativeHttp(
 			});
 		}
 
-		return toNativeHttpResponse(response);
+		// `timeout` bounds the header phase (types.ts RequestOptions.timeout), so it
+		// is disarmed before the body is read: awaiting the buffered body inside
+		// this try brands a mid-body failure as a transport error, but must not
+		// extend the deadline over the download. Cancellation still applies —
+		// `signal` stays attached to the native response. The discarded non-2xx
+		// bodies drained above stay under the deadline on purpose: nothing else
+		// bounds them, and their content is never returned to the caller.
+		disarmTimeout();
+		return await toNativeHttpResponse(response);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
-			throw error;
+			throw redactSensitiveError(
+				error,
+				serializedUrl.sensitiveValues,
+				serializedUrl.requestUrl,
+				serializedUrl.redactedUrl,
+			);
 		}
-		const transportError = toHttpTransportError(error) as NativeHttpAttemptError;
+		const transportError: NativeHttpAttemptError = redactSensitiveError(
+			toHttpTransportError(error, options.signal, controller?.signal),
+			serializedUrl.sensitiveValues,
+			serializedUrl.requestUrl,
+			serializedUrl.redactedUrl,
+		);
 		transportError.proxyUsed = Boolean(proxy);
 		throw transportError;
 	} finally {
-		if (timeoutHandle) clearTimeout(timeoutHandle);
+		disarmTimeout();
 	}
 }
 
 async function fetchNativeHttpStream(
 	baseUrl: string | undefined,
 	url: string,
-	method: HttpMethod,
+	method: Uppercase<HttpMethod>,
 	options: RequestOptions & { body?: unknown },
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
+	observeProxy?: (used: boolean) => void,
 ): Promise<HttpStreamResponse> {
-	const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
+	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
+	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
+	const signal = mergeAbortSignals(options.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	try {
+		throwIfAmbientAborted(options.signal);
 		const proxy = await resolveNativeProxy(options, clientOptions, warn);
+		observeProxy?.(Boolean(proxy));
+		throwIfAmbientAborted(options.signal);
+		// Streams never retry: a header factory is resolved once, as attempt 1.
+		const headers = await resolveAttemptHeaders(
+			options,
+			clientOptions,
+			() => ({ attempt: 1, url: requestUrl, method }),
+			signal,
+		);
 		const requestInit: NativeFetchInit = {
-			headers: options.headers,
+			headers,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
 		}
-		const response = await fetch(requestUrl, {
-			...requestInit,
-		});
+		const response = await fetchWithHttpRedirectPolicy(
+			requestUrl,
+			requestInit,
+			options.redirectPolicy,
+		);
 
 		if (response.status >= 400 && options.throwOnHttpError !== false) {
 			await drainNativeResponseBody(response);
@@ -387,12 +931,24 @@ async function fetchNativeHttpStream(
 			});
 		}
 
-		return toNativeHttpStreamResponse(response);
+		// The stream timeout remains header-scoped; composed ambient and local
+		// cancellation stays attached to native fetch for the body's full lifetime.
+		return toNativeHttpStreamResponse(response, serializedUrl, options.signal);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
-			throw error;
+			throw redactSensitiveError(
+				error,
+				serializedUrl.sensitiveValues,
+				serializedUrl.requestUrl,
+				serializedUrl.redactedUrl,
+			);
 		}
-		throw toHttpTransportError(error);
+		throw redactSensitiveError(
+			toHttpTransportError(error, options.signal, controller?.signal),
+			serializedUrl.sensitiveValues,
+			serializedUrl.requestUrl,
+			serializedUrl.redactedUrl,
+		);
 	} finally {
 		if (timeoutHandle) clearTimeout(timeoutHandle);
 	}
@@ -417,113 +973,257 @@ export function createHttpClient(
 		method: string,
 		options: RequestOptions & { body?: unknown } = {},
 	): Promise<HttpResponse> {
-		if (!baseUrl && !isAbsoluteUrl(url)) {
-			throw new TransportError(
-				"ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared",
-				{ code: "transport_invalid_url" },
-			);
-		}
-		assertNoHttpTransportOverrides(options);
-		const headersOptions = withClientHeaders(options, clientOptions, options.body);
-		const methodName = normalizeHttpMethod(method);
-		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 &&
-				isProxyTransportRetryMethod(methodName, retryOptions),
-		);
-		const statusRetryEnabled = Boolean(
-			retryEnabled &&
-				explicitRetry &&
-				retryOptions &&
-				retryOptions.statusCodes.length > 0 &&
-				headersOptions.throwOnHttpError !== false,
+		const { explicitRetry, headersOptions, methodName, retryOptions } = (() => {
+			try {
+				if (!baseUrl && !isAbsoluteUrl(url)) {
+					throw new TransportError(
+						"ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared",
+						{ code: "transport_invalid_url" },
+					);
+				}
+				assertNoHttpTransportOverrides(options);
+				const redirectPolicy = snapshotHttpRedirectPolicy(options);
+				const headersOptions = {
+					...withClientHeaders(options, clientOptions, options.body),
+					redirectPolicy,
+				};
+				const methodName = normalizeHttpMethod(method);
+				const explicitRetry = headersOptions.retry !== undefined;
+				const retryOptions =
+					normalizeProxyTransportRetryOptions(headersOptions.retry, {
+						label: "HTTP",
+					}) ??
+					(explicitRetry ? undefined : createDefaultProxyTransportRetryOptions({ label: "HTTP" }));
+				if (retryOptions) validateUnsafeProxyTransportRetryMethods(retryOptions, "HTTP");
+				return { explicitRetry, headersOptions, methodName, retryOptions };
+			} catch (error) {
+				throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+			}
+		})();
+		const requestStarted = performance.now();
+		const telemetry = startHttpTelemetry(
+			scopedHttpTelemetry(clientOptions.httpTelemetry),
+			retryOptions?.preset,
 		);
-		const attemptOptions: RequestOptions & { body?: unknown } = statusRetryEnabled
-			? { ...headersOptions, throwOnHttpError: false }
-			: headersOptions;
+		try {
+			return await runRequest();
+		} finally {
+			telemetry.finish(performance.now() - requestStarted);
+		}
 
-		const executeOnce = (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> =>
-			fetchNativeHttp(
-				baseUrl,
-				url,
-				methodName,
-				attemptOptions,
-				clientOptions,
-				warnOnce,
-				statusRetryEnabled ? retryOptions?.statusCodes : undefined,
-				proxyAttemptOffset,
+		async function runRequest(): Promise<HttpResponse> {
+			const retryEnabled = Boolean(
+				retryOptions &&
+					retryOptions.attempts > 1 &&
+					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;
 
-		if (!retryEnabled || !retryOptions) {
-			const outcome = await executeOnce();
-			if (isHttpStatusOutcome(outcome)) {
-				throw toUpstreamHttpError(outcome.status);
-			}
-			return outcome;
-		}
+			// 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;
 
-		let lastErrorCode: string | undefined;
-		let lastStatus: number | undefined;
-		for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
-			try {
-				const outcome = await executeOnce(attempt - 1);
+			// 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;
+
+			// Numbers the attempts a header factory sees: only requests that reached
+			// header resolution count, so a failed proxy allocation (which increments
+			// the telemetry `issued` count below) or a dedupe-skipped offset does not
+			// make the first request that is actually built report `attempt: 2`.
+			let headerAttempts = 0;
+			const nextHeaderAttempt = () => {
+				headerAttempts += 1;
+				return headerAttempts;
+			};
+
+			const executeOnce = async (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> => {
+				const started = performance.now();
+				let proxyUsed = false;
+				let observedStatus: number | undefined;
+				const record = (event: Omit<HttpAttemptTelemetryEvent, "ms" | "proxyUsed">) => {
+					telemetry.recordAttempt({ ...event, ms: performance.now() - started, proxyUsed });
+				};
+				try {
+					const outcome = await fetchNativeHttp(
+						baseUrl,
+						url,
+						methodName,
+						attemptOptions,
+						clientOptions,
+						warnOnce,
+						statusRetryEnabled ? retryOptions?.statusCodes : undefined,
+						proxyAttemptOffset,
+						dedupeContext,
+						(used, status) => {
+							proxyUsed = used;
+							observedStatus = status;
+						},
+						nextHeaderAttempt,
+					);
+					if (!isDedupeSkipOutcome(outcome))
+						record({
+							status: outcome.status,
+							...(isHttpStatusOutcome(outcome)
+								? { e: "upstream_http_error", statusRetry: true }
+								: {}),
+						});
+					return outcome;
+				} catch (error) {
+					// Record before the retry loop can catch/rethrow a terminal status.
+					record(httpAttemptFailure(error, observedStatus));
+					throw error;
+				}
+			};
+
+			if (!retryEnabled || !retryOptions) {
+				throwIfAmbientAborted(headersOptions.signal);
+				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)) {
-					lastStatus = outcome.status;
-					if (outcome.retryable && attempt < retryOptions.attempts) {
-						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
-						continue;
-					}
 					throw toUpstreamHttpError(outcome.status);
 				}
+				return outcome;
+			}
 
-				const response = outcome;
-				if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
-					throw toUpstreamHttpError(response.status);
-				}
+			let lastError: unknown;
+			// `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) {
+				throwIfAmbientAborted(headersOptions.signal);
+				// 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(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)) {
+						if (outcome.retryable && issued < retryOptions.attempts) {
+							await sleep(
+								computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers),
+								headersOptions.signal,
+							);
+							continue;
+						}
+						throw toUpstreamHttpError(outcome.status);
+					}
 
-				if (attempt > 1) {
-					const summary: HttpRetrySummary = {
-						attempts: attempt,
-						retries: attempt - 1,
-						...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
-						transport: "native",
-						...(lastErrorCode ? { lastErrorCode } : {}),
-						...(lastStatus ? { lastStatus } : {}),
-					};
-					clientOptions.onRetrySummary?.(summary);
-				}
-				return response;
-			} catch (error) {
-				lastErrorCode = proxyTransportRetryErrorCode(error);
-				lastStatus = proxyTransportRetryErrorStatus(error);
-				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
-				if (
-					attempt < retryOptions.attempts &&
-					shouldRetryProxyTransportAttempt({
-						error,
-						explicitRetry,
-						method: methodName,
-						options: retryOptions,
-						proxyUsed,
-					})
-				) {
-					await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt));
-					continue;
+					const response = outcome;
+					if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
+						throw toUpstreamHttpError(response.status);
+					}
+
+					if (issued > 1) {
+						const summary = telemetry.toTenantRetryPayload();
+						if (summary) telemetry.observe(() => clientOptions.onRetrySummary?.(summary));
+					}
+					return response;
+				} catch (error) {
+					throwIfAmbientAborted(headersOptions.signal);
+					if (!issuedThisAttempt) issued += 1;
+					lastError = error;
+					const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
+					if (
+						attempt < transportAttemptCap &&
+						shouldRetryProxyTransportAttempt({
+							error,
+							explicitRetry,
+							method: methodName,
+							options: retryOptions,
+							proxyUsed,
+						})
+					) {
+						await sleep(
+							computeProxyTransportRetryDelayMs(retryOptions, attempt),
+							headersOptions.signal,
+						);
+						continue;
+					}
+					throw error;
 				}
-				throw error;
 			}
-		}
 
-		throw new TransportError("HTTP retry exhausted without a terminal result", {
-			code: "retry_exhausted",
-		});
+			// 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",
+			});
+		}
 	}
 
 	async function streamRequest(
@@ -531,16 +1231,56 @@ export function createHttpClient(
 		method: string,
 		options: RequestOptions & { body?: unknown } = {},
 	): Promise<HttpStreamResponse> {
-		if (!baseUrl && !isAbsoluteUrl(url)) {
-			throw new TransportError(
-				"ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared",
-				{ code: "transport_invalid_url" },
+		const { headersOptions, methodName } = (() => {
+			try {
+				if (!baseUrl && !isAbsoluteUrl(url)) {
+					throw new TransportError(
+						"ctx.http requires an absolute URL when provider.upstream.baseUrl is not declared",
+						{ code: "transport_invalid_url" },
+					);
+				}
+				assertNoHttpTransportOverrides(options);
+				const redirectPolicy = snapshotHttpRedirectPolicy(options);
+				return {
+					headersOptions: {
+						...withClientHeaders(options, clientOptions, options.body),
+						redirectPolicy,
+					},
+					methodName: normalizeHttpMethod(method),
+				};
+			} catch (error) {
+				throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+			}
+		})();
+		// Streams never retry. Observe the header fetch without consuming its body.
+		const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), "off");
+		const started = performance.now();
+		const alreadyAborted = headersOptions.signal?.aborted === true;
+		let proxyUsed = false;
+		const record = (event: Omit<HttpAttemptTelemetryEvent, "ms" | "proxyUsed">) => {
+			if (alreadyAborted) return;
+			telemetry.recordAttempt({ ...event, ms: performance.now() - started, proxyUsed });
+		};
+		try {
+			const response = await fetchNativeHttpStream(
+				baseUrl,
+				url,
+				methodName,
+				headersOptions,
+				clientOptions,
+				warnOnce,
+				(used) => {
+					proxyUsed = used;
+				},
 			);
+			record({ status: response.status });
+			return response;
+		} catch (error) {
+			record(httpAttemptFailure(error));
+			throw error;
+		} finally {
+			telemetry.finish(performance.now() - started);
 		}
-		assertNoHttpTransportOverrides(options);
-		const headersOptions = withClientHeaders(options, clientOptions, options.body);
-		const methodName = normalizeHttpMethod(method);
-		return fetchNativeHttpStream(baseUrl, url, methodName, headersOptions, clientOptions, warnOnce);
 	}
 
 	return {
@@ -556,10 +1296,16 @@ export function createHttpClient(
 			url,
 			options: RequestWithMethodOptions = {},
 		): Promise<AsyncIterable<SseMessage>> => {
-			const headers = {
-				Accept: "text/event-stream",
-				...options.headers,
-			};
+			const callerHeaders = options.headers;
+			const headers: Record<string, string> | HttpHeadersFactory =
+				typeof callerHeaders === "function"
+					? async (attempt) => {
+							// Pass a malformed result through unchanged so the factory
+							// validation rejects it instead of spreading it into `{}`.
+							const minted = await callerHeaders(attempt);
+							return isHeaderRecord(minted) ? { Accept: "text/event-stream", ...minted } : minted;
+						}
+					: { Accept: "text/event-stream", ...callerHeaders };
 			const response = await streamRequest(url, options.method ?? "GET", {
 				...options,
 				headers,