@apifuse/provider-sdk 2.2.0-beta.5 → 2.2.0-beta.51

package/src/runtime/insights.ts

@@ -27,7 +27,7 @@ const DNS_WARN_MS = 5;
 const BROWSER_IDLE_MS = 5_000;
 const REFRESH_WARN_RATE = 0.1;
 
-const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+const TLS_REUSE_FIX = `const session = ctx.stealth.createSession({ stealth: { browser: 'chrome', os: 'macos' } });
 const resp = await session.fetch(url, opts);`;
 
 const TRANSFORM_FIX = `transformResponse: (raw) => {
@@ -39,7 +39,7 @@ const LARGE_RESPONSE_FIX = `const resp = await ctx.http.get('/items', {
 });`;
 
 const DNS_FIX = `// Enable DNS caching or reuse a long-lived session per host.
-const session = ctx.stealth.createSession({ profile: 'chrome-146' });
+const session = ctx.stealth.createSession({ stealth: { browser: 'chrome', os: 'macos' } });
 await session.fetch(url, opts);`;
 
 const PROXY_FIX = `// Re-check whether this operation really needs a proxy.

package/src/runtime/instrumentation.ts

@@ -1,20 +1,60 @@
-import type { ProviderContext } from "../types.js";
+import type {
+	HttpStreamResponse,
+	ProviderContext,
+	RequestOptions,
+	SseMessage,
+	StealthSession,
+	StealthRedirectRunResult,
+} from "../types.js";
+import { readableBytes, readableLines, readableTextChunks } from "../stream.js";
+import {
+	parseHttpRequestInvocation,
+	isSensitiveKey,
+	redactSensitiveError,
+	redactSensitiveText,
+	redactUrlQueryParams,
+	requestOptionsFromHttpInvocation,
+	serializeRequestUrl,
+	type SerializedRequestUrl,
+} from "./request-options.js";
 import {
 	type CreateTraceContextOptions,
 	createTraceContext,
 	getTraceRecorder,
 	type TraceContext,
 } from "./trace.js";
+import { RESOLVER_INSTRUMENTATION_METADATA } from "./resolver-shared.js";
 
 export interface InstrumentationOptions extends CreateTraceContextOptions {}
 
