rivetkit 2.0.37 → 2.0.39

package/src/client/errors.ts

@@ -1,5 +1,3 @@
-import { MAX_CONN_PARAMS_SIZE } from "@/common//network";
-
 export class ActorClientError extends Error {}
 
 export class InternalError extends ActorClientError {}
@@ -41,72 +39,38 @@ export class ActorConnDisposed extends ActorClientError {
 	}
 }
 
-// === Actor Scheduling Error Types ===
-
-/**
- * Errors from serverless connection workflow.
- * Matches ServerlessConnectionError from API.
- */
-export type ServerlessConnectionError =
-	| { http_error: { status_code: number; body: string } }
-	| "stream_ended_early"
-	| { connection_error: { message: string } }
-	| "invalid_base64"
-	| { invalid_payload: { message: string } }
-	| "runner_config_not_found"
-	| "runner_config_not_serverless"
-	| "namespace_not_found";
-
 /**
- * Actor error details from API response.
- * Matches ActorError from API.
+ * Checks if an error code indicates a scheduling error that may have more details.
  */
-export type ActorErrorDetails =
-	| { serverless_error: ServerlessConnectionError }
-	| { no_capacity: { runner_name: string } }
-	| { runner_no_response: { runner_id: string } };
+export function isSchedulingError(group: string, code: string): boolean {
+	return (
+		group === "guard" &&
+		(code === "actor_ready_timeout" || code === "actor_runner_failed")
+	);
+}
 
 /**
  * Error thrown when actor scheduling fails.
  * Provides detailed information about why the actor failed to start.
  */
