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

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. */

package/dist/runtime/native-network.js

@@ -101,6 +101,7 @@ async function synthesizeSmartproxyGateway(input) {
             proxyPolicy: input.policy,
             affinityKey: input.affinityKey,
             protocol: input.protocol,
+            telemetry: input.telemetry,
         }, {
             protocol: input.protocol,
             poolIndex: 0,
@@ -119,6 +120,9 @@ async function synthesizeSmartproxyGateway(input) {
         };
     }
     catch (error) {
+        if (error instanceof ProxyResolutionError && error.telemetry) {
+            emitTelemetry(() => input.telemetry?.recordProxyResolution(error.telemetry));
+        }
         const cause = error instanceof Error ? error : new Error(String(error));
         return skipped({
             kind: "allocation_failed",
@@ -184,6 +188,59 @@ function defaultVendorProtocol(vendor) {
         ? VENDOR_DEFAULT_PROTOCOL[vendor]
         : "http";
 }
+// Instrumentation must not change the transport's exceptions or vendor ordering.
+function emitTelemetry(emit) {
+    try {
+        emit();
+    }
+    catch {
+        /* An observer cannot fail an underlying operation. */
+    }
+}
+function nativeErrorCode(error) {
+    const code = error instanceof NativeNetworkError || error instanceof ProxyResolutionError
+        ? error.code
+        : undefined;
+    switch (code) {
+        case "native_connection_aborted":
+        case "native_connection_closed":
+        case "native_connection_failed":
+        case "native_connection_idle_timeout":
+        case "native_connection_timeout":
+        case "native_egress_authorization_failed":
+        case "native_egress_grant_expired":
+        case "native_egress_grant_invalid":
+        case "native_egress_grant_limit_exceeded":
+        case "native_egress_input_invalid":
+        case "native_egress_not_declared":
+        case "native_egress_policy_invalid":
+        case "native_dynamic_egress_unsupported":
+        case "native_proxy_expired":
+        case "native_proxy_invalid":
+        case "PROXY_REQUIRED":
+        case "PROXY_ALLOCATION_FAILED":
+            return code;
+        default:
+            return "other";
+    }
+}
+function nativeErrorDiagnostics(error) {
+    if (!(error instanceof Error))
+        return {};
+    const cause = error.cause instanceof Error ? error.cause : undefined;
+    const detail = cause ?? error;
+    const systemCode = Reflect.get(detail, "code");
+    const status = Reflect.get(detail, "connectStatusCode");
+    const socksReplyCode = Reflect.get(detail, "socks5ReplyCode");
+    return {
+        errorName: error.name,
+        errorMessage: error.message,
+        ...(cause ? { causeName: cause.name, causeMessage: cause.message } : {}),
+        ...(typeof systemCode === "string" ? { systemCode } : {}),
+        ...(typeof status === "number" ? { status } : {}),
+        ...(typeof socksReplyCode === "number" ? { socksReplyCode } : {}),
+    };
+}
 async function resolveNativeGatewayProxyDetailed(input) {
     if (input.policy.mode === "disabled")
         return { skips: [] };
@@ -191,14 +248,61 @@ async function resolveNativeGatewayProxyDetailed(input) {
     const credentials = input.credentials ?? createEnvVendorCredentialResolver();
     const now = input.now ?? Date.now();
     const skips = [];
-    for (const vendor of resolveNativeVendorChain(input.policy)) {
+    const chain = resolveNativeVendorChain(input.policy);
+    const recordSkip = (skip) => {
+        skips.push(skip);
+        emitTelemetry(() => input.nativeTelemetry?.recordVendorSkip({
+            vendor: skip.vendor,
+            reason: skip.reason.kind,
+            diagnostics: skip.reason.kind === "credentials_absent"
+                ? { missingFields: skip.reason.missing }
+                : skip.reason.kind === "protocol_unsupported"
+                    ? { protocol: skip.reason.protocol }
+                    : skip.reason.kind === "allocation_failed" ||
+                        skip.reason.kind === "credential_lookup_failed"
+                        ? nativeErrorDiagnostics(skip.reason.cause)
+                        : {},
+        }));
+        if (skip.vendor === "smartproxy" || skip.vendor === "nodemaven") {
+            const vendor = skip.vendor;
+            const next = chain[chain.indexOf(vendor) + 1];
+            emitTelemetry(() => input.telemetry?.recordProxyVendorFailover?.({
+                vendor,
+                ...(next === "smartproxy" || next === "nodemaven" ? { nextVendor: next } : {}),
+                phase: "resolution",
+                reason: skip.reason.kind === "credentials_absent"
+                    ? "no_credentials"
+                    : skip.reason.kind === "protocol_unsupported"
+                        ? "protocol_unsupported"
+                        : "allocation_failed",
+            }));
+        }
+    };
+    for (const vendor of chain) {
         const protocol = input.protocol ?? defaultVendorProtocol(vendor);
         if (!isProxyProtocol(protocol)) {
-            skips.push({ vendor, reason: { kind: "protocol_unsupported", protocol: String(protocol) } });
+            recordSkip({ vendor, reason: { kind: "protocol_unsupported", protocol: String(protocol) } });
             continue;
         }
+        let resolutionRecorded = false;
+        const telemetry = input.telemetry
+            ? {
+                recordProxyResolution(event) {
+                    resolutionRecorded = true;
+                    emitTelemetry(() => input.telemetry?.recordProxyResolution(event));
+                },
+                recordProxyAttempt(event) {
+                    emitTelemetry(() => input.telemetry?.recordProxyAttempt?.(event));
+                },
+                recordProxyVendorFailover(event) {
+                    emitTelemetry(() => input.telemetry?.recordProxyVendorFailover?.(event));
+                },
+            }
+            : undefined;
         let vendorSkip;
         for (const synthesize of synthesizers) {
+            const startedAt = Date.now();
+            resolutionRecorded = false;
             try {
                 const resolved = await synthesize({
                     vendor,
@@ -207,6 +311,7 @@ async function resolveNativeGatewayProxyDetailed(input) {
                     now,
                     protocol,
                     credentials,
+                    telemetry,
                 });
                 if (!resolved)
                     continue;
@@ -216,6 +321,17 @@ async function resolveNativeGatewayProxyDetailed(input) {
                 }
                 if (resolved.vendor === vendor) {
                     assertTunnelingScheme(resolved.url);
+                    if (!resolutionRecorded && (vendor === "smartproxy" || vendor === "nodemaven")) {
+                        const resolvedProtocol = new URL(resolved.url).protocol === "http:" ? "http" : "socks5";
+                        emitTelemetry(() => telemetry?.recordProxyResolution({
+                            provider: vendor,
+                            protocol: resolvedProtocol,
+                            cacheStatus: "disabled",
+                            cacheHit: false,
+                            resolutionMs: Math.max(0, Date.now() - startedAt),
+                            attempts: 1,
+                        }));
+                    }
                     return { proxy: resolved, skips };
                 }
             }
@@ -226,7 +342,7 @@ async function resolveNativeGatewayProxyDetailed(input) {
                 };
             }
         }
-        skips.push({ vendor, reason: vendorSkip ?? { kind: "adapter_unavailable" } });
+        recordSkip({ vendor, reason: vendorSkip ?? { kind: "adapter_unavailable" } });
     }
     return { skips };
 }
@@ -651,6 +767,10 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
             if (socket.readableEnded || socket.destroyed)
                 return;
             closeReason = new NativeIdleTimeoutError();
+            emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({
+                kind: "idle",
+                errorCode: "native_connection_idle_timeout",
+            }));
             socket.destroy(closeReason);
         }, Math.max(0, idleTimeoutMs));
         idleTimer.unref?.();
@@ -668,6 +788,11 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
     };
     socket.on("error", (error) => {
         terminalError = error;
+        if (!closeReason)
+            emitTelemetry(() => options.nativeTelemetry?.recordError({
+                errorCode: "native_connection_failed",
+                diagnostics: nativeErrorDiagnostics(error),
+            }));
     });
     socket.once("end", clearIdleTimer);
     socket.once("close", clearLifecycle);
@@ -689,16 +814,32 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
         const leadDelay = Math.max(0, remaining - leadSeconds * 1_000);
         expiringTimer = setTimeout(() => {
             expiringTimer = undefined;
+            emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({ kind: "drain" }));
             const handler = drainHandler;
             if (!handler) {
+                emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({ kind: "drain_missing_handler" }));
                 warn("Native sticky proxy is expiring without a drain handler");
                 return;
             }
             void (async () => {
                 try {
-                    await Promise.race([Promise.resolve(handler(event)), lifecycleCutoff]);
+                    await Promise.race([
+                        Promise.resolve(handler(event)).then(() => {
+                            if (socket.destroyed || lifecycleSettled)
+                                return;
+                            emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({ kind: "drain_acknowledged" }));
+                        }),
+                        lifecycleCutoff,
+                    ]);
                 }
-                catch {
+                catch (error) {
+                    if (socket.destroyed || lifecycleSettled)
+                        return;
+                    emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({
+                        kind: "drain_error",
+                        errorCode: "other",
+                        diagnostics: nativeErrorDiagnostics(error),
+                    }));
                     // Drain failures do not bypass the hard-expiry fail-safe.
                 }
             })();
