rivetkit 2.3.11-rc.8 → 2.3.11

package/src/actor/config.ts

@@ -5,6 +5,7 @@ import type {
 	InferDatabaseClient,
 } from "@/common/database/config";
 import type { UniversalWebSocket } from "@/common/websocket-interface";
+import type { WorkflowState } from "@/inspector/workflow";
 import type { Registry } from "@/registry";
 import { flattenActionHandlers } from "./actions";
 import type { BaseActorDefinition } from "./definition";
@@ -64,7 +65,7 @@ type ActorKvListOptions<
 type ActorClientFor<T> = T extends Registry<any> ? Client<T> : T;
 
 /**
- * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db` / `c.sql`)
+ * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db`)
  * or actor state instead.
  */
 export interface ActorKv {
@@ -332,6 +333,16 @@ export interface ActorQueue<
 		names: readonly TName[],
 		opts?: QueueWaitOptions<TCompletable>,
 	): Promise<any>;
+	/** @experimental */
+	waitForAvailable<const TName extends QueueFilterName<TQueues>>(
+		names?: readonly TName[],
+		opts?: Omit<QueueWaitOptions<false>, "completable">,
+	): Promise<void>;
+	/** @experimental */
+	complete<const TName extends QueueFilterName<TQueues>>(
+		message: { id: number | bigint; name: TName },
+		...args: QueueCompleteArgsForName<TQueues, TName>
+	): Promise<void>;
 	enqueueAndWait<const TName extends QueueFilterName<TQueues>>(
 		name: TName,
 		body: QueueMessageForName<TQueues, TName>["body"],
@@ -389,7 +400,7 @@ export interface ActorContext<
 	state: TState;
 	vars: TVars;
 	/**
-	 * @deprecated Actor KV is deprecated. Use embedded SQLite (`db` / `sql`)
+	 * @deprecated Actor KV is deprecated. Use embedded SQLite (`c.db`)
 	 * or actor state instead.
 	 */
 	readonly kv: ActorKv;
@@ -397,6 +408,8 @@ export interface ActorContext<
 	readonly schedule: ActorSchedule;
 	readonly cron: ActorCron;
 	readonly queue: ActorQueue<TQueues>;
+	/** @experimental */
+	readonly run: ActorRun;
 	readonly actorId: string;
 	readonly name: string;
 	readonly key: string[];
@@ -434,6 +447,15 @@ export interface ActorContext<
 	[key: string]: any;
 }
 
+/** @experimental */
+export interface ActorRun {
+	/**
+	 * @experimental Sets or clears the durable Unix-millisecond deadline that
+	 * ensures this actor's run handler is active, starting it if inactive.
+	 */
+	setWakeAt(timestamp: number | null): Promise<void>;
+}
+
 export type ActionContext<
 	TState,
 	TConnParams,
@@ -821,20 +843,27 @@ const zActionTree = z
 
 export type InspectorUnsubscribe = () => void;
 
+/** @experimental */
 export interface WorkflowInspectorConfig<THistory = unknown> {
 	getHistory: () => THistory | null;
+	getState?: () => Promise<WorkflowState | null>;
 	onHistoryUpdated?: (
 		listener: (history: THistory) => void,
 	) => InspectorUnsubscribe;
 	replayFromStep?: (entryId?: string) => Promise<THistory | null>;
 }
 
