rivetkit 2.3.0-rc.9 → 2.3.1

package/src/common/router.ts

@@ -1,17 +1,11 @@
-import type { Context as HonoContext, Next } from "hono";
 import * as envoyProtocol from "@rivetkit/engine-envoy-protocol";
+import type { Context as HonoContext, Next } from "hono";
 import type { ActorSpecifier } from "@/actor/errors";
 import {
 	HEADER_ACTOR_GENERATION,
 	HEADER_ACTOR_ID,
 	HEADER_ACTOR_KEY,
 } from "@/common/actor-router-consts";
-import type { Encoding } from "@/common/encoding";
-import {
-	getRequestEncoding,
-	getRequestExposeInternalError,
-} from "@/common/router-request";
-import { buildActorNames, type RegistryConfig } from "@/registry/config";
 import type * as protocol from "@/common/client-protocol";
 import {
 	CURRENT_VERSION as CLIENT_PROTOCOL_CURRENT_VERSION,
@@ -21,15 +15,17 @@ import {
 	type HttpResponseError as HttpResponseErrorJson,
 	HttpResponseErrorSchema,
 } from "@/common/client-protocol-zod";
+import type { Encoding, JsonCompatValue } from "@/common/encoding";
 import {
-	encodeCborCompat,
-	encodingIsBinary,
-	serializeWithEncoding,
-} from "@/serde";
+	getRequestEncoding,
+	getRequestExposeInternalError,
+} from "@/common/router-request";
+import { buildActorNames, type RegistryConfig } from "@/registry/config";
+import { encodeCborCompat, serializeWithEncoding } from "@/serde";
 import { bufferToArrayBuffer, VERSION } from "@/utils";
 import { getLogHeaders } from "@/utils/env-vars";
 import { getLogger, type Logger } from "./log";
