rivetkit 2.0.2 → 2.0.4

package/src/actor/keys.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, test } from "vitest";
+import {
+	deserializeActorKey,
+	EMPTY_KEY,
+	KEY_SEPARATOR,
+	serializeActorKey,
+} from "./keys";
+
+describe("Key serialization and deserialization", () => {
+	// Test serialization
+	describe("serializeActorKey", () => {
+		test("serializes empty key array", () => {
+			expect(serializeActorKey([])).toBe(EMPTY_KEY);
+		});
+
+		test("serializes single key", () => {
+			expect(serializeActorKey(["test"])).toBe("test");
+		});
+
+		test("serializes multiple keys", () => {
+			expect(serializeActorKey(["a", "b", "c"])).toBe(
+				`a${KEY_SEPARATOR}b${KEY_SEPARATOR}c`,
+			);
+		});
+
+		test("escapes forward slashes in keys", () => {
+			expect(serializeActorKey(["a/b"])).toBe("a\\/b");
+			expect(serializeActorKey(["a/b", "c"])).toBe(`a\\/b${KEY_SEPARATOR}c`);
+		});
+
+		test("escapes empty key marker in keys", () => {
+			expect(serializeActorKey([EMPTY_KEY])).toBe(`\\${EMPTY_KEY}`);
+		});
+
+		test("handles complex keys", () => {
+			expect(serializeActorKey(["a/b", EMPTY_KEY, "c/d"])).toBe(
+				`a\\/b${KEY_SEPARATOR}\\${EMPTY_KEY}${KEY_SEPARATOR}c\\/d`,
+			);
+		});
+	});
+
+	// Test deserialization
+	describe("deserializeActorKey", () => {
+		test("deserializes empty string", () => {
+			expect(deserializeActorKey("")).toEqual([]);
+		});
+
+		test("deserializes undefined/null", () => {
+			expect(deserializeActorKey(undefined as unknown as string)).toEqual([]);
+			expect(deserializeActorKey(null as unknown as string)).toEqual([]);
+		});
+
+		test("deserializes empty key marker", () => {
+			expect(deserializeActorKey(EMPTY_KEY)).toEqual([]);
+		});
+
+		test("deserializes single key", () => {
+			expect(deserializeActorKey("test")).toEqual(["test"]);
+		});
+
+		test("deserializes multiple keys", () => {
+			expect(
+				deserializeActorKey(`a${KEY_SEPARATOR}b${KEY_SEPARATOR}c`),
+			).toEqual(["a", "b", "c"]);
+		});
+
+		test("deserializes keys with escaped forward slashes", () => {
+			expect(deserializeActorKey("a\\/b")).toEqual(["a/b"]);
+			expect(deserializeActorKey(`a\\/b${KEY_SEPARATOR}c`)).toEqual([
+				"a/b",
+				"c",
+			]);
+		});
+
+		test("deserializes keys with escaped empty key marker", () => {
+			expect(deserializeActorKey(`\\${EMPTY_KEY}`)).toEqual([EMPTY_KEY]);
+		});
+
+		test("deserializes complex keys", () => {
+			expect(
+				deserializeActorKey(
+					`a\\/b${KEY_SEPARATOR}\\${EMPTY_KEY}${KEY_SEPARATOR}c\\/d`,
+				),
+			).toEqual(["a/b", EMPTY_KEY, "c/d"]);
+		});
+	});
+
+	// Test edge cases
+	describe("edge cases", () => {
+		test("handles empty string parts", () => {
+			const testCases: Array<[string[], string]> = [
+				[[""], "\\0"],
+				[["a", "", "b"], "a/\\0/b"],
+				[["", "a"], "\\0/a"],
+				[["a", ""], "a/\\0"],
+				[["", "", ""], "\\0/\\0/\\0"],
+				[["", "a", "", "b", ""], "\\0/a/\\0/b/\\0"],
+				[[], "/"],
+				[["test"], "test"],
+				[["a", "b", "c"], "a/b/c"],
+				[["a/b", "c"], "a\\/b/c"],
+				[[EMPTY_KEY], "\\/"],
+				[["a/b", EMPTY_KEY, "c/d"], "a\\/b/\\//c\\/d"],
+				[
+					["special\\chars", "more:complex,keys", "final key"],
+					"special\\\\chars/more:complex,keys/final key",
+				],
+			];
+
+			for (const [key, expectedSerialized] of testCases) {
+				const serialized = serializeActorKey(key);
+				expect(serialized).toBe(expectedSerialized);
+				const deserialized = deserializeActorKey(serialized);
+				expect(deserialized).toEqual(key);
+			}
+		});
+
+		test("differentiates empty array from array with empty string", () => {
+			const emptyArray: string[] = [];
+			const arrayWithEmptyString = [""];
+
+			const serialized1 = serializeActorKey(emptyArray);
+			const serialized2 = serializeActorKey(arrayWithEmptyString);
+
+			expect(serialized1).toBe(EMPTY_KEY); // Should be "/"
+			expect(serialized2).not.toBe(EMPTY_KEY); // Should NOT be "/"
+			expect(serialized2).toBe("\\0"); // Empty string becomes \0 marker
+
+			expect(deserializeActorKey(serialized1)).toEqual(emptyArray);
+			expect(deserializeActorKey(serialized2)).toEqual(arrayWithEmptyString);
+		});
+
+		test("handles mix of empty strings and forward slash (EMPTY_KEY)", () => {
+			const testCases: Array<[string[], string]> = [
+				[["", EMPTY_KEY, ""], "\\0/\\//\\0"],
+				[[EMPTY_KEY, ""], "\\//\\0"],
+				[["", EMPTY_KEY], "\\0/\\/"],
+				[["a", "", EMPTY_KEY, "", "b"], "a/\\0/\\//\\0/b"],
+			];
+
+			for (const [key, expectedSerialized] of testCases) {
+				const serialized = serializeActorKey(key);
+				expect(serialized).toBe(expectedSerialized);
+				const deserialized = deserializeActorKey(serialized);
+				expect(deserialized).toEqual(key);
+			}
+		});
+
+		test("handles literal backslash-zero string", () => {
+			const testCases: Array<[string[], string]> = [
+				[["\\0"], "\\\\0"], // Literal \0 string
+				[["a\\0b"], "a\\\\0b"], // Literal \0 in middle
+				[["\\0", ""], "\\\\0/\\0"], // Literal \0 with empty string
+				[["", "\\0"], "\\0/\\\\0"], // Empty string with literal \0
+			];
+
+			for (const [key, expectedSerialized] of testCases) {
+				const serialized = serializeActorKey(key);
+				expect(serialized).toBe(expectedSerialized);
+				const deserialized = deserializeActorKey(serialized);
+				expect(deserialized).toEqual(key);
+			}
+		});
+
+		test("handles backslash at the end", () => {
+			const key = ["abc\\"];
+			const serialized = serializeActorKey(key);
+			expect(serialized).toBe("abc\\\\");
+			const deserialized = deserializeActorKey(serialized);
+			expect(deserialized).toEqual(key);
+		});
+
+		test("handles backslashes in middle of string", () => {
+			const testCases: Array<[string[], string]> = [
+				[["abc\\def"], "abc\\\\def"],
+				[["abc\\\\def"], "abc\\\\\\\\def"],
+				[["path\\to\\file"], "path\\\\to\\\\file"],
+			];
+
+			for (const [key, expectedSerialized] of testCases) {
+				const serialized = serializeActorKey(key);
+				expect(serialized).toBe(expectedSerialized);
+				const deserialized = deserializeActorKey(serialized);
+				expect(deserialized).toEqual(key);
+			}
+		});
+
+		test("handles forward slashes at the end of strings", () => {
+			const serialized = serializeActorKey(["abc\\/"]);
+			expect(deserializeActorKey(serialized)).toEqual(["abc\\/"]);
+		});
+
+		test("handles mixed backslashes and forward slashes", () => {
+			const testCases: Array<[string[], string]> = [
+				[["path\\to\\file/dir"], "path\\\\to\\\\file\\/dir"],
+				[["file\\with/slash"], "file\\\\with\\/slash"],
+				[["path\\to\\file", "with/slash"], "path\\\\to\\\\file/with\\/slash"],
+			];
+
+			for (const [key, expectedSerialized] of testCases) {
+				const serialized = serializeActorKey(key);
+				expect(serialized).toBe(expectedSerialized);
+				const deserialized = deserializeActorKey(serialized);
+				expect(deserialized).toEqual(key);
+			}
+		});
+
+		test("handles multiple consecutive forward slashes", () => {
+			const key = ["a//b"];
+			const serialized = serializeActorKey(key);
+			expect(serialized).toBe("a\\/\\/b");
+			const deserialized = deserializeActorKey(serialized);
+			expect(deserialized).toEqual(key);
+		});
+
+		test("handles special characters", () => {
+			const key = ["a💻b", "c🔑d"];
+			const serialized = serializeActorKey(key);
+			expect(serialized).toBe("a💻b/c🔑d");
+			const deserialized = deserializeActorKey(serialized);
+			expect(deserialized).toEqual(key);
+		});
+
+		test("handles escaped forward slashes immediately after separator", () => {
+			const key = ["abc", "/def"];
+			const serialized = serializeActorKey(key);
+			expect(serialized).toBe(`abc${KEY_SEPARATOR}\\/def`);
+			expect(deserializeActorKey(serialized)).toEqual(key);
+		});
+	});
+
+	// Test exact key matching
+	describe("exact key matching", () => {
+		test("differentiates [a,b] from [a,b,c]", () => {
+			const key1 = ["a", "b"];
+			const key2 = ["a", "b", "c"];
+
+			const serialized1 = serializeActorKey(key1);
+			const serialized2 = serializeActorKey(key2);
+
+			expect(serialized1).not.toBe(serialized2);
+		});
+
+		test("differentiates [a,b] from [a]", () => {
+			const key1 = ["a", "b"];
+			const key2 = ["a"];
+
+			const serialized1 = serializeActorKey(key1);
+			const serialized2 = serializeActorKey(key2);
+
+			expect(serialized1).not.toBe(serialized2);
+		});
+
+		test("differentiates [a/b] from [a,b]", () => {
+			const key1 = ["a/b"];
+			const key2 = ["a", "b"];
+
+			const serialized1 = serializeActorKey(key1);
+			const serialized2 = serializeActorKey(key2);
+
+			expect(serialized1).not.toBe(serialized2);
+			expect(deserializeActorKey(serialized1)).toEqual(key1);
+			expect(deserializeActorKey(serialized2)).toEqual(key2);
+		});
+	});
+});

