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

package/src/provider.ts

@@ -115,8 +115,13 @@ export {
 	isProviderError,
 	isSessionExpiredError,
 	isTransportError,
+	ProviderEgressDeniedError,
+	ProviderEngineAuthenticationError,
+	ProviderEngineProtocolVersionError,
+	ProviderEngineUnavailableError,
 	ProviderError,
 	type ProviderErrorObservability,
+	SDKError,
 	SessionExpiredError,
 	TransportError,
 	ValidationError,
@@ -134,6 +139,7 @@ export {
 	isEngineOwnedRuntimeEnvName,
 	isEngineOwnedTelemetryEnvName,
 	PROVIDER_CAPABILITY_KEYS,
+	PROVIDER_ENGINE_MODE_ENV,
 	PROVIDER_ENGINE_PROTOCOL_VERSION,
 	readEngineProxyCredentials,
 } from "./engine.js";
@@ -143,6 +149,7 @@ export type {
 	ProviderEngineAttachmentInput,
 	ProviderEngineBindingCandidates,
 	ProviderEngineCapabilitySurface,
+	ProviderEngineMode,
 	ProviderEngineRequest,
 	ProviderEngineResidentSurface,
 	ProviderEngineSession,
@@ -150,10 +157,17 @@ export type {
 } from "./engine.js";
 export {
 	getProviderLocalePath,
+	type ProviderErrorMessageParams,
 	providerLocaleKey,
 	qualifyProviderLocaleKey,
 } from "./i18n/index.js";
 export * from "./handle.js";
+export {
+	APIFUSE_HANDLE_META_KEY,
+	HANDLE_KIND_NAME_PATTERN,
+	handleFieldDescription,
+	isHandleFieldMeta,
+} from "./handle-meta.js";
 export {
 	type CreateHandleContextOptions,
 	type CreateTestHandleContextOptions,
@@ -163,6 +177,10 @@ export {
 	type NormalizedHandle,
 	normalizeHandle,
 } from "./runtime/handle.js";
+export {
+	createMemoryProviderRuntimeState,
+	createUnsupportedProviderRuntimeState,
+} from "./runtime/state.js";
 export {
 	APIFUSE_CONTENT_PROVENANCE_META_KEY,
 	APIFUSE_CONTENT_TRUST_META_KEY,
@@ -202,6 +220,8 @@ export type {
 	HealthJourneyRunContext,
 	HealthJourneyRunResult,
 	HealthScheduleRandomization,
+	HttpAttemptContext,
+	HttpHeadersFactory,
 	HttpRedirectFailureReason,
 	HttpRedirectPolicy,
 	HttpRedirectPolicyMode,

package/src/runtime/browser-telemetry-binding.ts

@@ -0,0 +1,92 @@
+import type { BrowserClient } from "../types.js";
+import type { BrowserTelemetrySink } from "./browser-telemetry.js";
+import { observeTelemetryCallback } from "./http-telemetry-guard.js";
+
+const methods = new Set(["newPage", "rawPage", "withIsolatedContext", "solveChallenge"]);
+type State = { sink: BrowserTelemetrySink; adapter: BrowserClient };
+const adapters = new WeakMap<object, State>();
+let warned = false;
+
+export function isSupportedBrowserBinding(value: unknown): value is BrowserClient {
+	if ((typeof value !== "object" && typeof value !== "function") || value === null) return false;
+	return [...methods].some((method) => {
+		try {
+			return typeof Reflect.get(value, method) === "function";
+		} catch {
+			return false;
+		}
+	});
+}
+
+export function warnUnsupportedBrowserBinding(): void {
+	if (warned) return;
+	warned = true;
+	try {
+		console.warn("[apifuse] browser telemetry not attached; reason=unsupported_binding_shape");
+	} catch {}
+}
+
+export function bindBrowserTelemetry(
+	client: BrowserClient,
+	sink: BrowserTelemetrySink,
+): BrowserClient {
+	const existing = adapters.get(client as object);
+	if (existing) {
+		existing.sink = sink;
+		return existing.adapter;
+	}
+	const wrappers = new Map<
+		PropertyKey,
+		{ original: unknown; wrapped: (...args: unknown[]) => unknown }
+	>();
+	const adapter = new Proxy(Object.create(client) as BrowserClient, {
+		get(_target, property) {
+			const original = Reflect.get(client, property, client);
+			if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+				return original;
+			const cached = wrappers.get(property);
+			if (cached && cached.original === original) return cached.wrapped;
+			const wrapped = function (this: unknown, ...args: unknown[]) {
+				const receiver = this === adapter ? client : this;
+				observeTelemetryCallback(state.sink, () => {
+					const declared = client.engine;
+					const engine =
+						declared === "playwright-stealth" ||
+						declared === "nodriver" ||
+						declared === "selenium-uc"
+							? declared
+							: "host";
+					return state.sink.recordEngine(engine);
+				});
+				if (property === "newPage" || property === "rawPage" || property === "withIsolatedContext")
+					observeTelemetryCallback(state.sink, () =>
+						state.sink.recordPoolAcquire("not_configured"),
+					);
+				let result: unknown;
+				try {
+					result = Reflect.apply(original, receiver, args);
+				} catch (error) {
+					observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+					throw error;
+				}
+				try {
+					if (result instanceof Promise)
+						void Promise.prototype.then.call(result, undefined, () => {
+							observeTelemetryCallback(state.sink, () => state.sink.recordError("other"));
+						});
+				} catch (error) {
+					observeTelemetryCallback(state.sink, () => {
+						throw error;
+					});
+				}
+				return result;
+			};
+			wrappers.set(property, { original, wrapped });
+			return wrapped;
+		},
+	});
+	const state: State = { sink, adapter };
+	adapters.set(client as object, state);
+	adapters.set(adapter as object, state);
+	return adapter;
+}

package/src/runtime/browser-telemetry.ts

@@ -0,0 +1,289 @@
+import type { BrowserEngine } from "../types.js";
+import { Buffer } from "node:buffer";
+export type BrowserTelemetryEngine = BrowserEngine | "host";
+import {
+	closedEnum,
+	type ClosedEnum,
+	type SpanIndex,
+	type TelemetryContributor,
+} from "./request-telemetry.js";
+
+export type BrowserTelemetryPoolAcquireOutcome =
+	| "ok"
+	| "not_configured"
+	| "queue_full"
+	| "timed_out"
+	| "shutting_down"
+	| "unknown_lease"
+	| "unknown_method"
+	| "missing_allowed_hosts"
+	| "transport_failure"
+	| "other";
+
+export type BrowserTelemetryErrorCode =
+	| "BROWSER_CDP_POOL_REQUIRED"
+	| "BROWSER_PROXY_INVALID"
+	| "BROWSER_RUNTIME_UNSUPPORTED"
+	| "BROWSER_CDP_POOL_ERROR"
+	| "other";
+
+export type BrowserTelemetrySampleName =
+	| "browser.newPage"
+	| "browser.page.goto"
+	| "browser.page.fill"
+	| "browser.page.click"
+	| "browser.page.type"
+	| "browser.page.waitForSelector"
+	| "browser.evaluate"
+	| "browser.content"
+	| "browser.screenshot"
+	| "other";
+
+export type BrowserTelemetryLogPayload = {
+	allocateMs: number;
+	pages: number;
+	navigations: number;
+	actions: number;
+	evaluate: number;
+	content: number;
+	screenshot: number;
+	poolAcquireOutcome?: BrowserTelemetryPoolAcquireOutcome;
+	poolAcquireAttempts: number;
+	poolAcquireFailures: number;
+	poolAcquireUnknownCode?: number;
+	proxyAuthChallenges: number;
+	engine?: BrowserTelemetryEngine;
+	lastErrorCode?: BrowserTelemetryErrorCode;
+	samples: {
+		name: BrowserTelemetrySampleName;
+		ms: number;
+		status: "ok" | "error";
+		diagnostics?: string;
+	}[];
+	dropped: number;
+	telemetryFailed?: true;
+};
+
+export type BrowserTelemetryHeaderPayload = {
+	allocateMs: number;
+	pages: number;
+	navigations: number;
+	actions: number;
+	evaluate: number;
+	content: number;
+	screenshot: number;
+	poolAcquireOutcome?: ClosedEnum<BrowserTelemetryPoolAcquireOutcome>;
+	poolAcquireAttempts: number;
+	poolAcquireFailures: number;
+	proxyAuthChallenges: number;
+	engine?: ClosedEnum<BrowserTelemetryEngine>;
+	lastErrorCode?: ClosedEnum<BrowserTelemetryErrorCode>;
+	samples: {
+		name: ClosedEnum<BrowserTelemetrySampleName>;
+		ms: number;
+		status: ClosedEnum<"ok" | "error">;
+	}[];
+	dropped: number;
+};
+
+export interface BrowserTelemetrySink {
+	recordPoolAcquire(outcome: BrowserTelemetryPoolAcquireOutcome): void;
+	recordPoolAcquireUnknownCode?(code: number): void;
+	recordProxyAuthChallenge(): void;
+	recordEngine(engine: BrowserTelemetryEngine): void;
+	recordError(code: BrowserTelemetryErrorCode): void;
+	markTelemetryFailed?(): void;
+}
+
+const MAX_SAMPLES = 24;
+const SAMPLE_NAMES = new Set<BrowserTelemetrySampleName>([
+	"browser.newPage",
+	"browser.page.goto",
+	"browser.page.fill",
+	"browser.page.click",
+	"browser.page.type",
+	"browser.page.waitForSelector",
+	"browser.evaluate",
+	"browser.content",
+	"browser.screenshot",
+]);
+function sampleName(name: string): BrowserTelemetrySampleName {
+	if (name === "browser.page.evaluate") return "browser.evaluate";
+	if (name === "browser.page.content") return "browser.content";
+	if (name === "browser.page.screenshot") return "browser.screenshot";
+	return name === "[REDACTION_FAILED]" || !SAMPLE_NAMES.has(name as BrowserTelemetrySampleName)
+		? "other"
+		: (name as BrowserTelemetrySampleName);
+}
+
+function boundedDiagnostics(text: string, redact?: (value: string) => string): string {
+	let result: string;
+	try {
+		result = stripBrowserHeaderMaterial(redact?.(text) ?? text);
+	} catch {
+		return "[REDACTION_FAILED]";
+	}
+	const length = Math.min(result.length, 300);
+	const units = Buffer.alloc(length * 2);
+	for (let i = 0; i < length; i += 1) units.writeUInt16LE(result.charCodeAt(i), i * 2);
+	return units.toString("utf16le");
+}
+
+function integer(value: number): number {
+	return Math.min(
+		Number.MAX_SAFE_INTEGER,
+		Math.max(0, Math.floor(Number.isFinite(value) ? value : 0)),
+	);
+}
+
+function add(a: number, b: number): number {
+	return Math.min(Number.MAX_SAFE_INTEGER, integer(a) + integer(b));
+}
+
+export class BrowserTelemetryCollector
+	implements
+		TelemetryContributor<BrowserTelemetryLogPayload, BrowserTelemetryHeaderPayload>,
+		BrowserTelemetrySink
+{
+	readonly key = "browser" as const;
+	#poolAcquireOutcome: BrowserTelemetryPoolAcquireOutcome | undefined;
+	#poolAcquireAttempts = 0;
+	#poolAcquireFailures = 0;
+	#poolAcquireUnknownCode: number | undefined;
+	#telemetryFailed = false;
+	#proxyAuthChallenges = 0;
+	#engine: BrowserTelemetryEngine | undefined;
+	#lastErrorCode: BrowserTelemetryErrorCode | undefined;
+	readonly #redact: ((value: string) => string) | undefined;
+
+	constructor(options: { redact?: (value: string) => string } = {}) {
+		this.#redact = options.redact;
+	}
+
+	recordPoolAcquire(outcome: BrowserTelemetryPoolAcquireOutcome): void {
+		this.#poolAcquireOutcome = outcome;
+		this.#poolAcquireAttempts = add(this.#poolAcquireAttempts, 1);
+		if (outcome !== "ok") this.#poolAcquireFailures = add(this.#poolAcquireFailures, 1);
+	}
+	recordPoolAcquireUnknownCode(code: number): void {
+		this.#poolAcquireUnknownCode = code;
+	}
+	recordProxyAuthChallenge(): void {
+		this.#proxyAuthChallenges = add(this.#proxyAuthChallenges, 1);
+	}
+	recordEngine(engine: BrowserTelemetryEngine): void {
+		this.#engine = engine;
+	}
+	recordError(code: BrowserTelemetryErrorCode): void {
+		this.#lastErrorCode = code;
+	}
+	markTelemetryFailed(): void {
+		this.#telemetryFailed = true;
+	}
+
+	toLogPayload(spans: SpanIndex): BrowserTelemetryLogPayload | undefined {
+		const browserSpans = spans.spans.filter(
+			(span) =>
+				span.name === "browser.newPage" ||
+				span.name === "browser.rawPage" ||
+				span.name === "browser.withIsolatedContext" ||
+				span.name.startsWith("browser.page.") ||
+				/^browser\.(evaluate|content|screenshot)$/.test(span.name),
+		);
+		const failedSpan = spans.spans.some((span) => span.name === "[REDACTION_FAILED]");
+		if (
+			browserSpans.length === 0 &&
+			!failedSpan &&
+			!this.#poolAcquireOutcome &&
+			this.#proxyAuthChallenges === 0 &&
+			!this.#engine &&
+			!this.#lastErrorCode &&
+			!this.#telemetryFailed
+		)
+			return undefined;
+		const count = (name: string) => spans.count(name);
+		const sampleSpans = failedSpan
+			? [...browserSpans, ...spans.spans.filter((span) => span.name === "[REDACTION_FAILED]")]
+			: browserSpans;
+		const samples: BrowserTelemetryLogPayload["samples"] = sampleSpans
+			.slice(0, MAX_SAMPLES)
+			.map((span) => ({
+				name: sampleName(span.name),
+				ms: integer(span.duration_ms),
+				status: (span.status === "error" ? "error" : "ok") as "ok" | "error",
+				...(span.name === "[REDACTION_FAILED]"
+					? { diagnostics: "[REDACTION_FAILED]" }
+					: span.error
+						? { diagnostics: boundedDiagnostics(span.error, this.#redact) }
+						: {}),
+			}));
+		return {
+			allocateMs: integer(
+				browserSpans
+					.filter((span) => span.name === "browser.newPage")
+					.reduce((sum, span) => sum + Number(span.attributes.allocate_ms ?? span.duration_ms), 0),
+			),
+			pages: add(
+				add(count("browser.newPage"), count("browser.rawPage")),
+				count("browser.withIsolatedContext"),
+			),
+			navigations: integer(count("browser.page.goto")),
+			actions: ["fill", "click", "type", "waitForSelector"].reduce(
+				(sum, method) => add(sum, count(`browser.page.${method}`)),
+				0,
+			),
+			evaluate: add(count("browser.evaluate"), count("browser.page.evaluate")),
+			content: add(count("browser.page.content"), count("browser.content")),
+			screenshot: add(count("browser.page.screenshot"), count("browser.screenshot")),
+			...(this.#poolAcquireOutcome ? { poolAcquireOutcome: this.#poolAcquireOutcome } : {}),
+			poolAcquireAttempts: this.#poolAcquireAttempts,
+			poolAcquireFailures: this.#poolAcquireFailures,
+			...(this.#poolAcquireUnknownCode === undefined
+				? {}
+				: { poolAcquireUnknownCode: this.#poolAcquireUnknownCode }),
+			proxyAuthChallenges: this.#proxyAuthChallenges,
+			...(this.#engine ? { engine: this.#engine } : {}),
+			...(this.#lastErrorCode ? { lastErrorCode: this.#lastErrorCode } : {}),
+			samples,
+			dropped: Math.max(0, sampleSpans.length - samples.length),
+			...(this.#telemetryFailed ? { telemetryFailed: true as const } : {}),
+		};
+	}
+
+	toHeaderPayload(log: BrowserTelemetryLogPayload): BrowserTelemetryHeaderPayload {
+		return {
+			allocateMs: log.allocateMs,
+			pages: log.pages,
+			navigations: log.navigations,
+			actions: log.actions,
+			evaluate: log.evaluate,
+			content: log.content,
+			screenshot: log.screenshot,
+			...(log.poolAcquireOutcome ? { poolAcquireOutcome: closedEnum(log.poolAcquireOutcome) } : {}),
+			poolAcquireAttempts: log.poolAcquireAttempts,
+			poolAcquireFailures: log.poolAcquireFailures,
+			proxyAuthChallenges: log.proxyAuthChallenges,
+			...(log.engine ? { engine: closedEnum(log.engine) } : {}),
+			...(log.lastErrorCode ? { lastErrorCode: closedEnum(log.lastErrorCode) } : {}),
+			samples: log.samples.map((sample) => ({
+				name: closedEnum(sample.name),
+				ms: sample.ms,
+				status: closedEnum(sample.status),
+			})),
+			dropped: log.dropped,
+		};
+	}
+}
+
+/** Defence in depth for diagnostics that accidentally contain protocol headers. */
+export function stripBrowserHeaderMaterial(value: string): string {
+	return value
+		.replace(
+			/(^|[^\p{L}\p{N}_-])[\t ]*(?:cookie|set-cookie|authorization)[\t ]*(?::|=)[^\r\n]*/giu,
+			"$1[REDACTED]",
+		)
+		.replace(
+			/"(?:cookie|set-cookie|authorization)"[\t ]*:[\t ]*"(?:\\.|[^"\\])*"/giu,
+			"[REDACTED]",
+		);
+}