-import { deconstructError, stringifyError } from "./utils";
+import { deconstructError } from "./utils";
 
 export function logger() {
 	return getLogger("router");
@@ -67,10 +63,8 @@ export function handleRouteNotFound(c: HonoContext) {
 export function handleRouteError(error: unknown, c: HonoContext) {
 	const exposeInternalError = getRequestExposeInternalError(c.req.raw);
 
-	const { statusCode, group, code, message, metadata, actor } = deconstructError(
-		error,
-		exposeInternalError,
-	);
+	const { statusCode, group, code, message, metadata, actor } =
+		deconstructError(error, exposeInternalError);
 
 	if (actor) {
 		logger().warn({
@@ -111,7 +105,9 @@ export function handleRouteError(error: unknown, c: HonoContext) {
 			code: value.code,
 			message: value.message,
 			metadata: value.metadata
-				? bufferToArrayBuffer(encodeCborCompat(value.metadata))
+				? bufferToArrayBuffer(
+						encodeCborCompat(value.metadata as JsonCompatValue),
+					)
 				: null,
 			actor: value.actor
 				? {

package/src/common/utils.ts

@@ -36,155 +36,6 @@ export function safeStringify(obj: unknown, maxSize: number) {
 	return JSON.stringify(obj, replacer);
 }
 
-// TODO: Instead of doing this, use a temp var for state and attempt to write
-// it. Roll back state if fails to serialize.
-
-/**
- * Check if a value is CBOR serializable.
- * Optionally pass an onInvalid callback to receive the path to invalid values.
- *
- * For a complete list of supported CBOR tags, see:
- * https://github.com/kriszyp/cbor-x/blob/cc1cf9df8ba72288c7842af1dd374d73e34cdbc1/README.md#list-of-supported-tags-for-decoding
- */
-export function isCborSerializable(
-	value: unknown,
-	onInvalid?: (path: string) => void,
-	currentPath = "",
-): boolean {
-	// Handle primitive types directly
-	if (value === null || value === undefined) {
-		return true;
-	}
-
-	if (typeof value === "number") {
-		if (!Number.isFinite(value)) {
-			onInvalid?.(currentPath);
-			return false;
-		}
-		return true;
-	}
-
-	if (typeof value === "boolean" || typeof value === "string") {
-		return true;
-	}
-
-	// Handle BigInt (CBOR tags 2 and 3)
-	if (typeof value === "bigint") {
-		return true;
-	}
-
-	// Handle Date objects (CBOR tags 0 and 1)
-	if (value instanceof Date) {
-		return true;
-	}
-
-	// Handle typed arrays (CBOR tags 64-82)
-	if (
-		value instanceof Uint8Array ||
-		value instanceof Uint8ClampedArray ||
-		value instanceof Uint16Array ||
-		value instanceof Uint32Array ||
-		value instanceof BigUint64Array ||
-		value instanceof Int8Array ||
-		value instanceof Int16Array ||
-		value instanceof Int32Array ||
-		value instanceof BigInt64Array ||
-		value instanceof Float32Array ||
-		value instanceof Float64Array
-	) {
-		return true;
-	}
-
-	// Handle Map (CBOR tag 259)
-	if (value instanceof Map) {
-		for (const [key, val] of value.entries()) {
-			const keyPath = currentPath
-				? `${currentPath}.key(${String(key)})`
-				: `key(${String(key)})`;
-			const valPath = currentPath
-				? `${currentPath}.value(${String(key)})`
-				: `value(${String(key)})`;
-			if (
-				!isCborSerializable(key, onInvalid, keyPath) ||
-				!isCborSerializable(val, onInvalid, valPath)
-			) {
-				return false;
-			}
-		}
-		return true;
-	}
-
-	// Handle Set (CBOR tag 258)
-	if (value instanceof Set) {
-		let index = 0;
-		for (const item of value.values()) {
-			const itemPath = currentPath
-				? `${currentPath}.set[${index}]`
-				: `set[${index}]`;
-			if (!isCborSerializable(item, onInvalid, itemPath)) {
-				return false;
-			}
-			index++;
-		}
-		return true;
-	}
-
-	// Handle RegExp (CBOR tag 27)
-	if (value instanceof RegExp) {
-		return true;
-	}
-
-	// Handle Error objects (CBOR tag 27)
-	if (value instanceof Error) {
-		return true;
-	}
-
-	// Handle arrays
-	if (Array.isArray(value)) {
-		for (let i = 0; i < value.length; i++) {
-			const itemPath = currentPath ? `${currentPath}[${i}]` : `[${i}]`;
-			if (!isCborSerializable(value[i], onInvalid, itemPath)) {
-				return false;
-			}
-		}
-		return true;
-	}
-
-	// Handle plain objects and records (CBOR tags 105, 51, 57344-57599)
-	if (typeof value === "object") {
-		// Allow plain objects and objects with prototypes (for records and named objects)
-		const proto = Object.getPrototypeOf(value);
-		if (proto !== null && proto !== Object.prototype) {
-			// Check if it's a known serializable object type
-			const protoConstructor = value.constructor;
-			if (protoConstructor && typeof protoConstructor.name === "string") {
-				// Allow objects with named constructors (records, named objects)
-				// This includes user-defined classes and built-in objects
-				// that CBOR can serialize with tag 27 or record tags
-			}
-		}
-
-		// Check all properties recursively
-		for (const key in value) {
-			const propPath = currentPath ? `${currentPath}.${key}` : key;
-			if (
-				!isCborSerializable(
-					value[key as keyof typeof value],
-					onInvalid,
-					propPath,
-				)
-			) {
-				return false;
-			}
-		}
-		return true;
-	}
-
-	// Not serializable
-	onInvalid?.(currentPath);
-	return false;
-}
-
 export interface DeconstructedError {
 	__type: "ActorError";
 	statusCode: ContentfulStatusCode;
@@ -283,7 +134,7 @@ export function deconstructError(
 			actor = error.actor;
 		}
 		metadata = {
-			//url: `https://hub.rivet.dev/projects/${actorMetadata.project.slug}/environments/${actorMetadata.environment.slug}/actors?actorId=${actorMetadata.actor.id}`,
+			//url: `https://dashboard.rivet.dev/projects/${actorMetadata.project.slug}/environments/${actorMetadata.environment.slug}/actors?actorId=${actorMetadata.actor.id}`,
 		} satisfies errors.InternalErrorMetadata;
 	}
 

package/src/common/websocket-interface.ts

@@ -1,7 +1,7 @@
 // Re-export everything from the virtual-websocket package
 export type {
+	RivetCloseEvent,
 	RivetEvent,
 	RivetMessageEvent,
-	RivetCloseEvent,
 	UniversalWebSocket,
 } from "@rivetkit/virtual-websocket";

package/src/db/mod.ts

@@ -1,4 +1,3 @@
-export { db } from "@/common/database/mod";
 export type {
 	AnyDatabaseProvider,
 	DatabaseProvider,
@@ -11,3 +10,4 @@ export type {
 	SqliteNativeMetrics,
 	SqliteQueryResult,
 } from "@/common/database/config";
+export { db } from "@/common/database/mod";

package/src/devtools-loader/index.ts

@@ -1,16 +1,11 @@
 import type { ClientConfigInput } from "@/client/client";
-import { VERSION } from "@/utils";
 import { logger } from "./log";
 
 declare global {
 	// Injected via tsup config
-	// biome-ignore lint/style/noVar: required for global declaration
 	var CUSTOM_RIVETKIT_DEVTOOLS_URL: string | undefined;
 }
 
-const DEFAULT_DEVTOOLS_URL = (version = VERSION) =>
-	`https://releases.rivet.dev/rivet/latest/devtools/mod.js?v=${version}`;
-
 const scriptId = "rivetkit-devtools-script";
 
 export function injectDevtools(config: ClientConfigInput) {
@@ -20,10 +15,12 @@ export function injectDevtools(config: ClientConfigInput) {
 	}
 
 	if (!document.getElementById(scriptId)) {
+		const src =
+			globalThis.CUSTOM_RIVETKIT_DEVTOOLS_URL ||
+			`${config.endpoint?.replace(/\/$/, "")}/devtools/mod.js`;
 		const script = document.createElement("script");
 		script.id = scriptId;
-		script.src =
-			globalThis.CUSTOM_RIVETKIT_DEVTOOLS_URL || DEFAULT_DEVTOOLS_URL();
+		script.src = src;
 		script.async = true;
 		document.head.appendChild(script);
 	}

package/src/devtools-loader/serve-devtools.ts

@@ -0,0 +1,26 @@
+import { getNodeFs, getNodePath, getNodeUrl } from "@/utils/node";
+
+export async function getDevtoolsPath(): Promise<string> {
+	const url = getNodeUrl();
+	const path = getNodePath();
+
+	const devtoolsPath = path.join(
+		path.dirname(url.fileURLToPath(import.meta.url)),
+		"../../dist/devtools/mod.js",
+	);
+
+	try {
+		await getNodeFs().access(devtoolsPath);
+	} catch {
+		throw new Error(
+			`Devtools bundle not found at ${devtoolsPath}. Run 'pnpm build:pack-devtools' first.`,
+		);
+	}
+
+	return devtoolsPath;
+}
+
+export async function readDevtoolsBundle(): Promise<Buffer> {
+	const devtoolsPath = await getDevtoolsPath();
+	return getNodeFs().readFile(devtoolsPath);
+}

package/src/drivers/engine/actor-driver.ts

@@ -1,9 +1,9 @@
 import type { EnvoyConfig } from "@rivetkit/rivetkit-native/wrapper";
 import {
-	type HibernatingWebSocketMetadata,
 	type EnvoyHandle,
+	type HibernatingWebSocketMetadata,
 	openDatabaseFromEnvoy,
-	protocol,
+	type protocol,
 	startEnvoySync,
 } from "@rivetkit/rivetkit-native/wrapper";
 import * as cbor from "cbor-x";
@@ -11,17 +11,19 @@ import type { Context as HonoContext } from "hono";
 import { streamSSE } from "hono/streaming";
 import { WSContext, type WSContextInit } from "hono/ws";
 import invariant from "invariant";
-import { type AnyConn, CONN_STATE_MANAGER_SYMBOL } from "@/actor/conn/mod";
+import { CONN_STATE_MANAGER_SYMBOL } from "@/actor/conn/mod";
 import { isStaticActorDefinition, lookupInRegistry } from "@/actor/definition";
+import type { ActorDriver } from "@/actor/driver";
+import { KEYS } from "@/actor/instance/keys";
+import type { AnyActorInstance } from "@/actor/instance/mod";
 import {
-	isStaticActorInstance,
 	type AnyStaticActorInstance,
+	isStaticActorInstance,
 } from "@/actor/instance/mod";
-import { KEYS } from "@/actor/instance/keys";
 import {
-	type PreloadMap,
 	compareBytes,
 	createPreloadMap,
+	type PreloadMap,
 } from "@/actor/instance/preload-map";
 import { deserializeActorKey } from "@/actor/keys";
 import type { Encoding } from "@/actor/protocol/serde";
@@ -41,6 +43,10 @@ import {
 } from "@/common/actor-router-consts";
 import { getLogger } from "@/common/log";
 import { deconstructError } from "@/common/utils";
+import type {
+	RivetMessageEvent,
+	UniversalWebSocket,
+} from "@/common/websocket-interface";
 import {
 	buildHibernatableWebSocketAckStateTestResponse,
 	type IndexedWebSocketPayload,
@@ -49,21 +55,19 @@ import {
 	setHibernatableWebSocketAckTestHooks,
 	unregisterRemoteHibernatableWebSocketAckHooks,
 } from "@/common/websocket-test-hooks";
-import type {
-	RivetMessageEvent,
-	UniversalWebSocket,
-} from "@/common/websocket-interface";
-import type { ActorDriver } from "@/actor/driver";
-import type { AnyActorInstance } from "@/actor/instance/mod";
 import {
-	getInitialActorKvState,
+	type JsNativeDatabaseLike,
+	wrapJsNativeDatabase,
+} from "@/db/native-database";
+import {
 	type EngineControlClient,
+	getInitialActorKvState,
 } from "@/driver-helpers/mod";
 import { DynamicActorInstance } from "@/dynamic/instance";
-import { DynamicActorIsolateRuntime } from "@/dynamic/isolate-runtime";
 import { isDynamicActorDefinition } from "@/dynamic/internal";
-import { buildActorNames, type RegistryConfig } from "@/registry/config";
+import { DynamicActorIsolateRuntime } from "@/dynamic/isolate-runtime";
 import { getEndpoint } from "@/engine-client/api-utils";
+import { buildActorNames, type RegistryConfig } from "@/registry/config";
 import {
 	type LongTimeoutHandle,
 	promiseWithResolvers,
@@ -71,10 +75,6 @@ import {
 	stringifyError,
 	VERSION,
 } from "@/utils";
-import {
-	wrapJsNativeDatabase,
-	type JsNativeDatabaseLike,
-} from "@/db/native-database";
 import { logger } from "./log";
 
 const ENVOY_SSE_PING_INTERVAL = 1000;
@@ -88,13 +88,13 @@ const REMOTE_ACK_HOOK_QUERY_PARAM = "__rivetkitAckHook";
 //
 // See engine/packages/pegboard-gateway/src/shared_state.rs
 // (HWS_MESSAGE_ACK_TIMEOUT)
-const CONN_MESSAGE_ACK_DEADLINE = 5_000;
+const _CONN_MESSAGE_ACK_DEADLINE = 5_000;
 
 // Force saveState when cumulative message size reaches this threshold (0.5 MB)
 //
 // See engine/packages/pegboard-gateway/src/shared_state.rs
 // (HWS_MAX_PENDING_MSGS_SIZE_PER_REQ)
-const CONN_BUFFERED_MESSAGE_SIZE_THRESHOLD = 500_000;
+const _CONN_BUFFERED_MESSAGE_SIZE_THRESHOLD = 500_000;
 
 interface ActorHandler {
 	actor?: AnyActorInstance;
@@ -144,7 +144,6 @@ export type DriverContext = {};
 
 export class EngineActorDriver implements ActorDriver {
 	#config: RegistryConfig;
-	#engineClient: EngineControlClient;
 	#inlineClient: Client<any>;
 	#envoy: EnvoyHandle;
 	#actors: Map<string, ActorHandler> = new Map();
@@ -161,15 +160,6 @@ export class EngineActorDriver implements ActorDriver {
 		string,
 		HibernatableRunnerWebSocketBinding
 	>();
-	#hwsMessageIndex = new Map<
-		string,
-		{
-			serverMessageIndex: number;
-			bufferedMessageSize: number;
-			pendingAckFromMessageIndex: boolean;
-			pendingAckFromBufferSize: boolean;
-		}
-	>();
 	#actorRouter: ActorRouter;
 
 	#envoyStarted: PromiseWithResolvers<void> = promiseWithResolvers((reason) =>
@@ -284,7 +274,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().debug({
 					msg: "actor crash cleanup errored",
 					actorId,
-					err: stringifyError(err),
+					error: stringifyError(err),
 				});
 			}
 		}
@@ -376,8 +366,7 @@ export class EngineActorDriver implements ActorDriver {
 		requestId: ArrayBuffer,
 	): void {
 		const key = this.#hibernatableWebSocketAckKey(gatewayId, requestId);
-		const binding =
-			this.#hibernatableRunnerWebSocketBindings.get(key);
+		const binding = this.#hibernatableRunnerWebSocketBindings.get(key);
 		if (!binding) {
 			return;
 		}
@@ -397,8 +386,7 @@ export class EngineActorDriver implements ActorDriver {
 		requestId: ArrayBuffer,
 	): void {
 		const key = this.#hibernatableWebSocketAckKey(gatewayId, requestId);
-		const binding =
-			this.#hibernatableRunnerWebSocketBindings.get(key);
+		const binding = this.#hibernatableRunnerWebSocketBindings.get(key);
 		binding?.detach?.();
 		this.#hibernatableRunnerWebSocketBindings.delete(key);
 	}
@@ -585,7 +573,7 @@ export class EngineActorDriver implements ActorDriver {
 		return handler;
 	}
 
-	getContext(actorId: string): DriverContext {
+	getContext(_actorId: string): DriverContext {
 		return {};
 	}
 
@@ -1140,7 +1128,10 @@ export class EngineActorDriver implements ActorDriver {
 						actorId: binding.actorId,
 						error: stringifyError(error),
 					});
-					binding.websocket.close(1011, "dynamic.websocket_forward_failed");
+					binding.websocket.close(
+						1011,
+						"dynamic.websocket_forward_failed",
+					);
 				});
 		};
 		const onClose = (event: CloseEvent) => {
@@ -1270,7 +1261,10 @@ export class EngineActorDriver implements ActorDriver {
 					msg: "dynamic runtime websocket binding is missing after restore",
 					actorId: binding.actorId,
 				});
-				binding.websocket.close(1011, "dynamic.websocket_forward_failed");
+				binding.websocket.close(
+					1011,
+					"dynamic.websocket_forward_failed",
+				);
 				return;
 			}
 
@@ -1286,7 +1280,10 @@ export class EngineActorDriver implements ActorDriver {
 						actorId: binding.actorId,
 						error: stringifyError(error),
 					});
-					binding.websocket.close(1011, "dynamic.websocket_forward_failed");
+					binding.websocket.close(
+						1011,
+						"dynamic.websocket_forward_failed",
+					);
 				});
 		};
 		const onClose = (event: CloseEvent) => {
@@ -1357,7 +1354,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().warn({
 					msg: "failed to rebind dynamic hibernatable runner websocket",
 					actorId,
-					err: stringifyError(result.reason),
+					error: stringifyError(result.reason),
 				});
 			}
 		}
@@ -1380,7 +1377,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().warn({
 					msg: "failed to rebind hibernatable connect socket",
 					actorId,
-					err: stringifyError(result.reason),
+					error: stringifyError(result.reason),
 				});
 			}
 		}
@@ -1640,7 +1637,7 @@ export class EngineActorDriver implements ActorDriver {
 					logger().warn({
 						msg: "failed to restore dynamic hibernating requests after actor start",
 						actorId,
-						err: stringifyError(error),
+						error: stringifyError(error),
 					});
 				}
 			} else if (isStaticActorDefinition(definition)) {
@@ -1707,7 +1704,7 @@ export class EngineActorDriver implements ActorDriver {
 					logger().debug({
 						msg: "failed to dispose dynamic runtime after actor start failure",
 						actorId,
-						err: stringifyError(disposeError),
+						error: stringifyError(disposeError),
 					});
 				}
 				this.#dynamicRuntimes.delete(actorId);
@@ -1730,7 +1727,7 @@ export class EngineActorDriver implements ActorDriver {
 				actorId,
 				name,
 				key,
-				err: stringifyError(error),
+				error: stringifyError(error),
 			});
 
 			try {
@@ -1739,7 +1736,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().debug({
 					msg: "failed to stop actor after start failure",
 					actorId,
-					err: stringifyError(stopError),
+					error: stringifyError(stopError),
 				});
 			}
 		}
@@ -1786,7 +1783,7 @@ export class EngineActorDriver implements ActorDriver {
 				logger().debug({
 					msg: "actor start failed during stop, cleaning up handler",
 					actorId,
-					err: stringifyError(err),
+					error: stringifyError(err),
 				});
 			}
 		}
