rivetkit 2.3.0-rc.9 → 2.3.1

package/src/registry/index.ts

@@ -1,6 +1,11 @@
-import { ENGINE_ENDPOINT } from "@/common/engine";
+import { isLocalEngineEndpoint } from "@/common/engine";
 import { configureServerlessPool } from "@/serverless/configure";
 import { VERSION } from "@/utils";
+import {
+	getRivetkitPublicDir,
+	getRivetkitRuntimeMode,
+	parsePortEnv,
+} from "@/utils/env-vars";
 import {
 	type RegistryActors,
 	type RegistryConfig,
@@ -44,8 +49,18 @@ export interface RegistryRoutes {
 	prometheusMetrics(request?: Request): Promise<Response>;
 }
 
+/**
+ * Injectable dependencies for {@link Registry}. Production code uses the
+ * defaults. Tests override `buildConfiguredRegistry` to drive lifecycle
+ * orchestration against a fake `CoreRuntime` without an engine.
+ */
+export interface RegistryDeps {
+	buildConfiguredRegistry: typeof buildConfiguredRegistry;
+}
+
 export class Registry<A extends RegistryActors> {
 	#config: RegistryConfigInput<A>;
+	#buildConfiguredRegistry: typeof buildConfiguredRegistry;
 	public readonly routes: RegistryRoutes;
 
 	get config(): RegistryConfigInput<A> {
@@ -65,8 +80,10 @@ export class Registry<A extends RegistryActors> {
 	#shutdownInFlight: Promise<void> | null = null;
 	#signalHandlers: Partial<Record<ShutdownSignal, () => void>> = {};
 
-	constructor(config: RegistryConfigInput<A>) {
+	constructor(config: RegistryConfigInput<A>, deps?: Partial<RegistryDeps>) {
 		this.#config = config;
+		this.#buildConfiguredRegistry =
+			deps?.buildConfiguredRegistry ?? buildConfiguredRegistry;
 		this.routes = {
 			health: () => this.#healthRoute(),
 			metadata: () => this.#metadataRoute(),
@@ -75,16 +92,24 @@ export class Registry<A extends RegistryActors> {
 		};
 	}
 
-	#ensureServerlessPoolConfigured(config: RegistryConfig): Promise<void> | undefined {
+	/**
+	 * Fires `configureServerlessPool` once per process when the registry
+	 * config opts into it. Cached on the instance so repeated calls (from
+	 * `handler()` and `listen()`) only run the upsert once. The retry loop
+	 * inside `configureServerlessPool` tolerates the engine still warming up.
+	 */
+	#ensureServerlessPoolConfigured(
+		config: RegistryConfig,
+	): Promise<void> | undefined {
 		if (!config.configurePool) return undefined;
 
 		if (!this.#configureServerlessPoolPromise) {
-			this.#configureServerlessPoolPromise = configureServerlessPool(config).catch(
-				(error) => {
-					this.#configureServerlessPoolPromise = undefined;
-					throw error;
-				},
-			);
+			this.#configureServerlessPoolPromise = configureServerlessPool(
+				config,
+			).catch((error) => {
+				this.#configureServerlessPoolPromise = undefined;
+				throw error;
+			});
 			this.#configureServerlessPoolPromise.catch(() => {});
 		}
 
@@ -106,7 +131,8 @@ export class Registry<A extends RegistryActors> {
 		this.#printWelcome(config, "serverless");
 
 		if (!this.#runtimeServerlessPromise) {
-			this.#runtimeServerlessPromise = buildConfiguredRegistry(config);
+			this.#runtimeServerlessPromise =
+				this.#buildConfiguredRegistry(config);
 		}
 
 		const { runtime, registry, serveConfig } =
@@ -120,12 +146,13 @@ export class Registry<A extends RegistryActors> {
 			serveConfig.serverlessBasePath ?? "/api/rivet",
 		);
 		const isEngineMetadataRequest =
-			request.headers.get("user-agent")?.startsWith("RivetEngine/") ?? false;
+			request.headers.get("user-agent")?.startsWith("RivetEngine/") ??
+			false;
 
 		if (isStartRequest) {
 			try {
 				await this.#ensureServerlessPoolConfigured(config);
-			} catch (error) {
+			} catch (_error) {
 				return new Response(
 					JSON.stringify({
 						group: "guard",
@@ -267,7 +294,7 @@ export class Registry<A extends RegistryActors> {
 		if (isMetadataRequest && !isEngineMetadataRequest) {
 			try {
 				await this.#ensureServerlessPoolConfigured(config);
-			} catch (error) {
+			} catch (_error) {
 				return new Response(
 					JSON.stringify({
 						group: "guard",
@@ -303,6 +330,54 @@ export class Registry<A extends RegistryActors> {
 		};
 	}
 
+	/**
+	 * Bind an HTTP listener provided by the native (Rust) runtime and serve
+	 * the registry's serverless endpoints over it. Resolves only after the
+	 * registry is shut down (SIGINT/SIGTERM or `nativeRegistry.shutdown()`).
+	 *
+	 * @param opts.port      Port to listen on. Defaults to `process.env.RIVET_PORT`
+	 *                       if set, otherwise 3000.
+	 * @param opts.host      Address to bind. Defaults to `0.0.0.0`.
+	 * @param opts.publicDir If set, serves static files from this directory
+	 *                       as a fallback below the framework routes.
+	 *
+	 * @example
+	 * ```ts
+	 * await registry.listen();
+	 * await registry.listen({ port: 8080, publicDir: "./public" });
+	 * ```
+	 */
+	public async listen(
+		opts: { port?: number; host?: string; publicDir?: string } = {},
+	): Promise<void> {
+		const port = opts.port ?? parsePortEnv(process.env.RIVET_PORT) ?? 3000;
+		const publicDir = opts.publicDir ?? getRivetkitPublicDir();
+		const config = this.parseConfig();
+
+		// Cache on both promise fields so the shutdown drain sees Mode A and B.
+		const configuredRegistryPromise = buildConfiguredRegistry(config);
+		this.#runtimeServeConfiguredPromise = configuredRegistryPromise;
+		this.#runtimeServerlessPromise = configuredRegistryPromise;
+		this.#installSignalHandlers(config);
+
+		this.#printWelcome(config, "serverless", {
+			port,
+			host: opts.host,
+			publicDir,
+		});
+
+		// Background fire; the retry loop tolerates engine warm-up.
+		this.#ensureServerlessPoolConfigured(config);
+
+		const { runtime, registry, serveConfig } =
+			await configuredRegistryPromise;
+		await runtime.serveListener(
+			registry,
+			{ port, host: opts.host, publicDir },
+			serveConfig,
+		);
+	}
+
 	/**
 	 * Returns a health response suitable for mounting in a user-owned router.
 	 */
@@ -392,8 +467,11 @@ export class Registry<A extends RegistryActors> {
 		const candidates = [
 			this.#runtimeServerlessPromise,
 			this.#runtimeServeConfiguredPromise,
-		].filter((candidate): candidate is ReturnType<typeof buildConfiguredRegistry> =>
-			candidate !== undefined
+		].filter(
+			(
+				candidate,
+			): candidate is ReturnType<typeof buildConfiguredRegistry> =>
+				candidate !== undefined,
 		);
 
 		if (candidates.length === 0) return undefined;
@@ -405,35 +483,33 @@ export class Registry<A extends RegistryActors> {
 	 */
 	#startEnvoy(config: RegistryConfig, printWelcome: boolean) {
 		if (!this.#runtimeServePromise) {
-			const configuredRegistryPromise = buildConfiguredRegistry(config);
+			const configuredRegistryPromise =
+				this.#buildConfiguredRegistry(config);
 			this.#runtimeServeConfiguredPromise = configuredRegistryPromise;
 			this.#runtimeServePromise = configuredRegistryPromise
 				.then(async ({ runtime, registry, serveConfig }) => {
 					await runtime.serveRegistry(registry, serveConfig);
 				})
-				.catch((err) => {
+				.catch((error) => {
 					// Always-attached catch so the stored promise never leaves a
 					// rejection unhandled. Downstream awaits (e.g. #runShutdown's
 					// Promise.race) attach their own catches and still observe
 					// resolution via the race.
-					logger().warn({ err }, "runtime registry serve errored");
+					logger().warn({ error }, "runtime registry serve errored");
 				});
 			// Install signal handlers once an envoy lifecycle has begun. Only
 			// Mode A ever reaches here. Mode B (handler(request)) intentionally
 			// does not install handlers because it runs on Workers/Vercel/Deno
 			// Deploy where `process.on` is absent or forbidden; those platforms
 			// own their own signal policy.
-			this.#installSignalHandlers(config, configuredRegistryPromise);
+			this.#installSignalHandlers(config);
 		}
 		if (printWelcome) {
 			this.#printWelcome(config, "serverful");
 		}
 	}
 
-	#installSignalHandlers(
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): void {
+	#installSignalHandlers(config: RegistryConfig): void {
 		if (this.#shutdownInstalled) return;
 		if (config.shutdown?.disableSignalHandlers) return;
 		// Guard against non-Node runtimes (Workers/Edge) where `process` may
@@ -448,12 +524,7 @@ export class Registry<A extends RegistryActors> {
 		this.#shutdownInstalled = true;
 
 		const install = (signal: ShutdownSignal) => {
-			const handler = () =>
-				this.#onShutdownSignal(
-					signal,
-					config,
-					configuredRegistryPromise,
-				);
+			const handler = () => this.#onShutdownSignal(signal, config);
 			this.#signalHandlers[signal] = handler;
 			process.on(signal, handler);
 		};
@@ -461,37 +532,67 @@ export class Registry<A extends RegistryActors> {
 		install("SIGTERM");
 	}
 
-	#onShutdownSignal(
-		signal: ShutdownSignal,
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): void {
+	#onShutdownSignal(signal: ShutdownSignal, config: RegistryConfig): void {
 		if (this.#shutdownInFlight !== null) {
-			// Second delivery of the same (or another) shutdown signal.
-			// Remove our handler only, preserving any user-installed listeners.
-			// PID 1 must exit directly because re-raised default signals can be
+			// Second delivery of the same (or another) shutdown signal, or a
+			// drain already started by an explicit `shutdown()` call. Remove
+			// our handler only, preserving any user-installed listeners. PID 1
+			// must exit directly because re-raised default signals can be
 			// swallowed by the container signal path.
 			this.#removeSignalHandlers();
 			finishShutdownSignal(signal);
 			return;
 		}
-		this.#shutdownInFlight = this.#runShutdown(
-			signal,
-			config,
-			configuredRegistryPromise,
-		).catch((err) => {
+		this.#shutdownInFlight = this.#drain(config)
+			.catch((err) => {
+				logger().warn({ err }, "shutdown error");
+			})
+			.then(() => {
+				this.#removeSignalHandlers();
+				finishShutdownSignal(signal);
+			});
+	}
+
+	/**
+	 * Gracefully drains all live registries.
+	 *
+	 * Programmatic counterpart to the SIGINT/SIGTERM handlers: tears down
+	 * every live `CoreRegistry` (both `start()` and `handler()` modes) and
+	 * waits for the serve promise to resolve, all bounded by the shutdown
+	 * grace period. Unlike a signal-driven shutdown, this does not re-raise a
+	 * signal or exit the process. The caller owns process lifetime.
+	 *
+	 * Idempotent: concurrent or repeated calls share a single drain. Safe to
+	 * call even if nothing has been started.
+	 *
+	 * @example
+	 * ```ts
+	 * const registry = setup({ use: { counter } });
+	 * registry.start();
+	 * // ...later, on your own shutdown trigger:
+	 * await registry.shutdown();
+	 * ```
+	 */
+	public async shutdown(): Promise<void> {
+		if (this.#shutdownInFlight !== null) return this.#shutdownInFlight;
+		const config = this.parseConfig();
+		// Uninstall our signal handlers so a later SIGINT/SIGTERM does not
+		// re-trigger a drain on already-torn-down registries. Subsequent
+		// signals fall back to Node's default termination behavior.
+		this.#removeSignalHandlers();
+		this.#shutdownInFlight = this.#drain(config).catch((err) => {
 			logger().warn({ err }, "shutdown error");
 		});
+		return this.#shutdownInFlight;
 	}
 
-	async #runShutdown(
-		signal: ShutdownSignal,
-		config: RegistryConfig,
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
-	): Promise<void> {
+	async #drain(config: RegistryConfig): Promise<void> {
+		const modeAPromise = this.#runtimeServeConfiguredPromise;
+		const modeBPromise = this.#runtimeServerlessPromise;
+
 		const gracePeriodMs =
 			config.shutdown?.gracePeriodMs ??
-			(await this.#actorStopThresholdMs(configuredRegistryPromise)) ??
+			(await this.#actorStopThresholdMs(modeAPromise ?? modeBPromise)) ??
 			30 * 60 * 1000;
 		// Race the entire drain sequence (both modes + serve promise) against
 		// a single grace ceiling. By default, this uses the engine-provided
@@ -499,33 +600,33 @@ export class Registry<A extends RegistryActors> {
 		const drain = async () => {
 			// Shut down every live `CoreRegistry` we know about. Mode A
 			// (`start()`) and Mode B (`handler()`) each build a separate
-			// runtime registry, so one signal handler fans out to both to
-			// honor the spec invariant "single shutdown tears down both modes".
-			const registries: Promise<void>[] = [
-				(async () => {
-					try {
-						const { runtime, registry } =
-							await configuredRegistryPromise;
-						await runtime.shutdownRegistry(registry);
-					} catch (err) {
-						logger().warn(
-							{ err },
-							"runtime registry shutdown errored (mode A)",
-						);
-					}
-				})(),
-			];
-			const runtimeServerlessPromise = this.#runtimeServerlessPromise;
-			if (runtimeServerlessPromise !== undefined) {
+			// runtime registry, so one drain fans out to both to honor the
+			// spec invariant "single shutdown tears down both modes".
+			const registries: Promise<void>[] = [];
+			if (modeAPromise !== undefined) {
 				registries.push(
 					(async () => {
 						try {
-							const { runtime, registry } =
-								await runtimeServerlessPromise;
+							const { runtime, registry } = await modeAPromise;
 							await runtime.shutdownRegistry(registry);
 						} catch (err) {
 							logger().warn(
 								{ err },
+								"runtime registry shutdown errored (mode A)",
+							);
+						}
+					})(),
+				);
+			}
+			if (modeBPromise !== undefined) {
+				registries.push(
+					(async () => {
+						try {
+							const { runtime, registry } = await modeBPromise;
+							await runtime.shutdownRegistry(registry);
+						} catch (err) {
+							logger().warn(
+								{ error: err },
 								"runtime registry shutdown errored (mode B)",
 							);
 						}
@@ -548,13 +649,14 @@ export class Registry<A extends RegistryActors> {
 				setTimeout(resolve, gracePeriodMs).unref?.(),
 			),
 		]);
-		this.#removeSignalHandlers();
-		finishShutdownSignal(signal);
 	}
 
 	async #actorStopThresholdMs(
-		configuredRegistryPromise: ReturnType<typeof buildConfiguredRegistry>,
+		configuredRegistryPromise:
+			| ReturnType<typeof buildConfiguredRegistry>
+			| undefined,
 	): Promise<number | undefined> {
+		if (configuredRegistryPromise === undefined) return undefined;
 		try {
 			const { runtime, registry } = await configuredRegistryPromise;
 			const thresholdMs =
@@ -591,6 +693,10 @@ export class Registry<A extends RegistryActors> {
 	/**
 	 * Starts the actor envoy for standalone server deployments.
 	 *
+	 * Set `RIVETKIT_RUNTIME_MODE=serverless` to instead bind an HTTP listener
+	 * via `listen()` (Mode B). Mode A (envoy) and Mode B (listener) are
+	 * mutually exclusive per registry instance.
+	 *
 	 * @example
 	 * ```ts
 	 * const registry = setup({ use: { counter } });
@@ -598,6 +704,21 @@ export class Registry<A extends RegistryActors> {
 	 * ```
 	 */
 	public start() {
+		if (getRivetkitRuntimeMode() === "serverless") {
+			// start() defaults publicDir to "/public" unless overridden by env.
+			const publicDir = getRivetkitPublicDir() ?? "/public";
+			// Detached listener; bind failures are fatal so exit hard.
+			this.listen({ publicDir }).catch((error) => {
+				logger().error({ error }, "auto-listen failed; exiting");
+				if (
+					typeof process !== "undefined" &&
+					typeof process.exit === "function"
+				) {
+					process.exit(1);
+				}
+			});
+			return;
+		}
 		const config = this.parseConfig();
 		this.#startEnvoy(config, true);
 	}
@@ -605,6 +726,7 @@ export class Registry<A extends RegistryActors> {
 	#printWelcome(
 		config: RegistryConfig,
 		kind: "serverless" | "serverful",
+		listener?: { port: number; host?: string; publicDir?: string },
 	): void {
 		if (config.noWelcome || this.#welcomePrinted) return;
 		this.#welcomePrinted = true;
@@ -625,7 +747,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})`);
 		}
 
@@ -634,6 +758,15 @@ export class Registry<A extends RegistryActors> {
 		}
 
 		logLine("Actors", Object.keys(config.use).length.toString());
+
+		if (listener) {
+			const host = listener.host ?? "0.0.0.0";
+			logLine("Listening", `http://${host}:${listener.port}`);
+			if (listener.publicDir) {
+				logLine("Public Dir", listener.publicDir);
+			}
+		}
+
 		console.log();
 	}
 }
@@ -646,7 +779,10 @@ function isServerlessStartRequest(request: Request, basePath: string): boolean {
 	return parsed.pathname === `${normalizedBase}/start`;
 }
 
-function isServerlessMetadataRequest(request: Request, basePath: string): boolean {
+function isServerlessMetadataRequest(
+	request: Request,
+	basePath: string,
+): boolean {
 	if (request.method !== "GET") return false;
 	const parsed = new URL(request.url);
 	const normalizedBase =

package/src/registry/napi-runtime.ts

@@ -18,13 +18,14 @@ import type {
 	RuntimeHttpRequest,
 	RuntimeKvEntry,
 	RuntimeKvListOptions,
+	RuntimeListenerConfig,
 	RuntimeQueueEnqueueAndWaitOptions,
 	RuntimeQueueMessage,
 	RuntimeQueueNextBatchOptions,
 	RuntimeQueueTryNextBatchOptions,
 	RuntimeQueueWaitOptions,
-	RuntimeRequestSaveOpts,
 	RuntimeRegistryRouteResponse,
+	RuntimeRequestSaveOpts,
 	RuntimeServeConfig,
 	RuntimeServerlessRequest,
 	RuntimeServerlessResponseHead,
@@ -259,6 +260,21 @@ export class NapiCoreRuntime implements CoreRuntime {
 		);
 	}
 
+	async serveListener(
+		registry: RegistryHandle,
+		listener: RuntimeListenerConfig,
+		config: RuntimeServeConfig,
+	): Promise<void> {
+		await asNativeRegistry(registry).serveListener(
+			{
+				port: listener.port,
+				host: listener.host,
+				publicDir: listener.publicDir,
+			},
+			config,
+		);
+	}
+
 	createActorFactory(
 		callbacks: object,
 		config?: RuntimeActorConfig | undefined | null,
@@ -452,6 +468,12 @@ export class NapiCoreRuntime implements CoreRuntime {
 		return await asNativeActorContext(ctx).waitForTrackedShutdownWork();
 	}
 
+	async actorWaitForTrackedShutdownWorkUnbounded(
+		ctx: ActorContextHandle,
+	): Promise<void> {
+		await asNativeActorContext(ctx).waitForTrackedShutdownWorkUnbounded();
+	}
+
 	actorKeepAwake(ctx: ActorContextHandle, promise: Promise<unknown>): void {
 		asNativeActorContext(ctx).keepAwake(promise);
 	}
@@ -677,10 +699,15 @@ export class NapiCoreRuntime implements CoreRuntime {
 		ctx: ActorContextHandle,
 		names: string[],
 		options?: RuntimeQueueWaitOptions | undefined | null,
+		signal?: CancellationTokenHandle | undefined | null,
 	): Promise<void> {
 		await asNativeActorContext(ctx)
 			.queue()
-			.waitForNamesAvailable(names, options);
+			.waitForNamesAvailable(
+				names,
+				options,
+				signal ? asNativeCancellationToken(signal) : signal,
+			);
 	}
 
 	async actorQueueEnqueueAndWait(

package/src/registry/native-validation.ts

@@ -1,12 +1,12 @@
 import { RivetError } from "@/actor/errors";
 import {
+	type EventSchemaConfig,
 	isEventSchemaDefinition,
 	isQueueSchemaDefinition,
 	isStandardSchema,
-	validateSchemaSync,
-	type EventSchemaConfig,
 	type PrimitiveSchema,
 	type QueueSchemaConfig,
+	validateSchemaSync,
 } from "@/actor/schema";
 
 const CONN_PARAMS_KEY = "__conn_params__";
@@ -126,19 +126,17 @@ export function validateQueueComplete(
 		response,
 	);
 	if (!result.success) {
-		throw validationError(`queue \`${name}\` completion response`, result.issues);
+		throw validationError(
+			`queue \`${name}\` completion response`,
+			result.issues,
+		);
 	}
 	return result.data;
 }
 
 function validationError(target: string, issues: unknown[]): RivetError {
-	return new RivetError(
-		"actor",
-		"validation_error",
-		`Invalid ${target}`,
-		{
-			public: true,
-			metadata: { issues },
-		},
-	);
+	return new RivetError("actor", "validation_error", `Invalid ${target}`, {
+		public: true,
+		metadata: { issues },
+	});
 }