rivetkit 2.0.42 → 2.1.0-rc.1

package/src/inspector/actor-inspector.ts

@@ -5,48 +5,24 @@ import {
 	CONN_DRIVER_SYMBOL,
 	CONN_STATE_MANAGER_SYMBOL,
 } from "@/actor/conn/mod";
+import { getRunInspectorConfig } from "@/actor/config";
 import { ActionContext } from "@/actor/contexts/action";
 import * as actorErrors from "@/actor/errors";
 import type { AnyActorInstance } from "@/mod";
 import type * as schema from "@/schemas/actor-inspector/mod";
-import { assertUnreachable, bufferToArrayBuffer } from "@/utils";
-import type { Event } from "./mod";
+import { bufferToArrayBuffer } from "@/utils";
 
 interface ActorInspectorEmitterEvents {
 	stateUpdated: (state: unknown) => void;
 	connectionsUpdated: () => void;
-	eventFired: (event: EventDetails) => void;
-	eventsChanged: () => void;
+	queueUpdated: () => void;
+	workflowHistoryUpdated: (history: schema.WorkflowHistory) => void;
 }
 
 export type Connection = Omit<schema.Connection, "details"> & {
 	details: unknown;
 };
 
-type EventDetails =
-	| {
-			type: "action";
-			name: string;
-			args: unknown[];
-			connId: string;
-	  }
-	| {
-			type: "subscribe";
-			eventName: string;
-			connId: string;
-	  }
-	| {
-			type: "unsubscribe";
-			eventName: string;
-			connId: string;
-	  }
-	| {
-			type: "event";
-			eventName: string;
-			args: unknown[];
-			connId: string;
-	  }
-	| { type: "broadcast"; eventName: string; args: unknown[] };
 
 /**
  * Provides a unified interface for inspecting actor external and internal state.
@@ -54,34 +30,67 @@ type EventDetails =
 export class ActorInspector {
 	public readonly emitter = createNanoEvents<ActorInspectorEmitterEvents>();
 
-	#lastEvents: Event[] = [];
+	#lastQueueSize = 0;
+	#workflowInspector?: NonNullable<
+		ReturnType<typeof getRunInspectorConfig>
+	>["workflow"];
 
 	constructor(private readonly actor: AnyActorInstance) {
-		this.emitter.on("eventFired", (event) => {
-			const commonParams = {
-				id: crypto.randomUUID(),
-				timestamp: BigInt(Date.now()),
-			};
-
-			this.#lastEvents.push({
-				...commonParams,
-				...transformEvent(event),
+		this.#lastQueueSize = actor.queueManager?.size ?? 0;
+		const runInspector = getRunInspectorConfig(actor.config.run);
+		this.#workflowInspector = runInspector?.workflow;
+		if (this.#workflowInspector?.onHistoryUpdated) {
+			this.#workflowInspector.onHistoryUpdated((history) => {
+				this.emitter.emit(
+					"workflowHistoryUpdated",
+					history as schema.WorkflowHistory,
+				);
 			});
+		}
+	}
 
-			// keep the last 100 events
-			if (this.#lastEvents.length > 100) {
-				this.#lastEvents = this.#lastEvents.slice(-100);
-			}
-		});
+	getQueueSize() {
+		return this.#lastQueueSize;
 	}
 
-	getLastEvents() {
-		return this.#lastEvents;
+	async getQueueStatus(limit: number): Promise<schema.QueueStatus> {
+		const maxSize = this.actor.config.options.maxQueueSize;
+		const safeLimit = Math.max(0, Math.floor(limit));
+		const messages = await this.actor.queueManager.getMessages();
+		const sorted = messages.sort(
+			(a, b) => a.createdAt - b.createdAt,
+		);
+		const limited = safeLimit > 0 ? sorted.slice(0, safeLimit) : [];
+		return {
+			size: BigInt(this.#lastQueueSize),
+			maxSize: BigInt(maxSize),
+			truncated: sorted.length > limited.length,
+			messages: limited.map((message) => ({
+				id: message.id,
+				name: message.name,
+				createdAtMs: BigInt(message.createdAt),
+			})),
+		};
 	}
 
-	clearEvents() {
-		this.#lastEvents = [];
-		this.emitter.emit("eventsChanged");
+	updateQueueSize(size: number) {
+		if (this.#lastQueueSize === size) {
+			return;
+		}
+		this.#lastQueueSize = size;
+		this.emitter.emit("queueUpdated");
+	}
+
+	isWorkflowEnabled() {
+		return this.#workflowInspector !== undefined;
+	}
+
+	getWorkflowHistory(): schema.WorkflowHistory | null {
+		if (!this.#workflowInspector) {
+			return null;
+		}
+		const history = this.#workflowInspector.getHistory();
+		return (history ?? null) as schema.WorkflowHistory | null;
 	}
 
 	// actor accessor methods
@@ -94,6 +103,73 @@ export class ActorInspector {
 		}
 	}
 
+	async getDatabaseSchema(): Promise<ArrayBuffer> {
+		if (!this.isDatabaseEnabled()) {
+			throw new actorErrors.DatabaseNotEnabled();
+		}
+
+		const db = this.actor.db;
+
+		// Get table list from sqlite_master, excluding internal tables.
+		const tables = await db.execute(
+			"SELECT name, type FROM sqlite_master WHERE type IN ('table', 'view') AND name NOT LIKE 'sqlite_%' AND name NOT LIKE '__drizzle_%'",
+		) as { name: string; type: string }[];
+
+		// Serialize all queries to avoid concurrent @rivetkit/sqlite access
+		// which can cause "file is not a database" errors.
+		const tableInfos = [];
+		for (const table of tables) {
+			const quoted = `"${escapeDoubleQuotes(table.name)}"`;
+			const sample = await db.execute(
+				`SELECT * FROM ${quoted} LIMIT 1`,
+			) as Record<string, unknown>[];
+			const countResult = await db.execute(
+				`SELECT COUNT(*) as count FROM ${quoted}`,
+			) as { count: number }[];
+
+			const columnNames = sample?.[0]
+				? Object.keys(sample[0])
+				: [];
+
+			tableInfos.push({
+				table: { schema: "main", name: table.name, type: table.type },
+				columns: columnNames.map((name, cid) => ({
+					cid,
+					name,
+					type: "",
+					notnull: 0,
+					dflt_value: null,
+					pk: 0,
+				})),
+				foreignKeys: [],
+				records: countResult?.[0]?.count ?? 0,
+			});
+		}
+
+		return bufferToArrayBuffer(cbor.encode({ tables: tableInfos }));
+	}
+
+	async getDatabaseTableRows(
+		table: string,
+		limit: number,
+		offset: number,
+	): Promise<ArrayBuffer> {
+		if (!this.isDatabaseEnabled()) {
+			throw new actorErrors.DatabaseNotEnabled();
+		}
+
+		const db = this.actor.db;
+		const safeLimit = Math.max(0, Math.min(Math.floor(limit), 500));
+		const safeOffset = Math.max(0, Math.floor(offset));
+		const quoted = `"${escapeDoubleQuotes(table)}"`;
+		const result = await db.execute(
+			`SELECT * FROM ${quoted} LIMIT ? OFFSET ?`,
+			safeLimit,
+			safeOffset,
+		);
+		return bufferToArrayBuffer(cbor.encode(result));
+	}
+
 	isStateEnabled() {
 		return this.actor.stateEnabled;
 	}
@@ -168,63 +244,109 @@ export class ActorInspector {
 			conn.disconnect();
 		}
 	}
-}
 
-function transformEvent(event: EventDetails) {
-	if (event.type === "action") {
-		return {
-			body: {
-				tag: "ActionEvent",
-				val: {
-					name: event.name,
-					args: bufferToArrayBuffer(cbor.encode(event.args)),
+	// JSON-native methods for the HTTP inspector API. These return raw JS
+	// objects suitable for JSON serialization instead of CBOR-encoded buffers.
 
-					connId: event.connId,
-				},
-			},
-		} as const;
-	} else if (event.type === "subscribe") {
-		return {
-			body: {
-				tag: "SubscribeEvent",
-				val: {
-					eventName: event.eventName,
-					connId: event.connId,
-				},
-			},
-		} as const;
-	} else if (event.type === "unsubscribe") {
-		return {
-			body: {
-				tag: "UnSubscribeEvent",
-				val: {
-					eventName: event.eventName,
-					connId: event.connId,
-				},
-			},
-		} as const;
-	} else if (event.type === "event") {
-		return {
-			body: {
-				tag: "FiredEvent",
-				val: {
-					eventName: event.eventName,
-					args: bufferToArrayBuffer(cbor.encode(event.args)),
-					connId: event.connId,
+	getStateJson(): unknown {
+		if (!this.actor.stateEnabled) {
+			throw new actorErrors.StateNotEnabled();
+		}
+		return this.actor.stateManager.persistRaw.state;
+	}
+
+	async setStateJson(state: unknown): Promise<void> {
+		if (!this.actor.stateEnabled) {
+			throw new actorErrors.StateNotEnabled();
+		}
+		this.actor.stateManager.state = state;
+		await this.actor.stateManager.saveState({ immediate: true });
+	}
+
+	getConnectionsJson(): { id: string; details: unknown }[] {
+		return Array.from(
+			this.actor.connectionManager.connections.entries(),
+		).map(([id, conn]) => {
+			const connStateManager = conn[CONN_STATE_MANAGER_SYMBOL];
+			return {
+				type: conn[CONN_DRIVER_SYMBOL]?.type,
+				id,
+				details: {
+					type: conn[CONN_DRIVER_SYMBOL]?.type,
+					params: conn.params as any,
+					stateEnabled: connStateManager.stateEnabled,
+					state: connStateManager.stateEnabled
+						? connStateManager.state
+						: undefined,
+					subscriptions: conn.subscriptions.size,
+					isHibernatable: conn.isHibernatable,
 				},
-			},
-		} as const;
-	} else if (event.type === "broadcast") {
+			};
+		});
+	}
+
+	async executeActionJson(name: string, args: unknown[]): Promise<unknown> {
+		const conn = await this.actor.connectionManager.prepareAndConnectConn(
+			createHttpDriver(),
+			undefined,
+			undefined,
+			undefined,
+			undefined,
+		);
+
+		try {
+			return await this.actor.executeAction(
+				new ActionContext(this.actor, conn),
+				name,
+				args,
+			);
+		} finally {
+			conn.disconnect();
+		}
+	}
+
+	async getTracesJson(options: {
+		startMs: number;
+		endMs: number;
+		limit: number;
+	}): Promise<{ otlp: unknown; clamped: boolean }> {
+		const result = await this.actor.traces.readRange(options);
+		return result;
+	}
+
+	getWorkflowHistoryJson(): { history: unknown | null; isWorkflowEnabled: boolean } {
+		const bigIntReplacer = (_key: string, value: unknown) =>
+			typeof value === "bigint" ? Number(value) : value;
+		const history = this.getWorkflowHistory();
+		const safeHistory = history
+			? JSON.parse(JSON.stringify(history, bigIntReplacer))
+			: null;
 		return {
-			body: {
-				tag: "BroadcastEvent",
-				val: {
-					eventName: event.eventName,
-					args: bufferToArrayBuffer(cbor.encode(event.args)),
-				},
-			},
-		} as const;
-	} else {
-		assertUnreachable(event);
+			history: safeHistory,
+			isWorkflowEnabled: this.isWorkflowEnabled(),
+		};
+	}
+
+	getQueueStatusJson(limit: number): Promise<{
+		size: number;
+		maxSize: number;
+		truncated: boolean;
+		messages: { id: number; name: string; createdAtMs: number }[];
+	}> {
+		return this.getQueueStatus(limit).then((status) => ({
+			size: Number(status.size),
+			maxSize: Number(status.maxSize),
+			truncated: status.truncated,
+			messages: status.messages.map((m) => ({
+				id: Number(m.id),
+				name: m.name,
+				createdAtMs: Number(m.createdAtMs),
+			})),
+		}));
 	}
 }
+
+function escapeDoubleQuotes(value: string): string {
+	return value.replace(/"/g, '""');
+}
+

package/src/inspector/config.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import {
 	getRivetkitInspectorToken,
 	isDev,

package/src/inspector/handler.ts

@@ -3,11 +3,13 @@ import type { Unsubscribe } from "nanoevents";
 import type { UpgradeWebSocketArgs } from "@/actor/router-websocket-endpoints";
 import type { AnyActorInstance, RivetMessageEvent } from "@/mod";
 import type { ToClient } from "@/schemas/actor-inspector/mod";
+import { encodeReadRangeWire } from "@rivetkit/traces/encoding";
 import {
+	CURRENT_VERSION as INSPECTOR_CURRENT_VERSION,
 	TO_CLIENT_VERSIONED as toClient,
 	TO_SERVER_VERSIONED as toServer,
 } from "@/schemas/actor-inspector/versioned";
-import { assertUnreachable } from "@/utils";
+import { assertUnreachable, bufferToArrayBuffer } from "@/utils";
 import { inspectorLogger } from "./log";
 
 export async function handleWebSocketInspectorConnect({
@@ -16,6 +18,7 @@ export async function handleWebSocketInspectorConnect({
 	actor: AnyActorInstance;
 }): Promise<UpgradeWebSocketArgs> {
 	const inspector = actor.inspector;
+	const maxQueueStatusLimit = 200;
 
 	const listeners: Unsubscribe[] = [];
 	return {
@@ -26,13 +29,15 @@ export async function handleWebSocketInspectorConnect({
 					tag: "Init",
 					val: {
 						connections: inspector.getConnections(),
-						events: inspector.getLastEvents(),
 						rpcs: inspector.getRpcs(),
 						state: inspector.isStateEnabled()
 							? inspector.getState()
 							: null,
 						isStateEnabled: inspector.isStateEnabled(),
 						isDatabaseEnabled: inspector.isDatabaseEnabled(),
+						queueSize: BigInt(inspector.getQueueSize()),
+						workflowHistory: inspector.getWorkflowHistory(),
+						isWorkflowEnabled: inspector.isWorkflowEnabled(),
 					},
 				},
 			});
@@ -54,19 +59,21 @@ export async function handleWebSocketInspectorConnect({
 						},
 					});
 				}),
-				inspector.emitter.on("eventFired", () => {
+				inspector.emitter.on("queueUpdated", () => {
 					sendMessage(ws, {
 						body: {
-							tag: "EventsUpdated",
-							val: { events: inspector.getLastEvents() },
+							tag: "QueueUpdated",
+							val: {
+								queueSize: BigInt(inspector.getQueueSize()),
+							},
 						},
 					});
 				}),
-				inspector.emitter.on("eventsChanged", () => {
+				inspector.emitter.on("workflowHistoryUpdated", (history) => {
 					sendMessage(ws, {
 						body: {
-							tag: "EventsUpdated",
-							val: { events: inspector.getLastEvents() },
+							tag: "WorkflowHistoryUpdated",
+							val: { history },
 						},
 					});
 				}),
@@ -115,37 +122,112 @@ export async function handleWebSocketInspectorConnect({
 							},
 						},
 					});
-				} else if (message.body.tag === "EventsRequest") {
+				} else if (message.body.tag === "RpcsListRequest") {
 					sendMessage(ws, {
 						body: {
-							tag: "EventsResponse",
+							tag: "RpcsListResponse",
 							val: {
 								rid: message.body.val.id,
-								events: inspector.getLastEvents(),
+								rpcs: inspector.getRpcs(),
 							},
 						},
 					});
-				} else if (message.body.tag === "ClearEventsRequest") {
-					inspector.clearEvents();
+				} else if (message.body.tag === "TraceQueryRequest") {
+					const { id, startMs, endMs, limit } = message.body.val;
+					const wire = await actor.traces.readRangeWire({
+						startMs: Number(startMs),
+						endMs: Number(endMs),
+						limit: Number(limit),
+					});
 					sendMessage(ws, {
 						body: {
-							tag: "EventsResponse",
+							tag: "TraceQueryResponse",
 							val: {
-								rid: message.body.val.id,
-								events: [],
+								rid: id,
+								payload: bufferToArrayBuffer(
+									encodeReadRangeWire(wire),
+								),
 							},
 						},
 					});
-				} else if (message.body.tag === "RpcsListRequest") {
+				} else if (message.body.tag === "QueueRequest") {
+					const { id, limit } = message.body.val;
+					const status = await inspector.getQueueStatus(
+						Math.min(Number(limit), maxQueueStatusLimit),
+					);
 					sendMessage(ws, {
 						body: {
-							tag: "RpcsListResponse",
+							tag: "QueueResponse",
+							val: {
+								rid: id,
+								status,
+							},
+						},
+					});
+				} else if (message.body.tag === "WorkflowHistoryRequest") {
+					sendMessage(ws, {
+						body: {
+							tag: "WorkflowHistoryResponse",
 							val: {
 								rid: message.body.val.id,
-								rpcs: inspector.getRpcs(),
+								history: inspector.getWorkflowHistory(),
+								isWorkflowEnabled:
+									inspector.isWorkflowEnabled(),
 							},
 						},
 					});
+				} else if (message.body.tag === "DatabaseSchemaRequest") {
+					const { id } = message.body.val;
+					try {
+						const schema = await inspector.getDatabaseSchema();
+						sendMessage(ws, {
+							body: {
+								tag: "DatabaseSchemaResponse",
+								val: { rid: id, schema },
+							},
+						});
+					} catch (error) {
+						inspectorLogger().warn(
+							{ error },
+							"Failed to get database schema",
+						);
+						sendMessage(ws, {
+							body: {
+								tag: "Error",
+								val: {
+									message: `Failed to get database schema: ${error instanceof Error ? error.message : String(error)}`,
+								},
+							},
+						});
+					}
+				} else if (message.body.tag === "DatabaseTableRowsRequest") {
+					const { id, table, limit, offset } = message.body.val;
+					try {
+						const result = await inspector.getDatabaseTableRows(
+							table,
+							Number(limit),
+							Number(offset),
+						);
+						sendMessage(ws, {
+							body: {
+								tag: "DatabaseTableRowsResponse",
+								val: { rid: id, result },
+							},
+						});
+					} catch (error) {
+						inspectorLogger().warn(
+							{ error },
+							"Failed to get database table rows",
+						);
+						sendMessage(ws, {
+							body: {
+								tag: "Error",
+								val: {
+									message: `Failed to get database rows: ${error instanceof Error ? error.message : String(error)}`,
+								},
+							},
+						});
+					}
 				} else {
 					assertUnreachable(message.body);
 				}
@@ -181,7 +263,7 @@ function sendMessage(ws: WSContext, message: ToClient) {
 	ws.send(
 		toClient.serializeWithEmbeddedVersion(
 			message,
-			1,
+			INSPECTOR_CURRENT_VERSION,
 		) as unknown as ArrayBuffer,
 	);
 }

package/src/inspector/mod.browser.ts

@@ -0,0 +1,8 @@
+// Browser-safe inspector exports (schemas and types only, no server runtime)
+export * from "../schemas/actor-inspector/mod";
+export * from "../schemas/actor-inspector/versioned";
+export type { WorkflowHistory as TransportWorkflowHistory } from "../schemas/transport/mod";
+export {
+    decodeWorkflowHistoryTransport,
+    encodeWorkflowHistoryTransport,
+} from "./transport";

package/src/inspector/mod.ts

@@ -1,2 +1,4 @@
 export * from "../schemas/actor-inspector/mod";
 export * from "../schemas/actor-inspector/versioned";
+export { decodeWorkflowHistoryTransport, encodeWorkflowHistoryTransport } from "./transport";
+export type { WorkflowHistory as TransportWorkflowHistory } from "../schemas/transport/mod";

package/src/inspector/serve-ui.ts

@@ -0,0 +1,40 @@
+
+import { extract } from "tar";
+import { getNodeFs, getNodeOs, getNodePath, getNodeUrl } from "@/utils/node";
+
+let extractedDir: string | undefined;
+let extractionPromise: Promise<string> | undefined;
+
+export async function getInspectorDir(): Promise<string> {
+	if (extractedDir !== undefined) return extractedDir;
+	if (extractionPromise !== undefined) return extractionPromise;
+
+	const nodeFs = getNodeFs();
+	const os = getNodeOs();
+	const url = getNodeUrl();
+	const path = getNodePath();
+
+	extractionPromise = (async () => {
+		const tarball = path.join(
+			path.dirname(url.fileURLToPath(import.meta.url)),
+			"../../dist/inspector.tar.gz",
+		);
+
+		try {
+			await nodeFs.access(tarball);
+		} catch {
+			throw new Error(
+				`Inspector tarball not found at ${tarball}. Run 'pnpm build:pack-inspector' first.`,
+			);
+		}
+
+		const dest = path.join(os.tmpdir(), "rivetkit-inspector");
+		await nodeFs.mkdir(dest, { recursive: true });
+		await extract({ file: tarball, cwd: dest });
+
+		extractedDir = dest;
+		return dest;
+	})();
+
+	return extractionPromise;
+}

package/src/inspector/transport.ts

@@ -0,0 +1,18 @@
+import type { WorkflowHistory } from "@/schemas/transport/mod";
+import {
+	decodeWorkflowHistory,
+	encodeWorkflowHistory,
+} from "@/schemas/transport/mod";
+import { bufferToArrayBuffer, toUint8Array } from "@/utils";
+
+export function encodeWorkflowHistoryTransport(
+	history: WorkflowHistory,
+): ArrayBuffer {
+	return bufferToArrayBuffer(encodeWorkflowHistory(history));
+}
+
+export function decodeWorkflowHistoryTransport(
+	data: ArrayBuffer | ArrayBufferView,
+): WorkflowHistory {
+	return decodeWorkflowHistory(toUint8Array(data));
+}