rivetkit 0.0.0-skip-ready-wait-flatten-client-options.1cae221 → 0.0.0-sqlite-uds.4e59a38

package/src/actor/config.ts

@@ -1,24 +1,18 @@
 import { z } from "zod/v4";
-import type { UniversalWebSocket } from "@/common/websocket-interface";
+import type { Client } from "@/client/client";
 import type {
 	AnyDatabaseProvider,
 	InferDatabaseClient,
-	RawDatabaseClient,
-	DrizzleDatabaseClient,
-	NativeDatabaseProvider,
 } from "@/common/database/config";
-import type { Client } from "@/client/client";
+import type { UniversalWebSocket } from "@/common/websocket-interface";
 import type { Registry } from "@/registry";
 import type { BaseActorDefinition } from "./definition";
 import type {
 	EventSchemaConfig,
-	PrimitiveSchema,
-	QueueSchemaConfig,
-} from "./schema";
-import type {
-	InferEventArgs,
 	InferQueueCompleteMap,
 	InferSchemaMap,
+	PrimitiveSchema,
+	QueueSchemaConfig,
 } from "./schema";
 
 export const DEFAULT_SLEEP_GRACE_PERIOD = 15_000;
@@ -26,6 +20,7 @@ export const DEFAULT_SLEEP_GRACE_PERIOD = 15_000;
 export const ACTOR_CONTEXT_INTERNAL_SYMBOL = Symbol(
 	"rivetkit.actor_context_internal",
 );
+export const RAW_STATE_SYMBOL = Symbol("rivetkit.raw_state");
 export const CONN_DRIVER_SYMBOL = Symbol("rivetkit.conn_driver");
 export const CONN_STATE_MANAGER_SYMBOL = Symbol("rivetkit.conn_state_manager");
 
@@ -67,6 +62,10 @@ type ActorKvListOptions<
 
 type ActorClientFor<T> = T extends Registry<any> ? Client<T> : T;
 
