rivetkit 2.0.2 → 2.0.4-rc.1

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

@@ -0,0 +1,325 @@
+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("nextBatch 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("nextBatch 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("nextBatch 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("tryNextBatch 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 waitTimeout = driverTestConfig.useRealTimers ? 5_000 : 1_000;
+
+				const actionPromise = handle.receiveAndComplete("tasks");
+				const result = await handle.send("tasks", 
+					{ value: 123 },
+					{ wait: true, timeout: waitTimeout },
+				);
+
+			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

@@ -0,0 +1,97 @@
+import { describe, expect, test } from "vitest";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest, waitFor } from "../utils";
+
+export function runActorScheduleTests(driverTestConfig: DriverTestConfig) {
+	describe.skipIf(driverTestConfig.skip?.schedule)(
+		"Actor Schedule Tests",
+		() => {
+			// See alarm + actor sleeping test in actor-sleep.ts
+
+			describe("Scheduled Alarms", () => {
+				test("executes c.schedule.at() with specific timestamp", async (c) => {
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
+
+					// Create instance
+					const scheduled = client.scheduled.getOrCreate();
+
+					// Schedule a task to run using timestamp
+					const timestamp = Date.now() + 250;
+					await scheduled.scheduleTaskAt(timestamp);
+
+					// Wait for longer than the scheduled time
+					await waitFor(driverTestConfig, 500);
+
+					// Verify the scheduled task ran
+					const lastRun = await scheduled.getLastRun();
+					const scheduledCount = await scheduled.getScheduledCount();
+
+					expect(lastRun).toBeGreaterThan(0);
+					expect(scheduledCount).toBe(1);
+				});
+
+				test("executes c.schedule.after() with delay", async (c) => {
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
+
+					// Create instance
+					const scheduled = client.scheduled.getOrCreate();
+
+					// Schedule a task to run using delay
+					await scheduled.scheduleTaskAfter(250);
+
+					// Wait for longer than the scheduled time
+					await waitFor(driverTestConfig, 500);
+
+					// Verify the scheduled task ran
+					const lastRun = await scheduled.getLastRun();
+					const scheduledCount = await scheduled.getScheduledCount();
+
+					expect(lastRun).toBeGreaterThan(0);
+					expect(scheduledCount).toBe(1);
+				});
+
+				test("multiple scheduled tasks execute in order", async (c) => {
+					const { client } = await setupDriverTest(
+						c,
+						driverTestConfig,
+					);
+
+					// Create instance
+					const scheduled = client.scheduled.getOrCreate();
+
+					// Reset history to start fresh
+					await scheduled.clearHistory();
+
+					// Schedule multiple tasks with different delays
+					await scheduled.scheduleTaskAfterWithId("first", 250);
+					await scheduled.scheduleTaskAfterWithId("second", 750);
+					await scheduled.scheduleTaskAfterWithId("third", 1250);
+
+					// Wait for first task only
+					await waitFor(driverTestConfig, 500);
+					const history1 = await scheduled.getTaskHistory();
+					expect(history1[0]).toBe("first");
+
+					// Wait for second task
+					await waitFor(driverTestConfig, 500);
+					const history2 = await scheduled.getTaskHistory();
+					expect(history2.slice(0, 2)).toEqual([
+						"first",
+						"second",
+					]);
+
+					// Wait for third task
+					await waitFor(driverTestConfig, 500);
+					const history3 = await scheduled.getTaskHistory();
+					expect(history3).toEqual(["first", "second", "third"]);
+				});
+			});
+		},
+	);
+}