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

package/src/runtime/resolver.ts

@@ -29,7 +29,10 @@ import {
 import { createBrowserResolverVendorAdapter } from "./resolver-vendors/browser.js";
 import { createCapsolverResolverVendorAdapter } from "./resolver-vendors/capsolver.js";
 import { createHypersolutionsResolverVendorAdapter } from "./resolver-vendors/hypersolutions.js";
-import { assertResolverHostAllowed } from "./resolver-vendors/hosts.js";
+import {
+	assertResolverHostAllowed,
+	assertResolverVendorTransportHosts,
+} from "./resolver-vendors/hosts.js";
 import { createTwoCaptchaResolverVendorAdapter } from "./resolver-vendors/twocaptcha.js";
 import {
 	RESOLVER_VENDOR_CAPABILITIES,
@@ -63,6 +66,7 @@ import {
 } from "./resolver-config.js";
 import { DEFAULT_STEALTH_PROFILE } from "./stealth.js";
 import type { TraceRecorder } from "./trace.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
 import type {
 	ResolverTelemetryErrorClass,
 	ResolverTelemetryPhase,
@@ -127,6 +131,8 @@ export interface ResolverRuntimeOptions {
 	readonly cache?: ProviderCache;
 	/** Optional request-scoped observability sink; never used as resolver identity. */
 	readonly telemetry?: ResolverTelemetrySink;
+	/** Request-scoped browser sink used by the resolver-owned browser vendor. */
+	readonly browserTelemetry?: BrowserTelemetrySink;
 	/** Inputs for SDK-owned lazy proxy resolution. The SDK never accepts a caller-built identity. */
 	readonly proxyIntent?: {
 		readonly mode: ProviderProxyMode;
@@ -222,6 +228,7 @@ export type ResolverAdapterFactory = (
 	configuration: string | undefined,
 	timeoutMs: number,
 	allowedHosts: readonly string[],
+	telemetry?: BrowserTelemetrySink,
 ) => ResolverVendorAdapter;
 
 const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAdapterFactory>> = {
@@ -242,11 +249,12 @@ const resolverAdapterRegistry: Partial<Record<ProviderResolverVendor, ResolverAd
 			timeoutMs,
 		});
 	},
-	browser(configuration, timeoutMs, allowedHosts) {
+	browser(configuration, timeoutMs, allowedHosts, telemetry) {
 		return createBrowserResolverVendorAdapter({
 			allowedHosts,
 			cdpUrl: configuration,
 			timeoutMs,
+			telemetry,
 		});
 	},
 	hypersolutions(configuration, timeoutMs, allowedHosts) {
@@ -306,7 +314,7 @@ const KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS: ReadonlySet<ProviderResolverVendor>
 type ResolverChainEntry = {
 	readonly id: ProviderResolverVendor;
 	supports(kind: ProviderChallengeKind): boolean;
-	createAdapter(): ResolverVendorAdapter;
+	createAdapter(browserTelemetry?: BrowserTelemetrySink): ResolverVendorAdapter;
 };
 
 function normalizedEnvValue(env: EnvLike, key: string): string | undefined {
@@ -365,6 +373,7 @@ function createAdapter(
 	timeoutMs: number,
 	allowedHosts: readonly string[],
 	adapterFactories: Partial<Readonly<Record<ProviderResolverVendor, ResolverAdapterFactory>>>,
+	browserTelemetry?: BrowserTelemetrySink,
 ): ResolverVendorAdapter {
 	const factory = adapterFactories[vendor.vendor];
 	if (!factory && !KNOWN_UNIMPLEMENTED_RESOLVER_VENDORS.has(vendor.vendor)) {
@@ -377,7 +386,7 @@ function createAdapter(
 	}
 
 	if (factory) {
-		return factory(vendor.configuration, timeoutMs, allowedHosts);
+		return factory(vendor.configuration, timeoutMs, allowedHosts, browserTelemetry);
 	}
 	return createUnavailableAdapter(vendor.vendor, "not_implemented");
 }
@@ -480,15 +489,26 @@ function sanitizeCauseMessage(message: string): string {
 		.slice(0, 512);
 }
 
+function assertResolverTransportLive(revoked: boolean): void {
+	if (!revoked) return;
+	throw new ProviderError("Resolver transport was revoked when the vendor solve settled", {
+		code: "RESOLVER_TRANSPORT_REVOKED",
+		fix: "Complete every bound-transport call before solve() settles; the transport is per-attempt and must not be retained.",
+	});
+}
+
 function restrictResolverTransport(
 	transport: ResolverVendorTransport,
 	allowedHosts: readonly string[],
-): ResolverVendorTransport {
-	return {
+): { readonly transport: ResolverVendorTransport; revoke(): void } {
+	// A retained reference must fail closed once the adapter's solve has settled.
+	let revoked = false;
+	const restricted: ResolverVendorTransport = {
 		sessionHeaders: transport.sessionHeaders,
 		...(transport.getCookie
 			? {
 					getCookie(name, url) {
+						assertResolverTransportLive(revoked);
 						// Jar reads are gated like fetches: an adapter may only read state for declared hosts.
 						assertResolverHostAllowed(url, allowedHosts);
 						return transport.getCookie?.(name, url);
@@ -496,6 +516,7 @@ function restrictResolverTransport(
 				}
 			: {}),
 		async fetch(url, init) {
+			assertResolverTransportLive(revoked);
 			// Empty declarations remain deny-by-default, matching the adapter-factory/browser path.
 			assertResolverHostAllowed(url, allowedHosts);
 			const response = await transport.fetch(url, { ...init, redirect: "manual" });
@@ -511,6 +532,12 @@ function restrictResolverTransport(
 			return response;
 		},
 	};
+	return {
+		transport: restricted,
+		revoke() {
+			revoked = true;
+		},
+	};
 }
 
 function safeCause(error: ResolverVendorUnavailableError): ResolverChainAttempt["cause"] {
@@ -1042,7 +1069,8 @@ async function resolveResolverIdentity(
 }
 
 function createChainTelemetryBinding(options: Parameters<typeof createResolverChainClient>[0]) {
-	return (telemetry: ResolverTelemetrySink) => createResolverChainClient({ ...options, telemetry });
+	return (telemetry: ResolverTelemetrySink, browserTelemetry?: BrowserTelemetrySink) =>
+		createResolverChainClient({ ...options, telemetry, browserTelemetry });
 }
 
 function createResolverChainClient(options: {
@@ -1059,6 +1087,7 @@ function createResolverChainClient(options: {
 	readonly clientProfile?: string;
 	readonly allowedHosts?: readonly string[];
 	readonly telemetry?: ResolverTelemetrySink;
+	readonly browserTelemetry?: BrowserTelemetrySink;
 }): ResolverChainClient {
 	assertClientProfileTransportContract(options.clientProfile, options.transport);
 	const cache =
@@ -1167,7 +1196,7 @@ function createResolverChainClient(options: {
 				}
 				const attempts: ResolverChainAttempt[] = [];
 				for (const [entryIndex, entry] of supportingEntries.entries()) {
-					const adapter = entry.createAdapter();
+					const adapter = entry.createAdapter(options.browserTelemetry);
 					const attemptStartedAt = Date.now();
 					const diagnostics: ResolverAttemptDiagnostics = {};
 					const telemetryTraceRecorder = createResolverTelemetryTraceRecorder({
@@ -1179,7 +1208,11 @@ function createResolverChainClient(options: {
 					});
 					let solution: ChallengeSolution;
 					try {
-						const solveAttempt = () => {
+						const solveAttempt = async () => {
+							// Boundary first: an overreaching declaration is a caller fault even when no
+							// transport is configured, not a "missing_transport" vendor unavailability.
+							const adapterHosts = adapter.transportAllowedHosts ?? [];
+							assertResolverVendorTransportHosts(adapter.id, adapterHosts);
 							const requiresTransport = adapterRequiresTransport(adapter, challenge.kind);
 							const unrestrictedTransport =
 								options.transport ??
@@ -1192,10 +1225,10 @@ function createResolverChainClient(options: {
 							if (requiresTransport && unrestrictedTransport === undefined) {
 								throw new ResolverVendorUnavailableError(adapter.id, "missing_transport");
 							}
-							const transport = unrestrictedTransport
+							const boundTransport = unrestrictedTransport
 								? restrictResolverTransport(unrestrictedTransport, [
 										...(options.allowedHosts ?? []),
-										...(adapter.transportAllowedHosts ?? []),
+										...adapterHosts,
 									])
 								: undefined;
 							const usage: ResolverPaidUsageContext = {
@@ -1209,14 +1242,18 @@ function createResolverChainClient(options: {
 										}
 									: {}),
 							};
-							return adapter.solve(
-								challenge,
-								identity,
-								signal,
-								telemetryTraceRecorder,
-								transport,
-								usage,
-							);
+							try {
+								return await adapter.solve(
+									challenge,
+									identity,
+									signal,
+									telemetryTraceRecorder,
+									boundTransport?.transport,
+									usage,
+								);
+							} finally {
+								boundTransport?.revoke();
+							}
 						};
 						solution = traceRecorder
 							? await traceRecorder.runSpan("resolver.vendor.attempt", solveAttempt, {
@@ -1334,7 +1371,7 @@ function createResolverChainClient(options: {
 		},
 	};
 	resolverCaches.set(client, cache ?? null);
-	const reusableOptions = { ...options, telemetry: undefined };
+	const reusableOptions = { ...options, telemetry: undefined, browserTelemetry: undefined };
 	registerResolverTelemetryBinding(client, createChainTelemetryBinding(reusableOptions));
 	return client;
 }
@@ -1352,6 +1389,10 @@ export function createResolverClient(options: {
 	readonly allowedHosts?: readonly string[];
 	readonly telemetry?: ResolverTelemetrySink;
 }): ResolverChainClient {
+	for (const adapter of options.adapters) {
+		// Fail at construction, not on the first solve, when a supplied adapter oversteps its vendor.
+		assertResolverVendorTransportHosts(adapter.id, adapter.transportAllowedHosts ?? []);
+	}
 	return createResolverChainClient({
 		kinds: options.kinds,
 		entries: options.adapters.map((adapter) => ({
@@ -1459,12 +1500,13 @@ function createResolverClientFromEnvInternal(
 			return {
 				id: vendor,
 				supports: (kind: ProviderChallengeKind) => resolverVendorSupports(vendor, kind),
-				createAdapter: () =>
+				createAdapter: (browserTelemetry) =>
 					createAdapter(
 						resolveVendorAvailability(vendor, env),
 						timeoutMs,
 						allowedHosts,
 						adapterFactories,
+						browserTelemetry,
 					),
 			};
 		}),
@@ -1477,6 +1519,7 @@ function createResolverClientFromEnvInternal(
 		clientProfile: config.clientProfile,
 		allowedHosts,
 		telemetry: options.telemetry,
+		browserTelemetry: options.browserTelemetry,
 	});
 }
 

package/src/runtime/state-telemetry.ts

@@ -0,0 +1,298 @@
+import type {
+	ProviderRuntimeState,
+	ProviderStateNamespace,
+	StateNamespaceOptions,
+} from "../types.js";
+import { createTelemetryObserver } from "./http-telemetry-guard.js";
+import {
+	type ClosedEnum,
+	closedEnum,
+	type SpanIndex,
+	type TelemetryContributor,
+} from "./request-telemetry.js";
+import { getStateViolation, isStateRedisNoop } from "./state.js";
+
+export type StateTelemetryOperation =
+	| "list"
+	| "get"
+	| "set"
+	| "patch"
+	| "delete"
+	| "cas"
+	| "increment";
+export type StateTelemetryBackend = "redis" | "memory" | "unsupported";
+export type StateTelemetryViolation = "quota" | "ttl" | "size" | "unsupported" | "error";
+
+export type StateTelemetrySample = {
+	key: string;
+	op: StateTelemetryOperation;
+	ms: number;
+	backend: StateTelemetryBackend;
+};
+export type StateTelemetryLogPayload = {
+	telemetryFailed?: true;
+	ops: {
+		list: number;
+		get: number;
+		set: number;
+		patch: number;
+		delete: number;
+		cas: number;
+		increment: number;
+	};
+	casConflicts: number;
+	violations: { quota: number; ttl: number; size: number; unsupported: number; error: number };
+	backend: ClosedEnum<StateTelemetryBackend>;
+	/** State fails closed on Redis errors, so this remains 0 until a fallback exists. */
+	redisFallbacks: number;
+	redisMode: ClosedEnum<"not_configured" | "configured" | "degraded">;
+	/** Successful state operations that touch Redis; each operation counts once, regardless of command count. */
+	redisRoundTrips: number;
+	ms: number;
+	samples: StateTelemetrySample[];
+	dropped: number;
+};
+export type StateTelemetryHeaderPayload = Omit<
+	StateTelemetryLogPayload,
+	"samples" | "telemetryFailed"
+>;
+
+export interface StateTelemetrySink {
+	markTelemetryFailed?(): void;
+	setRedisConfigured?(configured: boolean): void;
+	record(event: {
+		op: StateTelemetryOperation;
+		key?: string;
+		ms: number;
+		backend: StateTelemetryBackend;
+		ok: boolean;
+		conflict?: boolean;
+		violation?: StateTelemetryViolation;
+		/** False for successful Redis-backed operations that execute no Redis commands. */
+		redisTouched?: boolean;
+	}): void;
+}
+
+const MAX_SAMPLES = 24;
+const MAX_TEXT = 300;
+const STATE_TELEMETRY_INSTRUMENTED = Symbol.for(
+	"@apifuse/provider-sdk/state-telemetry-instrumented",
+);
+function integer(value: number): number {
+	return Number.isFinite(value)
+		? Math.min(Number.MAX_SAFE_INTEGER, Math.max(0, Math.floor(value)))
+		: Number.MAX_SAFE_INTEGER;
+}
+function add(a: number, b: number): number {
+	return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+function keyText(value: string | undefined, redact?: (text: string) => string): string | undefined {
+	if (value === undefined) return undefined;
+	let result: string;
+	try {
+		result = redact?.(value) ?? value;
+	} catch {
+		result = "[REDACTION_FAILED]";
+	}
+	const length = Math.min(result.length, MAX_TEXT);
+	const units = new Uint16Array(length);
+	for (let index = 0; index < length; index += 1) units[index] = result.charCodeAt(index);
+	return String.fromCharCode(...units);
+}
+
+export class StateTelemetryCollector
+	implements
+		TelemetryContributor<StateTelemetryLogPayload, StateTelemetryHeaderPayload>,
+		StateTelemetrySink
+{
+	readonly key = "state" as const;
+	readonly #redact?: (text: string) => string;
+	#telemetryFailed = false;
+	#ops = { list: 0, get: 0, set: 0, patch: 0, delete: 0, cas: 0, increment: 0 };
+	#conflicts = 0;
+	#violations = { quota: 0, ttl: 0, size: 0, unsupported: 0, error: 0 };
+	#backend: StateTelemetryBackend = "unsupported";
+	#redisFallbacks = 0;
+	#configured: "not_configured" | "configured" | "degraded" = "not_configured";
+	#redisRoundTrips = 0;
+	#ms = 0;
+	#samples: StateTelemetrySample[] = [];
+	#dropped = 0;
+	constructor(options: { redact?: (text: string) => string } = {}) {
+		this.#redact = options.redact;
+	}
+	markTelemetryFailed(): void {
+		this.#telemetryFailed = true;
+	}
+	setRedisConfigured(configured: boolean): void {
+		if (configured && this.#configured === "not_configured") this.#configured = "configured";
+	}
+	record(event: {
+		op: StateTelemetryOperation;
+		key?: string;
+		ms: number;
+		backend: StateTelemetryBackend;
+		ok: boolean;
+		conflict?: boolean;
+		violation?: StateTelemetryViolation;
+		/** False for successful Redis-backed operations that execute no Redis commands. */
+		redisTouched?: boolean;
+	}): void {
+		if (
+			!["list", "get", "set", "patch", "delete", "cas", "increment"].includes(event.op) ||
+			!["redis", "memory", "unsupported"].includes(event.backend) ||
+			(event.violation !== undefined &&
+				!["quota", "ttl", "size", "unsupported", "error"].includes(event.violation))
+		) {
+			this.#telemetryFailed = true;
+			return;
+		}
+		this.#ops[event.op] = add(this.#ops[event.op], 1);
+		this.#backend = event.backend;
+		if (event.backend === "redis" && this.#configured === "not_configured")
+			this.#configured = "configured";
+		if (event.backend === "redis" && event.ok && event.redisTouched !== false)
+			this.#redisRoundTrips = add(this.#redisRoundTrips, 1);
+		if (event.backend === "redis" && !event.ok) this.#configured = "degraded";
+		this.#ms = add(this.#ms, event.ms);
+		if (event.conflict) this.#conflicts = add(this.#conflicts, 1);
+		if (event.violation)
+			this.#violations[event.violation] = add(this.#violations[event.violation], 1);
+		if (this.#samples.length < MAX_SAMPLES)
+			this.#samples.push({
+				key: keyText(event.key, this.#redact) ?? "",
+				op: event.op,
+				ms: integer(event.ms),
+				backend: event.backend,
+			});
+		else this.#dropped = add(this.#dropped, 1);
+	}
+	toLogPayload(_spans: SpanIndex): StateTelemetryLogPayload | undefined {
+		if (Object.values(this.#ops).every((value) => value === 0) && !this.#telemetryFailed)
+			return undefined;
+		return {
+			...(this.#telemetryFailed ? { telemetryFailed: true as const } : {}),
+			ops: { ...this.#ops },
+			casConflicts: this.#conflicts,
+			violations: { ...this.#violations },
+			backend: closedEnum(this.#backend),
+			redisFallbacks: this.#redisFallbacks,
+			redisMode: closedEnum(this.#configured),
+			redisRoundTrips: this.#redisRoundTrips,
+			ms: this.#ms,
+			samples: this.#samples.map((sample) => ({ ...sample })),
+			dropped: this.#dropped,
+		};
+	}
+	toHeaderPayload(log: StateTelemetryLogPayload): StateTelemetryHeaderPayload {
+		return {
+			ops: log.ops,
+			casConflicts: log.casConflicts,
+			violations: log.violations,
+			backend: log.backend,
+			redisFallbacks: log.redisFallbacks,
+			redisMode: log.redisMode,
+			redisRoundTrips: log.redisRoundTrips,
+			ms: log.ms,
+			dropped: log.dropped,
+		};
+	}
+}
+
+function backendOf(state: ProviderRuntimeState): StateTelemetryBackend {
+	try {
+		const name = state.constructor?.name;
+		return name?.includes("Redis") ? "redis" : name?.includes("Memory") ? "memory" : "unsupported";
+	} catch {
+		return "unsupported";
+	}
+}
+
+function violationOf(error: unknown): StateTelemetryViolation {
+	return getStateViolation(error) ?? "error";
+}
+
+function wrapNamespace(
+	namespace: ProviderStateNamespace,
+	sink: StateTelemetrySink,
+	backend: StateTelemetryBackend,
+): ProviderStateNamespace {
+	// Compare-and-set records one event per attempt; a three-attempt loop therefore
+	// reports cas: 3 and casConflicts: 2 when the first two attempts conflict.
+	const observe = createTelemetryObserver(sink);
+	return new Proxy(namespace, {
+		get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver);
+			if (typeof value !== "function" || property === "constructor") return value;
+			const op =
+				property === "compareAndSet" ? "cas" : (String(property) as StateTelemetryOperation);
+			if (!(op in { list: 1, get: 1, set: 1, patch: 1, delete: 1, cas: 1, increment: 1 }))
+				return value;
+			return async (...args: unknown[]) => {
+				const started = Date.now();
+				const key = typeof args[0] === "string" ? args[0] : undefined;
+				try {
+					const result = await Reflect.apply(value, target, args);
+					observe(() =>
+						sink.record({
+							op,
+							key,
+							ms: Date.now() - started,
+							backend,
+							ok: true,
+							redisTouched: !isStateRedisNoop(result),
+							conflict:
+								op === "cas" &&
+								!!result &&
+								typeof result === "object" &&
+								"ok" in result &&
+								result.ok === false,
+						}),
+					);
+					return result;
+				} catch (error) {
+					observe(() =>
+						sink.record({
+							op,
+							key,
+							ms: Date.now() - started,
+							backend,
+							ok: false,
+							violation: violationOf(error),
+						}),
+					);
+					throw error;
+				}
+			};
+		},
+	}) as ProviderStateNamespace;
+}
+
+export function instrumentProviderRuntimeState(
+	state: ProviderRuntimeState,
+	sink: StateTelemetrySink,
+	redact?: (text: string) => string,
+): ProviderRuntimeState {
+	if (
+		(state as ProviderRuntimeState & { [STATE_TELEMETRY_INSTRUMENTED]?: boolean })[
+			STATE_TELEMETRY_INSTRUMENTED
+		]
+	)
+		return state;
+	const backend = backendOf(state);
+	const observe = createTelemetryObserver(sink);
+	observe(() => sink.setRedisConfigured?.(backend === "redis"));
+	return new Proxy(state, {
+		get(target, property, receiver) {
+			if (property === STATE_TELEMETRY_INSTRUMENTED) return true;
+			const value = Reflect.get(target, property, receiver);
+			if (property === "forConnection" && typeof value === "function")
+				return (id: string | undefined) =>
+					instrumentProviderRuntimeState(value.call(target, id), sink, redact);
+			if (property === "namespace" && typeof value === "function")
+				return (name: string, options: StateNamespaceOptions) =>
+					wrapNamespace(value.call(target, name, options), sink, backend);
+			return value;
+		},
+	}) as ProviderRuntimeState;
+}