@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.63

package/src/runtime/http.ts

@@ -7,7 +7,9 @@ import {
 import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
+	HttpAttemptContext,
 	HttpClient,
+	HttpHeadersFactory,
 	HttpMethod,
 	HttpRedirectPolicy,
 	HttpResponse,
@@ -29,6 +31,11 @@ import {
 	shouldRetryProxyTransportAttempt,
 	validateUnsafeProxyTransportRetryMethods,
 } from "./proxy-retry-policy.js";
+import {
+	httpTelemetryErrorCode,
+	type HttpTelemetrySink,
+	type HttpAttemptTelemetryEvent,
+} from "./http-telemetry.js";
 import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } from "./redirects.js";
 import {
 	normalizeHttpRequestBody,
@@ -38,12 +45,70 @@ import {
 	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;
 };
 
@@ -131,26 +196,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"];
 
@@ -406,7 +553,7 @@ function toNativeHttpStreamResponse(
 	};
 }
 
-function normalizeHttpMethod(method: string): HttpMethod {
+function normalizeHttpMethod(method: string): Uppercase<HttpMethod> {
 	switch (method.toUpperCase()) {
 		case "HEAD":
 			return "HEAD";
@@ -615,7 +762,7 @@ async function fetchWithHttpRedirectPolicy(
 						return `Redirect loop refused target ${target}`;
 					case "missing_location":
 						return `Redirect response from ${redirectDiagnosticTarget(currentUrl)} is missing Location`;
-			}
+				}
 			})();
 			throw new HttpRedirectError(message, {
 				reason: decision.reason,
@@ -702,30 +849,38 @@ function serializeHttpRequestUrl(
 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 serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
-	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
-	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(clientOptions.signal);
+		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);
-		throwIfAmbientAborted(clientOptions.signal);
+		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
@@ -736,8 +891,17 @@ async function fetchNativeHttp(
 			}
 			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 ? { signal } : {}),
@@ -750,6 +914,7 @@ async function fetchNativeHttp(
 			requestInit,
 			options.redirectPolicy,
 		);
+		observeProxy?.(Boolean(proxy), response.status);
 		const headers = Object.fromEntries(response.headers.entries());
 
 		if (statusRetryCodes && response.status >= 400) {
@@ -771,7 +936,15 @@ 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 redactSensitiveError(
@@ -782,7 +955,7 @@ async function fetchNativeHttp(
 			);
 		}
 		const transportError: NativeHttpAttemptError = redactSensitiveError(
-			toHttpTransportError(error, clientOptions.signal, controller?.signal),
+			toHttpTransportError(error, options.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -790,32 +963,41 @@ async function fetchNativeHttp(
 		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 serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
-	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
+	const signal = mergeAbortSignals(options.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	try {
-		throwIfAmbientAborted(clientOptions.signal);
+		throwIfAmbientAborted(options.signal);
 		const proxy = await resolveNativeProxy(options, clientOptions, warn);
-		throwIfAmbientAborted(clientOptions.signal);
+		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 ? { signal } : {}),
@@ -837,9 +1019,9 @@ async function fetchNativeHttpStream(
 			});
 		}
 
-		// Per-call timeout remains header-scoped, while the ambient request signal
-		// stays attached to the response body for its full consumption lifetime.
-		return toNativeHttpStreamResponse(response, serializedUrl, clientOptions.signal);
+		// 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 redactSensitiveError(
@@ -850,7 +1032,7 @@ async function fetchNativeHttpStream(
 			);
 		}
 		throw redactSensitiveError(
-			toHttpTransportError(error, clientOptions.signal, controller?.signal),
+			toHttpTransportError(error, options.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -906,193 +1088,230 @@ export function createHttpClient(
 				throw redactSensitiveRequestError(error, url, options.sensitiveParams);
 			}
 		})();
-		const retryEnabled = Boolean(
-			retryOptions &&
-				retryOptions.attempts > 1 &&
-				isProxyTransportRetryMethod(methodName, retryOptions),
+		const requestStarted = performance.now();
+		const telemetry = startHttpTelemetry(
+			scopedHttpTelemetry(clientOptions.httpTelemetry),
+			retryOptions?.preset,
 		);
-		const statusRetryEnabled = Boolean(
-			retryEnabled &&
-				explicitRetry &&
-				retryOptions &&
-				retryOptions.statusCodes.length > 0 &&
-				headersOptions.throwOnHttpError !== false,
-		);
-		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;
-
-		// 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;
+		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,
-				dedupeContext,
+		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;
+
+			// 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;
+
+			// 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;
+			};
 
-		if (!retryEnabled || !retryOptions) {
-			throwIfAmbientAborted(clientOptions.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)) {
-				throw toUpstreamHttpError(outcome.status);
-			}
-			return outcome;
-		}
+			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;
+				}
+			};
 
-		let lastError: unknown;
-		let lastErrorCode: string | undefined;
-		let lastStatus: number | undefined;
-		// `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(clientOptions.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 (!retryEnabled || !retryOptions) {
+				throwIfAmbientAborted(headersOptions.signal);
+				const outcome = await executeOnce();
 				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;
+					// 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",
+					});
 				}
-				issued += 1;
-				issuedThisAttempt = true;
 				if (isHttpStatusOutcome(outcome)) {
-					lastStatus = outcome.status;
-					if (outcome.retryable && issued < retryOptions.attempts) {
-						await sleep(
-							computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers),
-							clientOptions.signal,
-						);
-						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 (issued > 1) {
-					const summary: HttpRetrySummary = {
-						attempts: issued,
-						retries: issued - 1,
-						...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
-						transport: "native",
-						...(lastErrorCode ? { lastErrorCode } : {}),
-						...(lastStatus ? { lastStatus } : {}),
-					};
-					clientOptions.onRetrySummary?.(summary);
-				}
-				return response;
-			} catch (error) {
-				throwIfAmbientAborted(clientOptions.signal);
-				if (!issuedThisAttempt) issued += 1;
-				lastError = error;
-				lastErrorCode = proxyTransportRetryErrorCode(error);
-				lastStatus = proxyTransportRetryErrorStatus(error);
-				const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
-				if (
-					attempt < transportAttemptCap &&
-					shouldRetryProxyTransportAttempt({
-						error,
-						explicitRetry,
-						method: methodName,
-						options: retryOptions,
-						proxyUsed,
-					})
-				) {
-					await sleep(
-						computeProxyTransportRetryDelayMs(retryOptions, attempt),
-						clientOptions.signal,
-					);
-					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;
 			}
-		}
 
-		// 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;
+			// 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",
+			});
 		}
-		throw new TransportError("HTTP retry exhausted without a terminal result", {
-			code: "retry_exhausted",
-		});
 	}
 
 	async function streamRequest(
@@ -1121,7 +1340,35 @@ export function createHttpClient(
 				throw redactSensitiveRequestError(error, url, options.sensitiveParams);
 			}
 		})();
-		return fetchNativeHttpStream(baseUrl, url, methodName, headersOptions, clientOptions, warnOnce);
+		// 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);
+		}
 	}
 
 	return {
@@ -1137,10 +1384,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,