rivetkit 2.0.2 → 2.0.4

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);
+			}
+		});
+	}
+}

package/src/inspector/config.ts

@@ -0,0 +1,88 @@
+import type { cors } from "hono/cors";
+import { z } from "zod";
+import { HEADER_ACTOR_QUERY } from "@/driver-helpers/mod";
+import { getEnvUniversal } from "@/utils";
+
+type CorsOptions = NonNullable<Parameters<typeof cors>[0]>;
+
+const defaultTokenFn = () => {
+	const envToken = getEnvUniversal("RIVETKIT_INSPECTOR_TOKEN");
+
+	if (envToken) {
+		return envToken;
+	}
+
+	return "";
+};
+
+const defaultEnabled = () => {
+	return (
+		getEnvUniversal("NODE_ENV") !== "production" ||
+		!getEnvUniversal("RIVETKIT_INSPECTOR_DISABLE")
+	);
+};
+
+const defaultInspectorOrigins = [
+	"http://localhost:43708",
+	"http://localhost:43709",
+	"https://studio.rivet.gg",
+	"https://inspect.rivet.dev",
+];
+
+const defaultCors: CorsOptions = {
+	origin: (origin) => {
+		if (
+			defaultInspectorOrigins.includes(origin) ||
+			(origin.startsWith("https://") && origin.endsWith("rivet-dev.vercel.app"))
+		) {
+			return origin;
+		} else {
+			return null;
+		}
+	},
+	allowMethods: ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+	allowHeaders: [
+		"Authorization",
+		"Content-Type",
+		"User-Agent",
+		"baggage",
+		"sentry-trace",
+		"x-rivet-actor",
+		"x-rivet-target",
+	],
+	maxAge: 3600,
+	credentials: true,
+};
+
+export const InspectorConfigSchema = z
+	.object({
+		enabled: z.boolean().optional().default(defaultEnabled),
+		/** CORS configuration for the router. Uses Hono's CORS middleware options. */
+		cors: z
+			.custom<CorsOptions>()
+			.optional()
+			.default(() => defaultCors),
+
+		/**
+		 * Token used to access the Inspector.
+		 */
+		token: z
+			.function()
+			.returns(z.string())
+			.optional()
+			.default(() => defaultTokenFn),
+
+		/**
+		 * Default RivetKit server endpoint for Rivet Inspector to connect to. This should be the same endpoint as what you use for your Rivet client to connect to RivetKit.
+		 *
+		 * This is a convenience property just for printing out the inspector URL.
+		 */
+		defaultEndpoint: z.string().optional(),
+	})
+	.optional()
+	.default(() => ({
+		enabled: defaultEnabled(),
+		token: defaultTokenFn,
+		cors: defaultCors,
+	}));
+export type InspectorConfig = z.infer<typeof InspectorConfigSchema>;

package/src/inspector/log.ts

@@ -0,0 +1,5 @@
+import { getLogger } from "@/common/log";
+
+export function inspectorLogger() {
+	return getLogger("inspector");
+}

package/src/inspector/manager.ts

