@apifuse/connector-sdk 2.0.0-beta.1

package/src/serve.ts

@@ -0,0 +1,665 @@
+import { Hono } from "hono";
+import { type ZodType, z } from "zod";
+
+import { ConnectorError } from "./errors";
+import type {
+	ConnectRequest,
+	ConnectResponse,
+	ContainerErrorResponse,
+	DisconnectRequest,
+	DisconnectResponse,
+	ExecuteRequest,
+	ExecuteResponse,
+	HealthResponse,
+	RefreshRequest,
+	RefreshResponse,
+	ResumeRequest,
+	ResumeResponse,
+	SchemaResponse,
+} from "./protocol";
+import { createBrowserClient } from "./runtime/browser";
+import { executeOperation } from "./runtime/executor";
+import { createHttpClient } from "./runtime/http";
+import { createStateContext } from "./runtime/state";
+import { createTlsClient } from "./runtime/tls";
+import { createTraceContext, type TraceContext } from "./runtime/trace";
+import type {
+	AuthContext,
+	BrowserClient,
+	ConnectorContext,
+	ConnectorDefinition,
+	SessionStore,
+	TlsClient,
+} from "./types";
+
+const AUTH_SESSION_KEY = "__auth__";
+const DEFAULT_PORT = 3900;
+
+type ErrorStatusCode = 400 | 404 | 500;
+
+type SessionPatch = Record<string, string | null>;
+
+type PendingAuthState = {
+	credentials: Record<string, string>;
+	resolvedFields: Record<string, string>;
+	requestedField: string;
+};
+
+class PendingFieldError extends Error {
+	constructor(readonly field: string) {
+		super(`Pending auth field: ${field}`);
+		this.name = "PendingFieldError";
+	}
+}
+
+function createSessionOverlay(snapshot: Record<string, string> = {}): {
+	store: SessionStore;
+	getPatch: () => SessionPatch;
+} {
+	const data = new Map<string, string>(Object.entries(snapshot));
+	const patch: SessionPatch = {};
+
+	return {
+		store: {
+			async get(key: string): Promise<string | null> {
+				return data.get(key) ?? null;
+			},
+			async set(key: string, value: string): Promise<void> {
+				data.set(key, value);
+				patch[key] = value;
+			},
+			async delete(key: string): Promise<void> {
+				data.delete(key);
+				patch[key] = null;
+			},
+		},
+		getPatch: () => ({ ...patch }),
+	};
+}
+
+function createBrowserStub(): BrowserClient {
+	return {
+		engine: "playwright-stealth",
+		async newPage() {
+			throw new ConnectorError("Browser runtime is not available", {
+				code: "BROWSER_RUNTIME_UNSUPPORTED",
+			});
+		},
+	};
+}
+
+async function closeBrowserRuntime(browser: BrowserClient): Promise<void> {
+	if (!Reflect.has(browser as object, "close")) {
+		return;
+	}
+
+	await (browser as BrowserClient & { close(): Promise<void> }).close();
+}
+
+function createTlsStub(): TlsClient {
+	return {
+		async fetch() {
+			throw new ConnectorError("TLS runtime is not available", {
+				code: "TLS_RUNTIME_UNSUPPORTED",
+			});
+		},
+		createSession() {
+			throw new ConnectorError("TLS runtime is not available", {
+				code: "TLS_RUNTIME_UNSUPPORTED",
+			});
+		},
+	};
+}
+
+function createAuthSessionMarker(
+	marker: Record<string, boolean | number>,
+): string {
+	return JSON.stringify(marker);
+}
+
+function toSessionSnapshot(
+	snapshot: Record<string, string> | undefined,
+): Record<string, string> {
+	return snapshot ?? {};
+}
+
+function toStringRecord(value: unknown): Record<string, string> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		return {};
+	}
+
+	return Object.fromEntries(
+		Object.entries(value).map(([key, entryValue]) => [key, String(entryValue)]),
+	);
+}
+
+function toErrorEnvelope(
+	error: unknown,
+	overrides?: Partial<ContainerErrorResponse["error"]>,
+): ContainerErrorResponse {
+	const connectorError = error instanceof ConnectorError ? error : null;
+	const fallbackMessage =
+		error instanceof Error ? error.message : "Unknown error";
+
+	return {
+		error: {
+			code: overrides?.code ?? connectorError?.code ?? "INTERNAL_ERROR",
+			message: overrides?.message ?? fallbackMessage,
+			...(overrides?.details !== undefined
+				? { details: overrides.details }
+				: connectorError?.options?.fix
+					? { details: { fix: connectorError.options.fix } }
+					: {}),
+		},
+	};
+}
+
+function getStatusCode(error: unknown): ErrorStatusCode {
+	if (error instanceof ConnectorError && error.code === "NOT_FOUND") {
+		return 404;
+	}
+
+	if (error instanceof z.ZodError) {
+		return 400;
+	}
+
+	return 500;
+}
+
+function getFieldLabel(
+	connector: ConnectorDefinition,
+	fieldName: string,
+): string | undefined {
+	return connector.auth?.fields?.find((field) => field.name === fieldName)
+		?.label;
+}
+
+function toConnectFailedResponse(error: unknown): ConnectResponse {
+	return {
+		status: "failed",
+		error:
+			error instanceof ConnectorError
+				? (error.code ?? "AUTH_FAILED")
+				: "AUTH_FAILED",
+		message: error instanceof Error ? error.message : "Authentication failed",
+	};
+}
+
+function toRefreshFailedResponse(error: unknown): RefreshResponse {
+	return {
+		status: "failed",
+		error:
+			error instanceof ConnectorError
+				? (error.code ?? "REFRESH_FAILED")
+				: "REFRESH_FAILED",
+		message: error instanceof Error ? error.message : "Refresh failed",
+	};
+}
+
+function toDisconnectFailedResponse(error: unknown): DisconnectResponse {
+	return {
+		status: "failed",
+		error:
+			error instanceof ConnectorError
+				? (error.code ?? "DISCONNECT_FAILED")
+				: error instanceof Error
+					? error.message
+					: "DISCONNECT_FAILED",
+	};
+}
+
+function toSchema(schema: ZodType): Record<string, unknown> {
+	const zodModule = z as typeof z & {
+		toJSONSchema?: (schema: ZodType) => Record<string, unknown>;
+	};
+	const schemaWithMethod = schema as ZodType & {
+		toJSONSchema?: () => Record<string, unknown>;
+	};
+
+	if (typeof zodModule.toJSONSchema === "function") {
+		return zodModule.toJSONSchema(schema);
+	}
+
+	if (typeof schemaWithMethod.toJSONSchema === "function") {
+		return schemaWithMethod.toJSONSchema();
+	}
+
+	throw new ConnectorError("Zod JSON Schema conversion is unavailable", {
+		code: "SCHEMA_CONVERSION_UNAVAILABLE",
+	});
+}
+
+function getTracePayload(
+	trace: TraceContext,
+): ExecuteResponse["trace"] | undefined {
+	const spans = trace.getSpans();
+	return spans.length > 0 ? { spans } : undefined;
+}
+
+function toStringSessionPatch(
+	sessionPatch: SessionPatch,
+): Record<string, string> {
+	return Object.fromEntries(
+		Object.entries(sessionPatch).filter(
+			(entry): entry is [string, string] => entry[1] !== null,
+		),
+	);
+}
+
+function assertAuthConfigured(
+	connector: ConnectorDefinition,
+): asserts connector is ConnectorDefinition & {
+	auth: NonNullable<ConnectorDefinition["auth"]>;
+} {
+	if (!connector.auth || connector.auth.mode === "none") {
+		throw new ConnectorError("Auth is not configured", {
+			code: "AUTH_NOT_CONFIGURED",
+		});
+	}
+
+	if (!connector.auth.exchange) {
+		throw new ConnectorError("Auth exchange is not configured", {
+			code: "AUTH_EXCHANGE_NOT_CONFIGURED",
+		});
+	}
+}
+
+function createContainerContext(
+	connector: ConnectorDefinition,
+	sessionSnapshot: Record<string, string> = {},
+	options: {
+		auth?: AuthContext;
+		baseUrl?: string;
+		stateSecret?: string;
+	} = {},
+): {
+	ctx: ConnectorContext;
+	getSessionPatch: () => SessionPatch;
+	close: () => Promise<void>;
+	trace: TraceContext;
+} {
+	const overlay = createSessionOverlay(sessionSnapshot);
+	const trace = createTraceContext({ onSpan: () => {} });
+	const browser =
+		connector.runtime === "browser"
+			? createBrowserClient({
+					cdpUrl: process.env.CDP_POOL_URL ?? process.env.APIFUSE_CDP_POOL_URL,
+					headless: true,
+					stealth: true,
+					engine: connector.browser?.engine,
+				})
+			: createBrowserStub();
+	const tls = options.baseUrl
+		? createTlsClient(options.baseUrl)
+		: createTlsStub();
+
+	const ctx: ConnectorContext = {
+		http: createHttpClient(options.baseUrl),
+		tls,
+		browser,
+		session: overlay.store,
+		state: createStateContext(options.stateSecret),
+		trace,
+		auth:
+			options.auth ??
+			({
+				async requestField(name: string): Promise<string> {
+					throw new ConnectorError(`Deferred auth field requested: ${name}`, {
+						code: "AUTH_FIELD_REQUESTED",
+					});
+				},
+			} satisfies AuthContext),
+	};
+
+	return {
+		ctx,
+		getSessionPatch: overlay.getPatch,
+		close: async () => await closeBrowserRuntime(browser),
+		trace,
+	};
+}
+
+async function runAuthExchange(
+	connector: ConnectorDefinition,
+	credentials: Record<string, string>,
+	sessionSnapshot: Record<string, string>,
+	resolvedFields: Record<string, string>,
+	options: {
+		baseUrl?: string;
+		stateSecret?: string;
+	},
+): Promise<
+	| { type: "success"; sessionPatch: Record<string, string> }
+	| {
+			type: "pending_field";
+			field: string;
+			fieldLabel?: string;
+			resumeToken: string;
+			sessionPatch?: Record<string, string>;
+	  }
+> {
+	assertAuthConfigured(connector);
+	const auth = connector.auth as NonNullable<ConnectorDefinition["auth"]> & {
+		exchange: NonNullable<NonNullable<ConnectorDefinition["auth"]>["exchange"]>;
+	};
+
+	let requestedField: string | null = null;
+	const { ctx, getSessionPatch, close } = createContainerContext(
+		connector,
+		sessionSnapshot,
+		{
+			baseUrl: options.baseUrl,
+			stateSecret: options.stateSecret,
+			auth: {
+				async requestField(name: string): Promise<string> {
+					const resolvedValue = resolvedFields[name];
+					if (resolvedValue !== undefined) {
+						return resolvedValue;
+					}
+
+					requestedField = name;
+					throw new PendingFieldError(name);
+				},
+			},
+		},
+	);
+
+	try {
+		await auth.exchange(ctx, credentials);
+		await ctx.session.set(
+			AUTH_SESSION_KEY,
+			createAuthSessionMarker({ authenticated: true, timestamp: Date.now() }),
+		);
+		return {
+			type: "success",
+			sessionPatch: toStringSessionPatch(getSessionPatch()),
+		};
+	} catch (error) {
+		if (error instanceof PendingFieldError && requestedField) {
+			const resumeToken = await ctx.state.seal(
+				{
+					credentials,
+					resolvedFields,
+					requestedField,
+				} satisfies PendingAuthState,
+				{ ttl: "15m" },
+			);
+
+			const sessionPatch = toStringSessionPatch(getSessionPatch());
+			return {
+				type: "pending_field",
+				field: requestedField,
+				fieldLabel: getFieldLabel(connector, requestedField),
+				resumeToken,
+				...(Object.keys(sessionPatch).length > 0 ? { sessionPatch } : {}),
+			};
+		}
+
+		throw error;
+	} finally {
+		await close();
+	}
+}
+
+async function parseJsonBody<T>(request: Request): Promise<T> {
+	try {
+		return (await request.json()) as T;
+	} catch (error) {
+		throw new ConnectorError("Invalid JSON body", {
+			code: "INVALID_JSON",
+			cause: error instanceof Error ? error : undefined,
+		});
+	}
+}
+
+export function createConnectorServer(
+	connector: ConnectorDefinition,
+	options: {
+		port?: number;
+		baseUrl?: string;
+		stateSecret?: string;
+		sessionDbPath?: string;
+	} = {},
+): { app: Hono; start: () => void } {
+	const startedAt = Date.now();
+	const app = new Hono();
+
+	app.post("/execute/:operationId", async (c) => {
+		try {
+			const operationId = c.req.param("operationId");
+			const body = await parseJsonBody<ExecuteRequest>(c.req.raw);
+			const { ctx, getSessionPatch, trace, close } = createContainerContext(
+				connector,
+				toSessionSnapshot(body.session),
+				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
+			);
+
+			try {
+				const data = await executeOperation(
+					connector,
+					operationId,
+					ctx,
+					body.input,
+				);
+				const response: ExecuteResponse = {
+					data,
+					sessionPatch: getSessionPatch(),
+					...(getTracePayload(trace) ? { trace: getTracePayload(trace) } : {}),
+				};
+
+				return c.json(response);
+			} finally {
+				await close();
+			}
+		} catch (error) {
+			return c.json(toErrorEnvelope(error), getStatusCode(error));
+		}
+	});
+
+	app.post("/connect", async (c) => {
+		try {
+			const body = await parseJsonBody<ConnectRequest>(c.req.raw);
+			const result = await runAuthExchange(
+				connector,
+				toStringRecord(body.credentials),
+				toSessionSnapshot(body.session),
+				{},
+				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
+			);
+
+			const response: ConnectResponse =
+				result.type === "success"
+					? {
+							status: "success",
+							sessionPatch: result.sessionPatch,
+						}
+					: {
+							status: "pending_field",
+							field: result.field,
+							resumeToken: result.resumeToken,
+							...(result.fieldLabel ? { fieldLabel: result.fieldLabel } : {}),
+							...(result.sessionPatch
+								? { sessionPatch: result.sessionPatch }
+								: {}),
+						};
+
+			return c.json(response);
+		} catch (error) {
+			return c.json(toConnectFailedResponse(error));
+		}
+	});
+
+	app.post("/connect/resume", async (c) => {
+		try {
+			const body = await parseJsonBody<ResumeRequest>(c.req.raw);
+			const state = createStateContext(options.stateSecret);
+			const pendingState = await state.unseal<PendingAuthState>(
+				body.resumeToken,
+			);
+
+			if (!pendingState) {
+				const response: ResumeResponse = {
+					status: "failed",
+					error: "INVALID_RESUME_TOKEN",
+					message: "Resume token is invalid or expired",
+				};
+				return c.json(response);
+			}
+
+			const result = await runAuthExchange(
+				connector,
+				pendingState.credentials,
+				toSessionSnapshot(body.session),
+				{
+					...pendingState.resolvedFields,
+					[pendingState.requestedField]: body.fieldValue,
+				},
+				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
+			);
+
+			const response: ResumeResponse =
+				result.type === "success"
+					? {
+							status: "success",
+							sessionPatch: result.sessionPatch,
+						}
+					: {
+							status: "pending_field",
+							field: result.field,
+							resumeToken: result.resumeToken,
+							...(result.fieldLabel ? { fieldLabel: result.fieldLabel } : {}),
+							...(result.sessionPatch
+								? { sessionPatch: result.sessionPatch }
+								: {}),
+						};
+
+			return c.json(response);
+		} catch (error) {
+			return c.json(toConnectFailedResponse(error));
+		}
+	});
+
+	app.post("/refresh", async (c) => {
+		try {
+			if (!connector.auth?.refresh) {
+				throw new ConnectorError("Auth refresh is not configured", {
+					code: "AUTH_REFRESH_NOT_CONFIGURED",
+				});
+			}
+
+			const body = await parseJsonBody<RefreshRequest>(c.req.raw);
+			const { ctx, getSessionPatch, close } = createContainerContext(
+				connector,
+				body.session,
+				{ baseUrl: options.baseUrl, stateSecret: options.stateSecret },
+			);
+
+			try {
+				await connector.auth.refresh(ctx);
+				await ctx.session.set(
+					AUTH_SESSION_KEY,
+					createAuthSessionMarker({
+						authenticated: true,
+						refreshed: true,
+						timestamp: Date.now(),
+					}),
+				);
+				const response: RefreshResponse = {
+					status: "success",
+					sessionPatch: toStringSessionPatch(getSessionPatch()),
+				};
+
+				return c.json(response);
+			} finally {
+				await close();
+			}
+		} catch (error) {
+			return c.json(toRefreshFailedResponse(error));
+		}
+	});
+
+	app.post("/disconnect", async (c) => {
+		try {
+			const body = await parseJsonBody<DisconnectRequest>(c.req.raw);
+			const { ctx, close } = createContainerContext(connector, body.session, {
+				baseUrl: options.baseUrl,
+				stateSecret: options.stateSecret,
+			});
+
+			try {
+				if (connector.auth?.disconnect) {
+					await connector.auth.disconnect(ctx);
+				}
+
+				await ctx.session.delete(AUTH_SESSION_KEY);
+				const response: DisconnectResponse = { status: "success" };
+				return c.json(response);
+			} finally {
+				await close();
+			}
+		} catch (error) {
+			return c.json(toDisconnectFailedResponse(error));
+		}
+	});
+
+	app.get("/health", (c) => {
+		const response: HealthResponse = {
+			status: "ok",
+			connector: connector.id,
+			version: connector.version,
+			uptime: Date.now() - startedAt,
+		};
+
+		return c.json(response);
+	});
+
+	app.get("/schema/:operationId", (c) => {
+		try {
+			const operationId = c.req.param("operationId");
+			const operation = connector.operations[operationId];
+
+			if (!operation) {
+				throw new ConnectorError(
+					`Unknown operation: ${connector.id}/${operationId}`,
+					{
+						code: "NOT_FOUND",
+						fix: `Valid operations: ${Object.keys(connector.operations).join(", ")}`,
+					},
+				);
+			}
+
+			const response: SchemaResponse = {
+				operationId,
+				...(operation.description
+					? { description: operation.description }
+					: {}),
+				input: toSchema(operation.input),
+				output: toSchema(operation.output),
+				...(operation.hints ? { hints: operation.hints } : {}),
+			};
+
+			return c.json(response);
+		} catch (error) {
+			return c.json(toErrorEnvelope(error), getStatusCode(error));
+		}
+	});
+
+	return {
+		app,
+		start() {
+			if (typeof Bun === "undefined") {
+				throw new ConnectorError(
+					"Bun runtime is required to start the server",
+					{
+						code: "RUNTIME_UNSUPPORTED",
+					},
+				);
+			}
+
+			Bun.serve({
+				port: options.port ?? DEFAULT_PORT,
+				fetch: app.fetch,
+			});
+		},
+	};
+}