rivetkit 2.3.0-rc.9 → 2.3.0

package/src/registry/process-metrics.ts

@@ -0,0 +1,250 @@
+/**
+ * Node.js runtime health metrics.
+ *
+ * Collects JS-internal data (event loop lag, GC, heap, libuv handles,
+ * event loop utilization, CPU) using Node built-ins (`node:perf_hooks`,
+ * `process`, `node:v8`, `PerformanceObserver`) and pushes them across NAPI
+ * into Rust-side prometheus collectors registered with
+ * `rivet_metrics::REGISTRY` so they appear on the existing `/metrics`
+ * endpoint.
+ *
+ * All data collection happens here in TypeScript. The NAPI bridge is pure
+ * type marshalling and the Rust side only registers + stores the metrics.
+ */
+import {
+	monitorEventLoopDelay,
+	PerformanceObserver,
+	performance,
+} from "node:perf_hooks";
+import { getHeapStatistics } from "node:v8";
+import * as napi from "@rivetkit/rivetkit-napi";
+
+type OptionalProcessMetricsNapi = typeof napi & {
+	jsObserveGcDuration?: (kind: string, durationSeconds: number) => void;
+	jsSetEventloopHeartbeatTsMs?: (timestampMs: number) => void;
+	jsSetEventloopLagQuantile?: (
+		quantile: string,
+		valueSeconds: number,
+	) => void;
+	jsSetEventloopUtilization?: (utilization: number) => void;
+	jsAddProcessCpuSeconds?: (mode: string, valueSeconds: number) => void;
+	jsSetProcessResidentMemoryBytes?: (bytes: number) => void;
+	jsSetHeapBytes?: (kind: string, bytes: number) => void;
+	jsSetActiveHandles?: (count: number) => void;
+	jsSetActiveRequests?: (count: number) => void;
+};
+
+type GcPerformanceEntry = {
+	duration: number;
+	detail?: { kind?: number };
+	kind?: number;
+};
+
+const processMetricsNapi = napi as OptionalProcessMetricsNapi;
+
+// Some napi process-metrics symbols may be missing on older native binaries
+// (the auto-generated index.js destructures them as `undefined` if the
+// underlying `.node` was built before they were added). Guard each call so
+// the metrics collection runs as a no-op instead of throwing
+// `TypeError: napi.jsXxx is not a function` on every interval tick.
+function callIfFn<T extends unknown[]>(
+	fn: ((...args: T) => void) | undefined,
+	...args: T
+): void {
+	if (typeof fn === "function") {
+		fn(...args);
+	}
+}
+
+const SCRAPE_INTERVAL_MS = 5_000;
+const HEARTBEAT_INTERVAL_MS = 100;
+const EVENTLOOP_DELAY_RESOLUTION_MS = 20;
+const NS_PER_SECOND = 1e9;
+const US_PER_SECOND = 1e6;
+
+// V8 GC kind bitfield from Node's perf_hooks documentation. A `gc` performance
+// entry's `kind` field is one of these values.
+const GC_KIND_NAMES: Record<number, string> = {
+	1: "minor",
+	2: "major",
+	4: "incremental",
+	8: "weakcb",
+};
+
+interface ProcessMetricsState {
+	scrapeInterval: NodeJS.Timeout;
+	heartbeatInterval: NodeJS.Timeout;
+	gcObserver: PerformanceObserver;
+	eventLoopHistogram: ReturnType<typeof monitorEventLoopDelay>;
+	lastCpuUsage: NodeJS.CpuUsage;
+	lastEventLoopUtilization: ReturnType<
+		typeof performance.eventLoopUtilization
+	>;
+}
+
+let state: ProcessMetricsState | undefined;
+
+export function startProcessMetrics(): void {
+	if (state) {
+		return;
+	}
+
+	const eventLoopHistogram = monitorEventLoopDelay({
+		resolution: EVENTLOOP_DELAY_RESOLUTION_MS,
+	});
+	eventLoopHistogram.enable();
+
+	const gcObserver = new PerformanceObserver((list) => {
+		for (const entry of list.getEntries()) {
+			const gcEntry = entry as GcPerformanceEntry;
+			const kind = gcEntry.detail?.kind ?? gcEntry.kind;
+			if (typeof kind !== "number") continue;
+			const kindName = GC_KIND_NAMES[kind];
+			if (!kindName) continue;
+			// `entry.duration` is in milliseconds; convert to seconds.
+			callIfFn(
+				processMetricsNapi.jsObserveGcDuration,
+				kindName,
+				gcEntry.duration / 1000,
+			);
+		}
+	});
+	gcObserver.observe({ entryTypes: ["gc"], buffered: false });
+
+	const lastCpuUsage = process.cpuUsage();
+	const lastEventLoopUtilization = performance.eventLoopUtilization();
+
+	const heartbeatInterval = setInterval(() => {
+		callIfFn(processMetricsNapi.jsSetEventloopHeartbeatTsMs, Date.now());
+	}, HEARTBEAT_INTERVAL_MS);
+	heartbeatInterval.unref();
+
+	const scrapeInterval = setInterval(() => {
+		try {
+			collectAndPush();
+		} catch {
+			// Collection errors must never bring down the process; metrics
+			// are best-effort.
+		}
+	}, SCRAPE_INTERVAL_MS);
+	scrapeInterval.unref();
+
+	state = {
+		scrapeInterval,
+		heartbeatInterval,
+		gcObserver,
+		eventLoopHistogram,
+		lastCpuUsage,
+		lastEventLoopUtilization,
+	};
+
+	// Emit one snapshot immediately so freshly-scraped instances have data.
+	callIfFn(processMetricsNapi.jsSetEventloopHeartbeatTsMs, Date.now());
+	try {
+		collectAndPush();
+	} catch {
+		// As above; best-effort.
+	}
+}
+
+export function stopProcessMetrics(): void {
+	if (!state) {
+		return;
+	}
+	clearInterval(state.scrapeInterval);
+	clearInterval(state.heartbeatInterval);
+	state.gcObserver.disconnect();
+	state.eventLoopHistogram.disable();
+	state = undefined;
+}
+
+function collectAndPush(): void {
+	if (!state) return;
+
+	// Event loop delay quantiles. `monitorEventLoopDelay()` reports values in
+	// nanoseconds; convert to seconds. Reset after reading so the next window
+	// reflects only the new interval.
+	const hist = state.eventLoopHistogram;
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p50",
+		hist.percentile(50) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p90",
+		hist.percentile(90) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"p99",
+		hist.percentile(99) / NS_PER_SECOND,
+	);
+	callIfFn(
+		processMetricsNapi.jsSetEventloopLagQuantile,
+		"max",
+		hist.max / NS_PER_SECOND,
+	);
+	hist.reset();
+
+	// Event loop utilization delta over the scrape window.
+	const nextElu = performance.eventLoopUtilization();
+	const eluDelta = performance.eventLoopUtilization(
+		nextElu,
+		state.lastEventLoopUtilization,
+	);
+	state.lastEventLoopUtilization = nextElu;
+	callIfFn(
+		processMetricsNapi.jsSetEventloopUtilization,
+		eluDelta.utilization,
+	);
+
+	// CPU usage delta. `process.cpuUsage()` returns microseconds.
+	const nextCpu = process.cpuUsage();
+	const userDeltaUs = nextCpu.user - state.lastCpuUsage.user;
+	const systemDeltaUs = nextCpu.system - state.lastCpuUsage.system;
+	state.lastCpuUsage = nextCpu;
+	if (userDeltaUs > 0) {
+		callIfFn(
+			processMetricsNapi.jsAddProcessCpuSeconds,
+			"user",
+			userDeltaUs / US_PER_SECOND,
+		);
+	}
+	if (systemDeltaUs > 0) {
+		callIfFn(
+			processMetricsNapi.jsAddProcessCpuSeconds,
+			"system",
+			systemDeltaUs / US_PER_SECOND,
+		);
+	}
+
+	// Memory + heap.
+	const mem = process.memoryUsage();
+	callIfFn(processMetricsNapi.jsSetProcessResidentMemoryBytes, mem.rss);
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "used", mem.heapUsed);
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "total", mem.heapTotal);
+	const heapLimit = getHeapStatistics().heap_size_limit;
+	callIfFn(processMetricsNapi.jsSetHeapBytes, "limit", heapLimit);
+
+	// libuv active handles + requests. These are unstable Node internals
+	// guarded behind underscore-prefixed names; if a future Node release
+	// removes them the try/catch above keeps the rest of the collection
+	// alive.
+	const proc = process as unknown as {
+		_getActiveHandles?: () => unknown[];
+		_getActiveRequests?: () => unknown[];
+	};
+	if (typeof proc._getActiveHandles === "function") {
+		callIfFn(
+			processMetricsNapi.jsSetActiveHandles,
+			proc._getActiveHandles().length,
+		);
+	}
+	if (typeof proc._getActiveRequests === "function") {
+		callIfFn(
+			processMetricsNapi.jsSetActiveRequests,
+			proc._getActiveRequests().length,
+		);
+	}
+}

