rivetkit 2.0.37 → 2.0.38

package/src/client/actor-query.ts

@@ -1,7 +1,9 @@
 import type { Context as HonoContext } from "hono";
 import * as errors from "@/actor/errors";
+import { stringifyError } from "@/common/utils";
 import type { ManagerDriver } from "@/driver-helpers/mod";
 import type { ActorQuery } from "@/manager/protocol/query";
+import { ActorSchedulingError } from "./errors";
 import { logger } from "./log";
 
 /**
@@ -63,3 +65,48 @@ export async function queryActor(
 	logger().debug({ msg: "actor query result", actorId: actorOutput.actorId });
 	return { actorId: actorOutput.actorId };
 }
+
+/**
+ * Extract the actor name from a query.
+ */
+export function getActorNameFromQuery(query: ActorQuery): string {
+	if ("getForId" in query) return query.getForId.name;
+	if ("getForKey" in query) return query.getForKey.name;
+	if ("getOrCreateForKey" in query) return query.getOrCreateForKey.name;
+	if ("create" in query) return query.create.name;
+	throw new errors.InvalidRequest("Invalid query format");
+}
+
+/**
+ * Fetch actor details and check for scheduling errors.
+ */
+export async function checkForSchedulingError(
+	group: string,
+	code: string,
+	actorId: string,
+	query: ActorQuery,
+	driver: ManagerDriver,
+): Promise<ActorSchedulingError | null> {
+	const name = getActorNameFromQuery(query);
+
+	try {
+		const actor = await driver.getForId({ name, actorId });
+
+		if (actor?.error) {
+			logger().info({
+				msg: "found actor scheduling error",
+				actorId,
+				error: actor.error,
+			});
+			return new ActorSchedulingError(group, code, actorId, actor.error);
+		}
+	} catch (err) {
+		logger().warn({
+			msg: "failed to fetch actor details for scheduling error check",
+			actorId,
+			error: stringifyError(err),
+		});
+	}
+
+	return null;
+}

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/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/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";
 
@@ -97,5 +95,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/mod.ts

@@ -81,9 +81,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,
 						});
 					}
 

package/src/serverless/router.test.ts

@@ -26,6 +26,12 @@ describe("normalizeEndpointUrl", () => {
 		);
 	});
 
