rivetkit 2.0.42 → 2.1.0-rc.1

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

@@ -1,11 +1,11 @@
-import { serve as honoServe } from "@hono/node-server";
-import { createNodeWebSocket } from "@hono/node-ws";
 import { createServer } from "node:net";
 import { fileURLToPath } from "node:url";
+import { serve as honoServe } from "@hono/node-server";
+import { createNodeWebSocket } from "@hono/node-ws";
 import invariant from "invariant";
-import { buildManagerRouter } from "@/manager/router";
-import { createFileSystemOrMemoryDriver } from "@/drivers/file-system/mod";
 import { logger } from "@/driver-test-suite/log";
+import { createFileSystemOrMemoryDriver } from "@/drivers/file-system/mod";
+import { buildManagerRouter } from "@/manager/router";
 import { registry } from "../../fixtures/driver-test-suite/registry";
 
 export interface ServeTestSuiteResult {
@@ -74,10 +74,9 @@ export async function serveTestSuite(): Promise<ServeTestSuiteResult> {
 		publicEndpoint: `http://127.0.0.1:${port}`,
 	};
 
-	const driver = await createFileSystemOrMemoryDriver(
-		true,
-		`/tmp/rivetkit-test-suite-${crypto.randomUUID()}`,
-	);
+	const driver = await createFileSystemOrMemoryDriver(true, {
+		path: `/tmp/rivetkit-test-suite-${crypto.randomUUID()}`,
+	});
 	registry.config.driver = driver;
 
 	let upgradeWebSocket: any;
@@ -114,7 +113,9 @@ export async function serveTestSuite(): Promise<ServeTestSuiteResult> {
 		namespace: "default",
 		runnerName: "default",
 		close: async () => {
-			await new Promise((resolve) => server.close(() => resolve(undefined)));
+			await new Promise((resolve) =>
+				server.close(() => resolve(undefined)),
+			);
 		},
 	};
 }

package/src/test/mod.ts

@@ -1,4 +1,3 @@
-import { createServer } from "node:net";
 import { serve as honoServe } from "@hono/node-server";
 import { createNodeWebSocket } from "@hono/node-ws";
 import invariant from "invariant";
