rivetkit 2.0.2 → 2.0.4-rc.1

package/src/utils/env-vars.ts

@@ -0,0 +1,78 @@
+// This file consolidates all environment variables that affect RivetKit's behavior.
+//
+// IMPORTANT: When adding or modifying environment variables here, also update the
+// documentation at: website/src/content/docs/general/environment-variables.mdx
+
+import { getEnvUniversal } from "@/utils";
+
+// Rivet configuration
+export const getRivetEngine = (): string | undefined =>
+	getEnvUniversal("RIVET_ENGINE");
+export const getRivetEndpoint = (): string | undefined =>
+	getEnvUniversal("RIVET_ENDPOINT");
+export const getRivetToken = (): string | undefined =>
+	getEnvUniversal("RIVET_TOKEN");
+export const getRivetNamespace = (): string | undefined =>
+	getEnvUniversal("RIVET_NAMESPACE");
+export const getRivetRunner = (): string | undefined =>
+	getEnvUniversal("RIVET_RUNNER");
+export const getRivetTotalSlots = (): number | undefined => {
+	const value = getEnvUniversal("RIVET_TOTAL_SLOTS");
+	return value !== undefined ? parseInt(value, 10) : undefined;
+};
+export const getRivetRunnerKey = (): string | undefined =>
+	getEnvUniversal("RIVET_RUNNER_KEY");
+export const getRivetRunEngine = (): boolean =>
+	getEnvUniversal("RIVET_RUN_ENGINE") === "1";
+export const getRivetRunEngineVersion = (): string | undefined =>
+	getEnvUniversal("RIVET_RUN_ENGINE_VERSION");
+export const getRivetRunnerKind = (): string | undefined =>
+	getEnvUniversal("RIVET_RUNNER_KIND");
+export const getRivetRunnerVersion = (): number | undefined => {
+	const value = getEnvUniversal("RIVET_RUNNER_VERSION");
+	return value !== undefined ? parseInt(value, 10) : undefined;
+};
+export const getRivetPublicEndpoint = (): string | undefined =>
+	getEnvUniversal("RIVET_PUBLIC_ENDPOINT");
+export const getRivetPublicToken = (): string | undefined =>
+	getEnvUniversal("RIVET_PUBLIC_TOKEN");
+// There is no RIVET_PUBLIC_NAMESPACE because the frontend and backend cannot
+// use different namespaces
+
+// RivetKit configuration
+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
+export const getLogLevel = (): string | undefined =>
+	getEnvUniversal("RIVET_LOG_LEVEL") ?? getEnvUniversal("LOG_LEVEL");
+export const getLogTarget = (): boolean =>
+	getEnvUniversal("RIVET_LOG_TARGET") === "1";
+export const getLogTimestamp = (): boolean =>
+	getEnvUniversal("RIVET_LOG_TIMESTAMP") === "1";
+export const getLogMessage = (): boolean =>
+	getEnvUniversal("RIVET_LOG_MESSAGE") === "1";
+export const getLogErrorStack = (): boolean =>
+	getEnvUniversal("RIVET_LOG_ERROR_STACK") === "1";
+export const getLogHeaders = (): boolean =>
+	getEnvUniversal("RIVET_LOG_HEADERS") === "1";
+
+// Environment configuration
+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