-export class ActorSchedulingError extends ActorClientError {
+export class ActorSchedulingError extends ActorError {
 	public readonly actorId: string;
-	public readonly errorType: string;
-	public readonly details: ActorErrorDetails;
+	public readonly details: unknown;
 
-	constructor(actorId: string, error: ActorErrorDetails) {
-		const message = ActorSchedulingError.formatMessage(error);
-		super(message);
+	constructor(
+		group: string,
+		code: string,
+		actorId: string,
+		details: unknown,
+	) {
+		super(
+			group,
+			code,
+			`Actor failed to start (${actorId}): ${JSON.stringify(details)}`,
+			{ actorId, details },
+		);
 		this.name = "ActorSchedulingError";
 		this.actorId = actorId;
-		this.errorType = Object.keys(error)[0];
-		this.details = error;
-	}
-
-	static formatMessage(error: ActorErrorDetails): string {
-		if ("serverless_error" in error) {
-			const se = error.serverless_error;
-			if (typeof se === "string") {
-				return `Serverless error: ${se.replace(/_/g, " ")}`;
-			}
-			if ("http_error" in se) {
-				return `Serverless HTTP ${se.http_error.status_code}: ${se.http_error.body}`;
-			}
-			if ("connection_error" in se) {
-				return `Serverless connection error: ${se.connection_error.message}`;
-			}
-			if ("invalid_payload" in se) {
-				return `Invalid serverless payload: ${se.invalid_payload.message}`;
-			}
-			return "Unknown serverless error";
-		}
-		if ("no_capacity" in error) {
-			return `No capacity available for runner: ${error.no_capacity.runner_name}`;
-		}
-		if ("runner_no_response" in error) {
-			return `Runner ${error.runner_no_response.runner_id} did not respond`;
-		}
-		return "Unknown scheduling error";
+		this.details = details;
 	}
 }

package/src/client/mod.ts

@@ -22,7 +22,7 @@ export {
 	ManagerError,
 } from "@/client/errors";
 export type { CreateRequest } from "@/manager/protocol/query";
-export { KEYS as KV_KEYS } from "../actor/instance/kv";
+export { KEYS as KV_KEYS } from "../actor/instance/keys";
 export type { ActorActionFunction } from "./actor-common";
 export type {
 	ActorConn,

package/src/client/utils.ts

@@ -20,6 +20,39 @@ import { httpUserAgent } from "@/utils";
 import { ActorError, HttpRequestError } from "./errors";
 import { logger } from "./log";
 
+export interface ParsedCloseReason {
+	group: string;
+	code: string;
+	rayId?: string;
+}
+
+/**
+ * Parses WebSocket close reason string into structured data.
+ *
+ * Expected format examples:
+ *   - "guard.actor_runner_failed#t1s80so6h3irenp8ymzltfoittcl00"
+ *   - "ws.client_closed"
+ *
+ * Returns undefined if the format is invalid
+ */
+export function parseWebSocketCloseReason(
+	reason: string,
+): ParsedCloseReason | undefined {
+	const [mainPart, rayId] = reason.split("#");
+	const [group, code] = mainPart.split(".");
+
+	if (!group || !code) {
+		logger().warn({ msg: "failed to parse close reason", reason });
+		return undefined;
+	}
+
+	return {
+		group,
+		code,
+		rayId,
+	};
+}
+
 export type WebSocketMessage = string | Blob | ArrayBuffer | Uint8Array;
 
 export function messageLength(message: WebSocketMessage): number {

package/src/driver-helpers/utils.ts

@@ -1,5 +1,5 @@
 import * as cbor from "cbor-x";
-import { KEYS } from "@/actor/instance/kv";
+import { KEYS } from "@/actor/instance/keys";
 import type * as persistSchema from "@/schemas/actor-persist/mod";
 import {
 	ACTOR_VERSIONED,

package/src/driver-test-suite/mod.ts

@@ -22,6 +22,7 @@ import { runActorErrorHandlingTests } from "./tests/actor-error-handling";
 import { runActorHandleTests } from "./tests/actor-handle";
 import { runActorInlineClientTests } from "./tests/actor-inline-client";
 import { runActorInspectorTests } from "./tests/actor-inspector";
+import { runActorKvTests } from "./tests/actor-kv";
 import { runActorMetadataTests } from "./tests/actor-metadata";
 import { runActorOnStateChangeTests } from "./tests/actor-onstatechange";
 import { runActorVarsTests } from "./tests/actor-vars";
@@ -122,6 +123,8 @@ export function runDriverTests(
 
 					runActorInlineClientTests(driverTestConfig);
 
+					runActorKvTests(driverTestConfig);
+
 					runRawHttpTests(driverTestConfig);
 
 					runRawHttpRequestPropertiesTests(driverTestConfig);

package/src/driver-test-suite/test-inline-client-driver.ts

@@ -237,6 +237,9 @@ export function createTestInlineClientDriver(
 			);
 			return upgradeWebSocket(() => wsHandler)(c, noopNext());
 		},
+		async buildGatewayUrl(actorId: string): Promise<string> {
+			return `${endpoint}/gateway/${actorId}`;
+		},
 		displayInformation(): ManagerDisplayInformation {
 			return { properties: {} };
 		},

package/src/driver-test-suite/tests/actor-kv.ts

@@ -0,0 +1,44 @@
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest } from "../utils";
+import { describe, expect, test, type TestContext } from "vitest";
+
+export function runActorKvTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor KV Tests", () => {
+		test("supports text encoding and decoding", async (c: TestContext) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const kvHandle = client.kvActor.getOrCreate(["kv-text"]);
+
+			await kvHandle.putText("greeting", "hello");
+			const value = await kvHandle.getText("greeting");
+			expect(value).toBe("hello");
+
+			await kvHandle.putText("prefix-a", "alpha");
+			await kvHandle.putText("prefix-b", "beta");
+
+			const results = await kvHandle.listText("prefix-");
+			const sorted = results.sort((a, b) => a.key.localeCompare(b.key));
+			expect(sorted).toEqual([
+				{ key: "prefix-a", value: "alpha" },
+				{ key: "prefix-b", value: "beta" },
+			]);
+		});
+
+		test(
+			"supports arrayBuffer encoding and decoding",
+			async (c: TestContext) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const kvHandle = client.kvActor.getOrCreate(["kv-array-buffer"]);
+
+			const values = await kvHandle.roundtripArrayBuffer("bytes", [
+				4,
+				8,
+				15,
+				16,
+				23,
+				42,
+			]);
+			expect(values).toEqual([4, 8, 15, 16, 23, 42]);
+		},
+		);
+	});
+}

package/src/driver-test-suite/utils.ts