+	test("normalizes IPv6 loopback [::1] to localhost", () => {
+		expect(normalizeEndpointUrl("http://[::1]:6420")).toBe(
+			"http://localhost:6420/",
+		);
+	});
+
 	test("preserves path without trailing slash", () => {
 		expect(normalizeEndpointUrl("http://example.com/api/v1")).toBe(
 			"http://example.com/api/v1",
@@ -69,6 +75,50 @@ describe("normalizeEndpointUrl", () => {
 	test("returns null for empty string", () => {
 		expect(normalizeEndpointUrl("")).toBeNull();
 	});
+
+	describe("regional endpoint normalization", () => {
+		test("normalizes api-us-west-1.rivet.dev to api.rivet.dev", () => {
+			expect(normalizeEndpointUrl("https://api-us-west-1.rivet.dev")).toBe(
+				"https://api.rivet.dev/",
+			);
+		});
+
+		test("normalizes api-lax.staging.rivet.dev to api.staging.rivet.dev", () => {
+			expect(
+				normalizeEndpointUrl("https://api-lax.staging.rivet.dev"),
+			).toBe("https://api.staging.rivet.dev/");
+		});
+
+		test("preserves api.rivet.dev unchanged", () => {
+			expect(normalizeEndpointUrl("https://api.rivet.dev")).toBe(
+				"https://api.rivet.dev/",
+			);
+		});
+
+		test("does not normalize non-api prefixed hostnames", () => {
+			expect(normalizeEndpointUrl("https://foo-bar.rivet.dev")).toBe(
+				"https://foo-bar.rivet.dev/",
+			);
+		});
+
+		test("does not normalize non-rivet.dev domains", () => {
+			expect(normalizeEndpointUrl("https://api-us-west-1.example.com")).toBe(
+				"https://api-us-west-1.example.com/",
+			);
+		});
+
+		test("preserves path when normalizing regional endpoint", () => {
+			expect(
+				normalizeEndpointUrl("https://api-us-west-1.rivet.dev/v1/actors"),
+			).toBe("https://api.rivet.dev/v1/actors");
+		});
+
+		test("preserves port when normalizing regional endpoint", () => {
+			expect(
+				normalizeEndpointUrl("https://api-us-west-1.rivet.dev:8080"),
+			).toBe("https://api.rivet.dev:8080/");
+		});
+	});
 });
 
 describe("endpointsMatch", () => {
@@ -102,6 +152,12 @@ describe("endpointsMatch", () => {
 		).toBe(true);
 	});
 
+	test("matches localhost and IPv6 loopback [::1]", () => {
+		expect(
+			endpointsMatch("http://localhost:6420", "http://[::1]:6420"),
+		).toBe(true);
+	});
+
 	test("does not match different hosts", () => {
 		expect(
 			endpointsMatch("http://localhost:6420", "http://example.com:6420"),
@@ -130,4 +186,114 @@ describe("endpointsMatch", () => {
 		expect(endpointsMatch("not-a-url", "not-a-url")).toBe(true);
 		expect(endpointsMatch("not-a-url", "different")).toBe(false);
 	});
+
+	describe("regional endpoint matching", () => {
+		test("matches api.rivet.dev with api-us-west-1.rivet.dev", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev",
+					"https://api-us-west-1.rivet.dev",
+				),
+			).toBe(true);
+		});
+
+		test("matches api-us-west-1.rivet.dev with api.rivet.dev (reverse order)", () => {
+			expect(
+				endpointsMatch(
+					"https://api-us-west-1.rivet.dev",
+					"https://api.rivet.dev",
+				),
+			).toBe(true);
+		});
+
+		test("matches api.staging.rivet.dev with api-lax.staging.rivet.dev", () => {
+			expect(
+				endpointsMatch(
+					"https://api.staging.rivet.dev",
+					"https://api-lax.staging.rivet.dev",
+				),
+			).toBe(true);
+		});
+
+		test("matches api-lax.staging.rivet.dev with api.staging.rivet.dev (reverse order)", () => {
+			expect(
+				endpointsMatch(
+					"https://api-lax.staging.rivet.dev",
+					"https://api.staging.rivet.dev",
+				),
+			).toBe(true);
+		});
+
+		test("matches with paths", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev/v1/actors",
+					"https://api-us-west-1.rivet.dev/v1/actors",
+				),
+			).toBe(true);
+		});
+
+		test("does not match different domains", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev",
+					"https://api-us-west-1.example.com",
+				),
+			).toBe(false);
+		});
+
+		test("does not match different protocols", () => {
+			expect(
+				endpointsMatch(
+					"http://api.rivet.dev",
+					"https://api-us-west-1.rivet.dev",
+				),
+			).toBe(false);
+		});
+
+		test("does not match different paths", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev/v1",
+					"https://api-us-west-1.rivet.dev/v2",
+				),
+			).toBe(false);
+		});
+
+		test("does not match different ports", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev:8080",
+					"https://api-us-west-1.rivet.dev:9090",
+				),
+			).toBe(false);
+		});
+
+		test("matches with same port", () => {
+			expect(
+				endpointsMatch(
+					"https://api.rivet.dev:8080",
+					"https://api-us-west-1.rivet.dev:8080",
+				),
+			).toBe(true);
+		});
+
+		test("does not match non-api prefixed hosts", () => {
+			expect(
+				endpointsMatch(
+					"https://foo.rivet.dev",
+					"https://foo-us-west-1.rivet.dev",
+				),
+			).toBe(false);
+		});
+
+		test("does not match api.staging.rivet.dev with api-us-west-1.rivet.dev (different base domains)", () => {
+			expect(
+				endpointsMatch(
+					"https://api.staging.rivet.dev",
+					"https://api-us-west-1.rivet.dev",
+				),
+			).toBe(false);
+		});
+	});
 });

package/src/serverless/router.ts

