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

package/dist/runtime/http.js

@@ -1,16 +1,77 @@
-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 { computeProxyAttemptIndex, computeProxyTransportRetryDelayMs, createDefaultProxyTransportRetryOptions, isProxyTransportRetryMethod, normalizeProxyTransportRetryOptions, proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, shouldRetryProxyTransportAttempt, validateUnsafeProxyTransportRetryMethods, } from "./proxy-retry-policy.js";
-import { appendQueryParams, normalizeHttpRequestBody } from "./request-options.js";
+import { httpTelemetryErrorCode, } from "./http-telemetry.js";
+import { invalidRedirectPolicy, isRedirectStatus, nextSameOriginRedirectHop, normalizeRedirectPolicy, } from "./redirects.js";
+import { normalizeHttpRequestBody, redactSensitiveError, redactSensitiveRequestError, 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, status) {
+    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" };
+    }
+}
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
-async function sleep(ms) {
+function isDedupeSkipOutcome(outcome) {
+    return "kind" in outcome && outcome.kind === "dedupe-skip";
+}
+function toAmbientCancellationError(signal, error = signal.reason) {
+    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) {
+    if (signal?.aborted)
+        throw toAmbientCancellationError(signal);
+}
+async function sleep(ms, signal) {
+    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((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) {
     return new TransportError(`Upstream request failed with status ${status}`, {
@@ -23,19 +84,92 @@ function hasHeader(headers, name) {
     const needle = name.toLowerCase();
     return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
-function withClientHeaders(options, clientOptions, body) {
-    const headers = {
+function withClientHeaderDefaults(headers, clientOptions, body) {
+    const merged = {
         ...(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, clientOptions, body) {
+    // 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, cause) {
+    // 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) {
+    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(promise, signal) {
+    if (!signal)
+        return promise;
+    return new Promise((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, clientOptions, attempt, signal) {
+    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;
+    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, headers) {
     const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
     if (contentType?.includes("application/json")) {
@@ -49,7 +183,17 @@ function parseJson(body) {
 function isTimeoutMessage(message) {
     return /\b(timed out|timeout|deadline exceeded)\b/i.test(message);
 }
-function toHttpTransportError(error) {
+function toHttpTransportError(error, ambientSignal, timeoutSignal) {
+    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;
@@ -121,9 +265,108 @@ function requireNativeResponseBody(response) {
     }
     return response.body;
 }
-function toNativeHttpStreamResponse(response) {
+function mergeAbortSignals(...signals) {
+    const activeSignals = signals.filter((signal) => signal != null);
+    if (activeSignals.length === 0)
+        return undefined;
+    if (activeSignals.length === 1)
+        return activeSignals[0];
+    return AbortSignal.any(activeSignals);
+}
+function cancelStreamOnAbort(body, signal) {
+    if (!signal)
+        return body;
+    let reader;
+    let finished = false;
+    let streamController;
+    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({
+        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, serializedUrl) {
+    if (serializedUrl.sensitiveValues.length === 0)
+        return body;
+    let reader;
+    return new ReadableStream({
+        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, serializedUrl, signal) {
     const headers = Object.fromEntries(response.headers.entries());
-    const body = requireNativeResponseBody(response);
+    const body = sanitizeStreamErrors(cancelStreamOnAbort(requireNativeResponseBody(response), signal), serializedUrl);
     return {
         body,
         headers,
@@ -158,24 +401,116 @@ function normalizeHttpMethod(method) {
             });
     }
 }
-function isAbsoluteUrl(url) {
+/** Whether `url` carries its own scheme, so it needs no `upstream.baseUrl` to resolve. */
+export function isAbsoluteUrl(url) {
     return /^[a-z][a-z\d+\-.]*:/i.test(url);
 }
 function resolveHttpUrl(baseUrl, url) {
     return new URL(url, baseUrl ?? DEFAULT_HTTP_BASE_URL).toString();
 }
+const MAX_HTTP_REDIRECT_HOPS = 20;
+const HTTP_REDIRECT_POLICY_TRANSPORT = {
+    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) {
+    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) {
+    const nextHeaders = new Headers(headers);
+    for (const name of REDIRECT_BODY_HEADERS)
+        nextHeaders.delete(name);
+    return nextHeaders;
+}
+function discardRedirectResponseBody(response) {
+    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, requestInit, policy) {
+    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, clientOptions, warn, proxyAttemptOffset = 0) {
     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("[provider-sdk] Provider requested proxy routing, but no proxy URL was configured. Continuing without proxy.");
@@ -196,27 +531,62 @@ function normalizeNativeFetchBody(body) {
     copied.set(normalized);
     return copied.buffer;
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0) {
-    const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
+function serializeHttpRequestUrl(baseUrl, url, options) {
+    try {
+        return serializeRequestUrl(resolveHttpUrl(baseUrl, url), options.params, options.sensitiveParams);
+    }
+    catch (error) {
+        throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+    }
+}
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe, observeProxy, nextHeaderAttempt = () => 1) {
+    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;
     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 = {
-            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) {
             await drainNativeResponseBody(response);
@@ -235,41 +605,53 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
                 status: response.status,
             });
         }
-        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);
+        const transportError = 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, url, method, options, clientOptions, warn) {
-    const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
+async function fetchNativeHttpStream(baseUrl, url, method, options, clientOptions, warn, observeProxy) {
+    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 = {
-            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);
             throw new TransportError(`Upstream request failed with status ${response.status}`, {
@@ -277,13 +659,15 @@ async function fetchNativeHttpStream(baseUrl, url, method, options, clientOption
                 status: response.status,
             });
         }
-        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)
@@ -301,98 +685,268 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         warn(message);
     };
     async function request(url, method, options = {}) {
-        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 attemptOptions = statusRetryEnabled
-            ? { ...headersOptions, throwOnHttpError: false }
-            : headersOptions;
-        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset);
-        if (!retryEnabled || !retryOptions) {
-            const outcome = await executeOnce();
-            if (isHttpStatusOutcome(outcome)) {
-                throw toUpstreamHttpError(outcome.status);
+        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 };
             }
-            return outcome;
+            catch (error) {
+                throw redactSensitiveRequestError(error, url, options.sensitiveParams);
+            }
+        })();
+        const requestStarted = performance.now();
+        const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), retryOptions?.preset);
+        try {
+            return await runRequest();
         }
-        let lastErrorCode;
-        let lastStatus;
-        for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
-            try {
-                const outcome = await executeOnce(attempt - 1);
+        finally {
+            telemetry.finish(performance.now() - requestStarted);
+        }
+        async function runRequest() {
+            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 = 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 = (() => {
+                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() } : 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) => {
+                const started = performance.now();
+                let proxyUsed = false;
+                let observedStatus;
+                const record = (event) => {
+                    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);
                 }
-                const response = outcome;
-                if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
-                    throw toUpstreamHttpError(response.status);
+                return outcome;
+            }
+            let lastError;
+            // `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);
+                    }
+                    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;
                 }
-                if (attempt > 1) {
-                    const summary = {
-                        attempts: attempt,
-                        retries: attempt - 1,
-                        ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
-                        transport: "native",
-                        ...(lastErrorCode ? { lastErrorCode } : {}),
-                        ...(lastStatus ? { lastStatus } : {}),
-                    };
-                    clientOptions.onRetrySummary?.(summary);
+                catch (error) {
+                    throwIfAmbientAborted(headersOptions.signal);
+                    if (!issuedThisAttempt)
+                        issued += 1;
+                    lastError = error;
+                    const proxyUsed = Boolean(error.proxyUsed);
+                    if (attempt < transportAttemptCap &&
+                        shouldRetryProxyTransportAttempt({
+                            error,
+                            explicitRetry,
+                            method: methodName,
+                            options: retryOptions,
+                            proxyUsed,
+                        })) {
+                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt), headersOptions.signal);
+                        continue;
+                    }
+                    throw error;
                 }
-                return response;
             }
-            catch (error) {
-                lastErrorCode = proxyTransportRetryErrorCode(error);
-                lastStatus = proxyTransportRetryErrorStatus(error);
-                const proxyUsed = Boolean(error.proxyUsed);
-                if (attempt < retryOptions.attempts &&
-                    shouldRetryProxyTransportAttempt({
-                        error,
-                        explicitRetry,
-                        method: methodName,
-                        options: retryOptions,
-                        proxyUsed,
-                    })) {
-                    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",
+            });
         }
-        throw new TransportError("HTTP retry exhausted without a terminal result", {
-            code: "retry_exhausted",
-        });
     }
     async function streamRequest(url, method, options = {}) {
-        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) => {
+            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 {
         request: async (url, options = {}) => request(url, options.method ?? "GET", options),
@@ -402,10 +956,15 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         delete: async (url, options) => request(url, "DELETE", options),
         stream: async (url, options = {}) => streamRequest(url, options.method ?? "GET", options),
         sse: async (url, options = {}) => {
-            const headers = {
-                Accept: "text/event-stream",
-                ...options.headers,
-            };
+            const callerHeaders = options.headers;
+            const headers = 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,