rivetkit-typescript 架构边界与工程规范解读:Rust 核心驱动的 Actors SDK 双运行时设计

原创2026-09-17 11:48:341,989 阅读
文章标签:后端云原生Serverless任务调度工作流自动化微服务

rivetkit-typescript 架构边界与工程规范解读:Rust 核心驱动的 Actors SDK 双运行时设计

本篇技术指南以仓库中 rivetkit-typescript/AGENTS.md 为骨架,系统讲解 rivetkit-typescript SDK 的模块边界、构建流程、运行时抽象、网关协议、KV 限额与生命周期语义。读者可以借此掌握该 SDK 从纯 TypeScript 迁移到 Rust 核心 + NAPI/Wasm 绑定后的内部设计约束,理解"为什么某些代码必须放在特定文件里""为什么某些接口要这样调用",从而避免踩中构建空包、运行时错位、状态泄漏等深坑。

一、构建与产物:Inspector UI 的两步嵌入流程

文档首先指出一个反直觉的构建依赖:Inspector UI 被嵌入到 @rivetkit/rivetkit-napi 与 @rivetkit/rivetkit-wasm 两个原生二进制中,嵌入动作由 rivetkit-core 的 build.rs 完成,但 Inspector UI 本身是原生包的下游产物——这形成了一个环。

解法是引入一个作用域限定的 build:embed 任务:它会在 build:inspector-ui 之后重新执行一次原生构建。仓库根执行 pnpm -w build(等价于 turbo build build:embed)即可正确完成两步构建。文档特别警告:

任何只运行 @rivetkit/rivetkit-napi#build 而没有运行 build:embed 的局部构建,都会留下一个内置 bundle 为空的 .node 文件,导致 /inspector/ui/* 返回 ui_asset_not_found 404。

也就是说,"构建成功"但 Inspector 打不开,几乎可以断定是只跑了单步构建。完整的排查上下文记录在 .claude/reference/build-troubleshooting.md 的 "Inspector UI embed empty bundle" 一节,遇到空 bundle 时优先对照该文档处理。

从包导出配置看,packages/rivetkit/package.json 使用 tsup 将 src/inspector/mod.ts、src/inspector/workflow.ts 等作为独立入口打包,Inspector 相关能力以 ./inspector、./inspector-tab 子路径对外暴露,与两步嵌入流程配合,保证 UI 资源与原生模块同时就绪。

二、运行时演进:从纯 TypeScript 到 Rust 核心 + NAPI 绑定

文档记录了一个关键的历史分界点:提交 1761e6f0f(chore: rivetkit to rust,2026-04-16)是从全 TypeScript 运行时切换到 Rust 核心 + NAPI 绑定的切割点。

这条信息的实际价值在于代码考古:当需要对比"当前行为"与"原 TypeScript 实现"的差异时——例如生命周期顺序(lifecycle ordering)、持久化布局(persistence layout)——应该检出 1761e6f0f^ 或更早的提交来对照,而不是在当前分支上猜测旧行为。

这种"核心下移、绑定上浮"的架构在源码中随处可见。例如 packages/rivetkit/src/registry/runtime.ts 定义了 RuntimeBytes = Uint8Array、RuntimeRequestSaveOpts { immediate?, maxWaitMs? } 等可移植的运行时类型,而 NAPI 专属的 Buffer 转换则被隔离在 NapiCoreRuntime 内部,确保共享胶水层(shared actor glue)不依赖 Node 专属类型。

三、模块边界与 Tree-Shaking 纪律

