rivetkit 2.0.42 → 2.1.0-rc.1

package/src/driver-test-suite/tests/actor-workflow.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "vitest";
+import {
+	WORKFLOW_QUEUE_NAME,
+} from "../../../fixtures/driver-test-suite/workflow";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest, waitFor } from "../utils";
+
+export function runActorWorkflowTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Workflow Tests", () => {
+		test("replays steps and guards state access", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const actor = client.workflowCounterActor.getOrCreate([
+				"workflow-basic",
+			]);
+
+			await waitFor(driverTestConfig, 1000);
+			const state = await actor.getState();
+			expect(state.runCount).toBeGreaterThan(0);
+			expect(state.history.length).toBeGreaterThan(0);
+			expect(state.guardTriggered).toBe(true);
+		});
+
+		test("consumes queue messages via workflow queue.next", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const actor = client.workflowQueueActor.getOrCreate(["workflow-queue"]);
+
+			await actor.send(WORKFLOW_QUEUE_NAME, {
+				hello: "world",
+			});
+
+			await waitFor(driverTestConfig, 200);
+			const messages = await actor.getMessages();
+			expect(messages).toEqual([{ hello: "world" }]);
+		});
+
+		test("workflow queue.next supports completing wait sends", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const actor = client.workflowQueueActor.getOrCreate([
+				"workflow-queue-wait",
+			]);
+
+			const result = await actor.sendAndWait({ value: 123 });
+			expect(result).toEqual({
+				status: "completed",
+				response: { echo: { value: 123 } },
+			});
+		});
+
+		test("db and client are step-only in workflow context", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const actor = client.workflowAccessActor.getOrCreate([
+				"workflow-access",
+			]);
+
+			let state = await actor.getState();
+			for (let i = 0; i < 20 && state.insideDbCount === 0; i++) {
+				await waitFor(driverTestConfig, 50);
+				state = await actor.getState();
+			}
+
+			expect(state.outsideDbError).toBe(
+				"db is only available inside workflow steps",
+			);
+			expect(state.outsideClientError).toBe(
+				"client is only available inside workflow steps",
+			);
+			expect(state.insideDbCount).toBeGreaterThan(0);
+			expect(state.insideClientAvailable).toBe(true);
+		});
+
+		test("sleeps and resumes between ticks", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const actor = client.workflowSleepActor.getOrCreate(["workflow-sleep"]);
+
+			const initial = await actor.getState();
+			await waitFor(driverTestConfig, 200);
+			const next = await actor.getState();
+
+			expect(next.ticks).toBeGreaterThan(initial.ticks);
+		});
+
+		test.skipIf(driverTestConfig.skip?.sleep)(
+			"workflow run teardown does not wait for runStopTimeout",
+			async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+				const actor = client.workflowStopTeardownActor.getOrCreate([
+					"workflow-stop-teardown",
+				]);
+
+				await actor.getTimeline();
+				await waitFor(driverTestConfig, 1_200);
+				const timeline = await actor.getTimeline();
+
+				expect(timeline.wakeAts.length).toBeGreaterThanOrEqual(2);
+				expect(timeline.sleepAts.length).toBeGreaterThanOrEqual(1);
+
+				const firstSleepDelayMs =
+					timeline.sleepAts[0] - timeline.wakeAts[0];
+				expect(firstSleepDelayMs).toBeLessThan(1_800);
+			},
+		);
+
+		// NOTE: Test for workflow persistence across actor sleep is complex because
+		// calling c.sleep() during a workflow prevents clean shutdown. The workflow
+		// persistence is implicitly tested by the "sleeps and resumes between ticks"
+		// test which verifies the workflow continues from persisted state.
+	});
+}

package/src/driver-test-suite/tests/manager-driver.ts

