rivetkit 2.0.1 → 2.0.3

package/src/driver-test-suite/tests/actor-error-handling.ts

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "vitest";
+import {
+	INTERNAL_ERROR_CODE,
+	INTERNAL_ERROR_DESCRIPTION,
+} from "@/actor/errors";
+import { assertUnreachable } from "@/actor/utils";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest } from "../utils";
+
+export function runActorErrorHandlingTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Error Handling Tests", () => {
+		describe("UserError Handling", () => {
+			test("should handle simple UserError with message", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Try to call an action that throws a simple UserError
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				try {
+					await handle.throwSimpleError();
+					// If we get here, the test should fail
+					expect(true).toBe(false); // This should not be reached
+				} catch (error: any) {
+					// Verify the error properties
+					expect(error.message).toBe("Simple error message");
+					// Default code is "user_error" when not specified
+					expect(error.code).toBe("user_error");
+					// No metadata by default
+					expect(error.metadata).toBeUndefined();
+				}
+			});
+
+			test("should handle detailed UserError with code and metadata", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Try to call an action that throws a detailed UserError
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				try {
+					await handle.throwDetailedError();
+					// If we get here, the test should fail
+					expect(true).toBe(false); // This should not be reached
+				} catch (error: any) {
+					// Verify the error properties
+					expect(error.message).toBe("Detailed error message");
+					expect(error.code).toBe("detailed_error");
+					expect(error.metadata).toBeDefined();
+					expect(error.metadata.reason).toBe("test");
+					expect(error.metadata.timestamp).toBeDefined();
+				}
+			});
+		});
+
+		describe("Internal Error Handling", () => {
+			test("should convert internal errors to safe format", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Try to call an action that throws an internal error
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				try {
+					await handle.throwInternalError();
+					// If we get here, the test should fail
+					expect(true).toBe(false); // This should not be reached
+				} catch (error: any) {
+					if (driverTestConfig.clientType === "http") {
+						// Verify the error is converted to a safe format
+						expect(error.code).toBe(INTERNAL_ERROR_CODE);
+						// Original error details should not be exposed
+						expect(error.message).toBe(INTERNAL_ERROR_DESCRIPTION);
+					} else if (driverTestConfig.clientType === "inline") {
+						// Verify that original error is preserved
+						expect(error.code).toBe(INTERNAL_ERROR_CODE);
+						expect(error.message).toBe("This is an internal error");
+					} else {
+						assertUnreachable(driverTestConfig.clientType);
+					}
+				}
+			});
+		});
+
+		// TODO: Does not work with fake timers
+		describe.skip("Action Timeout", () => {
+			test("should handle action timeouts with custom duration", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Call an action that should time out
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				// This should throw a timeout error because errorHandlingActor has
+				// a 500ms timeout and this action tries to run for much longer
+				const timeoutPromise = handle.timeoutAction();
+
+				try {
+					await timeoutPromise;
+					// If we get here, the test failed - timeout didn't occur
+					expect(true).toBe(false); // This should not be reached
+				} catch (error: any) {
+					// Verify it's a timeout error
+					expect(error.message).toMatch(/timed out/i);
+				}
+			});
+
+			test("should successfully run actions within timeout", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Call an action with a delay shorter than the timeout
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				// This should succeed because 200ms < 500ms timeout
+				const result = await handle.delayedAction(200);
+				expect(result).toBe("Completed after 200ms");
+			});
+
+			test("should respect different timeouts for different actors", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// The following actors have different timeout settings:
+				// customTimeoutActor: 200ms timeout
+				// standardTimeoutActor: default timeout (much longer)
+
+				// This should fail - 300ms delay with 200ms timeout
+				try {
+					await client.customTimeoutActor.getOrCreate().slowAction();
+					// Should not reach here
+					expect(true).toBe(false);
+				} catch (error: any) {
+					expect(error.message).toMatch(/timed out/i);
+				}
+
+				// This should succeed - 50ms delay with 200ms timeout
+				const quickResult = await client.customTimeoutActor
+					.getOrCreate()
+					.quickAction();
+				expect(quickResult).toBe("Quick action completed");
+			});
+		});
+
+		describe("Error Recovery", () => {
+			test("should continue working after errors", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const handle = client.errorHandlingActor.getOrCreate();
+
+				// Trigger an error
+				try {
+					await handle.throwSimpleError();
+				} catch (error) {
+					// Ignore error
+				}
+
+				// Actor should still work after error
+				const result = await handle.successfulAction();
+				expect(result).toBe("success");
+			});
+		});
+	});
+}

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

