rivetkit 2.0.2 → 2.0.3

package/src/actor/log.ts

@@ -0,0 +1,15 @@
+import { getLogger } from "@/common//log";
+
+/** Logger for this library. */
+export const RUNTIME_LOGGER_NAME = "actor-runtime";
+
+/** Logger used for logs from the actor instance itself. */
+export const ACTOR_LOGGER_NAME = "actor";
+
+export function logger() {
+	return getLogger(RUNTIME_LOGGER_NAME);
+}
+
+export function instanceLogger() {
+	return getLogger(ACTOR_LOGGER_NAME);
+}

package/src/actor/mod.ts

@@ -0,0 +1,113 @@
+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,
+	TAuthData,
+	TDatabase extends AnyDatabaseProvider,
+	TActions extends Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TAuthData,
+		TDatabase
+	>,
+>(
+	input: ActorConfigInput<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TAuthData,
+		TDatabase,
+		TActions
+	>,
+): ActorDefinition<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TAuthData,
+	TDatabase,
+	TActions
+> {
+	const config = ActorConfigSchema.parse(input) as ActorConfig<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TAuthData,
+		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;
+}

package/src/actor/protocol/old.ts

@@ -0,0 +1,281 @@
+import * as cbor from "cbor-x";
+import { z } from "zod";
+import type { AnyDatabaseProvider } from "@/actor/database";
+import * as errors from "@/actor/errors";
+import {
+	CachedSerializer,
+	type Encoding,
+	type InputData,
+} from "@/actor/protocol/serde";
+import { deconstructError } from "@/common/utils";
+import type * as protocol from "@/schemas/client-protocol/mod";
+import {
+	TO_CLIENT_VERSIONED,
+	TO_SERVER_VERSIONED,
+} from "@/schemas/client-protocol/versioned";
+import { deserializeWithEncoding } from "@/serde";
+import { assertUnreachable, bufferToArrayBuffer } from "../../utils";
+import { ActionContext } from "../action";
+import type { Conn } from "../connection";
+import type { ActorInstance } from "../instance";
+import { logger } from "../log";
+
+export const TransportSchema = z.enum(["websocket", "sse"]);
+
+/**
+ * Transport mechanism used to communicate between client & actor.
+ */
+export type Transport = z.infer<typeof TransportSchema>;
+
+interface MessageEventOpts {
+	encoding: Encoding;
+	maxIncomingMessageSize: number;
+}
+
+function getValueLength(value: InputData): number {
+	if (typeof value === "string") {
+		return value.length;
+	} else if (value instanceof Blob) {
+		return value.size;
+	} else if (
+		value instanceof ArrayBuffer ||
+		value instanceof SharedArrayBuffer ||
+		value instanceof Uint8Array
+	) {
+		return value.byteLength;
+	} else {
+		assertUnreachable(value);
+	}
+}
+
+export async function inputDataToBuffer(
+	data: InputData,
+): Promise<Uint8Array | string> {
+	if (typeof data === "string") {
+		return data;
+	} else if (data instanceof Blob) {
+		const arrayBuffer = await data.arrayBuffer();
+		return new Uint8Array(arrayBuffer);
+	} else if (data instanceof Uint8Array) {
+		return data;
+	} else if (data instanceof ArrayBuffer || data instanceof SharedArrayBuffer) {
+		return new Uint8Array(data);
+	} else {
+		throw new errors.MalformedMessage();
+	}
+}
+
+export async function parseMessage(
+	value: InputData,
+	opts: MessageEventOpts,
+): Promise<protocol.ToServer> {
+	// Validate value length
+	const length = getValueLength(value);
+	if (length > opts.maxIncomingMessageSize) {
+		throw new errors.MessageTooLong();
+	}
+
+	// Parse & validate message
+	const buffer = await inputDataToBuffer(value);
+	return deserializeWithEncoding(opts.encoding, buffer, TO_SERVER_VERSIONED);
+}
+
+export interface ProcessMessageHandler<
+	S,
+	CP,
+	CS,
+	V,
+	I,
+	AD,
+	DB extends AnyDatabaseProvider,
+> {
+	onExecuteAction?: (
+		ctx: ActionContext<S, CP, CS, V, I, AD, DB>,
+		name: string,
+		args: unknown[],
+	) => Promise<unknown>;
+	onSubscribe?: (
+		eventName: string,
+		conn: Conn<S, CP, CS, V, I, AD, DB>,
+	) => Promise<void>;
+	onUnsubscribe?: (
+		eventName: string,
+		conn: Conn<S, CP, CS, V, I, AD, DB>,
+	) => Promise<void>;
+}
+
+export async function processMessage<
+	S,
+	CP,
+	CS,
+	V,
+	I,
+	AD,
+	DB extends AnyDatabaseProvider,
+>(
+	message: protocol.ToServer,
+	actor: ActorInstance<S, CP, CS, V, I, AD, DB>,
+	conn: Conn<S, CP, CS, V, I, AD, DB>,
+	handler: ProcessMessageHandler<S, CP, CS, V, I, AD, DB>,
+) {
+	let actionId: bigint | undefined;
+	let actionName: string | undefined;
+
+	try {
+		if (message.body.tag === "ActionRequest") {
+			// Action request
+
+			if (handler.onExecuteAction === undefined) {
+				throw new errors.Unsupported("Action");
+			}
+
+			const { id, name, args: argsRaw } = message.body.val;
+			actionId = id;
+			actionName = name;
+			const args = cbor.decode(new Uint8Array(argsRaw));
+
+			logger().debug("processing action request", {
+				actionId: id,
+				actionName: name,
+			});
+
+			const ctx = new ActionContext<S, CP, CS, V, I, AD, DB>(
+				actor.actorContext,
+				conn,
+			);
+
+			// Process the action request and wait for the result
+			// This will wait for async actions to complete
+			const output = await handler.onExecuteAction(ctx, name, args);
+
+			logger().debug("sending action response", {
+				actionId: id,
+				actionName: name,
+				outputType: typeof output,
+				isPromise: output instanceof Promise,
+			});
+
+			// Send the response back to the client
+			conn._sendMessage(
+				new CachedSerializer<protocol.ToClient>(
+					{
+						body: {
+							tag: "ActionResponse",
+							val: {
+								id: id,
+								output: bufferToArrayBuffer(cbor.encode(output)),
+							},
+						},
+					},
+					TO_CLIENT_VERSIONED,
+				),
+			);
+
+			logger().debug("action response sent", { id, name: name });
+		} else if (message.body.tag === "SubscriptionRequest") {
+			// Subscription request
+
+			if (
+				handler.onSubscribe === undefined ||
+				handler.onUnsubscribe === undefined
+			) {
+				throw new errors.Unsupported("Subscriptions");
+			}
+
+			const { eventName, subscribe } = message.body.val;
+			logger().debug("processing subscription request", {
+				eventName,
+				subscribe,
+			});
+
+			if (subscribe) {
+				await handler.onSubscribe(eventName, conn);
+			} else {
+				await handler.onUnsubscribe(eventName, conn);
+			}
+
+			logger().debug("subscription request completed", {
+				eventName,
+				subscribe,
+			});
+		} else {
+			assertUnreachable(message.body);
+		}
+	} catch (error) {
+		const { code, message, metadata } = deconstructError(error, logger(), {
+			connectionId: conn.id,
+			actionId,
+			actionName,
+		});
+
+		logger().debug("sending error response", {
+			actionId,
+			actionName,
+			code,
+			message,
+		});
+
+		// Build response
+		conn._sendMessage(
+			new CachedSerializer<protocol.ToClient>(
+				{
+					body: {
+						tag: "Error",
+						val: {
+							code,
+							message,
+							metadata: bufferToArrayBuffer(cbor.encode(metadata)),
+							actionId: actionId ?? null,
+						},
+					},
+				},
+				TO_CLIENT_VERSIONED,
+			),
+		);
+
+		logger().debug("error response sent", { actionId, actionName });
+	}
+}
+
+///**
+// * Use `CachedSerializer` if serializing the same data repeatedly.
+// */
+//export function serialize<T>(value: T, encoding: Encoding): OutputData {
+//	if (encoding === "json") {
+//		return JSON.stringify(value);
+//	} else if (encoding === "cbor") {
+//		// TODO: Remove this hack, but cbor-x can't handle anything extra in data structures
+//		const cleanValue = JSON.parse(JSON.stringify(value));
+//		return cbor.encode(cleanValue);
+//	} else {
+//		assertUnreachable(encoding);
+//	}
+//}
+//
+//export async function deserialize(data: InputData, encoding: Encoding) {
+//	if (encoding === "json") {
+//		if (typeof data !== "string") {
+//			logger().warn("received non-string for json parse");
+//			throw new errors.MalformedMessage();
+//		} else {
+//			return JSON.parse(data);
+//		}
+//	} else if (encoding === "cbor") {
+//		if (data instanceof Blob) {
+//			const arrayBuffer = await data.arrayBuffer();
+//			return cbor.decode(new Uint8Array(arrayBuffer));
+//		} else if (data instanceof Uint8Array) {
+//			return cbor.decode(data);
+//		} else if (
+//			data instanceof ArrayBuffer ||
+//			data instanceof SharedArrayBuffer
+//		) {
+//			return cbor.decode(new Uint8Array(data));
+//		} else {
+//			logger().warn("received non-binary type for cbor parse");
+//			throw new errors.MalformedMessage();
+//		}
+//	} else {
+//		assertUnreachable(encoding);
+//	}
+//}

