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

package/src/runtime/http.ts

@@ -7,7 +7,9 @@ import {
 import { HttpRedirectError, ProviderError, TransportError } from "../errors.js";
 import { parseSseStream, readableBytes, readableLines, readableTextChunks } from "../stream.js";
 import type {
+	HttpAttemptContext,
 	HttpClient,
+	HttpHeadersFactory,
 	HttpMethod,
 	HttpRedirectPolicy,
 	HttpResponse,
@@ -194,26 +196,108 @@ function hasHeader(headers: Record<string, string>, name: string): boolean {
 	return Object.keys(headers).some((key) => key.toLowerCase() === needle);
 }
 
-function withClientHeaders(
-	options: RequestOptions | undefined,
+function withClientHeaderDefaults(
+	headers: Record<string, string> | undefined,
 	clientOptions: HttpClientOptions,
 	body: unknown,
-): RequestOptions {
-	const headers: Record<string, string> = {
+): Record<string, string> {
+	const merged: Record<string, string> = {
 		...(clientOptions.userAgent ? { "User-Agent": clientOptions.userAgent } : {}),
-		...options?.headers,
+		...headers,
 	};
 
-	if (body !== undefined && !hasHeader(headers, "Content-Type")) {
-		headers["Content-Type"] = "application/json";
+	if (body !== undefined && !hasHeader(merged, "Content-Type")) {
+		merged["Content-Type"] = "application/json";
 	}
 
+	return merged;
+}
+
+function withClientHeaders(
+	options: RequestOptions | undefined,
+	clientOptions: HttpClientOptions,
+	body: unknown,
+): RequestOptions {
+	// The ambient client signal is merged into the per-request one here so every
+	// downstream read (retry loop, sleep, body consumption) sees a single signal.
+	// The header-factory branch needs it too, otherwise factory-header requests
+	// would lose ambient cancellation entirely.
+	const signal = mergeAbortSignals(clientOptions.signal, options?.signal);
+	// A header factory is resolved per issued attempt (resolveAttemptHeaders);
+	// the client defaults are applied to its output at that point.
+	if (typeof options?.headers === "function") return { ...options, signal };
 	return {
 		...options,
-		headers,
+		headers: withClientHeaderDefaults(options?.headers, clientOptions, body),
+		signal,
 	};
 }
 
+function headerFactoryFailure(message: string, cause?: unknown): TransportError {
+	// A dedicated code keeps a broken proof minter out of the retry predicate:
+	// toHttpTransportError would otherwise brand a plain throw as
+	// transport_network_error, which the default retry policy re-issues.
+	// retryable:false is explicit so the served error envelope does not
+	// advertise a deterministic signing failure as retryable, and
+	// category:provider_error keeps a provider-local minting bug out of the
+	// upstream-failure signal (status 0 would otherwise fall through the
+	// observability ladder to upstream_http / source upstream_failure).
+	return new TransportError(message, {
+		code: "http_header_factory_failed",
+		status: 0,
+		retryable: false,
+		category: "provider_error",
+		...(cause instanceof Error ? { cause } : {}),
+	});
+}
+
+function isHeaderRecord(value: unknown): value is Record<string, string> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Settle `promise`, or reject with the signal's reason as soon as it aborts, so
+// a pending header factory cannot outlive the request deadline or an ambient
+// cancellation (native fetch has not started yet, so nothing else observes them).
+function settleBeforeAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+	if (!signal) return promise;
+	return new Promise<T>((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		if (signal.aborted) onAbort();
+		else signal.addEventListener("abort", onAbort, { once: true });
+		// Always attach handlers: a late rejection after the abort must settle
+		// here (a no-op on the already-rejected promise), never go unhandled.
+		promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+
+async function resolveAttemptHeaders(
+	options: RequestOptions & { body?: unknown },
+	clientOptions: HttpClientOptions,
+	attempt: () => HttpAttemptContext,
+	signal: AbortSignal | undefined,
+): Promise<Record<string, string> | undefined> {
+	const { headers } = options;
+	if (typeof headers !== "function") return headers;
+	// The per-call timeout may have fired during proxy resolution: do not start
+	// the factory at all once the request is already aborted.
+	if (signal?.aborted) throw signal.reason;
+	let minted: unknown;
+	try {
+		minted = await settleBeforeAbort(
+			Promise.resolve().then(() => headers(attempt())),
+			signal,
+		);
+	} catch (error) {
+		// An abort is classified by toHttpTransportError (cancelled / timed out).
+		if (signal?.aborted) throw error;
+		throw headerFactoryFailure("Request header factory failed", error);
+	}
+	if (!isHeaderRecord(minted)) {
+		throw headerFactoryFailure("Request header factory must return a header record");
+	}
+	return withClientHeaderDefaults(minted, clientOptions, options.body);
+}
+
 function parseHttpData(body: string, headers: Record<string, string>): unknown {
 	const contentType = headers["content-type"] ?? headers["Content-Type"] ?? headers["CONTENT-TYPE"];
 
@@ -469,7 +553,7 @@ function toNativeHttpStreamResponse(
 	};
 }
 
-function normalizeHttpMethod(method: string): HttpMethod {
+function normalizeHttpMethod(method: string): Uppercase<HttpMethod> {
 	switch (method.toUpperCase()) {
 		case "HEAD":
 			return "HEAD";
@@ -765,7 +849,7 @@ function serializeHttpRequestUrl(
 async function fetchNativeHttp(
 	baseUrl: string | undefined,
 	url: string,
-	method: HttpMethod,
+	method: Uppercase<HttpMethod>,
 	options: RequestOptions & { body?: unknown },
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
@@ -773,24 +857,30 @@ async function fetchNativeHttp(
 	proxyAttemptOffset = 0,
 	dedupe?: { attempted: Set<string> },
 	observeProxy?: (used: boolean, status?: number) => void,
+	nextHeaderAttempt: () => number = () => 1,
 ): Promise<NativeHttpAttemptOutcome> {
 	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
+	const signal = mergeAbortSignals(options.signal, controller?.signal);
+	let timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
+	const disarmTimeout = () => {
+		if (!timeoutHandle) return;
+		clearTimeout(timeoutHandle);
+		timeoutHandle = undefined;
+	};
 
 	let proxy: string | undefined;
 	try {
-		throwIfAmbientAborted(clientOptions.signal);
+		throwIfAmbientAborted(options.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);
 		observeProxy?.(Boolean(proxy));
-		throwIfAmbientAborted(clientOptions.signal);
+		throwIfAmbientAborted(options.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
@@ -801,8 +891,17 @@ async function fetchNativeHttp(
 			}
 			dedupe.attempted.add(proxy);
 		}
+		// Resolve after the dedupe check so a skipped duplicate offset never burns
+		// a single-use proof, and with the serialized URL so URL-bound proofs
+		// match what is actually issued.
+		const requestHeaders = await resolveAttemptHeaders(
+			options,
+			clientOptions,
+			() => ({ attempt: nextHeaderAttempt(), url: requestUrl, method }),
+			signal,
+		);
 		const requestInit: NativeFetchInit = {
-			headers: options.headers,
+			headers: requestHeaders,
 			method,
 			...(proxy ? { proxy } : {}),
 			...(signal ? { signal } : {}),
@@ -837,7 +936,15 @@ async function fetchNativeHttp(
 			});
 		}
 
-		return toNativeHttpResponse(response);
+		// `timeout` bounds the header phase (types.ts RequestOptions.timeout), so it
+		// is disarmed before the body is read: awaiting the buffered body inside
+		// this try brands a mid-body failure as a transport error, but must not
+		// extend the deadline over the download. Cancellation still applies —
+		// `signal` stays attached to the native response. The discarded non-2xx
+		// bodies drained above stay under the deadline on purpose: nothing else
+		// bounds them, and their content is never returned to the caller.
+		disarmTimeout();
+		return await toNativeHttpResponse(response);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
 			throw redactSensitiveError(
@@ -848,7 +955,7 @@ async function fetchNativeHttp(
 			);
 		}
 		const transportError: NativeHttpAttemptError = redactSensitiveError(
-			toHttpTransportError(error, clientOptions.signal, controller?.signal),
+			toHttpTransportError(error, options.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -856,14 +963,14 @@ async function fetchNativeHttp(
 		transportError.proxyUsed = Boolean(proxy);
 		throw transportError;
 	} finally {
-		if (timeoutHandle) clearTimeout(timeoutHandle);
+		disarmTimeout();
 	}
 }
 
 async function fetchNativeHttpStream(
 	baseUrl: string | undefined,
 	url: string,
-	method: HttpMethod,
+	method: Uppercase<HttpMethod>,
 	options: RequestOptions & { body?: unknown },
 	clientOptions: HttpClientOptions,
 	warn: (message: string) => void,
@@ -872,18 +979,25 @@ 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 signal = mergeAbortSignals(options.signal, controller?.signal);
 	const timeoutHandle = options.timeout
 		? setTimeout(() => controller?.abort(), options.timeout)
 		: undefined;
 
 	try {
-		throwIfAmbientAborted(clientOptions.signal);
+		throwIfAmbientAborted(options.signal);
 		const proxy = await resolveNativeProxy(options, clientOptions, warn);
 		observeProxy?.(Boolean(proxy));
-		throwIfAmbientAborted(clientOptions.signal);
+		throwIfAmbientAborted(options.signal);
+		// Streams never retry: a header factory is resolved once, as attempt 1.
+		const headers = await resolveAttemptHeaders(
+			options,
+			clientOptions,
+			() => ({ attempt: 1, url: requestUrl, method }),
+			signal,
+		);
 		const requestInit: NativeFetchInit = {
-			headers: options.headers,
+			headers,
 			method,
 			...(proxy ? { proxy } : {}),
 			...(signal ? { signal } : {}),
@@ -905,9 +1019,9 @@ async function fetchNativeHttpStream(
 			});
 		}
 
-		// 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);
+		// The stream timeout remains header-scoped; composed ambient and local
+		// cancellation stays attached to native fetch for the body's full lifetime.
+		return toNativeHttpStreamResponse(response, serializedUrl, options.signal);
 	} catch (error) {
 		if (error instanceof SyntaxError) {
 			throw redactSensitiveError(
@@ -918,7 +1032,7 @@ async function fetchNativeHttpStream(
 			);
 		}
 		throw redactSensitiveError(
-			toHttpTransportError(error, clientOptions.signal, controller?.signal),
+			toHttpTransportError(error, options.signal, controller?.signal),
 			serializedUrl.sensitiveValues,
 			serializedUrl.requestUrl,
 			serializedUrl.redactedUrl,
@@ -1052,6 +1166,16 @@ export function createHttpClient(
 			});
 			const dedupeContext = dedupeAllocatorEndpoints ? { attempted: new Set<string>() } : undefined;
 
+			// Numbers the attempts a header factory sees: only requests that reached
+			// header resolution count, so a failed proxy allocation (which increments
+			// the telemetry `issued` count below) or a dedupe-skipped offset does not
+			// make the first request that is actually built report `attempt: 2`.
+			let headerAttempts = 0;
+			const nextHeaderAttempt = () => {
+				headerAttempts += 1;
+				return headerAttempts;
+			};
+
 			const executeOnce = async (proxyAttemptOffset = 0): Promise<NativeHttpAttemptOutcome> => {
 				const started = performance.now();
 				let proxyUsed = false;
@@ -1074,6 +1198,7 @@ export function createHttpClient(
 							proxyUsed = used;
 							observedStatus = status;
 						},
+						nextHeaderAttempt,
 					);
 					if (!isDedupeSkipOutcome(outcome))
 						record({
@@ -1091,7 +1216,7 @@ export function createHttpClient(
 			};
 
 			if (!retryEnabled || !retryOptions) {
-				throwIfAmbientAborted(clientOptions.signal);
+				throwIfAmbientAborted(headersOptions.signal);
 				const outcome = await executeOnce();
 				if (isDedupeSkipOutcome(outcome)) {
 					// Single-shot path never de-duplicates (dedupeContext is undefined),
@@ -1114,7 +1239,7 @@ export function createHttpClient(
 			// allocations skip offsets.
 			let issued = 0;
 			for (let attempt = 1; attempt <= transportAttemptCap; attempt += 1) {
-				throwIfAmbientAborted(clientOptions.signal);
+				throwIfAmbientAborted(headersOptions.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
@@ -1134,7 +1259,7 @@ export function createHttpClient(
 						if (outcome.retryable && issued < retryOptions.attempts) {
 							await sleep(
 								computeProxyTransportRetryDelayMs(retryOptions, attempt, outcome.headers),
-								clientOptions.signal,
+								headersOptions.signal,
 							);
 							continue;
 						}
@@ -1152,7 +1277,7 @@ export function createHttpClient(
 					}
 					return response;
 				} catch (error) {
-					throwIfAmbientAborted(clientOptions.signal);
+					throwIfAmbientAborted(headersOptions.signal);
 					if (!issuedThisAttempt) issued += 1;
 					lastError = error;
 					const proxyUsed = Boolean((error as NativeHttpAttemptError).proxyUsed);
@@ -1168,7 +1293,7 @@ export function createHttpClient(
 					) {
 						await sleep(
 							computeProxyTransportRetryDelayMs(retryOptions, attempt),
-							clientOptions.signal,
+							headersOptions.signal,
 						);
 						continue;
 					}
@@ -1218,7 +1343,7 @@ export function createHttpClient(
 		// Streams never retry. Observe the header fetch without consuming its body.
 		const telemetry = startHttpTelemetry(scopedHttpTelemetry(clientOptions.httpTelemetry), "off");
 		const started = performance.now();
-		const alreadyAborted = clientOptions.signal?.aborted === true;
+		const alreadyAborted = headersOptions.signal?.aborted === true;
 		let proxyUsed = false;
 		const record = (event: Omit<HttpAttemptTelemetryEvent, "ms" | "proxyUsed">) => {
 			if (alreadyAborted) return;
@@ -1259,10 +1384,16 @@ export function createHttpClient(
 			url,
 			options: RequestWithMethodOptions = {},
 		): Promise<AsyncIterable<SseMessage>> => {
-			const headers = {
-				Accept: "text/event-stream",
-				...options.headers,
-			};
+			const callerHeaders = options.headers;
+			const headers: Record<string, string> | HttpHeadersFactory =
+				typeof callerHeaders === "function"
+					? async (attempt) => {
+							// Pass a malformed result through unchanged so the factory
+							// validation rejects it instead of spreading it into `{}`.
+							const minted = await callerHeaders(attempt);
+							return isHeaderRecord(minted) ? { Accept: "text/event-stream", ...minted } : minted;
+						}
+					: { Accept: "text/event-stream", ...callerHeaders };
 			const response = await streamRequest(url, options.method ?? "GET", {
 				...options,
 				headers,

package/src/runtime/instrumentation.ts

@@ -1,3 +1,4 @@
+import { runCapabilitySpan } from "./capability-telemetry.js";
 import { registerDiagnosticSensitiveValues } from "./diagnostic-redactor.js";
 import type {
 	HttpStreamResponse,
@@ -35,9 +36,26 @@ export type InstrumentedProviderContext<T extends Pick<ProviderContext, "trace">
 	trace: TraceContext;
 };
 
-type InstrumentedNamespace = "http" | "stealth" | "browser" | "session" | "state" | "resolver";
-
-const BROWSER_PAGE_METHODS = new Set(["goto", "fill", "click", "type", "waitForSelector"]);
+type InstrumentedNamespace =
+	| "http"
+	| "stealth"
+	| "browser"
+	| "session"
+	| "state"
+	| "resolver"
+	| "ocr"
+	| "stt";
+
+const BROWSER_PAGE_METHODS = new Set([
+	"goto",
+	"fill",
+	"click",
+	"type",
+	"waitForSelector",
+	"evaluate",
+	"content",
+	"screenshot",
+]);
 const DIAGNOSTIC_BASE_URL = "http://apifuse-instrumentation.invalid";
 
 type RequestDiagnostics = {
@@ -398,9 +416,19 @@ function buildSpanAttributes(
 		attributes.method = method;
 	}
 
-	if (status !== undefined && (namespace === "http" || namespace === "stealth")) {
+	if (
+		status !== undefined &&
+		(namespace === "http" || namespace === "stealth" || namespace === "ocr" || namespace === "stt")
+	) {
 		attributes.status = status;
 	}
+	if ((namespace === "ocr" || namespace === "stt") && result && typeof result === "object") {
+		if ("model" in result && typeof result.model === "string") attributes.model = result.model;
+		if ("durationMs" in result && typeof result.durationMs === "number")
+			attributes.duration_ms = result.durationMs;
+		if ("warnings" in result && Array.isArray(result.warnings))
+			attributes.warnings = result.warnings.length;
+	}
 
 	if (duration !== undefined) {
 		attributes.duration_ms = duration;
@@ -538,18 +566,33 @@ function wrapPage<T extends object>(page: T, trace: TraceContext): T {
 			const methodName = String(property);
 			const wrapped = (...args: unknown[]) => {
 				let elapsedMs = 0;
+				const diagnostics = snapshotRequestDiagnostics("browser", methodName, args);
+				registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
 
 				return recorder.runSpan(
-					`browser.page.${methodName}`,
+					["evaluate", "content", "screenshot"].includes(methodName)
+						? `browser.${methodName}`
+						: `browser.page.${methodName}`,
 					async () => {
 						const startedAt = Date.now();
-						const result = await Reflect.apply(value, pageTarget, args);
+						let result: unknown;
+						try {
+							result = await Reflect.apply(value, pageTarget, args);
+						} catch (error) {
+							throw sanitizeRequestError(error, diagnostics);
+						}
 						elapsedMs = Date.now() - startedAt;
 						return result;
 					},
 					{
-						onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
-						onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+						onSuccess: () => ({
+							...getBrowserPageAttributes(methodName, args, elapsedMs),
+							...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+						}),
+						onError: (error) => ({
+							...getBrowserPageAttributes(methodName, args, undefined, error),
+							...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+						}),
 					},
 				);
 			};
@@ -621,10 +664,15 @@ function wrapNamespace<T extends object>(
 	trace: TraceContext,
 	shouldInstrument?: (methodName: string, args: unknown[]) => boolean,
 ): T {
-	const recorder = getTraceRecorder(trace);
-	if (!recorder) {
-		return target;
-	}
+	const baseRecorder = getTraceRecorder(trace);
+	if (!baseRecorder) return target;
+	const recorder: NonNullable<ReturnType<typeof getTraceRecorder>> =
+		namespace === "ocr" || namespace === "stt"
+			? {
+					runSpan: (name, fn, options) =>
+						runCapabilitySpan(target, () => baseRecorder.runSpan(name, fn, options)),
+				}
+			: baseRecorder;
 
 	const wrappedMethods = new Map<PropertyKey, unknown>();
 	const resolverMetadata =
@@ -719,6 +767,32 @@ function wrapNamespace<T extends object>(
 				return wrapped;
 			}
 
+			if (namespace === "browser" && property === "rawPage") {
+				if (wrappedMethods.has(property)) return wrappedMethods.get(property);
+				const wrapped = (...args: unknown[]) =>
+					recorder.runSpan("browser.rawPage", async () => {
+						const page = await Reflect.apply(value, namespaceTarget, args);
+						return wrapPage(page, trace);
+					});
+				wrappedMethods.set(property, wrapped);
+				return wrapped;
+			}
+
+			if (namespace === "browser" && property === "withIsolatedContext") {
+				if (wrappedMethods.has(property)) return wrappedMethods.get(property);
+				const wrapped = (handler: unknown, ...args: unknown[]) =>
+					recorder.runSpan("browser.withIsolatedContext", async () => {
+						if (typeof handler !== "function")
+							return Reflect.apply(value, namespaceTarget, [handler, ...args]);
+						return Reflect.apply(value, namespaceTarget, [
+							(page: object) => Reflect.apply(handler, undefined, [wrapPage(page, trace)]),
+							...args,
+						]);
+					});
+				wrappedMethods.set(property, wrapped);
+				return wrapped;
+			}
+
 			if (wrappedMethods.has(property)) {
 				return wrappedMethods.get(property);
 			}
@@ -727,18 +801,31 @@ function wrapNamespace<T extends object>(
 			if (namespace === "browser") {
 				const wrapped = (...args: unknown[]) => {
 					let elapsedMs = 0;
+					const diagnostics = snapshotRequestDiagnostics("browser", methodName, args);
+					registerDiagnosticSensitiveValues(trace, diagnostics.sensitiveValues);
 
 					return recorder.runSpan(
 						`browser.${methodName}`,
 						async () => {
 							const startedAt = Date.now();
-							const result = await Reflect.apply(value, namespaceTarget, args);
+							let result: unknown;
+							try {
+								result = await Reflect.apply(value, namespaceTarget, args);
+							} catch (error) {
+								throw sanitizeRequestError(error, diagnostics);
+							}
 							elapsedMs = Date.now() - startedAt;
 							return result;
 						},
 						{
-							onSuccess: () => getBrowserPageAttributes(methodName, args, elapsedMs),
-							onError: (error) => getBrowserPageAttributes(methodName, args, undefined, error),
+							onSuccess: () => ({
+								...getBrowserPageAttributes(methodName, args, elapsedMs),
+								...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+							}),
+							onError: (error) => ({
+								...getBrowserPageAttributes(methodName, args, undefined, error),
+								...(diagnostics.traceUrl ? { url: diagnostics.traceUrl } : {}),
+							}),
 						},
 					);
 				};
@@ -878,7 +965,9 @@ export function wrapWithInstrumentation<T extends Pick<ProviderContext, "trace">
 				property === "browser" ||
 				property === "session" ||
 				property === "state" ||
-				property === "resolver"
+				property === "resolver" ||
+				property === "ocr" ||
+				property === "stt"
 			) {
 				const namespace = property;
 				if (wrappedTargets.has(namespace)) {