@@ -224,6 +224,17 @@ export function runManagerDriverTests(driverTestConfig: DriverTestConfig) {
 		});
 
 		describe("Key Matching", () => {
+			test("multi-part actor keys are passed through correctly", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create an actor with a multi-part key
+				const multiPartKey = ["tenant/with/slash", "room"];
+				const counter = client.counter.getOrCreate(multiPartKey);
+
+				// Should be preserved as a multi-part key (["tenant/with/slash", "room"])
+				expect(await counter.getKey()).toEqual(multiPartKey);
+			});
+
 			test("matches actors only with exactly the same keys", async (c) => {
 				const { client } = await setupDriverTest(c, driverTestConfig);
 

package/src/driver-test-suite/tests/raw-http-request-properties.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "vitest";
-import { z } from "zod";
+import { z } from "zod/v4";
 import { registry } from "../../../fixtures/driver-test-suite/registry";
 import type { DriverTestConfig } from "../mod";
 import { setupDriverTest } from "../utils";

package/src/driver-test-suite/tests/raw-websocket.ts

@@ -8,7 +8,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const { client } = await setupDriverTest(c, driverTestConfig);
 			const actor = client.rawWebSocketActor.getOrCreate(["basic"]);
 
-			const ws = await actor.websocket();
+			const ws = await actor.webSocket();
 
 			// The WebSocket should already be open since openWebSocket waits for openPromise
 			// But we still need to ensure any buffered events are processed
@@ -50,7 +50,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const { client } = await setupDriverTest(c, driverTestConfig);
 			const actor = client.rawWebSocketActor.getOrCreate(["echo"]);
 
-			const ws = await actor.websocket();
+			const ws = await actor.webSocket();
 
 			// Check if WebSocket is already open
 			if (ws.readyState !== WebSocket.OPEN) {
@@ -92,7 +92,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const { client } = await setupDriverTest(c, driverTestConfig);
 			const actor = client.rawWebSocketActor.getOrCreate(["ping"]);
 
-			const ws = await actor.websocket();
+			const ws = await actor.webSocket();
 
 			// Check if WebSocket is already open
 			if (ws.readyState !== WebSocket.OPEN) {
@@ -134,7 +134,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const actor1 = client.rawWebSocketActor.getOrCreate(["stats"]);
 
 			// Create first connection to ensure actor exists
-			const ws1 = await actor1.websocket();
+			const ws1 = await actor1.webSocket();
 			const ws1MessagePromise = new Promise<void>((resolve, reject) => {
 				ws1.addEventListener("message", () => resolve(), {
 					once: true,
@@ -147,7 +147,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 
 			// Now get reference to same actor
 			const actor2 = client.rawWebSocketActor.get(["stats"]);
-			const ws2 = await actor2.websocket();
+			const ws2 = await actor2.webSocket();
 			const ws2MessagePromise = new Promise<void>((resolve, reject) => {
 				ws2.addEventListener("message", () => resolve(), {
 					once: true,
@@ -203,7 +203,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 				"binary",
 			]);
 
-			const ws = await actor.websocket();
+			const ws = await actor.webSocket();
 
 			// Check if WebSocket is already open
 			if (ws.readyState !== WebSocket.OPEN) {
@@ -267,7 +267,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const { client } = await setupDriverTest(c, driverTestConfig);
 			const actor = client.rawWebSocketActor.getOrCreate(["paths"]);
 
-			const ws = await actor.websocket("custom/path");
+			const ws = await actor.webSocket("custom/path");
 
 			await new Promise<void>((resolve, reject) => {
 				ws.addEventListener("open", () => {
@@ -297,7 +297,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			const { client } = await setupDriverTest(c, driverTestConfig);
 			const actor = client.rawWebSocketActor.getOrCreate(["close-test"]);
 
-			const ws = await actor.websocket();
+			const ws = await actor.webSocket();
 
 			// Check if WebSocket is already open
 			if (ws.readyState !== WebSocket.OPEN) {
@@ -343,7 +343,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			]);
 
 			// Create first connection
-			const ws1 = await actor.websocket();
+			const ws1 = await actor.webSocket();
 
 			// Wait for open event
 			await new Promise<void>((resolve, reject) => {
@@ -367,7 +367,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			expect(welcome1.connectionCount).toBe(1);
 
 			// Create second connection to same actor
-			const ws2 = await actor.websocket();
+			const ws2 = await actor.webSocket();
 
 			await new Promise<void>((resolve, reject) => {
 				ws2.addEventListener("open", () => resolve(), { once: true });
@@ -438,7 +438,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 			]);
 
 			// Test WebSocket with query parameters
-			const ws = await actor.websocket(
+			const ws = await actor.webSocket(
 				"api/v1/stream?token=abc123&user=test",
 			);
 
@@ -478,7 +478,7 @@ export function runRawWebSocketTests(driverTestConfig: DriverTestConfig) {
 
 			// Test WebSocket with ONLY query parameters on the base path
 			// This tests the case where path is "/websocket?foo=bar" without trailing slash
-			const ws = await actor.websocket("?token=secret&session=123");
+			const ws = await actor.webSocket("?token=secret&session=123");
 
 			await new Promise<void>((resolve, reject) => {
 				ws.addEventListener("open", () => resolve(), { once: true });

package/src/drivers/default.ts

@@ -28,6 +28,11 @@ export function chooseDefaultDriver(
 		return createEngineDriver();
 	}
 
-	loggerWithoutContext().debug({ msg: "using default file system driver" });
-	return createFileSystemOrMemoryDriver(true);
+	loggerWithoutContext().debug({
+		msg: "using default file system driver",
+		storagePath: config.storagePath,
+	});
+	return createFileSystemOrMemoryDriver(true, {
+		path: config.storagePath,
+	});
 }

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

@@ -82,8 +82,8 @@ export class EngineActorDriver implements ActorDriver {
 	#actors: Map<string, ActorHandler> = new Map();
 	#actorRouter: ActorRouter;
 
-	#runnerStarted: PromiseWithResolvers<undefined> = promiseWithResolvers();
-	#runnerStopped: PromiseWithResolvers<undefined> = promiseWithResolvers();
+	#runnerStarted: PromiseWithResolvers<undefined> = promiseWithResolvers((reason) => logger().warn({ msg: "unhandled runner started promise rejection", reason }));
+	#runnerStopped: PromiseWithResolvers<undefined> = promiseWithResolvers((reason) => logger().warn({ msg: "unhandled runner stopped promise rejection", reason }));
 	#isRunnerStopped: boolean = false;
 
 	// HACK: Track actor stop intent locally since the runner protocol doesn't
@@ -232,9 +232,7 @@ export class EngineActorDriver implements ActorDriver {
 		this.#runner.setAlarm(actor.id, timestamp);
 	}
 
-	async getDatabase(_actorId: string): Promise<unknown | undefined> {
-		return undefined;
-	}
+	// No database overrides - will use KV-backed implementation from rivetkit/db
 
 	// MARK: - Batch KV operations
 	async kvBatchPut(
@@ -428,7 +426,7 @@ export class EngineActorDriver implements ActorDriver {
 			// async operations to avoid race conditions where multiple calls might try to
 			// create the same handler simultaneously.
 			handler = {
-				actorStartPromise: promiseWithResolvers(),
+				actorStartPromise: promiseWithResolvers((reason) => logger().warn({ msg: "unhandled actor start promise rejection", reason })),
 			};
 			this.#actors.set(actorId, handler);
 		}
@@ -437,40 +435,50 @@ export class EngineActorDriver implements ActorDriver {
 		invariant(actorConfig.key, "actor should have a key");
 		const key = deserializeActorKey(actorConfig.key);
 
-		// Initialize storage
-		const [persistDataBuffer] = await this.#runner.kvGet(actorId, [
-			KEYS.PERSIST_DATA,
-		]);
-		if (persistDataBuffer === null) {
-			const initialKvState = getInitialActorKvState(input);
-			await this.#runner.kvPut(actorId, initialKvState);
-			logger().debug({
-				msg: "initialized persist data for new actor",
-				actorId,
-			});
-		} else {
-			logger().debug({
-				msg: "found existing persist data for actor",
-				actorId,
-				dataSize: persistDataBuffer.byteLength,
-			});
-		}
+		try {
+			// Initialize storage
+			const [persistDataBuffer] = await this.#runner.kvGet(actorId, [
+				KEYS.PERSIST_DATA,
+			]);
+			if (persistDataBuffer === null) {
+				const initialKvState = getInitialActorKvState(input);
+				await this.#runner.kvPut(actorId, initialKvState);
+				logger().debug({
+					msg: "initialized persist data for new actor",
+					actorId,
+				});
+			} else {
+				logger().debug({
+					msg: "found existing persist data for actor",
+					actorId,
+					dataSize: persistDataBuffer.byteLength,
+				});
+			}
 
-		// Create actor instance
-		const definition = lookupInRegistry(this.#config, actorConfig.name);
-		handler.actor = definition.instantiate();
+			// Create actor instance
+			const definition = lookupInRegistry(this.#config, actorConfig.name);
+			handler.actor = await definition.instantiate();
 
-		// Start actor
-		await handler.actor.start(
-			this,
-			this.#inlineClient,
-			actorId,
-			name,
-			key,
-			"unknown", // TODO: Add regions
-		);
+			// Start actor
+			await handler.actor.start(
+				this,
+				this.#inlineClient,
+				actorId,
+				name,
+				key,
+				"unknown", // TODO: Add regions
+			);
 
-		logger().debug({ msg: "runner actor started", actorId, name, key });
+			logger().debug({ msg: "runner actor started", actorId, name, key });
+		} catch (innerError) {
+			const error = new Error(
+				`Failed to start actor ${actorId}: ${innerError}`,
+				{ cause: innerError },
+			);
+			handler.actorStartPromise?.reject(error);
+			handler.actorStartPromise = undefined;
+			throw error;
+		}
 	}
 
 	async #runnerOnActorStop(

package/src/drivers/engine/config.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v4";
 import {
 	ClientConfigSchemaBase,
 	transformClientConfig,

package/src/drivers/file-system/actor.ts

@@ -1,4 +1,6 @@
 import type { AnyClient } from "@/client/client";
+import type { RawDatabaseClient } from "@/db/config";
+import type { SqliteVfs } from "@rivetkit/sqlite-vfs";
 import type {
 	ActorDriver,
 	AnyActorInstance,
@@ -79,8 +81,20 @@ export class FileSystemActorDriver implements ActorDriver {
 		await this.#state.setActorAlarm(actor.id, timestamp);
 	}
 
-	getDatabase(actorId: string): Promise<unknown | undefined> {
-		return this.#state.createDatabase(actorId);
+	/** Creates a SQLite VFS instance for creating KV-backed databases */
+	async createSqliteVfs(): Promise<SqliteVfs> {
+		// Dynamic import keeps @rivetkit/sqlite out of the main entrypoint bundle,
+		// preserving tree-shakeability for environments that don't use SQLite.
+		// The async @rivetkit/sqlite build is not re-entrant per module instance.
+		// Returning a fresh SqliteVfs here gives each actor its own module,
+		// allowing actor-level parallelism without cross-actor re-entry.
+		//
+		// The specifier is built via concatenation so that bundlers like
+		// wrangler's esbuild cannot statically analyze and attempt to
+		// bundle the module (it is never used on Cloudflare Workers).
+		const specifier = "@rivetkit/" + "sqlite-vfs";
+		const { SqliteVfs } = await import(specifier);
+		return new SqliteVfs();
 	}
 
 	startSleep(actorId: string): void {
@@ -91,4 +105,8 @@ export class FileSystemActorDriver implements ActorDriver {
 	async startDestroy(actorId: string): Promise<void> {
 		await this.#state.destroyActor(actorId);
 	}
+
+	async onBeforeActorStart(actor: AnyActorInstance): Promise<void> {
+		await actor.cleanupPersistedConnections("file-system-driver.start");
+	}
 }