@apifuse/provider-sdk 2.2.0-beta.27 → 2.2.0-beta.28

package/src/runtime/http.ts

@@ -44,6 +44,7 @@ export type HttpClientOptions = ProxyResolutionOptions & {
 	warn?: (message: string) => void;
 	userAgent?: string;
 	onRetrySummary?: (summary: HttpRetrySummary) => void;
+	signal?: AbortSignal;
 };
 
 type HttpStatusOutcome = {
@@ -76,9 +77,45 @@ function isDedupeSkipOutcome(outcome: NativeHttpAttemptOutcome): outcome is Nati
 	return "kind" in outcome && outcome.kind === "dedupe-skip";
 }
 
-async function sleep(ms: number): Promise<void> {
+function toAmbientCancellationError(
+	signal: AbortSignal,
+	error: unknown = signal.reason,
+): TransportError {
+	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: AbortSignal | undefined): void {
+	if (signal?.aborted) throw toAmbientCancellationError(signal);
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	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<void>((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: number): TransportError {
@@ -132,7 +169,21 @@ function isTimeoutMessage(message: string): boolean {
 	return /\b(timed out|timeout|deadline exceeded)\b/i.test(message);
 }
 
-function toHttpTransportError(error: unknown): TransportError {
+function toHttpTransportError(
+	error: unknown,
+	ambientSignal?: AbortSignal,
+	timeoutSignal?: AbortSignal,
+): TransportError {
+	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;
@@ -216,6 +267,78 @@ function requireNativeResponseBody(response: Response): ReadableStream<Uint8Arra
 	return response.body;
 }
 
+function mergeAbortSignals(
+	...signals: Array<AbortSignal | null | undefined>
+): AbortSignal | undefined {
+	const activeSignals = signals.filter((signal): signal is AbortSignal => signal != null);
+	if (activeSignals.length === 0) return undefined;
+	if (activeSignals.length === 1) return activeSignals[0];
+	return AbortSignal.any(activeSignals);
+}
+
+function cancelStreamOnAbort(
+	body: ReadableStream<Uint8Array>,
+	signal: AbortSignal | undefined,
+): ReadableStream<Uint8Array> {
+	if (!signal) return body;
+
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	let finished = false;
+	let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+	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<Uint8Array>(
+		{
+			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: ReadableStream<Uint8Array>,
 	serializedUrl: SerializedRequestUrl,
@@ -265,9 +388,13 @@ function sanitizeStreamErrors(
 function toNativeHttpStreamResponse(
 	response: Response,
 	serializedUrl: SerializedRequestUrl,
+	signal?: AbortSignal,
 ): HttpStreamResponse {
 	const headers = Object.fromEntries(response.headers.entries());
-	const body = sanitizeStreamErrors(requireNativeResponseBody(response), serializedUrl);
+	const body = sanitizeStreamErrors(
+		cancelStreamOnAbort(requireNativeResponseBody(response), signal),
+		serializedUrl,
+	);
 	return {
 		body,
 		headers,
@@ -585,16 +712,19 @@ async function fetchNativeHttp(
 	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
+	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	let proxy: string | undefined;
 	try {
+		throwIfAmbientAborted(clientOptions.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);
+		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
 		// (instead of breaking) lets the loop keep advancing the flat offset until
@@ -609,7 +739,7 @@ async function fetchNativeHttp(
 			headers: options.headers,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
@@ -651,7 +781,7 @@ async function fetchNativeHttp(
 			);
 		}
 		const transportError: NativeHttpAttemptError = redactSensitiveError(
-			toHttpTransportError(error),
+			toHttpTransportError(error, clientOptions.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -674,17 +804,20 @@ async function fetchNativeHttpStream(
 	const serializedUrl = serializeHttpRequestUrl(baseUrl, url, options);
 	const { requestUrl } = serializedUrl;
 	const controller = options.timeout ? new AbortController() : undefined;
+	const signal = mergeAbortSignals(clientOptions.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	try {
+		throwIfAmbientAborted(clientOptions.signal);
 		const proxy = await resolveNativeProxy(options, clientOptions, warn);
+		throwIfAmbientAborted(clientOptions.signal);
 		const requestInit: NativeFetchInit = {
 			headers: options.headers,
 			method,
 			...(proxy ? { proxy } : {}),
-			signal: controller?.signal,
+			...(signal ? { signal } : {}),
 		};
 		if (options.body !== undefined) {
 			requestInit.body = normalizeNativeFetchBody(options.body);
@@ -703,7 +836,9 @@ async function fetchNativeHttpStream(
 			});
 		}
 
-		return toNativeHttpStreamResponse(response, serializedUrl);
+		// Per-call timeout remains header-scoped, while the ambient request signal
+		// stays attached to the response body for its full consumption lifetime.
+		return toNativeHttpStreamResponse(response, serializedUrl, clientOptions.signal);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
 			throw redactSensitiveError(
@@ -714,7 +849,7 @@ async function fetchNativeHttpStream(
 			);
 		}
 		throw redactSensitiveError(
-			toHttpTransportError(error),
+			toHttpTransportError(error, clientOptions.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -850,6 +985,7 @@ export function createHttpClient(
 			);
 
 		if (!retryEnabled || !retryOptions) {
+			throwIfAmbientAborted(clientOptions.signal);
 			const outcome = await executeOnce();
 			if (isDedupeSkipOutcome(outcome)) {
 				// Single-shot path never de-duplicates (dedupeContext is undefined),
@@ -874,6 +1010,7 @@ export function createHttpClient(
 		// 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
@@ -892,7 +1029,10 @@ export function createHttpClient(
 				if (isHttpStatusOutcome(outcome)) {
 					lastStatus = outcome.status;
 					if (outcome.retryable && issued < retryOptions.attempts) {
-						await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers));
+						await sleep(
+							computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers),
+							clientOptions.signal,
+						);
 						continue;
 					}
 					throw toUpstreamHttpError(outcome.status);
@@ -916,6 +1056,7 @@ export function createHttpClient(
 				}
 				return response;
 			} catch (error) {
+				throwIfAmbientAborted(clientOptions.signal);
 				if (!issuedThisAttempt) issued += 1;
 				lastError = error;
 				lastErrorCode = proxyTransportRetryErrorCode(error);
@@ -931,7 +1072,10 @@ export function createHttpClient(
 						proxyUsed,
 					})
 				) {
-					await sleep(computeProxyTransportRetryDelayMs(retryOptions, attempt));
+					await sleep(
+						computeProxyTransportRetryDelayMs(retryOptions, attempt),
+						clientOptions.signal,
+					);
 					continue;
 				}
 				throw error;

package/src/runtime/instrumentation.ts

@@ -23,7 +23,7 @@ import {
 	getTraceRecorder,
 	type TraceContext,
 } from "./trace.js";
-import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 

package/src/runtime/native-network-errors.ts

@@ -0,0 +1,99 @@
+import { TransportError } from "../errors.js";
+import { canonicalizeEgressHost } from "../native-address.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 class NativeNetworkError extends TransportError {
+	constructor(message: string, code: NativeNetworkErrorCode, cause?: Error) {
+		const isEgressPolicyFailure =
+			code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
+		super(message, {
+			code,
+			status: 0,
+			...(cause ? { cause } : {}),
+			...(isEgressPolicyFailure ? { category: "provider_error" as const, retryable: false } : {}),
+		});
+		this.name = "NativeNetworkError";
+	}
+
+	override get code(): NativeNetworkErrorCode {
+		return super.code as NativeNetworkErrorCode;
+	}
+}
+
+export function safeDiagnosticEgressHost(value: unknown): string {
+	const canonical = canonicalizeEgressHost(value);
+	return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
+}
+
+export class NativeProxyExpiredError extends NativeNetworkError {
+	constructor(readonly expiresAt: string) {
+		super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
+		this.name = "NativeProxyExpiredError";
+	}
+}
+
+/** Raised before transport setup when a native destination is not authorized. */
+export class NativeEgressNotDeclaredError extends NativeNetworkError {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`,
+			"native_egress_not_declared",
+		);
+		this.host = diagnosticHost;
+		this.name = "NativeEgressNotDeclaredError";
+	}
+}
+
+/**
+ * Raised when the destination was authorized by a grant whose TTL elapsed and
+ * its expiry remains in the client's bounded recent-expiry evidence window.
+ */
+export class NativeEgressGrantExpiredError extends NativeNetworkError {
+	readonly host: string;
+
+	constructor(
+		host: string,
+		readonly port: number,
+		readonly tls: "required" | "disabled",
+		readonly expiresAt: string,
+	) {
+		const diagnosticHost = safeDiagnosticEgressHost(host);
+		super(
+			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`,
+			"native_egress_grant_expired",
+		);
+		this.host = diagnosticHost;
+		this.name = "NativeEgressGrantExpiredError";
+	}
+}
+
+/** Raised when an established connection exceeds its opt-in read-idle window. */
+export class NativeIdleTimeoutError extends NativeNetworkError {
+	constructor() {
+		super("Native network socket timed out while reading.", "native_connection_idle_timeout");
+		this.name = "NativeIdleTimeoutError";
+	}
+}

package/src/runtime/native-network.ts

@@ -12,7 +12,6 @@ import {
 	VENDOR_DEFAULT_PROTOCOL,
 	resolveWithVendor,
 } from "../config/loader.js";
-import { TransportError } from "../errors.js";
 import {
 	type DynamicEgressRuleSnapshot,
 	NativeEgressPolicyValidationError,
@@ -46,6 +45,14 @@ import type {
 	EnvContext,
 } from "../types.js";
 import { createEnvContext } from "./env.js";
+import {
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
+	NativeIdleTimeoutError,
+	NativeNetworkError,
+	NativeProxyExpiredError,
+	safeDiagnosticEgressHost,
+} from "./native-network-errors.js";
 import {
 	NODEMAVEN_FILTER_ENV,
 	NODEMAVEN_PASSWORD_ENV,
@@ -55,102 +62,14 @@ import {
 } from "./proxy-nodemaven.js";
 import { redactSensitiveError } from "./request-options.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 class NativeNetworkError extends TransportError {
-	constructor(message: string, code: NativeNetworkErrorCode, cause?: Error) {
-		const isEgressPolicyFailure =
-			code.startsWith("native_egress_") || code === "native_dynamic_egress_unsupported";
-		super(message, {
-			code,
-			status: 0,
-			...(cause ? { cause } : {}),
-			...(isEgressPolicyFailure ? { category: "provider_error" as const, retryable: false } : {}),
-		});
-		this.name = "NativeNetworkError";
-	}
-
-	override get code(): NativeNetworkErrorCode {
-		return super.code as NativeNetworkErrorCode;
-	}
-}
-
-function safeDiagnosticEgressHost(value: unknown): string {
-	const canonical = canonicalizeEgressHost(value);
-	return canonical.ok ? canonical.host : `<invalid-host:${canonical.reason}>`;
-}
-
-export class NativeProxyExpiredError extends NativeNetworkError {
-	constructor(readonly expiresAt: string) {
-		super("Native connection closed at sticky proxy expiry", "native_proxy_expired");
-		this.name = "NativeProxyExpiredError";
-	}
-}
-
-/** Raised before transport setup when a native destination is not authorized. */
-export class NativeEgressNotDeclaredError extends NativeNetworkError {
-	readonly host: string;
-
-	constructor(
-		host: string,
-		readonly port: number,
-		readonly tls: "required" | "disabled",
-	) {
-		const diagnosticHost = safeDiagnosticEgressHost(host);
-		super(
-			`Native ${tls === "required" ? "TLS" : "TCP"} egress is not declared for ${diagnosticHost}:${port}`,
-			"native_egress_not_declared",
-		);
-		this.host = diagnosticHost;
-		this.name = "NativeEgressNotDeclaredError";
-	}
-}
-
-/**
- * Raised when the destination was authorized by a grant whose TTL elapsed and
- * its expiry remains in the client's bounded recent-expiry evidence window.
- */
-export class NativeEgressGrantExpiredError extends NativeNetworkError {
-	readonly host: string;
-
-	constructor(
-		host: string,
-		readonly port: number,
-		readonly tls: "required" | "disabled",
-		readonly expiresAt: string,
-	) {
-		const diagnosticHost = safeDiagnosticEgressHost(host);
-		super(
-			`Native ${tls === "required" ? "TLS" : "TCP"} egress grant expired for ${diagnosticHost}:${port}`,
-			"native_egress_grant_expired",
-		);
-		this.host = diagnosticHost;
-		this.name = "NativeEgressGrantExpiredError";
-	}
-}
-
-/** Raised when an established connection exceeds its opt-in read-idle window. */
-export class NativeIdleTimeoutError extends NativeNetworkError {
-	constructor() {
-		super("Native network socket timed out while reading.", "native_connection_idle_timeout");
-		this.name = "NativeIdleTimeoutError";
-	}
-}
+export {
+	NativeEgressGrantExpiredError,
+	NativeEgressNotDeclaredError,
+	NativeIdleTimeoutError,
+	NativeNetworkError,
+	NativeProxyExpiredError,
+} from "./native-network-errors.js";
+export type { NativeNetworkErrorCode } from "./native-network-errors.js";
 
 export type NativeGatewayProxy = NativeProxyEgressInfo & {
 	readonly url: string;

package/src/runtime/redis.ts

@@ -1,4 +1,8 @@
-import { Redis } from "ioredis";
+import { createRequire } from "node:module";
+
+import type { Redis } from "ioredis";
+
+const require = createRequire(import.meta.url);
 
 export type ProviderRedisClient = Redis;
 
@@ -17,7 +21,8 @@ type RedisTimeoutOptions<T> = {
 export function createProviderRedisClient(
 	options: ProviderRedisClientOptions,
 ): ProviderRedisClient {
-	const redis = new Redis(options.redisUrl, {
+	const { Redis: RedisClient } = require("ioredis") as typeof import("ioredis");
+	const redis = new RedisClient(options.redisUrl, {
 		connectTimeout: options.timeoutMs,
 		enableOfflineQueue: false,
 		lazyConnect: true,

package/src/runtime/resolver-config.ts

@@ -0,0 +1,6 @@
+export const APIFUSE__RESOLVER__2CAPTCHA__API_KEY = "APIFUSE__RESOLVER__2CAPTCHA__API_KEY";
+export const APIFUSE__RESOLVER__CAPSOLVER__API_KEY = "APIFUSE__RESOLVER__CAPSOLVER__API_KEY";
+export const APIFUSE__RESOLVER__CAPMONSTER__API_KEY = "APIFUSE__RESOLVER__CAPMONSTER__API_KEY";
+export const APIFUSE__RESOLVER__TIMEOUT_MS = "APIFUSE__RESOLVER__TIMEOUT_MS";
+export const APIFUSE__CDP_POOL__URL = "APIFUSE__CDP_POOL__URL";
+export const DEFAULT_RESOLVER_TIMEOUT_MS = 180_000;

package/src/runtime/resolver-shared.ts

@@ -0,0 +1,17 @@
+import { ProviderError } from "../errors.js";
+import type { ResolverContext } from "../types.js";
+
+export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
+	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",
+);
+
+export function createUnsupportedResolverClient(reason?: string): ResolverContext {
+	return {
+		async solve() {
+			throw new ProviderError(reason ?? "Resolver runtime is not configured", {
+				code: "RESOLVER_UNAVAILABLE",
+				fix: "Declare resolver on the provider definition and configure vendor credentials.",
+			});
+		},
+	};
+}