@@ -1804,7 +1801,7 @@ export class EngineActorDriver implements ActorDriver {
 			} catch (err) {
 				logger().error({
 					msg: "error in onStop, proceeding with removing actor",
-					err: stringifyError(err),
+					error: stringifyError(err),
 				});
 			}
 		}
@@ -1989,8 +1986,11 @@ export class EngineActorDriver implements ActorDriver {
 				isHibernatable,
 				isRestoringHibernatable,
 			);
-		} catch (err) {
-			logger().error({ msg: "building websocket handlers errored", err });
+		} catch (error) {
+			logger().error({
+				msg: "building websocket handlers errored",
+				error,
+			});
 			websocketRaw.close(1011, "ws.route_error");
 			return;
 		}
@@ -2005,7 +2005,7 @@ export class EngineActorDriver implements ActorDriver {
 		// Get connection and actor from wsHandler (may be undefined for inspector endpoint)
 		const conn = wsHandler.conn;
 		const actor = wsHandler.actor;
-		const connStateManager = conn?.[CONN_STATE_MANAGER_SYMBOL];
+		const _connStateManager = conn?.[CONN_STATE_MANAGER_SYMBOL];
 
 		// Bind event listeners to Hono WebSocket handlers
 		//
@@ -2044,16 +2044,15 @@ export class EngineActorDriver implements ActorDriver {
 
 			const currentActor = this.#actors.get(actorId)?.actor;
 			const actorForDispatch =
-				currentActor &&
-				isStaticActorInstance(currentActor)
+				currentActor && isStaticActorInstance(currentActor)
 					? currentActor
 					: actor;
 			const connForDispatch =
 				isHibernatable && actorForDispatch
-					? actorForDispatch.connectionManager.findHibernatableConn(
+					? (actorForDispatch.connectionManager.findHibernatableConn(
 							gatewayIdBuf,
 							requestIdBuf,
-						) ?? conn
+						) ?? conn)
 					: conn;
 
 			if (actorForDispatch?.isStopping) {
@@ -2063,7 +2062,10 @@ export class EngineActorDriver implements ActorDriver {
 					actorId: actorForDispatch?.id,
 					messageIndex: event.rivetMessageIndex,
 				});
-				if (!isRawWebSocketPath && websocket.readyState !== websocket.CLOSED) {
+				if (
+					!isRawWebSocketPath &&
+					websocket.readyState !== websocket.CLOSED
+				) {
 					websocket.close(1011, "actor.stopping");
 				}
 				return;

package/src/dynamic/instance.ts

@@ -0,0 +1,32 @@
+import type { DynamicActorIsolateRuntime } from "./isolate-runtime";
+
+export class DynamicActorInstance {
+	constructor(
+		public readonly id: string,
+		private readonly runtime: DynamicActorIsolateRuntime,
+	) {}
+
+	get isStopping(): boolean {
+		return this.runtime.isStopping;
+	}
+
+	async onStop(mode: "sleep" | "destroy"): Promise<void> {
+		await this.runtime.stop(mode);
+	}
+
+	async onAlarm(): Promise<void> {
+		await this.runtime.onAlarm();
+	}
+
+	async cleanupPersistedConnections(reason?: string): Promise<number> {
+		return await this.runtime.cleanupPersistedConnections(reason);
+	}
+
+	async getHibernatingWebSockets() {
+		return await this.runtime.getHibernatingWebSockets();
+	}
+
+	getHibernatingWebSocketMetadata() {
+		return this.runtime.getHibernatingWebSocketMetadata();
+	}
+}