RivetKit Rust 运行时边界指南:从 NAPI 到 wasm 的适配层设计规范
RivetKit Rust 运行时边界指南:从 NAPI 到 wasm 的适配层设计规范
RivetKit 的 Rust 核心(rivetkit-core)需要同时服务 Node/Deno/Bun 的 NAPI(原生)宿主与浏览器/边缘环境的 wasm 宿主,本文以仓库内 rivetkit-rust/CLAUDE.md 中定义的"RivetKit Runtime Boundary"五条规则为主线,结合 rivetkit-core、rivetkit-typescript 的实际源码,系统讲解字节边界、SQL 边界、wasm SQLite 约束、Serverless 注册表生命周期与运行时判别器的设计取舍。读完本文,你将掌握跨运行时适配层必须遵守的边界规范,并能在仓库中定位每条规则对应的实现与测试证据。
一、规则全景:五条运行时边界约束
rivetkit-rust/CLAUDE.md 用五条精炼规则划定了 RivetKit 运行时边界(Runtime Boundary)的不可逾越范围:
| # | 规则 | 核心约束 |
|---|---|---|
| 1 | 字节边界 | 运行时中立数据一律保持 Uint8Array/Vec<u8> 形态;Buffer 转换只允许出现在 TypeScript NAPI 适配层 |
| 2 | SQL 边界 | SQL 边界类型必须显式声明并在 native/wasm 两个适配器间共享,不得从 NAPI 专属数据库封装反推运行时 API 契约 |
| 3 | wasm SQLite | wasm 构建只支持远程 SQLite(remote-only),不得引入或暗示本地 SQLite 支持 |
| 4 | 生命周期对齐 | NAPI 与 wasm 的 Serverless 注册表生命周期语义必须保持一致,包括并发首次请求构建(concurrent first-request build)与构建期间关停(shutdown-during-build)行为 |
| 5 | 运行时判别 | 运行时选择应使用显式判别器(如 runtime.kind),而非具体适配器类的身份判断 |
这五条规则不是孤立的开发提示,而是仓库中多组 feature flag、类型设计与生命周期代码的直接约束。下面逐一结合源码展开。
二、字节边界:让 Uint8Array / Vec<u8> 成为运行时中立语言
第一条规则要求:凡是跨越运行时边界的数据,必须以 Uint8Array/Vec<u8> 形态传递;Node 特有的 Buffer 转换只允许存在于 TypeScript NAPI 适配代码中。
这样设计的原因很直接:wasm 宿主(浏览器、边缘运行时)根本没有 Node 的 Buffer 全局对象,如果核心契约里混入 Buffer,wasm 适配层就无法复用同一套协议编解码。仓库中的协议层实现印证了这一点——例如 client/src/protocol/codec.rs、client/src/protocol/to_client.rs 以及 client-protocol/src/versioned.rs 都直接以 Vec<u8> 作为线上数据形态。
在 TypeScript 侧,核心运行时接口使用 RuntimeBytes 抽象字节,见 rivetkit-typescript/packages/rivetkit/src/registry/runtime.ts 的 CoreRuntime 接口以及 RuntimeServerlessStreamEvent 中的 chunk?: RuntimeBytes 定义。真正出现 Buffer 的地方是 NAPI 专属的数据库封装 native-database.ts,其 NativeBindParam 的 blob 类型标注为 blobValue: Buffer——这正是"Buffer 转换只属于 NAPI 适配层"的实例:
// rivetkit-typescript/packages/rivetkit/src/common/database/native-database.ts
type NativeBindParam =
| ({ kind: "null" } & NativeBindNoValues)
| { kind: "int"; intValue: number; /* ... */ }
| { kind: "float"; floatValue: number; /* ... */ }
| { kind: "text"; textValue: string; /* ... */ }
| { kind: "blob"; blobValue: Buffer }; // ← Buffer 仅存在于 NAPI 适配层
三、SQL 边界:显式、共享的跨适配器类型
第二条规则要求:SQL 边界类型要显式声明并在 native 与 wasm 适配器间共享,禁止从 NAPI 专属数据库包装器反推运行时 API 契约。
Rust 侧的实现位于 rivetkit-core/src/actor/sqlite/mod.rs,它从 depot-client-types 直接重导出统一的 SQL 参数与结果类型,供整个核心层使用:
// rivetkit-rust/packages/rivetkit-core/src/actor/sqlite/mod.rs
pub use depot_client_types::{BindParam, ColumnValue, ExecResult, ExecuteResult, QueryResult};
这些显式共享类型(BindParam、ColumnValue、ExecuteResult、QueryResult 等)是 native 与 wasm 两条 SQL 路径的公共语言:无论底层走本地 VFS 还是远程 envoy 传输,SQL 语句的绑定参数和查询结果都先用这套显式类型建模。与之对照,TypeScript 侧的 NativeBindParam 只是在 NAPI 边界上的适配视图,绝不能让 SQL 运行时契约反过来依赖它——这正是规则"不要从 NAPI-only 数据库封装反推运行时 API 契约"的含义。
四、Wasm SQLite:只允许远程(remote-only)
第三条规则最为严格:wasm 构建下 SQLite 只支持远程访问,不得新增或暗示本地 SQLite。理由在于 wasm 沙箱没有真正的本地文件系统与线程模型,无法承载 SQLite 本地 VFS。
这一约束在 rivetkit-core/Cargo.toml 的 feature 设计中体现得非常清楚:
[features]
default = ["native-runtime"]
native-runtime = [ /* ... */ "rivet-envoy-client/native-transport" ]
wasm-runtime = ["rivet-envoy-client/wasm-transport"]
sqlite = ["sqlite-local"]
sqlite-local = ["native-runtime", "dep:depot-client", "dep:rivet-actor-runtime-socket-protocol"]
sqlite-remote = []
关键点:sqlite-local 强制依赖 native-runtime,而 wasm-runtime 只启用 envoy 的 wasm 传输层。也就是说,wasm 构建无论怎么组合 feature 都无法开启本地 SQLite。源码侧同样以 cfg(feature = "sqlite-local") 门控本地后端,sqlite/mod.rs 中的 SqliteBackend 枚举只有两种取值:
pub enum SqliteBackend {
LocalNative, // 仅 native-runtime + sqlite-local 可用
RemoteEnvoy, // wasm 唯一可用的路径
}
而 exec_backend_profiled 在匹配 SqliteBackend::LocalNative 时调用 local_exec_profiled(本地 VFS 执行),RemoteEnvoy 时走 remote_exec(经 envoy 转发到远端 SQLite),wasm 构建编译时本地分支根本不会存在。因此,在 wasm 文档与 API 面中只能出现远程 SQLite,任何"wasm 支持本地数据库"的说法都与本仓库实现相悖。
五、Serverless 注册表生命周期:NAPI 与 wasm 语义对齐
第四条规则要求 NAPI 与 wasm 的 Serverless 注册表在生命周期语义上保持一致,重点点名两个行为:并发首次请求构建(多个请求同时到达、只应构建一次 envoy)与构建期间关停(shutdown 与正在进行的首次构建并发时必须正确收敛)。
核心实现是 rivetkit-core/src/serverless.rs 中的 CoreServerlessRuntime:
- 懒启动与缓存:
handle_request首次到来时通过ensure_envoy(...)启动 envoy 并缓存,后续请求复用(cache_envoy配置开关控制是否缓存),见 serverless.rs; - 构建期间关停的竞态处理:
ensure_envoy在start_envoy之后会在锁内二次检查shutting_down标志,若关停已发生,则立即拆除刚建好的 envoy 而不是把它安装进缓存——源码注释明确提到这是为了避免"shutdown-during-build 竞态把死句柄缓存进进程级GLOBAL_ENVOY",因此start_envoy以not_global: true启动,见 serverless.rs; - 有界排空:
shutdown()使用SHUTDOWN_DRAIN_TIMEOUT(20 秒)等待 envoy 排空,超时后降级为立即Stop,避免引擎不可达时无限挂起,见 serverless.rs; - 逐请求取消:每个 Serverless 请求携带独立
CancellationToken,只取消单个 in-flight 请求,不会连带拆除缓存的 envoy——这与CoreRegistry层面的整体shutdown()是两个不同粒度的关停通道。
TypeScript 侧通过 CoreRuntime 接口(createRegistry、serveRegistry、handleServerlessRequest、shutdownRegistry 等)为两种宿主提供同一套生命周期契约,见 runtime.ts。rivetkit-core 的 CLAUDE.md 进一步补充了关停策略的宿主归属:库代码不得安装进程信号处理器(tokio::signal::ctrl_c() 会在 POSIX 层调用 sigaction(SIGINT, ...),导致以 NAPI 嵌入时 Node 无法正常退出),信号策略必须归属宿主二进制或 TS registry 层。
六、运行时判别:用 runtime.kind,而不是适配器类身份
第五条规则要求运行时选择必须走显式判别器。TypeScript 侧的判别器是 runtime.kind:
- 配置层定义
RuntimeKindSchema = z.enum(<a href="https://link.gitcode.com/i/81c20dd7af451699b30c6e8103619b15" target="_blank">"auto", "native", "wasm"]),见 [registry/config/index.ts,auto会通过resolveRuntimeKind在运行时解析为具体类型; CoreRuntime接口声明readonly kind: "napi" | "wasm"作为运行时身份,见 runtime.ts;- 实际分发点(如 registry/native.ts)使用
switch (runtime.kind)进行行为分支,而不是instanceof判断适配器类。
Rust 侧的同类设计体现在 rivetkit-core/src/runtime.rs 中:RuntimeBoxFuture、RuntimeFuture、RuntimeFutureOutput 等 trait 依据 feature 编译出不同的约束——native-runtime 下 future 要求 Send,而 wasm-runtime 下放宽为 'static,RuntimeSpawner::spawn 在 wasm 下走 tokio::task::spawn_local(见 runtime.rs)。这同样是"以显式 feature/判别器驱动适配"而非"按具体类身份推断"的体现。
选择显式判别器而非类身份判断的意义在于:行为分支只依赖契约化的 kind 字段,未来新增宿主(如其它原生嵌入环境)时无需改动既有分发逻辑,也避免把适配器内部实现细节泄露成运行时 API 的一部分。
七、如何在仓库中验证与践行这些边界规则
如果你要在 RivetKit 上开发或审查跨运行时代码,可以按以下清单核对:
- 字节数据:跨运行时函数签名是否只出现
Uint8Array/Vec<u8>?Buffer是否只出现在 NAPI 专属文件(如 native-database.ts)? - SQL 类型:SQL 参数/结果类型是否来自 sqlite/mod.rs 重导出的
depot_client_types显式类型? - wasm SQLite:新增 SQLite 能力时,是否确保 wasm feature 组合下只存在
RemoteEnvoy路径?sqlite-local是否仍被native-runtime强制约束? - Serverless 生命周期:首次请求的并发构建与
shutting_down二次检查是否保留?shutdown 是否统一收敛到CoreRegistry::shutdown()/CoreServerlessRuntime::shutdown()而不是挂在配置参数上? - 运行时分发:分支判断是否基于
runtime.kind(或 Rust 侧的 feature 判别)而非具体类/类型身份?
相关的单元与集成测试同样值得阅读:runtime.test.ts 直接以 { kind: "wasm" } 与 { kind: "napi" } 构造运行时对象验证判别逻辑;rivetkit-core/src/runtime.rs 内含 wasm 运行时下 spawn_local future 的编译期测试;而 rivetkit-core/tests 目录下的集成测试(含 sqlite、sleep、registry_http、serverless 等)则覆盖了生命周期与 SQL 边界的实际行为。
结语
rivetkit-rust/CLAUDE.md 的五条运行时边界规则,本质上是为"一份 Rust 核心、两种宿主(NAPI 原生 / wasm 沙箱)"这一架构收敛出的最小不可违背约束:字节数据中立、SQL 类型显式共享、wasm SQLite 仅远程、Serverless 生命周期语义对齐、运行时选择使用显式判别器。理解这些规则及其在 rivetkit-core 与 rivetkit-typescript 中的落地方式,是正确扩展 RivetKit 跨运行时能力的起点。