@apifuse/provider-sdk 2.1.0-beta.4 → 2.1.0-beta.6

package/src/server/serve.ts

@@ -1,6 +1,20 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
 import { Hono } from "hono";
 import { z } from "zod";
-import { ProviderError, TransportError } from "../errors";
+import {
+	AuthError,
+	ProviderError,
+	SessionExpiredError,
+	TransportError,
+} from "../errors";
+import {
+	loadProviderLocaleCatalogs,
+	localizeAuthTurn,
+	type ProviderLocaleCatalogMap,
+} from "../i18n/catalog";
+import type { ProviderLocale } from "../i18n/keys";
 import {
 	categoryForStatus,
 	isRetryableCategory,
@@ -10,6 +24,10 @@ import {
 import { createScratchpad } from "../runtime/auth-flow";
 import { createBrowserClient } from "../runtime/browser";
 import { createProviderCache } from "../runtime/cache";
+import {
+	createProviderChoiceContext,
+	PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+} from "../runtime/choice";
 import { createCredentialContext } from "../runtime/credential";
 import { createEnvContext } from "../runtime/env";
 import { executeOperation } from "../runtime/executor";
@@ -25,7 +43,10 @@ import {
 	PROVIDER_TELEMETRY_HEADER,
 	ProxyTelemetryCollector,
 } from "../runtime/proxy-telemetry";
-import { createUnsupportedProviderRuntimeState } from "../runtime/state";
+import {
+	createProviderRuntimeStateFromEnv,
+	createUnsupportedProviderRuntimeState,
+} from "../runtime/state";
 import { createStealthClient } from "../runtime/stealth";
 import { createSttClientFromEnv } from "../runtime/stt";
 import { createTraceContext } from "../runtime/trace";
@@ -39,6 +60,7 @@ import {
 } from "../stream";
 import type {
 	AuthContext,
+	AuthTurn,
 	BrowserClient,
 	FlowContext,
 	FlowContextStore,
@@ -48,6 +70,7 @@ import type {
 	OperationSseTransport,
 	ProviderContext,
 	ProviderDefinition,
+	ProviderRuntimeState,
 	ProviderStreamEvent,
 	StealthClient,
 	SttContext,
@@ -66,8 +89,11 @@ import {
 
 const DEFAULT_HOST = "0.0.0.0";
 const DEFAULT_PORT = 3000;
+const AUTH_FLOW_LOCALES = ["en", "ko", "ja"] as const;
 const retryResponseMeta = new WeakMap<ProviderContext, HttpRetrySummary>();
 
+type RequestCleanup = () => void | Promise<void>;
+
 function createAuthStub(): AuthContext {
 	return {
 		async requestField(name) {
@@ -81,11 +107,27 @@ function createAuthStub(): AuthContext {
 function createBrowserStub(): BrowserClient {
 	return {
 		engine: "playwright-stealth",
+		async close() {},
 		async newPage() {
 			throw new ProviderError("Browser runtime is not available", {
 				code: "BROWSER_RUNTIME_UNSUPPORTED",
 			});
 		},
+		async rawPage() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+		async withIsolatedContext() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+		async solveChallenge() {
+			throw new ProviderError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
 	};
 }
 
@@ -124,6 +166,23 @@ function getProviderStealthProfile(provider: ProviderDefinition) {
 		: undefined;
 }
 
+function isProductionProviderBrowserMode(
+	provider: ProviderDefinition,
+	env = process.env,
+): boolean {
+	if (provider.runtime !== "browser") {
+		return false;
+	}
+
+	if (env.APIFUSE__PROVIDER__RUNTIME === "browser") {
+		return true;
+	}
+
+	return (
+		env.NODE_ENV === "production" && env.APIFUSE__PROVIDER__ID === provider.id
+	);
+}
+
 export function resolveProviderProxyAffinityKey(
 	provider: ProviderDefinition,
 	request: OperationRequest,
@@ -146,6 +205,7 @@ function createProviderContext(
 	request: OperationRequest,
 	operationId: string,
 	options: ProviderServerOptions = {},
+	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
 ): ProviderContext {
 	const baseUrl = getProviderBaseUrl(provider);
@@ -167,18 +227,24 @@ function createProviderContext(
 		telemetry: proxyTelemetry,
 	};
 
+	const env = createEnvContext([
+		...(provider.secrets?.map((secret) => secret.name) ?? []),
+		PROVIDER_RUNTIME_CHOICE_TOKEN_MASTER_SECRET_ENV,
+	]);
+	const credential = createCredentialContext({
+		allowedKeys: provider.credential?.keys,
+		mode: request.connection?.mode,
+		scopes: request.connection?.scopes,
+		values: request.connection?.secrets,
+	});
+	const requestContext = {
+		connectionId: request.connection?.id,
+		headers: request.headers ?? {},
+	};
 	const context = wrapWithInstrumentation({
-		env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
-		credential: createCredentialContext({
-			allowedKeys: provider.credential?.keys,
-			mode: request.connection?.mode,
-			scopes: request.connection?.scopes,
-			values: request.connection?.secrets,
-		}),
-		request: {
-			connectionId: request.connection?.id,
-			headers: request.headers ?? {},
-		},
+		env,
+		credential,
+		request: requestContext,
 		http: createHttpClient(baseUrl, {
 			...proxyClientOptions,
 			onRetrySummary: (summary) => {
@@ -187,7 +253,7 @@ function createProviderContext(
 			},
 		}),
 		cache: createProviderCache({ providerId: provider.id }),
-		state: createUnsupportedProviderRuntimeState(),
+		state,
 		stealth: stealthBaseUrl
 			? stealthProfile
 				? createStealthClient(
@@ -200,8 +266,10 @@ function createProviderContext(
 		browser:
 			provider.runtime === "browser"
 				? createBrowserClient({
+						allowedHosts: provider.allowedHosts,
 						cdpUrl: process.env.APIFUSE__CDP_POOL__URL,
 						headless: true,
+						requireCdpPool: isProductionProviderBrowserMode(provider),
 						stealth: true,
 						engine: provider.browser?.engine,
 					})
@@ -209,6 +277,13 @@ function createProviderContext(
 		trace: createTraceContext(),
 		auth: createAuthStub(),
 		stt: options.stt ?? createSttClientFromEnv(provider.stt),
+		choice: createProviderChoiceContext({
+			providerId: provider.id,
+			env,
+			request: requestContext,
+			credential,
+			state,
+		}),
 	});
 	wrappedContext = context;
 	return context;
@@ -279,6 +354,14 @@ function createAuthFlowContext(
 		upstream: proxyClientOptions.upstream,
 		affinityKey: proxyClientOptions.affinityKey,
 	};
+	const credential = request.connection
+		? createCredentialContext({
+				allowedKeys: provider.credential?.keys,
+				mode: request.connection.mode,
+				scopes: request.connection.scopes,
+				values: request.connection.secrets,
+			})
+		: undefined;
 
 	return {
 		context: {
@@ -297,6 +380,7 @@ function createAuthFlowContext(
 					: createStealthClient(stealthBaseUrl, stealthClientOptions)
 				: createStealthStub(),
 			env: createEnvContext(provider.secrets?.map((secret) => secret.name)),
+			credential,
 			context: flowContextStore.context,
 			stt: options.stt ?? createSttClientFromEnv(provider.stt),
 		},
@@ -335,7 +419,18 @@ export type ProviderServerLogEvent =
 			taxonomyVersion?: string;
 			retryable?: boolean;
 			issues?: Array<{ path: string; code: string; message: string }>;
-	  });
+	  })
+	| {
+			level: "warn";
+			event: "provider_cleanup_failed";
+			providerId: string;
+			kind: "operation";
+			route: string;
+			requestId?: string;
+			resource: "browser" | "stealth";
+			errorClass: string;
+			message: string;
+	  };
 
 export type ProviderServerLogger = (event: ProviderServerLogEvent) => void;
 
@@ -343,6 +438,10 @@ export type ProviderServerOptions = {
 	logger?: ProviderServerLogger;
 	/** Optional STT override for tests or custom hosts; local/prod normally resolves from env. */
 	stt?: SttContext;
+	/** Optional runtime state override for tests or custom hosts. Production resolves Redis from env and fails closed when unavailable. */
+	state?: ProviderRuntimeState;
+	/** Allow process-local runtime state only for local development and tests. */
+	allowMemoryStateFallback?: boolean;
 };
 
 const defaultProviderServerLogger: ProviderServerLogger = (event) => {
@@ -457,6 +556,18 @@ function providerObservabilityDetails(error: ProviderError):
 			upstreamStatus?: number;
 	  }
 	| undefined {
+	// Session-expiry surfaces the credential_expired category + the opt-in
+	// retryable signal so Gateway/Credential Service can refresh and re-drive the
+	// operation (see design.md §4.3 D3). Without this branch the auth error would
+	// serialize as a bare 401 with no retryable/category, losing the refresh
+	// signal for exactly the retryOnAuthRefresh operations it is meant to enable.
+	if (error instanceof SessionExpiredError) {
+		return {
+			category: error.options?.category ?? "credential_expired",
+			taxonomyVersion: PROVIDER_OBSERVABILITY_TAXONOMY_VERSION,
+			retryable: error.options?.retryable ?? false,
+		};
+	}
 	if (!(error instanceof TransportError)) {
 		return undefined;
 	}
@@ -513,7 +624,9 @@ function publicProviderErrorMessage(error: ProviderError): string {
 	return error.message;
 }
 
-function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 503 | 504 {
+function toStatusCode(
+	error: unknown,
+): 400 | 401 | 404 | 429 | 500 | 502 | 503 | 504 {
 	if (error instanceof z.ZodError) {
 		return 400;
 	}
@@ -524,6 +637,9 @@ function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 503 | 504 {
 
 	if (error instanceof ProviderError) {
 		switch (error.code) {
+			case "AUTH_REQUIRED":
+			case "reauth_required":
+				return 401;
 			case "NOT_FOUND":
 			case "not_found":
 			case "NO_DATA":
@@ -533,6 +649,7 @@ function toStatusCode(error: unknown): 400 | 404 | 429 | 500 | 502 | 503 | 504 {
 			case "LIMITED_NUMBER_OF_SERVICE_REQUESTS_EXCEEDS_ERROR":
 				return 429;
 			case "UPSTREAM_ERROR":
+			case "BLOCKED":
 				return 502;
 			case "STT_UNAVAILABLE":
 			case "UNSUPPORTED_STT_BACKEND":
@@ -604,6 +721,31 @@ function logProviderError(
 	});
 }
 
+function logProviderCleanupError(
+	logger: ProviderServerLogger | unknown,
+	provider: ProviderDefinition,
+	operationId: string,
+	requestId: string | undefined,
+	resource: "browser" | "stealth",
+	error: unknown,
+): void {
+	const emit =
+		typeof logger === "function" ? logger : defaultProviderServerLogger;
+	const errorClass = error instanceof Error ? error.name : typeof error;
+	const message = error instanceof Error ? error.message : String(error);
+	emit({
+		level: "warn",
+		event: "provider_cleanup_failed",
+		providerId: provider.id,
+		kind: "operation",
+		route: operationId,
+		...(requestId ? { requestId } : {}),
+		resource,
+		errorClass,
+		message,
+	});
+}
+
 function logProviderSuccess(
 	logger: ProviderServerLogger | unknown,
 	provider: ProviderDefinition,
@@ -670,18 +812,18 @@ function isAsyncIterable<T = unknown>(
 
 function responseWithCleanup(
 	response: Response,
-	cleanup: () => void,
+	cleanup: RequestCleanup,
 ): Response {
 	if (!response.body) {
-		cleanup();
+		void cleanup();
 		return response;
 	}
 	const reader = response.body.getReader();
 	let cleaned = false;
-	const runCleanup = () => {
+	const runCleanup = async () => {
 		if (cleaned) return;
 		cleaned = true;
-		cleanup();
+		await cleanup();
 	};
 	const body = new ReadableStream<Uint8Array>({
 		async pull(controller) {
@@ -689,12 +831,12 @@ function responseWithCleanup(
 				const { done, value } = await reader.read();
 				if (done) {
 					controller.close();
-					runCleanup();
+					await runCleanup();
 					return;
 				}
 				if (value) controller.enqueue(value);
 			} catch (error) {
-				runCleanup();
+				await runCleanup();
 				controller.error(error);
 			}
 		},
@@ -702,7 +844,7 @@ function responseWithCleanup(
 			try {
 				await reader.cancel(reason);
 			} finally {
-				runCleanup();
+				await runCleanup();
 			}
 		},
 	});
@@ -775,7 +917,7 @@ function assertStreamPayloadWithinLimit(
 function toSseResponse(
 	operation: OperationDefinition,
 	result: AsyncIterable<ProviderStreamEvent>,
-	cleanup: () => void,
+	cleanup: RequestCleanup,
 	requestId?: string,
 ): Response {
 	const encoder = new TextEncoder();
@@ -783,24 +925,24 @@ function toSseResponse(
 	const transport = getSseTransport(operation);
 	let done = false;
 	let cleaned = false;
-	const runCleanup = () => {
+	const runCleanup = async () => {
 		if (cleaned) return;
 		cleaned = true;
-		cleanup();
+		await cleanup();
 	};
 	const body = new ReadableStream<Uint8Array>({
 		async pull(controller) {
 			try {
 				if (done) {
 					controller.close();
-					runCleanup();
+					await runCleanup();
 					return;
 				}
 				const next = await iterator.next();
 				if (next.done) {
 					done = true;
 					controller.close();
-					runCleanup();
+					await runCleanup();
 					return;
 				}
 				const validated = await validateSseEvent(operation, next.value);
@@ -826,14 +968,14 @@ function toSseResponse(
 				);
 				controller.close();
 				done = true;
-				runCleanup();
+				await runCleanup();
 			}
 		},
 		async cancel(reason) {
 			try {
 				await iterator.return?.(reason);
 			} finally {
-				runCleanup();
+				await runCleanup();
 			}
 		},
 	});
@@ -881,7 +1023,7 @@ function enforceStreamChunkLimit(
 function toStreamingResponse(
 	operation: OperationDefinition,
 	result: unknown,
-	cleanup: () => void,
+	cleanup: RequestCleanup,
 	requestId?: string,
 ): Response {
 	const transport = operation.transport?.kind ?? "json";
@@ -889,7 +1031,7 @@ function toStreamingResponse(
 		transport === "sse" &&
 		(result instanceof Response || result instanceof ReadableStream)
 	) {
-		cleanup();
+		void cleanup();
 		throw new ProviderError(
 			"SSE operations must return an AsyncIterable of typed stream.event(...) values.",
 			{
@@ -946,7 +1088,7 @@ function toStreamingResponse(
 	if (transport === "sse" && isAsyncIterable<ProviderStreamEvent>(result)) {
 		return toSseResponse(operation, result, cleanup, requestId);
 	}
-	cleanup();
+	void cleanup();
 	throw new ProviderError(
 		`Streaming operation returned unsupported result for transport "${transport}"`,
 		{
@@ -988,11 +1130,84 @@ function toAuthFlowResponse(
 	};
 }
 
+function authFlowLocaleFromHeaders(
+	headers?: Record<string, string>,
+): ProviderLocale {
+	const header = Object.entries(headers ?? {}).find(
+		([key]) => key.toLowerCase() === "accept-language",
+	)?.[1];
+	for (const token of (header ?? "").split(",")) {
+		const language = token.trim().split(";")[0]?.split("-")[0]?.toLowerCase();
+		if (isAuthFlowLocale(language)) {
+			return language;
+		}
+	}
+	return "en";
+}
+
+function isAuthFlowLocale(value: string | undefined): value is ProviderLocale {
+	return value === "en" || value === "ko" || value === "ja";
+}
+
+function isAuthTurn(value: unknown): value is AuthTurn {
+	return (
+		!!value && typeof value === "object" && "kind" in value && "turnId" in value
+	);
+}
+
+function loadAuthFlowLocaleCatalogs(
+	provider: ProviderDefinition,
+): ProviderLocaleCatalogMap | undefined {
+	for (const providerDir of [
+		process.cwd(),
+		join(process.cwd(), "providers", provider.id),
+		join(process.cwd(), "providers-staging", provider.id),
+	]) {
+		if (!existsSync(join(providerDir, "locales", "en.json"))) continue;
+		try {
+			return loadProviderLocaleCatalogs({
+				providerDir,
+				locales: AUTH_FLOW_LOCALES,
+			});
+		} catch {
+			return undefined;
+		}
+	}
+	return undefined;
+}
+
+function materializeAuthFlowTurn(
+	provider: ProviderDefinition,
+	request: AuthFlowRequest,
+	turn: AuthTurn,
+): AuthTurn {
+	const catalogs = loadAuthFlowLocaleCatalogs(provider);
+	if (!catalogs) return turn;
+	return localizeAuthTurn(turn, {
+		catalogs,
+		locale: authFlowLocaleFromHeaders(request.headers),
+	});
+}
+
+function withAuthRequestHeaders(
+	request: AuthFlowRequest,
+	headers: Headers,
+): AuthFlowRequest {
+	return {
+		...request,
+		headers: {
+			...(request.headers ?? {}),
+			...Object.fromEntries(headers.entries()),
+		},
+	};
+}
+
 async function handleOperation(
 	provider: ProviderDefinition,
 	request: OperationRequest,
 	operationId: string,
 	options: ProviderServerOptions = {},
+	state: ProviderRuntimeState = createUnsupportedProviderRuntimeState(),
 	proxyTelemetry?: ProxyTelemetryCollector,
 ): Promise<Response | OperationResponse> {
 	const ctx = createProviderContext(
@@ -1000,16 +1215,40 @@ async function handleOperation(
 		request,
 		operationId,
 		options,
+		state,
 		proxyTelemetry,
 	);
 	const operation = provider.operations[operationId];
 	const streaming =
 		operation?.transport?.kind && operation.transport.kind !== "json";
 	let cleanupCalled = false;
-	const cleanup = () => {
+	const cleanup = async () => {
 		if (cleanupCalled) return;
 		cleanupCalled = true;
-		ctx.stealth.close?.();
+		try {
+			ctx.stealth.close?.();
+		} catch (error) {
+			logProviderCleanupError(
+				options.logger,
+				provider,
+				operationId,
+				request.requestId,
+				"stealth",
+				error,
+			);
+		}
+		try {
+			await ctx.browser.close?.();
+		} catch (error) {
+			logProviderCleanupError(
+				options.logger,
+				provider,
+				operationId,
+				request.requestId,
+				"browser",
+				error,
+			);
+		}
 	};
 	try {
 		const result = await executeOperation(
@@ -1023,10 +1262,10 @@ async function handleOperation(
 		}
 		return toJsonSuccessResponse(result, ctx);
 	} catch (error) {
-		cleanup();
+		await cleanup();
 		throw error;
 	} finally {
-		if (!streaming) cleanup();
+		if (!streaming) await cleanup();
 	}
 }
 
@@ -1045,7 +1284,7 @@ function responseWithProviderTelemetry(
 	});
 }
 
-type AuthRoute = "start" | "continue" | "poll" | "abort";
+type AuthRoute = "start" | "continue" | "poll" | "abort" | "refresh";
 
 async function handleAuthFlow(
 	provider: ProviderDefinition,
@@ -1075,11 +1314,28 @@ async function handleAuthFlow(
 						? flow.poll
 							? await flow.poll(context)
 							: null
-						: flow.abort
-							? await flow.abort(context)
-							: null;
+						: route === "abort"
+							? flow.abort
+								? await flow.abort(context)
+								: null
+							: flow.refresh
+								? await flow.refresh(context, request.input ?? {})
+								: null;
+
+		if (route === "refresh" && !flow.refresh) {
+			throw new AuthError("Provider auth flow does not support refresh.", {
+				code: "refresh_not_supported",
+			});
+		}
 
-		return toAuthFlowResponse(result, getPatch());
+		const materializedResult =
+			result &&
+			!(result instanceof Response) &&
+			!(result instanceof ReadableStream) &&
+			isAuthTurn(result)
+				? materializeAuthFlowTurn(provider, request, result)
+				: result;
+		return toAuthFlowResponse(materializedResult, getPatch());
 	} finally {
 		context.stealth.close?.();
 	}
@@ -1091,6 +1347,12 @@ export function createServerApp(
 ): Hono {
 	const app = new Hono();
 	const logger = options.logger ?? defaultProviderServerLogger;
+	const state =
+		options.state ??
+		createProviderRuntimeStateFromEnv({
+			providerId: provider.id,
+			allowMemoryFallback: options.allowMemoryStateFallback === true,
+		});
 
 	app.notFound((c) =>
 		c.json(
@@ -1130,6 +1392,7 @@ export function createServerApp(
 				body,
 				operation,
 				options,
+				state,
 				proxyTelemetry,
 			);
 			if (response instanceof Response) {
@@ -1183,7 +1446,10 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = AuthFlowRequestSchema.parse(rawBody);
+			const body = withAuthRequestHeaders(
+				AuthFlowRequestSchema.parse(rawBody),
+				c.req.raw.headers,
+			);
 			const response = await handleAuthFlow(provider, body, "start", options);
 			logProviderSuccess(
 				logger,
@@ -1220,7 +1486,10 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = AuthFlowRequestSchema.parse(rawBody);
+			const body = withAuthRequestHeaders(
+				AuthFlowRequestSchema.parse(rawBody),
+				c.req.raw.headers,
+			);
 			const response = await handleAuthFlow(
 				provider,
 				body,
@@ -1262,7 +1531,10 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = AuthFlowRequestSchema.parse(rawBody);
+			const body = withAuthRequestHeaders(
+				AuthFlowRequestSchema.parse(rawBody),
+				c.req.raw.headers,
+			);
 			const response = await handleAuthFlow(provider, body, "poll", options);
 			logProviderSuccess(
 				logger,
@@ -1291,6 +1563,46 @@ export function createServerApp(
 		}
 	});
 
+	app.post("/auth/refresh", async (c) => {
+		let rawBody: unknown;
+		const requestCost = startRequestCost();
+		try {
+			rawBody = await c.req.raw
+				.clone()
+				.json()
+				.catch(() => undefined);
+			const body = withAuthRequestHeaders(
+				AuthFlowRequestSchema.parse(rawBody),
+				c.req.raw.headers,
+			);
+			const response = await handleAuthFlow(provider, body, "refresh", options);
+			logProviderSuccess(
+				logger,
+				provider,
+				"auth",
+				"refresh",
+				body.requestId,
+				response instanceof Response ? response.status : 200,
+				finishRequestCost(requestCost),
+			);
+			return response instanceof Response ? response : c.json(response);
+		} catch (error) {
+			const status = toStatusCode(error);
+			const requestId = extractRequestId(rawBody);
+			logProviderError(
+				logger,
+				provider,
+				"auth",
+				"refresh",
+				requestId,
+				error,
+				status,
+				finishRequestCost(requestCost),
+			);
+			return c.json(toErrorResponse(error, requestId), status);
+		}
+	});
+
 	app.post("/auth/disconnect", async (c) => {
 		let rawBody: unknown;
 		const requestCost = startRequestCost();
@@ -1299,7 +1611,10 @@ export function createServerApp(
 				.clone()
 				.json()
 				.catch(() => undefined);
-			const body = AuthFlowRequestSchema.parse(rawBody);
+			const body = withAuthRequestHeaders(
+				AuthFlowRequestSchema.parse(rawBody),
+				c.req.raw.headers,
+			);
 			const response = await handleAuthFlow(provider, body, "abort", options);
 			logProviderSuccess(
 				logger,