rivetkit 2.3.0-rc.8 → 2.3.0

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;
@@ -68,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,
@@ -98,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]]>>;
@@ -119,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>;
 
@@ -229,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"],
@@ -237,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,
@@ -261,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;
@@ -315,6 +309,10 @@ export interface ActorContext<
 	[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;
@@ -323,7 +321,19 @@ 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>>;
+	readonly conns: Map<
+		string,
+		Conn<
+			TState,
+			TConnParams,
+			TConnState,
+			TVars,
+			TInput,
+			TDatabase,
+			TEvents,
+			TQueues
+		>
+	>;
 	readonly log: ActorLogger;
 	readonly abortSignal: AbortSignal;
 	readonly aborted: boolean;
@@ -654,7 +664,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,
@@ -731,6 +743,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. */
@@ -947,6 +1041,7 @@ export const ActorConfigSchema = z
 		db: z.any().optional(),
 		createVars: zFunction().optional(),
 		options: ActorOptionsSchema,
+		inspector: ActorInspectorConfigSchema.optional(),
 	})
 	.strict()
 	.refine(
@@ -982,9 +1077,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,
@@ -1039,8 +1134,8 @@ type CreateConnState<
  */
 type CreateVars<
 	TState,
-	TConnParams,
-	TConnState,
+	_TConnParams,
+	_TConnState,
 	TVars,
 	TInput,
 	TDatabase extends AnyDatabaseProvider,
@@ -1501,6 +1596,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"
@@ -1536,16 +1650,7 @@ export type ActorConfig<
 		TDatabase,
 		TEvents,
 		TQueues,
-		Actions<
-			TState,
-			TConnParams,
-			TConnState,
-			TVars,
-			TInput,
-			TDatabase,
-			TEvents,
-			TQueues
-		>
+		TActions
 	> &
 	CreateState<
 		TState,

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,

package/src/actor/errors.ts

@@ -106,7 +106,9 @@ function isActorSpecifier(value: unknown): value is ActorSpecifier {
 		typeof value.actorId === "string" &&
 		"generation" in value &&
 		typeof value.generation === "number" &&
-		(!("key" in value) || value.key === undefined || typeof value.key === "string")
+		(!("key" in value) ||
+			value.key === undefined ||
+			typeof value.key === "string")
 	);
 }
 
