rivetkit 2.0.2 → 2.0.4-rc.1

package/src/actor/contexts/websocket.ts

@@ -0,0 +1,80 @@
+import type { Conn } from "../conn/mod";
+import type { AnyDatabaseProvider } from "../database";
+import type { ActorDefinition, AnyActorDefinition } from "../definition";
+import type { ActorInstance } from "../instance/mod";
+import type { EventSchemaConfig, QueueSchemaConfig } from "../schema";
+import { ConnContext } from "./base/conn";
+
+/**
+ * Context for raw WebSocket handlers (onWebSocket).
+ */
+export class WebSocketContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase extends AnyDatabaseProvider,
+	TEvents extends EventSchemaConfig = Record<never, never>,
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> extends ConnContext<
+	TState,
+	TConnParams,
+	TConnState,
+	TVars,
+	TInput,
+	TDatabase,
+	TEvents,
+	TQueues
+> {
+	/**
+	 * The incoming HTTP request that initiated the WebSocket upgrade.
+	 * May be undefined for WebSocket connections initiated without a direct HTTP request.
+	 */
+	public readonly request: Request | undefined;
+
+	/**
+	 * @internal
+	 */
+	constructor(
+		actor: ActorInstance<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		conn: Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>,
+		request?: Request,
+	) {
+		super(actor, conn);
+		this.request = request;
+	}
+}
+
+export type WebSocketContextOf<AD extends AnyActorDefinition> =
+	AD extends ActorDefinition<
+		infer S,
+		infer CP,
+		infer CS,
+		infer V,
+		infer I,
+		infer DB extends AnyDatabaseProvider,
+		infer E extends EventSchemaConfig,
+		infer Q extends QueueSchemaConfig,
+		any
+	>
+		? WebSocketContext<S, CP, CS, V, I, DB, E, Q>
+		: never;

package/src/actor/database.ts

@@ -0,0 +1,13 @@
+import type {
+	AnyDatabaseProvider,
+	DatabaseProvider,
+	RawDatabaseClient,
+	DrizzleDatabaseClient,
+} from "@/db/config";
+
+export type InferDatabaseClient<DBProvider extends AnyDatabaseProvider> =
+	DBProvider extends DatabaseProvider<any>
+		? Awaited<ReturnType<DBProvider["createClient"]>>
+		: never;
+
+export type { AnyDatabaseProvider, DatabaseProvider, RawDatabaseClient, DrizzleDatabaseClient };

package/src/actor/definition.ts

@@ -0,0 +1,64 @@
+import type { RegistryConfig } from "@/registry/config";
+import { DeepMutable } from "@/utils";
+import type { Actions, ActorConfig } from "./config";
+import type { ActionContextOf, ActorContext } from "./contexts";
+import type { AnyDatabaseProvider } from "./database";
+import { ActorInstance } from "./instance/mod";
+import type { EventSchemaConfig, QueueSchemaConfig } from "./schema";
+
+export type AnyActorDefinition = ActorDefinition<
+	any,
+	any,
+	any,
+	any,
+	any,
+	any,
+	any,
+	any,
+	any
+>;
+
+export class ActorDefinition<
+	S,
+	CP,
+	CS,
+	V,
+	I,
+	DB extends AnyDatabaseProvider,
+	E extends EventSchemaConfig = Record<never, never>,
+	Q extends QueueSchemaConfig = Record<never, never>,
+	R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<
+		S,
+		CP,
+		CS,
+		V,
+		I,
+		DB,
+		E,
+		Q
+	>,
+> {
+	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+
+	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q>) {
+		this.#config = config;
+	}
+
+	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q> {
+		return this.#config;
+	}
+
+	instantiate(): ActorInstance<S, CP, CS, V, I, DB, E, Q> {
+		return new ActorInstance(this.#config);
+	}
+}
+
+export function lookupInRegistry(
+	config: RegistryConfig,
+	name: string,
+): AnyActorDefinition {
+	// Build actor
+	const definition = config.use[name];
+	if (!definition) throw new Error(`no actor in registry for name ${name}`);
+	return definition;
+}

package/src/actor/driver.ts

