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

package/dist/runtime/http.js

@@ -1,316 +1,14 @@
-import { resolveProxyConfigAsync } from "../config/loader";
-import { ProviderError, TransportError } from "../errors";
-import { parseSseStream, readableBytes, readableLines, readableTextChunks, } from "../stream";
-import { HttpRetryAfterPolicy, HttpRetryDelayStrategy, HttpRetryJitter, HttpRetryPreset, HttpRetryUnsafeMethodPolicy, } from "../types";
-import { appendQueryParams, normalizeHttpRequestBody } from "./request-options";
+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";
 const DEFAULT_HTTP_BASE_URL = "http://localhost";
 function isHttpStatusOutcome(outcome) {
     return "kind" in outcome && outcome.kind === "http-status";
 }
-const DEFAULT_RETRY_METHODS = ["GET", "HEAD", "OPTIONS"];
-const DEFAULT_RETRY_ERROR_CODES = [
-    "transport_network_error",
-    "transport_timeout",
-];
-const SAFE_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
-const RATE_LIMIT_RETRY_STATUS_CODES = [429, 503];
-const KNOWN_RETRY_METHODS = new Set([
-    "GET",
-    "HEAD",
-    "POST",
-    "PUT",
-    "DELETE",
-    "OPTIONS",
-    "TRACE",
-    "PATCH",
-]);
-const UNSAFE_RETRY_METHODS = new Set([
-    "POST",
-    "PUT",
-    "PATCH",
-    "DELETE",
-    "TRACE",
-]);
-const MAX_RETRY_ATTEMPTS = 8;
-const MAX_RETRY_DELAY_MS = 30_000;
-function hasOwnValue(values, value) {
-    if (typeof value !== "string")
-        return false;
-    return Object.values(values).some((candidate) => candidate === value);
-}
-function createInvalidRetryPolicyError(message) {
-    return new ProviderError(message, { code: "retry_invalid_policy" });
-}
-function createRetryOptions(preset) {
-    switch (preset) {
-        case HttpRetryPreset.Off:
-            return {
-                preset,
-                attempts: 1,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: [],
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 1_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Ignore,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.SafeRead:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: SAFE_RETRY_STATUS_CODES,
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 2_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Cap,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.AggressiveRead:
-            return {
-                preset,
-                attempts: 4,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: SAFE_RETRY_STATUS_CODES,
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 150,
-                maxDelayMs: 5_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Cap,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.RateLimitAware:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: RATE_LIMIT_RETRY_STATUS_CODES,
-                errorCodes: ["transport_timeout"],
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 250,
-                maxDelayMs: 5_000,
-                jitter: HttpRetryJitter.Equal,
-                retryAfter: HttpRetryAfterPolicy.Respect,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-        case HttpRetryPreset.TransportTransient:
-            return {
-                preset,
-                attempts: 3,
-                methods: DEFAULT_RETRY_METHODS,
-                statusCodes: [],
-                errorCodes: DEFAULT_RETRY_ERROR_CODES,
-                delayStrategy: HttpRetryDelayStrategy.Exponential,
-                baseDelayMs: 100,
-                maxDelayMs: 1_000,
-                jitter: HttpRetryJitter.Full,
-                retryAfter: HttpRetryAfterPolicy.Ignore,
-                unsafeMethodPolicy: HttpRetryUnsafeMethodPolicy.Reject,
-            };
-    }
-    throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${preset}`);
-}
-function clampPositiveInteger(value, fallback, max) {
-    if (value === undefined)
-        return fallback;
-    if (!Number.isFinite(value) || value < 1)
-        return fallback;
-    return Math.min(Math.floor(value), max);
-}
-function clampDelay(value, fallback) {
-    if (value === undefined)
-        return fallback;
-    if (!Number.isFinite(value) || value < 0)
-        return fallback;
-    return Math.min(Math.floor(value), MAX_RETRY_DELAY_MS);
-}
-function normalizeRetryOptions(retry) {
-    if (retry === undefined || retry === false) {
-        return undefined;
-    }
-    if (retry === true) {
-        return createRetryOptions(HttpRetryPreset.TransportTransient);
-    }
-    if (typeof retry === "string") {
-        if (!hasOwnValue(HttpRetryPreset, retry)) {
-            throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${retry}`);
-        }
-        return createRetryOptions(retry);
-    }
-    if (typeof retry !== "object" || retry === null) {
-        throw createInvalidRetryPolicyError("HTTP retry policy must be an object");
-    }
-    if (Array.isArray(retry)) {
-        throw createInvalidRetryPolicyError("HTTP retry policy must be a plain object");
-    }
-    validateRetryOptionsShape(retry);
-    const base = createRetryOptions(retry.preset ?? HttpRetryPreset.TransportTransient);
-    const maxDelayMs = clampDelay(retry.maxDelayMs, base.maxDelayMs);
-    const normalized = {
-        preset: retry.preset ?? base.preset,
-        attempts: clampPositiveInteger(retry.attempts, base.attempts, MAX_RETRY_ATTEMPTS),
-        methods: retry.methods?.map((method) => method.toUpperCase()) ?? base.methods,
-        statusCodes: retry.statusCodes?.filter((status) => Number.isInteger(status)) ??
-            base.statusCodes,
-        errorCodes: retry.errorCodes ?? base.errorCodes,
-        delayStrategy: retry.delayStrategy ?? base.delayStrategy,
-        baseDelayMs: clampDelay(retry.baseDelayMs, base.baseDelayMs),
-        maxDelayMs,
-        jitter: retry.jitter ?? base.jitter,
-        retryAfter: retry.retryAfter ?? base.retryAfter,
-        unsafeMethodPolicy: retry.unsafeMethodPolicy ?? base.unsafeMethodPolicy,
-    };
-    return normalized;
-}
-function validateRetryOptionsShape(retry) {
-    if (retry.preset !== undefined &&
-        !hasOwnValue(HttpRetryPreset, retry.preset)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry preset: ${String(retry.preset)}`);
-    }
-    if (retry.delayStrategy !== undefined &&
-        !hasOwnValue(HttpRetryDelayStrategy, retry.delayStrategy)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry delay strategy: ${String(retry.delayStrategy)}`);
-    }
-    if (retry.jitter !== undefined &&
-        !hasOwnValue(HttpRetryJitter, retry.jitter)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry jitter policy: ${String(retry.jitter)}`);
-    }
-    if (retry.retryAfter !== undefined &&
-        !hasOwnValue(HttpRetryAfterPolicy, retry.retryAfter)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry-after policy: ${String(retry.retryAfter)}`);
-    }
-    if (retry.unsafeMethodPolicy !== undefined &&
-        !hasOwnValue(HttpRetryUnsafeMethodPolicy, retry.unsafeMethodPolicy)) {
-        throw createInvalidRetryPolicyError(`Unknown HTTP retry unsafe method policy: ${String(retry.unsafeMethodPolicy)}`);
-    }
-    if (retry.methods !== undefined) {
-        if (!Array.isArray(retry.methods)) {
-            throw createInvalidRetryPolicyError("HTTP retry methods must be an array");
-        }
-        const nonStringMethods = retry.methods.filter((method) => typeof method !== "string");
-        if (nonStringMethods.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry methods must contain only strings");
-        }
-        const unknownMethods = retry.methods
-            .map((method) => method.toUpperCase())
-            .filter((method) => !KNOWN_RETRY_METHODS.has(method));
-        if (unknownMethods.length > 0) {
-            throw createInvalidRetryPolicyError(`Unknown HTTP retry method(s): ${unknownMethods.join(", ")}`);
-        }
-    }
-    if (retry.statusCodes !== undefined) {
-        if (!Array.isArray(retry.statusCodes)) {
-            throw createInvalidRetryPolicyError("HTTP retry statusCodes must be an array");
-        }
-        const invalidStatusCodes = retry.statusCodes.filter((status) => !Number.isInteger(status) ||
-            Number(status) < 100 ||
-            Number(status) > 599);
-        if (invalidStatusCodes.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry statusCodes must contain HTTP status integers in [100, 599]");
-        }
-    }
-    if (retry.errorCodes !== undefined) {
-        if (!Array.isArray(retry.errorCodes)) {
-            throw createInvalidRetryPolicyError("HTTP retry errorCodes must be an array");
-        }
-        const nonStringErrorCodes = retry.errorCodes.filter((errorCode) => typeof errorCode !== "string");
-        if (nonStringErrorCodes.length > 0) {
-            throw createInvalidRetryPolicyError("HTTP retry errorCodes must contain only strings");
-        }
-    }
-    if (retry.preset === HttpRetryPreset.Off &&
-        ((retry.attempts !== undefined && retry.attempts > 1) ||
-            (retry.statusCodes !== undefined && retry.statusCodes.length > 0))) {
-        throw createInvalidRetryPolicyError("HTTP retry preset off cannot be combined with retry-enabling overrides");
-    }
-}
-function validateUnsafeRetryMethods(options) {
-    if (options.unsafeMethodPolicy ===
-        HttpRetryUnsafeMethodPolicy.AllowExplicitUnsafe) {
-        return;
-    }
-    const unsafeMethods = options.methods.filter((method) => UNSAFE_RETRY_METHODS.has(method.toUpperCase()));
-    if (unsafeMethods.length === 0)
-        return;
-    throw new ProviderError(`HTTP retry methods include unsafe method(s): ${unsafeMethods.join(", ")}`, { code: "retry_unsafe_method" });
-}
-function isMethodRetryable(method, options) {
-    return options.methods
-        .map((allowedMethod) => allowedMethod.toUpperCase())
-        .includes(method.toUpperCase());
-}
-function retryErrorCode(error) {
-    if (error instanceof TransportError) {
-        return error.code;
-    }
-    if (error && typeof error === "object" && "code" in error) {
-        const code = Reflect.get(error, "code");
-        return typeof code === "string" ? code : undefined;
-    }
-    return undefined;
-}
-function retryErrorStatus(error) {
-    if (error instanceof TransportError) {
-        return error.status ?? error.upstreamStatus;
-    }
-    return undefined;
-}
-function shouldRetryTransportError(error, options) {
-    const code = retryErrorCode(error);
-    return Boolean(code && options.errorCodes.includes(code));
-}
-function retryAfterHeader(headers) {
-    for (const [name, value] of Object.entries(headers)) {
-        if (name.toLowerCase() === "retry-after")
-            return value;
-    }
-    return undefined;
-}
-function parseRetryAfterMs(headers, now = Date.now()) {
-    const value = retryAfterHeader(headers);
-    if (!value)
-        return undefined;
-    const seconds = Number(value);
-    if (Number.isFinite(seconds)) {
-        return Math.max(0, Math.floor(seconds * 1_000));
-    }
-    const dateMs = Date.parse(value);
-    if (!Number.isNaN(dateMs)) {
-        return Math.max(0, dateMs - now);
-    }
-    return undefined;
-}
-function computeRetryDelayMs(options, attemptIndex, headers) {
-    const multiplier = options.delayStrategy === HttpRetryDelayStrategy.Exponential
-        ? 2 ** Math.max(0, attemptIndex - 1)
-        : 1;
-    const configuredDelay = Math.min(options.baseDelayMs * multiplier, options.maxDelayMs);
-    const retryAfterMs = options.retryAfter === HttpRetryAfterPolicy.Ignore
-        ? undefined
-        : headers
-            ? parseRetryAfterMs(headers)
-            : undefined;
-    if (retryAfterMs !== undefined) {
-        const boundedRetryAfterMs = Math.min(retryAfterMs, options.maxDelayMs);
-        if (options.retryAfter === HttpRetryAfterPolicy.Cap) {
-            return Math.min(boundedRetryAfterMs, configuredDelay);
-        }
-        return boundedRetryAfterMs;
-    }
-    switch (options.jitter) {
-        case HttpRetryJitter.None:
-            return configuredDelay;
-        case HttpRetryJitter.Equal:
-            return Math.floor(configuredDelay / 2 + Math.random() * (configuredDelay / 2));
-        case HttpRetryJitter.Full:
-            return Math.floor(Math.random() * configuredDelay);
-    }
+function isDedupeSkipOutcome(outcome) {
+    return "kind" in outcome && outcome.kind === "dedupe-skip";
 }
 async function sleep(ms) {
     if (ms <= 0)
@@ -330,9 +28,7 @@ function hasHeader(headers, name) {
 }
 function withClientHeaders(options, clientOptions, body) {
     const headers = {
-        ...(clientOptions.userAgent
-            ? { "User-Agent": clientOptions.userAgent }
-            : {}),
+        ...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
         ...options?.headers,
     };
     if (body !== undefined && !hasHeader(headers, "Content-Type")) {
@@ -344,9 +40,7 @@ function withClientHeaders(options, clientOptions, body) {
     };
 }
 function parseHttpData(body, headers) {
-    const contentType = headers["content-type"] ??
-        headers["Content-Type"] ??
-        headers["CONTENT-TYPE"];
+    const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
     if (contentType?.includes("application/json")) {
         return body ? JSON.parse(body) : null;
     }
@@ -396,22 +90,21 @@ function toHttpTransportError(error) {
 }
 async function toNativeHttpResponse(response) {
     const headers = Object.fromEntries(response.headers.entries());
-    const rawText = await response.text();
+    const bodyBytes = new Uint8Array(await response.arrayBuffer());
+    const rawText = new TextDecoder().decode(bodyBytes);
     const data = parseHttpData(rawText, headers);
     return {
         data,
         headers,
         json: async () => {
-            const contentType = headers["content-type"] ??
-                headers["Content-Type"] ??
-                headers["CONTENT-TYPE"];
-            return parseJson(contentType?.includes("application/json") && !rawText
-                ? "null"
-                : rawText);
+            const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
+            return parseJson(contentType?.includes("application/json") && !rawText ? "null" : rawText);
         },
         ok: response.status >= 200 && response.status < 300,
         status: response.status,
         text: async () => rawText,
+        arrayBuffer: async () => bodyBytes.buffer.slice(bodyBytes.byteOffset, bodyBytes.byteOffset + bodyBytes.byteLength),
+        bytes: async () => bodyBytes.slice(0),
     };
 }
 async function drainNativeResponseBody(response) {
@@ -474,12 +167,20 @@ function isAbsoluteUrl(url) {
 function resolveHttpUrl(baseUrl, url) {
     return new URL(url, baseUrl ?? DEFAULT_HTTP_BASE_URL).toString();
 }
-async function resolveNativeProxy(options, clientOptions, warn) {
+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,
     });
     if (resolvedProxy.shouldWarn) {
@@ -501,14 +202,28 @@ function normalizeNativeFetchBody(body) {
     copied.set(normalized);
     return copied.buffer;
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe) {
     const requestUrl = appendQueryParams(resolveHttpUrl(baseUrl, url), options.params);
     const controller = options.timeout ? new AbortController() : undefined;
     const timeoutHandle = options.timeout
         ? setTimeout(() => controller?.abort(), options.timeout)
         : undefined;
+    let proxy;
     try {
-        const proxy = await resolveNativeProxy(options, clientOptions, warn);
+        // Resolve inside the try (and after the timeout is armed) so allocator
+        // failures are branded as TransportErrors and count against the request
+        // deadline, exactly as an inline resolve would.
+        proxy = await resolveNativeProxy(options, clientOptions, warn, proxyAttemptOffset);
+        // For a registry allocator chain, skip an endpoint a prior attempt already
+        // tried rather than re-issuing the same request. Returning the sentinel
+        // (instead of breaking) lets the loop keep advancing the flat offset until
+        // it crosses into the fallback vendor's pool span.
+        if (dedupe && proxy) {
+            if (dedupe.attempted.has(proxy)) {
+                return { kind: "dedupe-skip" };
+            }
+            dedupe.attempted.add(proxy);
+        }
         const requestInit = {
             headers: options.headers,
             method,
@@ -529,6 +244,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
                 status: response.status,
                 headers,
                 retryable: statusRetryCodes.includes(response.status),
+                proxyUsed: Boolean(proxy),
             };
         }
         if (response.status >= 400 && options.throwOnHttpError !== false) {
@@ -544,7 +260,9 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
         if (error instanceof SyntaxError) {
             throw error;
         }
-        throw toHttpTransportError(error);
+        const transportError = toHttpTransportError(error);
+        transportError.proxyUsed = Boolean(proxy);
+        throw transportError;
     }
     finally {
         if (timeoutHandle)
@@ -608,49 +326,130 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
         assertNoHttpTransportOverrides(options);
         const headersOptions = withClientHeaders(options, clientOptions, options.body);
         const methodName = normalizeHttpMethod(method);
-        const retryOptions = normalizeRetryOptions(headersOptions.retry);
+        const explicitRetry = headersOptions.retry !== undefined;
+        const retryOptions = normalizeProxyTransportRetryOptions(headersOptions.retry, {
+            label: "HTTP",
+        }) ??
+            (explicitRetry ? undefined : createDefaultProxyTransportRetryOptions({ label: "HTTP" }));
         if (retryOptions)
-            validateUnsafeRetryMethods(retryOptions);
+            validateUnsafeProxyTransportRetryMethods(retryOptions, "HTTP");
         const retryEnabled = Boolean(retryOptions &&
             retryOptions.attempts > 1 &&
-            isMethodRetryable(methodName, retryOptions));
+            isProxyTransportRetryMethod(methodName, retryOptions));
         const statusRetryEnabled = Boolean(retryEnabled &&
+            explicitRetry &&
             retryOptions &&
             retryOptions.statusCodes.length > 0 &&
             headersOptions.throwOnHttpError !== false);
         const attemptOptions = statusRetryEnabled
             ? { ...headersOptions, throwOnHttpError: false }
             : headersOptions;
-        const executeOnce = () => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined);
+        // 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;
+        const executeOnce = (proxyAttemptOffset = 0) => fetchNativeHttp(baseUrl, url, methodName, attemptOptions, clientOptions, warnOnce, statusRetryEnabled ? retryOptions?.statusCodes : undefined, proxyAttemptOffset, dedupeContext);
         if (!retryEnabled || !retryOptions) {
             const outcome = await executeOnce();
+            if (isDedupeSkipOutcome(outcome)) {
+                // Single-shot path never de-duplicates (dedupeContext is undefined),
+                // but keep the union total.
+                throw new TransportError("HTTP request produced no terminal result", {
+                    code: "retry_exhausted",
+                });
+            }
             if (isHttpStatusOutcome(outcome)) {
                 throw toUpstreamHttpError(outcome.status);
             }
             return outcome;
         }
+        let lastError;
         let lastErrorCode;
         let lastStatus;
-        for (let attempt = 1; attempt <= retryOptions.attempts; attempt += 1) {
+        // `attempt` walks the flat proxy offset across the full chain span; `issued`
+        // counts requests that were actually sent (skipped duplicate offsets do not
+        // increment it). Retry summaries and the status-retry budget must reflect
+        // issued requests, not the raw offset, so they stay accurate when partial
+        // allocations skip offsets.
+        let issued = 0;
+        for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
+            // Whether this offset actually issued a request (vs. a skipped duplicate),
+            // so the catch counts a thrown *transport* failure once without
+            // double-counting a status outcome that already incremented before it
+            // re-threw as an upstream HTTP error.
+            let issuedThisAttempt = false;
             try {
-                const outcome = await executeOnce();
+                const outcome = await executeOnce(attempt - 1);
+                if (isDedupeSkipOutcome(outcome)) {
+                    // Duplicate endpoint from a partial allocation: advance the flat
+                    // offset without issuing the request (no backoff, not a failure) so
+                    // the loop keeps rotating toward the fallback vendor.
+                    continue;
+                }
+                issued += 1;
+                issuedThisAttempt = true;
                 if (isHttpStatusOutcome(outcome)) {
                     lastStatus = outcome.status;
-                    if (outcome.retryable && attempt < retryOptions.attempts) {
-                        await sleep(computeRetryDelayMs(retryOptions, attempt, outcome.headers));
+                    if (outcome.retryable && issued < retryOptions.attempts) {
+                        await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
                         continue;
                     }
                     throw toUpstreamHttpError(outcome.status);
                 }
                 const response = outcome;
-                if (response.status >= 400 &&
-                    headersOptions.throwOnHttpError !== false) {
+                if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
                     throw toUpstreamHttpError(response.status);
                 }
-                if (attempt > 1) {
+                if (issued > 1) {
                     const summary = {
-                        attempts: attempt,
-                        retries: attempt - 1,
+                        attempts: issued,
+                        retries: issued - 1,
                         ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
                         transport: "native",
                         ...(lastErrorCode ? { lastErrorCode } : {}),
@@ -661,16 +460,33 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 return response;
             }
             catch (error) {
-                lastErrorCode = retryErrorCode(error);
-                lastStatus = retryErrorStatus(error);
-                if (attempt < retryOptions.attempts &&
-                    shouldRetryTransportError(error, retryOptions)) {
-                    await sleep(computeRetryDelayMs(retryOptions, attempt));
+                if (!issuedThisAttempt)
+                    issued += 1;
+                lastError = error;
+                lastErrorCode = proxyTransportRetryErrorCode(error);
+                lastStatus = proxyTransportRetryErrorStatus(error);
+                const proxyUsed = Boolean(error.proxyUsed);
+                if (attempt < transportAttemptCap &&
+                    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",
         });

package/dist/runtime/insights.d.ts

@@ -1,4 +1,4 @@
-import type { Span } from "./trace";
+import type { Span } from "./trace.js";
 export type InsightSeverity = "info" | "warning" | "error";
 export type Insight = {
     id: string;