@@ -24,9 +23,9 @@ export async function setupTest<A extends Registry<any>>(
 	registry.config.test = { ...registry.config.test, enabled: true };
 
 	// Create driver
-	const driver = await createFileSystemOrMemoryDriver(
+	const driver = createFileSystemOrMemoryDriver(
 		true,
-		`/tmp/rivetkit-test-${crypto.randomUUID()}`,
+		{ path: `/tmp/rivetkit-test-${crypto.randomUUID()}` },
 	);
 
 	// Build driver config
@@ -42,6 +41,8 @@ export async function setupTest<A extends Registry<any>>(
 	const parsedConfig = registry.parseConfig();
 	const managerDriver = driver.manager?.(parsedConfig);
 	invariant(managerDriver, "missing manager driver");
+	const getUpgradeWebSocket = () => upgradeWebSocket;
+	managerDriver.setGetUpgradeWebSocket(getUpgradeWebSocket);
 	// const internalClient = createClientWithDriver(
 	// 	managerDriver,
 	// 	ClientConfigSchema.parse({}),
@@ -49,7 +50,7 @@ export async function setupTest<A extends Registry<any>>(
 	const { router } = buildManagerRouter(
 		parsedConfig,
 		managerDriver,
-		() => upgradeWebSocket!,
+		getUpgradeWebSocket,
 	);
 
 	// Inject WebSocket
@@ -58,17 +59,24 @@ export async function setupTest<A extends Registry<any>>(
 
 	// TODO: I think this whole function is fucked, we should probably switch to calling registry.serve() directly
 	// Start server
-	const port = await getPort();
 	const server = honoServe({
 		fetch: router.fetch,
 		hostname: "127.0.0.1",
-		port,
+		port: 0,
 	});
+	if (!server.listening) {
+		await new Promise<void>((resolve) => {
+			server.once("listening", () => resolve());
+		});
+	}
 	invariant(
 		nodeWebSocket.injectWebSocket !== undefined,
 		"should have injectWebSocket",
 	);
 	nodeWebSocket.injectWebSocket(server);
+	const address = server.address();
+	invariant(address && typeof address !== "string", "missing server address");
+	const port = address.port;
 	const endpoint = `http://127.0.0.1:${port}`;
 
 	logger().info({ msg: "test server listening", port });
@@ -83,58 +91,9 @@ export async function setupTest<A extends Registry<any>>(
 		endpoint,
 		namespace: "default",
 		runnerName: "default",
+		disableMetadataLookup: true,
 	});
 	c.onTestFinished(async () => await client.dispose());
 
 	return { client };
 }
-
-export async function getPort(): Promise<number> {
-	// Pick random port between 10000 and 65535 (avoiding well-known and registered ports)
-	const MIN_PORT = 10000;
-	const MAX_PORT = 65535;
-	const getRandomPort = () =>
-		Math.floor(Math.random() * (MAX_PORT - MIN_PORT + 1)) + MIN_PORT;
-
-	let port = getRandomPort();
-	let maxAttempts = 10;
-
-	while (maxAttempts > 0) {
-		try {
-			// Try to create a server on the port to check if it's available
-			const server = await new Promise<any>((resolve, reject) => {
-				const server = createServer();
-
-				server.once("error", (err: Error & { code?: string }) => {
-					if (err.code === "EADDRINUSE") {
-						reject(new Error(`Port ${port} is in use`));
-					} else {
-						reject(err);
-					}
-				});
-
-				server.once("listening", () => {
-					resolve(server);
-				});
-
-				server.listen(port);
-			});
-
-			// Close the server since we're just checking availability
-			await new Promise<void>((resolve) => {
-				server.close(() => resolve());
-			});
-
-			return port;
-		} catch (err) {
-			// If port is in use, try a different one
-			maxAttempts--;
-			if (maxAttempts <= 0) {
-				break;
-			}
-			port = getRandomPort();
-		}
-	}
-
-	throw new Error("Could not find an available port after multiple attempts");
-}

package/src/utils/endpoint-parser.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import type { z } from "zod";
+import type { z } from "zod/v4";
 import { tryParseEndpoint } from "./endpoint-parser";
 
 // Helper to create a mock Zod refinement context for testing

package/src/utils/endpoint-parser.ts

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

package/src/utils/env-vars.ts

@@ -1,7 +1,7 @@
 // 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
+// documentation at: website/src/content/docs/general/environment-variables.mdx
 
 import { getEnvUniversal } from "@/utils";
 
@@ -44,6 +44,8 @@ export const getRivetkitInspectorToken = (): string | undefined =>
 	getEnvUniversal("RIVET_INSPECTOR_TOKEN");
 export const getRivetkitInspectorDisable = (): boolean =>
 	getEnvUniversal("RIVET_INSPECTOR_DISABLE") === "1";
+export const getRivetkitStoragePath = (): string | undefined =>
+	getEnvUniversal("RIVETKIT_STORAGE_PATH");
 
 // Logging configuration
 // DEPRECATED: LOG_LEVEL will be removed in a future version
@@ -65,3 +67,12 @@ export const getNodeEnv = (): string | undefined => getEnvUniversal("NODE_ENV");
 export const getNextPhase = (): string | undefined =>
 	getEnvUniversal("NEXT_PHASE");
 export const isDev = (): boolean => getNodeEnv() !== "production";
+
+// Experimental
+/**
+ * Enables experimental OTel tracing for Rivet Actors.
+ *
+ * When disabled, actors use an in-memory no-op traces implementation.
+ */
+export const getRivetExperimentalOtel = (): boolean =>
+	getEnvUniversal("RIVET_EXPERIMENTAL_OTEL") === "1";

package/src/utils/node.ts

@@ -16,13 +16,14 @@ let nodePath: typeof import("node:path") | undefined;
 let nodeOs: typeof import("node:os") | undefined;
 let nodeChildProcess: typeof import("node:child_process") | undefined;
 let nodeStream: typeof import("node:stream/promises") | undefined;
+let nodeUrl: typeof import("node:url") | undefined;
 
 let hasImportedDependencies = false;
 
 // Helper to get a require function that works in both CommonJS and ESM.
 // We use require() instead of await import() because registry.start() cannot
 // be async and needs immediate access to Node.js modules during setup.
-function getRequireFn() {
+export function getRequireFn() {
 	// TODO: This causes issues in tsup
 	// CommonJS context - use global require
 	// if (typeof require !== "undefined") {
@@ -62,7 +63,7 @@ export function importNodeDependencies(): void {
 		nodeStream = requireFn(
 			/* webpackIgnore: true */ "node:stream/promises",
 		);
-
+		nodeUrl = requireFn(/* webpackIgnore: true */ "node:url");
 		hasImportedDependencies = true;
 	} catch (err) {
 		console.warn(
@@ -163,3 +164,15 @@ export function getNodeStream(): typeof import("node:stream/promises") {
 	}
 	return nodeStream;
 }
+
+/**
+ * Gets the Node.js url module lazily.
+ */
+export function getNodeUrl(): typeof import("node:url") {
+	if (!nodeUrl) {
+		throw new Error(
+			"Node url module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeUrl;
+}

package/src/utils.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, test } from "vitest";
+import { joinSignals } from "./utils";
+
+describe("joinSignals", () => {
+	test("returns a non-aborted signal when no inputs are provided", () => {
+		const signal = joinSignals();
+		expect(signal.aborted).toBe(false);
+	});
+
+	test("returns the same signal when only one input is provided", () => {
+		const controller = new AbortController();
+		const signal = joinSignals(controller.signal);
+		expect(signal).toBe(controller.signal);
+	});
+
+	test("aborts immediately when any input signal is already aborted", () => {
+		const controllerA = new AbortController();
+		const controllerB = new AbortController();
+		controllerA.abort("already-aborted");
+
+		const signal = joinSignals(controllerA.signal, controllerB.signal);
+		expect(signal.aborted).toBe(true);
+	});
+
+	test("aborts when one of the joined signals aborts", () => {
+		const controllerA = new AbortController();
+		const controllerB = new AbortController();
+		const signal = joinSignals(controllerA.signal, controllerB.signal);
+
+		expect(signal.aborted).toBe(false);
+		controllerB.abort("stopped");
+		expect(signal.aborted).toBe(true);
+	});
+});

package/src/utils.ts

@@ -1,11 +1,103 @@
-export { stringifyError } from "@/common/utils";
-export { assertUnreachable } from "./common/utils";
-
+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";
+
+/** @experimental */
+export { stringifyError };
+
+/** @experimental */
+export { assertUnreachable };
+
+/**
+ * Joins multiple abort signals into one.
+ *
+ * The returned signal aborts when the first input signal aborts.
+ * Uses `AbortSignal.any(...)` when available, with a runtime fallback.
+ *
+ * @experimental
+ */
+export function joinSignals(
+	...signals: Array<AbortSignal | undefined | null>
+): AbortSignal {
+	const validSignals = signals.filter(
+		(signal): signal is AbortSignal => signal != null,
+	);
+
+	if (validSignals.length === 0) {
+		return new AbortController().signal;
+	}
+
+	if (validSignals.length === 1) {
+		return validSignals[0];
+	}
+
+	const signalAny = (
+		AbortSignal as typeof AbortSignal & {
+			any?: (signals: AbortSignal[]) => AbortSignal;
+		}
+	).any;
+	if (typeof signalAny === "function") {
+		return signalAny(validSignals);
+	}
+
+	const controller = new AbortController();
+	const cleanups: Array<() => void> = [];
+
+	const abortWithSignal = (signal: AbortSignal) => {
+		if (controller.signal.aborted) {
+			return;
+		}
+
+		for (const cleanup of cleanups) {
+			cleanup();
+		}
+
+		const reason = (signal as AbortSignal & { reason?: unknown }).reason;
+		controller.abort(reason);
+	};
+
+	for (const signal of validSignals) {
+		if (signal.aborted) {
+			abortWithSignal(signal);
+			break;
+		}
+
+		const onAbort = () => abortWithSignal(signal);
+		signal.addEventListener("abort", onAbort, { once: true });
+		cleanups.push(() => signal.removeEventListener("abort", onAbort));
+	}
+
+	return controller.signal;
+}
+
+/**
+ * Returns a promise that resolves after the given number of milliseconds.
+ *
+ * @experimental
+ */
+export function sleep(ms: number): Promise<void> {
+	return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Creates a fixed-rate interval tick function that can be awaited in a loop.
+ *
+ * @example
+ * const tick = interval(100);
+ * while (!c.aborted) {
+ *   await tick();
+ *   if (c.aborted) break;
+ *   // ... game logic
+ * }
+ *
+ * @experimental
+ */
+export function interval(ms: number): () => Promise<void> {
+	return () => sleep(ms);
+}
 
 export const VERSION = pkgJson.version;
 
@@ -15,6 +107,11 @@ function logger() {
 	return getLogger("utils");
 }
 
+/**
+ * Builds the HTTP user agent used by this library.
+ *
+ * @experimental
+ */
 export function httpUserAgent(): string {
 	// Return cached value if already initialized
 	if (_userAgent !== undefined) {
@@ -40,6 +137,11 @@ export type UpgradeWebSocket = (
 
 export type GetUpgradeWebSocket = () => UpgradeWebSocket;
 
+/**
+ * Reads an environment variable from Deno or Node runtimes.
+ *
+ * @experimental
+ */
 export function getEnvUniversal(key: string): string | undefined {
 	if (typeof Deno !== "undefined") {
 		return Deno.env.get(key);
@@ -49,6 +151,11 @@ export function getEnvUniversal(key: string): string | undefined {
 	}
 }
 
+/**
+ * Traces a debug value and returns it.
+ *
+ * @experimental
+ */
 export function dbg<T>(x: T): T {
 	console.trace(`=== DEBUG ===\n${x}`);
 	return x;
@@ -60,6 +167,8 @@ export function dbg<T>(x: T): T {
  *
  * @param data - The ArrayBuffer or ArrayBufferView to convert
  * @returns A Uint8Array view of the data
+ *
+ * @experimental
  */
 export function toUint8Array(data: ArrayBuffer | ArrayBufferView): Uint8Array {
 	if (data instanceof Uint8Array) {
@@ -93,8 +202,10 @@ export type LongTimeoutHandle = { abort: () => void };
  * Polyfill for Promise.withResolvers().
  *
  * This is specifically for Cloudflare Workers. Their implementation of Promise.withResolvers does not work correctly.
+ *
+ * @experimental
  */
-export function promiseWithResolvers<T>(): {
+export function promiseWithResolvers<T>(onReject: (reason?: any) => void): {
 	promise: Promise<T>;
 	resolve: (value: T | PromiseLike<T>) => void;
 	reject: (reason?: any) => void;
@@ -105,9 +216,15 @@ export function promiseWithResolvers<T>(): {
 		resolve = res;
 		reject = rej;
 	});
+	promise.catch(onReject);
 	return { promise, resolve, reject };
 }
 
+/**
+ * Sets a timeout that supports delays larger than the JavaScript timer limit.
+ *
+ * @experimental
+ */
 export function setLongTimeout(
 	listener: () => void,
 	after: number,
@@ -155,7 +272,7 @@ export class SinglePromiseQueue {
 
 		// Ensure a shared resolver exists for all callers in this cycle
 		if (!this.#pending) {
-			this.#pending = promiseWithResolvers<void>();
+			this.#pending = promiseWithResolvers<void>((reason) => logger().warn({ msg: "unhandled single promise queue rejection", reason }));
 		}
 
 		const waitForThisCycle = this.#pending.promise;
@@ -199,6 +316,11 @@ export class SinglePromiseQueue {
 	}
 }
 
+/**
+ * Converts a Buffer or Uint8Array into an ArrayBuffer view.
+ *
+ * @experimental
+ */
 export function bufferToArrayBuffer(buf: Buffer | Uint8Array): ArrayBuffer {
 	return buf.buffer.slice(
 		buf.byteOffset,
@@ -221,6 +343,8 @@ export function bufferToArrayBuffer(buf: Buffer | Uint8Array): ArrayBuffer {
  * @param path The path to append to the endpoint (may include query parameters)
  * @param queryParams Optional additional query parameters to append
  * @returns The properly combined URL string
+ *
+ * @experimental
  */
 export function combineUrlPath(
 	endpoint: string,
@@ -259,6 +383,11 @@ export function combineUrlPath(
 	return `${baseUrl.protocol}//${baseUrl.host}${fullPath}${fullQuery}`;
 }
 
+/**
+ * Compares two ArrayBuffer values by byte content.
+ *
+ * @experimental
+ */
 export function arrayBuffersEqual(
 	buf1: ArrayBuffer,
 	buf2: ArrayBuffer,
@@ -282,6 +411,11 @@ export const EXTRA_ERROR_LOG = {
 
 export type Runtime = "deno" | "bun" | "node";
 
+/**
+ * Detects the current JavaScript runtime from the user agent.
+ *
+ * @experimental
+ */
 export function detectRuntime(): Runtime {
 	const userAgent =
 		typeof navigator !== "undefined" ? navigator.userAgent : "";

package/src/workflow/constants.ts

@@ -0,0 +1,2 @@
+export const WORKFLOW_GUARD_KV_KEY =
+	"__rivet_actor_workflow_guard_triggered";