@@ -0,0 +1,259 @@
+import { describe, expect, test } from "vitest";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest } from "../utils";
+
+export function runActorHandleTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Handle Tests", () => {
+		describe("Access Methods", () => {
+			test("should use .get() to access a actor", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create actor first
+				await client.counter.create(["test-get-handle"]);
+
+				// Access using get
+				const handle = client.counter.get(["test-get-handle"]);
+
+				// Verify Action works
+				const count = await handle.increment(5);
+				expect(count).toBe(5);
+
+				const retrievedCount = await handle.getCount();
+				expect(retrievedCount).toBe(5);
+			});
+
+			test("should use .getForId() to access a actor by ID", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create a actor first to get its ID
+				const handle = client.counter.getOrCreate(["test-get-for-id-handle"]);
+				await handle.increment(3);
+				const actorId = await handle.resolve();
+
+				// Access using getForId
+				const idHandle = client.counter.getForId(actorId);
+
+				// Verify Action works and state is preserved
+				const count = await idHandle.getCount();
+				expect(count).toBe(3);
+
+				const newCount = await idHandle.increment(4);
+				expect(newCount).toBe(7);
+			});
+
+			test("should use .getOrCreate() to access or create a actor", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Access using getOrCreate - should create the actor
+				const handle = client.counter.getOrCreate([
+					"test-get-or-create-handle",
+				]);
+
+				// Verify Action works
+				const count = await handle.increment(7);
+				expect(count).toBe(7);
+
+				// Get the same actor again - should retrieve existing actor
+				const sameHandle = client.counter.getOrCreate([
+					"test-get-or-create-handle",
+				]);
+				const retrievedCount = await sameHandle.getCount();
+				expect(retrievedCount).toBe(7);
+			});
+
+			test("should use (await create()) to create and return a handle", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create actor and get handle
+				const handle = await client.counter.create(["test-create-handle"]);
+
+				// Verify Action works
+				const count = await handle.increment(9);
+				expect(count).toBe(9);
+
+				const retrievedCount = await handle.getCount();
+				expect(retrievedCount).toBe(9);
+			});
+		});
+
+		describe("Action Functionality", () => {
+			test("should call actions directly on the handle", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const handle = client.counter.getOrCreate(["test-action-handle"]);
+
+				// Call multiple actions in sequence
+				const count1 = await handle.increment(3);
+				expect(count1).toBe(3);
+
+				const count2 = await handle.increment(5);
+				expect(count2).toBe(8);
+
+				const retrievedCount = await handle.getCount();
+				expect(retrievedCount).toBe(8);
+			});
+
+			test("should handle independent handles to the same actor", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create two handles to the same actor
+				const handle1 = client.counter.getOrCreate(["test-multiple-handles"]);
+				const handle2 = client.counter.get(["test-multiple-handles"]);
+
+				// Call actions on both handles
+				await handle1.increment(3);
+				const count = await handle2.getCount();
+
+				// Verify both handles access the same state
+				expect(count).toBe(3);
+
+				const finalCount = await handle2.increment(4);
+				expect(finalCount).toBe(7);
+
+				const checkCount = await handle1.getCount();
+				expect(checkCount).toBe(7);
+			});
+
+			test("should resolve a actor's ID", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				const handle = client.counter.getOrCreate(["test-resolve-id"]);
+
+				// Call an action to ensure actor exists
+				await handle.increment(1);
+
+				// Resolve the ID
+				const actorId = await handle.resolve();
+
+				// Verify we got a valid ID (string)
+				expect(typeof actorId).toBe("string");
+				expect(actorId).not.toBe("");
+
+				// Verify we can use this ID to get the actor
+				const idHandle = client.counter.getForId(actorId);
+				const count = await idHandle.getCount();
+				expect(count).toBe(1);
+			});
+		});
+
+		describe("Lifecycle Hooks", () => {
+			test("should trigger lifecycle hooks on actor creation", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Get or create a new actor - this should trigger onStart
+				const handle = client.counterWithLifecycle.getOrCreate([
+					"test-lifecycle-handle",
+				]);
+
+				// Verify onStart was triggered
+				const initialEvents = await handle.getEvents();
+				expect(initialEvents).toContain("onStart");
+
+				// Create a separate handle to the same actor
+				const sameHandle = client.counterWithLifecycle.getOrCreate([
+					"test-lifecycle-handle",
+				]);
+
+				// Verify events still include onStart but don't duplicate it
+				// (onStart should only be called once when the actor is first created)
+				const events = await sameHandle.getEvents();
+				expect(events).toContain("onStart");
+				expect(events.filter((e) => e === "onStart").length).toBe(1);
+			});
+
+			test("should trigger lifecycle hooks for each Action call", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create a normal handle to view events
+				const viewHandle = client.counterWithLifecycle.getOrCreate([
+					"test-lifecycle-action",
+				]);
+
+				// Initial state should only have onStart
+				const initialEvents = await viewHandle.getEvents();
+				expect(initialEvents).toContain("onStart");
+				expect(initialEvents).not.toContain("onBeforeConnect");
+				expect(initialEvents).not.toContain("onConnect");
+				expect(initialEvents).not.toContain("onDisconnect");
+
+				// Create a handle with trackLifecycle enabled for testing Action calls
+				const trackingHandle = client.counterWithLifecycle.getOrCreate(
+					["test-lifecycle-action"],
+					{ params: { trackLifecycle: true } },
+				);
+
+				// Make an Action call
+				await trackingHandle.increment(5);
+
+				// Check that it triggered the lifecycle hooks
+				const eventsAfterAction = await viewHandle.getEvents();
+
+				// Should have onBeforeConnect, onConnect, and onDisconnect for the Action call
+				expect(eventsAfterAction).toContain("onBeforeConnect");
+				expect(eventsAfterAction).toContain("onConnect");
+				expect(eventsAfterAction).toContain("onDisconnect");
+
+				// Each should have count 1
+				expect(
+					eventsAfterAction.filter((e) => e === "onBeforeConnect").length,
+				).toBe(1);
+				expect(eventsAfterAction.filter((e) => e === "onConnect").length).toBe(
+					1,
+				);
+				expect(
+					eventsAfterAction.filter((e) => e === "onDisconnect").length,
+				).toBe(1);
+
+				// Make another Action call
+				await trackingHandle.increment(10);
+
+				// Check that it triggered another set of lifecycle hooks
+				const eventsAfterSecondAction = await viewHandle.getEvents();
+
+				// Each hook should now have count 2
+				expect(
+					eventsAfterSecondAction.filter((e) => e === "onBeforeConnect").length,
+				).toBe(2);
+				expect(
+					eventsAfterSecondAction.filter((e) => e === "onConnect").length,
+				).toBe(2);
+				expect(
+					eventsAfterSecondAction.filter((e) => e === "onDisconnect").length,
+				).toBe(2);
+			});
+
+			test("should trigger lifecycle hooks for each Action call across multiple handles", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create a normal handle to view events
+				const viewHandle = client.counterWithLifecycle.getOrCreate([
+					"test-lifecycle-multi-handle",
+				]);
+
+				// Create two tracking handles to the same actor
+				const trackingHandle1 = client.counterWithLifecycle.getOrCreate(
+					["test-lifecycle-multi-handle"],
+					{ params: { trackLifecycle: true } },
+				);
+
+				const trackingHandle2 = client.counterWithLifecycle.getOrCreate(
+					["test-lifecycle-multi-handle"],
+					{ params: { trackLifecycle: true } },
+				);
+
+				// Make Action calls on both handles
+				await trackingHandle1.increment(5);
+				await trackingHandle2.increment(10);
+
+				// Check lifecycle hooks
+				const events = await viewHandle.getEvents();
+
+				// Should have 1 onStart, 2 each of onBeforeConnect, onConnect, and onDisconnect
+				expect(events.filter((e) => e === "onStart").length).toBe(1);
+				expect(events.filter((e) => e === "onBeforeConnect").length).toBe(2);
+				expect(events.filter((e) => e === "onConnect").length).toBe(2);
+				expect(events.filter((e) => e === "onDisconnect").length).toBe(2);
+			});
+		});
+	});
+}

