rivetkit 2.3.0-rc.12 → 2.3.0-rc.14

package/src/registry/config/index.ts

@@ -10,7 +10,7 @@ import {
 	queueMetadataKey,
 	workflowStoragePrefix,
 } from "@/actor/keys";
-import { ENGINE_ENDPOINT } from "@/common/engine";
+import { buildEngineEndpoint, ENGINE_HOST, ENGINE_PORT } from "@/common/engine";
 import { type Logger, LogLevelSchema } from "@/common/log";
 import { VERSION } from "@/utils";
 import { tryParseEndpoint } from "@/utils/endpoint-parser";
@@ -20,6 +20,8 @@ import {
 	getRivetkitRuntime,
 	getRivetNamespace,
 	getRivetRunEngine,
+	getRivetRunEngineHost,
+	getRivetRunEnginePort,
 	getRivetRunEngineVersion,
 	getRivetToken,
 	isDev,
@@ -224,6 +226,27 @@ export const RegistryConfigSchema = z
 		 * Starts the full Rust engine process locally.
 		 */
 		startEngine: z.boolean().default(() => getRivetRunEngine()),
+		/**
+		 * @experimental
+		 *
+		 * Host to bind the spawned local engine process to.
+		 */
+		engineHost: z
+			.string()
+			.optional()
+			.default(() => getRivetRunEngineHost() ?? ENGINE_HOST),
+		/**
+		 * @experimental
+		 *
+		 * Port to bind the spawned local engine process to.
+		 */
+		enginePort: z
+			.number()
+			.int()
+			.min(1)
+			.max(65_535)
+			.optional()
+			.default(() => getRivetRunEnginePort() ?? ENGINE_PORT),
 		/** @experimental */
 		engineVersion: z
 			.string()
@@ -312,7 +335,9 @@ export const RegistryConfigSchema = z
 				})
 			: undefined;
 
-		// Can't start a local engine and connect to a remote endpoint.
+		// RIVET_ENDPOINT configures what RivetKit connects to. Use
+		// engineHost/enginePort (or RIVET_RUN_ENGINE_HOST/PORT) to control the
+		// spawned local engine bind address.
 		if (config.startEngine && parsedEndpoint) {
 			ctx.addIssue({
 				code: "custom",
@@ -329,12 +354,17 @@ export const RegistryConfigSchema = z
 			});
 		}
 
-		// Flatten the endpoint and apply defaults for namespace/token
-		// If startEngine is enabled, set endpoint to the engine endpoint.
+		// Flatten the endpoint and apply defaults for namespace/token.
+		const localEngineEndpoint = buildEngineEndpoint(
+			config.engineHost,
+			config.enginePort,
+		);
 		const endpoint = config.startEngine
-			? ENGINE_ENDPOINT
+			? localEngineEndpoint
 			: (parsedEndpoint?.endpoint ??
-				(isDevEnv ? ENGINE_ENDPOINT : undefined));
+				(isDevEnv
+					? buildEngineEndpoint(ENGINE_HOST, ENGINE_PORT)
+					: undefined));
 		const validateServerlessEndpoint = Boolean(
 			config.startEngine || parsedEndpoint,
 		);
@@ -367,7 +397,7 @@ export const RegistryConfigSchema = z
 		// In dev mode, clients connect directly to the local Rivet Engine.
 		const publicEndpoint =
 			parsedPublicEndpoint?.endpoint ??
-			(isDevEnv && config.startEngine ? ENGINE_ENDPOINT : undefined);
+			(isDevEnv && config.startEngine ? endpoint : undefined);
 		// We extract publicNamespace to validate that it matches the backend
 		// namespace (see validation above), not for functional use.
 		const publicNamespace = parsedPublicEndpoint?.namespace;

package/src/registry/index.ts

@@ -1,5 +1,5 @@
 import { Hono } from "hono";
-import { ENGINE_ENDPOINT } from "@/common/engine";
+import { isLocalEngineEndpoint } from "@/common/engine";
 import { configureServerlessPool } from "@/serverless/configure";
 import { detectRuntime, VERSION } from "@/utils";
 import { crossPlatformServe, loadRuntimeServeStatic } from "@/utils/serve";