@@ -0,0 +1,178 @@
+import { createRequire } from "node:module";
+
+// Global variables for Node.js modules.
+//
+// We use synchronous require() instead of async import() for Node.js module loading because:
+// 1. These modules are only needed in Node.js environments (not browser/edge)
+// 2. registry.start() cannot be async and needs immediate access to Node modules
+// 3. The setup process must be synchronous to avoid breaking the API
+//
+// Biome only allows imports of node modules in this file in order to ensure
+// we're forcing the use of dynamic imports.
+let nodeCrypto: typeof import("node:crypto") | undefined;
+let nodeFsSync: typeof import("node:fs") | undefined;
+let nodeFs: typeof import("node:fs/promises") | undefined;
+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.
+export function getRequireFn() {
+	// TODO: This causes issues in tsup
+	// CommonJS context - use global require
+	// if (typeof require !== "undefined") {
+	// 	console.log("existing require");
+	// 	return require;
+	// }
+
+	// ESM context - use createRequire with import.meta.url
+	return createRequire(import.meta.url);
+}
+
+/**
+ * Dynamically imports all required Node.js dependencies. We do this early in a
+ * single function call in order to surface errors early.
+ *
+ * This function is idempotent and will only import once.
+ *
+ * @throws Error if Node.js modules are not available (e.g., in browser/edge environments)
+ */
+export function importNodeDependencies(): void {
+	// Check if already loaded
+	if (hasImportedDependencies) return;
+
+	try {
+		// Get a require function that works in both CommonJS and ESM
+		const requireFn = getRequireFn();
+
+		// Use requireFn with webpack ignore comment to prevent bundling
+		nodeCrypto = requireFn(/* webpackIgnore: true */ "node:crypto");
+		nodeFsSync = requireFn(/* webpackIgnore: true */ "node:fs");
+		nodeFs = requireFn(/* webpackIgnore: true */ "node:fs/promises");
+		nodePath = requireFn(/* webpackIgnore: true */ "node:path");
+		nodeOs = requireFn(/* webpackIgnore: true */ "node:os");
+		nodeChildProcess = requireFn(
+			/* webpackIgnore: true */ "node:child_process",
+		);
+		nodeStream = requireFn(
+			/* webpackIgnore: true */ "node:stream/promises",
+		);
+		nodeUrl = requireFn(/* webpackIgnore: true */ "node:url");
+		hasImportedDependencies = true;
+	} catch (err) {
+		console.warn(
+			"Node.js modules not available, file system driver will not work",
+			err,
+		);
+		throw err;
+	}
+}
+
+/**
+ * Gets the Node.js crypto module.
+ * @throws Error if crypto module is not loaded
+ */
+export function getNodeCrypto(): typeof import("node:crypto") {
+	if (!nodeCrypto) {
+		throw new Error(
+			"Node crypto module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeCrypto;
+}
+
+/**
+ * Gets the Node.js fs module.
+ * @throws Error if fs module is not loaded
+ */
+export function getNodeFsSync(): typeof import("node:fs") {
+	if (!nodeFsSync) {
+		throw new Error(
+			"Node fs module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeFsSync;
+}
+
+/**
+ * Gets the Node.js fs/promises module.
+ * @throws Error if fs/promises module is not loaded
+ */
+export function getNodeFs(): typeof import("node:fs/promises") {
+	if (!nodeFs) {
+		throw new Error(
+			"Node fs/promises module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeFs;
+}
+
+/**
+ * Gets the Node.js path module.
+ * @throws Error if path module is not loaded
+ */
+export function getNodePath(): typeof import("node:path") {
+	if (!nodePath) {
+		throw new Error(
+			"Node path module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodePath;
+}
+
+/**
+ * Gets the Node.js os module.
+ * @throws Error if os module is not loaded
+ */
+export function getNodeOs(): typeof import("node:os") {
+	if (!nodeOs) {
+		throw new Error(
+			"Node os module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeOs;
+}
+
+/**
+ * Gets the Node.js child_process module.
+ * @throws Error if child_process module is not loaded
+ */
+export function getNodeChildProcess(): typeof import("node:child_process") {
+	if (!nodeChildProcess) {
+		throw new Error(
+			"Node child_process module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	return nodeChildProcess;
+}
+
+/**
+ * Gets the Node.js stream/promises module.
+ * @throws Error if stream/promises module is not loaded
+ */
+export function getNodeStream(): typeof import("node:stream/promises") {
+	if (!nodeStream) {
+		throw new Error(
+			"Node stream/promises module not loaded. Ensure importNodeDependencies() has been called.",
+		);
+	}
+	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/router.ts

@@ -0,0 +1,83 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import type { Hono } from "hono";
+import { createMiddleware } from "hono/factory";
+import { cors } from "@/common/cors";
+import {
+	handleRouteError,
+	handleRouteNotFound,
+	loggerMiddleware,
+} from "@/common/router";
+import { getLogger } from "@/common/log";
+
+export function logger() {
+	return getLogger("router");
+}
+
+export function createRouter(
+	basePath: string,
+	builder: (app: OpenAPIHono) => void,
+): {
+	router: Hono;
+	openapi: OpenAPIHono;
+} {
+	const router = new OpenAPIHono({ strict: false }).basePath(basePath);
+
+	router.use("*", loggerMiddleware(logger()), cors());
+
+	// HACK: Add Sec-WebSocket-Protocol header to fix KIT-339
+	//
+	// Some Deno WebSocket providers do not auto-set the protocol, which
+	// will cause some WebSocket clients to fail
+	router.use(
+		"*",
+		createMiddleware(async (c, next) => {
+			const upgrade = c.req.header("upgrade");
+			const isWebSocket = upgrade?.toLowerCase() === "websocket";
+			const isGet = c.req.method === "GET";
+
+			if (isGet && isWebSocket) {
+				c.header("Sec-WebSocket-Protocol", "rivet");
+			}
+
+			await next();
+		}),
+	);
+
+	builder(router);
+
+	// Error handling
+	router.notFound(handleRouteNotFound);
+	router.onError(handleRouteError);
+
+	return { router: router as Hono, openapi: router };
+}
+
+export function buildOpenApiResponses<T>(schema: T) {
+	return {
+		200: {
+			description: "Success",
+			content: {
+				"application/json": {
+					schema,
+				},
+			},
+		},
+		400: {
+			description: "User error",
+		},
+		500: {
+			description: "Internal error",
+		},
+	};
+}
+
+export function buildOpenApiRequestBody<T>(schema: T) {
+	return {
+		required: true,
+		content: {
+			"application/json": {
+				schema,
+			},
+		},
+	};
+}

package/src/utils/serve.ts

@@ -0,0 +1,212 @@
+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";
+
+const DEFAULT_PORT = 6420;
+export type ServeStatic =
+	typeof import("@hono/node-server/serve-static").serveStatic;
+const serveStaticLoaderPromises: Partial<Record<Runtime, Promise<ServeStatic>>> =
+	{};
+
+/**
+ * Finds a free port starting from the given port.
+ *
+ * Tries ports incrementally until a free one is found.
+ */
+export async function findFreePort(
+	startPort: number = DEFAULT_PORT,
+): Promise<number> {
+	// TODO: Fix this
+	// const getPortModule = "get-port";
+	// const { default: getPort } = await import(/* webpackIgnore: true */ getPortModule);
+
+	// Create an iterable of ports starting from startPort
+	function* portRange(start: number, count: number = 100): Iterable<number> {
+		for (let i = 0; i < count; i++) {
+			yield start + i;
+		}
+	}
+
+	return getPort({ port: portRange(startPort) });
+}
+
+export async function crossPlatformServe(
+	config: RegistryConfig,
+	managerPort: number,
+	app: Hono<any>,
+	runtime: Runtime = detectRuntime(),
+): Promise<{ upgradeWebSocket: any }> {
+	logger().debug({ msg: "detected runtime for serve", runtime });
+
+	switch (runtime) {
+		case "deno":
+			return serveDeno(config, managerPort, app);
+		case "bun":
+			return serveBun(config, managerPort, app);
+		case "node":
+			return serveNode(config, managerPort, app);
+		default:
+			return serveNode(config, managerPort, app);
+	}
+}
+
+export async function loadRuntimeServeStatic(
+	runtime: Runtime,
+): Promise<ServeStatic> {
+	if (!serveStaticLoaderPromises[runtime]) {
+		if (runtime === "node") {
+			const nodeServeStaticModule = "@hono/node-server/serve-static";
+			serveStaticLoaderPromises[runtime] = import(
+				/* webpackIgnore: true */
+				nodeServeStaticModule
+			).then((x) => x.serveStatic);
+		} else if (runtime === "bun") {
+			const bunModule = "hono/bun";
+			serveStaticLoaderPromises[runtime] = import(
+				/* webpackIgnore: true */
+				bunModule
+			).then((x) => x.serveStatic as ServeStatic);
+		} else if (runtime === "deno") {
+			const denoModule = "hono/deno";
+			serveStaticLoaderPromises[runtime] = import(
+				/* webpackIgnore: true */
+				denoModule
+			).then((x) => x.serveStatic as ServeStatic);
+		} else {
+			throw new Error(`unsupported runtime: ${runtime}`);
+		}
+	}
+
+	return await serveStaticLoaderPromises[runtime]!;
+}
+
+async function serveNode(
+	config: RegistryConfig,
+	managerPort: number,
+	app: Hono<any>,
+): Promise<{ upgradeWebSocket: any }> {
+	// Import @hono/node-server using string variable to prevent static analysis
+	const nodeServerModule = "@hono/node-server";
+	let serve: any;
+	try {
+		const dep = await import(
+			/* webpackIgnore: true */
+			nodeServerModule
+		);
+		serve = dep.serve;
+	} catch (err) {
+		logger().error({
+			msg: "failed to import @hono/node-server. please run 'npm install @hono/node-server @hono/node-ws'",
+			error: stringifyError(err),
+		});
+		process.exit(1);
+	}
+
+	// Import @hono/node-ws using string variable to prevent static analysis
+	const nodeWsModule = "@hono/node-ws";
+	let createNodeWebSocket: any;
+	try {
+		const dep = await import(
+			/* webpackIgnore: true */
+			nodeWsModule
+		);
+		createNodeWebSocket = dep.createNodeWebSocket;
+	} catch (err) {
+		logger().error({
+			msg: "failed to import @hono/node-ws. please run 'npm install @hono/node-server @hono/node-ws'",
+			error: stringifyError(err),
+		});
+		process.exit(1);
+	}
+
+	// Inject WS
+	const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({
+		app: app,
+	});
+
+	// Start server
+	const port = managerPort;
+	const hostname = config.managerHost;
+	const server = serve({ fetch: app.fetch, port, hostname }, () =>
+		logger().info({ msg: "server listening", port, hostname }),
+	);
+	injectWebSocket(server);
+
+	return { upgradeWebSocket };
+}
+
+async function serveDeno(
+	config: RegistryConfig,
+	managerPort: number,
+	app: Hono<any>,
+): Promise<{ upgradeWebSocket: any }> {
+	// Import hono/deno using string variable to prevent static analysis
+	const honoDenoModule = "hono/deno";
+	let upgradeWebSocket: any;
+	try {
+		const dep = await import(
+			/* webpackIgnore: true */
+			honoDenoModule
+		);
+		upgradeWebSocket = dep.upgradeWebSocket;
+	} catch (err) {
+		logger().error({
+			msg: "failed to import hono/deno",
+			error: stringifyError(err),
+		});
+		process.exit(1);
+	}
+
+	const port = config.managerPort;
+	const hostname = config.managerHost;
+
+	// Use Deno.serve
+	Deno.serve({ port, hostname }, app.fetch);
+	logger().info({ msg: "server listening", port, hostname });
+
+	return { upgradeWebSocket };
+}
+
+async function serveBun(
+	config: RegistryConfig,
+	managerPort: number,
+	app: Hono<any>,
+): Promise<{ upgradeWebSocket: any }> {
+	// Import hono/bun using string variable to prevent static analysis
+	const honoBunModule = "hono/bun";
+	let createBunWebSocket: any;
+	try {
+		const dep = await import(
+			/* webpackIgnore: true */
+			honoBunModule
+		);
+		createBunWebSocket = dep.createBunWebSocket;
+	} catch (err) {
+		logger().error({
+			msg: "failed to import hono/bun",
+			error: stringifyError(err),
+		});
+		process.exit(1);
+	}
+
+	const { websocket, upgradeWebSocket } = createBunWebSocket();
+
+	const port = config.managerPort;
+	const hostname = config.managerHost;
+
+	// Use Bun.serve
+	// @ts-expect-error - Bun global
+	Bun.serve({
+		fetch: app.fetch,
+		port,
+		hostname,
+		websocket,
+	});
+	logger().info({ msg: "server listening", port, hostname });
+
+	return { upgradeWebSocket };
+}

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);
+	});
+});