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

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.",
+			});
+		},
+	};
+}

package/src/runtime/resolver-vendors/twocaptcha.ts

@@ -1,4 +1,5 @@
 import type { ChallengeSolution, ProviderChallenge } from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
 import { assertResolverHostAllowed } from "./hosts.js";
 import {
 	type ResolverIdentity,
@@ -34,6 +35,7 @@ export interface TwoCaptchaResolverVendorAdapter extends ResolverVendorAdapter {
 		challenge: ProviderChallenge,
 		identity: ResolverIdentity | undefined,
 		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
 	): Promise<Extract<ChallengeSolution, { readonly form: "token" }>>;
 }
 
@@ -231,6 +233,28 @@ function endpoint(baseUrl: string, path: string): string {
 	return `${baseUrl.replace(/\/+$/u, "")}/${path}`;
 }
 
+function spanErrorAttributes(
+	error: unknown,
+	phase: TwoCaptchaOperationPhase,
+): Record<string, unknown> | undefined {
+	if (error instanceof ResolverVendorUnavailableError) {
+		return {
+			unavailability_reason: error.reason,
+			transport_phase: error.phase,
+		};
+	}
+	// The solve budget raises TwoCaptchaSolveTimeoutError inside the spanned closure and
+	// the outer catch converts it only after the span has been finalized, so the span has
+	// to recognize it here or slow solves lose exactly the attribution these spans add.
+	if (error instanceof TwoCaptchaSolveTimeoutError) {
+		return {
+			unavailability_reason: "timeout",
+			transport_phase: phase,
+		};
+	}
+	return undefined;
+}
+
 export function createTwoCaptchaResolverVendorAdapter(
 	options: TwoCaptchaResolverVendorOptions,
 ): TwoCaptchaResolverVendorAdapter {
@@ -248,7 +272,7 @@ export function createTwoCaptchaResolverVendorAdapter(
 			return resolverVendorSupports(TWOCAPTCHA_VENDOR_ID, kind);
 		},
 
-		async solve(challenge, identity, callerSignal) {
+		async solve(challenge, identity, callerSignal, traceRecorder) {
 			const apiKey = options.apiKey?.trim();
 			if (!apiKey) {
 				throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "missing_credentials", {
@@ -285,62 +309,89 @@ export function createTwoCaptchaResolverVendorAdapter(
 			let phase: TwoCaptchaOperationPhase = "create_task";
 
 			try {
-				const createResult = await postJson(
-					fetchImpl,
-					endpoint(baseUrl, "createTask"),
-					{
-						clientKey: apiKey,
-						task: {
-							type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
-							websiteURL: challenge.pageUrl,
-							websiteKey: challenge.siteKey,
-							isInvisible: false,
-							...(identity ? { userAgent: identity.userAgent } : {}),
-							...(proxy ?? {}),
-						},
-					},
-					solveController.signal,
-					phase,
-				);
-				const taskId = taskIdFrom(createResult.payload);
-				if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
-					throw unavailableForPayload(createResult.payload, phase);
-				}
-
-				phase = "poll_result";
-				while (true) {
-					callerSignal.throwIfAborted();
-					const remainingMs = timeoutMs - (now() - startedAt);
-					if (remainingMs <= 0) throw new TwoCaptchaSolveTimeoutError();
-					await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
-					callerSignal.throwIfAborted();
-					if (now() - startedAt >= timeoutMs) throw new TwoCaptchaSolveTimeoutError();
-
-					const pollResult = await postJson(
+				const createTask = async () => {
+					const createResult = await postJson(
 						fetchImpl,
-						endpoint(baseUrl, "getTaskResult"),
-						{ clientKey: apiKey, taskId },
+						endpoint(baseUrl, "createTask"),
+						{
+							clientKey: apiKey,
+							task: {
+								type: proxy ? "RecaptchaV2Task" : "RecaptchaV2TaskProxyless",
+								websiteURL: challenge.pageUrl,
+								websiteKey: challenge.siteKey,
+								isInvisible: false,
+								...(identity ? { userAgent: identity.userAgent } : {}),
+								...(proxy ?? {}),
+							},
+						},
 						solveController.signal,
 						phase,
 					);
-					if (!pollResult.ok || pollResult.payload.errorId !== 0) {
-						throw unavailableForPayload(pollResult.payload, phase);
-					}
-					if (pollResult.payload.status === "processing") continue;
-					if (pollResult.payload.status !== "ready") {
-						throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
-							phase,
-						});
+					const taskId = taskIdFrom(createResult.payload);
+					if (!createResult.ok || createResult.payload.errorId !== 0 || taskId === undefined) {
+						throw unavailableForPayload(createResult.payload, phase);
 					}
+					return taskId;
+				};
+				const taskId = traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.create_task", createTask, {
+							attributes: {
+								vendor: TWOCAPTCHA_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "create_task"),
+						})
+					: await createTask();
 
-					const token = tokenFrom(pollResult.payload);
-					if (!token?.trim()) {
-						throw new ResolverVendorUnavailableError(TWOCAPTCHA_VENDOR_ID, "transport_failure", {
+				phase = "poll_result";
+				const pollResult = async () => {
+					while (true) {
+						callerSignal.throwIfAborted();
+						const remainingMs = timeoutMs - (now() - startedAt);
+						if (remainingMs <= 0) throw new TwoCaptchaSolveTimeoutError();
+						await delay(Math.min(pollIntervalMs, remainingMs), solveController.signal);
+						callerSignal.throwIfAborted();
+						if (now() - startedAt >= timeoutMs) throw new TwoCaptchaSolveTimeoutError();
+
+						const pollResult = await postJson(
+							fetchImpl,
+							endpoint(baseUrl, "getTaskResult"),
+							{ clientKey: apiKey, taskId },
+							solveController.signal,
 							phase,
-						});
+						);
+						if (!pollResult.ok || pollResult.payload.errorId !== 0) {
+							throw unavailableForPayload(pollResult.payload, phase);
+						}
+						if (pollResult.payload.status === "processing") continue;
+						if (pollResult.payload.status !== "ready") {
+							throw new ResolverVendorUnavailableError(
+								TWOCAPTCHA_VENDOR_ID,
+								"transport_failure",
+								{ phase },
+							);
+						}
+
+						const token = tokenFrom(pollResult.payload);
+						if (!token?.trim()) {
+							throw new ResolverVendorUnavailableError(
+								TWOCAPTCHA_VENDOR_ID,
+								"transport_failure",
+								{ phase },
+							);
+						}
+						return { form: "token" as const, token };
 					}
-					return { form: "token", token };
-				}
+				};
+				return traceRecorder
+					? await traceRecorder.runSpan("resolver.vendor.poll_result", pollResult, {
+							attributes: {
+								vendor: TWOCAPTCHA_VENDOR_ID,
+								challenge_kind: challenge.kind,
+							},
+							onError: (error) => spanErrorAttributes(error, "poll_result"),
+						})
+					: await pollResult();
 			} catch (error) {
 				if (callerSignal.aborted) throw abortReason(callerSignal);
 				if (

package/src/runtime/resolver-vendors/types.ts

@@ -112,6 +112,7 @@ export interface ResolverVendorAdapter {
 
 export type ResolverVendorUnavailableReason =
 	| "missing_credentials"
+	| "missing_proxy_identity"
 	| "missing_transport"
 	| "allocation_exhausted"
 	| "transport_failure"

package/src/runtime/resolver.ts

@@ -6,6 +6,7 @@ import type {
 	ProviderCache,
 	ProviderChallenge,
 	ProviderChallengeKind,
+	ProviderProxyMode,
 	ProviderResolverConfig,
 	ProviderResolverVendor,
 	ResolverContext,
@@ -29,14 +30,32 @@ import {
 	type ResolverVendorUnavailableReason,
 	resolverVendorSupports,
 } from "./resolver-vendors/types.js";
+import {
+	createUnsupportedResolverClient,
+	RESOLVER_INSTRUMENTATION_METADATA,
+} from "./resolver-shared.js";
+import {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+} from "./resolver-config.js";
 import type { TraceRecorder } from "./trace.js";
 
-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;
+export {
+	createUnsupportedResolverClient,
+	RESOLVER_INSTRUMENTATION_METADATA,
+} from "./resolver-shared.js";
+export {
+	APIFUSE__CDP_POOL__URL,
+	APIFUSE__RESOLVER__2CAPTCHA__API_KEY,
+	APIFUSE__RESOLVER__CAPMONSTER__API_KEY,
+	APIFUSE__RESOLVER__CAPSOLVER__API_KEY,
+	APIFUSE__RESOLVER__TIMEOUT_MS,
+	DEFAULT_RESOLVER_TIMEOUT_MS,
+} from "./resolver-config.js";
 
 type EnvLike = Record<string, string | undefined>;
 
@@ -75,6 +94,8 @@ type ResolverChainClient = ResolverContext & {
 export interface ResolverRuntimeOptions {
 	readonly allowedHosts?: readonly string[];
 	readonly cache?: ProviderCache;
+	/** Provider-declared proxy intent. The SDK never accepts a caller-built identity. */
+	readonly proxyMode?: ProviderProxyMode;
 	/** Server-owned context/proxy scope used only for identity-bound cache entries. */
 	readonly identityScope?: string;
 	/** SDK-owned transport already bound to the resolved proxy lease and client profile. */
@@ -143,10 +164,6 @@ const SAFE_CAUSE_MESSAGE_WORDS: ReadonlySet<string> = new Set([
 	"writing",
 ]);
 
-export const RESOLVER_INSTRUMENTATION_METADATA = Symbol.for(
-	"@apifuse/provider-sdk/runtime/resolver-instrumentation-metadata",
-);
-
 export type ResolverInstrumentationMetadata = {
 	readonly target: ResolverContext;
 	readonly traceRecorder: TraceRecorder;
@@ -340,7 +357,9 @@ function sanitizeCauseMessage(message: string): string {
 		.map((token) => {
 			if (token === "[REDACTED]" || /^[a-z][a-z\d+.-]*:\/\/[^\s]+$/i.test(token)) return token;
 			const word = token.replace(/^[^a-z\d]+|[^a-z\d]+$/gi, "");
-			return word.length > 0 && word.length <= 32 && SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
+			return word.length > 0 &&
+				word.length <= 32 &&
+				SAFE_CAUSE_MESSAGE_WORDS.has(word.toLowerCase())
 				? token
 				: "[REDACTED]";
 		});
@@ -691,6 +710,7 @@ function createResolverChainClient(options: {
 	readonly unavailableReason?: string;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
+	readonly proxyMode?: ProviderProxyMode;
 	readonly identityScope?: string;
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
@@ -715,6 +735,19 @@ function createResolverChainClient(options: {
 			const supportingEntries = options.entries.filter((entry) => entry.supports(challenge.kind));
 			if (supportingEntries.length === 0) throwUnsupportedKind(challenge.kind);
 			signal.throwIfAborted();
+			// A required proxy policy is checked before the cache. Solutions minted under a
+			// previous release are shared and long-lived, so consulting the cache first would
+			// keep reporting success without a proxy identity until every old entry expired.
+			const requiredProxyIdentityMissing =
+				options.proxyMode === "required" && options.identity === undefined;
+			if (requiredProxyIdentityMissing) {
+				throwExhausted(
+					supportingEntries.map((entry) => ({
+						vendor: entry.id,
+						reason: "missing_proxy_identity" as const,
+					})),
+				);
+			}
 			if (options.cache && resolverChallengeIsCacheable(challenge)) {
 				const cached = await findCachedSolution(
 					options.cache,
@@ -804,6 +837,7 @@ export function createResolverClient(options: {
 	readonly unavailableReason?: string;
 	readonly cache?: ProviderCache;
 	readonly identity?: ResolverIdentity;
+	readonly proxyMode?: ProviderProxyMode;
 	readonly transport?: ResolverVendorTransport;
 	readonly createTransport?: ResolverRuntimeOptions["createTransport"];
 	readonly clientProfile?: string;
@@ -819,6 +853,7 @@ export function createResolverClient(options: {
 		unavailableReason: options.unavailableReason,
 		cache: options.cache,
 		identity: options.identity,
+		proxyMode: options.proxyMode,
 		transport: options.transport,
 		createTransport: options.createTransport,
 		clientProfile: options.clientProfile,
@@ -853,17 +888,6 @@ function resolveVendorAvailability(
 		: { vendor, available: false, reason: "missing_credentials" };
 }
 
-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.",
-			});
-		},
-	};
-}
-
 export function bindResolverSignal(
 	resolver: ResolverContext,
 	defaultSignal: AbortSignal | undefined,
@@ -921,6 +945,7 @@ function createResolverClientFromEnvInternal(
 			};
 		}),
 		cache: options.cache,
+		proxyMode: options.proxyMode,
 		identityScope: options.identityScope,
 		transport: options.transport,
 		createTransport: options.createTransport,