@@ -700,7 +700,9 @@ export class Registry<A extends RegistryActors> {
 
 		if (config.endpoint) {
 			const endpointType =
-				config.endpoint === ENGINE_ENDPOINT ? "local native" : "remote";
+				config.startEngine || isLocalEngineEndpoint(config.endpoint)
+					? "local native"
+					: "remote";
 			logLine("Endpoint", `${config.endpoint} (${endpointType})`);
 		}
 

package/src/registry/native.ts

@@ -31,6 +31,7 @@ import {
 } from "@/client/client";
 import { convertRegistryConfigToClientConfig } from "@/client/config";
 import { HEADER_CONN_PARAMS } from "@/common/actor-router-consts";
+import { isLocalEngineEndpoint } from "@/common/engine";
 import type { AnyDatabaseProvider } from "@/common/database/config";
 import { wrapJsNativeDatabase } from "@/common/database/native-database";
 import { assertJsonCompatValue, type JsonCompatValue } from "@/common/encoding";
@@ -71,12 +72,15 @@ import type {
 	RuntimeActorConfig,
 	RuntimeBytes,
 	RuntimeHttpResponse,
+	RuntimeInspectorTabEntry,
 	RuntimeQueueMessage,
 	RuntimeServeConfig,
 	RuntimeStateDeltaPayload,
 	WebSocketHandle,
 } from "./runtime";
 import { loadWasmRuntime } from "./wasm-runtime";
+import nodeFs from "node:fs";
+import nodePath from "node:path";
 import { createWriteThroughProxy } from "./write-through-proxy";
 
 const textEncoder = new TextEncoder();
@@ -627,6 +631,14 @@ function encodeValue(value: unknown): RuntimeBytes {
 	return encodeCborCompat(value as JsonCompatValue);
 }
 
+function normalizeArgs(value: unknown): unknown[] {
+	return Array.isArray(value)
+		? value
+		: value === undefined || value === null
+			? []
+			: [value];
+}
+
 function unwrapTsfnPayload<T>(error: unknown, payload: T): T {
 	if (error !== null && error !== undefined) {
 		throw error;
@@ -1093,11 +1105,7 @@ function wrapNativeCallback<Args extends Array<unknown>, Result>(
 
 function decodeArgs(value?: RuntimeBytes | null): unknown[] {
 	const decoded = decodeValue<unknown>(value);
-	return Array.isArray(decoded)
-		? decoded
-		: decoded === undefined
-			? []
-			: [decoded];
+	return normalizeArgs(decoded);
 }
 
 function buildRequest(init: {
@@ -3323,9 +3331,87 @@ function buildActorConfig(
 		actions: Object.keys((config.actions ?? {}) as Record<string, unknown>)
 			.sort()
 			.map((name) => ({ name })),
+		inspectorTabs: buildInspectorTabs(config.inspector),
 	};
 }
 
+function buildInspectorTabs(
+	inspector: unknown,
+): Array<RuntimeInspectorTabEntry> | undefined {
+	if (!inspector || typeof inspector !== "object") return undefined;
+	const tabs = (inspector as { tabs?: unknown }).tabs;
+	if (!Array.isArray(tabs) || tabs.length === 0) return undefined;
+	return tabs.map((raw) => {
+		const entry = raw as {
+			id: string;
+			label?: string;
+			source?: string;
+			icon?: string;
+			hidden?: boolean;
+		};
+		if (entry.hidden === true) {
+			return { id: entry.id, hidden: true };
+		}
+		// Resolve the author's source path against the current working
+		// directory so the Rust runtime gets an absolute path. The author
+		// runs the actor process from their project root by convention.
+		const resolved =
+			entry.source !== undefined
+				? nodePath.resolve(entry.source)
+				: undefined;
+		if (resolved !== undefined) {
+			validateInspectorTabSource(entry.id, resolved);
+		}
+		return {
+			id: entry.id,
+			label: entry.label,
+			icon: entry.icon,
+			source: resolved,
+		};
+	});
+}
+
+function validateInspectorTabSource(tabId: string, resolved: string): void {
+	// Catch obviously dangerous misconfigurations at registry construction
+	// rather than silently exposing the wrong subtree over the unauthenticated
+	// `/inspector/custom-tabs/<id>/*` route. Fail loudly so misconfigured
+	// actors never start.
+	if (resolved === nodePath.parse(resolved).root) {
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source resolves to the filesystem root (${resolved}). ` +
+				"Point it at the tab's own static-asset directory instead.",
+		);
+	}
+	let stat: import("node:fs").Stats;
+	try {
+		stat = nodeFs.statSync(resolved);
+	} catch (err) {
+		const code = (err as NodeJS.ErrnoException)?.code;
+		if (code === "ENOENT") {
+			throw new Error(
+				`inspector.tabs[id="${tabId}"].source (${resolved}) does not exist.`,
+			);
+		}
+		if (code === "EACCES") {
+			throw new Error(
+				`inspector.tabs[id="${tabId}"].source (${resolved}) is not readable (EACCES).`,
+			);
+		}
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source (${resolved}) could not be stat'd: ${
+				(err as Error)?.message ?? err
+			}`,
+		);
+	}
+	if (!stat.isDirectory()) {
+		throw new Error(
+			`inspector.tabs[id="${tabId}"].source (${resolved}) must be a directory, got ${
+				stat.isFile() ? "file" : "non-directory"
+			}.`,
+		);
+	}
+}
+
 export function buildNativeFactory(
 	runtime: CoreRuntime,
 	registryConfig: RegistryConfig,
@@ -3756,14 +3842,38 @@ export function buildNativeFactory(
 						404,
 					);
 				}
-				const body = (await jsRequest.json()) as { args?: unknown[] };
+				const body = (await jsRequest.json()) as {
+					args?: unknown;
+					properties?: unknown;
+				};
+				if (body.args !== undefined && body.properties !== undefined) {
+					return jsonResponse(
+						{ error: "use either args or properties, not both" },
+						{ status: 400 },
+					);
+				}
+				if (
+					body.properties !== undefined &&
+					(body.properties === null ||
+						typeof body.properties !== "object" ||
+						Array.isArray(body.properties))
+				) {
+					return jsonResponse(
+						{ error: "properties must be an object" },
+						{ status: 400 },
+					);
+				}
+				const args =
+					body.properties !== undefined
+						? [body.properties]
+						: normalizeArgs(body.args);
 				try {
 					const output = await action(
 						actorCtx,
 						...validateActionArgs(
 							schemaConfig.actionInputSchemas,
 							actionName,
-							body.args ?? [],
+							args,
 						),
 					);
 					return jsonResponse({ output });
@@ -4647,9 +4757,16 @@ export async function buildServeConfig(
 		serverlessMaxStartPayloadBytes: config.serverless.maxStartPayloadBytes,
 	};
 
-	if (config.startEngine) {
+	// Provide the engine binary path whenever the core will manage a local
+	// engine. The core auto-spawns the engine for any loopback endpoint (its
+	// EngineSpawnMode::Auto), not only when `startEngine` is set, so gating the
+	// binary path on `startEngine` alone leaves auto-spawn unable to locate the
+	// npm-installed engine binary and fail with engine.binary_unavailable.
+	if (config.startEngine || isLocalEngineEndpoint(config.endpoint)) {
 		const { getEnginePath } = await loadEngineCli();
 		serveConfig.engineBinaryPath = getEnginePath();
+		serveConfig.engineHost = config.engineHost;
+		serveConfig.enginePort = config.enginePort;
 	}
 	if (config.test?.enabled) {
 		serveConfig.inspectorTestToken =

package/src/registry/runtime.ts

@@ -1,4 +1,5 @@
 import type { SqliteNativeMetrics } from "@/common/database/config";
+import { isLocalEngineEndpoint } from "@/common/engine";
 import type { RegistryConfig } from "./config";
 
 declare const handleBrand: unique symbol;
@@ -225,6 +226,22 @@ export interface RuntimeActorConfig {
 	preloadMaxWorkflowBytes?: number;
 	preloadMaxConnectionsBytes?: number;
 	actions?: Array<{ name: string }>;
+	inspectorTabs?: Array<RuntimeInspectorTabEntry>;
+}
+
+export interface RuntimeInspectorTabEntry {
+	id: string;
+	/** Required for custom entries; omitted for built-in hides. */
+	label?: string;
+	/**
+	 * Required for custom entries — absolute path to the source directory.
+	 * Resolved on the TS side before being handed to the runtime.
+	 */
+	source?: string;
+	/** Optional icon id for custom entries. */
+	icon?: string;
+	/** Set to true for built-in hide entries. */
+	hidden?: boolean;
 }
 
 export interface RuntimeServeConfig {
@@ -234,6 +251,8 @@ export interface RuntimeServeConfig {
 	namespace: string;
 	poolName: string;
 	engineBinaryPath?: string;
+	engineHost?: string;
+	enginePort?: number;
 	handleInspectorHttpInRuntime?: boolean;
 	inspectorTestToken?: string;
 	serverlessBasePath?: string;
@@ -581,8 +600,15 @@ export async function buildServeConfig(
 		serverlessMaxStartPayloadBytes: config.serverless.maxStartPayloadBytes,
 	};
 
-	if (config.startEngine) {
+	// Provide the engine binary path whenever the core will manage a local
+	// engine. The core auto-spawns the engine for any loopback endpoint (its
+	// EngineSpawnMode::Auto), not only when `startEngine` is set, so gating the
+	// binary path on `startEngine` alone leaves auto-spawn unable to locate the
+	// npm-installed engine binary and fail with engine.binary_unavailable.
+	if (config.startEngine || isLocalEngineEndpoint(config.endpoint)) {
 		serveConfig.engineBinaryPath = await loadEnginePath();
+		serveConfig.engineHost = config.engineHost;
+		serveConfig.enginePort = config.enginePort;
 	}
 	if (config.test?.enabled) {
 		serveConfig.inspectorTestToken =

package/src/utils/env-vars.ts

@@ -22,6 +22,12 @@ export const getRivetTotalSlots = (): number | undefined => {
 };
 export const getRivetRunEngine = (): boolean =>
 	getEnvUniversal("RIVET_RUN_ENGINE") === "1";
+export const getRivetRunEngineHost = (): string | undefined =>
+	getEnvUniversal("RIVET_RUN_ENGINE_HOST");
+export const getRivetRunEnginePort = (): number | undefined => {
+	const value = getEnvUniversal("RIVET_RUN_ENGINE_PORT");
+	return value !== undefined ? parseInt(value, 10) : undefined;
+};
 export const getRivetRunEngineVersion = (): string | undefined =>
 	getEnvUniversal("RIVET_RUN_ENGINE_VERSION");
 export const getRivetEnvoyKind = (): string | undefined =>