@rivetkit/engine 1.0.0 → 2.2.1-pr.4600.b74ff3b

package/sdks/typescript/test-runner/src/index.ts

@@ -12,20 +12,18 @@ const INTERNAL_SERVER_PORT = process.env.INTERNAL_SERVER_PORT
 	: 5051;
 const RIVET_NAMESPACE = process.env.RIVET_NAMESPACE ?? "default";
 const RIVET_RUNNER_NAME = process.env.RIVET_RUNNER_NAME ?? "test-runner";
-const RIVET_RUNNER_KEY = process.env.RIVET_RUNNER_KEY;
 const RIVET_RUNNER_VERSION = process.env.RIVET_RUNNER_VERSION
 	? Number(process.env.RIVET_RUNNER_VERSION)
 	: 1;
-const RIVET_RUNNER_TOTAL_SLOTS = process.env.RIVET_RUNNER_TOTAL_SLOTS
-	? Number(process.env.RIVET_RUNNER_TOTAL_SLOTS)
-	: 100;
+const RIVET_RUNNER_TOTAL_SLOTS = parseInt(process.env.RIVET_RUNNER_TOTAL_SLOTS ?? "1");
 const RIVET_ENDPOINT = process.env.RIVET_ENDPOINT ?? "http://127.0.0.1:6420";
 const RIVET_TOKEN = process.env.RIVET_TOKEN ?? "dev";
-const AUTOSTART_SERVER = process.env.NO_AUTOSTART_SERVER === undefined;
-const AUTOSTART_RUNNER = process.env.NO_AUTOSTART_RUNNER === undefined;
+const AUTOSTART_SERVER = (process.env.AUTOSTART_SERVER ?? "1") == "1";
+const AUTOSTART_RUNNER = (process.env.AUTOSTART_RUNNER ?? "0") == "1";
+const AUTOCONFIGURE_SERVERLESS = (process.env.AUTOCONFIGURE_SERVERLESS ?? "1") == "1";
 
-let runnerStarted = Promise.withResolvers();
-let runnerStopped = Promise.withResolvers();
+const runnerStarted = Promise.withResolvers<Runner>();
+const runnerStopped = Promise.withResolvers<Runner>();
 let runner: Runner | null = null;
 const websocketLastMsgIndexes: Map<string, number> = new Map();
 