+/**
+ * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db` / `c.sql`)
+ * or actor state instead.
+ */
 export interface ActorKv {
 	get<T extends ActorKvValueType = "text">(
 		key: Uint8Array | string,
@@ -97,7 +96,10 @@ export interface ActorKv {
 		end: Uint8Array | string,
 		options?: ActorKvListOptions<T, K>,
 	): Promise<Array<[ActorKvKeyTypeMap[K], ActorKvValueTypeMap[T]]>>;
-	list<T extends ActorKvValueType = "text", K extends ActorKvKeyType = "text">(
+	list<
+		T extends ActorKvValueType = "text",
+		K extends ActorKvKeyType = "text",
+	>(
 		prefix: Uint8Array | string,
 		options?: ActorKvListOptions<T, K>,
 	): Promise<Array<[ActorKvKeyTypeMap[K], ActorKvValueTypeMap[T]]>>;
@@ -118,7 +120,8 @@ export type QueueMessageOf<Name extends string, Body> = {
 	[key: string]: unknown;
 };
 
-export type QueueName<TQueues extends QueueSchemaConfig> = keyof TQueues & string;
+export type QueueName<TQueues extends QueueSchemaConfig> = keyof TQueues &
+	string;
 export type QueueFilterName<TQueues extends QueueSchemaConfig> =
 	keyof TQueues extends never ? string : QueueName<TQueues>;
 
@@ -228,7 +231,9 @@ export interface QueueIterOptions<
 	completable?: TCompletable;
 }
 
-export interface ActorQueue<TQueues extends QueueSchemaConfig = Record<never, never>> {
+export interface ActorQueue<
+	TQueues extends QueueSchemaConfig = Record<never, never>,
+> {
 	send<TName extends QueueFilterName<TQueues>>(
 		name: TName,
 		body: QueueMessageForName<TQueues, TName>["body"],
@@ -236,15 +241,11 @@ export interface ActorQueue<TQueues extends QueueSchemaConfig = Record<never, ne
 	next<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
-	>(
-		opts?: QueueNextOptions<TName, TCompletable>,
-	): Promise<any>;
+	>(opts?: QueueNextOptions<TName, TCompletable>): Promise<any>;
 	nextBatch<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
-	>(
-		opts?: QueueNextBatchOptions<TName, TCompletable>,
-	): Promise<any[]>;
+	>(opts?: QueueNextBatchOptions<TName, TCompletable>): Promise<any[]>;
 	waitForNames<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
@@ -260,33 +261,27 @@ export interface ActorQueue<TQueues extends QueueSchemaConfig = Record<never, ne
 	tryNext<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
-	>(
-		opts?: QueueTryNextOptions<TName, TCompletable>,
-	): Promise<any>;
+	>(opts?: QueueTryNextOptions<TName, TCompletable>): Promise<any>;
 	tryNextBatch<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
-	>(
-		opts?: QueueTryNextBatchOptions<TName, TCompletable>,
-	): Promise<any[]>;
+	>(opts?: QueueTryNextBatchOptions<TName, TCompletable>): Promise<any[]>;
 	iter<
 		const TName extends QueueFilterName<TQueues>,
 		const TCompletable extends boolean = false,
-	>(
-		opts?: QueueIterOptions<TName, TCompletable>,
-	): AsyncIterable<any>;
+	>(opts?: QueueIterOptions<TName, TCompletable>): AsyncIterable<any>;
 	[key: string]: any;
 }
 
 export interface Conn<
-	TState = unknown,
+	_TState = unknown,
 	TConnParams = unknown,
 	TConnState = unknown,
-	TVars = unknown,
-	TInput = unknown,
-	TDatabase extends AnyDatabaseProvider = AnyDatabaseProvider,
-	TEvents extends EventSchemaConfig = Record<never, never>,
-	TQueues extends QueueSchemaConfig = Record<never, never>,
+	_TVars = unknown,
+	_TInput = unknown,
+	_TDatabase extends AnyDatabaseProvider = AnyDatabaseProvider,
+	_TEvents extends EventSchemaConfig = Record<never, never>,
+	_TQueues extends QueueSchemaConfig = Record<never, never>,
 > {
 	id: string;
 	params: TConnParams;
@@ -310,8 +305,14 @@ export interface ActorContext<
 	TQueues extends QueueSchemaConfig = Record<never, never>,
 > {
 	[ACTOR_CONTEXT_INTERNAL_SYMBOL]?: unknown;
+	/** Returns the raw unwrapped state without the write-through proxy. */
+	[RAW_STATE_SYMBOL](): TState;
 	state: TState;
 	vars: TVars;
+	/**
+	 * @deprecated Actor KV is deprecated. Use embedded SQLite (`db` / `sql`)
+	 * or actor state instead.
+	 */
 	readonly kv: ActorKv;
 	readonly db: InferDatabaseClient<TDatabase>;
 	readonly schedule: ActorSchedule;
@@ -320,7 +321,21 @@ export interface ActorContext<
 	readonly name: string;
 	readonly key: string[];
 	readonly region: string;
-	readonly conns: Map<string, Conn<TState, TConnParams, TConnState, TVars, TInput, TDatabase, TEvents, TQueues>>;
+	/** Provisions credentials for the experimental local actor Unix socket API. */
+	actorUds(): Promise<{ path: string; token: string }>;
+	readonly conns: Map<
+		string,
+		Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>
+	>;
 	readonly log: ActorLogger;
 	readonly abortSignal: AbortSignal;
 	readonly aborted: boolean;
@@ -651,7 +666,9 @@ export type WebSocketContext<
 	TQueues
 >;
 
-export type ActorContextOf<AD extends BaseActorDefinition<any, any, any, any, any, any, any, any, any>> =
+export type ActorContextOf<
+	AD extends BaseActorDefinition<any, any, any, any, any, any, any, any, any>,
+> =
 	AD extends BaseActorDefinition<
 		infer TState,
 		infer TConnParams,
@@ -728,6 +745,88 @@ const RunInspectorConfigSchema = z
 	})
 	.optional();
 
+/**
+ * Built-in inspector tabs the dashboard ships. Used to validate
+ * `hidden: true` entries and reject custom-tab ids that collide with
+ * a built-in.
+ */
+export const BUILTIN_INSPECTOR_TAB_IDS = [
+	"workflow",
+	"database",
+	"state",
+	"queue",
+	"connections",
+	"console",
+] as const;
+
+export const BuiltinInspectorTabIdSchema = z.enum(BUILTIN_INSPECTOR_TAB_IDS);
+
+// Custom tab id grammar — mirrored in Rust at
+// `rivetkit-rust/packages/rivetkit-core/src/inspector/tabs.rs`. Slashes are
+// forbidden because the runtime splits `/inspector/custom-tabs/<id>/<rest>`
+// on the first `/`.
+const CUSTOM_INSPECTOR_TAB_ID_RE = /^[A-Za-z0-9_-]+$/;
+
+export const CustomInspectorTabEntrySchema = z
+	.object({
+		id: z
+			.string()
+			.regex(
+				CUSTOM_INSPECTOR_TAB_ID_RE,
+				"inspector.tabs[].id must contain only letters, digits, underscore, or dash",
+			),
+		label: z.string().min(1),
+		source: z.string().min(1),
+		/**
+		 * Optional icon id. The dashboard maps strings to glyphs (see its
+		 * icon registry); unknown ids fall back to a generic icon.
+		 */
+		icon: z.string().min(1).optional(),
+		hidden: z.literal(false).optional(),
+	})
+	.strict();
+
+export const HideInspectorTabEntrySchema = z
+	.object({
+		id: BuiltinInspectorTabIdSchema,
+		hidden: z.literal(true),
+	})
+	.strict();
+
+export const InspectorTabEntrySchema = z.union([
+	CustomInspectorTabEntrySchema,
+	HideInspectorTabEntrySchema,
+]);
+
+export const ActorInspectorConfigSchema = z
+	.object({
+		tabs: z.array(InspectorTabEntrySchema).default(() => []),
+	})
+	.strict()
+	.refine(
+		(data) => {
+			const ids = data.tabs.map((t) => t.id);
+			return new Set(ids).size === ids.length;
+		},
+		{ message: "Duplicate id in inspector.tabs", path: ["tabs"] },
+	)
+	.refine(
+		(data) => {
+			// A custom entry's id must not collide with a built-in id.
+			const builtinSet = new Set(BUILTIN_INSPECTOR_TAB_IDS);
+			return data.tabs.every(
+				(t) => t.hidden === true || !builtinSet.has(t.id as any),
+			);
+		},
+		{
+			message:
+				"Custom inspector tab id collides with a built-in (use hidden: true to hide a built-in)",
+			path: ["tabs"],
+		},
+	);
+
+export type ActorInspectorConfig = z.input<typeof ActorInspectorConfigSchema>;
+
 // Schema for run handler with metadata
 export const RunConfigSchema = z.object({
 	/** Display name for the actor in the Inspector UI. */
@@ -784,6 +883,8 @@ interface RunFunctionConfig {
 	icon?: string;
 	inspector?: RunInspectorConfig;
 	inspectorFactory?: (actor: unknown) => RunInspectorConfig | undefined;
+	/** Release any per-actor inspector state held for this actor id. */
+	disposeInspector?: (actorId: string) => void;
 }
 
 type RunFunctionWithConfig = ((...args: any[]) => any) & {
@@ -834,6 +935,18 @@ export function getRunInspectorConfig(
 	return run.inspector;
 }
 
+/** Release per-actor inspector state for a destroyed actor, if the run handler registered a disposer. */
+export function disposeRunInspector(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+	actorId: string,
+): void {
+	if (!run || typeof run !== "function") {
+		return;
+	}
+	const config = (run as RunFunctionWithConfig)[RUN_FUNCTION_CONFIG_SYMBOL];
+	config?.disposeInspector?.(actorId);
+}
+
 // This schema is used to validate the input at runtime. The generic types are defined below in `ActorConfig`.
 //
 // We don't use Zod generics with `z.custom` because:
@@ -944,6 +1057,7 @@ export const ActorConfigSchema = z
 		db: z.any().optional(),
 		createVars: zFunction().optional(),
 		options: ActorOptionsSchema,
+		inspector: ActorInspectorConfigSchema.optional(),
 	})
 	.strict()
 	.refine(
@@ -979,9 +1093,9 @@ export const ActorConfigSchema = z
 // Data returned from this handler will be available on `c.state`.
 type CreateState<
 	TState,
-	TConnParams,
-	TConnState,
-	TVars,
+	_TConnParams,
+	_TConnState,
+	_TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
 	TEvents extends EventSchemaConfig,
@@ -1001,6 +1115,7 @@ type CreateState<
 // This must have only one or the other or else TState will not be able to be inferred
 //
 // Data returned from this handler will be available on `c.conn.state`.
+// The pending connection is not visible in `c.conns` until this succeeds.
 type CreateConnState<
 	TState,
 	TConnParams,
@@ -1035,8 +1150,8 @@ type CreateConnState<
  */
 type CreateVars<
 	TState,
-	TConnParams,
-	TConnState,
+	_TConnParams,
+	_TConnState,
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
@@ -1227,7 +1342,7 @@ interface BaseActorConfig<
 	 * shutdown window (`sleepGracePeriod`) cover deferred work.
 	 *
 	 * The handler receives an abort signal via `c.abortSignal` and a
-	 * `c.aborted` alias for loop checks. Use these to gracefully exit.
+	 * `c.aborted` alias. Use these to gracefully exit when shutdown starts.
 	 *
 	 * If this handler exits, the actor will follow the normal idle sleep timeout
 	 * once it becomes idle.
@@ -1292,10 +1407,11 @@ interface BaseActorConfig<
 	 * Called before a client connects to the actor.
 	 *
 	 * Use this hook to determine if a connection should be accepted
-	 * and to initialize connection-specific state.
+	 * and to validate client-provided parameters. The pending connection
+	 * is not visible in `c.conns` while this hook runs.
 	 *
 	 * @param opts Connection parameters including client-provided data
-	 * @returns The initial connection state or a Promise that resolves to it
+	 * @returns Void or a Promise.
 	 * @throws Throw an error to reject the connection
 	 */
 	onBeforeConnect?: (
@@ -1314,7 +1430,8 @@ interface BaseActorConfig<
 	 * Called when a client successfully connects to the actor.
 	 *
 	 * Use this hook to perform actions when a connection is established,
-	 * such as sending initial data or updating the actor's state.
+	 * such as sending initial data or updating the actor's state. The
+	 * connection is visible in `c.conns` before this hook runs.
 	 *
 	 * @param conn The connection object
 	 * @returns Void or a Promise that resolves when connection handling is complete
@@ -1495,6 +1612,25 @@ export type ActorConfig<
 	TDatabase extends AnyDatabaseProvider,
 	TEvents extends EventSchemaConfig = Record<never, never>,
 	TQueues extends QueueSchemaConfig = Record<never, never>,
+	TActions extends Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	> = Actions<
+		TState,
+		TConnParams,
+		TConnState,
+		TVars,
+		TInput,
+		TDatabase,
+		TEvents,
+		TQueues
+	>,
 > = Omit<
 	z.infer<typeof ActorConfigSchema>,
 	| "actions"
@@ -1530,16 +1666,7 @@ export type ActorConfig<
 		TDatabase,
 		TEvents,
 		TQueues,
-		Actions<
-			TState,
-			TConnParams,
-			TConnState,
-			TVars,
-			TInput,
-			TDatabase,
-			TEvents,
-			TQueues
-		>
+		TActions
 	> &
 	CreateState<
 		TState,
@@ -1770,7 +1897,7 @@ export const DocActorOptionsSchema = z
 			.number()
 			.optional()
 			.describe(
-				`Max time in ms for the graceful shutdown window. Covers lifecycle hooks (onSleep, onDestroy), the run handler abort wait, async raw WebSocket handlers, disconnect callbacks, and final state serialization. Default: ${DEFAULT_SLEEP_GRACE_PERIOD}.`,
+				`Max time in ms for the graceful shutdown window. Covers lifecycle hooks (onSleep, onDestroy), the run handler wait, async raw WebSocket handlers, disconnect callbacks, and final state serialization. Default: ${DEFAULT_SLEEP_GRACE_PERIOD}.`,
 			),
 		onDestroyTimeout: z
 			.number()
@@ -1875,7 +2002,7 @@ export const DocActorConfigSchema = z
 			.unknown()
 			.optional()
 			.describe(
-				"Function to create connection state. Receives context and connection params. Cannot be used with connState.",
+				"Function to create connection state. Receives context and connection params. The pending connection is not visible in c.conns until this succeeds. Cannot be used with connState.",
 			),
 		vars: z
 			.unknown()
@@ -1937,12 +2064,14 @@ export const DocActorConfigSchema = z
 			.unknown()
 			.optional()
 			.describe(
-				"Called before a client connects. Throw an error to reject the connection.",
+				"Called before a client connects. Throw an error to reject the connection. The pending connection is not visible in c.conns while this runs.",
 			),
 		onConnect: z
 			.unknown()
 			.optional()
-			.describe("Called when a client successfully connects."),
+			.describe(
+				"Called when a client successfully connects. The connection is visible in c.conns before this runs.",
+			),
 		onDisconnect: z
 			.unknown()
 			.optional()

package/src/actor/contexts/index.ts

@@ -16,10 +16,15 @@ import type {
 	WakeContext,
 	WebSocketContext,
 } from "@/actor/config";
+
 export type { ActorContextOf } from "@/actor/config";
-import type { AnyActorDefinition, BaseActorDefinition } from "@/actor/definition";
-import type { AnyDatabaseProvider } from "@/common/database/config";
+
+import type {
+	AnyActorDefinition,
+	BaseActorDefinition,
+} from "@/actor/definition";
 import type { EventSchemaConfig, QueueSchemaConfig } from "@/actor/schema";
+import type { AnyDatabaseProvider } from "@/common/database/config";
 
 export type ActionContextOf<AD extends AnyActorDefinition> =
 	AD extends BaseActorDefinition<

package/src/actor/definition.ts

@@ -1,7 +1,12 @@
+import type { AnyDatabaseProvider } from "@/common/database/config";
 import type { RegistryConfig } from "@/registry/config";
-import { ActorConfigSchema, type Actions, type ActorConfig, type ActorConfigInput } from "./config";
+import {
+	type Actions,
+	type ActorConfig,
+	type ActorConfigInput,
+	ActorConfigSchema,
+} from "./config";
 import { loggerWithoutContext } from "./log";
-import type { AnyDatabaseProvider } from "@/common/database/config";
 import type { EventSchemaConfig, QueueSchemaConfig } from "./schema";
 
 const warnedDeprecatedTimeoutKeys = new Set<string>();
@@ -28,7 +33,7 @@ export interface BaseActorDefinition<
 	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<
+	_R extends Actions<S, CP, CS, V, I, DB, E, Q> = Actions<
 		S,
 		CP,
 		CS,
@@ -39,20 +44,12 @@ export interface BaseActorDefinition<
 		Q
 	>,
 > {
-	readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+	readonly config: ActorConfig<S, CP, CS, V, I, DB, E, Q, _R>;
 }
 
-export type AnyActorDefinition = BaseActorDefinition<
-	any,
-	any,
-	any,
-	any,
-	any,
-	any,
-	any,
-	any,
-	any
->;
+export interface AnyActorDefinition {
+	readonly config: any;
+}
 
 export type AnyStaticActorDefinition = ActorDefinition<
 	any,
@@ -87,13 +84,13 @@ export class ActorDefinition<
 	>,
 > implements BaseActorDefinition<S, CP, CS, V, I, DB, E, Q, R>
 {
-	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q>;
+	#config: ActorConfig<S, CP, CS, V, I, DB, E, Q, R>;
 
-	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q>) {
+	constructor(config: ActorConfig<S, CP, CS, V, I, DB, E, Q, R>) {
 		this.#config = config;
 	}
 
-	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q> {
+	get config(): ActorConfig<S, CP, CS, V, I, DB, E, Q, R> {
 		return this.#config;
 	}
 }
@@ -195,7 +192,8 @@ export function actor<
 		TInput,
 		TDatabase,
 		TEvents,
-		TQueues
+		TQueues,
+		TActions
 	>;
 	return new ActorDefinition(config);
 }

package/src/actor/driver.ts

@@ -1,12 +1,12 @@
 import type { Context as HonoContext } from "hono";
 import type { AnyClient } from "@/client/client";
-import type { EngineControlClient } from "@/engine-client/driver";
-import type { AnyActorInstance, AnyStaticActorInstance } from "./definition";
-import type { RegistryConfig } from "@/registry/config";
 import type {
 	DrizzleDatabaseClient,
 	NativeDatabaseProvider,
 } from "@/common/database/config";
+import type { EngineControlClient } from "@/engine-client/driver";
+import type { RegistryConfig } from "@/registry/config";
+import type { AnyActorInstance, AnyStaticActorInstance } from "./definition";
 
 export type ActorDriverBuilder = (
 	config: RegistryConfig,