文档对打包边界提出了几条硬性约束,直接关系到产物体积与平台兼容性:

  1. 不要在任何非 workflow 入口导入 @rivetkit/workflow-engine。它只能由 rivetkit/workflow 入口引用,否则会破坏 tree-shaking,把整个工作流引擎拖进所有使用者的包中。对应地,package.json 为 workflow 单独声明了 "./workflow" 导出,与主入口平级隔离。
  2. SQLite 运行时只走原生 @rivetkit/rivetkit-napi 路径。不允许重新引入 WebAssembly SQLite 或基于 KV 的 VFS 回退方案;import "rivetkit/db" 是显式 opt-in,不能从这个入口惰性加载额外 SQLite 运行时。
  3. 核心驱动必须保持 SQLite 无关(SQLite-agnostic),任何 SQLite 专属接线都只能放在原生数据库提供方的边界之后。
  4. 删除 rivetkit/* 导出前,必须先 grep examples/、website/、frontend/ 中的自我导入(self-imports),这些消费方属于本分支支持的公开包面(package surface)。

这四条规则共同回答了同一个问题:为什么 SDK 能同时服务 Node、边缘平台与浏览器场景——因为平台相关的重量级依赖都被严格锁在特定导出子路径之后。

四、运行时边界:用 CoreRuntime.kind 而非 instanceof 选择行为

文档规定:运行时行为的选择必须依据 CoreRuntime.kind,而不是对 adapter 类做 instanceof 判断。NAPI 映射到 native 运行时类型,wasm 映射到 wasm 类型。这是一条面向未来的约定——当新增运行时种类时,只需要扩展 kind 枚举,而不用在每个调用点追加分支。

配套的字节契约约定包括:

  • CoreRuntime 的 SQL 方法应保持在 RuntimeSql* 可移植结构体上(见 packages/rivetkit/src/registry/runtime.ts),NAPI 专属的 Buffer 转换属于 NapiCoreRuntime;
  • RuntimeSqlBindParam 的变体必须保持精确,RuntimeSqlExecuteResult.route 只允许 read、write、writeFallback 三个值,生成适配器输出前必须规范化;
  • wasm 绑定对 NAPI 支持的运行时 API 应转发到 rivetkit-core,不能返回占位结果破坏运行时对等性(runtime parity);
  • wasm 的 registerTask 必须转发到核心的 ActorContext::register_task(...) 而不是 waitUntil,这样关闭时的 drain 语义才能与 NAPI 一致,也不会把公共 waitUntil 工作混入其中;
  • 桥接层的 HTTP 错误状态提升(status promotion)归属 rivetkit-core,TS 侧适配器只负责解码编码后的状态字段,不维护自己的提升表;
  • 使用公共 sqlite 配置选择运行时 SQLite 后端,wasm 在未配置 SQLite 时默认走 remote,并且必须在运行时构造前拒绝 local 配置。

从实现看,runtime.ts 还定义了 RuntimeStateDeltaPayload(state 快照 + connHibernation 连接休眠字节 + connHibernationRemoved 移除列表)、RuntimeInspectorSnapshot(state/connections/queue 各 revision 计数)等统一数据结构,这些结构同时被 native 与 wasm 两条路径消费,正是"运行时对等性"落地的载体。

五、Native SQLite v2:页面重建与致命错误处理

文档用一整节描述 SQLite v2 VFS 的实现红线,对理解该 SDK 的 KV 与数据库可靠性设计至关重要:

  1. 部分读写必须重建完整 4 KiB 页:SQLite 即使提交保持页级(page-based),也可能发出 sub-page 头部 I/O,所以 v2 VFS 的 xRead / xWrite 回调必须能基于部分数据重建完整 4 KiB 页。
  2. head_txid 与 db_size_pages 是 VFS 拥有的状态:读侧 get_pages(...) 响应可以刷新 max_delta_bytes,但只有提交响应以及本地 xWrite / xTruncate 路径才允许推进或收缩这两个字段——防止读路径意外改变元数据。
  3. 构建联动:修改 packages/rivetkit-napi 或 packages/sqlite-native 下的 Rust 代码后,必须从 packages/rivetkit-napi 执行 pnpm build:force,让原生 .node 产物重新生成,否则测试到的还是旧二进制。
  4. 测试运行时要求:真正驱动 v2 VFS 的 sqlite-native 测试(通过直接 SqliteEngine)需要 multithread Tokio runtime;current_thread 只适用于 mock 传输测试,否则真实引擎回调可能停滞。
  5. 致命错误策略:任何 sqlite v2 传输或提交错误对当前 VFS 实例都是致命的——标记 dead、通过 take_last_kv_error() 暴露、依赖 reopen + takeover 恢复,绝不带着脏页继续向前走;致命提交清理集中在 flush_dirty_pages 与 commit_atomic_write,回调包装层只负责把 fence 不匹配翻译成 SQLite I/O 返回码。
  6. 可观测性透传:原生 SQLite 层新增 introspection / metrics getter 时,必须通过 wrapJsNativeDatabase(...) 转发,否则 actor inspector 指标会静默丢失。

六、网关协议:GatewayTarget 与 rvt-* 查询参数

网关目标是客户端与引擎控制面的核心衔接点。文档规定使用共享的 GatewayTarget 类型(定义于 packages/rivetkit/src/engine-client/driver.ts),而不是临时拼 string | ActorQuery 联合类型:

export type GatewayTarget = { directId: string } | ActorQuery;

客户端实现(client/actor-query.ts 中的 getGatewayTarget(state))负责把 ActorResolutionState 收敛为 GatewayTarget:getForId 状态映射为 { directId },其余则保留 ActorQuery 交给网关在请求/重连时重新解析。这样高层客户端流程可以拓宽目标类型而无需复制查询解析逻辑。

6.1 查询式网关 URL 协议

基于查询参数的远端网关 URL 使用 rvt-* 前缀参数,路径形状为:

/gateway/{name}/{path}?rvt-namespace=...&rvt-method=...&rvt-key=...

其中 actor 名是干净的路径段,所有路由参数都是带 rvt- 前缀的普通查询参数。目前已知的 rvt-* 参数全集如下:

参数 语义
rvt-namespace 命名空间
rvt-method 目标方法
rvt-runner 目标 runner(getOrCreate 必需,get 禁止)
rvt-key actor key,多段 key 用单个逗号分隔参数,如 rvt-key=tenant,room
rvt-input 输入负载
rvt-region 区域选择
rvt-crash-policy 崩溃策略
rvt-token 访问令牌

构建与解析一律使用 URLSearchParams。buildGatewayUrl() 对 get() / getOrCreate() 保持查询式构造,不预解析为 actor ID;仅直接 actor ID 目标走 /gateway/{actorId}。

6.2 网关路径解析的七条铁律

在 actor-gateway/gateway.ts(或对等实现)中解析查询路径时:

  1. 通过"任一查询参数以 rvt- 开头"来识别查询路径;
  2. 用 URLSearchParams 解析查询参数;
  3. 把参数划分为 rvt-* 参数与 actor 参数两组;
  4. 拒绝裸 @token 语法、未知 rvt-* 参数、重复的标量 rvt-* 参数;
  5. 转发给 actor 前,从查询串中剥离所有 rvt-* 参数(仅用 actor 参数重建查询串);
  6. 解析完成后,在共享的基于路径的 HTTP / WebSocket 网关辅助函数中把查询路径解析为 actor ID,再调用 proxyRequest / proxyWebSocket;
  7. 解析后复用已有的直接 ID 代理流程,并保留剥离 rvt-* 参数后的剩余原始路径。

6.3 客户端侧的配套约束

  • 输入大小校验时机:在 engine-client/actor-websocket-client.ts 中,ClientConfig.maxInputSize 必须针对 base64url 编码前的原始 CBOR 字节长度校验,让限额与实际序列化负载对齐,而非编码膨胀后的 URL 长度。
  • 不要缓存解析结果:ClientRaw.get() / ClientRaw.getOrCreate() 不把已解析的 actor ID 缓存在 ActorResolutionState 上。基于 key 的 handle 与连接应每次操作都重新解析,避免在 destroy / recreate 之后仍钉在旧 actor 选择上。
  • 网关目标推导:面向网关的客户端辅助函数(packages/rivetkit/src/client 内)从 getGatewayTarget() 推导 EngineControlClient 目标,而不是提前 resolveActorId()。get() / getOrCreate() handle 必须把 ActorQuery 一路传给 sendRequest、openWebSocket、buildGatewayUrl,保证每次请求与重连都在网关处重新解析;只有 getForId() 与 create 类 handle 才收敛为纯 actor ID 目标。
  • actionId 可空语义:actor-connect 协议的 actionId 是可空的,0 是合法 action ID,只有 null 才视为连接级错误。

七、Raw KV 限额:硬性约束与失败语义

文档给出了使用原始 actor KV 时必须遵守的引擎限额,这些是硬限制:

维度 限额
单个 key 最大长度 2048 字节
单次批量写入(kv put)总负载 976 KiB(keys + values 合计)
单批最大条数(kv put) 128 对 key-value
单 actor KV 总存储 10 GiB

设计约定:若单请求可能超过上述任一限额,必须拆分为多个请求;总存储 10 GiB 是硬限制,超限时必须以显式错误 fail closed,不允许吞掉、截断或忽略 KV 写入失败。

此外文档要求:任何涉及 KV、队列、workflow 持久化、SQLite-over-KV 或相关限额的 actor 行为变更,必须同步更新 website/src/content/docs/actors/limits.mdx(对应仓库中的 docs/content/docs 文档站点)。限额条款被当成与实现变更绑定的契约来维护。

八、启动阶段日志:perf internal 与 perf user 双前缀约定

为了让启动耗时"可 grep、可区分框架与用户代码",文档规定 actor 启动的每个离散阶段必须有对应的 debug 日志,且命名约定与 ActorMetrics.startup 的 key 严格一致:

DEBUG perf internal: loadStateMs          durationMs=...
DEBUG perf internal: initQueueMs          durationMs=...
DEBUG perf user: onCreateMs               durationMs=...
DEBUG perf user: dbMigrateMs              durationMs=...
  • 框架 / 基础设施阶段用 perf internal: 前缀;
  • 用户代码回调用 perf user: 前缀;
  • 新增启动阶段时,必须补上对应前缀的日志;若该阶段运行用户代码,还要更新 ActorInstance 中的 #userStartupKeys 集合。

该约定在源码中有直接落地证据:packages/rivetkit/src/registry/native.ts 中可以看到 perf user: createStateMs、perf user: createVarsMs、perf user: onWakeMs 等日志,均以 logger().debug({ msg: ..., durationMs: performance.now() - startedAt }) 的形式输出,前后缀命名与文档完全一致。

九、NAPI 接收循环:任务回收、超时与结束原因

NAPI 接收循环(receive loop)是原生侧事件分发的心脏,文档给出了四条关键实现纪律:

  1. 长生命周期任务句柄归 adapter 所有:NAPI run handler 这类 adapter 持有的长任务句柄放在 packages/rivetkit-napi/src/napi_actor_events.rs,只通过共享 ActorContext 状态暴露同步重启钩子;JS 侧重启方法不得依赖异步锁。
  2. 生命周期门闩单源化:不要在 packages/rivetkit-napi/src/actor_context.rs 镜像 actor 的 ready / started 标志,读写都走核心 ActorContext,保证 sleep 门控只有一个事实来源。
  3. 优雅 drain 用 while let Some(...) = tasks.join_next().await:JoinSet::shutdown() 会 abort 进行中的任务,破坏 Sleep/Destroy 的顺序。源码中确实可以看到这样的循环:一边 join_next() 回收完成的后台任务(避免 JoinSet 在整个 actor 生命周期内持续膨胀造成原生 RSS 增长),一边在主事件上检查 ctx.has_end_reason() 决定是否退出。
  4. Sleep / Destroy 必须在成功和错误两条回复路径上都设置共享 adapter 的 end_reason,否则外层接收循环在关闭失败后还会继续消费排队事件。

另外两条与异步安全直接相关的纪律:带回复的 TSF 分发必须通过共享 timed-spawn 辅助函数用 with_timeout(...) 包裹回调 future(源码中 onMigrate、createState 等回调正是用 with_timeout("onMigrate", config.on_migrate_timeout, ...) 形式调度的),直接 spawn_reply(...) 可能让卡死的 JS Promise 泄漏到关闭为止;取消语义必须在 NAPI 层与 TS 层之间端到端传递 CancellationToken 对象,禁止回归 BigInt token 注册表或轮询循环。

十、Sleep 关闭语义与持久化胶水

  • Sleep 关闭的等待范围:等待进行中的 HTTP action 工作与挂起的 disconnect 回调完成后再进入 onSleep,但不阻塞在开放的休眠连接(hibernatable connections)上——因为现有连接上的 action 在优雅关闭窗口内仍可能完成。
  • 测试纪律:等待目标 actor 进入 sleep 的 driver 测试,应把生命周期事件记录到独立的 observer actor,而不是轮询目标 actor 的 action 或保持普通目标连接。
  • 持久化胶水仍在 TS 侧:本分支上原生 TS actor/连接持久化胶水还位于 packages/rivetkit/src/registry/native.ts;文档提醒 PRD 中拆分 state-manager.ts / connection-manager.ts 的引用可能已过时,除非这些模块重新出现,否则等价行为落在 registry/native.ts 中。
  • onWake 映射:公共 TS actor 的 onWake 映射到原生回调包的 onWake;onBeforeActorStart 是内部 driver/NAPI 启动钩子,不是公共 actor 配置。
  • 静态 state 必须结构化克隆:native.ts 中 actor 的静态 state 值必须按 actor 实例 structuredClone(...),直接复用字面量会让不同 keyed actor 之间泄漏变更。
  • 缓存位置:JS-only 的原生 actor 缓存应放在 ActorContext.runtimeState(),而不是以 actorId 为 key 的模块级全局;同 key 重建必须拿到全新 bag。
  • 连接休眠追踪:每条 NativeConnAdapter 构造路径都必须保留 CONN_STATE_MANAGER_SYMBOL 挂接,休眠连接变更依赖核心 ConnHandle::set_state 的 dirty 追踪来请求持久化。
  • 持久化保存:原生 actor 持久化保存必须用 ctx.requestSaveAndWait({ immediate: true }),状态字节只通过 serializeState 回调收集。
  • undefined 保真:需要在 Rust JSON/CBOR 桥上保留 JS undefined 的不透明用户负载,应走 encodeCborCompat / decodeCborCompat;结构性 JSON 信封不要用这两个辅助函数(其中省略的字段必须保持省略)。

十一、Workflow 上下文的访问守卫

文档把 workflow 上下文拆成两半(packages/rivetkit/src/workflow/context.ts),这是理解 workflow 可重放性设计的钥匙:

  • WorkflowContext:供 workflow 函数及 try / loop / race / join 回调使用,只暴露可重放原语,不暴露任何 actor 数据。actor 数据成员(state、vars、db、client、broadcast)严禁加入 WorkflowContext。
  • WorkflowStepContext:供 step / tryStep / rollback 回调使用,是唯一能触达 actor 数据与副作用的地方。

守卫机制在源码中是真实存在的:WorkflowStepContext 的 state / vars 等 getter 都会先调用 #ensureActive("state") / #ensureActive("vars"),当 step 上下文在 step 落定之后仍被捕获使用时会抛出错误;只有只读属性(如 actorId、name、key、log、abortSignal)豁免。

十二、Drizzle 兼容性测试

rivetkit/db/drizzle 公共面需要跨多个 drizzle-orm 版本验证。仓库提供了现成脚本 scripts/test-drizzle-compat.sh:

cd rivetkit-typescript/packages/rivetkit
./scripts/test-drizzle-compat.sh                   # 测试全部默认版本
./scripts/test-drizzle-compat.sh 0.44.2 0.45.1     # 测试指定版本

脚本行为:逐个安装指定 drizzle-orm 版本,针对 rivetkit/db/drizzle 公共面对 scripts/drizzle-compat-smoke.ts 做类型检查,按版本报告 pass/fail;退出时恢复原始 package.json 与 lockfile。当前 DEFAULT_VERSIONS 数组为 ("0.44" "0.45"),支持新 drizzle 版本发布时需同步更新该数组。脚本内部确实实现了备份(package.json.drizzle-compat-bak、pnpm-lock.yaml.drizzle-compat-bak)与 trap cleanup EXIT 恢复逻辑。

十三、测试基础设施与平台测试纪律

  • 共享引擎生命周期:TypeScript 测试共享的本地 rivet-engine 生命周期位于 packages/rivetkit/tests/shared-engine.ts,driver 与平台测试应复用它,而不是各自启动独立引擎。
  • 运行时对等性测试:可用 fake binding 类实例化 NapiCoreRuntime 与 WasmCoreRuntime,再通过 buildNativeFactory(...) 驱动共享 actor 胶水——这样不需要生成真实的 NAPI / wasm 产物。
  • 平台 wasm 冒烟测试:复用 packages/rivetkit/tests/platforms/shared-registry.ts 中的 raw-SQL SQLite 计数器 actor 与公共 wasm setup(...) 形态。
  • 平台冒烟测试基础设施:tests/platforms/shared-platform-harness.ts 负责 serverless runner 的启动、app 进程日志、临时 app 目录、健康检查以及固定的 pnpm dlx CLI 启动。
  • 测试文件清单同步:新增 / 删除 / 重命名 packages/rivetkit/tests/driver/*.test.ts(使用 describeDriverMatrix 的)时,必须同步更新 .claude/skills/driver-test-runner/SKILL.md 中的 Fast/Slow/Excluded 测试列表与套件描述表。

十四、平台兼容:Cloudflare Workers 与 Wasm 绑定约束

14.1 Cloudflare Workers:构造器不得在全局作用域做异步 I/O

Cloudflare Workers 禁止在全局作用域(request handler 之外)使用 setTimeout、fetch、connect 等异步 I/O。而 Registry 构造函数运行在全局作用域,因此绝不能无条件调用这些 API。任何延迟工作(例如预启动运行时)都必须先通过同步配置检查,再调度 timer。参考实现见 packages/rivetkit/src/registry/index.ts:外层 if 守卫 setTimeout 的注册,内层 if 在 tick 之后复查,以拾取迟到的配置变更。

14.2 Wasm 绑定包的纪律

  • packages/rivetkit-wasm/pkg/ 是 wasm-pack 输出目录:提交源码与构建脚本,包构建时再重新生成产物。
  • wasm raw WebSocket handle 导出为 WebSocketHandle 而非 WebSocket——wasm-bindgen 会拒绝遮蔽宿主全局类的类名。
  • wasm 运行时适配器的字节归一化保持在 Uint8Array 上,不得给 packages/rivetkit/src/registry/wasm-runtime.ts 引入 Node Buffer 依赖。
  • 平台 wasm 绑定通过 setup({ wasm: { bindings, initInput } }) 传入,不添加隐藏的 globalThis 绑定钩子。
  • wasm CoreRegistry 的 serverless 启动必须使用 BuildingServerless waiter 状态;构建期间 shutdown 必须唤醒 waiters 并 drain 新建的运行时。
  • 在转换为核心 ServeConfig 或启动 registry 副作用前,先校验 wasm-only serve 配置约束。
  • wasm 包导出或文件变更后,运行 pnpm --filter @rivetkit/rivetkit-wasm run check:package 验证发布 tarball 包含根入口与 wasm 产物。
  • wasm 构建使用包内固定的 wasm-pack 依赖,禁止 npx -y wasm-pack。
  • wasm 桥接的 RivetErrorSchema 只按 (group, code) 内部化;动态错误信息必须留在 RivetError.message,不能膨胀 schema 缓存 key。
  • wasm websocket 回调区域(callback region)用按活跃 region ID 的 map 追踪并在结束时移除条目,防止重复回调残留空槽;region ID 0 是"未追踪"哨兵,u32 分配通过跳过活跃 ID 来避免 panic。

十五、文档同步约定:Context 类型与内部架构文档

最后是两条防止文档漂移的约定:

  • Context 类型三处同步:*ContextOf 类型从 packages/rivetkit/src/actor/contexts/index.ts 导出并由 packages/rivetkit/src/actor/mod.ts 再导出;增删改 context 类型时必须同步更新 website/src/content/docs/actors/types.mdx(公开文档页)与 website/src/content/docs/actors/index.mdx(crash course 的 Context Types 一节)。
  • 动态 actor 架构文档:涉及动态 actor 行为、桥接契约、isolate 生命周期或运行时沙箱接线时,先参考 docs-internal/rivetkit-typescript/DYNAMIC_ACTORS_ARCHITECTURE.md;任何动态 actor 架构、生命周期、桥接负载、安全行为或临时兼容路径的变更,都必须在同一变更中更新该文档。

总结

rivetkit-typescript 的这份工程规范看似只是给 AI 代理与维护者的工作守则,实则浓缩了该 SDK 最核心的架构决策:Rust 核心统一语义、NAPI 与 Wasm 双运行时对等、SQLite v2 的可恢复性设计、查询式网关协议的参数契约、KV 硬限额,以及 workflow 可重放性驱动的上下文守卫。理解这些边界,无论是在 Node、边缘平台还是 Cloudflare Workers 上构建 stateful actor,都能更准确地预判 SDK 行为、定位构建与运行时问题,并写出与引擎契约一致的客户端代码。

登录后查看全文
rivet