@apifuse/provider-sdk 2.2.0-beta.16 → 2.2.0-beta.17

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

@@ -1,10 +1,11 @@
 import { Socket } from "node:net";
 import { type TLSSocket } from "node:tls";
+import { type ProxyProtocol } from "../config/loader.js";
 import { TransportError } from "../errors.js";
-import type { NativeNetworkClient, NativeNetworkConnection, NativeNetworkConnectInput, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider } from "../types.js";
+import type { NativeNetworkClient, NativeNetworkConnectInput, NativeNetworkConnection, NativeNetworkDynamicGrantOptions, NativeNetworkEgressGrant, NativeProviderConfig, NativeProxyEgressInfo, ProviderProxyPolicy, ProviderProxyProvider, EnvContext } from "../types.js";
 export type NativeNetworkErrorCode = "native_connection_aborted" | "native_connection_closed" | "native_connection_failed" | "native_connection_idle_timeout" | "native_connection_timeout" | "native_egress_authorization_failed" | "native_egress_grant_expired" | "native_egress_grant_invalid" | "native_egress_grant_limit_exceeded" | "native_egress_input_invalid" | "native_egress_not_declared" | "native_egress_policy_invalid" | "native_dynamic_egress_unsupported" | "native_proxy_expired" | "native_proxy_invalid";
 export declare class NativeNetworkError extends TransportError {
-    constructor(message: string, code: NativeNetworkErrorCode);
+    constructor(message: string, code: NativeNetworkErrorCode, cause?: Error);
     get code(): NativeNetworkErrorCode;
 }
 export declare class NativeProxyExpiredError extends NativeNetworkError {
@@ -13,9 +14,9 @@ export declare class NativeProxyExpiredError extends NativeNetworkError {
 }
 /** Raised before transport setup when a native destination is not authorized. */
 export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
-    readonly host: string;
     readonly port: number;
     readonly tls: "required" | "disabled";
+    readonly host: string;
     constructor(host: string, port: number, tls: "required" | "disabled");
 }
 /**
@@ -23,10 +24,10 @@ export declare class NativeEgressNotDeclaredError extends NativeNetworkError {
  * its expiry remains in the client's bounded recent-expiry evidence window.
  */
 export declare class NativeEgressGrantExpiredError extends NativeNetworkError {
-    readonly host: string;
     readonly port: number;
     readonly tls: "required" | "disabled";
     readonly expiresAt: string;
+    readonly host: string;
     constructor(host: string, port: number, tls: "required" | "disabled", expiresAt: string);
 }
 /** Raised when an established connection exceeds its opt-in read-idle window. */
@@ -41,13 +42,42 @@ export type NativeGatewayProxySynthesisInput = {
     readonly policy: ProviderProxyPolicy;
     readonly affinityKey?: string;
     readonly now: number;
+    readonly protocol: ProxyProtocol;
+    readonly credentials: VendorCredentialResolver;
+};
+export type VendorCredentialLookup = {
+    readonly kind: "present";
+    readonly values: Readonly<Record<string, string>>;
+} | {
+    readonly kind: "absent";
+    readonly missing: readonly string[];
+};
+export type VendorCredentialResolver = (vendor: ProviderProxyProvider) => VendorCredentialLookup;
+export type NativeGatewayProxySkipReason = {
+    readonly kind: "credentials_absent";
+    readonly missing: readonly string[];
+} | {
+    readonly kind: "protocol_unsupported";
+    readonly protocol: string;
+} | {
+    readonly kind: "allocation_failed";
+    readonly cause: Error;
+} | {
+    readonly kind: "credential_lookup_failed";
+    readonly cause: Error;
 };
+export type NativeGatewayProxySynthesisResult = NativeGatewayProxy | {
+    readonly kind: "skipped";
+    readonly reason: NativeGatewayProxySkipReason;
+} | undefined;
 /** A vendor adapter in the ordered native gateway resolution chain. */
-export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxy | undefined;
+export type NativeGatewayProxySynthesizer = (input: NativeGatewayProxySynthesisInput) => NativeGatewayProxySynthesisResult | Promise<NativeGatewayProxySynthesisResult>;
 export type NativeGatewayProxyResolutionInput = {
     readonly policy: ProviderProxyPolicy;
     readonly affinityKey?: string;
     readonly now?: number;
+    readonly protocol?: ProxyProtocol;
+    readonly credentials?: VendorCredentialResolver;
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
 };
 export type NativeNetworkClientOptions = {
@@ -55,6 +85,10 @@ export type NativeNetworkClientOptions = {
     readonly affinityKey?: string;
     /** Stable credential/account identity; hashed before vendor synthesis. */
     readonly credentialIdentity?: string;
+    /** Vendor credential lookup; defaults to the process EnvContext. */
+    readonly credentials?: VendorCredentialResolver;
+    /** Explicit CONNECT/SOCKS5 override; vendors otherwise choose their default. */
+    readonly proxyProtocol?: ProxyProtocol;
     /** Vendor adapters in priority order within each policy vendor slot. */
     readonly gatewaySynthesizers?: readonly NativeGatewayProxySynthesizer[];
     /** Warning-level lifecycle diagnostic sink. */
@@ -67,10 +101,12 @@ export type NativeNetworkClientOptions = {
     /** Additional deployment authorization layered on top of SDK enforcement. */
     readonly grantTcpEgress?: (input: NativeNetworkDynamicGrantOptions) => NativeNetworkEgressGrant;
 };
+/** Build a resolver over the SDK's existing injectable environment context. */
+export declare function createEnvVendorCredentialResolver(env?: EnvContext): VendorCredentialResolver;
 /** Domain-separated, process-independent affinity derived from credential identity. */
 export declare function deriveNativeCredentialAffinityKey(credentialIdentity: string): string;
-/** Resolve the first configured native gateway without invoking an allocator API. */
-export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): NativeGatewayProxy | undefined;
+/** Resolve the first configured native gateway, including allocation vendors. */
+export declare function resolveNativeGatewayProxy(input: NativeGatewayProxyResolutionInput): Promise<NativeGatewayProxy | undefined>;
 export declare function createNativeNetworkConnection(socket: Socket | TLSSocket, proxy: NativeGatewayProxy | undefined, options: NativeNetworkClientOptions, idleTimeoutMs?: number): NativeNetworkConnection;
 type NativeConnectTls = "required" | "disabled";
 export declare const NATIVE_EGRESS_EXPIRED_EVIDENCE_LIMIT = 256;