@@ -124,7 +124,8 @@ export function buildServerlessRouter(
 
 /**
  * Normalizes a URL for comparison by extracting protocol, host, port, and pathname.
- * Normalizes 127.0.0.1 and 0.0.0.0 to localhost for consistent comparison.
+ * Normalizes loopback addresses (127.0.0.1, 0.0.0.0, ::1) to localhost for consistent comparison.
+ * Normalizes regional endpoints (api-*.domain) to base endpoints (api.domain).
  * Returns null if the URL is invalid.
  */
 export function normalizeEndpointUrl(url: string): string | null {
@@ -133,13 +134,20 @@ export function normalizeEndpointUrl(url: string): string | null {
 		// Normalize pathname by removing trailing slash (except for root)
 		const pathname =
 			parsed.pathname === "/" ? "/" : parsed.pathname.replace(/\/+$/, "");
+
 		// Normalize loopback addresses to localhost
-		const hostname =
-			parsed.hostname === "127.0.0.1" || parsed.hostname === "0.0.0.0"
-				? "localhost"
-				: parsed.hostname;
+		let hostname = isLoopbackAddress(parsed.hostname)
+			? "localhost"
+			: parsed.hostname;
+
+		// Normalize regional endpoints (api-region.domain) to base endpoints (api.domain)
+		// HACK: This is specific to Rivet Cloud and will not work for self-hosted
+		// engines with different regional endpoint naming conventions.
+		hostname = normalizeRegionalHostname(hostname);
+
 		// Reconstruct host with normalized hostname and port
 		const host = parsed.port ? `${hostname}:${parsed.port}` : hostname;
+
 		// Reconstruct normalized URL with protocol, host, and pathname
 		return `${parsed.protocol}//${host}${pathname}`;
 	} catch {
@@ -147,6 +155,39 @@ export function normalizeEndpointUrl(url: string): string | null {
 	}
 }
 
+/**
+ * Normalizes regional hostnames (api-region.domain) to base hostnames (api.domain).
+ * Only applies to rivet.dev domains.
+ *
+ * Examples:
+ * - api-us-west-1.rivet.dev -> api.rivet.dev
+ * - api-lax.staging.rivet.dev -> api.staging.rivet.dev
+ * - api.rivet.dev -> api.rivet.dev (unchanged)
+ * - api-us-west-1.example.com -> api-us-west-1.example.com (unchanged, not rivet.dev)
+ * - foo-bar.rivet.dev -> foo-bar.rivet.dev (unchanged, not api- prefix)
+ */
+function normalizeRegionalHostname(hostname: string): string {
+	// Only apply to rivet.dev domains
+	if (!hostname.endsWith(".rivet.dev")) {
+		return hostname;
+	}
+
+	if (!hostname.startsWith("api-")) {
+		return hostname;
+	}
+
+	// Find the first dot after "api-"
+	const withoutPrefix = hostname.slice(4); // Remove "api-"
+	const firstDotIndex = withoutPrefix.indexOf(".");
+	if (firstDotIndex === -1) {
+		return hostname;
+	}
+
+	// Extract the domain part and prepend "api."
+	const domain = withoutPrefix.slice(firstDotIndex + 1);
+	return `api.${domain}`;
+}
+
 /**
  * Compares two endpoint URLs after normalization.
  * Returns true if they match (same protocol, host, port, and path).
@@ -160,3 +201,15 @@ export function endpointsMatch(a: string, b: string): boolean {
 	}
 	return normalizedA === normalizedB;
 }
+
+/**
+ * Checks if a hostname is a loopback address that should be normalized to localhost.
+ */
+function isLoopbackAddress(hostname: string): boolean {
+	return (
+		hostname === "127.0.0.1" ||
+		hostname === "0.0.0.0" ||
+		hostname === "::1" ||
+		hostname === "[::1]"
+	);
+}

package/src/utils/env-vars.ts

@@ -1,4 +1,7 @@
-// TODO: briefly document this file is used for consolidating all env vars that affect rivet's behavior
+// This file consolidates all environment variables that affect RivetKit's behavior.
+//
+// IMPORTANT: When adding or modifying environment variables here, also update the
+// documentation at: docs/general/registry-configuration.mdx
 
 import { getEnvUniversal } from "@/utils";