rivetkit 2.0.2 → 2.0.3

package/src/inline-client-driver/mod.ts

@@ -0,0 +1,385 @@
+import * as cbor from "cbor-x";
+import type { Context as HonoContext } from "hono";
+import invariant from "invariant";
+import onChange from "on-change";
+import type { WebSocket } from "ws";
+import * as errors from "@/actor/errors";
+import type { Encoding } from "@/actor/protocol/serde";
+import {
+	PATH_CONNECT_WEBSOCKET,
+	PATH_RAW_WEBSOCKET_PREFIX,
+} from "@/actor/router";
+import {
+	HEADER_CONN_ID,
+	HEADER_CONN_PARAMS,
+	HEADER_CONN_TOKEN,
+	HEADER_ENCODING,
+	HEADER_EXPOSE_INTERNAL_ERROR,
+} from "@/actor/router-endpoints";
+import { assertUnreachable } from "@/actor/utils";
+import type { ClientDriver } from "@/client/client";
+import { ActorError as ClientActorError } from "@/client/errors";
+import { sendHttpRequest } from "@/client/utils";
+import { importEventSource } from "@/common/eventsource";
+import type { UniversalEventSource } from "@/common/eventsource-interface";
+import { deconstructError } from "@/common/utils";
+import type { ManagerDriver } from "@/manager/driver";
+import type { ActorQuery } from "@/manager/protocol/query";
+import type { RunConfig } from "@/mod";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	HTTP_ACTION_REQUEST_VERSIONED,
+	HTTP_ACTION_RESPONSE_VERSIONED,
+	TO_CLIENT_VERSIONED,
+	TO_SERVER_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import { bufferToArrayBuffer, httpUserAgent } from "@/utils";
+import { logger } from "./log";
+
+/**
+ * Client driver that calls the manager driver inline.
+ *
+ * This is only applicable to standalone & coordinated topologies.
+ *
+ * This driver can access private resources.
+ *
+ * This driver serves a double purpose as:
+ * - Providing the client for the internal requests
+ * - Provide the driver for the manager HTTP router (see manager/router.ts)
+ */
+export function createInlineClientDriver(
+	managerDriver: ManagerDriver,
+): ClientDriver {
+	const driver: ClientDriver = {
+		action: async <Args extends Array<unknown> = unknown[], Response = unknown>(
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			actionName: string,
+			args: Args,
+			opts: { signal?: AbortSignal },
+		): Promise<Response> => {
+			try {
+				// Get the actor ID
+				const { actorId } = await queryActor(c, actorQuery, managerDriver);
+				logger().debug("found actor for action", { actorId });
+				invariant(actorId, "Missing actor ID");
+
+				// Invoke the action
+				logger().debug("handling action", { actionName, encoding });
+				const responseData = await sendHttpRequest<
+					protocol.HttpActionRequest,
+					protocol.HttpActionResponse
+				>({
+					url: `http://actor/action/${encodeURIComponent(actionName)}`,
+					method: "POST",
+					headers: {
+						[HEADER_ENCODING]: encoding,
+						...(params !== undefined
+							? { [HEADER_CONN_PARAMS]: JSON.stringify(params) }
+							: {}),
+						[HEADER_EXPOSE_INTERNAL_ERROR]: "true",
+					},
+					body: {
+						args: bufferToArrayBuffer(cbor.encode(args)),
+					} satisfies protocol.HttpActionRequest,
+					encoding: encoding,
+					customFetch: managerDriver.sendRequest.bind(managerDriver, actorId),
+					signal: opts?.signal,
+					requestVersionedDataHandler: HTTP_ACTION_REQUEST_VERSIONED,
+					responseVersionedDataHandler: HTTP_ACTION_RESPONSE_VERSIONED,
+				});
+
+				return cbor.decode(new Uint8Array(responseData.output));
+			} catch (err) {
+				// Standardize to ClientActorError instead of the native backend error
+				const { code, message, metadata } = deconstructError(
+					err,
+					logger(),
+					{},
+					true,
+				);
+				const x = new ClientActorError(code, message, metadata);
+				throw new ClientActorError(code, message, metadata);
+			}
+		},
+
+		resolveActorId: async (
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			_encodingKind: Encoding,
+		): Promise<string> => {
+			// Get the actor ID
+			const { actorId } = await queryActor(c, actorQuery, managerDriver);
+			logger().debug("resolved actor", { actorId });
+			invariant(actorId, "missing actor ID");
+
+			return actorId;
+		},
+
+		connectWebSocket: async (
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encodingKind: Encoding,
+			params?: unknown,
+		): Promise<WebSocket> => {
+			// Get the actor ID
+			const { actorId } = await queryActor(c, actorQuery, managerDriver);
+			logger().debug("found actor for action", { actorId });
+			invariant(actorId, "Missing actor ID");
+
+			// Invoke the action
+			logger().debug("opening websocket", { actorId, encoding: encodingKind });
+
+			// Open WebSocket
+			const ws = await managerDriver.openWebSocket(
+				PATH_CONNECT_WEBSOCKET,
+				actorId,
+				encodingKind,
+				params,
+			);
+
+			// Node & browser WebSocket types are incompatible
+			return ws as any;
+		},
+
+		connectSse: async (
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encodingKind: Encoding,
+			params: unknown,
+		): Promise<UniversalEventSource> => {
+			// Get the actor ID
+			const { actorId } = await queryActor(c, actorQuery, managerDriver);
+			logger().debug("found actor for sse connection", { actorId });
+			invariant(actorId, "Missing actor ID");
+
+			logger().debug("opening sse connection", {
+				actorId,
+				encoding: encodingKind,
+			});
+
+			const EventSourceClass = await importEventSource();
+
+			const eventSource = new EventSourceClass("http://actor/connect/sse", {
+				fetch: (input, init) => {
+					return fetch(input, {
+						...init,
+						headers: {
+							...init?.headers,
+							"User-Agent": httpUserAgent(),
+							[HEADER_ENCODING]: encodingKind,
+							...(params !== undefined
+								? { [HEADER_CONN_PARAMS]: JSON.stringify(params) }
+								: {}),
+							[HEADER_EXPOSE_INTERNAL_ERROR]: "true",
+						},
+					});
+				},
+			}) as UniversalEventSource;
+
+			return eventSource;
+		},
+
+		sendHttpMessage: async (
+			c: HonoContext | undefined,
+			actorId: string,
+			encoding: Encoding,
+			connectionId: string,
+			connectionToken: string,
+			message: protocol.ToServer,
+		): Promise<void> => {
+			logger().debug("sending http message", { actorId, connectionId });
+
+			// Send an HTTP request to the connections endpoint
+			await sendHttpRequest({
+				url: "http://actor/connections/message",
+				method: "POST",
+				headers: {
+					[HEADER_ENCODING]: encoding,
+					[HEADER_CONN_ID]: connectionId,
+					[HEADER_CONN_TOKEN]: connectionToken,
+					[HEADER_EXPOSE_INTERNAL_ERROR]: "true",
+				},
+				body: message,
+				encoding,
+				skipParseResponse: true,
+				customFetch: managerDriver.sendRequest.bind(managerDriver, actorId),
+				requestVersionedDataHandler: TO_SERVER_VERSIONED,
+				responseVersionedDataHandler: TO_CLIENT_VERSIONED,
+			});
+		},
+
+		rawHttpRequest: async (
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			path: string,
+			init: RequestInit,
+		): Promise<Response> => {
+			try {
+				// Get the actor ID
+				const { actorId } = await queryActor(c, actorQuery, managerDriver);
+				logger().debug("found actor for raw http", { actorId });
+				invariant(actorId, "Missing actor ID");
+
+				// Build the URL with normalized path
+				const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+				const url = new URL(`http://actor/raw/http/${normalizedPath}`);
+
+				// Forward conn params if provided
+				const proxyRequestHeaders = new Headers(init.headers);
+				if (params) {
+					proxyRequestHeaders.set(HEADER_CONN_PARAMS, JSON.stringify(params));
+				}
+
+				// Forward the request to the actor
+				const proxyRequest = new Request(url, {
+					...init,
+					headers: proxyRequestHeaders,
+				});
+
+				return await managerDriver.sendRequest(actorId, proxyRequest);
+			} catch (err) {
+				// Standardize to ClientActorError instead of the native backend error
+				const { code, message, metadata } = deconstructError(
+					err,
+					logger(),
+					{},
+					true,
+				);
+				throw new ClientActorError(code, message, metadata);
+			}
+		},
+
+		rawWebSocket: async (
+			c: HonoContext | undefined,
+			actorQuery: ActorQuery,
+			encoding: Encoding,
+			params: unknown,
+			path: string,
+			protocols: string | string[] | undefined,
+		): Promise<WebSocket> => {
+			// Get the actor ID
+			const { actorId } = await queryActor(c, actorQuery, managerDriver);
+			logger().debug("found actor for action", { actorId });
+			invariant(actorId, "Missing actor ID");
+
+			// Normalize path to match raw HTTP behavior
+			const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
+			logger().debug("opening websocket", {
+				actorId,
+				encoding,
+				path: normalizedPath,
+			});
+
+			// Open WebSocket
+			const ws = await managerDriver.openWebSocket(
+				`${PATH_RAW_WEBSOCKET_PREFIX}${normalizedPath}`,
+				actorId,
+				encoding,
+				params,
+			);
+
+			// Node & browser WebSocket types are incompatible
+			return ws as any;
+		},
+	};
+
+	return driver;
+}
+
+/**
+ * Query the manager driver to get or create a actor based on the provided query
+ */
+export async function queryActor(
+	c: HonoContext | undefined,
+	query: ActorQuery,
+	driver: ManagerDriver,
+): Promise<{ actorId: string }> {
+	logger().debug("querying actor", { query });
+	let actorOutput: { actorId: string };
+	if ("getForId" in query) {
+		const output = await driver.getForId({
+			c,
+			name: query.getForId.name,
+			actorId: query.getForId.actorId,
+		});
+		if (!output) throw new errors.ActorNotFound(query.getForId.actorId);
+		actorOutput = output;
+	} else if ("getForKey" in query) {
+		const existingActor = await driver.getWithKey({
+			c,
+			name: query.getForKey.name,
+			key: query.getForKey.key,
+		});
+		if (!existingActor) {
+			throw new errors.ActorNotFound(
+				`${query.getForKey.name}:${JSON.stringify(query.getForKey.key)}`,
+			);
+		}
+		actorOutput = existingActor;
+	} else if ("getOrCreateForKey" in query) {
+		const getOrCreateOutput = await driver.getOrCreateWithKey({
+			c,
+			name: query.getOrCreateForKey.name,
+			key: query.getOrCreateForKey.key,
+			input: query.getOrCreateForKey.input,
+			region: query.getOrCreateForKey.region,
+		});
+		actorOutput = {
+			actorId: getOrCreateOutput.actorId,
+		};
+	} else if ("create" in query) {
+		const createOutput = await driver.createActor({
+			c,
+			name: query.create.name,
+			key: query.create.key,
+			input: query.create.input,
+			region: query.create.region,
+		});
+		actorOutput = {
+			actorId: createOutput.actorId,
+		};
+	} else {
+		throw new errors.InvalidRequest("Invalid query format");
+	}
+
+	logger().debug("actor query result", {
+		actorId: actorOutput.actorId,
+	});
+	return { actorId: actorOutput.actorId };
+}
+
+/**
+ * Removes the on-change library's proxy recursively from a value so we can clone it with `structuredClone`.
+ */
+function unproxyRecursive<T>(objProxied: T): T {
+	const obj = onChange.target<any>(objProxied);
+
+	// Short circuit if this object was proxied
+	//
+	// If the reference is different, then this value was proxied and no
+	// nested values are proxied
+	if (obj !== objProxied) return obj;
+
+	// Handle null/undefined
+	if (!obj || typeof obj !== "object") {
+		return obj;
+	}
+
+	// Handle arrays
+	if (Array.isArray(obj)) {
+		return obj.map((x) => unproxyRecursive<any>(x)) as T;
+	}
+
+	// Handle objects
+	const result: any = {};
+	for (const key in obj) {
+		result[key] = unproxyRecursive<any>(obj[key]);
+	}
+
+	return result;
+}