package/src/driver-test-suite/tests/actor-inline-client.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "vitest";
+import type { DriverTestConfig } from "../mod";
+import { setupDriverTest } from "../utils";
+
+export function runActorInlineClientTests(driverTestConfig: DriverTestConfig) {
+	describe("Actor Inline Client Tests", () => {
+		describe("Stateless Client Calls", () => {
+			test("should make stateless calls to other actors", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create the inline client actor
+				const inlineClientHandle = client.inlineClientActor.getOrCreate([
+					"inline-client-test",
+				]);
+
+				// Test calling counter.increment via inline client
+				const result = await inlineClientHandle.callCounterIncrement(5);
+				expect(result).toBe(5);
+
+				// Verify the counter state was actually updated
+				const counterState = await inlineClientHandle.getCounterState();
+				expect(counterState).toBe(5);
+
+				// Check that messages were logged
+				const messages = await inlineClientHandle.getMessages();
+				expect(messages).toHaveLength(2);
+				expect(messages[0]).toContain("Called counter.increment(5), result: 5");
+				expect(messages[1]).toContain("Got counter state: 5");
+			});
+
+			test("should handle multiple stateless calls", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create the inline client actor
+				const inlineClientHandle = client.inlineClientActor.getOrCreate([
+					"inline-client-multi",
+				]);
+
+				// Clear any existing messages
+				await inlineClientHandle.clearMessages();
+
+				// Make multiple calls
+				const result1 = await inlineClientHandle.callCounterIncrement(3);
+				const result2 = await inlineClientHandle.callCounterIncrement(7);
+				const finalState = await inlineClientHandle.getCounterState();
+
+				expect(result1).toBe(3);
+				expect(result2).toBe(10); // 3 + 7
+				expect(finalState).toBe(10);
+
+				// Check messages
+				const messages = await inlineClientHandle.getMessages();
+				expect(messages).toHaveLength(3);
+				expect(messages[0]).toContain("Called counter.increment(3), result: 3");
+				expect(messages[1]).toContain(
+					"Called counter.increment(7), result: 10",
+				);
+				expect(messages[2]).toContain("Got counter state: 10");
+			});
+		});
+
+		describe("Stateful Client Calls", () => {
+			test("should connect to other actors and receive events", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create the inline client actor
+				const inlineClientHandle = client.inlineClientActor.getOrCreate([
+					"inline-client-stateful",
+				]);
+
+				// Clear any existing messages
+				await inlineClientHandle.clearMessages();
+
+				// Test stateful connection with events
+				const result = await inlineClientHandle.connectToCounterAndIncrement(4);
+
+				expect(result.result1).toBe(4);
+				expect(result.result2).toBe(12); // 4 + 8
+				expect(result.events).toEqual([4, 12]); // Should have received both events
+
+				// Check that message was logged
+				const messages = await inlineClientHandle.getMessages();
+				expect(messages).toHaveLength(1);
+				expect(messages[0]).toContain(
+					"Connected to counter, incremented by 4 and 8",
+				);
+				expect(messages[0]).toContain("results: 4, 12");
+				expect(messages[0]).toContain("events: [4,12]");
+			});
+
+			test("should handle stateful connection independently", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create the inline client actor
+				const inlineClientHandle = client.inlineClientActor.getOrCreate([
+					"inline-client-independent",
+				]);
+
+				// Clear any existing messages
+				await inlineClientHandle.clearMessages();
+
+				// Test with different increment values
+				const result = await inlineClientHandle.connectToCounterAndIncrement(2);
+
+				expect(result.result1).toBe(2);
+				expect(result.result2).toBe(6); // 2 + 4
+				expect(result.events).toEqual([2, 6]);
+
+				// Verify the state is independent from previous tests
+				const messages = await inlineClientHandle.getMessages();
+				expect(messages).toHaveLength(1);
+				expect(messages[0]).toContain(
+					"Connected to counter, incremented by 2 and 4",
+				);
+			});
+		});
+
+		describe("Mixed Client Usage", () => {
+			test("should handle both stateless and stateful calls", async (c) => {
+				const { client } = await setupDriverTest(c, driverTestConfig);
+
+				// Create the inline client actor
+				const inlineClientHandle = client.inlineClientActor.getOrCreate([
+					"inline-client-mixed",
+				]);
+
+				// Clear any existing messages
+				await inlineClientHandle.clearMessages();
+
+				// Start with stateless calls
+				await inlineClientHandle.callCounterIncrement(1);
+				const statelessResult = await inlineClientHandle.getCounterState();
+				expect(statelessResult).toBe(1);
+
+				// Then do stateful call
+				const statefulResult =
+					await inlineClientHandle.connectToCounterAndIncrement(3);
+				expect(statefulResult.result1).toBe(3);
+				expect(statefulResult.result2).toBe(9); // 3 + 6
+
+				// Check all messages were logged
+				const messages = await inlineClientHandle.getMessages();
+				expect(messages).toHaveLength(3);
+				expect(messages[0]).toContain("Called counter.increment(1), result: 1");
+				expect(messages[1]).toContain("Got counter state: 1");
+				expect(messages[2]).toContain(
+					"Connected to counter, incremented by 3 and 6",
+				);
+			});
+		});
+	});
+}