@@ -56,8 +54,8 @@ function loggerMiddleware(logger: Logger) {
 app.use("*", loggerMiddleware(getLogger()));
 
 app.get("/wait-ready", async (c) => {
-	await runnerStarted.promise;
-	return c.json(runner?.runnerId);
+	const runner = await runnerStarted.promise;
+	return c.json(runner.runnerId);
 });
 
 app.get("/has-actor", async (c) => {
@@ -71,18 +69,24 @@ app.get("/has-actor", async (c) => {
 	return c.text("ok");
 });
 
+app.get("/health", (c) => {
+	return c.text("ok");
+});
+
 app.get("/shutdown", async (c) => {
 	await runner?.shutdown(true);
 	return c.text("ok");
 });
 
-app.get("/start", async (c) => {
+app.get("/api/rivet/start", async (c) => {
 	return streamSSE(c, async (stream) => {
-		const [runner, runnerStarted, runnerStopped] = await startRunner();
+		const runnerStarted = Promise.withResolvers<Runner>();
+		const runnerStopped = Promise.withResolvers<Runner>();
+		const runner = await startRunner(runnerStarted, runnerStopped);
 
 		c.req.raw.signal.addEventListener("abort", () => {
 			getLogger().debug("SSE aborted, shutting down runner");
-			runner.shutdown(true);
+			runner!.shutdown(true);
 		});
 
 		await runnerStarted.promise;
@@ -93,6 +97,14 @@ app.get("/start", async (c) => {
 	});
 });
 
+app.get("/api/rivet/metadata", async (c) => {
+	return c.json({
+		// Not actually rivetkit
+		runtime: "rivetkit",
+		version: "1",
+	});
+});
+
 if (AUTOSTART_SERVER) {
 	serve({
 		fetch: app.fetch,
@@ -104,12 +116,31 @@ if (AUTOSTART_SERVER) {
 }
 
 if (AUTOSTART_RUNNER) {
-	[runner, runnerStarted, runnerStopped] = await startRunner();
-} else await autoConfigureServerless();
+	runner = await startRunner(runnerStarted, runnerStopped);
+} else if (AUTOCONFIGURE_SERVERLESS) {
+	await autoConfigureServerless();
+}
+
+process.on("SIGTERM", async () => {
+	getLogger().debug("received SIGTERM, force exiting in 3s");
+
+	await new Promise(res => setTimeout(res, 3000));
+
+	process.exit(0);
+});
+process.on("SIGINT", async () => {
+	getLogger().debug("received SIGTERM, force exiting in 3s");
+
+	await new Promise(res => setTimeout(res, 3000));
+
+	process.exit(0);
+});
 
 async function autoConfigureServerless() {
+	getLogger().info("Configuring serverless");
+
 	const res = await fetch(
-		`http://127.0.0.1:6420/runner-configs/${RIVET_RUNNER_NAME}?namespace=${RIVET_NAMESPACE}`,
+		`${RIVET_ENDPOINT}/runner-configs/${RIVET_RUNNER_NAME}?namespace=${RIVET_NAMESPACE}`,
 		{
 			method: "PUT",
 			headers: {
@@ -120,10 +151,10 @@ async function autoConfigureServerless() {
 				datacenters: {
 					default: {
 						serverless: {
-							url: `http://localhost:${INTERNAL_SERVER_PORT}`,
-							max_runners: 10,
+							url: `http://localhost:${INTERNAL_SERVER_PORT}/api/rivet`,
+							max_runners: 10000,
 							slots_per_runner: 1,
-							request_lifespan: 15,
+							request_lifespan: 300,
 						},
 					},
 				},
@@ -138,14 +169,12 @@ async function autoConfigureServerless() {
 	}
 }
 
-async function startRunner(): Promise<
-	[Runner, PromiseWithResolvers<unknown>, PromiseWithResolvers<unknown>]
-> {
+async function startRunner(
+	runnerStarted: PromiseWithResolvers<Runner>,
+	runnerStopped: PromiseWithResolvers<Runner>,
+): Promise<Runner> {
 	getLogger().info("Starting runner");
-
-	const runnerStarted = Promise.withResolvers();
-	const runnerStopped = Promise.withResolvers();
-
+	let runner: Runner;
 	const config: RunnerConfig = {
 		logger: getLogger(),
 		version: RIVET_RUNNER_VERSION,
@@ -153,16 +182,14 @@ async function startRunner(): Promise<
 		token: RIVET_TOKEN,
 		namespace: RIVET_NAMESPACE,
 		runnerName: RIVET_RUNNER_NAME,
-		runnerKey:
-			RIVET_RUNNER_KEY ?? `key-${Math.floor(Math.random() * 10000)}`,
 		totalSlots: RIVET_RUNNER_TOTAL_SLOTS,
 		prepopulateActorNames: {},
 		onConnected: () => {
-			runnerStarted.resolve(undefined);
+			runnerStarted.resolve(runner);
 		},
-		onDisconnected: () => {},
+		onDisconnected: () => { },
 		onShutdown: () => {
-			runnerStopped.resolve(undefined);
+			runnerStopped.resolve(runner);
 		},
 		fetch: async (
 			runner: Runner,
@@ -259,18 +286,14 @@ async function startRunner(): Promise<
 				});
 			});
 		},
-		// TODO:
-		hibernatableWebSocket: undefined as any,
-		// getActorHibernationConfig(actorId, gatewayId, requestId) {
-		// 	const websocketId = Buffer.from(requestId).toString("base64");
-		// 	return {
-		// 		enabled: true,
-		// 		lastMsgIndex: websocketLastMsgIndexes.get(websocketId),
-		// 	};
-		// },
+		hibernatableWebSocket: {
+			canHibernate() {
+				return true;
+			},
+		},
 	};
 
-	const runner = new Runner(config);
+	runner = new Runner(config);
 
 	// Start runner
 	await runner.start();
@@ -281,7 +304,7 @@ async function startRunner(): Promise<
 
 	getLogger().info("Runner started");
 
-	return [runner, runnerStarted, runnerStopped];
+	return runner;
 }
 
 export default app;

package/sdks/typescript/test-runner/src/log.ts

@@ -10,21 +10,12 @@ import {
 export type { Logger } from "pino";
 
 let baseLogger: Logger | undefined;
-let configuredLogLevel: Level | undefined;
 
 /** Cache of child loggers by logger name. */
 const loggerCache = new Map<string, Logger>();
 
-export function getPinoLevel(logLevel?: Level): LevelWithSilent {
-	// Priority: provided > configured > env > default
-	if (logLevel) {
-		return logLevel;
-	}
-
-	if (configuredLogLevel) {
-		return configuredLogLevel;
-	}
-
+export function getPinoLevel(): LevelWithSilent {
+	// Priority: env > default
 	return (process.env["LOG_LEVEL"] || "warn")
 		.toString()
 		.toLowerCase() as LevelWithSilent;
@@ -90,14 +81,9 @@ function customWrite(level: string, o: any) {
 /**
  * Configure the default logger with optional log level.
  */
-export async function configureDefaultLogger(logLevel?: Level): Promise<void> {
-	// Store the configured log level
-	if (logLevel) {
-		configuredLogLevel = logLevel;
-	}
-
+export async function configureDefaultLogger(): Promise<void> {
 	baseLogger = pino({
-		level: getPinoLevel(logLevel),
+		level: getPinoLevel(),
 		messageKey: "msg",
 		// Do not include pid/hostname in output
 		base: {},

package/artifacts/errors/actor.no_runners_available.json

@@ -1,5 +0,0 @@
-{
-  "code": "no_runners_available",
-  "group": "actor",
-  "message": "No runners are available in any datacenter. Validate the runner is listed in the Connect tab and that the runner's name matches the requested runner name."
-}

package/artifacts/errors/guard.actor_destroyed.json

@@ -1,5 +0,0 @@
-{
-  "code": "actor_destroyed",
-  "group": "guard",
-  "message": "Actor destroyed."
-}

package/artifacts/errors/guard.actor_not_found.json

@@ -1,5 +0,0 @@
-{
-  "code": "actor_not_found",
-  "group": "guard",
-  "message": "Actor not found."
-}

package/contrib-docs/ACTOR_KEY_RESERVATION.md

@@ -1,101 +0,0 @@
-# Actor Key Reservation
-
-Epoxy is used to globally store which datacenter an actor lives in for a given actor ID.
-
-## Schema
-
-In Epoxy KV store: `Actor key -> reservation ID`
-
-The reservation ID includes the datacenter of where the actor lives.
-
-## Consistency Limitations
-
-Actors have 2 touch points with Epoxy:
-
-- Reserve actor key (epaxos fast path = 1 RTT, epaxos slow path = 2 RTT)
-- Resolve actor ID for key (fast path = 0 RTT, slow path = 1 RTT to nearest DC that has the key)
-
-Resolving actor ID uses `kv_get_optimistic`, which assumes a value does not change after being set. This allows us to cache the actor's datacenter locally and never have to read from other nodes once we've resolved it once.
-
-## Reservation ID
-
-A reservation ID is a unique ID (which includes the datacenter label).
-
-**Why not store the actor ID**
-
-Actor IDs initially make sense to use since they include the datacenter ID that the actor lives in.
-
-Actor IDs can be created and destroyed, but our consistency limitations above requires that we do not change the value after set. Therefore, because we cannot update keys to new actor IDs, we cannot store the actor ID.
-
-**Why not store just the datacenter label**
-
-A naiive approach would be to store just the datacenter label in epoxy where the actor lives.
-
-See reservation chains below.
-
-### Reservation Chains & Moving Reservation Datacenters (Future Work)
-
-Eventually, actors need to be moved between datacenters OR destroyed then create in a different datacenter. 
-
-To do this, we'll set up reservation ID chains. Reservation ID chains are used to resolve where a reservation was moved to. When attempting to resolve a reservation that was moved, that datacenter will return the pointer to the reservation that it was moved to.
-
-Consider:
-
-- Actor 1 created in DC A with key "foo"
-	- Generates reservation ID X (in DC A)
-	- Epoxy stores: foo = reservation X
-- Actor 1 destroyed
-- Actor 2 created in DC B with key "foo"
-	- Generations reservation ID Y (in DC B)
-	- DC A stores pointer from reservation X to reservation Y
-	- Epoxy still has: foo = reservation X (does not get updated)
-- Next request to key "foo":
-	- Read reservation ID X (in DC A) from Epoxy
-	- Client send request to DC A with reservation ID X
-	- DC A returns pointer to reservation ID Y (in DC B)
-		- Client caches this pointer
-	- Client sends request to DC B with reservation ID Y
-- If the client requests key "foo" again:
-	- Read reservation ID X (in DC A) from Epoxy
-	- Client reads cache for reservation X to reservation Y (in DC B)
-	- Sends request to DC B
-
-The resulting state is:
-
-```
-Epoxy:
-- foo = reservation X (in DC A)
-
-Pointer cache (DC A):
-- Reservation X (in DC A) -> reservation Y (in DC B)
-```
-
-**Why not just use datacenter label**
-
-Consider a chain of pointers between the following datacenters:
-
-```
-DC label: 1 -> 2 -> 1 -> 3
-Pointer:    A    B    C
-```
-
-There is a race condition & possible infinite loop when:
-
-- DC 2 has pointer to DC 1 (pointer B)
-- DC 1 still has pointer to DC 2 (pointer A) (has not updated to DC 3, pointer C)
-
-Using unique reservation IDs allow us to create IDs like `{dc}.{unique}`. The chain would look like:
-
-```
-Reservation ID: 1.1 -> 2.2 -> 1.3 -> 3.4
-Pointer:            A      B      C
-```
-
-Now there cannot be a loop between DC 1 & 2 since clients will follow the chain of pointers.
-
-_This section needs more elaboration on edge cases._
-
-## Current Limitation: Keys are tied to a datacenter
-
-Because we cannot change the value of the reservation ID, actors can only be created in the original for a given ID.
-

package/contrib-docs/API.md

@@ -1,11 +0,0 @@
-# API
-
-## Packages
-
-- `packages/common/api-types`:
-    - `src/{}/mod.rs`: Common API types shared between multiple packages.
-    - `src/{}/{}.rs`: Request types used in api-peer (e.g. `get`, `list`). This is not in `rivet-api-peer` because these types must be used with `rivet-api-client` in packaes that don't depend ont `rivet-api-peer` (often because of cirular dependency issues, e.g. `rivet-api-peer` -> `pegboard` -> `rivet-api-peer`)
-- `packages/common/api-client`: Helper utilities for making requests to `api-peer`
-- `packages/common/api-builder`: Helper utilities for building API servers with Axum
-- `packages/services/api-peer`: API endpoint used for peer-to-peer communication across datacenters, only used by internal Rivet packages
-- `packages/services/api-public`: API endpoints used by clients calling Rivet APIs

package/contrib-docs/DOCKER.md

@@ -1,5 +0,0 @@
-# Runner Docker Compose
-
-`docker compose -f ../docker/dev/docker-compose.yml up --build`
-
-> Sometimes adding `--force-recreate` is required to get it to deploy the new build

package/contrib-docs/ERRORS.md

@@ -1,13 +0,0 @@
-# Errors
-
-## RivetError
-
-TODO: Document the derive macro
-TODO: Document .build() -> anyhow
-
-## Error chains
-
-- TODO: use `.chain().filter_map(|x| x.downcast_ref::<T>())` otherwise it'll only check the top-most error
-- TODO: use `#[source]` in thiserror variants in order for wrapped errors to show up in `.chain()`
-- TODO: `#[from]` automatically adds `#[source]`
-

package/contrib-docs/GUARD.md

@@ -1,76 +0,0 @@
-# Guard Routing & Retry Behavior
-
-## Guard Core - Retry Behavior
-
-The retry mechanism enables optimistic routing with cache invalidation:
-
-- **Fast path with cached routes**: Guard uses cached routing information to avoid expensive database lookups on every request, providing low-latency routing decisions
-- **Graceful cache invalidation**: When actors are stopped, destroyed, or moved to different runners, the cache becomes stale. Rather than proactively invalidating cache entries (which would require complex coordination), any failure response signals that the cached route is invalid
-- **Fresh service discovery on retry**: Retry attempts ignore the cache and perform fresh database lookups to discover current actor locations, ensuring requests reach the correct destination
-
-This approach optimizes for the common case (actors are running and routes are valid) while gracefully handling the uncommon case (actors have moved/stopped) without sacrificing performance
-
-### Retry Flow
-
-**Initial Request (Attempt 1)**:
-
-1. Check route cache for target location
-2. If cached route exists, send request to cached target
-3. If request succeeds → return response to client
-4. If request fails with retry-able error → proceed to retry
-
-**Retry Attempts (Attempts 2-N)**:
-
-1. Wait for exponential backoff delay (100ms × 2^(attempt-2))
-2. **Ignore cache** and perform fresh database lookup for target location
-3. Send request to newly discovered target
-4. If request succeeds → return response to client
-5. If request fails and max attempts not reached → repeat retry flow
-6. If max attempts exceeded → return `502 Bad Gateway` to client
-
-**Configuration**:
-
-- **Exponential backoff**: Starting interval 100ms, doubles each attempt (100ms, 200ms, 400ms...)
-- **Maximum attempts**: Default 3 total attempts
-- **Retry triggers**: TCP connection errors OR `503 Service Unavailable` with `x-rivet-error` header
-
-### Expected Service Response for Retries
-
-Services that want to trigger guard retries must respond with:
-
-- `503 Service Unavailable` status code
-- `x-rivet-error: <error>` header
-
-## Guard Router - Routing Logic
-
-### Routing Priority
-
-Requests are routed in the following priority order:
-
-#### 1. Target-Based Routing (Header: `x-rivet-target`)
-
-When the `x-rivet-target` header is present, routes to specific service types:
-
-**Actor Services** (`x-rivet-target: actor`):
-- **Required headers**: 
-  - `x-rivet-actor: <actor_id>` - UUID of the specific actor instance
-- **Optional headers**:
-  - `x-rivet-addr: <address>` - Direct address override for actor location
-- **Behavior**: Routes to the specific actor instance, with cross-datacenter routing if the actor resides in a different DC
-
-**Runner** (`x-rivet-target: runner`):
-- **Purpose**: Routes WebSocket connections to the Pegboard runner service
-- **Target**: Routes to the configured Pegboard service (`pegboard.lan_host:pegboard.port`)
-- **Use case**: WebSocket connections between runners and the orchestration system
-
-#### 2. API Routing (No target header)
-
-When no `x-rivet-target` header is present:
-- **Target**: Routes to the public API service (`api_public.lan_host:api_public.port`)
-- **Behavior**: Standard HTTP API requests for general application functionality
-- **Path preservation**: The original request path is preserved in the upstream request
-
-#### 3. Fallback
-
-Returns `404 Not Found` if no routing rules match.
-

package/contrib-docs/PEGBOARD_TUNNEL_RETRIES.md

@@ -1,83 +0,0 @@
-# Pegboard Tunnel Retries
-
-_TODO: Clean up this AI slop explanation_
-
-This document explains how retries are coordinated between Guard and Pegboard-based handlers when transient tunnel (UPS) issues occur, for both HTTP and WebSocket traffic.
-
-## HTTP
-
-- Signal: A retryable transient tunnel failure is signaled by returning an HTTP 503 with the `X-RIVET-ERROR` header set.
-  - Example (Pegboard Gateway): on tunnel closed (e.g., UPS `request_timeout`), the gateway replies with `503` and `X-RIVET-ERROR: pegboard_gateway.tunnel_closed`.
-
-- Guard behavior
-  - Guard considers a response retryable if `status == 503` and the `X-RIVET-ERROR` header is present.
-  - Guard then applies exponential backoff (from middleware-config: `max_attempts`, `initial_interval`), re-resolves the route with `ignore_cache = true`, and retries the request.
-  - On successful retry, traffic proceeds normally to the new target.
-  - If attempts are exhausted, Guard returns an upstream error to the client.
-
-- Notes for implementers
-  - For transient tunnel failures, return a 503 with `X-RIVET-ERROR` to trigger Guard retries. Use an empty body or minimal payload as appropriate.
-  - Do not 503 for non-transient errors; let the normal error flow apply.
-
-## WebSocket
-
-This section explains how WebSocket retries are coordinated between Guard and Pegboard-based handlers.
-
-## Overview
-
-- Retries are only possible before the client WebSocket is accepted ("opening" stage).
-- A retryable transient failure is signaled via the error `guard.websocket_service_unavailable` (WebSocketServiceUnavailable).
-- When Guard receives this error during opening, it re-resolves routes (ignoring cache), applies backoff, and retries with the same client socket and a new handler if available.
-- After the client socket is accepted ("open"), retries are not possible; the handler must close gracefully on failure.
-
-### Lifecycle Behavior
-
-- Opening (before accept)
-  - Source: handler detects a transient UPS/tunnel issue before awaiting the `HyperWebsocket` (e.g., failing to `ups.request(...)` to open, or failing to `ups.subscribe(...)`).
-  - Handler contract:
-    - Do not await the client websocket yet.
-    - Return the untouched `HyperWebsocket` in the error tuple so Guard still owns it: `Err((client_ws, err))`.
-    - The outer wrapper maps tunnel-closed UPS errors (e.g., `ups.request_timeout`) to `WebSocketServiceUnavailable`.
-  - Guard reaction:
-    - Treats `WebSocketServiceUnavailable` as retryable.
-    - Re-resolves the route with ignore-cache=true, using middleware-config retry/backoff.
-    - Outcomes:
-      - Re-resolve → `CustomServe`: reuse the same `client_ws` and retry with the new handler.
-      - Re-resolve → `Response`: accept client, send a Close with the response message as the reason.
-      - Re-resolve → `Target` (non-CustomServe) or mismatch: accept client, send a Close with a generic message (cannot retry).
-      - Attempts exhausted: accept client and send a Close with the original error message.
-
-- Open (after accept)
-  - The handler has awaited the client websocket; Guard can no longer retry.
-  - Any failures (UPS send/receive, serialization, etc.) should be handled by closing the connection gracefully.
-
-- Closing
-  - Best-effort signaling to the server via `ups.request(...)` and to the client via Close frames.
-  - Failures are ignored; no retries.
-
-- Closed
-  - No further action.
-
-### Implementer Guidance
-
-- Keep the client socket intact for retries:
-  - Only return a retryable error (that maps to `WebSocketServiceUnavailable`) before awaiting the client websocket.
-  - Return the socket in the error tuple: `Err((client_ws, err))`.
-
-- Map tunnel-closed errors at the wrapper:
-  - In the outer `handle_websocket` wrapper, detect tunnel-closed (e.g., `ups.request_timeout`) and map to `WebSocketServiceUnavailable`.
-  - `handle_websocket_inner` should return raw errors; do not construct `WebSocketServiceUnavailable` inside the inner function.
-
-- Use `ups.request` for all tunnel operations (open, messages, close):
-  - Pre-accept failures should surface as errors with the unconsumed `client_ws` so Guard can retry.
-  - Post-accept failures should break streams and close gracefully; do not attempt retries.
-
-- Backoff and attempts:
-  - Guard uses middleware-config values for `max_attempts` and `initial_interval` to perform exponential backoff between retries.
-  - Routes are re-resolved with ignore-cache=true on each retry to avoid stale targets.
-
-### Rationale
-
-- Returning the untouched `HyperWebsocket` in errors preserves the ability for Guard to re-route and retry without disconnecting the client.
-- Mapping tunnel-closed conditions to a single sentinel error (`WebSocketServiceUnavailable`) provides a consistent, guard-specific signal for retryability.
-- Restricting retries to pre-accept avoids protocol violations and simplifies resource ownership.