package/src/inspector/actor.ts

@@ -0,0 +1,298 @@
+import { sValidator } from "@hono/standard-validator";
+import jsonPatch from "@rivetkit/fast-json-patch";
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { createNanoEvents, type Unsubscribe } from "nanoevents";
+import z from "zod/v4";
+import type {
+	AnyDatabaseProvider,
+	InferDatabaseClient,
+} from "@/actor/database";
+import {
+	ColumnsSchema,
+	type Connection,
+	ForeignKeysSchema,
+	PatchSchema,
+	type RealtimeEvent,
+	type RecordedRealtimeEvent,
+	TablesSchema,
+} from "./protocol/common";
+
+export type ActorInspectorRouterEnv = {
+	Variables: {
+		inspector: ActorInspector;
+	};
+};
+
+/**
+ * Create a router for the Actor Inspector.
+ * @internal
+ */
+export function createActorInspectorRouter() {
+	return new Hono<ActorInspectorRouterEnv>()
+		.get("/ping", (c) => {
+			return c.json({ message: "pong" }, 200);
+		})
+		.get("/state", async (c) => {
+			if (await c.var.inspector.accessors.isStateEnabled()) {
+				return c.json(
+					{
+						enabled: true,
+						state: await c.var.inspector.accessors.getState(),
+					},
+					200,
+				);
+			}
+			return c.json({ enabled: false, state: null }, 200);
+		})
+		.patch(
+			"/state",
+			sValidator(
+				"json",
+				z.object({ patch: PatchSchema }).or(z.object({ replace: z.any() })),
+			),
+			async (c) => {
+				if (!(await c.var.inspector.accessors.isStateEnabled())) {
+					return c.json({ enabled: false }, 200);
+				}
+
+				const body = c.req.valid("json");
+				if ("replace" in body) {
+					await c.var.inspector.accessors.setState(body.replace);
+					return c.json(
+						{
+							enabled: true,
+							state: await c.var.inspector.accessors.getState(),
+						},
+						200,
+					);
+				}
+				const state = await c.var.inspector.accessors.getState();
+
+				const { newDocument: newState } = jsonPatch.applyPatch(
+					state,
+					body.patch,
+				);
+				await c.var.inspector.accessors.setState(newState);
+
+				return c.json(
+					{ enabled: true, state: await c.var.inspector.accessors.getState() },
+					200,
+				);
+			},
+		)
+		.get("/state/stream", async (c) => {
+			if (!(await c.var.inspector.accessors.isStateEnabled())) {
+				return c.json({ enabled: false }, 200);
+			}
+
+			let id = 0;
+			let unsub: Unsubscribe;
+			return streamSSE(
+				c,
+				async (stream) => {
+					unsub = c.var.inspector.emitter.on("stateUpdated", async (state) => {
+						stream.writeSSE({
+							data: JSON.stringify(state) || "",
+							event: "state-update",
+							id: String(id++),
+						});
+					});
+
+					const { promise } = Promise.withResolvers<void>();
+
+					return promise;
+				},
+				async () => {
+					unsub?.();
+				},
+			);
+		})
+		.get("/connections", async (c) => {
+			const connections = await c.var.inspector.accessors.getConnections();
+			return c.json({ connections }, 200);
+		})
+		.get("/connections/stream", async (c) => {
+			let id = 0;
+			let unsub: Unsubscribe;
+			return streamSSE(
+				c,
+				async (stream) => {
+					unsub = c.var.inspector.emitter.on("connectionUpdated", async () => {
+						stream.writeSSE({
+							data: JSON.stringify(
+								await c.var.inspector.accessors.getConnections(),
+							),
+							event: "connection-update",
+							id: String(id++),
+						});
+					});
+
+					const { promise } = Promise.withResolvers<void>();
+
+					return promise;
+				},
+				async () => {
+					unsub?.();
+				},
+			);
+		})
+		.get("/events", async (c) => {
+			const events = c.var.inspector.lastRealtimeEvents;
+			return c.json({ events }, 200);
+		})
+		.post("/events/clear", async (c) => {
+			c.var.inspector.lastRealtimeEvents.length = 0; // Clear the events
+			return c.json({ message: "Events cleared" }, 200);
+		})
+		.get("/events/stream", async (c) => {
+			let id = 0;
+			let unsub: Unsubscribe;
+			return streamSSE(
+				c,
+				async (stream) => {
+					unsub = c.var.inspector.emitter.on("eventFired", () => {
+						stream.writeSSE({
+							data: JSON.stringify(c.var.inspector.lastRealtimeEvents),
+							event: "realtime-event",
+							id: String(id++),
+						});
+					});
+
+					const { promise } = Promise.withResolvers<void>();
+
+					return promise;
+				},
+				async () => {
+					unsub?.();
+				},
+			);
+		})
+		.get("/rpcs", async (c) => {
+			const rpcs = await c.var.inspector.accessors.getRpcs();
+			return c.json({ rpcs }, 200);
+		})
+		.get("/db", async (c) => {
+			if (!(await c.var.inspector.accessors.isDbEnabled())) {
+				return c.json({ enabled: false, db: null }, 200);
+			}
+
+			// Access the SQLite database
+			const db = await c.var.inspector.accessors.getDb();
+
+			// Get list of tables
+			const rows = await db.execute(`PRAGMA table_list`);
+			const tables = TablesSchema.parse(rows).filter(
+				(table) => table.schema !== "temp" && !table.name.startsWith("sqlite_"),
+			);
+			// Get columns for each table
+			const tablesInfo = await Promise.all(
+				tables.map((table) => db.execute(`PRAGMA table_info(${table.name})`)),
+			);
+			const columns = tablesInfo.map((def) => ColumnsSchema.parse(def));
+
+			// Get foreign keys for each table
+			const foreignKeysList = await Promise.all(
+				tables.map((table) =>
+					db.execute(`PRAGMA foreign_key_list(${table.name})`),
+				),
+			);
+			const foreignKeys = foreignKeysList.map((def) =>
+				ForeignKeysSchema.parse(def),
+			);
+
+			// Get record counts for each table
+			const countInfo = await Promise.all(
+				tables.map((table) =>
+					db.execute(`SELECT COUNT(*) as count FROM ${table.name}`),
+				),
+			);
+			const counts = countInfo.map((def) => {
+				return def[0].count || 0;
+			});
+
+			return c.json(
+				{
+					enabled: true,
+					db: tablesInfo.map((_, index) => {
+						return {
+							table: tables[index],
+							columns: columns[index],
+							foreignKeys: foreignKeys[index],
+							records: counts[index],
+						};
+					}),
+				},
+				200,
+			);
+		})
+		.post(
+			"/db",
+			sValidator(
+				"json",
+				z.object({ query: z.string(), params: z.array(z.any()).optional() }),
+			),
+			async (c) => {
+				if (!(await c.var.inspector.accessors.isDbEnabled())) {
+					return c.json({ enabled: false }, 200);
+				}
+				const db = await c.var.inspector.accessors.getDb();
+
+				try {
+					const result = (await db.execute(
+						c.req.valid("json").query,
+						...(c.req.valid("json").params || []),
+					)) as unknown;
+					return c.json({ result }, 200);
+				} catch (error) {
+					c;
+					return c.json({ error: (error as Error).message }, 500);
+				}
+			},
+		);
+}
+
+interface ActorInspectorAccessors {
+	isStateEnabled: () => Promise<boolean>;
+	getState: () => Promise<unknown>;
+	setState: (state: unknown) => Promise<void>;
+	isDbEnabled: () => Promise<boolean>;
+	getDb: () => Promise<InferDatabaseClient<AnyDatabaseProvider>>;
+	getRpcs: () => Promise<string[]>;
+	getConnections: () => Promise<Connection[]>;
+}
+
+interface ActorInspectorEmitterEvents {
+	stateUpdated: (state: unknown) => void;
+	connectionUpdated: () => void;
+	eventFired: (event: RealtimeEvent) => void;
+}
+
+/**
+ * Provides a unified interface for inspecting actor external and internal state.
+ */
+export class ActorInspector {
+	public readonly accessors: ActorInspectorAccessors;
+	public readonly emitter = createNanoEvents<ActorInspectorEmitterEvents>();
+
+	#lastRealtimeEvents: RecordedRealtimeEvent[] = [];
+
+	get lastRealtimeEvents() {
+		return this.#lastRealtimeEvents;
+	}
+
+	constructor(accessors: () => ActorInspectorAccessors) {
+		this.accessors = accessors();
+		this.emitter.on("eventFired", (event) => {
+			this.#lastRealtimeEvents.push({
+				id: crypto.randomUUID(),
+				timestamp: Date.now(),
+				...event,
+			});
+			// keep the last 100 events
+			if (this.#lastRealtimeEvents.length > 100) {
+				this.#lastRealtimeEvents = this.#lastRealtimeEvents.slice(-100);
+			}
+		});
+	}
+}