@@ -0,0 +1,86 @@
+import { sValidator } from "@hono/standard-validator";
+import { Hono } from "hono";
+import invariant from "invariant";
+import type { CreateInput } from "@/manager/driver";
+import { inspectorLogger } from "./log";
+import { type Actor, type Builds, CreateActorSchema } from "./protocol/common";
+
+export type ManagerInspectorRouterEnv = {
+	Variables: {
+		inspector: ManagerInspector;
+	};
+};
+
+/**
+ * Create a router for the Manager Inspector.
+ * @internal
+ */
+export function createManagerInspectorRouter() {
+	return new Hono<ManagerInspectorRouterEnv>()
+		.get("/ping", (c) => {
+			return c.json({ message: "pong" }, 200);
+		})
+		.get("/actors", async (c) => {
+			const limit = Number.parseInt(c.req.query("limit") ?? "") || undefined;
+			const cursor = c.req.query("cursor") || undefined;
+
+			if (!limit || (limit && limit <= 0)) {
+				return c.json("Invalid limit", 400);
+			}
+
+			try {
+				const actors = await c.var.inspector.accessors.getAllActors({
+					limit,
+					cursor,
+				});
+				return c.json(actors, 200);
+			} catch (error) {
+				inspectorLogger().error({ msg: "Failed to fetch actors", error });
+				return c.json("Failed to fetch actors", 500);
+			}
+		})
+
+		.post("/actors", sValidator("json", CreateActorSchema), async (c) => {
+			const actor = await c.var.inspector.accessors.createActor(
+				c.req.valid("json"),
+			);
+			return c.json(actor, 201);
+		})
+		.get("/builds", async (c) => {
+			const builds = await c.var.inspector.accessors.getBuilds();
+			return c.json(builds, 200);
+		})
+		.get("/actor/:id", async (c) => {
+			const id = c.req.param("id");
+			const actor = await c.var.inspector.accessors.getActorById(id);
+			if (!actor) {
+				return c.json({ error: "Actor not found" }, 404);
+			}
+			return c.json(actor, 200);
+		})
+		.get("/bootstrap", async (c) => {
+			const actors = await c.var.inspector.accessors.getAllActors({
+				limit: 10,
+			});
+			return c.json({ actors }, 200);
+		});
+}
+
+interface ManagerInspectorAccessors {
+	getAllActors: (param: { cursor?: string; limit: number }) => Promise<Actor[]>;
+	getActorById: (id: string) => Promise<Actor | null>;
+	getBuilds: () => Promise<Builds>;
+	createActor: (input: CreateInput) => Promise<Actor | null>;
+}
+
+/**
+ * Provides a unified interface for inspecting actor external and internal state.
+ */
+export class ManagerInspector {
+	public readonly accessors: ManagerInspectorAccessors;
+
+	constructor(accessors: () => ManagerInspectorAccessors) {
+		this.accessors = accessors();
+		inspectorLogger().debug({ msg: "Manager Inspector enabled and ready" });
+	}
+}

package/src/inspector/mod.ts

@@ -0,0 +1,2 @@
+export * from "./protocol/common";
+export * from "./protocol/mod";

package/src/inspector/protocol/actor.ts

@@ -0,0 +1,10 @@
+import { hc } from "hono/client";
+import type { createActorInspectorRouter } from "../actor";
+
+type ActorInspectorRouter = ReturnType<typeof createActorInspectorRouter>;
+const client = hc<ActorInspectorRouter>("");
+export type ActorInspectorClient = typeof client;
+
+export const createActorInspectorClient = (
+	...args: Parameters<typeof hc>
+): ActorInspectorClient => hc<ActorInspectorRouter>(...args);

package/src/inspector/protocol/common.ts

