@apifuse/provider-sdk 2.2.0-beta.23 → 2.2.0-beta.25

package/src/runtime/instrumentation.ts

@@ -23,6 +23,7 @@ import {
 	getTraceRecorder,
 	type TraceContext,
 } from "./trace.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 
@@ -30,7 +31,7 @@ export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "tr
 	trace: TraceContext;
 };
 
-type InstrumentedNamespace = "http" | "stealth" | "browser" | "session" | "state";
+type InstrumentedNamespace = "http" | "stealth" | "browser" | "session" | "state" | "resolver";
 
 const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
 const DIAGNOSTIC_BASE_URL = "http://apifuse-instrumentation.invalid";
@@ -621,15 +622,47 @@ function wrapNamespace<T extends object>(
 	}
 
 	const wrappedMethods = new Map<PropertyKey, unknown>();
+	const resolverMetadata =
+		namespace === "resolver" ? { target, traceRecorder: recorder } : undefined;
 
 	return new Proxy(target, {
 		get(namespaceTarget, property, receiver) {
+			if (property === RESOLVER_INSTRUMENTATION_METADATA && resolverMetadata) {
+				return resolverMetadata;
+			}
 			const value = Reflect.get(namespaceTarget, property, receiver);
 
 			if (typeof value !== "function" || property === "constructor") {
 				return value;
 			}
 
+			if (namespace === "resolver" && property === "solve") {
+				if (wrappedMethods.has(property)) {
+					return wrappedMethods.get(property);
+				}
+
+				const wrapped = (...args: unknown[]) => {
+					const challenge = args[0];
+					const challengeKind =
+						typeof challenge === "object" &&
+						challenge !== null &&
+						"kind" in challenge &&
+						typeof challenge.kind === "string"
+							? challenge.kind
+							: undefined;
+					return recorder.runSpan(
+						"resolver.solve",
+						() => Reflect.apply(value, namespaceTarget, [args[0], args[1], recorder]),
+						{
+							attributes: challengeKind ? { challenge_kind: challengeKind } : undefined,
+						},
+					);
+				};
+
+				wrappedMethods.set(property, wrapped);
+				return wrapped;
+			}
+
 			if (namespace === "browser" && property === "newPage") {
 				if (wrappedMethods.has(property)) {
 					return wrappedMethods.get(property);
@@ -838,7 +871,8 @@ export function wrapWithInstrumentation<T extends ProviderContext>(
 				property === "stealth" ||
 				property === "browser" ||
 				property === "session" ||
-				property === "state"
+				property === "state" ||
+				property === "resolver"
 			) {
 				const namespace = property;
 				if (wrappedTargets.has(namespace)) {

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

@@ -0,0 +1,31 @@
+import type { ProviderChallenge, ProviderChallengeKind } from "../../types.js";
+import type { ResolverIssuingIdentity } from "./types.js";
+
+export const RESOLVER_CHALLENGE_BINDINGS = {
+	aws_waf: "portable",
+	cloudflare_interstitial: "identity_scoped",
+} as const satisfies Partial<
+	Readonly<Record<ProviderChallengeKind, "identity_scoped" | "portable">>
+>;
+
+export function resolverChallengeIsIdentityScoped(challenge: ProviderChallenge): boolean {
+	return (
+		RESOLVER_CHALLENGE_BINDINGS[challenge.kind as keyof typeof RESOLVER_CHALLENGE_BINDINGS] ===
+		"identity_scoped"
+	);
+}
+
+export function resolverChallengeIssuingIdentity(
+	challenge: ProviderChallenge,
+	identity: ResolverIssuingIdentity,
+): ResolverIssuingIdentity {
+	const binding = (
+		RESOLVER_CHALLENGE_BINDINGS as Partial<
+			Readonly<Record<ProviderChallengeKind, "identity_scoped" | "portable">>
+		>
+	)[challenge.kind];
+	if (binding === "portable") {
+		return { userAgent: identity.userAgent };
+	}
+	return identity;
+}

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

@@ -0,0 +1,420 @@
+import { isProviderError, ProviderError } from "../../errors.js";
+import type {
+	BrowserClient,
+	BrowserCookie,
+	BrowserPage,
+	ChallengeSolution,
+	ProviderChallenge,
+} from "../../types.js";
+import { type BrowserClientOptions, createBrowserClient } from "../browser.js";
+import type { TraceRecorder } from "../trace.js";
+import { resolverChallengeIssuingIdentity } from "./bindings.js";
+import {
+	type ResolverIdentity,
+	type ResolverVendorAdapter,
+	ResolverVendorUnavailableError,
+} from "./types.js";
+
+const BROWSER_VENDOR_ID = "browser" as const;
+const DEFAULT_COOKIE_POLL_INTERVAL_MS = 100;
+
+const SUCCESS_COOKIE_NAMES = {
+	aws_waf: "aws-waf-token",
+	cloudflare_interstitial: "cf_clearance",
+} as const;
+
+type SupportedBrowserChallengeKind = keyof typeof SUCCESS_COOKIE_NAMES;
+
+type BrowserClientFactory = (options: BrowserClientOptions) => BrowserClient;
+
+export interface BrowserResolverVendorOptions {
+	readonly cdpUrl?: string;
+	readonly timeoutMs: number;
+	readonly pollIntervalMs?: number;
+	readonly allowedHosts: readonly string[];
+	readonly createClient?: BrowserClientFactory;
+}
+
+export type BrowserResolverSolution = Extract<ChallengeSolution, { readonly form: "cookies" }> & {
+	/** Unix seconds from the cookie that proved the challenge cleared. */
+	readonly expires?: number;
+};
+
+export interface BrowserResolverVendorAdapter extends ResolverVendorAdapter {
+	readonly id: "browser";
+	solve(
+		challenge: ProviderChallenge,
+		identity: ResolverIdentity | undefined,
+		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<BrowserResolverSolution>;
+}
+
+class BrowserSolveTimeoutError extends Error {
+	constructor() {
+		super("Browser resolver solve budget elapsed");
+		this.name = "BrowserSolveTimeoutError";
+	}
+}
+
+class BrowserCleanupTimeoutError extends Error {
+	constructor(timeoutMs: number) {
+		super(`Browser resolver cleanup exceeded ${timeoutMs}ms`);
+		this.name = "BrowserCleanupTimeoutError";
+	}
+}
+
+function abortReason(signal: AbortSignal): unknown {
+	return signal.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+function raceWithAbort<T>(operation: () => Promise<T>, signal: AbortSignal): Promise<T> {
+	if (signal.aborted) {
+		return Promise.reject(abortReason(signal));
+	}
+
+	return new Promise<T>((resolve, reject) => {
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		const onAbort = () => {
+			cleanup();
+			reject(abortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation().then(
+			(value) => {
+				cleanup();
+				resolve(value);
+			},
+			(error: unknown) => {
+				cleanup();
+				reject(error);
+			},
+		);
+	});
+}
+
+async function runBoundedCleanup(
+	cleanup: () => Promise<unknown>,
+	timeoutMs: number,
+	challengeKind: ProviderChallenge["kind"],
+	operation: "client.close" | "context.close",
+	traceRecorder: TraceRecorder | undefined,
+): Promise<void> {
+	let timeout: ReturnType<typeof setTimeout> | undefined;
+	const boundedCleanup = async () => {
+		try {
+			await Promise.race([
+				cleanup(),
+				new Promise<never>((_resolve, reject) => {
+					timeout = setTimeout(() => reject(new BrowserCleanupTimeoutError(timeoutMs)), timeoutMs);
+				}),
+			]);
+		} finally {
+			if (timeout !== undefined) clearTimeout(timeout);
+		}
+	};
+
+	if (!traceRecorder) {
+		await boundedCleanup().catch(() => undefined);
+		return;
+	}
+
+	await traceRecorder
+		.runSpan("resolver.vendor.cleanup", boundedCleanup, {
+			attributes: {
+				vendor: BROWSER_VENDOR_ID,
+				challenge_kind: challengeKind,
+				operation,
+			},
+			onError(error) {
+				return {
+					error_message: error instanceof Error ? error.message : String(error),
+					...(error instanceof Error && error.stack ? { error_stack: error.stack } : {}),
+				};
+			},
+		})
+		.catch(() => undefined);
+}
+
+async function abortableDelay(ms: number, signal: AbortSignal): Promise<void> {
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	try {
+		await raceWithAbort(
+			() =>
+				new Promise<void>((resolve) => {
+					timer = setTimeout(resolve, ms);
+				}),
+			signal,
+		);
+	} finally {
+		if (timer !== undefined) clearTimeout(timer);
+	}
+}
+
+function isSupportedKind(kind: string): kind is SupportedBrowserChallengeKind {
+	return Object.hasOwn(SUCCESS_COOKIE_NAMES, kind);
+}
+
+function normalizedHostname(hostname: string): string {
+	return hostname.trim().toLowerCase().replace(/\.$/, "");
+}
+
+function assertChallengeHostAllowed(pageUrl: string, allowedHosts: readonly string[]): void {
+	const challengeHost = normalizedHostname(new URL(pageUrl).hostname);
+	const isAllowed = allowedHosts.some((host) => {
+		const declaredHost = normalizedHostname(host);
+		return declaredHost.length > 0 && !declaredHost.includes("*") && declaredHost === challengeHost;
+	});
+	if (isAllowed) return;
+
+	throw new ProviderError(`Resolver challenge host "${challengeHost}" is not declared`, {
+		code: "RESOLVER_HOST_NOT_ALLOWED",
+		fix: "Add the exact challenge hostname to the provider's allowedHosts declaration.",
+	});
+}
+
+function cookieDomainSpecificity(cookie: BrowserCookie): number {
+	return normalizedHostname(cookie.domain.replace(/^\./, "")).length;
+}
+
+function isHostOnlyCookieFor(cookie: BrowserCookie, hostname: string): boolean {
+	return (
+		!cookie.domain.startsWith(".") &&
+		normalizedHostname(cookie.domain) === normalizedHostname(hostname)
+	);
+}
+
+function cookieAppliesToUrl(cookie: BrowserCookie, url: URL): boolean {
+	const cookieDomain = normalizedHostname(cookie.domain.replace(/^\./, ""));
+	const requestHostname = normalizedHostname(url.hostname);
+	const domainMatches =
+		cookieDomain.length > 0 &&
+		(requestHostname === cookieDomain ||
+			(cookie.domain.startsWith(".") && requestHostname.endsWith(`.${cookieDomain}`)));
+	if (!domainMatches || (cookie.secure && url.protocol !== "https:")) return false;
+
+	const requestPath = url.pathname || "/";
+	const cookiePath = cookie.path;
+	return (
+		cookiePath.startsWith("/") &&
+		(requestPath === cookiePath ||
+			(requestPath.startsWith(cookiePath) &&
+				(cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/")))
+	);
+}
+
+function selectSuccessCookie(
+	cookies: readonly BrowserCookie[],
+	successCookieName: string,
+	pageUrl: string,
+): BrowserCookie | undefined {
+	const url = new URL(pageUrl);
+	return cookies
+		.filter((cookie) => cookie.name === successCookieName && cookieAppliesToUrl(cookie, url))
+		.sort(
+			(left, right) =>
+				Number(isHostOnlyCookieFor(right, url.hostname)) -
+					Number(isHostOnlyCookieFor(left, url.hostname)) ||
+				cookieDomainSpecificity(right) - cookieDomainSpecificity(left) ||
+				right.path.length - left.path.length,
+		)[0];
+}
+
+async function solveInPage(
+	page: BrowserPage,
+	pageUrl: string,
+	successCookieName: string,
+	pollIntervalMs: number,
+	signal: AbortSignal,
+): Promise<BrowserResolverSolution> {
+	await raceWithAbort(() => page.goto(pageUrl), signal);
+
+	while (true) {
+		const cookies = await raceWithAbort(() => page.cookies(), signal);
+		const successCookie = selectSuccessCookie(cookies, successCookieName, pageUrl);
+		if (successCookie) {
+			const userAgent = await raceWithAbort(
+				() => page.evaluate<string>("navigator.userAgent"),
+				signal,
+			);
+			return {
+				form: "cookies",
+				cookies: { [successCookieName]: successCookie.value },
+				userAgent,
+				...(successCookie.expires === undefined ? {} : { expires: successCookie.expires }),
+			};
+		}
+
+		await abortableDelay(pollIntervalMs, signal);
+	}
+}
+
+const POOL_ALLOCATION_EXHAUSTED_CODES = new Set([
+	-32_001, // queue full
+	-32_002, // acquire timed out
+	-32_003, // shutting down
+]);
+
+function poolErrorCode(error: Error): number | undefined {
+	const code = (error as Error & { readonly code?: unknown }).code;
+	return typeof code === "number" ? code : undefined;
+}
+
+function knownUnavailableReason(
+	error: unknown,
+): "allocation_exhausted" | "missing_credentials" | "transport_failure" | undefined {
+	// Source-grounded mappings:
+	// - apps/cdp-pool/src/index.ts: the JSON-RPC codes and messages below.
+	// - src/runtime/browser.ts: BROWSER_CDP_POOL_REQUIRED and the two WebSocket messages.
+	// The pool's numeric JSON-RPC code is authoritative and is preferred whenever present.
+	// The message substrings remain as a fallback for pool builds predating code
+	// propagation; they are exact strings verified against the pool source. -32004 (unknown
+	// lease) and -32006 (missing allowedHosts) are deliberately unmapped: both are caller
+	// bugs, and the next vendor would fail identically, so they propagate unchanged.
+	if (isProviderError(error)) {
+		return error.code === "BROWSER_CDP_POOL_REQUIRED" ? "missing_credentials" : undefined;
+	}
+	if (!(error instanceof Error)) return undefined;
+
+	const code = poolErrorCode(error);
+	if (code !== undefined) {
+		return POOL_ALLOCATION_EXHAUSTED_CODES.has(code) ? "allocation_exhausted" : undefined;
+	}
+
+	if (
+		error.message.includes("CDP pool acquire queue is full") ||
+		error.message.includes("CDP pool acquire timed out") ||
+		error.message.includes("CDP pool is shutting down")
+	) {
+		return "allocation_exhausted";
+	}
+
+	if (
+		error.message.includes("Unable to connect to WebSocket endpoint") ||
+		error.message.includes("WebSocket closed")
+	) {
+		return "transport_failure";
+	}
+
+	return undefined;
+}
+
+async function closeBrowserClient(
+	client: BrowserClient | undefined,
+	timeoutMs: number,
+	challengeKind: ProviderChallenge["kind"],
+	traceRecorder: TraceRecorder | undefined,
+): Promise<void> {
+	const close = client?.close;
+	if (!close) return;
+	await runBoundedCleanup(
+		() => close.call(client),
+		timeoutMs,
+		challengeKind,
+		"client.close",
+		traceRecorder,
+	);
+}
+
+export function createBrowserResolverVendorAdapter(
+	options: BrowserResolverVendorOptions,
+): BrowserResolverVendorAdapter {
+	const createClient = options.createClient ?? createBrowserClient;
+	const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_COOKIE_POLL_INTERVAL_MS;
+
+	return {
+		id: BROWSER_VENDOR_ID,
+
+		supports(kind) {
+			return isSupportedKind(kind);
+		},
+
+		getIssuingIdentity(solution, requestedIdentity, challenge) {
+			if (solution.form !== "cookies" || !isSupportedKind(challenge.kind)) return undefined;
+			return resolverChallengeIssuingIdentity(challenge, {
+				...(requestedIdentity ? { proxyUrl: requestedIdentity.proxyUrl } : {}),
+				userAgent: solution.userAgent,
+			});
+		},
+
+		async solve(challenge, identity, callerSignal, traceRecorder) {
+			void identity;
+			if (!options.cdpUrl?.trim()) {
+				throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "missing_credentials");
+			}
+			if (!isSupportedKind(challenge.kind)) {
+				throw new TypeError(`Browser resolver does not support ${challenge.kind}`);
+			}
+			assertChallengeHostAllowed(challenge.pageUrl, options.allowedHosts);
+			const challengeKind = challenge.kind;
+			callerSignal.throwIfAborted();
+
+			const solveController = new AbortController();
+			const onCallerAbort = () => solveController.abort(abortReason(callerSignal));
+			callerSignal.addEventListener("abort", onCallerAbort, { once: true });
+			const timeout = setTimeout(
+				() => solveController.abort(new BrowserSolveTimeoutError()),
+				options.timeoutMs,
+			);
+
+			let client: BrowserClient | undefined;
+			let handlerEntered = false;
+			try {
+				client = createClient({
+					allowedHosts: [...options.allowedHosts],
+					cdpUrl: options.cdpUrl.trim(),
+					requireCdpPool: true,
+				});
+				const contextOperation = client.withIsolatedContext(async (page) => {
+					handlerEntered = true;
+					return await solveInPage(
+						page,
+						challenge.pageUrl,
+						SUCCESS_COOKIE_NAMES[challengeKind],
+						pollIntervalMs,
+						solveController.signal,
+					);
+				});
+
+				try {
+					return await raceWithAbort(() => contextOperation, solveController.signal);
+				} catch (error) {
+					if (solveController.signal.aborted) {
+						if (handlerEntered) {
+							await runBoundedCleanup(
+								() => contextOperation,
+								options.timeoutMs,
+								challengeKind,
+								"context.close",
+								traceRecorder,
+							);
+							throw error;
+						}
+						await closeBrowserClient(client, options.timeoutMs, challengeKind, traceRecorder);
+						void contextOperation.catch(() => undefined);
+					}
+					throw error;
+				}
+			} catch (error) {
+				if (callerSignal.aborted) throw abortReason(callerSignal);
+				if (error instanceof BrowserSolveTimeoutError) {
+					throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, "timeout", {
+						cause: error,
+					});
+				}
+				if (error instanceof ResolverVendorUnavailableError) {
+					throw error;
+				}
+				const reason = knownUnavailableReason(error);
+				if (reason) {
+					throw new ResolverVendorUnavailableError(BROWSER_VENDOR_ID, reason, { cause: error });
+				}
+				throw error;
+			} finally {
+				clearTimeout(timeout);
+				callerSignal.removeEventListener("abort", onCallerAbort);
+				await closeBrowserClient(client, options.timeoutMs, challengeKind, traceRecorder);
+			}
+		},
+	};
+}

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

@@ -0,0 +1,113 @@
+import type {
+	ChallengeSolution,
+	ProviderChallenge,
+	ProviderChallengeKind,
+	ProviderResolverVendor,
+} from "../../types.js";
+import type { TraceRecorder } from "../trace.js";
+
+export const RESOLVER_VENDOR_CAPABILITIES = {
+	browser: ["aws_waf", "cloudflare_interstitial"],
+	"2captcha": [
+		"turnstile",
+		"recaptcha_v2",
+		"recaptcha_v3",
+		"hcaptcha",
+		"cloudflare_interstitial",
+		"aws_waf",
+	],
+	capsolver: [
+		"turnstile",
+		"recaptcha_v2",
+		"recaptcha_v3",
+		"hcaptcha",
+		"cloudflare_interstitial",
+		"aws_waf",
+	],
+	capmonster: ["turnstile", "recaptcha_v2", "recaptcha_v3", "hcaptcha"],
+	custom: [
+		"turnstile",
+		"recaptcha_v2",
+		"recaptcha_v3",
+		"hcaptcha",
+		"cloudflare_interstitial",
+		"aws_waf",
+	],
+} as const satisfies Readonly<Record<ProviderResolverVendor, readonly ProviderChallengeKind[]>>;
+
+export function resolverVendorSupports(
+	vendor: ProviderResolverVendor,
+	kind: ProviderChallengeKind,
+): boolean {
+	return (RESOLVER_VENDOR_CAPABILITIES[vendor] as readonly ProviderChallengeKind[]).includes(kind);
+}
+
+export interface ResolverIdentity {
+	readonly proxyUrl: string;
+	readonly userAgent: string;
+}
+
+export interface ResolverIssuingIdentity {
+	/** Absent when the adapter genuinely solved without a proxy. */
+	readonly proxyUrl?: string;
+	readonly userAgent: string;
+}
+
+export interface ResolverVendorAdapter {
+	readonly id: ProviderResolverVendor;
+	supports(kind: ProviderChallengeKind): boolean;
+	/** Identity the adapter actually used, reported after a successful solve. */
+	getIssuingIdentity?(
+		solution: ChallengeSolution,
+		requestedIdentity: ResolverIdentity | undefined,
+		challenge: ProviderChallenge,
+	): ResolverIssuingIdentity | undefined;
+	solve(
+		challenge: ProviderChallenge,
+		identity: ResolverIdentity | undefined,
+		signal: AbortSignal,
+		traceRecorder?: TraceRecorder,
+	): Promise<ChallengeSolution>;
+}
+
+export type ResolverVendorUnavailableReason =
+	| "missing_credentials"
+	| "missing_transport"
+	| "allocation_exhausted"
+	| "transport_failure"
+	| "timeout"
+	| "not_implemented";
+
+export type ResolverChallengeVerdictReason = "human_puzzle";
+
+type ResolverErrorOptions = {
+	readonly cause?: unknown;
+};
+
+export class ResolverVendorUnavailableError extends Error {
+	constructor(
+		readonly vendor: ProviderResolverVendor,
+		readonly reason: ResolverVendorUnavailableReason,
+		options: ResolverErrorOptions = {},
+	) {
+		super(`Resolver vendor ${vendor} is unavailable: ${reason}`);
+		this.name = "ResolverVendorUnavailableError";
+		if (options.cause !== undefined) {
+			this.cause = options.cause;
+		}
+	}
+}
+
+export class ResolverChallengeVerdictError extends Error {
+	constructor(
+		readonly vendor: ProviderResolverVendor,
+		readonly reason: ResolverChallengeVerdictReason,
+		options: ResolverErrorOptions = {},
+	) {
+		super(`Resolver vendor ${vendor} returned a challenge verdict: ${reason}`);
+		this.name = "ResolverChallengeVerdictError";
+		if (options.cause !== undefined) {
+			this.cause = options.cause;
+		}
+	}
+}