rivetkit 2.0.1 → 2.0.3

package/src/drivers/engine/api-endpoints.ts

@@ -0,0 +1,128 @@
+import { apiCall } from "./api-utils";
+import type { Config } from "./config";
+import { serializeActorKey } from "./keys";
+
+// MARK: Common types
+export type RivetId = string;
+
+export interface Actor {
+	actor_id: RivetId;
+	name: string;
+	key: string;
+	namespace_id: RivetId;
+	runner_name_selector: string;
+	create_ts: number;
+	connectable_ts?: number | null;
+	destroy_ts?: number | null;
+	sleep_ts?: number | null;
+	start_ts?: number | null;
+}
+
+export interface ActorsGetResponse {
+	actor: Actor;
+}
+
+export interface ActorsGetByIdResponse {
+	actor_id?: RivetId | null;
+}
+
+export interface ActorsGetOrCreateResponse {
+	actor: Actor;
+	created: boolean;
+}
+
+export interface ActorsGetOrCreateByIdResponse {
+	actor_id: RivetId;
+	created: boolean;
+}
+
+export interface ActorsCreateRequest {
+	name: string;
+	runner_name_selector: string;
+	crash_policy: string;
+	key?: string | null;
+	input?: string | null;
+}
+
+export interface ActorsCreateResponse {
+	actor: Actor;
+}
+
+// MARK: Get actor
+export async function getActor(
+	config: Config,
+	actorId: RivetId,
+): Promise<ActorsGetResponse> {
+	return apiCall<never, ActorsGetResponse>(
+		config.endpoint,
+		config.namespace,
+		"GET",
+		`/actors/${encodeURIComponent(actorId)}`,
+	);
+}
+
+// MARK: Get actor by id
+export async function getActorById(
+	config: Config,
+	name: string,
+	key: string[],
+): Promise<ActorsGetByIdResponse> {
+	const serializedKey = serializeActorKey(key);
+	return apiCall<never, ActorsGetByIdResponse>(
+		config.endpoint,
+		config.namespace,
+		"GET",
+		`/actors/by-id?name=${encodeURIComponent(name)}&key=${encodeURIComponent(serializedKey)}`,
+	);
+}
+
+// MARK: Get or create actor by id
+export interface ActorsGetOrCreateByIdRequest {
+	name: string;
+	key: string;
+	runner_name_selector: string;
+	crash_policy: string;
+	input?: string | null;
+}
+
+export async function getOrCreateActorById(
+	config: Config,
+	request: ActorsGetOrCreateByIdRequest,
+): Promise<ActorsGetOrCreateByIdResponse> {
+	return apiCall<ActorsGetOrCreateByIdRequest, ActorsGetOrCreateByIdResponse>(
+		config.endpoint,
+		config.namespace,
+		"PUT",
+		`/actors/by-id`,
+		request,
+	);
+}
+
+// MARK: Create actor
+export async function createActor(
+	config: Config,
+	request: ActorsCreateRequest,
+): Promise<ActorsCreateResponse> {
+	return apiCall<ActorsCreateRequest, ActorsCreateResponse>(
+		config.endpoint,
+		config.namespace,
+		"POST",
+		`/actors`,
+		request,
+	);
+}
+
+// MARK: Destroy actor
+export type ActorsDeleteResponse = {};
+
+export async function destroyActor(
+	config: Config,
+	actorId: RivetId,
+): Promise<ActorsDeleteResponse> {
+	return apiCall<never, ActorsDeleteResponse>(
+		config.endpoint,
+		config.namespace,
+		"DELETE",
+		`/actors/${encodeURIComponent(actorId)}`,
+	);
+}

package/src/drivers/engine/api-utils.ts

@@ -0,0 +1,70 @@
+import { logger } from "./log";
+
+// Error class for Engine API errors
+export class EngineApiError extends Error {
+	constructor(
+		public readonly group: string,
+		public readonly code: string,
+		message?: string,
+	) {
+		super(message || `Engine API error: ${group}/${code}`);
+		this.name = "EngineApiError";
+	}
+}
+
+// Helper function for making API calls
+export async function apiCall<TInput = unknown, TOutput = unknown>(
+	endpoint: string,
+	namespace: string,
+	method: "GET" | "POST" | "PUT" | "DELETE",
+	path: string,
+	body?: TInput,
+): Promise<TOutput> {
+	const url = `${endpoint}${path}${path.includes("?") ? "&" : "?"}namespace=${encodeURIComponent(namespace)}`;
+
+	const options: RequestInit = {
+		method,
+		headers: {
+			"Content-Type": "application/json",
+		},
+	};
+
+	if (body !== undefined && method !== "GET") {
+		options.body = JSON.stringify(body);
+	}
+
+	logger().debug("making api call", { method, url });
+
+	const response = await fetch(url, options);
+
+	if (!response.ok) {
+		const errorText = await response.text();
+		logger().error("api call failed", {
+			status: response.status,
+			statusText: response.statusText,
+			error: errorText,
+			method,
+			path,
+		});
+
+		// Try to parse error response
+		try {
+			const errorData = JSON.parse(errorText);
+			if (errorData.kind === "error" && errorData.group && errorData.code) {
+				throw new EngineApiError(
+					errorData.group,
+					errorData.code,
+					errorData.message,
+				);
+			}
+		} catch (parseError) {
+			// If parsing fails or it's not our expected error format, continue
+		}
+
+		throw new Error(
+			`API call failed: ${response.status} ${response.statusText}`,
+		);
+	}
+
+	return response.json() as Promise<TOutput>;
+}

package/src/drivers/engine/config.ts

@@ -0,0 +1,39 @@
+import type { Hono } from "hono";
+import { z } from "zod";
+import { getEnvUniversal } from "@/utils";
+
+export const ConfigSchema = z
+	.object({
+		app: z.custom<Hono>().optional(),
+		endpoint: z
+			.string()
+			.default(
+				() => getEnvUniversal("RIVET_ENGINE") ?? "http://localhost:7080",
+			),
+		pegboardEndpoint: z.string().optional(),
+		namespace: z
+			.string()
+			.default(() => getEnvUniversal("RIVET_NAMESPACE") ?? "default"),
+		runnerName: z
+			.string()
+			.default(() => getEnvUniversal("RIVET_RUNNER") ?? "rivetkit"),
+		// TODO: Automatically attempt ot determine key by common env vars (e.g. k8s pod name)
+		runnerKey: z
+			.string()
+			.default(
+				() => getEnvUniversal("RIVET_RUNNER_KEY") ?? crypto.randomUUID(),
+			),
+		totalSlots: z.number().default(100_000),
+		addresses: z
+			.record(
+				z.object({
+					host: z.string(),
+					port: z.number(),
+				}),
+			)
+			.default({ main: { host: "127.0.0.1", port: 5051 } }),
+	})
+	.default({});
+
+export type InputConfig = z.input<typeof ConfigSchema>;
+export type Config = z.infer<typeof ConfigSchema>;

package/src/drivers/engine/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/drivers/engine/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/drivers/engine/kv.ts

@@ -0,0 +1,3 @@
+export const KEYS = {
+	PERSIST_DATA: Uint8Array.from([1, 1]),
+};

package/src/drivers/engine/log.ts

@@ -0,0 +1,7 @@
+import { getLogger } from "@/common/log";
+
+export const LOGGER_NAME = "driver-engine";
+
+export function logger() {
+	return getLogger(LOGGER_NAME);
+}