rivetkit-typescript 架构边界与工程规范解读:Rust 核心驱动的 Actors SDK 双运行时设计
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_found404。
也就是说,"构建成功"但 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 纪律
文档对打包边界提出了几条硬性约束,直接关系到产物体积与平台兼容性:
- 不要在任何非 workflow 入口导入
@rivetkit/workflow-engine。它只能由rivetkit/workflow入口引用,否则会破坏 tree-shaking,把整个工作流引擎拖进所有使用者的包中。对应地,package.json 为 workflow 单独声明了"./workflow"导出,与主入口平级隔离。 - SQLite 运行时只走原生
@rivetkit/rivetkit-napi路径。不允许重新引入 WebAssembly SQLite 或基于 KV 的 VFS 回退方案;import "rivetkit/db"是显式 opt-in,不能从这个入口惰性加载额外 SQLite 运行时。 - 核心驱动必须保持 SQLite 无关(SQLite-agnostic),任何 SQLite 专属接线都只能放在原生数据库提供方的边界之后。
- 删除
rivetkit/*导出前,必须先 grepexamples/、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 与数据库可靠性设计至关重要:
- 部分读写必须重建完整 4 KiB 页:SQLite 即使提交保持页级(page-based),也可能发出 sub-page 头部 I/O,所以 v2 VFS 的
xRead/xWrite回调必须能基于部分数据重建完整 4 KiB 页。 head_txid与db_size_pages是 VFS 拥有的状态:读侧get_pages(...)响应可以刷新max_delta_bytes,但只有提交响应以及本地xWrite/xTruncate路径才允许推进或收缩这两个字段——防止读路径意外改变元数据。- 构建联动:修改
packages/rivetkit-napi或packages/sqlite-native下的 Rust 代码后,必须从packages/rivetkit-napi执行pnpm build:force,让原生.node产物重新生成,否则测试到的还是旧二进制。 - 测试运行时要求:真正驱动 v2 VFS 的
sqlite-native测试(通过直接SqliteEngine)需要 multithread Tokio runtime;current_thread只适用于 mock 传输测试,否则真实引擎回调可能停滞。 - 致命错误策略:任何 sqlite v2 传输或提交错误对当前 VFS 实例都是致命的——标记 dead、通过
take_last_kv_error()暴露、依赖 reopen + takeover 恢复,绝不带着脏页继续向前走;致命提交清理集中在flush_dirty_pages与commit_atomic_write,回调包装层只负责把 fence 不匹配翻译成 SQLite I/O 返回码。 - 可观测性透传:原生 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(或对等实现)中解析查询路径时:
- 通过"任一查询参数以
rvt-开头"来识别查询路径; - 用
URLSearchParams解析查询参数; - 把参数划分为
rvt-*参数与 actor 参数两组; - 拒绝裸
@token语法、未知rvt-*参数、重复的标量rvt-*参数; - 转发给 actor 前,从查询串中剥离所有
rvt-*参数(仅用 actor 参数重建查询串); - 解析完成后,在共享的基于路径的 HTTP / WebSocket 网关辅助函数中把查询路径解析为 actor ID,再调用
proxyRequest/proxyWebSocket; - 解析后复用已有的直接 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)是原生侧事件分发的心脏,文档给出了四条关键实现纪律:
- 长生命周期任务句柄归 adapter 所有:NAPI
runhandler 这类 adapter 持有的长任务句柄放在 packages/rivetkit-napi/src/napi_actor_events.rs,只通过共享ActorContext状态暴露同步重启钩子;JS 侧重启方法不得依赖异步锁。 - 生命周期门闩单源化:不要在 packages/rivetkit-napi/src/actor_context.rs 镜像 actor 的
ready/started标志,读写都走核心ActorContext,保证 sleep 门控只有一个事实来源。 - 优雅 drain 用
while let Some(...) = tasks.join_next().await:JoinSet::shutdown()会 abort 进行中的任务,破坏 Sleep/Destroy 的顺序。源码中确实可以看到这样的循环:一边join_next()回收完成的后台任务(避免 JoinSet 在整个 actor 生命周期内持续膨胀造成原生 RSS 增长),一边在主事件上检查ctx.has_end_reason()决定是否退出。 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 dlxCLI 启动。 - 测试文件清单同步:新增 / 删除 / 重命名
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 引入 NodeBuffer依赖。 - 平台 wasm 绑定通过
setup({ wasm: { bindings, initInput } })传入,不添加隐藏的globalThis绑定钩子。 - wasm
CoreRegistry的 serverless 启动必须使用BuildingServerlesswaiter 状态;构建期间 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 行为、定位构建与运行时问题,并写出与引擎契约一致的客户端代码。