@@ -0,0 +1,114 @@
+import type { Context as HonoContext } from "hono";
+import type { AnyClient } from "@/client/client";
+import type { ManagerDriver } from "@/manager/driver";
+import { type AnyConn } from "./conn/mod";
+import type { AnyActorInstance } from "./instance/mod";
+import type { RegistryConfig } from "@/registry/config";
+import type {
+	RawDatabaseClient,
+} from "@/db/config";
+import type { SqliteVfs } from "@rivetkit/sqlite-vfs";
+import { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";
+
+export type ActorDriverBuilder = (
+	config: RegistryConfig,
+	managerDriver: ManagerDriver,
+	inlineClient: AnyClient,
+) => ActorDriver;
+
+export interface ActorDriver {
+	//load(): Promise<LoadOutput>;
+
+	loadActor(actorId: string): Promise<AnyActorInstance>;
+
+	getContext(actorId: string): unknown;
+
+	// Batch KV operations
+	/** Batch write multiple key-value pairs. Keys and values are Uint8Arrays. */
+	kvBatchPut(
+		actorId: string,
+		entries: [Uint8Array, Uint8Array][],
+	): Promise<void>;
+
+	/** Batch read multiple keys. Returns null for keys that don't exist. */
+	kvBatchGet(
+		actorId: string,
+		keys: Uint8Array[],
+	): Promise<(Uint8Array | null)[]>;
+
+	/** Batch delete multiple keys. */
+	kvBatchDelete(actorId: string, keys: Uint8Array[]): Promise<void>;
+
+	/** List all keys with a given prefix. */
+	kvListPrefix(
+		actorId: string,
+		prefix: Uint8Array,
+	): Promise<[Uint8Array, Uint8Array][]>;
+
+	// Schedule
+	/** ActorInstance ensure that only one instance of setAlarm is called in parallel at a time. */
+	setAlarm(actor: AnyActorInstance, timestamp: number): Promise<void>;
+
+	// Database
+	/**
+	 * Override the default raw database client for the actor.
+	 * If not provided, rivetkit will construct a KV-backed SQLite client.
+	 * @experimental
+	 */
+	overrideRawDatabaseClient?(
+		actorId: string,
+	): Promise<RawDatabaseClient | undefined>;
+
+	/**
+	 * Override the default Drizzle database client for the actor.
+	 * If not provided, rivetkit will construct a KV-backed Drizzle client.
+	 * @experimental
+	 */
+	overrideDrizzleDatabaseClient?(
+		actorId: string,
+	): Promise<BaseSQLiteDatabase<any,any,any,any> | undefined>;
+
+	/**
+	 * Creates a SQLite VFS instance for creating KV-backed databases.
+	 * If not provided, the database provider will need an override.
+	 *
+	 * @rivetkit/sqlite's async build is not re-entrant per module instance. Drivers
+	 * should return a new instance per call for actor-level isolation.
+	 *
+	 * This is a method (not a property) so drivers can use dynamic imports,
+	 * keeping the core driver tree-shakeable from @rivetkit/sqlite.
+	 */
+	createSqliteVfs?(): SqliteVfs | Promise<SqliteVfs>;
+
+	/**
+	 * Requests the actor to go to sleep.
+	 *
+	 * This will call `ActorInstance.onStop` independently.
+	 */
+	startSleep?(actorId: string): void;
+
+	/**
+	 * Destroys the actor and its associated data.
+	 *
+	 * This will call `ActorInstance.onStop` independently.
+	 */
+	startDestroy(actorId: string): void;
+
+	/**
+	 * Shuts down the actor runner.
+	 */
+	shutdownRunner?(immediate: boolean): Promise<void>;
+
+	// Serverless
+	/** This handles the serverless start request. This should manage the lifecycle of the runner tied to the request lifecycle. */
+	serverlessHandleStart?(c: HonoContext): Promise<Response>;
+
+	/** Extra properties to add to logs for each actor. */
+	getExtraActorLogParams?(): Record<string, string>;
+
+	onBeforeActorStart?(actor: AnyActorInstance): Promise<void>;
+	onCreateConn?(conn: AnyConn): void;
+	onDestroyConn?(conn: AnyConn): void;
+	onBeforePersistConn?(conn: AnyConn): void;
+	onAfterPersistConn?(conn: AnyConn): void;
+}