package/src/registry/runtime.ts

@@ -1,5 +1,7 @@
+import { stringifyError } from "@/common/utils";
 import type { SqliteNativeMetrics } from "@/common/database/config";
 import type { RegistryConfig } from "./config";
+import { logger } from "./log";
 
 declare const handleBrand: unique symbol;
 
@@ -225,6 +227,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 +252,8 @@ export interface RuntimeServeConfig {
 	namespace: string;
 	poolName: string;
 	engineBinaryPath?: string;
+	engineHost?: string;
+	enginePort?: number;
 	handleInspectorHttpInRuntime?: boolean;
 	inspectorTestToken?: string;
 	serverlessBasePath?: string;
@@ -399,6 +419,9 @@ export interface CoreRuntime {
 	): void;
 	actorWaitUntil(ctx: ActorContextHandle, promise: Promise<unknown>): void;
 	actorWaitForTrackedShutdownWork(ctx: ActorContextHandle): Promise<boolean>;
+	actorWaitForTrackedShutdownWorkUnbounded(
+		ctx: ActorContextHandle,
+	): Promise<void>;
 	actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void;
 	actorBeginKeepAwake(ctx: ActorContextHandle): number;
 	actorEndKeepAwake(ctx: ActorContextHandle, regionId: number): void;
@@ -491,6 +514,7 @@ export interface CoreRuntime {
 		ctx: ActorContextHandle,
 		names: string[],
 		options?: RuntimeQueueWaitOptions | undefined | null,
+		signal?: CancellationTokenHandle | undefined | null,
 	): Promise<void>;
 	actorQueueEnqueueAndWait(
 		ctx: ActorContextHandle,
@@ -577,9 +601,25 @@ export async function buildServeConfig(
 		serverlessMaxStartPayloadBytes: config.serverless.maxStartPayloadBytes,
 	};
 
-	if (config.startEngine) {
+	// Always best-effort resolve the engine binary path and hand it to the core.
+	// The core alone decides whether to actually spawn a local engine, so JS must
+	// not duplicate that decision here. `loadEnginePath` throws when no binary is
+	// available (remote-only install, unsupported platform, optional deps
+	// skipped); in that case leave it unset and let the core report
+	// `engine.binary_unavailable` only if it actually needs one.
+	try {
 		serveConfig.engineBinaryPath = await loadEnginePath();
+	} catch (error) {
+		// The engine binary could not be resolved. The core still decides whether
+		// it needs to spawn a local engine; if it does, it will fail with
+		// engine.binary_unavailable (auto-download is off in the napi runtime).
+		logger().warn({
+			msg: "could not resolve a local engine binary; if a local engine must be spawned it will fail with engine.binary_unavailable — set RIVET_ENGINE_BINARY_PATH or install the @rivetkit/engine-cli platform package",
+			error: stringifyError(error),
+		});
 	}
+	serveConfig.engineHost = config.engineHost;
+	serveConfig.enginePort = config.enginePort;
 	if (config.test?.enabled) {
 		serveConfig.inspectorTestToken =
 			process.env._RIVET_TEST_INSPECTOR_TOKEN ?? "token";

package/src/registry/wasm-runtime.ts

@@ -32,8 +32,8 @@ import type {
 	RuntimeQueueNextBatchOptions,
 	RuntimeQueueTryNextBatchOptions,
 	RuntimeQueueWaitOptions,
-	RuntimeRequestSaveOpts,
 	RuntimeRegistryRouteResponse,
+	RuntimeRequestSaveOpts,
 	RuntimeServeConfig,
 	RuntimeServerlessRequest,
 	RuntimeServerlessResponseHead,
@@ -519,6 +519,15 @@ export class WasmCoreRuntime implements CoreRuntime {
 		);
 	}
 
+	async actorWaitForTrackedShutdownWorkUnbounded(
+		ctx: ActorContextHandle,
+	): Promise<void> {
+		await callHandle<Promise<void>>(
+			asWasmActorContext(ctx),
+			"waitForTrackedShutdownWorkUnbounded",
+		);
+	}
+
 	actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void {
 		const wasmCtx = asWasmActorContext(ctx);
 		const regionId = callHandle<number>(wasmCtx, "beginKeepAwake");
@@ -764,9 +773,16 @@ export class WasmCoreRuntime implements CoreRuntime {
 		ctx: ActorContextHandle,
 		names: string[],
 		options?: RuntimeQueueWaitOptions | undefined | null,
+		signal?: CancellationTokenHandle | undefined | null,
 	): Promise<void> {
 		const queue = childHandle(asWasmActorContext(ctx), "queue");
-		await callHandleAsync(queue, "waitForNamesAvailable", names, options);
+		await callHandleAsync(
+			queue,
+			"waitForNamesAvailable",
+			names,
+			options,
+			signal,
+		);
 	}
 
 	async actorQueueEnqueueAndWait(

package/src/registry/write-through-proxy.ts

@@ -0,0 +1,40 @@
+import onChange from "@rivetkit/on-change";
+
+/**
+ * Creates a proxy that tracks deep mutations on an object and calls `commit`
+ * after every change. Uses `@rivetkit/on-change` internally, which correctly
+ * detects mutations via methods on Map, Set, Date, TypedArrays, and arrays.
+ *
+ * If the value is not an object (primitive, null, undefined), it is returned
+ * as-is since primitives cannot be proxied or mutated.
+ *
+ * @param value - The root value to watch.
+ * @param commit - Called after every detected mutation with the root object.
+ * @param beforeChange - Called before every mutation with the new value being
+ *   assigned. Throw to reject the change.
+ */
+export function createWriteThroughProxy<T>(
+	value: T,
+	commit: (next: T) => void,
+	beforeChange?: (newValue: unknown) => void,
+): T {
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	return onChange(
+		value as T & Record<string, any>,
+		() => {
+			commit(value);
+		},
+		{
+			// Rejection is throw-based: beforeChange throws to prevent the
+			// mutation. We always return true so on-change applies the change
+			// if beforeChange did not throw.
+			onValidate(_path: string, newValue: unknown) {
+				beforeChange?.(newValue);
+				return true;
+			},
+		},
+	) as T;
+}

package/src/serde.ts

@@ -2,8 +2,8 @@ import * as cbor from "cbor-x";
 import invariant from "invariant";
 import type { VersionedDataHandler } from "vbare";
 import type { z } from "zod/v4";
+import type { Encoding, JsonCompatValue } from "@/common/encoding";
 import { assertUnreachable } from "@/common/utils";
-import type { Encoding } from "@/common/encoding";
 import {
 	encodeJsonCompatValue,
 	jsonParseCompat,
@@ -46,7 +46,7 @@ export function contentTypeForEncoding(encoding: Encoding): string {
 	}
 }
 
-export function encodeCborCompat(value: unknown): Uint8Array {
+export function encodeCborCompat(value: JsonCompatValue): Uint8Array {
 	return cbor.encode(encodeJsonCompatValue(value));
 }
 

package/src/serverless/configure.ts

@@ -1,9 +1,9 @@
 import { convertRegistryConfigToClientConfig } from "@/client/config";
+import { stringifyError } from "@/common/utils";
 import {
 	getDatacenters,
 	updateRunnerConfig,
 } from "@/engine-client/api-endpoints";
-import { stringifyError } from "@/common/utils";
 import type { RegistryConfig } from "@/registry/config";
 import { logger } from "@/registry/log";
 
@@ -16,11 +16,14 @@ function sleep(ms: number): Promise<void> {
 
 function configureTimeoutMs() {
 	const value = process.env.RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS;
-	if (value === undefined || value === "") return DEFAULT_CONFIGURE_TIMEOUT_MS;
+	if (value === undefined || value === "")
+		return DEFAULT_CONFIGURE_TIMEOUT_MS;
 
 	const parsed = Number(value);
 	if (!Number.isFinite(parsed) || parsed < 0) {
-		throw new Error("RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number");
+		throw new Error(
+			"RIVET_SERVERLESS_CONFIGURE_TIMEOUT_MS must be a finite non-negative number",
+		);
 	}
 
 	return parsed;
@@ -40,13 +43,19 @@ export async function configureServerlessPool(
 		attempts += 1;
 		try {
 			if (!config.namespace) {
-				throw new Error("namespace is required for serverless configuration");
+				throw new Error(
+					"namespace is required for serverless configuration",
+				);
 			}
 			if (!config.endpoint) {
-				throw new Error("endpoint is required for serverless configuration");
+				throw new Error(
+					"endpoint is required for serverless configuration",
+				);
 			}
 			if (!config.configurePool) {
-				throw new Error("configurePool is required for serverless configuration");
+				throw new Error(
+					"configurePool is required for serverless configuration",
+				);
 			}
 
 			const customConfig = config.configurePool;
@@ -55,7 +64,9 @@ export async function configureServerlessPool(
 			const poolName = customConfig.name ?? "default";
 			const serverlessToken = config.token ?? config.publicToken;
 			const headers = {
-				...(serverlessToken ? { "x-rivet-token": serverlessToken } : {}),
+				...(serverlessToken
+					? { "x-rivet-token": serverlessToken }
+					: {}),
 				...(customConfig.headers ?? {}),
 			};
 			const serverlessConfig = {

package/src/test/mod.ts

@@ -1,7 +1,7 @@
 import pRetry from "p-retry";
 import type { TestContext } from "vitest";
-import { type Client, createClient } from "@/client/mod";
 import { convertRegistryConfigToClientConfig } from "@/client/config";
+import { type Client, createClient } from "@/client/mod";
 import { getMetadata } from "@/engine-client/api-endpoints";
 import type { Registry } from "@/registry";
 
@@ -14,13 +14,16 @@ async function waitForRegistryReady(registry: Registry<any>): Promise<void> {
 		registry.parseConfig(),
 	);
 
-	await pRetry(async () => {
-		await getMetadata(clientConfig);
-	}, {
-		retries: 20,
-		minTimeout: 50,
-		maxTimeout: 250,
-	});
+	await pRetry(
+		async () => {
+			await getMetadata(clientConfig);
+		},
+		{
+			retries: 20,
+			minTimeout: 50,
+			maxTimeout: 250,
+		},
+	);
 }
 
 export async function setupTest<A extends Registry<any>>(

package/src/utils/endpoint-parser.ts

@@ -1,4 +1,4 @@
-import { z } from "zod/v4";
+import type { z } from "zod/v4";
 
 export interface ParsedEndpoint {
 	endpoint: string;

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 =>

package/src/utils/router.ts

@@ -2,12 +2,12 @@ import { OpenAPIHono } from "@hono/zod-openapi";
 import type { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
 import { cors } from "@/common/cors";
+import { getLogger } from "@/common/log";
 import {
 	handleRouteError,
 	handleRouteNotFound,
 	loggerMiddleware,
 } from "@/common/router";
-import { getLogger } from "@/common/log";
 
 export function logger() {
 	return getLogger("router");

package/src/utils/serve.ts

@@ -1,10 +1,9 @@
-import type { Hono } from "hono";
-import { detectRuntime, stringifyError, type Runtime } from "../utils";
-import { RegistryConfig } from "@/registry/config";
-import { logger } from "@/registry/log";
-
 // TODO: Go back to dynamic import for this
 import getPort from "get-port";
+import type { Hono } from "hono";
+import type { RegistryConfig } from "@/registry/config";
+import { logger } from "@/registry/log";
+import { detectRuntime, type Runtime, stringifyError } from "../utils";
 
 const DEFAULT_PORT = 6421;
 export type ServeStatic =

package/src/utils.ts

@@ -1,6 +1,5 @@
-import { stringifyError } from "@/common/utils";
 import type { Context as HonoContext, Handler as HonoHandler } from "hono";
-import { stringify as uuidstringify } from "uuid";
+import { stringifyError } from "@/common/utils";
 import pkgJson from "../package.json" with { type: "json" };
 import { getLogger } from "./common/log";
 import { assertUnreachable } from "./common/utils";