@@ -0,0 +1,196 @@
+import z from "zod/v4";
+import { ActorKeySchema, MAX_ACTOR_KEY_SIZE } from "@/manager/protocol/query";
+
+export const ActorId = z.string().brand("ActorId");
+export type ActorId = z.infer<typeof ActorId>;
+
+export enum ActorFeature {
+	Logs = "logs",
+	Config = "config",
+	Connections = "connections",
+	State = "state",
+	Console = "console",
+	Runtime = "runtime",
+	Metrics = "metrics",
+	EventsMonitoring = "events-monitoring",
+	Database = "database",
+}
+
+export const ActorLogEntry = z.object({
+	level: z.string(),
+	message: z.string(),
+	timestamp: z.string(),
+	metadata: z.record(z.string(), z.any()).optional(),
+});
+
+export const ActorSchema = z.object({
+	id: ActorId,
+	name: z.string(),
+	key: z.array(z.string()),
+	tags: z.record(z.string(), z.string()).optional(),
+	region: z.string().optional(),
+	createdAt: z.string().optional(),
+	startedAt: z.string().optional(),
+	destroyedAt: z.string().optional(),
+	features: z.array(z.enum(ActorFeature)).optional(),
+});
+
+export type Actor = z.infer<typeof ActorSchema>;
+export type ActorLogEntry = z.infer<typeof ActorLogEntry>;
+
+// MARK: State
+
+export const OperationSchema = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("remove"),
+		path: z.string(),
+	}),
+	z.object({
+		op: z.literal("add"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+	z.object({
+		op: z.literal("replace"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+	z.object({
+		op: z.literal("move"),
+		path: z.string(),
+		from: z.string(),
+	}),
+	z.object({
+		op: z.literal("copy"),
+		path: z.string(),
+		from: z.string(),
+	}),
+	z.object({
+		op: z.literal("test"),
+		path: z.string(),
+		value: z.unknown(),
+	}),
+]);
+export type Operation = z.infer<typeof OperationSchema>;
+
+export const PatchSchema = z.array(OperationSchema);
+export type Patch = z.infer<typeof PatchSchema>;
+
+// MARK: Connections
+
+export const ConnectionSchema = z.object({
+	params: z.record(z.string(), z.any()).optional(),
+	id: z.string(),
+	stateEnabled: z.boolean().optional(),
+	state: z.any().optional(),
+	auth: z.record(z.string(), z.any()).optional(),
+});
+export type Connection = z.infer<typeof ConnectionSchema>;
+
+// MARK: Realtime Events
+
+export const RealtimeEventSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("action"),
+		name: z.string(),
+		args: z.array(z.any()),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("broadcast"),
+		eventName: z.string(),
+		args: z.array(z.any()),
+	}),
+	z.object({
+		type: z.literal("subscribe"),
+		eventName: z.string(),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("unsubscribe"),
+		eventName: z.string(),
+		connId: z.string(),
+	}),
+	z.object({
+		type: z.literal("event"),
+		eventName: z.string(),
+		args: z.array(z.any()),
+		connId: z.string(),
+	}),
+]);
+export type RealtimeEvent = z.infer<typeof RealtimeEventSchema>;
+export const RecordedRealtimeEventSchema = RealtimeEventSchema.and(
+	z.object({
+		id: z.string(),
+		timestamp: z.number(),
+	}),
+);
+export type RecordedRealtimeEvent = z.infer<typeof RecordedRealtimeEventSchema>;
+
+// MARK: Database
+
+export const DatabaseQuerySchema = z.object({
+	sql: z.string(),
+	args: z.array(z.string().or(z.number())),
+});
+export type DatabaseQuery = z.infer<typeof DatabaseQuerySchema>;
+
+export const TableSchema = z.object({
+	schema: z.string(),
+	name: z.string(),
+	type: z.enum(["table", "view"]),
+});
+export type Table = z.infer<typeof TableSchema>;
+
+export const TablesSchema = z.array(TableSchema);
+export type Tables = z.infer<typeof TablesSchema>;
+
+export const ColumnSchema = z.object({
+	cid: z.number(),
+	name: z.string(),
+	type: z
+		.string()
+		.toLowerCase()
+		.transform((val) => {
+			return z
+				.enum(["integer", "text", "real", "blob", "numeric", "serial"])
+				.parse(val);
+		}),
+	notnull: z.coerce.boolean(),
+	dflt_value: z.string().nullable(),
+	pk: z.coerce.boolean().nullable(),
+});
+export type Column = z.infer<typeof ColumnSchema>;
+
+export const ColumnsSchema = z.array(ColumnSchema);
+export type Columns = z.infer<typeof ColumnsSchema>;
+
+export const ForeignKeySchema = z.object({
+	id: z.number(),
+	table: z.string(),
+	from: z.string(),
+	to: z.string(),
+});
+export type ForeignKey = z.infer<typeof ForeignKeySchema>;
+
+export const ForeignKeysSchema = z.array(ForeignKeySchema);
+export type ForeignKeys = z.infer<typeof ForeignKeysSchema>;
+
+// MARK: Builds
+
+export const BuildSchema = z.object({
+	name: z.string(),
+	createdAt: z.string().optional(),
+	tags: z.record(z.string(), z.string()).optional(),
+});
+export type Build = z.infer<typeof BuildSchema>;
+export const BuildsSchema = z.array(BuildSchema);
+export type Builds = z.infer<typeof BuildsSchema>;
+
+export const CreateActorSchema = z.object({
+	name: z.string(),
+	// FIXME: Replace with ActorKeySchema when ready
+	key: z.array(z.string().max(MAX_ACTOR_KEY_SIZE)),
+	input: z.any(),
+});
+export type CreateActor = z.infer<typeof CreateActorSchema>;

package/src/inspector/protocol/manager.ts

@@ -0,0 +1,10 @@
+import { hc } from "hono/client";
+import type { createManagerInspectorRouter } from "../manager";
+
+type ManagerInspectorRouter = ReturnType<typeof createManagerInspectorRouter>;
+const client = hc<ManagerInspectorRouter>("");
+export type ManagerInspectorClient = typeof client;
+
+export const createManagerInspectorClient = (
+	...args: Parameters<typeof hc>
+): ManagerInspectorClient => hc<ManagerInspectorRouter>(...args);

package/src/inspector/protocol/mod.ts

@@ -0,0 +1,2 @@
+export * from "./actor";
+export * from "./manager";