package/src/actor/protocol/serde.ts

@@ -0,0 +1,131 @@
+import * as cbor from "cbor-x";
+import { z } from "zod";
+import * as errors from "@/actor/errors";
+import type { VersionedDataHandler } from "@/common/versioned-data";
+import { serializeWithEncoding } from "@/serde";
+import { logger } from "../log";
+import { assertUnreachable } from "../utils";
+
+/** Data that can be deserialized. */
+export type InputData = string | Buffer | Blob | ArrayBufferLike | Uint8Array;
+
+/** Data that's been serialized. */
+export type OutputData = string | Uint8Array;
+
+export const EncodingSchema = z.enum(["json", "cbor", "bare"]);
+
+/**
+ * Encoding used to communicate between the client & actor.
+ */
+export type Encoding = z.infer<typeof EncodingSchema>;
+
+/**
+ * Helper class that helps serialize data without re-serializing for the same encoding.
+ */
+export class CachedSerializer<T> {
+	#data: T;
+	#cache = new Map<Encoding, OutputData>();
+	#versionedDataHandler: VersionedDataHandler<T>;
+
+	constructor(data: T, versionedDataHandler: VersionedDataHandler<T>) {
+		this.#data = data;
+		this.#versionedDataHandler = versionedDataHandler;
+	}
+
+	public get rawData(): T {
+		return this.#data;
+	}
+
+	public serialize(encoding: Encoding): OutputData {
+		const cached = this.#cache.get(encoding);
+		if (cached) {
+			return cached;
+		} else {
+			const serialized = serializeWithEncoding(
+				encoding,
+				this.#data,
+				this.#versionedDataHandler,
+			);
+			this.#cache.set(encoding, serialized);
+			return serialized;
+		}
+	}
+}
+
+///**
+// * Use `CachedSerializer` if serializing the same data repeatedly.
+// */
+//export function serialize<T>(value: T, encoding: Encoding): OutputData {
+//	if (encoding === "json") {
+//		return JSON.stringify(value);
+//	} else if (encoding === "cbor") {
+//		// TODO: Remove this hack, but cbor-x can't handle anything extra in data structures
+//		const cleanValue = JSON.parse(JSON.stringify(value));
+//		return cbor.encode(cleanValue);
+//	} else {
+//		assertUnreachable(encoding);
+//	}
+//}
+//
+//export async function deserialize(data: InputData, encoding: Encoding) {
+//	if (encoding === "json") {
+//		if (typeof data !== "string") {
+//			logger().warn("received non-string for json parse");
+//			throw new errors.MalformedMessage();
+//		} else {
+//			return JSON.parse(data);
+//		}
+//	} else if (encoding === "cbor") {
+//		if (data instanceof Blob) {
+//			const arrayBuffer = await data.arrayBuffer();
+//			return cbor.decode(new Uint8Array(arrayBuffer));
+//		} else if (data instanceof Uint8Array) {
+//			return cbor.decode(data);
+//		} else if (
+//			data instanceof ArrayBuffer ||
+//			data instanceof SharedArrayBuffer
+//		) {
+//			return cbor.decode(new Uint8Array(data));
+//		} else {
+//			logger().warn("received non-binary type for cbor parse");
+//			throw new errors.MalformedMessage();
+//		}
+//	} else {
+//		assertUnreachable(encoding);
+//	}
+//}
+
+// TODO: Encode base 128
+function base64EncodeUint8Array(uint8Array: Uint8Array): string {
+	let binary = "";
+	const len = uint8Array.byteLength;
+	for (let i = 0; i < len; i++) {
+		binary += String.fromCharCode(uint8Array[i]);
+	}
+	return btoa(binary);
+}
+
+function base64EncodeArrayBuffer(arrayBuffer: ArrayBuffer): string {
+	const uint8Array = new Uint8Array(arrayBuffer);
+	return base64EncodeUint8Array(uint8Array);
+}
+
+/** Converts data that was encoded to a string. Some formats (like SSE) don't support raw binary data. */
+export function encodeDataToString(message: OutputData): string {
+	if (typeof message === "string") {
+		return message;
+	} else if (message instanceof ArrayBuffer) {
+		return base64EncodeArrayBuffer(message);
+	} else if (message instanceof Uint8Array) {
+		return base64EncodeUint8Array(message);
+	} else {
+		assertUnreachable(message);
+	}
+}
+
+/** Stringifies with compat for values that BARE & CBOR supports. */
+export function jsonStringifyCompat(input: any): string {
+	return JSON.stringify(input, (_key, value) =>
+		typeof value === "bigint" ? value.toString() : value,
+	);
+}