WASI 0.3.0 规范全解析:基于 Component Model 与 async/future/stream 的下一代 WebAssembly 系统接口
WASI 0.3.0 规范全解析:基于 Component Model 与 async/future/stream 的下一代 WebAssembly 系统接口
WASI 0.3.0(Preview 3)是 WebAssembly System Interface 的最新一代规范版本,它彻底转向 WebAssembly Component Model,用原生的 async、future 与 stream 类型取代了 0.2 时代显式的 streams 与 polling 接口。本文以 specifications/wasi-0.3.0/Overview.md 为骨架,结合本仓库中六个提案的 WIT 源码与配套文档,完整解读 0.3.0 的版本定位、提案清单、实现门槛(gated features)以及各核心 API 的实际接口形态,帮助你理解并开始使用这套新一代 WASI 规范。
一、版本定位:从 Preview 1 到 Preview 3 的演进脉络
WASI 0.3.0 规范基于 WebAssembly Component Model):
- Preview 1(WASI 0.1):使用 witx IDL 定义,深受 POSIX 与 CloudABI 影响,已得到广泛使用;
- WASI 0.2(Preview 2):改用 Wit IDL,定义为一组模块化 API 集合,支持更广泛的语言、更强的类型系统与虚拟化能力;
- WASI 0.3(Preview 3):当前预览版本,在 0.2 基础上用 Component Model 原生的、可组合的
async功能(通过future与stream类型)替换了此前显式的 streams 与 polling 接口。
换言之,0.3.0 不再需要 WASI 自己维护一套独立的流与轮询抽象,而是直接复用 Component Model 的异步类型系统,这也正是下文 "Component Model features" 一节把 async、future、stream 列为实现前提的根本原因。
二、0.3.0 包含的六个提案(Proposals)
本版本规范收录了六个处于标准化进程中的提案,它们的 WIT(WebAssembly Interface Type)定义均以 Wasm OCI Artifact 布局 推送到 OCI 注册表(依据 Overview.md)。在本仓库中,每个提案的完整 WIT 源码、设计文档与测试套件分别位于 proposals/ 目录下:
| 提案包名 | 版本 | 仓库目录 | 核心能力 |
|---|---|---|---|
wasi:random |
0.3.0 | proposals/random | 加密安全随机数与不安全伪随机数 |
wasi:clocks |
0.3.0 | proposals/clocks | 单调时钟、系统时钟与时区 |
wasi:sockets |
0.3.0 | proposals/sockets | TCP/UDP 套接字与域名解析 |
wasi:filesystem |
0.3.0 | proposals/filesystem | 基于 descriptor 的文件系统访问 |
wasi:cli |
0.3.0 | proposals/cli | 命令行程序世界(command world) |
wasi:http |
0.3.0 | proposals/http | HTTP 服务端 / 中间件世界与客户端 |
根据 docs/Proposals.md,一个提案要纳入 WASI 0.3 必须同时满足三个条件:达到 WASI Subgroup 阶段流程 中的 Phase 3(实现阶段)、满足自身的可移植性标准、并由 WASI Subgroup 投票通过。目前上述六项均处于 Phase 3,而时区(Timezone)、HTTP Informational Outbound Response、Key-value Store、WebGPU 等更多提案则处于 Phase 2 及以下阶段,尚未进入 0.3 版本。
三、Component Model features:实现 0.3.0 的硬性门槛
这是 Overview.md 的核心内容之一。WASI API 以 Component Model 为基础定义,而 Component Model 的新语法、新类型与 canonical ABI 功能是在 gated features(门控特性)之后开发的。WASI 0.3.0 明确要求:
实现本版本规范,需要默认(非门控)的 Component Model 功能,加上 WASI Subgroup 截至本版本已采用的门控功能。
0.3.0 采用的 gated feature 只有一项(原文表格):
| Gate | Feature | Adopted in |
|---|---|---|
| 🔀 | async、future 和 stream |
0.3.0 |
结合 docs/ComponentModelFeatures.md 可得到更完整的视角:
| WASI 版本 | Gate | Feature | 采用方式 |
|---|---|---|---|
| 0.2.0 | — | 默认(非门控)的 Component Model 功能 | WASI 0.2 投票(早于此流程) |
| 0.3.0 | 🔀 | async lift/lower、future 和 stream |
WASI 0.3 投票 |
| 0.3.1 | 🗺️ | map<K, V> 类型 |
2026-08-06 子组会议 |
| 0.3.1 | 🏷️ | 普通命名接口导入/导出上的 implements 与 external-id 注解 |
2026-08-06 子组会议 |
关于这门控机制,有几条关键语义值得特别注意(依据 docs/ComponentModelFeatures.md):
- 采用是累积的:实现某个 WASI 版本,需要默认功能 + 该版本及其所有更早版本采用的全部 gated feature。因此 0.3.1 的实现者除了
async/future/stream,还必须支持map类型与implements/external-id注解。 - 采用 ≠ API 必须使用:某版本采用某项特性,只意味着该版本及之后的 WASI API 可以使用它;但运行时与工具链无论是否实际用到,都必须实现该特性。
- 未采用的特性受限:WASI 提案只能在预发布版本(如
0.3.0-rc-*)中实验未采用的门控特性,稳定版本必须保持在不依赖它们的前提下可实现。 - CI 强制执行:每个变更的提案都会被编码为组件,并使用上述表格中的特性集做校验,一旦依赖了未采用的特性即校验失败。这正是本仓库中 CONTRIBUTING.md 所描述的"采用 Component Model 特性"流程的落地保障。
对照本仓库中 specifications/wasi-0.3.1/Overview.md 可以看到,0.3.1 的规范表正是 0.3.0 表格的扩展——这直观演示了 0.3.x 系列如何在累积式门控机制下演进。
四、从 WIT 到 OCI:规范的发布与分发方式
Overview.md 指出,本版本所含提案的 WIT 定义按 Wasm OCI Artifact 布局 推送到 OCI。这意味着:
- 规范不再仅以 Markdown 形式分发,WIT 定义作为 OCI artifact 可以像镜像一样被拉取、签名、复用;
- 每个包使用语义化版本(semver)标识,例如
wasi:random@0.3.0,版本号直接嵌入 WIT 文件的package声明中。
本仓库的 wit 源码反映了这一版本化体系。以 proposals/cli/wit/imports.wit 为例,文件头声明 package wasi:cli@0.3.1;,且每个接口、函数都用 @since(version = 0.3.0) 标注引入版本——这是稳定的 WASI API 只能依赖已采用 gated feature 的配套机制(依据 docs/ComponentModelFeatures.md)。当前仓库中六个提案的 wit 文件已演进到 0.3.1 版本系列(0.3.x),与 Overview.md 所记录的 0.3.0 版本一脉相承。
提案间的依赖通过 deps.toml 管理。例如 proposals/cli/wit/deps.toml 声明了 clocks、sockets、random、filesystem 四个依赖目录,配合 deps.lock 锁住版本;proposals/cli/wit/imports.wit 中 include wasi:clocks/imports@0.3.1 这样的语句则显式引用了其它包的 world 与版本。这就是 docs/WitInWasi.md 所描述的跨包类型复用约定(use 声明 + 顶层 wit/deps 目录存放被依赖 wit 文件的快照)。
五、六大提案的 API 形态深度解读
本节逐一结合仓库 WIT 源码,说明 0.3.0 核心 API 的接口形态——这是理解"async/future/stream 如何落地"的最佳入口。
5.1 wasi:cli —— command world 与基于流的 stdio
wasi:cli 定义了命令行程序的 world。从 proposals/cli/wit/command.wit 可以看到 command world 的结构:
package wasi:cli@0.3.1;
@since(version = 0.3.0)
world command {
@since(version = 0.3.0)
include imports;
@since(version = 0.3.0)
export run;
}
即:一个 command 组件导入环境变量、退出、stdin/stdout/stderr、终端等接口(由 imports.wit 汇总 clocks/filesystem/sockets/random 四个子系统的 imports 并追加 CLI 专属接口),同时导出唯一的 run 入口函数。值得注意的是 run 是异步的:
@since(version = 0.3.0)
interface run {
/// Run the program.
@since(version = 0.3.0)
run: async func() -> result;
}
stdio 的形态最能体现 0.3.0 的流式设计(见 proposals/cli/wit/stdio.wit):
@since(version = 0.3.0)
interface stdin {
use types.{error-code};
@since(version = 0.3.0)
read-via-stream: func() -> tuple<stream<u8>, future<result<_, error-code>>>;
}
@since(version = 0.3.0)
interface stdout {
use types.{error-code};
@since(version = 0.3.0)
write-via-stream: func(data: stream<u8>) -> future<result<_, error-code>>;
}
stdin.read-via-stream 返回一个 stream<u8>(字节流)加一个 future<result<_, error-code>>(错误信号);stdout/stderr.write-via-stream 接收一个 stream<u8> 并返回 future 报告写入结果。错误码枚举只有三个:io(输入/输出错误)、illegal-byte-sequence(非法或不完整的多字节/宽字符)、pipe(管道断裂)。对照 proposals/cli/README.md 的设计讨论可知:stdout/stderr 之所以没有做成"永不失败的单函数接口",是为了保持与 stdin 的一致性,同时把更大的简化空间留给更专门的 world(如云/边缘场景)。
CLI 的其它导入接口还包括(proposals/cli/wit/environment.wit、proposals/cli/wit/exit.wit):
get-environment: func() -> list<tuple<string, string>>:POSIX 风格环境变量;其注释明确说明"道德上是 value import",在 value imports 就绪前要求每次调用返回相同值;get-arguments: func() -> list<string>:命令行参数;get-initial-cwd: func() -> option<string>:初始工作目录(.表示它本身);exit: func(status: result)与exit-with-code: func(status-code: u8):退出当前实例及所有链接实例;后者不返回,效果类似 trap 但不带有"出了坏事"的含义。
5.2 wasi:random —— 加密安全随机与不安全随机
wasi:random 的 random 接口(proposals/random/wit/random.wit)提供两个函数:
get-random-bytes: func(max-len: u64) -> list<u8>;
get-random-u64: func() -> u64;
其语义约束非常严格(WIT 注释原文要点):
- 数据必须至少达到"充分播种的 CSPRNG"级别的加密安全性,且必须始终不可预测;
- 任何情况下都不得阻塞,包括首次调用与任意字节数请求;
- 允许"短读"(返回少于请求的字节数),需要精确
max-len字节的调用方必须循环调用直至凑齐;max-len大于 0 时至少返回 1 字节,等于 0 时必须返回空列表且不 trap; - 必须始终返回新数据:确定性环境必须省略此函数,而不是用确定性数据实现它。
wasi:random 还定义了配套的 insecure 接口(proposals/random/wit/insecure.wit),提供 get-insecure-random-bytes 与 get-insecure-random-u64,用于不需要加密安全性的场景(如模拟、测试),注释明确警告"不要用于任何与安全相关的事"。world 层面(proposals/random/wit/world.wit)同时导入 random、insecure 与 insecure-seed 三个接口,由宿主决定授予哪些能力。
5.3 wasi:clocks —— 单调时钟与系统时钟
monotonic-clock 接口(proposals/clocks/wit/monotonic-clock.wit)用于测量流逝时间:
type mark = u64:自某个未指定初始值以来的纳秒数,只能与同一时钟实例产生的 mark 比较;now: func() -> mark:读取当前值,重复调用产生非递减序列;如果值无法用mark表示则 trap,因此实现应保证起始时间足够低以避免溢出;get-resolution: func() -> duration:查询时钟分辨率;wait-until: async func(when: mark)与wait-for: async func(how-long: duration):异步等待——这正是 0.3.0 用 Component Modelasync取代旧轮询接口的直接证据,在 0.2 中这类等待需要显式的 pollable 机制。
system-clock 接口(proposals/clocks/wit/system-clock.wit)用于向人类报告当前日期时间:
record instant { seconds: s64, nanoseconds: u32 }:以 1970-01-01T00:00:00Z(POSIX epoch / Unix Time)为参考点;即使秒为负数,纳秒递增也始终代表时间向前(如{-1 秒, 999999999 纳秒}表示 epoch 前一纳秒);纳秒字段恒小于 1,000,000,000;now: func() -> instant与get-resolution: func() -> duration。
另外 wasi:clocks 还包含 timezone 接口(iana-id、utc-offset、to-debug-string),但注意它在 world 中以 @unstable(feature = clocks-timezone) 标注(proposals/clocks/wit/world.wit),即属于不稳定特性,不构成 0.3.0 稳定规范的组成部分。
5.4 wasi:filesystem —— descriptor 资源与路径沙箱
wasi:filesystem(proposals/filesystem/wit/types.wit)以 descriptor 资源为核心,模块头部注释明确了关键约定:
- 目录分隔符始终是
/; - 所有路径都是相对路径,相对于指向基准目录的
descriptor解释;任何路径以/开头、解析过程中(含..与符号链接步骤)越出基准目录、或触及底层文件系统中绝对/根路径的符号链接,都会以error-code::not-permitted失败; - API 以 POSIX 为模型,但优先兼容性而非可移植性(路径可能大小写折叠、删除文件可能因其它打开的描述符失败、并发写者的持久性与原子性因平台而异);需要精确定义可移植语义的用户应改用 key-value 存储或数据库。
类型体系包括 descriptor-type(此前版本叫 filetype)、descriptor-flags(此前叫 fdflags,含 read、write、file-integrity-sync(类似 O_SYNC)、data-integrity-sync(类似 O_DSYNC)、requested-write-sync(类似 O_RSYNC)、mutate-directory)、path-flags(symlink-follow)、open-flags(create/directory/exclusive/truncate,对应 POSIX 的 O_CREAT/O_DIRECTORY/O_EXCL/O_TRUNC)等。descriptor 的方法同样全面流式化,例如 [method]descriptor.read-via-stream(类似 pread)、[method]descriptor.write-via-stream(类似 pwrite,允许越界写入并零填充间隔字节)、[method]descriptor.append-via-stream(类似 write + O_APPEND)、read-directory 返回 stream<directory-entry> 等。宿主预打开的目录通过 preopens 接口暴露:
@since(version = 0.3.0)
interface preopens {
use types.{descriptor};
/// Return the set of preopened directories, and their paths.
@since(version = 0.3.0)
get-directories: func() -> list<tuple<descriptor, string>>;
}
更详细的路径解析与沙箱语义可参考 proposals/filesystem/path-resolution.md。
5.5 wasi:sockets —— 套接字资源与域名解析
wasi:sockets(proposals/sockets/wit/types.wit)定义了 tcp-socket、udp-socket 等资源类型与详尽的 error-code 变体(每个错误码都标注了 POSIX 等价项,如 access-denied ↔ EACCES/EPERM、connection-refused ↔ ECONNREFUSED、remote-unreachable ↔ EHOSTUNREACH 等)。tcp-socket 的状态机(unbound → bound → listening/connecting/connected → closed)与共享所有权语义在 WIT 注释与 proposals/sockets/TcpSocketOperationalSemantics.md 中有完整描述;其设计还明确"WASI 套接字没有 POSIX 式 O_NONBLOCK 标志,完全依赖 Component Model 的 async 支持"(proposals/sockets/wit/types.wit 第 182-184 行注释)。IPv4/IPv6 地址族、ip-socket-address 记录等基础类型也在同一文件中定义。
域名解析接口 ip-name-lookup(proposals/sockets/wit/ip-name-lookup.wit)同样体现了异步设计:
resolve-addresses: async func(name: string) -> result<list<ip-address>, error-code>;
其语义包括:Unicode 域名自动经 IDNA 编码转为 ASCII;若输入本身是 IP 地址字符串则直接解析返回、不发起任何外部请求;结果按连接优先级顺序返回;绝不返回 IPv4-mapped IPv6 地址;成功时至少返回一个地址。wasi:sockets 的 world(proposals/sockets/wit/world.wit)导入 types 与 ip-name-lookup 两个接口。
5.6 wasi:http —— service 与 middleware 世界
wasi:http(proposals/http/wit/worlds.wit)定义了 HTTP 请求/响应的类型与方法(method、scheme、庞大的 error-code 变体等,见 proposals/http/wit/types.wit),以及两个世界:
wasi:http/service:涵盖网页应用、API 服务器与代理等广泛 HTTP 服务;它 include clocks/random 的 imports,导入wasi:cli/stdout、stderr(以及一个临时的stdin兼容项),导入client,并导出handler。宿主通过调用组件导出的handle函数投递入站请求;组件必须能处理 0..N 次handle调用,且宿主可能并发复用实例(组件可通过 Component Model 的背压机制退出并发复用)。wasi:http/middleware:includeservice并额外导入handler,使请求能沿处理器链流转(下游/上游两个方向的 handler 分别对应导出与导入),中间件链直接建立在 Component Model 链接之上。
handler 与 client 的签名都呈现典型 0.3.0 异步形态:
handle: async func(request: request) -> result<response, error-code>;
send: async func(request: request) -> result<response, error-code>;
根据 proposals/http/README.md,client.send 与 handler.handle 的签名相同是因为当前工具链无法表达"导入同一接口的两个实例";client.send 导入可以直接链接到另一个组件的 handler.handle 导出以绕过网络。该 README 还给出了生成绑定的示例命令:
wit-bindgen c wit/ --world service
以及用 wasm-tools component wit 校验/操作 WIT 的用法——这是从本仓库 WIT 源码生成实际代码的标准路径。
六、0.3.0 的能力模型:link-time 与 runtime capabilities
Overview.md 虽未展开,但 WASI 规范的能力模型是理解其 API 设计的底层框架。依据 docs/Capabilities.md,WASI 有两种主要能力:
- 链接期能力(link-time capabilities):本质上是可以导入的、做事的函数;因"满足导入的导出在链接时被选定"而得名。严格地说,它们属于 Component Model 的 instance imports——请求一个已实例化的实例,该实例自身又带着在它自己链接期被授予的能力,因此也被称为"实例化期能力"。若想虚拟化或衰减这些能力,可在链接期改用一个提供所需导出的组件顶替。
- 运行时能力(runtime capabilities):可四处传递、授予资源访问权的 handles(句柄)。handles 是一等公民(可在运行时任意流动)且不可伪造(只能传递对单个资源的访问权,不会暴露其它资源)。在无法直接操作不可伪造引用的语言中,handles 常以"每组件实例表"中的
i32索引形式暴露。
选择原则:需要同时存在多个可动态区分的资源时(如同时打开多个文件)用运行时能力;多数场景只有一个资源(如时钟的"获取时间")时,链接期能力更便利。0.3.0 的 API 正是按此原则混合使用两种能力——文件、套接字用 descriptor/handle,时钟、随机数则常作为链接期导入。
七、实践指引:如何阅读、验证与使用这份规范
本仓库是只读的规范与提案工作仓库,你可以按以下路径深入:
- 读规范概览:从 specifications/wasi-0.3.0/Overview.md 出发,横向对比 specifications/wasi-0.2.12/Overview.md(0.2 系最新,不含 gated features 表)与 specifications/wasi-0.3.1/Overview.md(0.3 系后续,新增两项 gated feature),即可看清 0.3 的差异与累积演进;
- 读提案细节:每个提案目录下的
README.md、*.md设计文档(如 proposals/sockets/TcpSocketOperationalSemantics.md、proposals/filesystem/path-resolution.md、proposals/http/service.md 与 proposals/http/middleware.md); - 读 WIT 源码:
proposals/*/wit/下的.wit文件是接口的一手定义,注释即规范语义;deps.toml/deps.lock描述提案间依赖; - 跑测试:各提案
test/目录(如 proposals/cli/test/README.md、proposals/random/test/README.md)中的测试套件可用于验证宿主实现是否满足可移植性标准; - 生成绑定与校验:按 proposals/http/README.md 的方法,用
wit-bindgen从wit/目录生成目标语言绑定,用wasm-tools component wit校验组件与 WIT 的一致性。
结语
WASI 0.3.0 是 WASI 全面拥抱 Component Model 的分水岭:六个提案统一以 WIT 定义并以 OCI artifact 形式发布,async/future/stream 作为首个被采用的 gated feature 成为所有运行时与工具链的硬性实现前提。从 command world 的异步 run,到 stdio 的 read-via-stream/write-via-stream,再到时钟的 wait-until、套接字的 resolve-addresses 与 HTTP 的 handler.handle,异步流式抽象贯穿了 0.3.0 的每个角落。理解本文所述的版本脉络、提案清单与门控特性机制,你就掌握了进入 WASI 0.3 世界的第一把钥匙。