rivetkit 2.0.42 → 2.1.0-rc.1

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

@@ -3,10 +3,25 @@ import { setupDriverTest } from "../utils";
 import { describe, expect, test, type TestContext } from "vitest";
 
 export function runActorKvTests(driverTestConfig: DriverTestConfig) {
-	describe("Actor KV Tests", () => {
-		test("supports text encoding and decoding", async (c: TestContext) => {
-			const { client } = await setupDriverTest(c, driverTestConfig);
-			const kvHandle = client.kvActor.getOrCreate(["kv-text"]);
+	type KvTextHandle = {
+		putText: (key: string, value: string) => Promise<unknown>;
+		getText: (key: string) => Promise<string | null>;
+		listText: (prefix: string) => Promise<Array<{ key: string; value: string }>>;
+	};
+
+	type KvArrayBufferHandle = {
+		roundtripArrayBuffer: (key: string, bytes: number[]) => Promise<number[]>;
+	};
+
+		describe("Actor KV Tests", () => {
+			test("supports text encoding and decoding", async (c: TestContext) => {
+				const { client: rawClient } = await setupDriverTest(
+					c,
+					driverTestConfig,
+				);
+				const client = rawClient as any;
+				const kvHandle =
+					client.kvActor.getOrCreate(["kv-text"]) as unknown as KvTextHandle;
 
 			await kvHandle.putText("greeting", "hello");
 			const value = await kvHandle.getText("greeting");
@@ -26,19 +41,25 @@ export function runActorKvTests(driverTestConfig: DriverTestConfig) {
 		test(
 			"supports arrayBuffer encoding and decoding",
 			async (c: TestContext) => {
-			const { client } = await setupDriverTest(c, driverTestConfig);
-			const kvHandle = client.kvActor.getOrCreate(["kv-array-buffer"]);
-
-			const values = await kvHandle.roundtripArrayBuffer("bytes", [
-				4,
-				8,
-				15,
-				16,
-				23,
-				42,
-			]);
-			expect(values).toEqual([4, 8, 15, 16, 23, 42]);
-		},
-		);
-	});
-}
+				const { client: rawClient } = await setupDriverTest(
+					c,
+					driverTestConfig,
+				);
+				const client = rawClient as any;
+				const kvHandle = client.kvActor.getOrCreate([
+					"kv-array-buffer",
+				]) as unknown as KvArrayBufferHandle;
+
+				const values = await kvHandle.roundtripArrayBuffer("bytes", [
+					4,
+					8,
+					15,
+					16,
+					23,
+					42,
+				]);
+				expect(values).toEqual([4, 8, 15, 16, 23, 42]);
+			},
+			);
+		});
+	}

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

@@ -0,0 +1,324 @@
+import { describe, expect, test } from "vitest";
+import type { ActorError } from "@/client/mod";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest, waitFor } from "../utils";
+
+export function runActorQueueTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Queue Tests", () => {
+		test("client can send to actor queue", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["client-send"]);
+
+			await handle.send("greeting", { hello: "world" });
+
+			const message = await handle.receiveOne("greeting");
+			expect(message).toEqual({
+				name: "greeting",
+				body: { hello: "world" },
+			});
+		});
+
+		test("actor can send to its own queue", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["self-send"]);
+
+			await handle.sendToSelf("self", { value: 42 });
+
+			const message = await handle.receiveOne("self");
+			expect(message).toEqual({ name: "self", body: { value: 42 } });
+		});
+
+		test("next supports name arrays and counts", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["receive-array"]);
+
+			await handle.send("a", 1);
+			await handle.send("b", 2);
+			await handle.send("c", 3);
+
+			const messages = await handle.receiveMany(["a", "b"], { count: 2 });
+			expect(messages).toEqual([
+				{ name: "a", body: 1 },
+				{ name: "b", body: 2 },
+			]);
+		});
+
+		test("next supports request objects", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["receive-request"]);
+
+			await handle.send("one", "first");
+			await handle.send("two", "second");
+
+			const messages = await handle.receiveRequest({
+				names: ["one", "two"],
+				count: 2,
+			});
+			expect(messages).toEqual([
+				{ name: "one", body: "first" },
+				{ name: "two", body: "second" },
+			]);
+		});
+
+		test("next defaults to all names when names is omitted", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"receive-request-all",
+			]);
+
+			await handle.send("one", "first");
+			await handle.send("two", "second");
+
+			const messages = await handle.receiveRequest({ count: 2 });
+			expect(messages).toEqual([
+				{ name: "one", body: "first" },
+				{ name: "two", body: "second" },
+			]);
+		});
+
+		test("next timeout returns empty array", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["receive-timeout"]);
+
+			const promise = handle.receiveMany(["missing"], { timeout: 50 });
+			await waitFor(driverTestConfig, 60);
+			const messages = await promise;
+			expect(messages).toEqual([]);
+		});
+
+		test("tryNext does not wait and returns empty array", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["try-next-empty"]);
+
+			const messages = await handle.tryReceiveMany({
+				names: ["missing"],
+				count: 1,
+			});
+			expect(messages).toEqual([]);
+		});
+
+		test("abort throws ActorAborted", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["abort-test"]);
+
+			try {
+				await handle.waitForAbort();
+				expect.fail("expected ActorAborted error");
+			} catch (error) {
+				expect((error as ActorError).group).toBe("actor");
+				expect((error as ActorError).code).toBe("aborted");
+			}
+		});
+
+		test("next supports signal abort", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["signal-abort-next"]);
+
+			const result = await handle.waitForSignalAbort();
+			expect(result).toEqual({
+				group: "actor",
+				code: "aborted",
+			});
+		});
+
+		test("next supports actor abort when signal is provided", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"actor-abort-with-signal-next",
+			]);
+
+			const result = await handle.waitForActorAbortWithSignal();
+			expect(result).toEqual({
+				group: "actor",
+				code: "aborted",
+			});
+		});
+
+		test("iter supports signal abort", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["signal-abort-iter"]);
+
+			const result = await handle.iterWithSignalAbort();
+			expect(result).toEqual({ ok: true });
+		});
+
+		test("enforces queue size limit", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const key = `size-limit-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+			const handle = client.queueLimitedActor.getOrCreate([key]);
+
+			await handle.send("message", 1);
+
+			await waitFor(driverTestConfig, 10);
+
+			try {
+				await handle.send("message", 2);
+				expect.fail("expected queue full error");
+			} catch (error) {
+				expect(error).toBeInstanceOf(Error);
+				expect((error as Error).message).toContain(
+					"Queue is full. Limit is",
+				);
+				if (driverTestConfig.clientType !== "http") {
+					expect((error as ActorError).group).toBe("queue");
+					expect((error as ActorError).code).toBe("full");
+				}
+			}
+		});
+
+		test("enforces message size limit", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueLimitedActor.getOrCreate([
+				"message-limit",
+			]);
+			const largePayload = "a".repeat(200);
+
+			try {
+				await handle.send("oversize", largePayload);
+				expect.fail("expected message_too_large error");
+			} catch (error) {
+				expect((error as ActorError).group).toBe("queue");
+				expect((error as ActorError).code).toBe("message_too_large");
+			}
+		});
+
+		test("wait send returns completion response", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["wait-complete"]);
+
+			const actionPromise = handle.receiveAndComplete("tasks");
+			const result = await handle.send("tasks", 
+				{ value: 123 },
+				{ wait: true, timeout: 1_000 },
+			);
+
+			await actionPromise;
+			expect(result).toEqual({
+				status: "completed",
+				response: { echo: { value: 123 } },
+			});
+		});
+
+		test("wait send times out", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["wait-timeout"]);
+
+			const resultPromise = handle.send("timeout", 
+				{ value: 456 },
+				{ wait: true, timeout: 50 },
+			);
+
+			await waitFor(driverTestConfig, 60);
+			const result = await resultPromise;
+
+			expect(result.status).toBe("timedOut");
+		});
+
+		test("manual receive retries message when not completed", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"manual-retry-uncompleted",
+			]);
+
+			await handle.send("tasks", { value: 789 });
+			const first = await handle.receiveWithoutComplete("tasks");
+			expect(first).toEqual({ name: "tasks", body: { value: 789 } });
+
+			const retried = await handle.receiveOne("tasks", { timeout: 1_000 });
+			expect(retried).toEqual({ name: "tasks", body: { value: 789 } });
+		});
+
+		test("next throws when previous manual message is not completed", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"manual-next-requires-complete",
+			]);
+
+			await handle.send("tasks", { value: 111 });
+			const result = await handle.receiveManualThenNextWithoutComplete(
+				"tasks",
+			);
+			expect(result).toEqual({
+				group: "queue",
+				code: "previous_message_not_completed",
+			});
+		});
+
+		test("manual receive includes complete even without completion schema", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"complete-not-allowed",
+			]);
+
+			await handle.send("nowait", { value: "test" });
+			const result = await handle.receiveWithoutCompleteMethod("nowait");
+
+			expect(result).toEqual({
+				hasComplete: true,
+			});
+		});
+
+		test("manual receive retries queues without completion schema until completed", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"complete-not-allowed-consume",
+			]);
+
+			await handle.send("nowait", { value: "test" });
+			const result = await handle.receiveWithoutCompleteMethod("nowait");
+			expect(result).toEqual({ hasComplete: true });
+
+			const next = await handle.receiveOne("nowait", { timeout: 1_000 });
+			expect(next).toEqual({ name: "nowait", body: { value: "test" } });
+		});
+
+		test("complete throws when called twice", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"complete-twice",
+			]);
+
+			await handle.send("twice", { value: "test" });
+			const result = await handle.receiveAndCompleteTwice("twice");
+
+			expect(result).toEqual({
+				group: "queue",
+				code: "already_completed",
+			});
+		});
+
+		test("wait send no longer requires queue completion schema", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"missing-completion-schema",
+			]);
+
+			const result = await handle.send(
+				"nowait",
+				{ value: "test" },
+				{ wait: true, timeout: 50 },
+			);
+			expect(result).toEqual({ status: "timedOut" });
+		});
+
+		test("iter can consume queued messages", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate(["iter-consume"]);
+
+			await handle.send("one", "first");
+			const message = await handle.receiveWithIterator("one");
+			expect(message).toEqual({ name: "one", body: "first" });
+		});
+
+		test("queue async iterator can consume queued messages", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+			const handle = client.queueActor.getOrCreate([
+				"async-iter-consume",
+			]);
+
+			await handle.send("two", "second");
+			const message = await handle.receiveWithAsyncIterator();
+			expect(message).toEqual({ name: "two", body: "second" });
+		});
+	});
+}

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

@@ -0,0 +1,181 @@
+import { describe, expect, test } from "vitest";
+import { RUN_SLEEP_TIMEOUT } from "../../../fixtures/driver-test-suite/run";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest, waitFor } from "../utils";
+
+export function runActorRunTests(driverTestConfig: DriverTestConfig) {
+	describe.skipIf(driverTestConfig.skip?.sleep)("Actor Run Tests", () => {
+		test("run handler starts after actor startup", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithTicks.getOrCreate(["run-starts"]);
+
+			// Wait a bit for run handler to start
+			await waitFor(driverTestConfig, 100);
+
+			const state = await actor.getState();
+			expect(state.runStarted).toBe(true);
+			expect(state.tickCount).toBeGreaterThan(0);
+		});
+
+		test("run handler ticks continuously", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithTicks.getOrCreate(["run-ticks"]);
+
+			// Wait for some ticks
+			await waitFor(driverTestConfig, 200);
+
+			const state1 = await actor.getState();
+			expect(state1.tickCount).toBeGreaterThan(0);
+
+			const count1 = state1.tickCount;
+
+			// Wait more and check tick count increased
+			await waitFor(driverTestConfig, 200);
+
+			const state2 = await actor.getState();
+			expect(state2.tickCount).toBeGreaterThan(count1);
+		});
+
+			test("active run handler keeps actor awake past sleep timeout", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const actor = client.runWithTicks.getOrCreate([
+					"run-stays-awake",
+				]);
+
+				// Wait for run to start
+				await waitFor(driverTestConfig, 100);
+
+				const state1 = await actor.getState();
+				expect(state1.runStarted).toBe(true);
+				const tickCount1 = state1.tickCount;
+
+				// Active run loops should keep the actor awake.
+				await waitFor(driverTestConfig, RUN_SLEEP_TIMEOUT + 300);
+
+				const state2 = await actor.getState();
+				expect(state2.runStarted).toBe(true);
+				expect(state2.runExited).toBe(false);
+				expect(state2.tickCount).toBeGreaterThan(tickCount1);
+			});
+
+		test("actor without run handler works normally", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithoutHandler.getOrCreate([
+				"no-run-handler",
+			]);
+
+			const state = await actor.getState();
+			expect(state.wakeCount).toBe(1);
+
+			// Wait for sleep and wake again
+			await waitFor(driverTestConfig, RUN_SLEEP_TIMEOUT + 300);
+
+			const state2 = await actor.getState();
+			expect(state2.wakeCount).toBe(2);
+		});
+
+			test("run handler can consume from queue", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithQueueConsumer.getOrCreate([
+				"queue-consumer",
+			]);
+
+			// Wait for run handler to start
+			await waitFor(driverTestConfig, 100);
+
+			// Send some messages to the queue
+			await actor.sendMessage({ type: "test", value: 1 });
+			await actor.sendMessage({ type: "test", value: 2 });
+			await actor.sendMessage({ type: "test", value: 3 });
+
+			// Wait for messages to be consumed
+			await waitFor(driverTestConfig, 1200);
+
+			const state = await actor.getState();
+			expect(state.runStarted).toBe(true);
+			expect(state.messagesReceived.length).toBe(3);
+			expect(state.messagesReceived[0].body).toEqual({
+				type: "test",
+				value: 1,
+			});
+			expect(state.messagesReceived[1].body).toEqual({
+				type: "test",
+				value: 2,
+			});
+				expect(state.messagesReceived[2].body).toEqual({
+					type: "test",
+					value: 3,
+				});
+			});
+
+			test("queue-waiting run handler can sleep and resume", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const actor = client.runWithQueueConsumer.getOrCreate([
+					"queue-consumer-sleep",
+				]);
+
+				await waitFor(driverTestConfig, 100);
+				const state1 = await actor.getState();
+				expect(state1.runStarted).toBe(true);
+
+				await waitFor(driverTestConfig, RUN_SLEEP_TIMEOUT + 500);
+				const state2 = await actor.getState();
+
+				expect(state2.wakeCount).toBeGreaterThan(state1.wakeCount);
+			});
+
+		test("run handler that exits early triggers destroy", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithEarlyExit.getOrCreate(["early-exit"]);
+
+			// Wait for run to start and exit
+			await waitFor(driverTestConfig, 100);
+
+			const state1 = await actor.getState();
+			expect(state1.runStarted).toBe(true);
+
+			// Wait for the actor to be destroyed
+			await waitFor(driverTestConfig, 300);
+
+			// After the run handler exits early, the actor should be destroyed.
+			// Depending on the driver, it may be in a destroyed state or recreated.
+			// In the file-system driver test environment, the actor is not automatically
+			// rescheduled, so we just verify the initial behavior worked.
+			// A new getOrCreate should create a fresh actor.
+			const actor2 = client.runWithEarlyExit.getOrCreate([
+				"early-exit-fresh",
+			]);
+			const state2 = await actor2.getState();
+			expect(state2.runStarted).toBe(true);
+		});
+
+		test("run handler that throws error triggers destroy", async (c) => {
+			const { client } = await setupDriverTest(c, driverTestConfig);
+
+			const actor = client.runWithError.getOrCreate(["run-error"]);
+
+			// Wait for run to start and throw
+			await waitFor(driverTestConfig, 100);
+
+			const state1 = await actor.getState();
+			expect(state1.runStarted).toBe(true);
+
+			// Wait for the actor to be destroyed
+			await waitFor(driverTestConfig, 300);
+
+			// After the run handler throws, the actor should be destroyed.
+			// Similar to the early exit test, the driver may not automatically reschedule.
+			// A new getOrCreate should create a fresh actor.
+			const actor2 = client.runWithError.getOrCreate(["run-error-fresh"]);
+			const state2 = await actor2.getState();
+			expect(state2.runStarted).toBe(true);
+		});
+	});
+}

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

@@ -76,12 +76,15 @@ export function runActorScheduleTests(driverTestConfig: DriverTestConfig) {
 					// Wait for first task only
 					await waitFor(driverTestConfig, 500);
 					const history1 = await scheduled.getTaskHistory();
-					expect(history1).toEqual(["first"]);
+					expect(history1[0]).toBe("first");
 
 					// Wait for second task
 					await waitFor(driverTestConfig, 500);
 					const history2 = await scheduled.getTaskHistory();
-					expect(history2).toEqual(["first", "second"]);
+					expect(history2.slice(0, 2)).toEqual([
+						"first",
+						"second",
+					]);
 
 					// Wait for third task
 					await waitFor(driverTestConfig, 500);

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

@@ -283,7 +283,7 @@ export function runActorSleepTests(driverTestConfig: DriverTestConfig) {
 			}
 
 			// Connect WebSocket
-			const ws = await sleepActor.websocket();
+			const ws = await sleepActor.webSocket();
 
 			await new Promise<void>((resolve, reject) => {
 				ws.onopen = () => resolve();
@@ -292,7 +292,7 @@ export function runActorSleepTests(driverTestConfig: DriverTestConfig) {
 
 			// Wait for connection message
 			await new Promise<void>((resolve) => {
-				ws.onmessage = (event) => {
+				ws.onmessage = (event: { data: string }) => {
 					const data = JSON.parse(event.data);
 					if (data.type === "connected") {
 						resolve();
@@ -307,7 +307,7 @@ export function runActorSleepTests(driverTestConfig: DriverTestConfig) {
 			ws.send(JSON.stringify({ type: "getCounts" }));
 
 			const counts = await new Promise<any>((resolve) => {
-				ws.onmessage = (event) => {
+				ws.onmessage = (event: { data: string }) => {
 					const data = JSON.parse(event.data);
 					if (data.type === "counts") {
 						resolve(data);

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

@@ -0,0 +1,70 @@
+import { describe, expect, test } from "vitest";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest } from "../utils";
+
+export function runActorStatelessTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Stateless Tests", () => {
+		describe("Stateless Actor Operations", () => {
+			test("can call actions on stateless actor", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.statelessActor.getOrCreate();
+
+				const result = await instance.ping();
+				expect(result).toBe("pong");
+			});
+
+			test("can echo messages", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.statelessActor.getOrCreate();
+
+				const message = "Hello, World!";
+				const result = await instance.echo(message);
+				expect(result).toBe(message);
+			});
+
+			test("can access actorId", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.statelessActor.getOrCreate(["test-id"]);
+
+				const actorId = await instance.getActorId();
+				expect(actorId).toBeDefined();
+				expect(typeof actorId).toBe("string");
+			});
+
+			test("accessing state throws StateNotEnabled", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.statelessActor.getOrCreate();
+
+				const result = await instance.tryGetState();
+				expect(result.success).toBe(false);
+				expect(result.error).toContain("state");
+			});
+
+			test("accessing db throws DatabaseNotEnabled", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const instance = client.statelessActor.getOrCreate();
+
+				const result = await instance.tryGetDb();
+				expect(result.success).toBe(false);
+				expect(result.error).toContain("database");
+			});
+
+			test("multiple stateless actors can exist independently", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const actor1 = client.statelessActor.getOrCreate(["actor-1"]);
+				const actor2 = client.statelessActor.getOrCreate(["actor-2"]);
+
+				const id1 = await actor1.getActorId();
+				const id2 = await actor2.getActorId();
+
+				expect(id1).not.toBe(id2);
+			});
+		});
+	});
+}