rivetkit 2.0.24-rc.1 → 2.0.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rivetkit",
-  "version": "2.0.24-rc.1",
+  "version": "2.0.24",
   "description": "Lightweight libraries for building stateful actors on edge platforms",
   "license": "Apache-2.0",
   "keywords": [
@@ -165,24 +165,26 @@
     "pino": "^9.5.0",
     "uuid": "^12.0.0",
     "zod": "^3.25.76",
-    "@rivetkit/engine-runner": "2.0.24-rc.1"
+    "@rivetkit/engine-runner": "2.0.24"
   },
   "devDependencies": {
     "@bare-ts/tools": "^0.13.0",
+    "@biomejs/biome": "^2.2.3",
     "@hono/node-server": "^1.18.2",
     "@hono/node-ws": "^1.1.1",
     "@types/invariant": "^2",
     "@types/node": "^22.13.1",
     "@types/ws": "^8",
     "@vitest/ui": "3.1.1",
-    "bundle-require": "^5.1.0",
     "commander": "^12.1.0",
     "eventsource": "^4.0.0",
     "tsup": "^8.4.0",
     "tsx": "^4.19.4",
     "typescript": "^5.7.3",
+    "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.1.1",
-    "ws": "^8.18.1"
+    "ws": "^8.18.1",
+    "zod-to-json-schema": "^3.24.6"
   },
   "peerDependencies": {
     "@hono/node-server": "^1.14.0",
@@ -207,10 +209,15 @@
   "stableVersion": "0.8.0",
   "scripts": {
     "build": "tsup src/mod.ts src/client/mod.ts src/common/log.ts src/common/websocket.ts src/actor/errors.ts src/topologies/coordinate/mod.ts src/topologies/partition/mod.ts src/utils.ts src/driver-helpers/mod.ts src/driver-test-suite/mod.ts src/test/mod.ts src/inspector/mod.ts",
-    "build:schema": "./scripts/compile-bare.ts compile schemas/client-protocol/v1.bare -o dist/schemas/client-protocol/v1.ts && ./scripts/compile-bare.ts compile schemas/file-system-driver/v1.bare -o dist/schemas/file-system-driver/v1.ts && ./scripts/compile-bare.ts compile schemas/actor-persist/v1.bare -o dist/schemas/actor-persist/v1.ts && ./scripts/compile-bare.ts compile schemas/actor-persist/v2.bare -o dist/schemas/actor-persist/v2.ts",
+    "build:schema": "./scripts/compile-bare.ts compile schemas/client-protocol/v1.bare -o dist/schemas/client-protocol/v1.ts && ./scripts/compile-bare.ts compile schemas/client-protocol/v2.bare -o dist/schemas/client-protocol/v2.ts && ./scripts/compile-bare.ts compile schemas/file-system-driver/v1.bare -o dist/schemas/file-system-driver/v1.ts && ./scripts/compile-bare.ts compile schemas/file-system-driver/v2.bare -o dist/schemas/file-system-driver/v2.ts && ./scripts/compile-bare.ts compile schemas/actor-persist/v1.bare -o dist/schemas/actor-persist/v1.ts && ./scripts/compile-bare.ts compile schemas/actor-persist/v2.bare -o dist/schemas/actor-persist/v2.ts && ./scripts/compile-bare.ts compile schemas/actor-persist/v3.bare -o dist/schemas/actor-persist/v3.ts",
     "check-types": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format .",
+    "format:write": "biome format --write .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "dump-openapi": "tsx scripts/dump-openapi.ts"
+    "dump-openapi": "tsx scripts/dump-openapi.ts",
+    "dump-asyncapi": "tsx scripts/dump-asyncapi.ts"
   }
 }

package/src/actor/config.ts

@@ -1,8 +1,13 @@
 import { z } from "zod";
 import type { UniversalWebSocket } from "@/common/websocket-interface";
-import type { ActionContext } from "./action";
-import type { Conn } from "./conn";
-import type { ActorContext } from "./context";
+import type { Conn } from "./conn/mod";
+import type { ActionContext } from "./contexts/action";
+import type { ActorContext } from "./contexts/actor";
+import type { CreateConnStateContext } from "./contexts/create-conn-state";
+import type { OnBeforeConnectContext } from "./contexts/on-before-connect";
+import type { OnConnectContext } from "./contexts/on-connect";
+import type { RequestContext } from "./contexts/request";
+import type { WebSocketContext } from "./contexts/websocket";
 import type { AnyDatabaseProvider } from "./database";
 
 export type InitContext = ActorContext<
