@apifuse/provider-sdk 2.1.0-beta.12 → 2.1.0-beta.14

package/src/runtime/browser.ts

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import type { Frame, LaunchOptions, Locator, Page } from "playwright";
+import type { Frame, LaunchOptions, Locator, Page, Request, Route } from "playwright";
 
 import { ProviderError } from "../errors";
 import type {
@@ -11,11 +11,18 @@ import type {
 	BrowserLocator,
 	BrowserOptions,
 	BrowserPage,
+	BrowserResourceBody,
+	BrowserResourceDecision,
+	BrowserResourceMethod,
+	BrowserResourcePolicy,
+	BrowserResourceRequest,
 } from "../types";
 
 const require = createRequire(import.meta.url);
 const DEFAULT_WAIT_TIMEOUT_MS = 30_000;
 const SELECTOR_POLL_INTERVAL_MS = 100;
+const RESOURCE_POLICY_ROUTE_PATTERN = "**/*";
+const DEFAULT_RESOURCE_METHODS = ["GET", "HEAD"] as const;
 
 type PlaywrightModule = typeof import("playwright");
 type PlaywrightExtraModule = {
@@ -62,8 +69,153 @@ type CdpFrameTreeNode = {
 	};
 };
 
+type CdpFetchFulfillParams = {
+	readonly requestId: string;
+	readonly responseCode: number;
+	readonly responseHeaders?: readonly {
+		readonly name: string;
+		readonly value: string;
+	}[];
+	readonly body?: string;
+};
+
 type BrowserPageContract = BrowserPage;
 
+function toResourceBody(
+	body: BrowserResourceBody | undefined,
+): Buffer | string | undefined {
+	if (body === undefined || typeof body === "string" || Buffer.isBuffer(body)) {
+		return body;
+	}
+
+	if (body instanceof ArrayBuffer) {
+		return Buffer.from(new Uint8Array(body));
+	}
+
+	return Buffer.from(body);
+}
+
+function isResourceMethod(method: string): method is BrowserResourceMethod {
+	return method === "GET" || method === "HEAD";
+}
+
+async function toResourceRequest(
+	request: Request,
+): Promise<BrowserResourceRequest | null> {
+	const method = request.method().toUpperCase();
+	if (!isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		headers: await request.allHeaders(),
+		method,
+		resourceType: request.resourceType(),
+		url: request.url(),
+	};
+}
+
+function toCdpResourceRequest(
+	params: unknown,
+): { requestId: string; request: BrowserResourceRequest } | null {
+	if (!isRecord(params)) {
+		return null;
+	}
+
+	const requestId = params.requestId;
+	const rawRequest = params.request;
+	if (typeof requestId !== "string" || !isRecord(rawRequest)) {
+		return null;
+	}
+
+	const url = rawRequest.url;
+	const method = String(rawRequest.method ?? "").toUpperCase();
+	if (typeof url !== "string" || !isResourceMethod(method)) {
+		return null;
+	}
+
+	return {
+		requestId,
+		request: {
+			headers: toCdpResourceHeaders(rawRequest.headers),
+			method,
+			resourceType:
+				typeof params.resourceType === "string" ? params.resourceType : undefined,
+			url,
+		},
+	};
+}
+
+function getCdpPausedRequestId(params: unknown): string | null {
+	if (!isRecord(params) || typeof params.requestId !== "string") {
+		return null;
+	}
+
+	return params.requestId;
+}
+
+function toCdpResourceHeaders(value: unknown): Record<string, string> {
+	if (!isRecord(value)) {
+		return {};
+	}
+
+	const headers: Record<string, string> = {};
+	for (const [name, headerValue] of Object.entries(value)) {
+		if (typeof headerValue === "string") {
+			headers[name] = headerValue;
+		}
+	}
+
+	return headers;
+}
+
+function matchesResourceRoute(
+	match: BrowserResourcePolicy["routes"][number]["match"],
+	request: BrowserResourceRequest,
+): boolean {
+	if (typeof match === "string") {
+		return request.url === match;
+	}
+	if (match instanceof RegExp) {
+		return match.test(request.url);
+	}
+
+	return match(request);
+}
+
+function toCdpFulfillParams(
+	requestId: string,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): CdpFetchFulfillParams {
+	const body = toResourceBody(decision.body);
+	return {
+		...(body === undefined
+			? {}
+			: { body: Buffer.from(body).toString("base64") }),
+		...(decision.headers === undefined
+			? {}
+			: {
+					responseHeaders: Object.entries(decision.headers).map(
+						([name, value]) => ({ name, value }),
+					),
+				}),
+		requestId,
+		responseCode: decision.status ?? 200,
+	};
+}
+
+async function fulfillResourceRoute(
+	route: Route,
+	decision: Extract<BrowserResourceDecision, { readonly action: "fulfill" }>,
+): Promise<void> {
+	const body = toResourceBody(decision.body);
+	await route.fulfill({
+		...(body === undefined ? {} : { body }),
+		...(decision.headers === undefined ? {} : { headers: decision.headers }),
+		status: decision.status ?? 200,
+	});
+}
+
 export type BrowserClientOptions = BrowserOptions & {
 	allowedHosts?: string[];
 	cdpUrl?: string;
@@ -398,6 +550,47 @@ class PlaywrightBrowserPage implements BrowserPageContract {
 	async close(): Promise<void> {
 		await this.page.close();
 	}
+
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handler = async (route: Route): Promise<void> => {
+			const request = await toResourceRequest(route.request());
+			if (!request || !allowedMethods.has(request.method)) {
+				await route.abort("blockedbyclient");
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(request);
+				switch (decision.action) {
+					case "fulfill":
+						await fulfillResourceRoute(route, decision);
+						return;
+					case "block":
+						await route.abort("blockedbyclient");
+						return;
+				}
+			}
+
+			await route.abort("blockedbyclient");
+		};
+
+		await this.page.route(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		try {
+			return await run();
+		} finally {
+			await this.page.unroute(RESOURCE_POLICY_ROUTE_PATTERN, handler);
+		}
+	}
 }
 
 class PlaywrightBrowserClient implements SupportedBrowserClient {
@@ -1055,6 +1248,105 @@ class CdpPoolBrowserPage implements BrowserPageContract {
 		}
 	}
 
+	async withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T> {
+		const allowedMethods = new Set(
+			policy.allowedMethods ?? DEFAULT_RESOURCE_METHODS,
+		);
+		const handlePausedRequest = (params: unknown): void => {
+			void this.handleResourcePolicyPausedRequest(
+				params,
+				policy,
+				allowedMethods,
+			);
+		};
+
+		const unsubscribe = this.pageClient.on(
+			"Fetch.requestPaused",
+			handlePausedRequest,
+		);
+
+		try {
+			await this.pageClient.send("Fetch.enable", {
+				patterns: [{ requestStage: "Request", urlPattern: "*" }],
+			});
+		} catch (error) {
+			unsubscribe();
+			throw new ProviderError(
+				"CDP browser target does not support BrowserPage.withResourcePolicy()",
+				{
+					cause: error instanceof Error ? error : undefined,
+					code: "BROWSER_RUNTIME_UNSUPPORTED",
+					fix: "Use a Chromium CDP target with the Fetch domain enabled, or use the local Playwright browser runtime.",
+				},
+			);
+		}
+
+		try {
+			return await run();
+		} finally {
+			unsubscribe();
+			await this.pageClient.send("Fetch.disable");
+		}
+	}
+
+	private async handleResourcePolicyPausedRequest(
+		params: unknown,
+		policy: BrowserResourcePolicy,
+		allowedMethods: ReadonlySet<BrowserResourceMethod>,
+	): Promise<void> {
+		const requestId = getCdpPausedRequestId(params);
+		if (requestId === null) {
+			return;
+		}
+
+		try {
+			const parsed = toCdpResourceRequest(params);
+			if (!parsed || !allowedMethods.has(parsed.request.method)) {
+				await this.failCdpResourceRequest(requestId);
+				return;
+			}
+
+			for (const resourceRoute of policy.routes) {
+				if (!matchesResourceRoute(resourceRoute.match, parsed.request)) {
+					continue;
+				}
+
+				const decision = await resourceRoute.handle(parsed.request);
+				switch (decision.action) {
+					case "fulfill":
+						await this.pageClient.send(
+							"Fetch.fulfillRequest",
+							toCdpFulfillParams(parsed.requestId, decision),
+						);
+						return;
+					case "block":
+						await this.failCdpResourceRequest(parsed.requestId);
+						return;
+				}
+			}
+
+			await this.failCdpResourceRequest(parsed.requestId);
+		} catch {
+			await this.failCdpResourceRequest(requestId);
+		}
+	}
+
+	private async failCdpResourceRequest(requestId: string): Promise<void> {
+		try {
+			await this.pageClient.send("Fetch.failRequest", {
+				errorReason: "BlockedByClient",
+				requestId,
+			});
+		} catch (error) {
+			if (error instanceof Error) {
+				return;
+			}
+		}
+	}
+
 	private async initialize(): Promise<void> {
 		if (this.initialized) {
 			return;

package/src/server/serve.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 
 import { Hono } from "hono";
 import { z } from "zod";
+import { AuthAbortError, createAuthFlowHelpers } from "../auth";
 import {
 	AuthError,
 	ProviderError,
@@ -329,6 +330,7 @@ function createAuthFlowContext(
 	provider: ProviderDefinition,
 	request: AuthFlowRequest,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): {
 	context: FlowContext;
 	getPatch: () => Record<string, unknown | null> | undefined;
@@ -383,6 +385,7 @@ function createAuthFlowContext(
 			credential,
 			context: flowContextStore.context,
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
+			auth: createAuthFlowHelpers({ signal }),
 		},
 		getPatch: flowContextStore.getPatch,
 	};
@@ -1291,6 +1294,7 @@ async function handleAuthFlow(
 	request: AuthFlowRequest,
 	route: AuthRoute,
 	options: ProviderServerOptions = {},
+	signal?: AbortSignal,
 ): Promise<Response | AuthFlowResponse> {
 	const flow = provider.auth?.flow;
 	if (!flow) {
@@ -1303,6 +1307,7 @@ async function handleAuthFlow(
 		provider,
 		request,
 		options,
+		signal,
 	);
 	try {
 		const result =
@@ -1336,6 +1341,11 @@ async function handleAuthFlow(
 				? materializeAuthFlowTurn(provider, request, result)
 				: result;
 		return toAuthFlowResponse(materializedResult, getPatch());
+	} catch (error) {
+		if (error instanceof AuthAbortError) {
+			return toAuthFlowResponse(error.turn, getPatch());
+		}
+		throw error;
 	} finally {
 		context.stealth.close?.();
 	}
@@ -1450,7 +1460,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "start", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"start",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1495,6 +1511,7 @@ export function createServerApp(
 				body,
 				"continue",
 				options,
+				c.req.raw.signal,
 			);
 			logProviderSuccess(
 				logger,
@@ -1535,7 +1552,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "poll", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"poll",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1575,7 +1598,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "refresh", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"refresh",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,
@@ -1615,7 +1644,13 @@ export function createServerApp(
 				AuthFlowRequestSchema.parse(rawBody),
 				c.req.raw.headers,
 			);
-			const response = await handleAuthFlow(provider, body, "abort", options);
+			const response = await handleAuthFlow(
+				provider,
+				body,
+				"abort",
+				options,
+				c.req.raw.signal,
+			);
 			logProviderSuccess(
 				logger,
 				provider,

package/src/types.ts

@@ -331,9 +331,20 @@ export interface HealthJourneySchedule {
 	kind: "interval";
 	/** ISO 8601 duration, for example PT8H. */
 	interval: Iso8601Duration;
+	randomize?: HealthScheduleRandomization;
 	jitter?: Iso8601Duration;
 }
 
+export type HealthScheduleRandomization =
+	| {
+			mode: "centered";
+			maxOffset: Iso8601Duration;
+	  }
+	| {
+			mode: "delayed";
+			maxDelay: Iso8601Duration;
+	  };
+
 export interface HealthJourneyStep {
 	id: string;
 	description?: string;
@@ -612,6 +623,9 @@ export interface HealthCheckCase<TInput = unknown, TOutput = unknown> {
 export interface HealthCheckSuite<TInput = unknown, TOutput = unknown> {
 	/** Polling interval for the suite. All cases share this cadence. */
 	interval: ProbeInterval;
+	schedule?: {
+		randomize?: HealthScheduleRandomization;
+	};
 	/** Per-case timeout in milliseconds. Default: 30000. */
 	timeoutMs?: number;
 	/** Default degradation threshold for cases in this suite. Default: runtime threshold. */
@@ -1244,6 +1258,45 @@ export interface BrowserFrame {
 	locator(selector: string): BrowserLocator;
 }
 
+export type BrowserResourceMethod = "GET" | "HEAD";
+
+export type BrowserResourceRequest = {
+	readonly url: string;
+	readonly method: BrowserResourceMethod;
+	readonly resourceType?: string;
+	readonly headers: Readonly<Record<string, string>>;
+};
+
+export type BrowserResourceBody = Buffer | Uint8Array | ArrayBuffer | string;
+
+export type BrowserResourceDecision =
+	| {
+			readonly action: "fulfill";
+			readonly status?: number;
+			readonly headers?: Readonly<Record<string, string>>;
+			readonly body?: BrowserResourceBody;
+	  }
+	| {
+			readonly action: "block";
+			readonly reason?: string;
+	  };
+
+export type BrowserResourceRoute = {
+	readonly match:
+		| string
+		| RegExp
+		| ((request: BrowserResourceRequest) => boolean);
+	readonly handle: (
+		request: BrowserResourceRequest,
+	) => Promise<BrowserResourceDecision> | BrowserResourceDecision;
+};
+
+export type BrowserResourcePolicy = {
+	readonly defaultAction?: "block";
+	readonly allowedMethods?: readonly BrowserResourceMethod[];
+	readonly routes: readonly BrowserResourceRoute[];
+};
+
 export interface BrowserPage extends BrowserFrame {
 	close(): Promise<void>;
 	fill(selector: string, text: string): Promise<void>;
@@ -1257,6 +1310,10 @@ export interface BrowserPage extends BrowserFrame {
 		options?: { timeout?: number },
 	): Promise<void>;
 	frames(): Promise<BrowserFrame[]>;
+	withResourcePolicy<T>(
+		policy: BrowserResourcePolicy,
+		run: () => Promise<T>,
+	): Promise<T>;
 }
 
 export type BrowserChallengeRequest = {
@@ -1435,6 +1492,84 @@ export interface ContextScratchpad {
 
 export type FlowContextStore = ContextScratchpad;
 
+export type AuthSafeJson =
+	| string
+	| number
+	| boolean
+	| null
+	| readonly AuthSafeJson[]
+	| { readonly [key: string]: AuthSafeJson };
+
+export type AuthSafeData = { readonly [key: string]: AuthSafeJson };
+
+export type AuthAbortRetry = "never" | "retry" | "after_user_action";
+
+export type AuthAbortData = Record<string, unknown> & {
+	readonly code: string;
+	readonly message?: string;
+	readonly retry?: AuthAbortRetry;
+	readonly actionHint?: AuthSafeJson;
+	readonly fieldErrors?: { readonly [field: string]: string };
+	readonly details?: AuthSafeData;
+};
+
+export interface AuthFlowTerminalContext {
+	readonly signal?: AbortSignal;
+	readonly deadline?: string;
+	complete<TCredential extends Record<string, string>>(options: {
+		readonly credential: TCredential;
+		readonly metadata?: AuthSafeData;
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+	}): AuthTurn;
+	abort(options: {
+		readonly code: string;
+		readonly message?: string;
+		readonly retry?: AuthAbortRetry;
+		readonly actionHint?: AuthSafeJson;
+		readonly fieldErrors?: { readonly [field: string]: string };
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+	}): AuthTurn;
+	nextForm(
+		options: {
+			readonly hintKey?: ProviderLocaleKeyInput;
+			readonly data?: AuthSafeData;
+			readonly turnId?: string;
+			readonly expiresAt?: string;
+			readonly timing?: AuthTurn["timing"];
+		} & (
+			| {
+					readonly fields: Record<
+						string,
+						{
+							readonly type?: "string" | "email" | "password" | "otp";
+							readonly labelKey?: ProviderLocaleKeyInput;
+							readonly descriptionKey?: ProviderLocaleKeyInput;
+							readonly placeholderKey?: ProviderLocaleKeyInput;
+							readonly required?: boolean;
+							readonly sensitive?: boolean;
+						}
+					>;
+					readonly expectedInput?: never;
+			  }
+			| {
+					readonly expectedInput: Record<string, unknown>;
+					readonly fields?: never;
+			  }
+		),
+	): AuthTurn;
+	nextPoll(options?: {
+		readonly hintKey?: ProviderLocaleKeyInput;
+		readonly data?: AuthSafeData;
+		readonly turnId?: string;
+		readonly expiresAt?: string;
+		readonly timing?: AuthTurn["timing"];
+	}): AuthTurn;
+}
+
 export interface FlowContext {
 	connectionId?: string;
 	externalRef?: string;
@@ -1446,6 +1581,7 @@ export interface FlowContext {
 	credential?: CredentialContext;
 	context: ContextScratchpad;
 	stt: SttContext;
+	auth: AuthFlowTerminalContext;
 }
 
 export interface AuthTurn {