package/src/actor/keys.ts

@@ -0,0 +1,89 @@
+import type { ActorKey } from "@/mod";
+
+export const EMPTY_KEY = "/";
+export const KEY_SEPARATOR = "/";
+
+export function serializeActorKey(key: ActorKey): string {
+	// Use a special marker for empty key arrays
+	if (key.length === 0) {
+		return EMPTY_KEY;
+	}
+
+	// Escape each key part to handle the separator and the empty key marker
+	const escapedParts = key.map((part) => {
+		// Handle empty strings by using a special marker
+		if (part === "") {
+			return "\\0"; // Use \0 as a marker for empty strings
+		}
+
+		// Escape backslashes first to avoid conflicts with our markers
+		let escaped = part.replace(/\\/g, "\\\\");
+
+		// Then escape separators
+		escaped = escaped.replace(/\//g, `\\${KEY_SEPARATOR}`);
+
+		return escaped;
+	});
+
+	return escapedParts.join(KEY_SEPARATOR);
+}
+
+export function deserializeActorKey(keyString: string | undefined): ActorKey {
+	// Check for special empty key marker
+	if (
+		keyString === undefined ||
+		keyString === null ||
+		keyString === EMPTY_KEY
+	) {
+		return [];
+	}
+
+	// Split by unescaped separators and unescape the escaped characters
+	const parts: string[] = [];
+	let currentPart = "";
+	let escaping = false;
+	let isEmptyStringMarker = false;
+
+	for (let i = 0; i < keyString.length; i++) {
+		const char = keyString[i];
+
+		if (escaping) {
+			// Handle special escape sequences
+			if (char === "0") {
+				// \0 represents an empty string marker
+				isEmptyStringMarker = true;
+			} else {
+				// This is an escaped character, add it directly
+				currentPart += char;
+			}
+			escaping = false;
+		} else if (char === "\\") {
+			// Start of an escape sequence
+			escaping = true;
+		} else if (char === KEY_SEPARATOR) {
+			// This is a separator
+			if (isEmptyStringMarker) {
+				parts.push("");
+				isEmptyStringMarker = false;
+			} else {
+				parts.push(currentPart);
+			}
+			currentPart = "";
+		} else {
+			// Regular character
+			currentPart += char;
+		}
+	}
+
+	// Add the last part
+	if (escaping) {
+		// Incomplete escape at the end - treat as literal backslash
+		parts.push(currentPart + "\\");
+	} else if (isEmptyStringMarker) {
+		parts.push("");
+	} else if (currentPart !== "" || parts.length > 0) {
+		parts.push(currentPart);
+	}
+
+	return parts;
+}

package/src/actor/log.ts

@@ -0,0 +1,6 @@
+import { getLogger } from "@/common/log";
+
+/** Prever to use ActorInstance.rlog child logger. This does not provide context in the log, should only be used as a last resort if you cannot pass the actor's child logger. */
+export function loggerWithoutContext() {
+	return getLogger("actor-runtime");
+}

package/src/actor/mod.ts

@@ -0,0 +1,108 @@
+import {
+	type Actions,
+	type ActorConfig,
+	type ActorConfigInput,
+	ActorConfigSchema,
+	ActorTypes,
+} from "./config";
+import type { AnyDatabaseProvider } from "./database";
+import { ActorDefinition } from "./definition";
+
+export function actor<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TActions extends Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase
+	>,
+>(
+	input: ActorConfigInput<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TActions
+	>,
+): ActorDefinition<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase,
+	TActions
+> {
+	const config = ActorConfigSchema.parse(input) as ActorConfig<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase
+	>;
+	return new ActorDefinition(config);
+}
+export type { Encoding } from "@/actor/protocol/serde";
+export type {
+	UniversalErrorEvent,
+	UniversalEvent,
+	UniversalEventSource,
+	UniversalMessageEvent,
+} from "@/common/eventsource-interface";
+export type { UpgradeWebSocketArgs } from "@/common/inline-websocket-adapter2";
+export type {
+	RivetCloseEvent,
+	RivetEvent,
+	RivetMessageEvent,
+	UniversalWebSocket,
+} from "@/common/websocket-interface";
+export type { ActorKey } from "@/manager/protocol/query";
+export type { ActionContext } from "./action";
+export type * from "./config";
+export type {
+	Conn,
+	ConnectionDriver,
+	ConnectionStatus,
+	generateConnId,
+	generateConnToken,
+} from "./connection";
+export {
+	CONNECTION_DRIVER_HTTP,
+	CONNECTION_DRIVER_SSE,
+	CONNECTION_DRIVER_WEBSOCKET,
+} from "./connection";
+export type { ActorContext } from "./context";
+export type {
+	ActionContextOf,
+	ActorContextOf,
+	ActorDefinition,
+	AnyActorDefinition,
+} from "./definition";
+export { lookupInRegistry } from "./definition";
+export { UserError, type UserErrorOptions } from "./errors";
+export {
+	createGenericConnDrivers,
+	GenericConnGlobalState,
+} from "./generic-conn-driver";
+export type { AnyActorInstance } from "./instance";
+export {
+	type ActorRouter,
+	createActorRouter,
+	PATH_CONNECT_WEBSOCKET,
+	PATH_RAW_WEBSOCKET_PREFIX,
+} from "./router";
+export {
+	ALLOWED_PUBLIC_HEADERS,
+	handleRawWebSocketHandler,
+	handleWebSocketConnect,
+} from "./router-endpoints";

package/src/actor/persisted.ts

@@ -0,0 +1,42 @@
+import type { ConnectionDriver } from "./connection";
+
+/** State object that gets automatically persisted to storage. */
+export interface PersistedActor<S, CP, CS, I> {
+	input?: I;
+	hasInitiated: boolean;
+	state: S;
+	connections: PersistedConn<CP, CS>[];
+	scheduledEvents: PersistedScheduleEvent[];
+}
+
+/** Object representing connection that gets persisted to storage. */
+export interface PersistedConn<CP, CS> {
+	connId: string;
+	token: string;
+	connDriver: ConnectionDriver;
+	connDriverState: unknown;
+	params: CP;
+	state: CS;
+	authData?: unknown;
+	subscriptions: PersistedSubscription[];
+	lastSeen: number;
+}
+
+export interface PersistedSubscription {
+	eventName: string;
+}
+
+export interface GenericPersistedScheduleEvent {
+	actionName: string;
+	args: ArrayBuffer | null;
+}
+
+export type PersistedScheduleEventKind = {
+	generic: GenericPersistedScheduleEvent;
+};
+
+export interface PersistedScheduleEvent {
+	eventId: string;
+	timestamp: number;
+	kind: PersistedScheduleEventKind;
+}