@rivetkit/rivetkit-napi 0.0.0-main.41efcce → 0.0.0-main.49693dc

package/index.d.ts

@@ -23,10 +23,16 @@ export interface StateDeltaPayload {
   connHibernation: Array<StateDeltaConnHibernationEntry>
   connHibernationRemoved: Array<string>
 }
+export interface WorkflowKvWritePayload {
+  key: Buffer
+  value: Buffer
+}
 export interface JsRequestSaveOpts {
   immediate?: boolean
   maxWaitMs?: number
 }
+export declare function decodeInspectorRequest(bytes: Buffer, advertisedVersion: number): Buffer
+export declare function encodeInspectorResponse(bytes: Buffer, targetVersion: number): Buffer
 export interface JsInspectorSnapshot {
   stateRevision: number
   connectionsRevision: number
@@ -35,6 +41,9 @@ export interface JsInspectorSnapshot {
   queueSize: number
   connectedClients: number
 }
+export interface JsActorRuntimeSocketEndpointInfo {
+  path: string
+}
 export interface JsHttpResponse {
   status?: number
   headers?: Record<string, string>
@@ -47,10 +56,50 @@ export interface JsQueueSendResult {
 export interface JsActionDefinition {
   name: string
 }
+/**
+ * One entry in the actor's `inspector.tabs[]` declaration. Either a
+ * custom-tab descriptor (id + label + source dir) or a built-in modifier
+ * (id + hidden=true). Validation already happened on the TS side; the
+ * runtime just splits the discriminator.
+ */
+export interface JsInspectorTabEntry {
+  id: string
+  /** Required for custom entries; omitted for HideBuiltin. */
+  label?: string
+  /** Required for custom entries — absolute path to the source directory. */
+  source?: string
+  /**
+   * Optional icon id for custom entries. Dashboard maps strings to
+   * glyphs; unknown ids fall back to a generic icon.
+   */
+  icon?: string
+  /** Set to true for HideBuiltin entries. */
+  hidden?: boolean
+}
+/**
+ * Experimental SQLite profiling configuration. This entire configuration
+ * surface is subject to change without notice.
+ */
+export interface JsSqliteProfilingConfig {
+  enabled?: boolean
+  maxTrackedStatementFingerprints?: number
+  maxTrackedTransactionFingerprints?: number
+  maxPrometheusSeries?: number
+  maxStatementsPerTransactionTrace?: number
+  maxGetPagesRequestsPerTrace?: number
+  maxTransactionNameBytes?: number
+  slowOperationThresholdMs?: number
+  baselineSampleRate?: number
+  maxDiagnosticEventsPerMinute?: number
+  diagnosticEventQueueCapacity?: number
+}
 export interface JsActorConfig {
   name?: string
   icon?: string
   hasDatabase?: boolean
+  remoteSqlite?: boolean
+  sqliteProfiling?: JsSqliteProfilingConfig
+  enableActorRuntimeSocket?: boolean
   hasState?: boolean
   canHibernateWebsocket?: boolean
   stateSaveIntervalMs?: number
@@ -71,12 +120,12 @@ export interface JsActorConfig {
   connectionLivenessTimeoutMs?: number
   connectionLivenessIntervalMs?: number
   maxQueueSize?: number
+  maxSchedules?: number
   maxQueueMessageSize?: number
   maxIncomingMessageSize?: number
   maxOutgoingMessageSize?: number
-  preloadMaxWorkflowBytes?: number
-  preloadMaxConnectionsBytes?: number
   actions?: Array<JsActionDefinition>
+  inspectorTabs?: Array<JsInspectorTabEntry>
 }
 export interface JsBindParam {
   kind: string
@@ -92,6 +141,16 @@ export interface QueryResult {
   columns: Array<string>
   rows: Array<Array<any>>
 }
+export interface NativeExecuteResult {
+  columns: Array<string>
+  rows: Array<Array<any>>
+  changes: number
+  lastInsertRowId?: number
+}
+export interface JsSqliteBatchStatement {
+  sql: string
+  params?: Array<JsBindParam>
+}
 export interface JsSqliteVfsMetrics {
   requestBuildNs: number
   serializeNs: number
@@ -99,6 +158,11 @@ export interface JsSqliteVfsMetrics {
   stateUpdateNs: number
   totalNs: number
   commitCount: number
+  pageCacheEntries: number
+  pageCacheWeightedSize: number
+  pageCacheCapacityPages: number
+  writeBufferDirtyPages: number
+  dbSizePages: number
 }
 export interface JsQueueNextOptions {
   names?: Array<string>
@@ -143,6 +207,8 @@ export interface JsServeConfig {
   namespace: string
   poolName: string
   engineBinaryPath?: string
+  engineHost?: string
+  enginePort?: number
   handleInspectorHttpInRuntime?: boolean
   serverlessBasePath?: string
   serverlessPackageVersion: string
@@ -152,6 +218,16 @@ export interface JsServeConfig {
   serverlessValidateEndpoint: boolean
   serverlessMaxStartPayloadBytes: number
 }
+export interface JsListenerConfig {
+  /** Host to bind. Defaults to `0.0.0.0` when not provided. */
+  host?: string
+  port: number
+  /**
+   * Optional static file root mounted as a fallback below the framework
+   * routes.
+   */
+  publicDir?: string
+}
 export interface JsServerlessRequest {
   method: string
   url: string
@@ -162,11 +238,53 @@ export interface JsServerlessResponseHead {
   status: number
   headers: Record<string, string>
 }
+export interface JsApplicationResponse {
+  status: number
+  headers: Record<string, string>
+  body: Buffer
+}
+export interface JsRegistryRouteResponse {
+  status: number
+  headers: Record<string, string>
+  body: Buffer
+}
 export interface JsServerlessStreamError {
   group: string
   code: string
   message: string
 }
+export interface JsScheduledEventInfo {
+  id: string
+  action: string
+  args: Buffer
+  runAt: number
+}
+export interface JsCronJobInfo {
+  name: string
+  kind: string
+  action: string
+  args: Buffer
+  nextRunAt: number
+  lastRunAt?: number
+  expression?: string
+  timezone?: string
+  intervalMs?: number
+  maxHistory: number
+}
+export interface JsScheduleErrorInfo {
+  group: string
+  code: string
+  message: string
+  metadata?: any
+}
+export interface JsCronFire {
+  action: string
+  scheduledAt: number
+  firedAt: number
+  finishedAt?: number
+  result: string
+  error?: JsScheduleErrorInfo
+}
 /** Options for KV list operations. */
 export interface JsKvListOptions {
   reverse?: boolean
@@ -179,12 +297,12 @@ export interface JsKvEntry {
 }
 /** N-API wrapper around `rivetkit-core::ActorContext`. */
 export declare class ActorContext {
-  constructor(actorId: string, name: string, region: string)
   state(): Buffer
   beginOnStateChange(): void
   endOnStateChange(): void
   kv(): Kv
   sql(): JsNativeDatabase
+  provisionActorRuntimeSocket(): Promise<JsActorRuntimeSocketEndpointInfo>
   schedule(): Schedule
   queue(): Queue
   setAlarm(timestampMs?: number | undefined | null): void
@@ -199,6 +317,8 @@ export declare class ActorContext {
   takePendingHibernationChanges(): Array<string>
   dirtyHibernatableConns(): Array<ConnHandle>
   saveState(payload: StateDeltaPayload): Promise<void>
+  beginStateTransaction(timeoutMs?: number | undefined | null): Promise<JsActorStateTransaction>
+  saveStateAndWorkflowBatch(writes: Array<WorkflowKvWritePayload>): Promise<void>
   actorId(): string
   name(): string
   key(): Array<JsActorKeySegment>
@@ -212,6 +332,10 @@ export declare class ActorContext {
   aborted(): boolean
   runHandlerActive(): boolean
   restartRunHandler(): void
+  setRunWakeAt(timestampMs?: number | undefined | null): Promise<void>
+  beginKeepAwake(): number
+  endKeepAwake(regionId: number): void
+  keepAwake(promise: Promise<any>): void
   beginWebsocketCallback(): number
   endWebsocketCallback(regionId: number): void
   abortSignal(): AbortSignal
@@ -221,7 +345,8 @@ export declare class ActorContext {
   disconnectConns(predicate: (...args: any[]) => any): Promise<void>
   broadcast(name: string, args: Buffer): void
   waitUntil(promise: Promise<any>): void
-  keepAwake(promise: Promise<any>): Promise<any>
+  waitForTrackedShutdownWork(): Promise<boolean>
+  waitForTrackedShutdownWorkUnbounded(): Promise<void>
   registerTask(promise: Promise<any>): void
   runtimeState(): object
   clearRuntimeState(): void
@@ -246,11 +371,25 @@ export declare class ConnHandle {
 }
 export declare class JsNativeDatabase {
   takeLastKvError(): string | null
-  getSqliteVfsMetrics(): JsSqliteVfsMetrics | null
+  metrics(): JsSqliteVfsMetrics | null
   run(sql: string, params?: Array<JsBindParam> | undefined | null): Promise<ExecuteResult>
   query(sql: string, params?: Array<JsBindParam> | undefined | null): Promise<QueryResult>
+  execute(sql: string, params?: Array<JsBindParam> | undefined | null): Promise<NativeExecuteResult>
+  executeBatch(statements: Array<JsSqliteBatchStatement>): Promise<Array<NativeExecuteResult>>
   exec(sql: string): Promise<QueryResult>
   close(): Promise<void>
+  beginTransaction(timeoutMs?: number | undefined | null, name?: string | undefined | null): Promise<JsSqliteTransaction>
+}
+export declare class JsSqliteTransaction {
+  execute(sql: string, params?: Array<JsBindParam> | undefined | null): Promise<NativeExecuteResult>
+  exec(sql: string): Promise<QueryResult>
+  commit(): Promise<void>
+  rollback(): Promise<void>
+}
+export declare class JsActorStateTransaction {
+  execute(sql: string, params?: Array<JsBindParam> | undefined | null): Promise<NativeExecuteResult>
+  commit(payload: StateDeltaPayload): Promise<void>
+  rollback(): Promise<void>
 }
 export declare class Kv {
   get(key: Buffer): Promise<Buffer | null>
@@ -268,11 +407,13 @@ export declare class Queue {
   next(options?: JsQueueNextOptions | undefined | null, signal?: CancellationToken | undefined | null): Promise<QueueMessage | null>
   nextBatch(options?: JsQueueNextBatchOptions | undefined | null, signal?: CancellationToken | undefined | null): Promise<Array<QueueMessage>>
   waitForNames(names: Array<string>, options?: JsQueueWaitOptions | undefined | null, signal?: CancellationToken | undefined | null): Promise<QueueMessage>
-  waitForNamesAvailable(names: Array<string>, options?: JsQueueWaitOptions | undefined | null): Promise<void>
+  waitForNamesAvailable(names: Array<string>, options?: JsQueueWaitOptions | undefined | null, signal?: CancellationToken | undefined | null): Promise<void>
+  completePersisted(messageId: bigint, expectedName: string, response?: Buffer | undefined | null): Promise<boolean>
   enqueueAndWait(name: string, body: Buffer, options?: JsQueueEnqueueAndWaitOptions | undefined | null, signal?: CancellationToken | undefined | null): Promise<Buffer | null>
   tryNext(options?: JsQueueTryNextOptions | undefined | null): QueueMessage | null
   tryNextBatch(options?: JsQueueTryNextBatchOptions | undefined | null): Array<QueueMessage>
   maxSize(): number
+  reset(): Promise<void>
   inspectMessages(): Promise<Array<JsQueueInspectMessage>>
 }
 export declare class QueueMessage {
@@ -287,6 +428,13 @@ export declare class CoreRegistry {
   constructor()
   register(name: string, factory: NapiActorFactory): void
   serve(config: JsServeConfig): Promise<void>
+  /**
+   * Wait until the serverful envoy has completed its Engine registration.
+   *
+   * Readiness is the envoy client's `ToEnvoyInit` signal, not HTTP health or
+   * merely constructing the envoy handle.
+   */
+  waitReady(): Promise<void>
   /**
    * Trip the shutdown token and tear down any live serverless runtime.
    *
@@ -295,11 +443,26 @@ export declare class CoreRegistry {
    * separately to avoid re-entrancy.
    */
   shutdown(): Promise<void>
+  actorStopThresholdMs(): Promise<number | null>
+  health(): Promise<JsRegistryRouteResponse>
+  metadata(): JsRegistryRouteResponse
+  metrics(): JsRegistryRouteResponse
+  serveApplicationListener(listener: JsListenerConfig, application: (...args: any[]) => any, config: JsServeConfig): Promise<void>
+  serveListener(listener: JsListenerConfig, config: JsServeConfig, application?: (...args: any[]) => any | undefined | null): Promise<void>
   handleServerlessRequest(req: JsServerlessRequest, onStreamEvent: (...args: any[]) => any, cancelToken: CancellationToken, config: JsServeConfig): Promise<JsServerlessResponseHead>
 }
 export declare class Schedule {
-  after(durationMs: number, actionName: string, args: Buffer): void
-  at(timestampMs: number, actionName: string, args: Buffer): void
+  after(durationMs: number, actionName: string, args: Buffer): Promise<string>
+  at(timestampMs: number, actionName: string, args: Buffer): Promise<string>
+  cancel(id: string): Promise<boolean>
+  get(id: string): Promise<JsScheduledEventInfo | null>
+  list(): Promise<Array<JsScheduledEventInfo>>
+  cronSet(name: string, expression: string, timezone: string | undefined | null, actionName: string, args: Buffer, maxHistory?: number | undefined | null): Promise<void>
+  cronEvery(name: string, intervalMs: number, actionName: string, args: Buffer, maxHistory?: number | undefined | null): Promise<void>
+  cronGet(name: string): Promise<JsCronJobInfo | null>
+  cronList(): Promise<Array<JsCronJobInfo>>
+  cronDelete(name: string): Promise<boolean>
+  cronHistory(name: string, limit?: number | undefined | null): Promise<Array<JsCronFire>>
 }
 export declare class WebSocket {
   send(data: Buffer, binary: boolean): void

package/index.js

@@ -310,13 +310,17 @@ if (!nativeBinding) {
   throw new Error(`Failed to load native binding`)
 }
 
-const { ActorContext, NapiActorFactory, CancellationToken, ConnHandle, JsNativeDatabase, Kv, Queue, QueueMessage, CoreRegistry, Schedule, WebSocket } = nativeBinding
+const { ActorContext, decodeInspectorRequest, encodeInspectorResponse, NapiActorFactory, CancellationToken, ConnHandle, JsNativeDatabase, JsSqliteTransaction, JsActorStateTransaction, Kv, Queue, QueueMessage, CoreRegistry, Schedule, WebSocket } = nativeBinding
 
 module.exports.ActorContext = ActorContext
+module.exports.decodeInspectorRequest = decodeInspectorRequest
+module.exports.encodeInspectorResponse = encodeInspectorResponse
 module.exports.NapiActorFactory = NapiActorFactory
 module.exports.CancellationToken = CancellationToken
 module.exports.ConnHandle = ConnHandle
 module.exports.JsNativeDatabase = JsNativeDatabase
+module.exports.JsSqliteTransaction = JsSqliteTransaction
+module.exports.JsActorStateTransaction = JsActorStateTransaction
 module.exports.Kv = Kv
 module.exports.Queue = Queue
 module.exports.QueueMessage = QueueMessage

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rivetkit/rivetkit-napi",
-	"version": "0.0.0-main.41efcce",
+	"version": "0.0.0-main.49693dc",
 	"description": "Native N-API addon for RivetKit providing envoy client and SQLite access",
 	"license": "Apache-2.0",
 	"main": "index.js",
@@ -39,19 +39,24 @@
 		"build": "node scripts/build.mjs",
 		"build:release": "node scripts/build.mjs --release",
 		"build:force": "node scripts/build.mjs --force",
-		"build:force:release": "node scripts/build.mjs --force --release"
+		"build:force:release": "node scripts/build.mjs --force --release",
+		"build:embed": "node scripts/build.mjs"
 	},
 	"dependencies": {
 		"@napi-rs/cli": "^2.18.4",
-		"@rivetkit/engine-envoy-protocol": "0.0.0-main.41efcce"
+		"@rivetkit/engine-envoy-protocol": "0.0.0-main.49693dc"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/rivet-dev/actors.git",
+		"directory": "rivetkit-typescript/packages/rivetkit-napi"
 	},
 	"optionalDependencies": {
-		"@rivetkit/rivetkit-napi-darwin-arm64": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-darwin-x64": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-linux-arm64-gnu": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-linux-arm64-musl": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-linux-x64-gnu": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-linux-x64-musl": "0.0.0-main.41efcce",
-		"@rivetkit/rivetkit-napi-win32-x64-msvc": "0.0.0-main.41efcce"
+		"@rivetkit/rivetkit-napi-darwin-arm64": "0.0.0-main.49693dc",
+		"@rivetkit/rivetkit-napi-darwin-x64": "0.0.0-main.49693dc",
+		"@rivetkit/rivetkit-napi-linux-arm64-gnu": "0.0.0-main.49693dc",
+		"@rivetkit/rivetkit-napi-linux-arm64-musl": "0.0.0-main.49693dc",
+		"@rivetkit/rivetkit-napi-linux-x64-gnu": "0.0.0-main.49693dc",
+		"@rivetkit/rivetkit-napi-linux-x64-musl": "0.0.0-main.49693dc"
 	}
 }

package/scripts/build.mjs

@@ -16,6 +16,14 @@ if (process.env.SKIP_NAPI_BUILD === "1") {
 	process.exit(0);
 }
 
+// The per-actor inspector UI (frontend/dist/inspector-ui, embedded into
+// rivetkit-core by its build.rs) must be built before this napi build runs.
+// It is NOT built here: rivetkit-core's embed needs rivetkit/inspector-tab,
+// which is downstream of this package in the build graph, so building it from
+// the napi build would invert the dependency order. CI builds it via
+// `turbo build:inspector-ui` in docker/build/*.Dockerfile before `napi build`;
+// for local builds run `pnpm -F @rivetkit/engine-frontend build:inspector-ui`
+// (or `turbo build:inspector-ui`) first.
 const cmd = ["build", "--platform", ...extraFlags];
 console.log(`[rivetkit-napi/build] running: napi ${cmd.join(" ")}`);
 execFileSync("napi", cmd, { stdio: "inherit" });