rivetkit 2.0.8 → 2.0.10

package/src/drivers/engine/actor-driver.ts

@@ -1,6 +1,6 @@
 import type {
+	RunnerConfig as EngineRunnerConfig,
 	ActorConfig as RunnerActorConfig,
-	RunnerConfig,
 } from "@rivetkit/engine-runner";
 import { Runner } from "@rivetkit/engine-runner";
 import * as cbor from "cbor-x";
@@ -34,13 +34,13 @@ import {
 	serializeEmptyPersistData,
 } from "@/driver-helpers/mod";
 import type { RegistryConfig } from "@/registry/config";
-import type { RunConfig } from "@/registry/run-config";
+import type { RunnerConfig } from "@/registry/run-config";
+import { getEndpoint } from "@/remote-manager-driver/api-utils";
 import {
 	type LongTimeoutHandle,
 	promiseWithResolvers,
 	setLongTimeout,
 } from "@/utils";
-import type { Config } from "./config";
 import { KEYS } from "./kv";
 import { logger } from "./log";
 
@@ -54,10 +54,9 @@ export type DriverContext = {};
 
 export class EngineActorDriver implements ActorDriver {
 	#registryConfig: RegistryConfig;
-	#runConfig: RunConfig;
+	#runConfig: RunnerConfig;
 	#managerDriver: ManagerDriver;
 	#inlineClient: Client<any>;
-	#config: Config;
 	#runner: Runner;
 	#actors: Map<string, ActorHandler> = new Map();
 	#actorRouter: ActorRouter;
@@ -69,16 +68,22 @@ export class EngineActorDriver implements ActorDriver {
 
 	constructor(
 		registryConfig: RegistryConfig,
-		runConfig: RunConfig,
+		runConfig: RunnerConfig,
 		managerDriver: ManagerDriver,
 		inlineClient: Client<any>,
-		config: Config,
 	) {
 		this.#registryConfig = registryConfig;
 		this.#runConfig = runConfig;
 		this.#managerDriver = managerDriver;
 		this.#inlineClient = inlineClient;
-		this.#config = config;
+
+		// HACK: Override inspector token (which are likely to be
+		// removed later on) with token from x-rivet-token header
+		const token = runConfig.token ?? runConfig.token;
+		if (token && runConfig.inspector && runConfig.inspector.enabled) {
+			runConfig.inspector.token = () => token;
+		}
+
 		this.#actorRouter = createActorRouter(
 			runConfig,
 			this,
@@ -87,15 +92,14 @@ export class EngineActorDriver implements ActorDriver {
 
 		// Create runner configuration
 		let hasDisconnected = false;
-		const runnerConfig: RunnerConfig = {
+		const engineRunnerConfig: EngineRunnerConfig = {
 			version: this.#version,
-			endpoint: config.endpoint,
-			token: runConfig.token ?? config.token,
-			pegboardEndpoint: config.pegboardEndpoint,
-			namespace: config.namespace,
-			totalSlots: runConfig.totalSlots ?? config.totalSlots,
-			runnerName: config.runnerName,
-			runnerKey: config.runnerKey,
+			endpoint: getEndpoint(runConfig),
+			token,
+			namespace: runConfig.namespace ?? runConfig.namespace,
+			totalSlots: runConfig.totalSlots ?? runConfig.totalSlots,
+			runnerName: runConfig.runnerName ?? runConfig.runnerName,
+			runnerKey: runConfig.runnerKey,
 			metadata: {
 				inspectorToken: this.#runConfig.inspector.token(),
 			},
@@ -109,14 +113,14 @@ export class EngineActorDriver implements ActorDriver {
 				if (hasDisconnected) {
 					logger().info({
 						msg: "runner reconnected",
-						namespace: this.#config.namespace,
-						runnerName: this.#config.runnerName,
+						namespace: this.#runConfig.namespace,
+						runnerName: this.#runConfig.runnerName,
 					});
 				} else {
 					logger().debug({
 						msg: "runner connected",
-						namespace: this.#config.namespace,
-						runnerName: this.#config.runnerName,
+						namespace: this.#runConfig.namespace,
+						runnerName: this.#runConfig.runnerName,
 					});
 				}
 
@@ -125,8 +129,8 @@ export class EngineActorDriver implements ActorDriver {
 			onDisconnected: () => {
 				logger().warn({
 					msg: "runner disconnected",
-					namespace: this.#config.namespace,
-					runnerName: this.#config.runnerName,
+					namespace: this.#runConfig.namespace,
+					runnerName: this.#runConfig.runnerName,
 				});
 				hasDisconnected = true;
 			},
@@ -141,13 +145,13 @@ export class EngineActorDriver implements ActorDriver {
 		};
 
 		// Create and start runner
-		this.#runner = new Runner(runnerConfig);
+		this.#runner = new Runner(engineRunnerConfig);
 		this.#runner.start();
 		logger().debug({
 			msg: "engine runner started",
-			endpoint: config.endpoint,
-			namespace: config.namespace,
-			runnerName: config.runnerName,
+			endpoint: runConfig.endpoint,
+			namespace: runConfig.namespace,
+			runnerName: runConfig.runnerName,
 		});
 	}
 
@@ -228,20 +232,20 @@ export class EngineActorDriver implements ActorDriver {
 	async #runnerOnActorStart(
 		actorId: string,
 		generation: number,
-		config: RunnerActorConfig,
+		runConfig: RunnerActorConfig,
 	): Promise<void> {
 		logger().debug({
 			msg: "runner actor starting",
 			actorId,
-			name: config.name,
-			key: config.key,
+			name: runConfig.name,
+			key: runConfig.key,
 			generation,
 		});
 
 		// Deserialize input
 		let input: any;
-		if (config.input) {
-			input = cbor.decode(config.input);
+		if (runConfig.input) {
+			input = cbor.decode(runConfig.input);
 		}
 
 		// Get or create handler
@@ -254,15 +258,12 @@ export class EngineActorDriver implements ActorDriver {
 			this.#actors.set(actorId, handler);
 		}
 
-		const name = config.name as string;
-		invariant(config.key, "actor should have a key");
-		const key = deserializeActorKey(config.key);
+		const name = runConfig.name as string;
+		invariant(runConfig.key, "actor should have a key");
+		const key = deserializeActorKey(runConfig.key);
 
 		// Create actor instance
-		const definition = lookupInRegistry(
-			this.#registryConfig,
-			config.name as string, // TODO: Remove cast
-		);
+		const definition = lookupInRegistry(this.#registryConfig, runConfig.name);
 		handler.actor = definition.instantiate();
 
 		// Start actor
@@ -413,7 +414,7 @@ export class EngineActorDriver implements ActorDriver {
 			// Runner id should be set if the runner started
 			const payload = this.#runner.getServerlessInitPacket();
 			invariant(payload, "runnerId not set");
-			stream.writeSSE({ data: payload });
+			await stream.writeSSE({ data: payload });
 
 			return this.#runnerStopped.promise;
 		});

package/src/drivers/engine/config.ts

@@ -1,35 +1,22 @@
-import type { Hono } from "hono";
 import { z } from "zod";
+import { ClientConfigSchema } from "@/client/config";
 import { getEnvUniversal } from "@/utils";
 
-export const ConfigSchema = z
+export const EngingConfigSchema = z
 	.object({
-		app: z.custom<Hono>().optional(),
-		endpoint: z
-			.string()
-			.default(
-				() => getEnvUniversal("RIVET_ENGINE") ?? "http://localhost:6420",
-			),
-		token: z
-			.string()
-			.optional()
-			.transform((val) => val ?? getEnvUniversal("RIVET_TOKEN")),
-		pegboardEndpoint: z.string().optional(),
-		namespace: z
-			.string()
-			.default(() => getEnvUniversal("RIVET_NAMESPACE") ?? "default"),
-		runnerName: z
-			.string()
-			.default(() => getEnvUniversal("RIVET_RUNNER") ?? "rivetkit"),
-		// TODO: Automatically attempt to determine key by common env vars (e.g. k8s pod name)
+		/** Unique key for this runner. Runners connecting a given key will replace any other runner connected with the same key. */
 		runnerKey: z
 			.string()
 			.default(
 				() => getEnvUniversal("RIVET_RUNNER_KEY") ?? crypto.randomUUID(),
 			),
+
+		/** How many actors this runner can run. */
 		totalSlots: z.number().default(100_000),
 	})
+	// We include the client config since this includes the common properties like endpoint, namespace, etc.
+	.merge(ClientConfigSchema)
 	.default({});
 
-export type InputConfig = z.input<typeof ConfigSchema>;
-export type Config = z.infer<typeof ConfigSchema>;
+export type EngineConfig = z.infer<typeof EngingConfigSchema>;
+export type EngineConfigInput = z.input<typeof EngingConfigSchema>;

package/src/drivers/engine/mod.ts

@@ -1,17 +1,19 @@
 import type { Client } from "@/client/client";
 import type { ManagerDriver } from "@/manager/driver";
 import type { RegistryConfig } from "@/registry/config";
-import type { DriverConfig, RunConfig } from "@/registry/run-config";
+import type { DriverConfig, RunnerConfig } from "@/registry/run-config";
 import { RemoteManagerDriver } from "@/remote-manager-driver/mod";
 import { EngineActorDriver } from "./actor-driver";
-import { ConfigSchema, type InputConfig } from "./config";
+import { type EngineConfigInput, EngingConfigSchema } from "./config";
 
 export { EngineActorDriver } from "./actor-driver";
-export { type Config, ConfigSchema, type InputConfig } from "./config";
-
-export function createEngineDriver(inputConfig?: InputConfig): DriverConfig {
-	const config = ConfigSchema.parse(inputConfig);
+export {
+	type EngineConfig as Config,
+	type EngineConfigInput as InputConfig,
+	EngingConfigSchema as ConfigSchema,
+} from "./config";
 
+export function createEngineDriver(): DriverConfig {
 	return {
 		name: "engine",
 		manager: (_registryConfig, runConfig) => {
@@ -19,7 +21,7 @@ export function createEngineDriver(inputConfig?: InputConfig): DriverConfig {
 		},
 		actor: (
 			registryConfig: RegistryConfig,
-			runConfig: RunConfig,
+			runConfig: RunnerConfig,
 			managerDriver: ManagerDriver,
 			inlineClient: Client<any>,
 		) => {
@@ -28,7 +30,6 @@ export function createEngineDriver(inputConfig?: InputConfig): DriverConfig {
 				runConfig,
 				managerDriver,
 				inlineClient,
-				config,
 			);
 		},
 	};

package/src/drivers/file-system/global-state.ts

@@ -14,7 +14,7 @@ import {
 	serializeEmptyPersistData,
 } from "@/driver-helpers/mod";
 import type { RegistryConfig } from "@/registry/config";
-import type { RunConfig } from "@/registry/run-config";
+import type { RunnerConfig } from "@/registry/run-config";
 import type * as schema from "@/schemas/file-system-driver/mod";
 import {
 	ACTOR_ALARM_VERSIONED,
@@ -73,7 +73,7 @@ export class FileSystemGlobalState {
 
 	#runnerParams?: {
 		registryConfig: RegistryConfig;
-		runConfig: RunConfig;
+		runConfig: RunnerConfig;
 		inlineClient: AnyClient;
 		actorDriver: ActorDriver;
 	};
@@ -410,7 +410,7 @@ export class FileSystemGlobalState {
 	 */
 	onRunnerStart(
 		registryConfig: RegistryConfig,
-		runConfig: RunConfig,
+		runConfig: RunnerConfig,
 		inlineClient: AnyClient,
 		actorDriver: ActorDriver,
 	) {
@@ -436,7 +436,7 @@ export class FileSystemGlobalState {
 
 	async startActor(
 		registryConfig: RegistryConfig,
-		runConfig: RunConfig,
+		runConfig: RunnerConfig,
 		inlineClient: AnyClient,
 		actorDriver: ActorDriver,
 		actorId: string,

package/src/engine-process/log.ts

@@ -0,0 +1,5 @@
+import { getLogger } from "@/common/log";
+
+export function logger() {
+	return getLogger("engine-process");
+}

package/src/engine-process/mod.ts

@@ -0,0 +1,316 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { pipeline } from "node:stream/promises";
+import {
+	ensureDirectoryExists,
+	getStoragePath,
+} from "@/drivers/file-system/utils";
+import { logger } from "./log";
+
+export const ENGINE_PORT = 6420;
+export const ENGINE_ENDPOINT = `http://localhost:${ENGINE_PORT}`;
+
+const ENGINE_BASE_URL = "https://releases.rivet.gg/engine";
+const ENGINE_BINARY_NAME = "rivet-engine";
+
+interface EnsureEngineProcessOptions {
+	version: string;
+}
+
+export async function ensureEngineProcess(
+	options: EnsureEngineProcessOptions,
+): Promise<void> {
+	logger().debug({ msg: "ensuring engine process", version: options.version });
+	const storageRoot = getStoragePath();
+	const binDir = path.join(storageRoot, "bin");
+	const varDir = path.join(storageRoot, "var");
+	const logsDir = path.join(varDir, "logs", "rivet-engine");
+	await ensureDirectoryExists(binDir);
+	await ensureDirectoryExists(varDir);
+	await ensureDirectoryExists(logsDir);
+
+	const executableName =
+		process.platform === "win32"
+			? `${ENGINE_BINARY_NAME}-${options.version}.exe`
+			: `${ENGINE_BINARY_NAME}-${options.version}`;
+	const binaryPath = path.join(binDir, executableName);
+	await downloadEngineBinaryIfNeeded(binaryPath, options.version, varDir);
+
+	// Check if the engine is already running on the port
+	if (await isEngineRunning()) {
+		try {
+			await waitForEngineHealth();
+			logger().debug({
+				msg: "engine already running and healthy",
+				version: options.version,
+			});
+			return;
+		} catch (error) {
+			logger().warn({
+				msg: "existing engine process not healthy, cannot restart automatically",
+				error,
+			});
+			throw new Error(
+				"Engine process exists but is not healthy. Please manually stop the process on port 6420 and retry.",
+			);
+		}
+	}
+
+	// Create log file streams with timestamp in the filename
+	const timestamp = new Date()
+		.toISOString()
+		.replace(/:/g, "-")
+		.replace(/\./g, "-");
+	const stdoutLogPath = path.join(logsDir, `engine-${timestamp}-stdout.log`);
+	const stderrLogPath = path.join(logsDir, `engine-${timestamp}-stderr.log`);
+
+	const stdoutStream = createWriteStream(stdoutLogPath, { flags: "a" });
+	const stderrStream = createWriteStream(stderrLogPath, { flags: "a" });
+
+	logger().debug({
+		msg: "creating engine log files",
+		stdout: stdoutLogPath,
+		stderr: stderrLogPath,
+	});
+
+	const child = spawn(binaryPath, ["start"], {
+		cwd: path.dirname(binaryPath),
+		stdio: ["inherit", "pipe", "pipe"],
+		env: {
+			...process.env,
+		},
+	});
+
+	if (!child.pid) {
+		throw new Error("failed to spawn rivet engine process");
+	}
+
+	// Pipe stdout and stderr to log files
+	if (child.stdout) {
+		child.stdout.pipe(stdoutStream);
+	}
+	if (child.stderr) {
+		child.stderr.pipe(stderrStream);
+	}
+
+	logger().debug({
+		msg: "spawned engine process",
+		pid: child.pid,
+		cwd: path.dirname(binaryPath),
+	});
+
+	child.once("exit", (code, signal) => {
+		logger().warn({
+			msg: "engine process exited",
+			code,
+			signal,
+		});
+		// Clean up log streams
+		stdoutStream.end();
+		stderrStream.end();
+	});
+
+	child.once("error", (error) => {
+		logger().error({
+			msg: "engine process failed",
+			error,
+		});
+		// Clean up log streams on error
+		stdoutStream.end();
+		stderrStream.end();
+	});
+
+	// Wait for engine to be ready
+	await waitForEngineHealth();
+
+	logger().info({
+		msg: "engine process started",
+		pid: child.pid,
+		version: options.version,
+		logs: {
+			stdout: stdoutLogPath,
+			stderr: stderrLogPath,
+		},
+	});
+}
+
+async function downloadEngineBinaryIfNeeded(
+	binaryPath: string,
+	version: string,
+	varDir: string,
+): Promise<void> {
+	const binaryExists = await fileExists(binaryPath);
+	if (binaryExists) {
+		logger().debug({
+			msg: "engine binary already cached",
+			version,
+			path: binaryPath,
+		});
+		return;
+	}
+
+	const { targetTriplet, extension } = resolveTargetTriplet();
+	const remoteFile = `${ENGINE_BINARY_NAME}-${targetTriplet}${extension}`;
+	const downloadUrl = `${ENGINE_BASE_URL}/${version}/${remoteFile}`;
+	logger().info({
+		msg: "downloading engine binary",
+		url: downloadUrl,
+		path: binaryPath,
+		version,
+	});
+
+	const response = await fetch(downloadUrl);
+	if (!response.ok || !response.body) {
+		throw new Error(
+			`failed to download rivet engine binary from ${downloadUrl}: ${response.status} ${response.statusText}`,
+		);
+	}
+
+	const tempPath = `${binaryPath}.${process.pid}.tmp`;
+	await pipeline(response.body, createWriteStream(tempPath));
+	if (process.platform !== "win32") {
+		await fs.chmod(tempPath, 0o755);
+	}
+	await fs.rename(tempPath, binaryPath);
+	logger().debug({
+		msg: "engine binary download complete",
+		version,
+		path: binaryPath,
+	});
+	logger().info({
+		msg: "engine binary downloaded",
+		version,
+		path: binaryPath,
+	});
+}
+
+function resolveTargetTriplet(): { targetTriplet: string; extension: string } {
+	return resolveTargetTripletFor(process.platform, process.arch);
+}
+
+export function resolveTargetTripletFor(
+	platform: NodeJS.Platform,
+	arch: typeof process.arch,
+): { targetTriplet: string; extension: string } {
+	switch (platform) {
+		case "darwin":
+			if (arch === "arm64") {
+				return { targetTriplet: "aarch64-apple-darwin", extension: "" };
+			}
+			if (arch === "x64") {
+				return { targetTriplet: "x86_64-apple-darwin", extension: "" };
+			}
+			break;
+		case "linux":
+			if (arch === "x64") {
+				return { targetTriplet: "x86_64-unknown-linux-musl", extension: "" };
+			}
+			break;
+		case "win32":
+			if (arch === "x64") {
+				return { targetTriplet: "x86_64-pc-windows-gnu", extension: ".exe" };
+			}
+			break;
+	}
+
+	throw new Error(
+		`unsupported platform for rivet engine binary: ${platform}/${arch}`,
+	);
+}
+
+async function isEngineRunning(): Promise<boolean> {
+	// Check if the engine is running on the port
+	return await checkIfEngineAlreadyRunningOnPort(ENGINE_PORT);
+}
+
+async function checkIfEngineAlreadyRunningOnPort(
+	port: number,
+): Promise<boolean> {
+	let response: Response;
+	try {
+		response = await fetch(`http://localhost:${port}/health`);
+	} catch (err) {
+		// Nothing is running on this port
+		return false;
+	}
+
+	if (response.ok) {
+		const health = (await response.json()) as {
+			status?: string;
+			runtime?: string;
+			version?: string;
+		};
+
+		// Check what's running on this port
+		if (health.runtime === "engine") {
+			logger().debug({
+				msg: "rivet engine already running on port",
+				port,
+			});
+			return true;
+		} else if (health.runtime === "rivetkit") {
+			logger().error({
+				msg: "another rivetkit process is already running on port",
+				port,
+			});
+			throw new Error(
+				"RivetKit process already running on port 6420, stop that process and restart this.",
+			);
+		} else {
+			throw new Error(
+				"Unknown process running on port 6420, cannot identify what it is.",
+			);
+		}
+	}
+
+	// Port responded but not with OK status
+	return false;
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+	try {
+		await fs.access(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+const HEALTH_MAX_WAIT = 10_000;
+const HEALTH_INTERVAL = 100;
+
+async function waitForEngineHealth(): Promise<void> {
+	const maxRetries = Math.ceil(HEALTH_MAX_WAIT / HEALTH_INTERVAL);
+
+	logger().debug({ msg: "waiting for engine health check" });
+
+	for (let i = 0; i < maxRetries; i++) {
+		try {
+			const response = await fetch(`${ENGINE_ENDPOINT}/health`);
+			if (response.ok) {
+				logger().debug({ msg: "engine health check passed" });
+				return;
+			}
+		} catch (error) {
+			// Expected to fail while engine is starting up
+			if (i === maxRetries - 1) {
+				throw new Error(
+					`engine health check failed after ${maxRetries} retries: ${error}`,
+				);
+			}
+		}
+
+		if (i < maxRetries - 1) {
+			logger().trace({
+				msg: "engine not ready, retrying",
+				attempt: i + 1,
+				maxRetries,
+			});
+			await new Promise((resolve) => setTimeout(resolve, HEALTH_INTERVAL));
+		}
+	}
+
+	throw new Error(`engine health check failed after ${maxRetries} retries`);
+}

package/src/inspector/utils.ts

@@ -2,7 +2,7 @@ import crypto from "node:crypto";
 import { createMiddleware } from "hono/factory";
 import type { ManagerDriver } from "@/driver-helpers/mod";
 import type { RunConfig } from "@/mod";
-import type { RunConfigInput } from "@/registry/run-config";
+import type { RunnerConfigInput } from "@/registry/run-config";
 import { inspectorLogger } from "./log";
 
 export function compareSecrets(providedSecret: string, validSecret: string) {
@@ -47,7 +47,7 @@ export const secureInspector = (runConfig: RunConfig) =>
 		await next();
 	});
 
-export function getInspectorUrl(runConfig: RunConfigInput | undefined) {
+export function getInspectorUrl(runConfig: RunnerConfigInput | undefined) {
 	if (!runConfig?.inspector?.enabled) {
 		return "disabled";
 	}
@@ -65,8 +65,10 @@ export function getInspectorUrl(runConfig: RunConfigInput | undefined) {
 
 	url.searchParams.set("t", accessToken);
 
-	if (runConfig?.inspector?.defaultEndpoint) {
-		url.searchParams.set("u", runConfig.inspector.defaultEndpoint);
+	const overrideDefaultEndpoint =
+		runConfig?.inspector?.defaultEndpoint ?? runConfig.overrideServerAddress;
+	if (overrideDefaultEndpoint) {
+		url.searchParams.set("u", overrideDefaultEndpoint);
 	}
 
 	return url.href;

package/src/manager/driver.ts

@@ -2,11 +2,11 @@ import type { Env, Hono, Context as HonoContext } from "hono";
 import type { ActorKey, Encoding, UniversalWebSocket } from "@/actor/mod";
 import type { ManagerInspector } from "@/inspector/manager";
 import type { RegistryConfig } from "@/registry/config";
-import type { RunConfig } from "@/registry/run-config";
+import type { RunnerConfig } from "@/registry/run-config";
 
 export type ManagerDriverBuilder = (
 	registryConfig: RegistryConfig,
-	runConfig: RunConfig,
+	runConfig: RunnerConfig,
 ) => ManagerDriver;
 
 export interface ManagerDriver {
@@ -52,7 +52,7 @@ export interface ManagerDriver {
 
 	/**
 	 * Get or create the inspector access token.
-	 * @internal
+	 * @experimental
 	 * @returns creates or returns existing inspector access token
 	 */
 	getOrCreateInspectorAccessToken: () => string;