+/** @experimental */
 export interface RunInspectorConfig<THistory = unknown> {
 	workflow?: WorkflowInspectorConfig<THistory>;
 }
 
 const WorkflowInspectorConfigSchema = z.object({
 	getHistory: zFunction<WorkflowInspectorConfig<unknown>["getHistory"]>(),
+	getState:
+		zFunction<
+			NonNullable<WorkflowInspectorConfig<unknown>["getState"]>
+		>().optional(),
 	onHistoryUpdated:
 		zFunction<
 			NonNullable<WorkflowInspectorConfig<unknown>["onHistoryUpdated"]>
@@ -981,9 +1010,72 @@ type AnyRunConfig = RunConfig<
 	any
 >;
 
-export const RUN_FUNCTION_CONFIG_SYMBOL = Symbol.for(
-	"rivetkit.run_function_config",
-);
+const RUN_FUNCTION_CONFIG_SYMBOL = Symbol.for("rivetkit.run_function_config");
+
+/** @experimental */
+export type RunInspectorKind = "workflow";
+
+/** @experimental */
+export interface RunWithInactiveOptions {
+	/** Restart the run handler before releasing the exclusive gate on success. */
+	restartOnSuccess?: boolean;
+}
+
+/** @experimental */
+export interface RunControl {
+	run: {
+		/**
+		 * Executes only while no run handler is active or waiting to start.
+		 *
+		 * This is a non-blocking acquisition: concurrent replay/control requests
+		 * fail instead of waiting behind an active run.
+		 */
+		withInactive<T>(
+			options: RunWithInactiveOptions,
+			callback: () => T | Promise<T>,
+		): Promise<T>;
+	};
+}
+
+/** @experimental */
+export interface RunInspectorFactoryContext {
+	actorId: string;
+	control: RunControl;
+}
+
+/** @experimental */
+export interface RunInspectorFactoryResult<THistory = unknown> {
+	inspector: {
+		workflow: Required<WorkflowInspectorConfig<THistory>> & {
+			getState: () => Promise<WorkflowState | null>;
+		};
+	};
+	/** Releases actor-specific listeners and encoded history. */
+	dispose?: () => void;
+}
+
+interface RunHandlerDisplayOptions {
+	name?: string;
+	icon?: string;
+}
+
+/** @experimental */
+export type DefineRunHandlerOptions<THistory = unknown> =
+	RunHandlerDisplayOptions &
+		(
+			| {
+					inspectorKind?: never;
+					createInspector?: never;
+			  }
+			| {
+					/** Static metadata used to install Inspector callbacks at registry build time. */
+					inspectorKind: RunInspectorKind;
+					/** Creates one Inspector adapter for each live actor. */
+					createInspector: (
+						context: RunInspectorFactoryContext,
+					) => RunInspectorFactoryResult<THistory>;
+			  }
+		);
 
 interface RunFunctionConfig {
 	name?: string;
@@ -992,12 +1084,69 @@ interface RunFunctionConfig {
 	inspectorFactory?: (actor: unknown) => RunInspectorConfig | undefined;
 	/** Release any per-actor inspector state held for this actor id. */
 	disposeInspector?: (actorId: string) => void;
+	inspectorKind?: RunInspectorKind;
+	createInspector?: (
+		context: RunInspectorFactoryContext,
+	) => RunInspectorFactoryResult;
 }
 
 type RunFunctionWithConfig = ((...args: any[]) => any) & {
 	[RUN_FUNCTION_CONFIG_SYMBOL]?: RunFunctionConfig;
 };
 
+/**
+ * @experimental Adds supported RivetKit run metadata while preserving the function's exact
+ * callable type.
+ */
+export function defineRunHandler<
+	TRun extends (...args: any[]) => any,
+	THistory = unknown,
+>(run: TRun, options: DefineRunHandlerOptions<THistory>): TRun {
+	if (
+		(options.inspectorKind === undefined) !==
+		(options.createInspector === undefined)
+	) {
+		throw new TypeError(
+			"defineRunHandler requires inspectorKind and createInspector together",
+		);
+	}
+
+	Object.defineProperty(run, RUN_FUNCTION_CONFIG_SYMBOL, {
+		configurable: false,
+		enumerable: false,
+		writable: false,
+		value: {
+			name: options.name,
+			icon: options.icon,
+			inspectorKind: options.inspectorKind,
+			createInspector:
+				options.createInspector as RunFunctionConfig["createInspector"],
+		} satisfies RunFunctionConfig,
+	});
+
+	return run;
+}
+
+/** @internal */
+export function getRunInspectorKind(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+): RunInspectorKind | undefined {
+	if (!run || typeof run !== "function") return undefined;
+	return (run as RunFunctionWithConfig)[RUN_FUNCTION_CONFIG_SYMBOL]
+		?.inspectorKind;
+}
+
+/** @internal */
+export function createRunInspector(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+	context: RunInspectorFactoryContext,
+): RunInspectorFactoryResult | undefined {
+	if (!run || typeof run !== "function") return undefined;
+	return (run as RunFunctionWithConfig)[
+		RUN_FUNCTION_CONFIG_SYMBOL
+	]?.createInspector?.(context);
+}
+
 // Run can be either a function or an object with name/icon/run
 const zRunHandler = z.union([zFunction(), RunConfigSchema]).optional();
 
@@ -1042,6 +1191,21 @@ export function getRunInspectorConfig(
 	return run.inspector;
 }
 
+/** @internal */
+export function hasRunInspectorConfig(
+	run: ((...args: any[]) => any) | AnyRunConfig | undefined,
+): boolean {
+	if (!run) return false;
+	if (typeof run !== "function") return run.inspector !== undefined;
+	const config = (run as RunFunctionWithConfig)[RUN_FUNCTION_CONFIG_SYMBOL];
+	return (
+		config?.inspectorKind !== undefined ||
+		config?.createInspector !== undefined ||
+		config?.inspector !== undefined ||
+		config?.inspectorFactory !== undefined
+	);
+}
+
 /** 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,

package/src/actor/mod.ts

@@ -14,6 +14,7 @@ export type {
 	UniversalWebSocket,
 } from "@/common/websocket-interface";
 export type * from "./config";
+export { defineRunHandler } from "./config";
 export type {
 	ActionContextOf,
 	BeforeActionResponseContextOf,
@@ -57,4 +58,12 @@ export {
 	UserError,
 	type UserErrorOptions,
 } from "./errors";
-export { event, queue, type Type } from "./schema";
+export {
+	type EventSchemaConfig,
+	event,
+	type InferEventArgs,
+	type InferSchemaMap,
+	type QueueSchemaConfig,
+	queue,
+	type Type,
+} from "./schema";

package/src/client/actor-common.ts

@@ -48,20 +48,11 @@ type ActorActionMap<R> = {
 			: never;
 };
 
-type ActionsOf<AD extends AnyActorDefinition> =
-	AD extends BaseActorDefinition<
-		any,
-		any,
-		any,
-		any,
-		any,
-		any,
-		any,
-		any,
-		infer R
-	>
-		? R
-		: never;
+type ActionsOf<AD extends AnyActorDefinition> = AD["config"] extends {
+	actions?: infer R;
+}
+	? R
+	: never;
 
 export interface ActorGatewayOptions {
 	skipReadyWait?: boolean;

package/src/common/database/config.ts

@@ -9,7 +9,7 @@ export interface ActorMetricsLike {
 export type InferDatabaseClient<DBProvider extends AnyDatabaseProvider> =
 	DBProvider extends DatabaseProvider<any>
 		? Awaited<ReturnType<DBProvider["createClient"]>>
-		: never;
+		: RawAccess;
 
 export type SqliteBindings = unknown[] | Record<string, unknown>;
 
@@ -28,6 +28,43 @@ export interface SqliteBatchStatement {
 	params?: SqliteBindings;
 }
 
+export interface SqliteTransactionOptions {
+	/** Static operation name used to aggregate transaction performance. */
+	name?: string;
+	/** Deadlock-safety timeout in milliseconds. */
+	timeout?: number;
+	/** @experimental */
+	experimental?: {
+		/**
+		 * Atomically includes actor and hibernatable connection state.
+		 * Only single-statement `execute` calls are supported in the transaction.
+		 * Concurrent actions that try to mutate state while the transaction is
+		 * active fail with `actor.state_transaction_conflict`.
+		 */
+		includeState?: boolean;
+	};
+}
+
+/**
+ * SQLite profiling configuration.
+ *
+ * @experimental This entire configuration surface is experimental and subject
+ * to change without notice.
+ */
+export interface SqliteProfilingOptions {
+	enabled?: boolean;
+	maxTrackedStatementFingerprints?: number;
+	maxTrackedTransactionFingerprints?: number;
+	maxPrometheusSeries?: number;
+	maxStatementsPerTransactionTrace?: number;
+	maxGetPagesRequestsPerTrace?: number;
+	maxTransactionNameBytes?: number;
+	slowOperationThresholdMs?: number;
+	baselineSampleRate?: number;
+	maxDiagnosticEventsPerMinute?: number;
+	diagnosticEventQueueCapacity?: number;
+}
+
 export interface SqliteNativeMetrics {
 	requestBuildNs: number;
 	serializeNs: number;
@@ -51,7 +88,10 @@ export interface SqliteDatabase {
 	executeBatch(
 		statements: SqliteBatchStatement[],
 	): Promise<SqliteExecuteResult[]>;
-	beginTransaction(timeoutMs?: number): Promise<SqliteTransactionDatabase>;
+	beginTransaction(
+		timeoutMs?: number,
+		name?: string,
+	): Promise<SqliteTransactionDatabase>;
 	run(sql: string, params?: SqliteBindings): Promise<void>;
 	query(sql: string, params?: SqliteBindings): Promise<SqliteQueryResult>;
 	nativeMetrics?():
@@ -121,6 +161,13 @@ export interface DatabaseProviderContext {
 }
 
 export type DatabaseProvider<DB extends RawAccess> = {
+	/**
+	 * Local SQLite profiling controls consumed by the actor runtime.
+	 *
+	 * @experimental This entire configuration surface is experimental and
+	 * subject to change without notice.
+	 */
+	sqliteProfiling?: SqliteProfilingOptions;
 	/**
 	 * Creates a new database client for the actor.
 	 * The result is passed to the actor context as `c.db`.
@@ -165,7 +212,7 @@ export type RawAccess = {
 	/** Runs a callback in an isolated SQLite transaction. */
 	transaction: <T>(
 		callback: (tx: RawAccess) => Promise<T> | T,
-		options?: { timeout?: number },
+		options?: SqliteTransactionOptions,
 	) => Promise<T>;
 	/**
 	 * Returns native SQLite metrics when the active runtime supports them.

package/src/common/database/mod.test.ts

@@ -8,14 +8,16 @@ import type {
 	SqliteExecuteResult,
 	SqliteTransactionDatabase,
 } from "./config";
-import { db } from "./mod";
+import { db, registerNativeStateTransactionOpener } from "./mod";
 
 let logLines: string[];
 
 class FakeSqliteDatabase implements SqliteDatabase {
 	failSql = new Map<string, Error>();
 	executeCalls: { sql: string; params?: SqliteBindings }[] = [];
+	stateTransactionTimeouts: Array<number | undefined> = [];
 	transactionTimeouts: Array<number | undefined> = [];
+	transactionNames: Array<string | undefined> = [];
 
 	async exec(): Promise<void> {}
 
@@ -29,8 +31,10 @@ class FakeSqliteDatabase implements SqliteDatabase {
 
 	async beginTransaction(
 		timeoutMs?: number,
+		name?: string,
 	): Promise<SqliteTransactionDatabase> {
 		this.transactionTimeouts.push(timeoutMs);
+		this.transactionNames.push(name);
 		this.record("BEGIN");
 		return {
 			exec: async () => {},
@@ -42,6 +46,21 @@ class FakeSqliteDatabase implements SqliteDatabase {
 			rollback: async () => this.record("ROLLBACK"),
 		};
 	}
+	async beginStateTransaction(
+		timeoutMs?: number,
+	): Promise<SqliteTransactionDatabase> {
+		this.stateTransactionTimeouts.push(timeoutMs);
+		this.record("BEGIN_STATE");
+		return {
+			exec: async () => {},
+			execute: async (sql, params) => {
+				this.record(sql, params);
+				return emptyResult();
+			},
+			commit: async () => this.record("COMMIT"),
+			rollback: async () => this.record("ROLLBACK"),
+		};
+	}
 
 	async executeBatch(
 		statements: Array<{ sql: string; params?: SqliteBindings }>,
@@ -81,7 +100,8 @@ function emptyResult(): SqliteExecuteResult {
 }
 
 function testProviderContext(
-	database: SqliteDatabase,
+	database: FakeSqliteDatabase,
+	includeStateTransactions = false,
 ): DatabaseProviderContext {
 	return {
 		actorId: "actor-a",
@@ -91,7 +111,13 @@ function testProviderContext(
 			batchDelete: async () => {},
 			deleteRange: async () => {},
 		},
-		nativeDatabaseProvider: { open: async () => database },
+		nativeDatabaseProvider: includeStateTransactions
+			? registerNativeStateTransactionOpener(
+					{ open: async () => database },
+					async (timeoutMs?: number) =>
+						await database.beginStateTransaction(timeoutMs),
+				)
+			: { open: async () => database },
 	};
 }
 
@@ -128,6 +154,23 @@ describe("db", () => {
 			"COMMIT",
 		]);
 		expect(nativeDb.transactionTimeouts).toEqual([300_000]);
+		expect(nativeDb.transactionNames).toEqual(["rivetkit-migration"]);
+	});
+
+	test("exposes profiling controls to the actor runtime", () => {
+		const provider = db({
+			profiling: {
+				enabled: false,
+				maxTrackedStatementFingerprints: 12,
+				baselineSampleRate: 0.25,
+			},
+		});
+
+		expect(provider.sqliteProfiling).toEqual({
+			enabled: false,
+			maxTrackedStatementFingerprints: 12,
+			baselineSampleRate: 0.25,
+		});
 	});
 
 	test("rolls back migrations when onMigrate fails", async () => {
@@ -163,10 +206,11 @@ describe("db", () => {
 				);
 				return 42;
 			},
-			{ timeout: 120_000 },
+			{ name: "insert-item", timeout: 120_000 },
 		);
 		expect(value).toBe(42);
 		expect(nativeDb.transactionTimeouts).toEqual([120_000]);
+		expect(nativeDb.transactionNames).toEqual(["insert-item"]);
 		expect(nativeDb.executeCalls.map(({ sql }) => sql)).toEqual([
 			"BEGIN",
 			"INSERT INTO items(value) VALUES (?)",
@@ -174,6 +218,25 @@ describe("db", () => {
 		]);
 	});
 
+	test("validates transaction names", async () => {
+		const client = await db().createClient(
+			testProviderContext(new FakeSqliteDatabase()),
+		);
+		await expect(
+			client.transaction(async () => {}, { name: "" }),
+		).rejects.toThrow("must not be empty");
+	});
+
+	test("defers the configured transaction name byte limit to the runtime", async () => {
+		const nativeDb = new FakeSqliteDatabase();
+		const client = await db().createClient(testProviderContext(nativeDb));
+		const name = "x".repeat(129);
+
+		await client.transaction(async () => {}, { name });
+
+		expect(nativeDb.transactionNames).toEqual([name]);
+	});
+
 	test("rolls back a transaction when the callback throws", async () => {
 		const nativeDb = new FakeSqliteDatabase();
 		const client = await db().createClient(testProviderContext(nativeDb));
@@ -193,6 +256,81 @@ describe("db", () => {
 		]);
 	});
 
+	test("uses the state-aware transaction bridge when explicitly requested", async () => {
+		const nativeDb = new FakeSqliteDatabase();
+		const client = await db().createClient(
+			testProviderContext(nativeDb, true),
+		);
+
+		await client.transaction(
+			async (tx) => {
+				await tx.execute(
+					"INSERT INTO items(value) VALUES (?)",
+					"inside",
+				);
+			},
+			{
+				timeout: 120_000,
+				experimental: { includeState: true },
+			},
+		);
+
+		expect(nativeDb.transactionTimeouts).toEqual([]);
+		expect(nativeDb.stateTransactionTimeouts).toEqual([120_000]);
+		expect(nativeDb.executeCalls.map(({ sql }) => sql)).toEqual([
+			"BEGIN_STATE",
+			"INSERT INTO items(value) VALUES (?)",
+			"COMMIT",
+		]);
+	});
+
+	test("rolls back state-aware transactions when the callback throws", async () => {
+		const nativeDb = new FakeSqliteDatabase();
+		const client = await db().createClient(
+			testProviderContext(nativeDb, true),
+		);
+
+		await expect(
+			client.transaction(
+				async (tx) => {
+					await tx.execute(
+						"INSERT INTO items(value) VALUES (?)",
+						"inside",
+					);
+					throw new Error("callback failed");
+				},
+				{ experimental: { includeState: true } },
+			),
+		).rejects.toThrow("callback failed");
+		expect(nativeDb.executeCalls.map(({ sql }) => sql)).toEqual([
+			"BEGIN_STATE",
+			"INSERT INTO items(value) VALUES (?)",
+			"ROLLBACK",
+		]);
+	});
+
+	test("rejects nested state-aware transactions", async () => {
+		const nativeDb = new FakeSqliteDatabase();
+		const client = await db().createClient(
+			testProviderContext(nativeDb, true),
+		);
+
+		await expect(
+			client.transaction(
+				async (tx) => {
+					await tx.transaction(async () => {}, {
+						experimental: { includeState: true },
+					});
+				},
+				{ experimental: { includeState: true } },
+			),
+		).rejects.toThrow("not supported for nested transactions");
+		expect(nativeDb.executeCalls.map(({ sql }) => sql)).toEqual([
+			"BEGIN_STATE",
+			"ROLLBACK",
+		]);
+	});
+
 	test("validates transaction timeouts", async () => {
 		const client = await db().createClient(
 			testProviderContext(new FakeSqliteDatabase()),