@@ -39,6 +39,10 @@ export async function setupDriverTest(
 			namespace,
 			runnerName,
 			encoding: driverTestConfig.encoding,
+			// Disable metadata lookup to prevent redirect to the wrong port.
+			// Each test starts a new server on a dynamic port, but the
+			// registry's publicEndpoint defaults to port 6420.
+			disableMetadataLookup: true,
 		});
 	} else if (driverTestConfig.clientType === "inline") {
 		// Use inline client from driver

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

@@ -11,7 +11,7 @@ import { WSContext, type WSContextInit } from "hono/ws";
 import invariant from "invariant";
 import { type AnyConn, CONN_STATE_MANAGER_SYMBOL } from "@/actor/conn/mod";
 import { lookupInRegistry } from "@/actor/definition";
-import { KEYS } from "@/actor/instance/kv";
+import { KEYS } from "@/actor/instance/keys";
 import { deserializeActorKey } from "@/actor/keys";
 import { getValueLength } from "@/actor/protocol/old";
 import { type ActorRouter, createActorRouter } from "@/actor/router";
@@ -153,7 +153,7 @@ export class EngineActorDriver implements ActorDriver {
 			onConnected: () => {
 				this.#runnerStarted.resolve(undefined);
 			},
-			onDisconnected: (_code, _reason) => { },
+			onDisconnected: (_code, _reason) => {},
 			onShutdown: () => {
 				this.#runnerStopped.resolve(undefined);
 				this.#isRunnerStopped = true;
@@ -358,7 +358,7 @@ export class EngineActorDriver implements ActorDriver {
 	async serverlessHandleStart(c: HonoContext): Promise<Response> {
 		return streamSSE(c, async (stream) => {
 			// NOTE: onAbort does not work reliably
-			stream.onAbort(() => { });
+			stream.onAbort(() => {});
 			c.req.raw.signal.addEventListener("abort", () => {
 				logger().debug("SSE aborted, shutting down runner");
 

package/src/drivers/file-system/manager.ts

@@ -147,6 +147,11 @@ export class FileSystemManagerDriver implements ManagerDriver {
 		return upgradeWebSocket(() => wsHandler)(c, noopNext());
 	}
 
+	async buildGatewayUrl(actorId: string): Promise<string> {
+		const port = this.#config.managerPort ?? 6420;
+		return `http://127.0.0.1:${port}/gateway/${encodeURIComponent(actorId)}`;
+	}
+
 	async getForId({
 		actorId,
 	}: GetForIdInput): Promise<ActorOutput | undefined> {

package/src/manager/driver.ts

@@ -1,7 +1,5 @@
 import type { Env, Hono, Context as HonoContext } from "hono";
 import type { ActorKey, Encoding, UniversalWebSocket } from "@/actor/mod";
-
-import type { ActorErrorDetails } from "@/client/errors";
 import type { RegistryConfig } from "@/registry/config";
 import type { GetUpgradeWebSocket } from "@/utils";
 
@@ -34,6 +32,13 @@ export interface ManagerDriver {
 		params: unknown,
 	): Promise<Response>;
 
+	/**
+	 * Build a public gateway URL for a specific actor.
+	 *
+	 * This lives on the driver because the base endpoint varies by runtime.
+	 */
+	buildGatewayUrl(actorId: string): Promise<string>;
+
 	displayInformation(): ManagerDisplayInformation;
 
 	extraStartupLog?: () => Record<string, unknown>;
@@ -97,5 +102,5 @@ export interface ActorOutput {
 	connectableTs?: number | null;
 	sleepTs?: number | null;
 	destroyTs?: number | null;
-	error?: ActorErrorDetails | null;
+	error?: unknown;
 }

package/src/manager-api/actors.ts

@@ -1,25 +1,6 @@
 import { z } from "zod";
 import { RivetIdSchema } from "./common";
 
-// Schema for serverless connection errors
-const ServerlessConnectionErrorSchema = z.union([
-	z.object({ http_error: z.object({ status_code: z.number(), body: z.string() }) }),
-	z.literal("stream_ended_early"),
-	z.object({ connection_error: z.object({ message: z.string() }) }),
-	z.literal("invalid_base64"),
-	z.object({ invalid_payload: z.object({ message: z.string() }) }),
-	z.literal("runner_config_not_found"),
-	z.literal("runner_config_not_serverless"),
-	z.literal("namespace_not_found"),
-]);
-
-// Schema for actor error details from API
-const ActorErrorDetailsSchema = z.union([
-	z.object({ serverless_error: ServerlessConnectionErrorSchema }),
-	z.object({ no_capacity: z.object({ runner_name: z.string() }) }),
-	z.object({ runner_no_response: z.object({ runner_id: z.string() }) }),
-]);
-
 export const ActorSchema = z.object({
 	actor_id: RivetIdSchema,
 	name: z.string(),
@@ -31,7 +12,7 @@ export const ActorSchema = z.object({
 	destroy_ts: z.number().nullable().optional(),
 	sleep_ts: z.number().nullable().optional(),
 	start_ts: z.number().nullable().optional(),
-	error: ActorErrorDetailsSchema.nullable().optional(),
+	error: z.unknown().nullable().optional(),
 });
 export type Actor = z.infer<typeof ActorSchema>;
 

package/src/registry/config/index.ts

@@ -264,3 +264,71 @@ export function buildActorNames(
 		Object.keys(config.use).map((name) => [name, { metadata: {} }]),
 	);
 }
+
+// MARK: Documentation Schemas
+// These schemas are JSON-serializable versions used for documentation generation.
+// They exclude runtime-only fields (transforms, custom types, Logger instances).
+
+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."),
+	})
+	.optional()
+	.describe("Inspector configuration for debugging and development.");
+
+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."),
+	})
+	.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 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"),
+		logging: z
+			.object({
+				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"),
+		inspector: DocInspectorConfigSchema,
+		serverless: DocServerlessConfigSchema.optional(),
+		runner: DocRunnerConfigSchema.optional(),
+	})
+	.describe("RivetKit registry configuration.");

package/src/remote-manager-driver/actor-http-client.ts

@@ -1,6 +1,6 @@
 import type { ClientConfig } from "@/client/config";
 import { HEADER_RIVET_TOKEN } from "@/common/actor-router-consts";
-import { combineUrlPath } from "@/utils";
+import { buildActorGatewayUrl } from "./actor-websocket-client";
 import { getEndpoint } from "./api-utils";
 
 export async function sendHttpRequestToActor(
@@ -11,9 +11,11 @@ export async function sendHttpRequestToActor(
 	// Route through guard port
 	const url = new URL(actorRequest.url);
 	const endpoint = getEndpoint(runConfig);
-	const guardUrl = combineUrlPath(
+	const guardUrl = buildActorGatewayUrl(
 		endpoint,
-		`/gateway/${actorId}${url.pathname}${url.search}`,
+		actorId,
+		runConfig.token,
+		`${url.pathname}${url.search}`,
 	);
 
 	// Handle body properly based on method and presence

package/src/remote-manager-driver/actor-websocket-client.ts

@@ -13,6 +13,18 @@ import { combineUrlPath } from "@/utils";
 import { getEndpoint } from "./api-utils";
 import { logger } from "./log";
 
+export function buildActorGatewayUrl(
+	endpoint: string,
+	actorId: string,
+	token: string | undefined,
+	path = "",
+): string {
+	const tokenSegment =
+		token !== undefined ? `@${encodeURIComponent(token)}` : "";
+	const gatewayPath = `/gateway/${encodeURIComponent(actorId)}${tokenSegment}${path}`;
+	return combineUrlPath(endpoint, gatewayPath);
+}
+
 export async function openWebSocketToActor(
 	runConfig: ClientConfig,
 	path: string,
@@ -24,13 +36,12 @@ export async function openWebSocketToActor(
 
 	// WebSocket connections go through guard
 	const endpoint = getEndpoint(runConfig);
-	let gatewayPath;
-	if (runConfig.token !== undefined) {
-		gatewayPath = `/gateway/${encodeURIComponent(actorId)}@${encodeURIComponent(runConfig.token)}${path}`;
-	} else {
-		gatewayPath = `/gateway/${encodeURIComponent(actorId)}${path}`;
-	}
-	const guardUrl = combineUrlPath(endpoint, gatewayPath);
+	const guardUrl = buildActorGatewayUrl(
+		endpoint,
+		actorId,
+		runConfig.token,
+		path,
+	);
 
 	logger().debug({
 		msg: "opening websocket to actor via guard",

package/src/remote-manager-driver/mod.ts

@@ -21,6 +21,7 @@ import { combineUrlPath, type GetUpgradeWebSocket } from "@/utils";
 import { getNextPhase } from "@/utils/env-vars";
 import { sendHttpRequestToActor } from "./actor-http-client";
 import {
+	buildActorGatewayUrl,
 	buildWebSocketProtocols,
 	openWebSocketToActor,
 } from "./actor-websocket-client";
@@ -81,9 +82,19 @@ export class RemoteManagerDriver implements ManagerDriver {
 					// Override endpoint for all future requests
 					if (metadataData.clientEndpoint) {
 						this.#config.endpoint = metadataData.clientEndpoint;
+						if (metadataData.clientNamespace) {
+							this.#config.namespace =
+								metadataData.clientNamespace;
+						}
+						if (metadataData.clientToken) {
+							this.#config.token = metadataData.clientToken;
+						}
+
 						logger().info({
-							msg: "overriding cached client endpoint",
+							msg: "overriding client endpoint",
 							endpoint: metadataData.clientEndpoint,
+							namespace: metadataData.clientNamespace,
+							token: metadataData.clientToken,
 						});
 					}
 
@@ -299,6 +310,15 @@ export class RemoteManagerDriver implements ManagerDriver {
 		);
 	}
 
+	async buildGatewayUrl(actorId: string): Promise<string> {
+		if (this.#metadataPromise) {
+			await this.#metadataPromise;
+		}
+
+		const endpoint = getEndpoint(this.#config);
+		return buildActorGatewayUrl(endpoint, actorId, this.#config.token);
+	}
+
 	async proxyRequest(
 		_c: HonoContext,
 		actorRequest: Request,