rivetkit 2.0.42 → 2.1.0-rc.1

package/src/actor/protocol/old.ts

@@ -1,5 +1,5 @@
 import * as cbor from "cbor-x";
-import { z } from "zod";
+import { z } from "zod/v4";
 import type { AnyDatabaseProvider } from "@/actor/database";
 import * as errors from "@/actor/errors";
 import {
@@ -29,6 +29,7 @@ import {
 import { CONN_SEND_MESSAGE_SYMBOL, type Conn } from "../conn/mod";
 import { ActionContext } from "../contexts";
 import type { ActorInstance } from "../instance/mod";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
 
 interface MessageEventOpts {
 	encoding: Encoding;
@@ -139,19 +140,21 @@ export interface ProcessMessageHandler<
 	V,
 	I,
 	DB extends AnyDatabaseProvider,
+	E extends EventSchemaConfig,
+	Q extends QueueSchemaConfig,
 > {
 	onExecuteAction?: (
-		ctx: ActionContext<S, CP, CS, V, I, DB>,
+		ctx: ActionContext<S, CP, CS, V, I, DB, E, Q>,
 		name: string,
 		args: unknown[],
 	) => Promise<unknown>;
 	onSubscribe?: (
 		eventName: string,
-		conn: Conn<S, CP, CS, V, I, DB>,
+		conn: Conn<S, CP, CS, V, I, DB, E, Q>,
 	) => Promise<void>;
 	onUnsubscribe?: (
 		eventName: string,
-		conn: Conn<S, CP, CS, V, I, DB>,
+		conn: Conn<S, CP, CS, V, I, DB, E, Q>,
 	) => Promise<void>;
 }
 
@@ -162,6 +165,8 @@ export async function processMessage<
 	V,
 	I,
 	DB extends AnyDatabaseProvider,
+	E extends EventSchemaConfig,
+	Q extends QueueSchemaConfig,
 >(
 	message: {
 		body:
@@ -174,9 +179,9 @@ export async function processMessage<
 					val: { eventName: string; subscribe: boolean };
 			  };
 	},
-	actor: ActorInstance<S, CP, CS, V, I, DB>,
-	conn: Conn<S, CP, CS, V, I, DB>,
-	handler: ProcessMessageHandler<S, CP, CS, V, I, DB>,
+	actor: ActorInstance<S, CP, CS, V, I, DB, E, Q>,
+	conn: Conn<S, CP, CS, V, I, DB, E, Q>,
+	handler: ProcessMessageHandler<S, CP, CS, V, I, DB, E, Q>,
 ) {
 	let actionId: bigint | undefined;
 	let actionName: string | undefined;
@@ -199,7 +204,10 @@ export async function processMessage<
 				actionName: name,
 			});
 
-			const ctx = new ActionContext<S, CP, CS, V, I, DB>(actor, conn);
+			const ctx = new ActionContext<S, CP, CS, V, I, DB, E, Q>(
+				actor,
+				conn,
+			);
 
 			// Process the action request and wait for the result
 			// This will wait for async actions to complete
@@ -265,11 +273,18 @@ export async function processMessage<
 				subscribe,
 			});
 
