rivetkit 2.0.42 → 2.1.0-rc.1

package/src/inspector/utils.ts

@@ -1,29 +1,6 @@
 import { createMiddleware } from "hono/factory";
-import { inspectorLogger } from "./log";
 import type { RegistryConfig } from "@/registry/config";
-
-export function compareSecrets(providedSecret: string, validSecret: string) {
-	// Early length check to avoid unnecessary processing
-	if (providedSecret.length !== validSecret.length) {
-		return false;
-	}
-
-	const encoder = new TextEncoder();
-
-	const a = encoder.encode(providedSecret);
-	const b = encoder.encode(validSecret);
-
-	if (a.byteLength !== b.byteLength) {
-		return false;
-	}
-
-	// TODO:
-	// // Perform timing-safe comparison
-	// if (!crypto.timingSafeEqual(a, b)) {
-	// 	return false;
-	// }
-	return true;
-}
+import { timingSafeEqual } from "@/utils/crypto";
 
 export const secureInspector = (config: RegistryConfig) =>
 	createMiddleware(async (c, next) => {
@@ -37,8 +14,7 @@ export const secureInspector = (config: RegistryConfig) =>
 			return c.text("Unauthorized", 401);
 		}
 
-		const isValid = compareSecrets(userToken, inspectorToken);
-		if (!isValid) {
+		if (!timingSafeEqual(userToken, inspectorToken)) {
 			return c.text("Unauthorized", 401);
 		}
 		await next();
@@ -50,17 +26,7 @@ export function getInspectorUrl(
 ): string | undefined {
 	if (!config.inspector.enabled) return undefined;
 
-	const url = new URL("https://inspect.rivet.dev");
-
-	// Only override endpoint if using non-default port or custom endpoint is set
-	const endpoint =
-		config.inspector.defaultEndpoint ??
-		(config.managerPort !== 6420
-			? `http://127.0.0.1:${managerPort}`
-			: undefined);
-	if (endpoint) {
-		url.searchParams.set("u", endpoint);
-	}
-
-	return url.href;
+	const base =
+		config.inspector.defaultEndpoint ?? `http://127.0.0.1:${managerPort}`;
+	return new URL("/ui/", base).href;
 }

package/src/manager/gateway.ts

@@ -425,7 +425,7 @@ export async function createTestWebSocketProxy(
 		promise: clientToProxyWsPromise,
 		resolve: clientToProxyWsResolve,
 		reject: clientToProxyWsReject,
-	} = promiseWithResolvers<WSContext>();
+	} = promiseWithResolvers<WSContext>((reason) => logger().warn({ msg: "unhandled client websocket promise rejection", reason }));
 	try {
 		// Resolve the client WebSocket promise
 		logger().debug({ msg: "awaiting client websocket promise" });

package/src/manager/protocol/mod.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { ActorQuerySchema } from "./query";
 
 export * from "./query";

package/src/manager/protocol/query.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { EncodingSchema } from "@/actor/protocol/serde";
 import {
 	HEADER_ACTOR_ID,

package/src/manager/router-schema.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const ServerlessStartHeadersSchema = z.object({
 	endpoint: z.string({

package/src/manager/router.ts

@@ -1,13 +1,11 @@
+import { serveStatic } from "@hono/node-server/serve-static";
 import { createRoute } from "@hono/zod-openapi";
 import * as cbor from "cbor-x";
-
 import type { Hono } from "hono";
 import invariant from "invariant";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { Forbidden, RestrictedFeature } from "@/actor/errors";
-
-import { serializeActorKey } from "@/actor/keys";
-
+import { deserializeActorKey, serializeActorKey } from "@/actor/keys";
 import type { Encoding } from "@/client/mod";
 import {
 	HEADER_RIVET_TOKEN,
@@ -23,6 +21,7 @@ import type {
 	TestInlineDriverCallRequest,
 	TestInlineDriverCallResponse,
 } from "@/driver-test-suite/test-inline-client-driver";
+import { getInspectorDir } from "@/inspector/serve-ui";
 import {
 	ActorsCreateRequestSchema,
 	type ActorsCreateResponse,
@@ -95,9 +94,9 @@ export function buildManagerRouter(
 
 				const actorIdsParsed = actor_ids
 					? actor_ids
-							.split(",")
-							.map((id) => id.trim())
-							.filter((id) => id.length > 0)
+						.split(",")
+						.map((id) => id.trim())
+						.filter((id) => id.length > 0)
 					: undefined;
 
 				const actors: ActorOutput[] = [];
@@ -171,7 +170,7 @@ export function buildManagerRouter(
 					const actorOutput = await managerDriver.getWithKey({
 						c,
 						name,
-						key: [key], // Convert string to ActorKey array
+						key: deserializeActorKey(key),
 					});
 					if (actorOutput) {
 						actors.push(actorOutput);
@@ -245,7 +244,7 @@ export function buildManagerRouter(
 				const existingActor = await managerDriver.getWithKey({
 					c,
 					name: body.name,
-					key: [body.key], // Convert string to ActorKey array
+					key: deserializeActorKey(body.key),
 				});
 
 				if (existingActor) {
@@ -259,7 +258,7 @@ export function buildManagerRouter(
 				const newActor = await managerDriver.getOrCreateWithKey({
 					c,
 					name: body.name,
-					key: [body.key], // Convert string to ActorKey array
+					key: deserializeActorKey(body.key),
 					input: body.input
 						? cbor.decode(Buffer.from(body.input, "base64"))
 						: undefined,
@@ -291,7 +290,7 @@ export function buildManagerRouter(
 				const actorOutput = await managerDriver.createActor({
 					c,
 					name: body.name,
-					key: [body.key || crypto.randomUUID()], // Generate key if not provided, convert to ActorKey array
+					key: deserializeActorKey(body.key || crypto.randomUUID()),
 					input: body.input
 						? cbor.decode(Buffer.from(body.input, "base64"))
 						: undefined,
@@ -587,6 +586,33 @@ export function buildManagerRouter(
 			});
 		}
 
+		if (config.inspector.enabled) {
+			let inspectorRoot: string | undefined;
+
+
+			router.get("/ui/*", async (c, next) => {
+				if (!inspectorRoot) {
+					inspectorRoot = await getInspectorDir();
+				}
+				const root = inspectorRoot;
+				const rewrite = (path: string) =>
+					path.replace(/^\/ui/, "") || "/";
+
+				return serveStatic({
+					root,
+					rewriteRequestPath: rewrite,
+					onNotFound: async (_path, c) => {
+						await serveStatic({ root, path: "index.html" })(
+							c,
+							next,
+						);
+					},
+				})(c, next);
+			});
+
+			router.get("/ui", (c) => c.redirect("/ui/"));
+		}
+
 		router.get("/health", (c) => handleHealthRequest(c));
 
 		router.get("/metadata", (c) =>

package/src/manager-api/actors.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { RivetIdSchema } from "./common";
 
 export const ActorSchema = z.object({

package/src/manager-api/common.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 
 export const RivetIdSchema = z.string();
 export type RivetId = z.infer<typeof RivetIdSchema>;

package/src/registry/config/driver.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { ActorDriverBuilder } from "@/actor/driver";
 import { ManagerDriverBuilder } from "@/manager/driver";
 

package/src/registry/config/index.ts

@@ -1,12 +1,15 @@
 import { z } from "zod";
+import { getRunMetadata } from "@/actor/config";
 import type { ActorDefinition, AnyActorDefinition } from "@/actor/definition";
 import { type Logger, LogLevelSchema } from "@/common/log";
 import { ENGINE_ENDPOINT } from "@/engine-process/constants";
 import { InspectorConfigSchema } from "@/inspector/config";
+import { DeepReadonly } from "@/utils";
 import { tryParseEndpoint } from "@/utils/endpoint-parser";
 import {
 	getRivetEndpoint,
 	getRivetEngine,
+	getRivetkitStoragePath,
 	getRivetNamespace,
 	getRivetToken,
 	isDev,
@@ -14,13 +17,12 @@ import {
 import { type DriverConfig, DriverConfigSchema } from "./driver";
 import { RunnerConfigSchema } from "./runner";
 import { ServerlessConfigSchema } from "./serverless";
-import { DeepReadonly } from "@/utils";
 
 export { DriverConfigSchema, type DriverConfig };
 
 export const ActorsSchema = z.record(
 	z.string(),
-	z.custom<ActorDefinition<any, any, any, any, any, any, any>>(),
+	z.custom<ActorDefinition<any, any, any, any, any, any, any, any, any>>(),
 );
 export type RegistryActors = z.infer<typeof ActorsSchema>;
 
@@ -44,6 +46,17 @@ export const RegistryConfigSchema = z
 
 		// MARK: Driver
 		driver: DriverConfigSchema.optional(),
+		/**
+		 * Storage path for RivetKit file-system state when using the default driver.
+		 *
+		 * If not set, RivetKit uses the platform default data location.
+		 *
+		 * Can also be set via RIVETKIT_STORAGE_PATH.
+		 */
+		storagePath: z
+			.string()
+			.optional()
+			.transform((val) => val ?? getRivetkitStoragePath()),
 
 		// MARK: Networking
 		/** @experimental */
@@ -265,9 +278,21 @@ export type RegistryConfigInput<A extends RegistryActors> = Omit<
 
 export function buildActorNames(
 	config: RegistryConfig,
-): Record<string, { metadata: Record<string, any> }> {
+): Record<string, { metadata: Record<string, unknown> }> {
 	return Object.fromEntries(
-		Object.keys(config.use).map((name) => [name, { metadata: {} }]),
+		Object.keys(config.use).map((actorName) => {
+			const definition = config.use[actorName];
+			const options = definition.config.options ?? {};
+			const runMeta = getRunMetadata(definition.config.run);
+			const metadata: Record<string, unknown> = {};
+			// Actor options take precedence over run metadata
+			metadata.icon = options.icon ?? runMeta.icon;
+			metadata.name = options.name ?? runMeta.name;
+			// Remove undefined values
+			if (!metadata.icon) delete metadata.icon;
+			if (!metadata.name) delete metadata.name;
+			return [actorName, { metadata }];
+		}),
 	);
 }
 
@@ -277,9 +302,22 @@ export function buildActorNames(
 
 export const DocInspectorConfigSchema = z
 	.object({
-		enabled: z.boolean().optional().describe("Whether to enable the Rivet Inspector. Defaults to true in development mode."),
-		token: z.string().optional().describe("Token used to access the Inspector."),
-		defaultEndpoint: z.string().optional().describe("Default RivetKit server endpoint for Rivet Inspector to connect to."),
+		enabled: z
+			.boolean()
+			.optional()
+			.describe(
+				"Whether to enable the Rivet Inspector. Defaults to true in development mode.",
+			),
+		token: z
+			.string()
+			.optional()
+			.describe("Token used to access the Inspector."),
+		defaultEndpoint: z
+			.string()
+			.optional()
+			.describe(
+				"Default RivetKit server endpoint for Rivet Inspector to connect to.",
+			),
 	})
 	.optional()
 	.describe("Inspector configuration for debugging and development.");
@@ -287,53 +325,184 @@ export const DocInspectorConfigSchema = z
 export const DocConfigureRunnerPoolSchema = z
 	.object({
 		name: z.string().optional().describe("Name of the runner pool."),
-		url: z.string().describe("URL of the serverless platform to configure runners."),
-		headers: z.record(z.string(), z.string()).optional().describe("Headers to include in requests to the serverless platform."),
-		maxRunners: z.number().optional().describe("Maximum number of runners in the pool."),
-		minRunners: z.number().optional().describe("Minimum number of runners to keep warm."),
-		requestLifespan: z.number().optional().describe("Maximum lifespan of a request in milliseconds."),
-		runnersMargin: z.number().optional().describe("Buffer margin for scaling runners."),
-		slotsPerRunner: z.number().optional().describe("Number of actor slots per runner."),
-		metadata: z.record(z.string(), z.unknown()).optional().describe("Additional metadata to pass to the serverless platform."),
-		metadataPollInterval: z.number().optional().describe("Interval in milliseconds between metadata polls from the engine. Defaults to 10000 milliseconds (10 seconds)."),
+		url: z
+			.string()
+			.describe("URL of the serverless platform to configure runners."),
+		headers: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe(
+				"Headers to include in requests to the serverless platform.",
+			),
+		maxRunners: z
+			.number()
+			.optional()
+			.describe("Maximum number of runners in the pool."),
+		minRunners: z
+			.number()
+			.optional()
+			.describe("Minimum number of runners to keep warm."),
+		requestLifespan: z
+			.number()
+			.optional()
+			.describe("Maximum lifespan of a request in milliseconds."),
+		runnersMargin: z
+			.number()
+			.optional()
+			.describe("Buffer margin for scaling runners."),
+		slotsPerRunner: z
+			.number()
+			.optional()
+			.describe("Number of actor slots per runner."),
+		metadata: z
+			.record(z.string(), z.unknown())
+			.optional()
+			.describe(
+				"Additional metadata to pass to the serverless platform.",
+			),
+		metadataPollInterval: z
+			.number()
+			.optional()
+			.describe(
+				"Interval in milliseconds between metadata polls from the engine. Defaults to 10000 milliseconds (10 seconds).",
+			),
 	})
 	.optional();
 
-export const DocServerlessConfigSchema = z.object({
-	spawnEngine: z.boolean().optional().describe("Downloads and starts the full Rust engine process. Auto-enabled in development mode when no endpoint is provided. Default: false"),
-	engineVersion: z.string().optional().describe("Version of the engine to download. Defaults to the current RivetKit version."),
-	configureRunnerPool: DocConfigureRunnerPoolSchema.describe("Automatically configure serverless runners in the engine."),
-	basePath: z.string().optional().describe("Base path for serverless API routes. Default: '/api/rivet'"),
-	publicEndpoint: z.string().optional().describe("The endpoint that clients should connect to. Supports URL auth syntax: https://namespace:token@api.rivet.dev"),
-	publicToken: z.string().optional().describe("Token that clients should use when connecting via the public endpoint."),
-}).describe("Configuration for serverless deployment mode.");
-
-export const DocRunnerConfigSchema = z.object({
-	totalSlots: z.number().optional().describe("Total number of actor slots available. Default: 100000"),
-	runnerName: z.string().optional().describe("Name of this runner. Default: 'default'"),
-	runnerKey: z.string().optional().describe("Authentication key for the runner."),
-	version: z.number().optional().describe("Version number of this runner. Default: 1"),
-}).describe("Configuration for runner mode.");
+export const DocServerlessConfigSchema = z
+	.object({
+		spawnEngine: z
+			.boolean()
+			.optional()
+			.describe(
+				"Downloads and starts the full Rust engine process. Auto-enabled in development mode when no endpoint is provided. Default: false",
+			),
+		engineVersion: z
+			.string()
+			.optional()
+			.describe(
+				"Version of the engine to download. Defaults to the current RivetKit version.",
+			),
+		configureRunnerPool: DocConfigureRunnerPoolSchema.describe(
+			"Automatically configure serverless runners in the engine.",
+		),
+		basePath: z
+			.string()
+			.optional()
+			.describe(
+				"Base path for serverless API routes. Default: '/api/rivet'",
+			),
+		publicEndpoint: z
+			.string()
+			.optional()
+			.describe(
+				"The endpoint that clients should connect to. Supports URL auth syntax: https://namespace:token@api.rivet.dev",
+			),
+		publicToken: z
+			.string()
+			.optional()
+			.describe(
+				"Token that clients should use when connecting via the public endpoint.",
+			),
+	})
+	.describe("Configuration for serverless deployment mode.");
+
+export const DocRunnerConfigSchema = z
+	.object({
+		totalSlots: z
+			.number()
+			.optional()
+			.describe("Total number of actor slots available. Default: 100000"),
+		runnerName: z
+			.string()
+			.optional()
+			.describe("Name of this runner. Default: 'default'"),
+		runnerKey: z
+			.string()
+			.optional()
+			.describe("Authentication key for the runner."),
+		version: z
+			.number()
+			.optional()
+			.describe("Version number of this runner. Default: 1"),
+	})
+	.describe("Configuration for runner mode.");
 
 export const DocRegistryConfigSchema = z
 	.object({
-		use: z.record(z.string(), z.unknown()).describe("Actor definitions. Keys are actor names, values are actor definitions."),
-		maxIncomingMessageSize: z.number().optional().describe("Maximum size of incoming WebSocket messages in bytes. Default: 65536"),
-		maxOutgoingMessageSize: z.number().optional().describe("Maximum size of outgoing WebSocket messages in bytes. Default: 1048576"),
-		noWelcome: z.boolean().optional().describe("Disable the welcome message on startup. Default: false"),
+		use: z
+			.record(z.string(), z.unknown())
+			.describe(
+				"Actor definitions. Keys are actor names, values are actor definitions.",
+			),
+		storagePath: z
+			.string()
+			.optional()
+			.describe(
+				"Storage path for RivetKit file-system state when using the default driver. Can also be set via RIVETKIT_STORAGE_PATH.",
+			),
+		maxIncomingMessageSize: z
+			.number()
+			.optional()
+			.describe(
+				"Maximum size of incoming WebSocket messages in bytes. Default: 65536",
+			),
+		maxOutgoingMessageSize: z
+			.number()
+			.optional()
+			.describe(
+				"Maximum size of outgoing WebSocket messages in bytes. Default: 1048576",
+			),
+		noWelcome: z
+			.boolean()
+			.optional()
+			.describe("Disable the welcome message on startup. Default: false"),
 		logging: z
 			.object({
-				level: LogLevelSchema.optional().describe("Log level for RivetKit. Default: 'warn'"),
+				level: LogLevelSchema.optional().describe(
+					"Log level for RivetKit. Default: 'warn'",
+				),
 			})
 			.optional()
 			.describe("Logging configuration."),
-		endpoint: z.string().optional().describe("Endpoint URL to connect to Rivet Engine. Supports URL auth syntax: https://namespace:token@api.rivet.dev. Can also be set via RIVET_ENDPOINT environment variable."),
-		token: z.string().optional().describe("Authentication token for Rivet Engine. Can also be set via RIVET_TOKEN environment variable."),
-		namespace: z.string().optional().describe("Namespace to use. Default: 'default'. Can also be set via RIVET_NAMESPACE environment variable."),
-		headers: z.record(z.string(), z.string()).optional().describe("Additional headers to include in requests to Rivet Engine."),
-		serveManager: z.boolean().optional().describe("Whether to start the local manager server. Auto-determined based on endpoint and NODE_ENV if not specified."),
-		managerBasePath: z.string().optional().describe("Base path for the manager API. Default: '/'"),
-		managerPort: z.number().optional().describe("Port to run the manager on. Default: 6420"),
+		endpoint: z
+			.string()
+			.optional()
+			.describe(
+				"Endpoint URL to connect to Rivet Engine. Supports URL auth syntax: https://namespace:token@api.rivet.dev. Can also be set via RIVET_ENDPOINT environment variable.",
+			),
+		token: z
+			.string()
+			.optional()
+			.describe(
+				"Authentication token for Rivet Engine. Can also be set via RIVET_TOKEN environment variable.",
+			),
+		namespace: z
+			.string()
+			.optional()
+			.describe(
+				"Namespace to use. Default: 'default'. Can also be set via RIVET_NAMESPACE environment variable.",
+			),
+		headers: z
+			.record(z.string(), z.string())
+			.optional()
+			.describe(
+				"Additional headers to include in requests to Rivet Engine.",
+			),
+		serveManager: z
+			.boolean()
+			.optional()
+			.describe(
+				"Whether to start the local manager server. Auto-determined based on endpoint and NODE_ENV if not specified.",
+			),
+		managerBasePath: z
+			.string()
+			.optional()
+			.describe("Base path for the manager API. Default: '/'"),
+		managerPort: z
+			.number()
+			.optional()
+			.describe("Port to run the manager on. Default: 6420"),
 		inspector: DocInspectorConfigSchema,
 		serverless: DocServerlessConfigSchema.optional(),
 		runner: DocRunnerConfigSchema.optional(),

package/src/registry/config/legacy-runner.ts

@@ -1,5 +1,5 @@
 import type { Logger } from "pino";
-import { z } from "zod";
+import { z } from "zod/v4";
 import type { ActorDriverBuilder } from "@/actor/driver";
 import { LogLevelSchema } from "@/common/log";
 import {

package/src/registry/config/runner.ts

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

package/src/registry/config/serverless.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import { VERSION } from "@/utils";
 import {
 	getRivetRunEngineVersion,

package/src/registry/index.ts

@@ -1,6 +1,6 @@
 import type { Client } from "@/client/client";
 import { createClient } from "@/client/mod";
-import { isDev } from "@/utils/env-vars";
+import { getNodeEnv, isDev } from "@/utils/env-vars";
 import {
 	type RegistryActors,
 	type RegistryConfig,
@@ -49,10 +49,12 @@ export class Registry<A extends RegistryActors> {
 		this.#config = config;
 
 		// Auto-prepare on next tick (gives time for sync config modification)
-		setTimeout(() => {
-			// biome-ignore lint/nursery/noFloatingPromises: fire-and-forget auto-prepare
-			this.#ensureRuntime();
-		}, 0);
+		if (getNodeEnv() !== "test") {
+			setTimeout(() => {
+				// biome-ignore lint/nursery/noFloatingPromises: fire-and-forget auto-prepare
+				this.#ensureRuntime();
+			}, 0);
+		}
 	}
 
 	/** Creates runtime if not already created. Idempotent. */

package/src/remote-manager-driver/api-utils.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import type { ClientConfig } from "@/client/config";
 import { sendHttpRequest } from "@/client/utils";
 import { combineUrlPath } from "@/utils";

package/src/schemas/actor-inspector/mod.ts

@@ -1 +1 @@
-export * from "../../../dist/schemas/actor-inspector/v1";
+export * from "../../../dist/schemas/actor-inspector/v3";