@@ -709,6 +850,11 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
             if (socket.destroyed)
                 return;
             closeReason = new NativeProxyExpiredError(expiresAt);
+            emitTelemetry(() => options.nativeTelemetry?.recordLifecycle({
+                kind: "expiry",
+                errorCode: "native_proxy_expired",
+                diagnostics: { expiresAt },
+            }));
             settleLifecycle();
             socket.destroy();
         }, remaining);
@@ -722,6 +868,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
         const chunk = socket.read();
         if (chunk) {
             resetIdleTimer();
+            emitTelemetry(() => options.nativeTelemetry?.recordBytes({ direction: "in", bytes: chunk.byteLength }));
             return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength);
         }
         if (socket.readableEnded || socket.destroyed)
@@ -770,6 +917,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
             if (closeReason)
                 throw closeReason;
             if (socket.destroyed) {
+                emitTelemetry(() => options.nativeTelemetry?.recordError({ errorCode: "native_connection_closed" }));
                 throw new NativeNetworkError("Native connection is closed", "native_connection_closed");
             }
             await new Promise((resolve, reject) => {
@@ -780,6 +928,7 @@ export function createNativeNetworkConnection(socket, proxy, options, idleTimeou
                         resolve();
                 });
             });
+            emitTelemetry(() => options.nativeTelemetry?.recordBytes({ direction: "out", bytes: data.byteLength }));
         },
         close: async () => {
             if (socket.closed || socket.destroyed) {
@@ -808,6 +957,8 @@ async function resolveConnectionProxy(options, input, deadline) {
         protocol: options.proxyProtocol,
         credentials: options.credentials,
         gatewaySynthesizers: options.gatewaySynthesizers,
+        telemetry: options.telemetry,
+        nativeTelemetry: options.nativeTelemetry,
     }), input.signal, deadline);
     if (!resolution.proxy && policy.mode === "required") {
         throw proxyRequiredError(policy, resolution.skips);
@@ -1201,32 +1352,82 @@ export function createNativeEgressAuthorization(options) {
 /** Create the SDK byte-stream runtime with provider-declared egress enforcement. */
 export function createNativeNetworkClient(options = {}) {
     const egress = createNativeEgressAuthorization(options);
-    return {
-        connectTcp: async (input) => {
-            const request = snapshotNativeConnectInput(input);
-            egress.assertConnect(request, "disabled");
-            const deadline = deadlineFrom(request.timeoutMs);
-            assertCanStart(request.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, request, deadline);
-            egress.assertConnect(request, "disabled");
-            const socket = proxy
-                ? await connectProxyTunnel(proxy, request, deadline, () => egress.assertConnect(request, "disabled"))
-                : await connectPlainSocket(request.host, request.port, request.signal, deadline);
-            return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
-        },
-        connectTls: async (input) => {
-            const request = snapshotNativeConnectInput(input);
-            egress.assertConnect(request, "required");
+    const connect = async (input, kind) => {
+        const startedAt = Date.now();
+        let proxy;
+        let request;
+        let tunnelMs = 0;
+        let outcome = "error";
+        let failure;
+        try {
+            request = snapshotNativeConnectInput(input);
+            const tls = kind === "tls" ? "required" : "disabled";
+            egress.assertConnect(request, tls);
             const deadline = deadlineFrom(request.timeoutMs);
             assertCanStart(request.signal, deadline);
-            const proxy = await resolveConnectionProxy(options, request, deadline);
-            egress.assertConnect(request, "required");
-            const tunnel = proxy
-                ? await connectProxyTunnel(proxy, request, deadline, () => egress.assertConnect(request, "required"))
-                : undefined;
-            const socket = await upgradeTls(tunnel, request, deadline);
-            return createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
-        },
+            proxy = await resolveConnectionProxy(options, request, deadline);
+            egress.assertConnect(request, tls);
+            let tunnel;
+            if (proxy) {
+                const tunnelStartedAt = Date.now();
+                try {
+                    const destination = request;
+                    tunnel = await connectProxyTunnel(proxy, request, deadline, () => egress.assertConnect(destination, tls));
+                }
+                finally {
+                    tunnelMs = Math.max(0, Date.now() - tunnelStartedAt);
+                }
+            }
+            const socket = kind === "tls"
+                ? await upgradeTls(tunnel, request, deadline)
+                : (tunnel ??
+                    (await connectPlainSocket(request.host, request.port, request.signal, deadline)));
+            const connection = createNativeNetworkConnection(socket, proxy, options, request.idleTimeoutMs);
+            outcome = "ok";
+            return connection;
+        }
+        catch (error) {
+            failure = error;
+            throw error;
+        }
+        finally {
+            // One terminal sample for this connect call, including preflight and rethrows.
+            emitTelemetry(() => options.nativeTelemetry?.recordConnect({
+                kind,
+                outcome,
+                ms: Math.max(0, Date.now() - startedAt),
+                tunnelMs,
+                proxyUsed: proxy !== undefined,
+                ...(proxy ? { vendor: proxy.vendor } : {}),
+                ...(outcome === "error" ? { errorCode: nativeErrorCode(failure) } : {}),
+                diagnostics: {
+                    ...(request
+                        ? {
+                            host: request.host,
+                            port: request.port,
+                            ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+                            ...(request.idleTimeoutMs === undefined
+                                ? {}
+                                : { idleTimeoutMs: request.idleTimeoutMs }),
+                            ...(request.serverName ? { serverName: request.serverName } : {}),
+                        }
+                        : {}),
+                    ...(proxy
+                        ? {
+                            protocol: new URL(proxy.url).protocol,
+                            sticky: proxy.sticky,
+                            ...(proxy.sessionId ? { sessionId: proxy.sessionId } : {}),
+                            ...(proxy.expiresAt ? { expiresAt: proxy.expiresAt } : {}),
+                        }
+                        : {}),
+                    ...nativeErrorDiagnostics(failure),
+                },
+            }));
+        }
+    };
+    return {
+        connectTcp: (input) => connect(input, "tcp"),
+        connectTls: (input) => connect(input, "tls"),
         grantTcpEgress: (input) => egress.grant(snapshotNativeGrantInput(input)),
     };
 }

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

@@ -0,0 +1,142 @@
+import type { ProviderProxyProvider } from "../types.js";
+import type { NativeNetworkErrorCode } from "./native-network-errors.js";
+import { type ClosedEnum, type TelemetryContributor } from "./request-telemetry.js";
+export type NativeTelemetryErrorCode = NativeNetworkErrorCode | "PROXY_REQUIRED" | "PROXY_ALLOCATION_FAILED" | "other";
+export type NativeTelemetryKind = "tcp" | "tls";
+export type NativeTelemetryOutcome = "ok" | "error";
+export type NativeTelemetryVendorSkipReason = "credentials_absent" | "protocol_unsupported" | "allocation_failed" | "credential_lookup_failed" | "adapter_unavailable";
+export type NativeTelemetryLifecycleKind = "drain" | "drain_acknowledged" | "drain_error" | "drain_missing_handler" | "idle" | "expiry";
+/** Operator-only text is redacted before it is detached and bounded to 300 code units. */
+export type NativeTelemetryDiagnostics = {
+    host?: string;
+    serverName?: string;
+    protocol?: string;
+    sessionId?: string;
+    expiresAt?: string;
+    errorName?: string;
+    errorMessage?: string;
+    causeName?: string;
+    causeMessage?: string;
+    systemCode?: string;
+    missingFields?: readonly string[];
+    port?: number;
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    status?: number;
+    socksReplyCode?: number;
+    sticky?: boolean;
+};
+export type NativeConnectTelemetryEvent = {
+    kind: NativeTelemetryKind;
+    outcome: NativeTelemetryOutcome;
+    /** Entire establishment, including lease resolution, tunnel and TLS handshake. */
+    ms: number;
+    /** Tunnel establishment only; included in ms, never added to it. */
+    tunnelMs: number;
+    proxyUsed: boolean;
+    /** Selected vendor for this connection; operator log only. */
+    vendor?: ProviderProxyProvider;
+    errorCode?: NativeTelemetryErrorCode;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export type NativeVendorSkipTelemetryEvent = {
+    vendor: ProviderProxyProvider;
+    reason: NativeTelemetryVendorSkipReason;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export type NativeLifecycleTelemetryEvent = {
+    kind: NativeTelemetryLifecycleKind;
+    errorCode?: NativeTelemetryErrorCode;
+    diagnostics?: NativeTelemetryDiagnostics;
+};
+export interface NativeTelemetrySink {
+    recordConnect(event: NativeConnectTelemetryEvent): void;
+    recordVendorSkip(event: NativeVendorSkipTelemetryEvent): void;
+    recordLifecycle(event: NativeLifecycleTelemetryEvent): void;
+    /** Application bytes returned by read or accepted by a successful write. Excludes tunnel/TLS framing. */
+    recordBytes(event: {
+        direction: "in" | "out";
+        bytes: number;
+    }): void;
+    recordError(event: {
+        errorCode: NativeTelemetryErrorCode;
+        diagnostics?: NativeTelemetryDiagnostics;
+    }): void;
+}
+export type NativeAttemptSample = NativeConnectTelemetryEvent & {
+    n: number;
+};
+export type NativeTelemetryLogPayload = {
+    attempts: number;
+    connectMs: number;
+    tunnelMs: number;
+    vendorSkips: number;
+    vendorSkipReasons: {
+        reason: NativeTelemetryVendorSkipReason;
+        count: number;
+    }[];
+    drain: number;
+    drainAcknowledged: number;
+    drainErrors: number;
+    drainMissingHandler: number;
+    idle: number;
+    expiry: number;
+    bytesIn: number;
+    bytesOut: number;
+    lastErrorCode?: NativeTelemetryErrorCode;
+    lastErrorDiagnostics?: NativeTelemetryDiagnostics;
+    attemptSamples?: NativeAttemptSample[];
+    attemptSamplesDropped?: number;
+    vendorSkipSamples?: NativeVendorSkipTelemetryEvent[];
+    vendorSkipSamplesDropped?: number;
+};
+export type NativeTelemetryHeaderPayload = {
+    attempts: number;
+    connectMs: number;
+    tunnelMs: number;
+    vendorSkips: number;
+    vendorSkipReasons: {
+        reason: ClosedEnum<NativeTelemetryVendorSkipReason>;
+        count: number;
+    }[];
+    drain: number;
+    drainAcknowledged: number;
+    drainErrors: number;
+    drainMissingHandler: number;
+    idle: number;
+    expiry: number;
+    bytesIn: number;
+    bytesOut: number;
+    lastErrorCode?: ClosedEnum<NativeTelemetryErrorCode>;
+    attemptSamples?: {
+        n: number;
+        kind: ClosedEnum<NativeTelemetryKind>;
+        outcome: ClosedEnum<NativeTelemetryOutcome>;
+        ms: number;
+        tunnelMs: number;
+        proxyUsed: boolean;
+        errorCode?: ClosedEnum<NativeTelemetryErrorCode>;
+    }[];
+    attemptSamplesDropped?: number;
+    vendorSkipSamplesDropped?: number;
+};
+export declare class NativeTelemetryCollector implements NativeTelemetrySink, TelemetryContributor<NativeTelemetryLogPayload, NativeTelemetryHeaderPayload> {
+    #private;
+    readonly key: "native";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    recordConnect(event: NativeConnectTelemetryEvent): void;
+    recordVendorSkip(event: NativeVendorSkipTelemetryEvent): void;
+    recordLifecycle(event: NativeLifecycleTelemetryEvent): void;
+    recordBytes(event: {
+        direction: "in" | "out";
+        bytes: number;
+    }): void;
+    recordError(event: {
+        errorCode: NativeTelemetryErrorCode;
+        diagnostics?: NativeTelemetryDiagnostics;
+    }): void;
+    toLogPayload(): NativeTelemetryLogPayload | undefined;
+    toHeaderPayload(log: NativeTelemetryLogPayload): NativeTelemetryHeaderPayload;
+}