@@ -237,7 +239,11 @@ export function decodeBridgeRivetErrorPayload(
 		if (!isRivetErrorLike(payload)) {
 			return undefined;
 		}
-		if (payload.actor !== undefined && payload.actor !== null && !isActorSpecifier(payload.actor)) {
+		if (
+			payload.actor !== undefined &&
+			payload.actor !== null &&
+			!isActorSpecifier(payload.actor)
+		) {
 			return undefined;
 		}
 

package/src/actor/instance/mod.ts

@@ -9,22 +9,21 @@ import {
 	type SpanStatusInput,
 	type Traces,
 } from "@rivetkit/traces";
-import { ActorMetrics, type StartupTimingKey } from "@/actor/metrics";
 import invariant from "invariant";
+import { ActorMetrics, type StartupTimingKey } from "@/actor/metrics";
 import type { Client } from "@/client/client";
+import type { ActorKey } from "@/client/query";
 import { getBaseLogger, getIncludeTarget, type Logger } from "@/common/log";
 import { stringifyError } from "@/common/utils";
 import type { UniversalWebSocket } from "@/common/websocket-interface";
 import { ActorInspector } from "@/inspector/actor-inspector";
-import type { ActorKey } from "@/client/query";
 import type { Registry } from "@/mod";
 import {
 	ACTOR_VERSIONED,
 	CONN_VERSIONED,
 } from "@/schemas/actor-persist/versioned";
-import { EXTRA_ERROR_LOG } from "@/utils";
+import { EXTRA_ERROR_LOG, promiseWithResolvers } from "@/utils";
 import { getRivetExperimentalOtel } from "@/utils/env-vars";
-import { promiseWithResolvers } from "@/utils";
 import {
 	type Actions,
 	type ActorConfig,
@@ -32,16 +31,13 @@ import {
 	ActorConfigSchema,
 	getRunFunction,
 } from "../config";
-import type { ConnDriver } from "../conn/driver";
-import { createHttpDriver } from "../conn/drivers/http";
 import {
-	HibernatableWebSocketAckState,
 	handleInboundHibernatableWebSocketMessage as applyInboundHibernatableWebSocketMessage,
+	HibernatableWebSocketAckState,
 } from "../conn/hibernatable-websocket-ack-state";
 import {
-	CONN_DRIVER_SYMBOL,
-	CONN_STATE_MANAGER_SYMBOL,
 	type AnyConn,
+	CONN_STATE_MANAGER_SYMBOL,
 	type Conn,
 	type ConnId,
 } from "../conn/mod";
@@ -50,7 +46,7 @@ import {
 	type PersistedConn,
 } from "../conn/persisted";
 import {
-	ActionContext,
+	type ActionContext,
 	ActorContext,
 	RequestContext,
 	WebSocketContext,
@@ -79,20 +75,16 @@ import {
 import { ConnectionManager } from "./connection-manager";
 import { EventManager } from "./event-manager";
 import { KEYS, workflowStoragePrefix } from "./keys";
-import {
-	type PreloadedEntries,
-	type PreloadHit,
-	type PreloadMap,
-} from "./preload-map";
 import {
 	convertActorFromBarePersisted,
 	type PersistedActor,
 } from "./persisted";
+import type { PreloadedEntries, PreloadMap } from "./preload-map";
 import { QueueManager } from "./queue-manager";
 import { ScheduleManager } from "./schedule-manager";
 import { type SaveStateOptions, StateManager } from "./state-manager";
-import { TrackedWebSocket } from "./tracked-websocket";
 import { ActorTracesDriver } from "./traces-driver";
+import { TrackedWebSocket } from "./tracked-websocket";
 import { WriteCollector } from "./write-collector";
 
 export type { SaveStateOptions };
@@ -215,14 +207,14 @@ const ACTIVE_ASYNC_REGION_ERROR_MESSAGES: Record<
  * only on `ActorInstance`.
  */
 export interface BaseActorInstance<
-	S = any,
-	CP = any,
-	CS = any,
-	V = any,
-	I = any,
-	DB extends AnyDatabaseProvider = AnyDatabaseProvider,
-	E extends EventSchemaConfig = Record<never, never>,
-	Q extends QueueSchemaConfig = Record<never, never>,
+	_S = any,
+	_CP = any,
+	_CS = any,
+	_V = any,
+	_I = any,
+	_DB extends AnyDatabaseProvider = AnyDatabaseProvider,
+	_E extends EventSchemaConfig = Record<never, never>,
+	_Q extends QueueSchemaConfig = Record<never, never>,
 > {
 	readonly id: string;
 	readonly isStopping: boolean;
@@ -1274,7 +1266,7 @@ export class ActorInstance<
 							"actor.onBeforeActionResponse",
 							{ "rivet.action.name": actionName },
 							() =>
-								this.#config.onBeforeActionResponse!(
+								this.#config.onBeforeActionResponse?.(
 									this.actorContext,
 									actionName,
 									args,
@@ -1406,7 +1398,7 @@ export class ActorInstance<
 
 			// NOTE: This is async and will run in the background
 			const voidOrPromise = this.#traces.withSpan(span, () =>
-				this.#config.onWebSocket!(ctx, trackedWebSocket),
+				this.#config.onWebSocket?.(ctx, trackedWebSocket),
 			);
 
 			// Save changes from the WebSocket open
@@ -1645,10 +1637,10 @@ export class ActorInstance<
 		attributes?: Record<string, unknown>,
 	): Record<string, unknown> {
 		return {
-			"rivet.actor.id": this.#actorId,
-			"rivet.actor.name": this.#name,
-			"rivet.actor.key": this.#actorKeyString,
-			"rivet.actor.region": this.#region,
+			"rivet.actors.actor.id": this.#actorId,
+			"rivet.actors.actor.name": this.#name,
+			"rivet.actors.actor.key": this.#actorKeyString,
+			"rivet.actors.actor.region": this.#region,
 			...(attributes ?? {}),
 		};
 	}
@@ -1882,7 +1874,7 @@ export class ActorInstance<
 				"actor.createVars",
 				undefined,
 				() => {
-					const dataOrPromise = createVars!(
+					const dataOrPromise = createVars?.(
 						this.actorContext as any,
 						this.driver.getContext(this.#actorId),
 					);
@@ -2084,7 +2076,7 @@ export class ActorInstance<
 		}
 	}
 
-	async #setupDatabase(preload?: PreloadMap) {
+	async #setupDatabase(_preload?: PreloadMap) {
 		if (!("db" in this.#config) || !this.#config.db) {
 			return;
 		}
@@ -2099,14 +2091,14 @@ export class ActorInstance<
 					overrideRawDatabaseClient: this.driver
 						.overrideRawDatabaseClient
 						? () =>
-								this.driver.overrideRawDatabaseClient!(
+								this.driver.overrideRawDatabaseClient?.(
 									this.#actorId,
 								)
 						: undefined,
 					overrideDrizzleDatabaseClient: this.driver
 						.overrideDrizzleDatabaseClient
 						? () =>
-								this.driver.overrideDrizzleDatabaseClient!(
+								this.driver.overrideDrizzleDatabaseClient?.(
 									this.#actorId,
 								)
 						: undefined,

package/src/actor/keys.ts

@@ -135,7 +135,7 @@ export function deserializeActorKey(keyString: string | undefined): ActorKey {
 	// Add the last part
 	if (escaping) {
 		// Incomplete escape at the end - treat as literal backslash
-		parts.push(currentPart + "\\");
+		parts.push(`${currentPart}\\`);
 	} else if (isEmptyStringMarker) {
 		parts.push("");
 	} else if (currentPart !== "" || parts.length > 0) {