RivetKit Rust 运行时边界指南:从 NAPI 到 wasm 的适配层设计规范

原创2026-09-17 20:30:171,722 阅读
文章标签:后端云原生Serverless任务调度工作流自动化微服务

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 上开发或审查跨运行时代码,可以按以下清单核对:

  1. 字节数据:跨运行时函数签名是否只出现 Uint8Array/Vec<u8>?Buffer 是否只出现在 NAPI 专属文件(如 native-database.ts)?
  2. SQL 类型:SQL 参数/结果类型是否来自 sqlite/mod.rs 重导出的 depot_client_types 显式类型?
  3. wasm SQLite:新增 SQLite 能力时,是否确保 wasm feature 组合下只存在 RemoteEnvoy 路径?sqlite-local 是否仍被 native-runtime 强制约束?
  4. Serverless 生命周期:首次请求的并发构建与 shutting_down 二次检查是否保留?shutdown 是否统一收敛到 CoreRegistry::shutdown() / CoreServerlessRuntime::shutdown() 而不是挂在配置参数上?
  5. 运行时分发:分支判断是否基于 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 跨运行时能力的起点。

登录后查看全文
rivet