@@ -38,14 +43,15 @@ export interface ActorTypes<
 export const ActorConfigSchema = z
 	.object({
 		onCreate: z.function().optional(),
-		onStart: z.function().optional(),
-		onStop: z.function().optional(),
+		onDestroy: z.function().optional(),
+		onWake: z.function().optional(),
+		onSleep: z.function().optional(),
 		onStateChange: z.function().optional(),
 		onBeforeConnect: z.function().optional(),
 		onConnect: z.function().optional(),
 		onDisconnect: z.function().optional(),
 		onBeforeActionResponse: z.function().optional(),
-		onFetch: z.function().optional(),
+		onRequest: z.function().optional(),
 		onWebSocket: z.function().optional(),
 		actions: z.record(z.function()).default({}),
 		state: z.any().optional(),
@@ -61,7 +67,8 @@ export const ActorConfigSchema = z
 				createConnStateTimeout: z.number().positive().default(5000),
 				onConnectTimeout: z.number().positive().default(5000),
 				// This must be less than ACTOR_STOP_THRESHOLD_MS
-				onStopTimeout: z.number().positive().default(5000),
+				onSleepTimeout: z.number().positive().default(5000),
+				onDestroyTimeout: z.number().positive().default(5000),
 				stateSaveInterval: z.number().positive().default(10_000),
 				actionTimeout: z.number().positive().default(60_000),
 				// Max time to wait for waitUntil background promises during shutdown
@@ -70,8 +77,14 @@ export const ActorConfigSchema = z
 				connectionLivenessInterval: z.number().positive().default(5000),
 				noSleep: z.boolean().default(false),
 				sleepTimeout: z.number().positive().default(30_000),
-				/** @experimental */
-				canHibernatWebSocket: z
+				/**
+				 * Can hibernate WebSockets for onWebSocket.
+				 *
+				 * WebSockets using actions/events are hibernatable by default.
+				 *
+				 * @experimental
+				 **/
+				canHibernateWebSocket: z
 					.union([
 						z.boolean(),
 						z
@@ -111,15 +124,6 @@ export const ActorConfigSchema = z
 		},
 	);
 
-export interface OnConnectOptions {
-	/**
-	 * The request object associated with the connection.
-	 *
-	 * @experimental
-	 */
-	request?: Request;
-}
-
 // Creates state config
 //
 // This must have only one or the other or else TState will not be able to be inferred
@@ -146,13 +150,12 @@ type CreateConnState<
 	TConnState,
 	TVars,
 	TInput,
-	TDatabase,
+	TDatabase extends AnyDatabaseProvider,
 > =
 	| { connState: TConnState }
 	| {
 			createConnState: (
-				c: InitContext,
-				opts: OnConnectOptions,
+				c: CreateConnStateContext<TState, TVars, TInput, TDatabase>,
 				params: TConnParams,
 			) => TConnState | Promise<TConnState>;
 	  }
@@ -247,6 +250,20 @@ interface BaseActorConfig<
 		input: TInput,
 	) => void | Promise<void>;
 
+	/**
+	 * Called when the actor is destroyed.
+	 */
+	onDestroy?: (
+		c: ActorContext<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase
+		>,
+	) => void | Promise<void>;
+
 	/**
 	 * Called when the actor is started and ready to receive connections and action.
 	 *
@@ -255,7 +272,7 @@ interface BaseActorConfig<
 	 *
 	 * @returns Void or a Promise that resolves when startup is complete
 	 */
-	onStart?: (
+	onWake?: (
 		c: ActorContext<
 			TState,
 			TConnParams,
@@ -276,7 +293,7 @@ interface BaseActorConfig<
 	 *
 	 * @returns Void or a Promise that resolves when shutdown is complete
 	 */
-	onStop?: (
+	onSleep?: (
 		c: ActorContext<
 			TState,
 			TConnParams,
@@ -321,15 +338,7 @@ interface BaseActorConfig<
 	 * @throws Throw an error to reject the connection
 	 */
 	onBeforeConnect?: (
-		c: ActorContext<
-			TState,
-			TConnParams,
-			TConnState,
-			TVars,
-			TInput,
-			TDatabase
-		>,
-		opts: OnConnectOptions,
+		c: OnBeforeConnectContext<TState, TVars, TInput, TDatabase>,
 		params: TConnParams,
 	) => void | Promise<void>;
 
@@ -343,7 +352,7 @@ interface BaseActorConfig<
 	 * @returns Void or a Promise that resolves when connection handling is complete
 	 */
 	onConnect?: (
-		c: ActorContext<
+		c: OnConnectContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -407,11 +416,13 @@ interface BaseActorConfig<
 	 * This handler receives raw HTTP requests made to `/actors/{actorName}/http/*` endpoints.
 	 * Use this hook to handle custom HTTP patterns, REST APIs, or other HTTP-based protocols.
 	 *
+	 * @param c The request context with access to the connection
 	 * @param request The raw HTTP request object
+	 * @param opts Additional options
 	 * @returns A Response object to send back, or void to continue with default routing
 	 */
-	onFetch?: (
-		c: ActorContext<
+	onRequest?: (
+		c: RequestContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -420,7 +431,6 @@ interface BaseActorConfig<
 			TDatabase
 		>,
 		request: Request,
-		opts: {},
 	) => Response | Promise<Response>;
 
 	/**
@@ -429,11 +439,12 @@ interface BaseActorConfig<
 	 * This handler receives WebSocket connections made to `/actors/{actorName}/websocket/*` endpoints.
 	 * Use this hook to handle custom WebSocket protocols, binary streams, or other WebSocket-based communication.
 	 *
+	 * @param c The WebSocket context with access to the connection
 	 * @param websocket The raw WebSocket connection
-	 * @param request The original HTTP upgrade request
+	 * @param opts Additional options including the original HTTP upgrade request
 	 */
 	onWebSocket?: (
-		c: ActorContext<
+		c: WebSocketContext<
 			TState,
 			TConnParams,
 			TConnState,
@@ -442,7 +453,6 @@ interface BaseActorConfig<
 			TDatabase
 		>,
 		websocket: UniversalWebSocket,
-		opts: { request: Request },
 	) => void | Promise<void>;
 
 	actions: TActions;
@@ -471,13 +481,14 @@ export type ActorConfig<
 	z.infer<typeof ActorConfigSchema>,
 	| "actions"
 	| "onCreate"
-	| "onStart"
+	| "onDestroy"
+	| "onWake"
 	| "onStateChange"
 	| "onBeforeConnect"
 	| "onConnect"
 	| "onDisconnect"
 	| "onBeforeActionResponse"
-	| "onFetch"
+	| "onRequest"
 	| "onWebSocket"
 	| "state"
 	| "createState"
@@ -530,14 +541,15 @@ export type ActorConfigInput<
 	z.input<typeof ActorConfigSchema>,
 	| "actions"
 	| "onCreate"
-	| "onStart"
-	| "onStop"
+	| "onDestroy"
+	| "onWake"
+	| "onSleep"
 	| "onStateChange"
 	| "onBeforeConnect"
 	| "onConnect"
 	| "onDisconnect"
 	| "onBeforeActionResponse"
-	| "onFetch"
+	| "onRequest"
 	| "onWebSocket"
 	| "state"
 	| "createState"

package/src/actor/conn/driver.ts

@@ -0,0 +1,61 @@
+import type { AnyConn } from "@/actor/conn/mod";
+import type { AnyActorInstance } from "@/actor/instance/mod";
+import type { CachedSerializer } from "@/actor/protocol/serde";
+
+export enum DriverReadyState {
+	UNKNOWN = -1,
+	CONNECTING = 0,
+	OPEN = 1,
+	CLOSING = 2,
+	CLOSED = 3,
+}
+
+export interface ConnDriver {
+	/** The type of driver. Used for debug purposes only. */
+	type: string;
+
+	/**
+	 * If defined, this connection driver talks the RivetKit client driver (see
+	 * schemas/client-protocol/).
+	 *
+	 * If enabled, events like `Init`, subscription events, etc. will be sent
+	 * to this connection.
+	 */
+	rivetKitProtocol?: {
+		/** Sends a RivetKit client message. */
+		sendMessage(
+			actor: AnyActorInstance,
+			conn: AnyConn,
+			message: CachedSerializer<any, any, any>,
+		): void;
+	};
+
+	/**
+	 * If the connection can be hibernated. If true, this will allow the actor to go to sleep while the connection is still active.
+	 **/
+	hibernatable?: {
+		gatewayId: ArrayBuffer;
+		requestId: ArrayBuffer;
+	};
+
+	/**
+	 * This returns a promise since we commonly disconnect at the end of a program, and not waiting will cause the socket to not close cleanly.
+	 */
+	disconnect(
+		actor: AnyActorInstance,
+		conn: AnyConn,
+		reason?: string,
+	): Promise<void>;
+
+	/** Terminates the connection without graceful handling. */
+	terminate?(actor: AnyActorInstance, conn: AnyConn): void;
+
+	/**
+	 * Returns the ready state of the connection.
+	 * This is used to determine if the connection is ready to send messages, or if the connection is stale.
+	 */
+	getConnectionReadyState(
+		actor: AnyActorInstance,
+		conn: AnyConn,
+	): DriverReadyState | undefined;
+}

package/src/actor/conn/drivers/http.ts

@@ -0,0 +1,17 @@
+import { type ConnDriver, DriverReadyState } from "../driver";
+
+export type ConnHttpState = Record<never, never>;
+
+export function createHttpDriver(): ConnDriver {
+	return {
+		type: "http",
+		getConnectionReadyState(_actor, _conn) {
+			// TODO: This might not be the correct logic
+			return DriverReadyState.OPEN;
+		},
+		disconnect: async () => {
+			// Noop
+			// TODO: Configure with abort signals to abort the request
+		},
+	};
+}

package/src/actor/conn/drivers/raw-request.ts

@@ -0,0 +1,24 @@
+import type { ConnDriver } from "../driver";
+import { DriverReadyState } from "../driver";
+
+/**
+ * Creates a raw HTTP connection driver.
+ *
+ * This driver is used for raw HTTP connections that don't use the RivetKit protocol.
+ * Unlike the standard HTTP driver, this provides connection lifecycle management
+ * for tracking the HTTP request through the actor's onRequest handler.
+ */
+export function createRawRequestDriver(): ConnDriver {
+	return {
+		type: "raw-request",
+
+		disconnect: async () => {
+			// Noop
+		},
+
+		getConnectionReadyState: (): DriverReadyState | undefined => {
+			// HTTP connections are always considered open until the request completes
+			return DriverReadyState.OPEN;
+		},
+	};
+}

package/src/actor/conn/drivers/raw-websocket.ts

@@ -0,0 +1,65 @@
+import type { AnyConn } from "@/actor/conn/mod";
+import type { AnyActorInstance } from "@/actor/instance/mod";
+import type { UniversalWebSocket } from "@/common/websocket-interface";
+import { loggerWithoutContext } from "../../log";
+import { type ConnDriver, DriverReadyState } from "../driver";
+
+/**
+ * Creates a raw WebSocket connection driver.
+ *
+ * This driver is used for raw WebSocket connections that don't use the RivetKit protocol.
+ * Unlike the standard WebSocket driver, this doesn't have sendMessage since raw WebSockets
+ * don't handle messages from the RivetKit protocol - they handle messages directly in the
+ * actor's onWebSocket handler.
+ */
+export function createRawWebSocketDriver(
+	hibernatable: ConnDriver['hibernatable'],
+	closePromise: Promise<void>,
+): { driver: ConnDriver; setWebSocket(ws: UniversalWebSocket): void } {
+	let websocket: UniversalWebSocket | undefined;
+
+	const driver: ConnDriver = {
+		type: "raw-websocket",
+		hibernatable,
+
+		// No sendMessage implementation since this is a raw WebSocket that doesn't
+		// handle messages from the RivetKit protocol
+
+		disconnect: async (
+			_actor: AnyActorInstance,
+			_conn: AnyConn,
+			reason?: string,
+		) => {
+			if (!websocket) {
+				loggerWithoutContext().warn(
+					"disconnecting raw ws without websocket",
+				);
+				return;
+			}
+
+			// Close socket
+			websocket.close(1000, reason);
+
+			// Wait for socket to close gracefully
+			await closePromise;
+		},
+
+		terminate: () => {
+			(websocket as any)?.terminate?.();
+		},
+
+		getConnectionReadyState: (
+			_actor: AnyActorInstance,
+			_conn: AnyConn,
+		): DriverReadyState | undefined => {
+			return websocket?.readyState ?? DriverReadyState.CONNECTING;
+		},
+	};
+
+	return {
+		driver,
+		setWebSocket(ws) {
+			websocket = ws;
+		},
+	};
+}

package/src/actor/conn/drivers/websocket.ts

@@ -0,0 +1,129 @@
+import type { WSContext } from "hono/ws";
+import type { AnyConn } from "@/actor/conn/mod";
+import type { AnyActorInstance } from "@/actor/instance/mod";
+import type { CachedSerializer, Encoding } from "@/actor/protocol/serde";
+import { loggerWithoutContext } from "../../log";
+import { type ConnDriver, DriverReadyState } from "../driver";
+
+export type ConnDriverWebSocketState = Record<never, never>;
+
+export function createWebSocketDriver(
+	hibernatable: ConnDriver['hibernatable'],
+	encoding: Encoding,
+	closePromise: Promise<void>,
+): { driver: ConnDriver; setWebSocket(ws: WSContext): void } {
+	loggerWithoutContext().debug({
+		msg: "createWebSocketDriver creating driver",
+		hibernatable,
+	});
+	// Wait for WS to open
+	let websocket: WSContext | undefined;
+
+	const driver: ConnDriver = {
+		type: "websocket",
+		hibernatable,
+		rivetKitProtocol: {
+			sendMessage: (
+				actor: AnyActorInstance,
+				conn: AnyConn,
+				message: CachedSerializer<any, any, any>,
+			) => {
+				if (!websocket) {
+					actor.rLog.warn({
+						msg: "websocket not open",
+						connId: conn.id,
+					});
+					return;
+				}
+				if (websocket.readyState !== DriverReadyState.OPEN) {
+					actor.rLog.warn({
+						msg: "attempting to send message to closed websocket, this is likely a bug in RivetKit",
+						connId: conn.id,
+						wsReadyState: websocket.readyState,
+					});
+					return;
+				}
+
+				const serialized = message.serialize(encoding);
+
+				actor.rLog.debug({
+					msg: "sending websocket message",
+					encoding: encoding,
+					dataType: typeof serialized,
+					isUint8Array: serialized instanceof Uint8Array,
+					isArrayBuffer: serialized instanceof ArrayBuffer,
+					dataLength:
+						(serialized as any).byteLength ||
+						(serialized as any).length,
+				});
+
+				// Convert Uint8Array to ArrayBuffer for proper transmission
+				if (serialized instanceof Uint8Array) {
+					const buffer = serialized.buffer.slice(
+						serialized.byteOffset,
+						serialized.byteOffset + serialized.byteLength,
+					);
+					// Handle SharedArrayBuffer case
+					if (buffer instanceof SharedArrayBuffer) {
+						const arrayBuffer = new ArrayBuffer(buffer.byteLength);
+						new Uint8Array(arrayBuffer).set(new Uint8Array(buffer));
+						actor.rLog.debug({
+							msg: "converted SharedArrayBuffer to ArrayBuffer",
+							byteLength: arrayBuffer.byteLength,
+						});
+						websocket.send(arrayBuffer);
+					} else {
+						actor.rLog.debug({
+							msg: "sending ArrayBuffer",
+							byteLength: buffer.byteLength,
+						});
+						websocket.send(buffer);
+					}
+				} else {
+					actor.rLog.debug({
+						msg: "sending string data",
+						length: (serialized as string).length,
+					});
+					websocket.send(serialized);
+				}
+			},
+		},
+
+		disconnect: async (
+			_actor: AnyActorInstance,
+			_conn: AnyConn,
+			reason?: string,
+		) => {
+			if (!websocket) {
+				loggerWithoutContext().warn(
+					"disconnecting ws without websocket",
+				);
+				return;
+			}
+
+			// Close socket
+			websocket.close(1000, reason);
+
+			// Create promise to wait for socket to close gracefully
+			await closePromise;
+		},
+
+		terminate: () => {
+			(websocket as any).terminate();
+		},
+
+		getConnectionReadyState: (
+			_actor: AnyActorInstance,
+			_conn: AnyConn,
+		): DriverReadyState | undefined => {
+			return websocket?.readyState ?? DriverReadyState.CONNECTING;
+		},
+	};
+
+	return {
+		driver,
+		setWebSocket(ws) {
+			websocket = ws;
+		},
+	};
+}