@rivetkit/engine-runner 2.1.4 → 2.1.6-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivetkit/engine-runner",
-  "version": "2.1.4",
+  "version": "2.1.6-rc.1",
   "type": "module",
   "files": [
     "dist",
@@ -22,7 +22,7 @@
     "pino": "^9.9.5",
     "ws": "^8.18.3",
     "@rivetkit/virtual-websocket": "2.0.33",
-    "@rivetkit/engine-runner-protocol": "2.1.4"
+    "@rivetkit/engine-runner-protocol": "2.1.6-rc.1"
   },
   "devDependencies": {
     "@types/node": "^22.18.1",

package/src/mod.ts

@@ -12,13 +12,16 @@ import {
 	unreachable,
 } from "./utils";
 import { importWebSocket } from "./websocket.js";
+import {
+	v4 as uuidv4,
+} from "uuid";
 
 export type { HibernatingWebSocketMetadata };
 export { RunnerActor, type ActorConfig };
 export { idToStr } from "./utils";
 
 const KV_EXPIRE: number = 30_000;
-const PROTOCOL_VERSION: number = 5;
+const PROTOCOL_VERSION: number = 7;
 
 /** Warn once the backlog significantly exceeds the server's ack batch size. */
 const EVENT_BACKLOG_WARN_THRESHOLD = 10_000;
@@ -40,7 +43,6 @@ export interface RunnerConfig {
 	namespace: string;
 	totalSlots: number;
 	runnerName: string;
-	runnerKey: string;
 	prepopulateActorNames: Record<string, { metadata: Record<string, any> }>;
 	metadata?: Record<string, any>;
 	onConnected: () => void;
@@ -175,6 +177,15 @@ export interface RunnerConfig {
 
 	onActorStop: (actorId: string, generation: number) => Promise<void>;
 	noAutoShutdown?: boolean;
+
+	/**
+	 * Debug option to inject artificial latency (in ms) into WebSocket
+	 * communication. Messages are queued and delivered in order after the
+	 * configured delay.
+	 *
+	 * @experimental For testing only.
+	 */
+	debugLatencyMs?: number;
 }
 
 export interface KvListOptions {
@@ -193,6 +204,7 @@ interface KvRequestEntry {
 
 export class Runner {
 	#config: RunnerConfig;
+	#runnerKey: string = uuidv4();
 
 	get config(): RunnerConfig {
 		return this.#config;
@@ -443,6 +455,8 @@ export class Runner {
 			throw error;
 		}
 
+		// When changing SIGTERM/shutdown behavior, update
+		// website/src/content/docs/actors/versions.mdx (SIGTERM Handling section).
 		if (!this.#config.noAutoShutdown) {
 			if (!SIGNAL_HANDLERS.length) {
 				process.on("SIGTERM", async () => {
@@ -614,6 +628,9 @@ export class Runner {
 	 * - All actors are stopped
 	 * - The WebSocket connection is closed
 	 * - The shutdown timeout is reached (120 seconds)
+	 *
+	 * When changing this timeout, update
+	 * website/src/content/docs/actors/versions.mdx (SIGTERM Handling section).
 	 */
 	async #waitForActorsToStop(ws: WebSocket): Promise<void> {
 		const shutdownTimeout = 120_000; // 120 seconds
@@ -705,7 +722,7 @@ export class Runner {
 		const baseUrl = wsEndpoint.endsWith("/")
 			? wsEndpoint.slice(0, -1)
 			: wsEndpoint;
-		return `${baseUrl}/runners/connect?protocol_version=${PROTOCOL_VERSION}&namespace=${encodeURIComponent(this.#config.namespace)}&runner_key=${encodeURIComponent(this.#config.runnerKey)}`;
+		return `${baseUrl}/runners/connect?protocol_version=${PROTOCOL_VERSION}&namespace=${encodeURIComponent(this.#config.namespace)}&runner_key=${encodeURIComponent(this.#runnerKey)}`;
 	}
 
 	// MARK: Runner protocol
@@ -735,7 +752,7 @@ export class Runner {
 			msg: "connecting",
 			endpoint: this.pegboardEndpoint,
 			namespace: this.#config.namespace,
-			runnerKey: this.#config.runnerKey,
+			runnerKey: this.#runnerKey,
 			hasToken: !!this.config.token,
 		});
 
@@ -823,6 +840,8 @@ export class Runner {
 				throw new Error(`expected binary data, got ${typeof ev.data}`);
 			}
 
+			await this.#injectLatency();
+
 			// Parse message
 			const message = protocol.decodeToClient(buf);
 			this.log?.debug({
@@ -1551,6 +1570,31 @@ export class Runner {
 		await this.#sendKvRequest(actorId, requestData);
 	}
 
+	async kvDeleteRange(
+		actorId: string,
+		start: Uint8Array,
+		end: Uint8Array,
+	): Promise<void> {
+		const startKey: protocol.KvKey = start.buffer.slice(
+			start.byteOffset,
+			start.byteOffset + start.byteLength,
+		) as ArrayBuffer;
+		const endKey: protocol.KvKey = end.buffer.slice(
+			end.byteOffset,
+			end.byteOffset + end.byteLength,
+		) as ArrayBuffer;
+
+		const requestData: protocol.KvRequestData = {
+			tag: "KvDeleteRangeRequest",
+			val: {
+				start: startKey,
+				end: endKey,
+			},
+		};
+
+		await this.#sendKvRequest(actorId, requestData);
+	}
+
 	async kvDrop(actorId: string): Promise<void> {
 		const requestData: protocol.KvRequestData = {
 			tag: "KvDropRequest",
@@ -1662,6 +1706,13 @@ export class Runner {
 		}
 	}
 
+	/** Resolves after the configured debug latency, or immediately if none. */
+	#injectLatency(): Promise<void> {
+		const ms = this.#config.debugLatencyMs;
+		if (!ms) return Promise.resolve();
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+
 	/** Asserts WebSocket exists and is ready. */
 	getPegboardWebSocketIfReady(): WebSocket | undefined {
 		if (
@@ -1681,14 +1732,19 @@ export class Runner {
 		});
 
 		const encoded = protocol.encodeToServer(message);
-		const pegboardWebSocket = this.getPegboardWebSocketIfReady();
-		if (pegboardWebSocket) {
-			pegboardWebSocket.send(encoded);
-		} else {
-			this.log?.error({
-				msg: "WebSocket not available or not open for sending data",
-			});
-		}
+
+		// Normally synchronous. When debugLatencyMs is set, the send is
+		// deferred but message order is preserved.
+		this.#injectLatency().then(() => {
+			const pegboardWebSocket = this.getPegboardWebSocketIfReady();
+			if (pegboardWebSocket) {
+				pegboardWebSocket.send(encoded);
+			} else {
+				this.log?.error({
+					msg: "WebSocket not available or not open for sending data",
+				});
+			}
+		});
 	}
 
 	sendHibernatableWebSocketMessageAck(

package/src/stringify.ts

@@ -303,6 +303,10 @@ function stringifyKvRequestData(data: protocol.KvRequestData): string {
 			const { keys } = data.val;
 			return `KvDeleteRequest{keys: ${keys.length}}`;
 		}
+		case "KvDeleteRangeRequest": {
+			const { start, end } = data.val;
+			return `KvDeleteRangeRequest{start: ${stringifyArrayBuffer(start)}, end: ${stringifyArrayBuffer(end)}}`;
+		}
 		case "KvDropRequest":
 			return "KvDropRequest";
 	}

package/src/tunnel.ts

@@ -5,11 +5,6 @@ import type {
 	RequestId,
 } from "@rivetkit/engine-runner-protocol";
 import type { Logger } from "pino";
-import {
-	parse as uuidparse,
-	stringify as uuidstringify,
-	v4 as uuidv4,
-} from "uuid";
 import { type Runner, type RunnerActor, RunnerShutdownError } from "./mod";
 import {
 	stringifyToClientTunnelMessageKind,