-export type InstrumentedProviderContext<T extends ProviderContext> = Omit<T, "trace"> & {
+export type InstrumentedProviderContext<T extends Pick<ProviderContext, "trace">> = Omit<
+	T,
+	"trace"
+> & {
 	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";
+
+type RequestDiagnostics = {
+	diagnosticUrlDegraded?: boolean;
+	requestId?: string;
+	serializedUrl?: SerializedRequestUrl;
+	sensitiveParamNames: readonly string[];
+	sensitiveValues: readonly string[];
+	traceUrl?: string;
+};
+
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+	return (
+		(typeof value === "object" || typeof value === "function") &&
+		value !== null &&
+		typeof (value as { then?: unknown }).then === "function"
+	);
+}
 
 function getErrorStatus(error: unknown): number | undefined {
 	if (
@@ -84,12 +124,231 @@ function getUrl(
 	return undefined;
 }
 
+function requestOptionsForInvocation(
+	namespace: InstrumentedNamespace,
+	methodName: string,
+	args: readonly unknown[],
+): RequestOptions | undefined {
+	if (namespace === "http") {
+		const invocation = parseHttpRequestInvocation(methodName, [...args]);
+		return invocation ? requestOptionsFromHttpInvocation(invocation) : undefined;
+	}
+	if (namespace !== "stealth" || methodName !== "fetch" || typeof args[0] !== "string") {
+		return undefined;
+	}
+	const options = args[1];
+	return options !== null && typeof options === "object" && !Array.isArray(options)
+		? (options as RequestOptions)
+		: undefined;
+}
+
+function fallbackSensitiveValues(options?: RequestOptions): readonly string[] {
+	const sensitiveParams = options?.sensitiveParams;
+	if (!sensitiveParams || typeof sensitiveParams !== "object") return [];
+	return Object.values(sensitiveParams).map(String);
+}
+
+function stripDiagnosticBase(url: string): string {
+	return url.startsWith(DIAGNOSTIC_BASE_URL) ? url.slice(DIAGNOSTIC_BASE_URL.length) || "/" : url;
+}
+
+function serializeDiagnosticUrl(
+	url: string,
+	options?: RequestOptions,
+): { degraded: boolean; serializedUrl: SerializedRequestUrl } {
+	try {
+		return {
+			degraded: false,
+			serializedUrl: serializeRequestUrl(url, options?.params, options?.sensitiveParams),
+		};
+	} catch {
+		try {
+			const absoluteUrl = new URL(url, DIAGNOSTIC_BASE_URL).toString();
+			const serialized = serializeRequestUrl(
+				absoluteUrl,
+				options?.params,
+				options?.sensitiveParams,
+			);
+			return {
+				degraded: false,
+				serializedUrl: {
+					requestUrl: stripDiagnosticBase(serialized.requestUrl),
+					redactedUrl: stripDiagnosticBase(serialized.redactedUrl),
+					sensitiveValues: serialized.sensitiveValues,
+				},
+			};
+		} catch {
+			const sensitiveParamNames = Object.keys(options?.sensitiveParams ?? {});
+			const structural = redactUrlQueryParams(url, sensitiveParamNames);
+			return {
+				degraded: true,
+				serializedUrl: {
+					requestUrl: url,
+					redactedUrl: structural.redactedUrl,
+					sensitiveValues: [
+						...new Set([...fallbackSensitiveValues(options), ...structural.sensitiveValues]),
+					],
+				},
+			};
+		}
+	}
+}
+
+function snapshotRequestDiagnostics(
+	namespace: InstrumentedNamespace,
+	methodName: string,
+	args: readonly unknown[],
+): RequestDiagnostics {
+	const options = requestOptionsForInvocation(namespace, methodName, args);
+	const url = typeof args[0] === "string" ? args[0] : undefined;
+	const hasSensitiveParams = Boolean(
+		options?.sensitiveParams && Object.keys(options.sensitiveParams).length > 0,
+	);
+	const sensitiveParamNames = Object.keys(options?.sensitiveParams ?? {});
+	const diagnosticUrl =
+		hasSensitiveParams && url ? serializeDiagnosticUrl(url, options) : undefined;
+	const traceUrl =
+		hasSensitiveParams && url
+			? serializeDiagnosticUrl(url, { sensitiveParams: options?.sensitiveParams }).serializedUrl
+					.redactedUrl
+			: undefined;
+	return {
+		...(diagnosticUrl?.degraded ? { diagnosticUrlDegraded: true } : {}),
+		...(hasSensitiveParams ? { requestId: crypto.randomUUID() } : {}),
+		serializedUrl: diagnosticUrl?.serializedUrl,
+		sensitiveParamNames,
+		sensitiveValues:
+			diagnosticUrl?.serializedUrl.sensitiveValues ?? fallbackSensitiveValues(options),
+		traceUrl,
+	};
+}
+
+function sanitizeRequestError(error: unknown, diagnostics: RequestDiagnostics): unknown {
+	return redactSensitiveError(
+		error,
+		diagnostics.sensitiveValues,
+		diagnostics.serializedUrl?.requestUrl,
+		diagnostics.serializedUrl?.redactedUrl,
+	);
+}
+
+function isHttpStreamResponse(value: unknown): value is HttpStreamResponse {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"body" in value &&
+		value.body instanceof ReadableStream
+	);
+}
+
+function instrumentHttpStreamConsumption(
+	value: HttpStreamResponse,
+	recorder: NonNullable<ReturnType<typeof getTraceRecorder>>,
+	args: unknown[],
+	diagnostics: RequestDiagnostics,
+): HttpStreamResponse {
+	const source = value.body;
+	let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+	const body = new ReadableStream<Uint8Array>(
+		{
+			async pull(controller) {
+				try {
+					reader ??= source.getReader();
+					const chunk = await reader.read();
+					if (chunk.done) {
+						controller.close();
+						return;
+					}
+					controller.enqueue(chunk.value);
+				} catch (error) {
+					const sanitizedError = sanitizeRequestError(error, diagnostics);
+					try {
+						await recorder.runSpan(
+							"http.stream.consume",
+							() => {
+								throw sanitizedError;
+							},
+							{
+								onError: (spanError) =>
+									buildSpanAttributes("http", "stream", args, undefined, spanError, diagnostics),
+							},
+						);
+					} catch (recordedError) {
+						controller.error(recordedError);
+					}
+				}
+			},
+			async cancel(reason) {
+				try {
+					await (reader ? reader.cancel(reason) : source.cancel(reason));
+				} catch (error) {
+					throw sanitizeRequestError(error, diagnostics);
+				}
+			},
+		},
+		{ highWaterMark: 0 },
+	);
+
+	const instrumented = {
+		...value,
+		body,
+		bytes: () => readableBytes(body),
+		textChunks: () => readableTextChunks(body),
+		lines: () => readableLines(body),
+	} satisfies HttpStreamResponse;
+	try {
+		Object.assign(value, instrumented);
+		return value;
+	} catch {
+		return instrumented;
+	}
+}
+
+function isAsyncIterable<T = unknown>(value: unknown): value is AsyncIterable<T> {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		Symbol.asyncIterator in value &&
+		typeof value[Symbol.asyncIterator] === "function"
+	);
+}
+
+function instrumentHttpSseConsumption(
+	value: AsyncIterable<SseMessage>,
+	recorder: NonNullable<ReturnType<typeof getTraceRecorder>>,
+	args: unknown[],
+	diagnostics: RequestDiagnostics,
+): AsyncIterable<SseMessage> {
+	const source = value;
+	return {
+		async *[Symbol.asyncIterator]() {
+			try {
+				for await (const event of source) yield event;
+			} catch (error) {
+				const sanitizedError = sanitizeRequestError(error, diagnostics);
+				return await recorder.runSpan(
+					"http.sse.consume",
+					() => {
+						throw sanitizedError;
+					},
+					{
+						onError: (spanError) =>
+							buildSpanAttributes("http", "sse", args, undefined, spanError, diagnostics),
+					},
+				);
+			}
+		},
+	};
+}
+
 function getMethod(
 	namespace: InstrumentedNamespace,
 	methodName: string,
 	args: unknown[],
 ): string | undefined {
 	if (namespace === "http") {
+		// Preserve the original instrumentation contract: generic entry points are
+		// reported as REQUEST/STREAM/SSE, independent of transport options.
 		return methodName.toUpperCase();
 	}
 
@@ -111,9 +370,19 @@ function buildSpanAttributes(
 	args: unknown[],
 	result?: unknown,
 	error?: unknown,
+	diagnostics: RequestDiagnostics = { sensitiveParamNames: [], sensitiveValues: [] },
 ): Record<string, string | number | boolean> {
 	const attributes: Record<string, string | number | boolean> = {};
-	const url = getUrl(namespace, args, result);
+	const rawUrl = getUrl(namespace, args, result);
+	const structuralUrl = diagnostics.traceUrl ?? rawUrl;
+	const url = structuralUrl
+		? redactSensitiveText(
+				structuralUrl,
+				diagnostics.sensitiveValues,
+				diagnostics.serializedUrl?.requestUrl,
+				diagnostics.serializedUrl?.redactedUrl,
+			)
+		: undefined;
 	const method = getMethod(namespace, methodName, args);
 	const status = error ? getErrorStatus(error) : getResponseStatus(namespace, result);
 	const duration = error ? undefined : getResponseDuration(result);
@@ -121,6 +390,8 @@ function buildSpanAttributes(
 	if (url) {
 		attributes.url = url;
 	}
+	if (diagnostics.requestId) attributes.request_id = diagnostics.requestId;
+	if (diagnostics.diagnosticUrlDegraded) attributes.redaction_degraded = true;
 
 	if (method) {
 		attributes.method = method;
@@ -145,6 +416,64 @@ function buildSpanAttributes(
 	return attributes;
 }
 
+function isStealthRedirectRunResult(value: unknown): value is StealthRedirectRunResult {
+	return (
+		typeof value === "object" &&
+		value !== null &&
+		"reason" in value &&
+		typeof value.reason === "string" &&
+		"hops" in value &&
+		Array.isArray(value.hops) &&
+		"final" in value &&
+		typeof value.final === "object" &&
+		value.final !== null
+	);
+}
+
+function buildStealthRedirectAttributes(
+	args: unknown[],
+	result: unknown,
+	error: unknown,
+	diagnostics: RequestDiagnostics,
+): Record<string, string | number | boolean> {
+	const attributes = buildSpanAttributes("stealth", "fetch", args, undefined, error, diagnostics);
+	if (!isStealthRedirectRunResult(result)) return attributes;
+
+	attributes.redirect_reason = result.reason;
+	attributes.redirect_hop_count = result.hops.length;
+	attributes.status = result.final.status;
+	if (result.hops.length > 0) {
+		const sensitiveValues = new Set(diagnostics.sensitiveValues);
+		const path = result.hops
+			.map((hop) => {
+				const hopUrl = hop.nextUrl ?? hop.url;
+				const responseSensitiveParamNames = [...queryParamNames(hopUrl)].filter(isSensitiveKey);
+				const structural = redactUrlQueryParams(hopUrl, [
+					...new Set([...diagnostics.sensitiveParamNames, ...responseSensitiveParamNames]),
+				]);
+				for (const value of structural.sensitiveValues) sensitiveValues.add(value);
+				const safeUrl = redactSensitiveText(structural.redactedUrl, [...sensitiveValues]);
+				return `${hop.method} ${hop.status} ${safeUrl}`;
+			})
+			.join(" -> ");
+		attributes.redirect_path = redactSensitiveText(
+			path,
+			[...sensitiveValues],
+			diagnostics.serializedUrl?.requestUrl,
+			diagnostics.serializedUrl?.redactedUrl,
+		);
+	}
+	return attributes;
+}
+
+function queryParamNames(url: string): Set<string> {
+	const queryStart = url.indexOf("?");
+	if (queryStart === -1) return new Set();
+	const fragmentStart = url.indexOf("#", queryStart);
+	const query = url.slice(queryStart + 1, fragmentStart === -1 ? undefined : fragmentStart);
+	return new Set(new URLSearchParams(query).keys());
+}
+
 function getBrowserPageAttributes(
 	methodName: string,
 	args: unknown[],
@@ -230,10 +559,65 @@ function wrapPage<T extends object>(page: T, trace: TraceContext): T {
 	});
 }
 
+function wrapStealthRedirects(
+	redirects: StealthSession["redirects"],
+	trace: TraceContext,
+): StealthSession["redirects"] {
+	const recorder = getTraceRecorder(trace);
+	if (!recorder) return redirects;
+
+	return {
+		run(...args: Parameters<StealthSession["redirects"]["run"]>) {
+			const diagnosticArgs = [args[0].url, args[0]];
+			const diagnostics = snapshotRequestDiagnostics("stealth", "fetch", diagnosticArgs);
+			let result: ReturnType<StealthSession["redirects"]["run"]>;
+			try {
+				result = redirects.run(...args);
+			} catch (error) {
+				const sanitizedError = sanitizeRequestError(error, diagnostics);
+				recorder
+					.runSpan(
+						"stealth.redirects.run",
+						() => {
+							throw sanitizedError;
+						},
+						{
+							onError: (spanError) =>
+								buildStealthRedirectAttributes(diagnosticArgs, undefined, spanError, diagnostics),
+						},
+					)
+					.catch(() => undefined);
+				throw sanitizedError;
+			}
+
+			const sanitizedResult = Promise.resolve(result).catch((error: unknown) => {
+				throw sanitizeRequestError(error, diagnostics);
+			});
+			return recorder.runSpan("stealth.redirects.run", () => sanitizedResult, {
+				onSuccess: (spanResult) =>
+					buildStealthRedirectAttributes(diagnosticArgs, spanResult, undefined, diagnostics),
+				onError: (error) =>
+					buildStealthRedirectAttributes(diagnosticArgs, undefined, error, diagnostics),
+			});
+		},
+	};
+}
+
+function wrapStealthSession(session: StealthSession, trace: TraceContext): StealthSession {
+	const wrappedSession = wrapNamespace("stealth", session, trace);
+	const redirects = wrapStealthRedirects(session.redirects, trace);
+	return new Proxy(wrappedSession, {
+		get(target, property, receiver) {
+			return property === "redirects" ? redirects : Reflect.get(target, property, receiver);
+		},
+	});
+}
+
 function wrapNamespace<T extends object>(
 	namespace: InstrumentedNamespace,
 	target: T,
 	trace: TraceContext,
+	shouldInstrument?: (methodName: string, args: unknown[]) => boolean,
 ): T {
 	const recorder = getTraceRecorder(trace);
 	if (!recorder) {
@@ -241,15 +625,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);
@@ -329,15 +745,103 @@ function wrapNamespace<T extends object>(
 				return wrapped;
 			}
 
-			const wrapped = (...args: unknown[]) =>
-				recorder.runSpan(
-					`${namespace}.${methodName}`,
-					() => Reflect.apply(value, namespaceTarget, args),
-					{
-						onSuccess: (result) => buildSpanAttributes(namespace, methodName, args, result),
-						onError: (error) => buildSpanAttributes(namespace, methodName, args, undefined, error),
-					},
-				);
+			const wrapped = (...args: unknown[]) => {
+				if (shouldInstrument && !shouldInstrument(methodName, args)) {
+					return Reflect.apply(value, namespaceTarget, args);
+				}
+				const requestDiagnostics = snapshotRequestDiagnostics(namespace, methodName, args);
+				// Invoke first and decide by the RETURN VALUE. `runSpan` always
+				// returns a Promise, so unconditionally span-wrapping every member
+				// silently rewrote synchronous contracts: `ctx.state.namespace()`
+				// (a sync factory) came back as a Promise, and every method call on
+				// it threw a raw TypeError — surfaced in production as catchtable's
+				// deterministic CONFIRM_STATE_UNAVAILABLE on 2026-07-27 (and the
+				// 2026-07-22 reserve internal_error loop before it). Sync members
+				// keep their sync contract; only genuinely async operations are
+				// recorded as spans.
+				let result: unknown;
+				try {
+					result = Reflect.apply(value, namespaceTarget, args);
+				} catch (error) {
+					const sanitizedError = sanitizeRequestError(error, requestDiagnostics);
+					// A promise-returning implementation may still throw
+					// SYNCHRONOUSLY during pre-flight validation. Preserve the
+					// synchronous throw contract, but keep recording the failure
+					// span (the pre-fidelity wrapper captured these).
+					recorder
+						.runSpan(
+							`${namespace}.${methodName}`,
+							() => {
+								throw sanitizedError;
+							},
+							{
+								onError: (spanError) =>
+									buildSpanAttributes(
+										namespace,
+										methodName,
+										args,
+										undefined,
+										spanError,
+										requestDiagnostics,
+									),
+							},
+						)
+						.catch(() => undefined);
+					throw sanitizedError;
+				}
+				if (!isThenable(result)) {
+					// The state namespace factory returns the object whose METHODS
+					// are the operations worth tracing — instrument that object so
+					// `state.get`/`state.compareAndSet`/… spans exist (they never
+					// could before: the factory's return value was destroyed).
+					if (
+						namespace === "state" &&
+						methodName === "namespace" &&
+						typeof result === "object" &&
+						result !== null
+					) {
+						return wrapNamespace(namespace, result, trace);
+					}
+					if (
+						namespace === "stealth" &&
+						methodName === "createSession" &&
+						typeof result === "object" &&
+						result !== null
+					) {
+						return wrapStealthSession(result as StealthSession, trace);
+					}
+					return result;
+				}
+				const sanitizedResult = Promise.resolve(result).catch((error: unknown) => {
+					throw sanitizeRequestError(error, requestDiagnostics);
+				});
+				const tracedResult = recorder.runSpan(`${namespace}.${methodName}`, () => sanitizedResult, {
+					onSuccess: (spanResult) =>
+						buildSpanAttributes(
+							namespace,
+							methodName,
+							args,
+							spanResult,
+							undefined,
+							requestDiagnostics,
+						),
+					onError: (error) =>
+						buildSpanAttributes(namespace, methodName, args, undefined, error, requestDiagnostics),
+				});
+				return namespace === "http" && methodName === "stream"
+					? tracedResult.then((spanResult) =>
+							isHttpStreamResponse(spanResult)
+								? instrumentHttpStreamConsumption(spanResult, recorder, args, requestDiagnostics)
+								: spanResult,
+						)
+					: namespace === "http" && methodName === "sse"
+						? tracedResult.then((spanResult) =>
+								isAsyncIterable<SseMessage>(spanResult)
+									? instrumentHttpSseConsumption(spanResult, recorder, args, requestDiagnostics)
+									: spanResult,
+							)
+						: tracedResult;
+			};
 
 			wrappedMethods.set(property, wrapped);
 			return wrapped;
@@ -349,7 +853,7 @@ function hasTraceOverrides(options: InstrumentationOptions): boolean {
 	return options.maxSpans !== undefined || options.onSpan !== undefined;
 }
 
-export function wrapWithInstrumentation<T extends ProviderContext>(
+export function wrapWithInstrumentation<T extends Pick<ProviderContext, "trace">>(
 	ctx: T,
 	options: InstrumentationOptions = {},
 ): InstrumentedProviderContext<T> {
@@ -370,7 +874,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)) {