-			if (subscribe) {
-				await handler.onSubscribe(eventName, conn);
-			} else {
-				await handler.onUnsubscribe(eventName, conn);
-			}
+				if (subscribe) {
+					await actor.assertCanSubscribe(
+						new ActionContext<S, CP, CS, V, I, DB, E, Q>(
+							actor,
+							conn,
+						),
+						eventName,
+					);
+					await handler.onSubscribe(eventName, conn);
+				} else {
+					await handler.onUnsubscribe(eventName, conn);
+				}
 
 			actor.rLog.debug({
 				msg: "subscription request completed",

package/src/actor/protocol/serde.ts

@@ -1,6 +1,6 @@
 import * as cbor from "cbor-x";
 import type { VersionedDataHandler } from "vbare";
-import { z } from "zod";
+import { z } from "zod/v4";
 import * as errors from "@/actor/errors";
 import { serializeWithEncoding } from "@/serde";
 import { loggerWithoutContext } from "../log";

package/src/actor/router-endpoints.ts

@@ -5,6 +5,7 @@ import { ActionContext } from "@/actor/contexts";
 import * as errors from "@/actor/errors";
 import type { AnyActorInstance } from "@/actor/instance/mod";
 import { type Encoding, EncodingSchema } from "@/actor/protocol/serde";
+import { hasSchemaConfigKey } from "@/actor/schema";
 import {
 	HEADER_ACTOR_QUERY,
 	HEADER_CONN_PARAMS,
@@ -13,17 +14,24 @@ import {
 	WS_PROTOCOL_ENCODING,
 } from "@/common/actor-router-consts";
 import { stringifyError } from "@/common/utils";
+import type { RegistryConfig } from "@/registry/config";
 import type * as protocol from "@/schemas/client-protocol/mod";
 import {
 	CURRENT_VERSION as CLIENT_PROTOCOL_CURRENT_VERSION,
 	HTTP_ACTION_REQUEST_VERSIONED,
 	HTTP_ACTION_RESPONSE_VERSIONED,
+	HTTP_QUEUE_SEND_REQUEST_VERSIONED,
+	HTTP_QUEUE_SEND_RESPONSE_VERSIONED,
 } from "@/schemas/client-protocol/versioned";
 import {
 	type HttpActionRequest as HttpActionRequestJson,
 	HttpActionRequestSchema,
 	type HttpActionResponse as HttpActionResponseJson,
 	HttpActionResponseSchema,
+	type HttpQueueSendRequest as HttpQueueSendRequestJson,
+	HttpQueueSendRequestSchema,
+	type HttpQueueSendResponse as HttpQueueSendResponseJson,
+	HttpQueueSendResponseSchema,
 } from "@/schemas/client-protocol-zod/mod";
 import {
 	contentTypeForEncoding,
@@ -35,7 +43,6 @@ import { createHttpDriver } from "./conn/drivers/http";
 import { createRawRequestDriver } from "./conn/drivers/raw-request";
 import type { ActorDriver } from "./driver";
 import { loggerWithoutContext } from "./log";
-import { RegistryConfig } from "@/registry/config";
 
 export interface ActionOpts {
 	req?: HonoRequest;
@@ -61,6 +68,15 @@ export interface FetchOpts {
 	actorId: string;
 }
 
+export interface QueueSendOpts {
+	req?: HonoRequest;
+	name: string;
+	body: unknown;
+	wait?: boolean;
+	timeout?: number;
+	actorId: string;
+}
+
 /**
  * Creates an action handler
  */
@@ -96,31 +112,50 @@ export async function handleAction(
 	const actionArgs = request;
 
 	// Invoke the action
-	let actor: AnyActorInstance | undefined;
-	let conn: AnyConn | undefined;
 	let output: unknown | undefined;
-	try {
-		actor = await actorDriver.loadActor(actorId);
+	let outputReady = false;
+	const maxAttempts = 3;
+	for (let attempt = 0; attempt < maxAttempts; attempt++) {
+		let actor: AnyActorInstance | undefined;
+		let conn: AnyConn | undefined;
+		try {
+			actor = await actorDriver.loadActor(actorId);
 
-		actor.rLog.debug({ msg: "handling action", actionName, encoding });
+			actor.rLog.debug({ msg: "handling action", actionName, encoding });
 
-		// Create conn
-		conn = await actor.connectionManager.prepareAndConnectConn(
-			createHttpDriver(),
-			parameters,
-			c.req.raw,
-			c.req.path,
-			c.req.header(),
-		);
+			// Create conn
+			conn = await actor.connectionManager.prepareAndConnectConn(
+				createHttpDriver(),
+				parameters,
+				c.req.raw,
+				c.req.path,
+				c.req.header(),
+			);
 
-		// Call action
-		const ctx = new ActionContext(actor, conn!);
-		output = await actor.executeAction(ctx, actionName, actionArgs);
-	} finally {
-		if (conn) {
-			conn.disconnect();
+			// Call action
+			const ctx = new ActionContext(actor, conn);
+			output = await actor.executeAction(ctx, actionName, actionArgs);
+			outputReady = true;
+			break;
+		} catch (error) {
+			const shouldRetry =
+				error instanceof errors.InternalError &&
+				error.message === "Actor is stopping" &&
+				attempt < maxAttempts - 1;
+			if (shouldRetry) {
+				await new Promise((resolve) => setTimeout(resolve, 25));
+				continue;
+			}
+			throw error;
+		} finally {
+			if (conn) {
+				conn.disconnect();
+			}
 		}
 	}
+	if (!outputReady) {
+		throw new errors.InternalError("Action did not complete");
+	}
 
 	// Send response
 	const serialized = serializeWithEncoding(
@@ -138,7 +173,10 @@ export async function handleAction(
 	);
 
 	// Check outgoing message size
-	const messageSize = serialized instanceof Uint8Array ? serialized.byteLength : serialized.length;
+	const messageSize =
+		serialized instanceof Uint8Array
+			? serialized.byteLength
+			: serialized.length;
 	if (messageSize > config.maxOutgoingMessageSize) {
 		throw new errors.OutgoingMessageTooLong();
 	}
@@ -149,6 +187,124 @@ export async function handleAction(
 	});
 }
 
+export async function handleQueueSend(
+	c: HonoContext,
+	config: RegistryConfig,
+	actorDriver: ActorDriver,
+	actorId: string,
+	queueName?: string,
+) {
+	const encoding = getRequestEncoding(c.req);
+	const params = getRequestConnParams(c.req);
+	const arrayBuffer = await c.req.arrayBuffer();
+
+	if (arrayBuffer.byteLength > config.maxIncomingMessageSize) {
+		throw new errors.IncomingMessageTooLong();
+	}
+
+	const request = deserializeWithEncoding(
+		encoding,
+		new Uint8Array(arrayBuffer),
+		HTTP_QUEUE_SEND_REQUEST_VERSIONED,
+		HttpQueueSendRequestSchema,
+		(json: HttpQueueSendRequestJson) => json,
+		(bare: protocol.HttpQueueSendRequest) => ({
+			name: bare.name ?? undefined,
+			body: cbor.decode(new Uint8Array(bare.body)),
+			wait: bare.wait ?? undefined,
+			timeout:
+				bare.timeout !== null && bare.timeout !== undefined
+					? Number(bare.timeout)
+					: undefined,
+		}),
+	);
+
+	const name = queueName ?? request.name;
+	if (!name) {
+		throw new errors.InvalidRequest("missing queue name");
+	}
+
+	const actor = await actorDriver.loadActor(actorId);
+	if (!hasSchemaConfigKey(actor.config.queues, name)) {
+		actor.rLog.warn({
+			msg: "ignoring incoming queue message for undefined queue",
+			queueName: name,
+			hasQueueConfig: actor.config.queues !== undefined,
+		});
+		const ignoredResponse = serializeWithEncoding(
+			encoding,
+			{ status: "completed" as const, response: undefined },
+			HTTP_QUEUE_SEND_RESPONSE_VERSIONED,
+			CLIENT_PROTOCOL_CURRENT_VERSION,
+			HttpQueueSendResponseSchema,
+			(value): HttpQueueSendResponseJson => ({
+				status: value.status,
+				response: value.response,
+			}),
+			(value): protocol.HttpQueueSendResponse => ({
+				status: value.status,
+				response:
+					value.response !== undefined
+						? bufferToArrayBuffer(cbor.encode(value.response))
+						: null,
+			}),
+		);
+		return c.body(ignoredResponse as Uint8Array as any, 200, {
+			"Content-Type": contentTypeForEncoding(encoding),
+		});
+	}
+
+	const conn = await actor.connectionManager.prepareAndConnectConn(
+		createHttpDriver(),
+		params,
+		c.req.raw,
+		c.req.path,
+		c.req.header(),
+	);
+	let result: { status: "completed" | "timedOut"; response?: unknown } = {
+		status: "completed",
+	};
+	try {
+		const ctx = new ActionContext(actor, conn);
+		await actor.assertCanPublish(ctx, name);
+
+		if (request.wait) {
+			result = await actor.queueManager.enqueueAndWait(
+				name,
+				request.body,
+				request.timeout,
+			);
+		} else {
+			await actor.queueManager.enqueue(name, request.body);
+		}
+	} finally {
+		conn.disconnect();
+	}
+
+	const response = serializeWithEncoding(
+		encoding,
+		result,
+		HTTP_QUEUE_SEND_RESPONSE_VERSIONED,
+		CLIENT_PROTOCOL_CURRENT_VERSION,
+		HttpQueueSendResponseSchema,
+		(value): HttpQueueSendResponseJson => ({
+			status: value.status,
+			response: value.response,
+		}),
+		(value): protocol.HttpQueueSendResponse => ({
+			status: value.status,
+			response:
+				value.response !== undefined
+					? bufferToArrayBuffer(cbor.encode(value.response))
+					: null,
+		}),
+	);
+
+	return c.body(response as Uint8Array as any, 200, {
+		"Content-Type": contentTypeForEncoding(encoding),
+	});
+}
+
 export async function handleRawRequest(
 	c: HonoContext,
 	req: Request,

package/src/actor/router-websocket-endpoints.ts

@@ -86,7 +86,7 @@ export async function routeWebSocket(
 		});
 
 		// Promise used to wait for the websocket close in `disconnect`
-		const closePromiseResolvers = promiseWithResolvers<void>();
+		const closePromiseResolvers = promiseWithResolvers<void>((reason) => loggerWithoutContext().warn({ msg: "unhandled websocket close promise rejection", reason }));
 
 		// Strip query parameters from requestPath for routing purposes.
 		// This handles paths like "/websocket?query=value" which should route
@@ -188,13 +188,13 @@ export async function routeWebSocket(
 		return {
 			conn: createdConn!,
 			onOpen: (_evt: any, ws: WSContext) => {
-				ws.close(1011, code);
+				ws.close(1011, `${group}.${code}`);
 			},
 			onMessage: (_evt: { data: any }, ws: WSContext) => {
 				ws.close(1011, "actor.not_loaded");
 			},
-			onClose: (_event: any, _ws: WSContext) => {},
-			onError: (_error: unknown) => {},
+			onClose: (_event: any, _ws: WSContext) => { },
+			onError: (_error: unknown) => { },
 		};
 	}
 }
@@ -213,6 +213,10 @@ export async function handleWebSocketConnect(
 		exposeInternalError,
 	}: WebSocketHandlerOpts,
 ): Promise<UpgradeWebSocketArgs> {
+	// Process WS messages in order to avoid races between subscription updates
+	// and subsequent action requests.
+	let pendingMessage = Promise.resolve();
+
 	return {
 		conn,
 		actor,
@@ -230,33 +234,18 @@ export async function handleWebSocketConnect(
 			actor.connectionManager.connectConn(conn);
 		},
 		onMessage: (evt: RivetMessageEvent, ws: WSContext) => {
-			// Handle message asynchronously
 			actor.rLog.debug({ msg: "received message" });
-
 			const value = evt.data.valueOf() as InputData;
-			parseMessage(value, {
-				encoding: encoding,
-				maxIncomingMessageSize: runConfig.maxIncomingMessageSize,
-			})
-				.then((message) => {
-					actor.processMessage(message, conn).catch((error) => {
-						const { code } = deconstructError(
-							error,
-							actor.rLog,
-							{
-								wsEvent: "message",
-							},
-							exposeInternalError,
-						);
-						ws.close(1011, code);
+			pendingMessage = pendingMessage
+				.then(async () => {
+					const message = await parseMessage(value, {
+						encoding: encoding,
+						maxIncomingMessageSize: runConfig.maxIncomingMessageSize,
 					});
+					await actor.processMessage(message, conn);
 				})
 				.catch((error) => {
-					// Close connection on parse errors (including incoming message too large).
-					// This is fail-fast behavior: we cannot send an error response for a
-					// message we couldn't parse (no actionId), and skipping the message
-					// could cause request/response ordering corruption.
-					const { code } = deconstructError(
+					const { group, code } = deconstructError(
 						error,
 						actor.rLog,
 						{
@@ -264,7 +253,7 @@ export async function handleWebSocketConnect(
 						},
 						exposeInternalError,
 					);
-					ws.close(1011, code);
+					ws.close(1011, `${group}.${code}`);
 				});
 		},
 		onClose: (
@@ -350,7 +339,7 @@ export async function handleRawWebSocket(
 		},
 		// Raw websocket messages are handled directly by the actor's event
 		// listeners on the WebSocket object, not through this callback
-		onMessage: (_evt: any, _ws: any) => {},
+		onMessage: (_evt: any, _ws: any) => { },
 		onClose: (evt: any, ws: any) => {
 			// Resolve the close promise
 			closePromiseResolvers.resolve();
@@ -358,7 +347,7 @@ export async function handleRawWebSocket(
 			// Clean up the connection
 			conn.disconnect(evt?.reason);
 		},
-		onError: (error: any, ws: any) => {},
+		onError: (error: any, ws: any) => { },
 	};
 }
 

package/src/actor/router.ts

@@ -4,8 +4,10 @@ import {
 	type ActionOutput,
 	type ConnsMessageOpts,
 	handleAction,
+	handleQueueSend,
 	handleRawRequest,
 } from "@/actor/router-endpoints";
+
 import {
 	PATH_CONNECT,
 	PATH_INSPECTOR_CONNECT,
@@ -17,6 +19,9 @@ import {
 	loggerMiddleware,
 } from "@/common/router";
 import { noopNext } from "@/common/utils";
+import { inspectorLogger } from "@/inspector/log";
+import { timingSafeEqual } from "@/utils/crypto";
+import { getNodeEnv } from "@/utils/env-vars";
 
 import type { RegistryConfig } from "@/registry/config";
 import { type GetUpgradeWebSocket, VERSION } from "@/utils";
@@ -158,12 +163,184 @@ export function createActorRouter(
 		);
 	}
 
+	// Inspector HTTP endpoints for agent-based debugging
+	if (config.inspector.enabled) {
+		// Auth middleware for inspector routes
+		const inspectorAuth = async (c: any): Promise<Response | undefined> => {
+			if (getNodeEnv() === "development" && !config.inspector.token()) {
+				inspectorLogger().warn({
+					msg: "RIVET_INSPECTOR_TOKEN is not set, skipping inspector auth in development mode",
+				});
+				return undefined;
+			}
+
+			const userToken = c.req.header("Authorization")?.replace("Bearer ", "");
+			if (!userToken) {
+				return c.text("Unauthorized", 401);
+			}
+
+			const inspectorToken = config.inspector.token();
+			if (!inspectorToken) {
+				return c.text("Unauthorized", 401);
+			}
+
+			if (!timingSafeEqual(userToken, inspectorToken)) {
+				return c.text("Unauthorized", 401);
+			}
+
+			return undefined;
+		};
+
+		router.get("/inspector/state", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const isStateEnabled = actor.inspector.isStateEnabled();
+			const state = isStateEnabled ? actor.inspector.getStateJson() : undefined;
+			return c.json({ state, isStateEnabled });
+		});
+
+		router.patch("/inspector/state", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const body = await c.req.json<{ state: unknown }>();
+			await actor.inspector.setStateJson(body.state);
+			return c.json({ ok: true });
+		});
+
+		router.get("/inspector/connections", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const connections = actor.inspector.getConnectionsJson();
+			return c.json({ connections });
+		});
+
+		router.get("/inspector/rpcs", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const rpcs = actor.inspector.getRpcs();
+			return c.json({ rpcs });
+		});
+
+		router.post("/inspector/action/:name", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const name = c.req.param("name");
+			const body = await c.req.json<{ args: unknown[] }>();
+			const output = await actor.inspector.executeActionJson(
+				name,
+				body.args ?? [],
+			);
+			return c.json({ output });
+		});
+
+		router.get("/inspector/queue", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const limit = parseInt(c.req.query("limit") ?? "50", 10);
+			const status = await actor.inspector.getQueueStatusJson(limit);
+			return c.json(status);
+		});
+
+		router.get("/inspector/traces", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const startMs = parseInt(c.req.query("startMs") ?? "0", 10);
+			const endMs = parseInt(
+				c.req.query("endMs") ?? String(Date.now()),
+				10,
+			);
+			const limit = parseInt(c.req.query("limit") ?? "1000", 10);
+
+			await actor.traces.flush();
+			const result = await actor.inspector.getTracesJson({
+				startMs,
+				endMs,
+				limit,
+			});
+			return c.json(result);
+		});
+
+		router.get("/inspector/workflow-history", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+			const result = actor.inspector.getWorkflowHistoryJson();
+			return c.json(result);
+		});
+
+		router.get("/inspector/summary", async (c) => {
+			const authResponse = await inspectorAuth(c);
+			if (authResponse) return authResponse;
+
+			const actor = await actorDriver.loadActor(c.env.actorId);
+
+			const isStateEnabled = actor.inspector.isStateEnabled();
+			const isDatabaseEnabled = actor.inspector.isDatabaseEnabled();
+			const isWorkflowEnabled = actor.inspector.isWorkflowEnabled();
+
+			const state = isStateEnabled
+				? actor.inspector.getStateJson()
+				: undefined;
+			const connections = actor.inspector.getConnectionsJson();
+			const rpcs = actor.inspector.getRpcs();
+			const queueSize = actor.inspector.getQueueSize();
+			const workflowHistory = actor.inspector.getWorkflowHistory();
+
+			// Convert BigInt values in workflow history to numbers for JSON serialization.
+			const bigIntReplacer = (_key: string, value: unknown) =>
+				typeof value === "bigint" ? Number(value) : value;
+			const safeWorkflowHistory = workflowHistory
+				? JSON.parse(JSON.stringify(workflowHistory, bigIntReplacer))
+				: null;
+
+			return c.json({
+				state,
+				connections,
+				rpcs,
+				queueSize,
+				isStateEnabled,
+				isDatabaseEnabled,
+				isWorkflowEnabled,
+				workflowHistory: safeWorkflowHistory,
+			});
+		});
+	}
+
 	router.post("/action/:action", async (c) => {
 		const actionName = c.req.param("action");
 
 		return handleAction(c, config, actorDriver, actionName, c.env.actorId);
 	});
 
+	router.post("/queue", async (c) => {
+		return handleQueueSend(c, config, actorDriver, c.env.actorId);
+	});
+
+	router.post("/queue/:name", async (c) => {
+		return handleQueueSend(
+			c,
+			config,
+			actorDriver,
+			c.env.actorId,
+			c.req.param("name"),
+		);
+	});
+
 	router.all("/request/*", async (c) => {
 		// TODO: This is not a clean way of doing this since `/http/` might exist mid-path
 		// Strip the /http prefix from the URL to get the original path