@apifuse/provider-sdk 2.2.0-beta.60 → 2.2.0-beta.62

package/dist/runtime/http.js

@@ -2,9 +2,34 @@ import { policyRotatesTransportVendorChain, resolvePolicyTransportAttemptCap, re
 import { HttpRedirectError, 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 { httpTelemetryErrorCode, } from "./http-telemetry.js";
 import { evaluateRedirectHop, isRedirectStatus, resolveRedirectUrl } 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";
 }
@@ -527,7 +552,7 @@ function serializeHttpRequestUrl(baseUrl, url, options) {
         throw redactSensitiveRequestError(error, url, options.sensitiveParams);
     }
 }
-async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe) {
+async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, warn, statusRetryCodes, proxyAttemptOffset = 0, dedupe, observeProxy) {
     const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
     const { requestUrl } = serializedUrl;
     const controller = options.timeout ? new AbortController() : undefined;
@@ -542,6 +567,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
         // 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(clientOptions.signal);
         // For a registry allocator chain, skip an endpoint a prior attempt already
         // tried rather than re-issuing the same request. Returning the sentinel
@@ -563,6 +589,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
             requestInit.body = normalizeNativeFetchBody(options.body);
         }
         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);
@@ -596,7 +623,7 @@ async function fetchNativeHttp(baseUrl, url, method, options, clientOptions, war
             clearTimeout(timeoutHandle);
     }
 }
-async function fetchNativeHttpStream(baseUrl, url, method, options, clientOptions, warn) {
+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;
@@ -607,6 +634,7 @@ async function fetchNativeHttpStream(baseUrl, url, method, options, clientOption
     try {
         throwIfAmbientAborted(clientOptions.signal);
         const proxy = await resolveNativeProxy(options, clientOptions, warn);
+        observeProxy?.(Boolean(proxy));
         throwIfAmbientAborted(clientOptions.signal);
         const requestInit = {
             headers: options.headers,
@@ -676,164 +704,189 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 throw redactSensitiveRequestError(error, url, options.sensitiveParams);
             }
         })();
-        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({
+        const requestStarted = performance.now();
+        const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), retryOptions?.preset);
+        try {
+            return await runRequest();
+        }
+        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,
-                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) {
-            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;
-        }
-        let lastError;
-        let lastErrorCode;
-        let lastStatus;
-        // `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);
+            });
+            const dedupeContext = dedupeAllocatorEndpoints ? { attempted: new Set() } : undefined;
+            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;
+                    });
+                    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(clientOptions.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);
                 }
-                const response = outcome;
-                if (response.status >= 400 && headersOptions.throwOnHttpError !== false) {
-                    throw toUpstreamHttpError(response.status);
-                }
-                if (issued > 1) {
-                    const summary = {
-                        attempts: issued,
-                        retries: issued - 1,
-                        ...(retryOptions.preset ? { preset: retryOptions.preset } : {}),
-                        transport: "native",
-                        ...(lastErrorCode ? { lastErrorCode } : {}),
-                        ...(lastStatus ? { lastStatus } : {}),
-                    };
-                    clientOptions.onRetrySummary?.(summary);
-                }
-                return response;
+                return outcome;
             }
-            catch (error) {
+            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(clientOptions.signal);
-                if (!issuedThisAttempt)
+                // 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;
-                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), clientOptions.signal);
-                    continue;
+                    issuedThisAttempt = true;
+                    if (isHttpStatusOutcome(outcome)) {
+                        if (outcome.retryable && issued < retryOptions.attempts) {
+                            await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers), clientOptions.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;
+                }
+                catch (error) {
+                    throwIfAmbientAborted(clientOptions.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), clientOptions.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;
+            }
+            throw new TransportError("HTTP retry exhausted without a terminal result", {
+                code: "retry_exhausted",
+            });
         }
-        // Reached when the attempt cap is consumed without a terminal outcome —
-        // e.g. the final offsets of a partial allocation all resolved to
-        // already-tried endpoints and were skipped. Surface the last real transport
-        // failure rather than a synthetic exhaustion error.
-        if (lastError !== undefined) {
-            throw lastError;
-        }
-        throw new TransportError("HTTP retry exhausted without a terminal result", {
-            code: "retry_exhausted",
-        });
     }
     async function streamRequest(url, method, options = {}) {
         const { headersOptions, methodName } = (() => {
@@ -855,7 +908,30 @@ export function createHttpClient(baseUrl, clientOptions = {}) {
                 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 = clientOptions.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);
+        }
     }
     return {
         request: async (url, options = {}) => request(url, options.method ?? "GET", options),

package/dist/runtime/native-network.d.ts

@@ -1,8 +1,9 @@
 import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
-import { type ProxyProtocol } from "../config/loader.js";
+import { type ProxyProtocol, type ProxyTelemetrySink } from "../config/loader.js";
 import { type DynamicEgressRuleSnapshot } from "../native-egress-policy.js";
 import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
+import type { NativeTelemetrySink } from "./native-telemetry.js";
 export { NativeEgressGrantExpiredError, NativeEgressNotDeclaredError, NativeIdleTimeoutError, NativeNetworkError, NativeProxyExpiredError, } from "./native-network-errors.js";
 export type { NativeNetworkErrorCode } from "./native-network-errors.js";
 export type NativeGatewayProxy = NativeProxyEgressInfo & {
@@ -15,6 +16,8 @@ export type NativeGatewayProxySynthesisInput = {
     readonly now: number;
     readonly protocol: ProxyProtocol;
     readonly credentials: VendorCredentialResolver;
+    /** Existing proxy lease telemetry; adapters may report detailed allocation facts. */
+    readonly telemetry?: ProxyTelemetrySink;
 };
 export type VendorCredentialLookup = {
     readonly kind: "present";
@@ -50,8 +53,14 @@ export type NativeGatewayProxyResolutionInput = {
     readonly protocol?: ProxyProtocol;
     readonly credentials?: VendorCredentialResolver;
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
+    readonly telemetry?: ProxyTelemetrySink;
+    readonly nativeTelemetry?: NativeTelemetrySink;
 };
 export type NativeNetworkClientOptions = {
+    /** Existing proxy lease contributor, shared with HTTP and stealth. */
+    readonly telemetry?: ProxyTelemetrySink;
+    /** Request-scoped connection, byte and lifecycle observations. */
+    readonly nativeTelemetry?: NativeTelemetrySink;
     readonly proxyPolicy?: ProviderProxyPolicy;
     readonly affinityKey?: string;
     /** Stable credential/account identity; hashed before vendor synthesis. */