rivetkit 2.0.36 → 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/config.ts

@@ -16,7 +16,7 @@ import { tryParseEndpoint } from "@/utils/endpoint-parser";
  *
  * In browser: uses current origin + /api/rivet
  *
- * Server-side: uses localhost:6420
+ * Server-side: uses 127.0.0.1:6420
  */
 function getDefaultEndpoint(): string {
 	if (typeof window !== "undefined" && window.location?.origin) {
@@ -38,7 +38,7 @@ export const ClientConfigSchemaBase = z.object({
 	 *
 	 * Can also be set via RIVET_ENDPOINT environment variables.
 	 *
-	 * Defaults to current origin + /api/rivet in browser, or localhost:6420 server-side.
+	 * Defaults to current origin + /api/rivet in browser, or 127.0.0.1:6420 server-side.
 	 */
 	endpoint: z
 		.string()
@@ -88,7 +88,8 @@ export const ClientConfigSchemaBase = z.object({
 		.default(
 			() =>
 				typeof window !== "undefined" &&
-				window?.location?.hostname === "localhost",
+				(window?.location?.hostname === "127.0.0.1" ||
+					window.location?.hostname === "localhost"),
 		),
 });
 
@@ -144,6 +145,7 @@ export function convertRegistryConfigToClientConfig(
 		disableMetadataLookup: true,
 		devtools:
 			typeof window !== "undefined" &&
-			window?.location?.hostname === "localhost",
+			(window?.location?.hostname === "127.0.0.1" ||
+				window?.location?.hostname === "localhost"),
 	};
 }

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/engine-process/constants.ts

@@ -1,2 +1,2 @@
 export const ENGINE_PORT = 6420;
-export const ENGINE_ENDPOINT = `http://localhost:${ENGINE_PORT}`;
+export const ENGINE_ENDPOINT = `http://127.0.0.1:${ENGINE_PORT}`;

package/src/engine-process/mod.ts

@@ -308,7 +308,7 @@ async function checkIfEngineAlreadyRunningOnPort(
 ): Promise<boolean> {
 	let response: Response;
 	try {
-		response = await fetch(`http://localhost:${port}/health`);
+		response = await fetch(`http://127.0.0.1:${port}/health`);
 	} catch (err) {
 		// Nothing is running on this port
 		return false;

package/src/inspector/utils.ts

@@ -56,7 +56,7 @@ export function getInspectorUrl(
 	const endpoint =
 		config.inspector.defaultEndpoint ??
 		(config.managerPort !== 6420
-			? `http://localhost:${managerPort}`
+			? `http://127.0.0.1:${managerPort}`
 			: undefined);
 	if (endpoint) {
 		url.searchParams.set("u", endpoint);

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

@@ -213,11 +213,11 @@ export const RegistryConfigSchema = z
 		// Determine serveManager: default to true in dev mode without endpoint, false otherwise
 		const serveManager = config.serveManager ?? (isDevEnv && !endpoint);
 
-		// In dev mode, fall back to localhost if serving manager
+		// In dev mode, fall back to 127.0.0.1 if serving manager
 		const publicEndpoint =
 			parsedPublicEndpoint?.endpoint ??
-			(isDevEnv && serveManager
-				? `http://localhost:${config.managerPort}`
+			(isDevEnv && (serveManager || config.serverless.spawnEngine)
+				? `http://127.0.0.1:${config.managerPort}`
 				: undefined);
 		// We extract publicNamespace to validate that it matches the backend
 		// namespace (see validation above), not for functional use.
@@ -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,
 						});
 					}