WASI 0.2.2 规范解析:基于 Component Model 的七大提案与 WIT 接口全览

原创2026-10-13 16:57:401,987 阅读

WASI 0.2.2 规范解析:基于 Component Model 的七大提案与 WIT 接口全览

本文围绕本仓库 specifications/wasi-0.2.2/Overview.md 展开,系统讲解 WebAssembly System Interface(WASI)0.2.2 规范的技术定位、提案组成与发布形态:它基于 WebAssembly Component Model,将 wasi:io、wasi:random、wasi:clocks、wasi:sockets、wasi:filesystem、wasi:cli、wasi:http 七个提案的 WIT(WebAssembly Interface Type)定义按 Wasm OCI Artifact 布局推送到 OCI 分发。读完本文,你将掌握 WASI 0.2.x(Preview 2)这一代接口的完整组成、每个提案的核心接口与仓库中的对应 WIT 源码位置,以及 0.2.2 与相邻 0.2.0/0.2.1 乃至 0.3.x 系列的版本脉络。

WASI 0.2 的时代背景:从 witx 到 Component Model

在进入 0.2.2 的具体内容前,有必要先定位它在 WASI 演进序列中的坐标。仓库根目录的 README.md 给出了清晰的代际划分:

  • Preview 1(WASI 0.1):最早发布并已广泛使用的 API,使用 witx IDL 定义,主要受 POSIX 与 CloudABI 影响;
  • WASI 0.2(Preview 2):以 Wit IDL 定义的一组模块化 API 集合,吸收了 0.1 的经验教训,支持更广泛的源语言、更强的模块化、更具表达力的类型系统以及可虚拟化(virtualizability);
  • WASI 0.3(Preview 3):当前预览版,用组件模型原生的 future/stream 异步能力替代 0.2 中显式的流与轮询接口。

因此,specifications/wasi-0.2.2/Overview.md 开头那句 "based on the WebAssembly Component Model" 并非修饰语,而是 0.2 世代所有接口定义的方式论前提:每个提案都不再是扁平的函数清单,而是组件模型中的 world、interface、resource、stream、future 等一等公民。

仓库 specifications/ 目录按版本号排列了从 wasi-0.2.0 到 wasi-0.2.12、再到 wasi-0.3.0、wasi-0.3.1 的系列 Overview 文档,本篇文章聚焦的 specifications/wasi-0.2.2/Overview.md 即位于这一版本谱系之中。

0.2.2 规范的提案组成:七个 WASI API 包

specifications/wasi-0.2.2/Overview.md 正文的核心内容,是声明包含在 0.2.2 规范中的七个提案,其 WIT 定义被推送到 OCI 分发。完整清单如下:

提案(WIT 包) 职责 仓库对应目录
wasi:io@0.2.2 流与 future 等基础 I/O 类型 未在 proposals/ 下单独成目录(见下文说明)
wasi:random@0.2.2 加密安全的随机数 proposals/random/wit/
wasi:clocks@0.2.2 单调时钟、系统时钟与时区 proposals/clocks/wit/
wasi:sockets@0.2.2 TCP/UDP/IP 域名解析等网络能力 proposals/sockets/wit/
wasi:filesystem@0.2.2 基于 descriptor 的文件系统访问 proposals/filesystem/wit/
wasi:cli@0.2.2 命令行环境:参数、环境变量、stdio、退出码 proposals/cli/wit/
wasi:http@0.2.2 HTTP 服务端与客户端 proposals/http/wit/

说明:文档列出的 wasi:io@0.2.2 在 proposals/ 目录下没有对应的独立提案文件夹,从源码结构看,stream<u8>、future<result<...>> 等 io 类型直接以依赖形式出现在 filesystem、cli(stdio)、http 等提案的 WIT 签名中(例如 proposals/cli/wit/stdio.wit、proposals/http/wit/types.wit),即 io 承担着"被其余接口复用的底层类型底座"角色。

从 docs/Proposals.md 的活跃提案清单可以看到,clocks、random、filesystem、sockets、cli、http 六个提案目前处于 Phase 3(Implementation Phase),分别由 Dan Gohman、Dave Bakker、Piotr Sikora 等人担任 Champion——这与 0.2.2 规范"收录哪些提案"的决策依据直接相关。

发布形态:Wasm OCI Artifact 布局与 WIT 分发

规范文档特别强调,每个提案的 WIT 定义是 "pushed to OCI based on the Wasm OCI Artifact layout",即按 Wasm OCI Artifact 的布局标准打包进 OCI 镜像仓库进行版本化分发。这意味着:

  1. 每个提案包对应一个独立的 OCI 镜像,以 wasi:<proposal> 为命名空间,以 0.2.2 为 tag(例如 wasi:cli@0.2.2);
  2. WIT 定义成为可被 wit-deps 等工具直接拉取的依赖单元——仓库中 filesystem、sockets、http、cli 等提案目录内均带 deps.toml 与 deps.lock 文件,正是 WIT 包依赖声明与锁定机制的实际体现;
  3. 版本号通过 OCI tag 表达,同一提案的不同规范版本可并行共存,互不覆盖。

这种分发方式的收益在于:工具链和宿主实现可以按精确版本获取接口定义,而不是依赖某个"最新主干",为多版本并行(0.2.x 与 0.3.x 共存)提供了分发基础。

逐个拆解:七大提案的核心接口

wasi:io:stream 与 future 的类型底座

wasi:io 提供的是组件模型 I/O 的类型基础。虽然本仓库没有其独立 WIT 文件,但它的影响无处不在:CLI 的 stdin/stdout/stderr 通过 read-via-stream/write-via-stream 返回或接收 stream<u8> 与 future<result<_, error-code>>(proposals/cli/wit/stdio.wit),HTTP 请求/响应体同样是 option<stream<u8>>(proposals/http/wit/types.wit)。可以推断,wasi:io 定义了这些跨提案共享的流式原语,是其余提案的公共依赖。

wasi:random:加密安全的随机数

WASI Random 的目标是让 WASI 程序获得适合密码学用途的高质量底层随机数据。核心接口在 proposals/random/wit/random.wit 中定义了两个函数:

  • get-random-bytes(max-len: u64) -> list<u8>:返回至多 max-len 字节的加密安全随机(或伪随机)数据。规范要求数据至少达到充分播种的 CSPRNG 的强度、任何情况下都不得阻塞、且总是不可预测的;实现允许"短读"(返回少于请求的字节),因此需要精确字节数的调用方必须循环调用直至凑齐;max-len 为 0 时必须返回空列表而不能 trap;
  • get-random-u64() -> u64:同样的随机数据以 u64 形式返回,用于规避 list<u8> 绑定的额外开销。

此外,该提案还包含 insecure.wit(用于哈希表 DoS 防护的固定大小种子,见 proposals/random/README.md)与 insecure-seed.wit。其设计目标还包括让源语言在宿主环境支持下为哈希表启用 DoS 防护。

wasi:clocks:单调时钟、系统时钟与时区

proposals/clocks/wit/monotonic-clock.wit 定义单调时钟:起点未指定,连续读取产生非递减值,适合测量流逝时间。其接口包括:

  • now() -> mark:读取当前值,mark 是自未指定起点起的纳秒数(u64);
  • get-resolution() -> duration:查询时钟分辨率;
  • wait-until(when: mark) 与 wait-for(how-long: duration):异步等待到指定时刻或等待指定时长。

proposals/clocks/wit/system-clock.wit 定义系统时钟,面向"给人看"的当前日期时间:now() -> instant 返回以 1970-01-01T00:00:00Z 为纪元(POSIX 秒)的 {seconds: s64, nanoseconds: u32} 记录;该时钟可能被外部重置,不保证单调,因此不适合测量流逝时间。

两者共用 proposals/clocks/wit/types.wit 中的 duration = u64(纳秒)。在 0.2.2 版本中,timezone 接口(world imports 中以 @unstable(feature = clocks-timezone) 标记,见 proposals/clocks/wit/world.wit)属于未稳定特性,这也解释了该提案在 docs/Proposals.md 中"Clocks: Timezone"单列于 Phase 2 的原因。

wasi:sockets:TCP/UDP 与 IP 域名解析

wasi:sockets 提供网络能力。proposals/sockets/wit/types.wit 定义了地址族(ipv4/ipv6,对应 POSIX AF_INET/AF_INET6)、IPv4/IPv6 地址、套接字地址(含 port、flow-info、scope-id 等字段)以及面向 socket 的错误码(如 address-in-use、connection-refused、timeout),每个错误码都标注了 POSIX 对应项。TCP socket 资源处于 unbound → bound → listening/connecting → connected → closed 的状态机中,详细的运行语义可参见仓库中的 TcpSocketOperationalSemantics.md 与 Posix-compatibility.md。

域名解析在 proposals/sockets/wit/ip-name-lookup.wit 中通过 resolve-addresses(name: string) -> result<list<ip-address>, error-code> 提供,Unicode 域名自动经 IDNA 转 ASCII,IP 字符串则直接解析不发起外部请求,结果按连接顺序偏好返回,且保证成功时至少返回一个地址、从不返回 IPv4-mapped IPv6 地址。

wasi:filesystem:基于 descriptor 的沙箱化文件访问

wasi:filesystem 的目标是让 WASI 程序在既有文件系统上低开销地访问文件。proposals/filesystem/wit/types.wit 给出了几条关键的语义约定:

  • 路径即字符串:路径以 Unicode 标量值序列(string)传递,目录分隔符恒为 /;
  • 全部相对路径:所有路径都相对于一个指向基准目录的 descriptor 解释。若路径以 / 开头,或解析过程中任何一步(含 .. 与符号链接)触及基准目录之外、或触及指向底层文件系统绝对/根路径的符号链接,函数将以 error-code::not-permitted 失败——这是 WASI 沙箱模型在文件系统层面的落点,详细规则见 path-resolution.md;
  • 兼容优先于可移植:底层平台可能导致路径大小写折叠差异、删除被打开文件的行为差异、并发写者的持久性与原子性差异;需要严格可移植语义的用户应改用键值存储或数据库。

接口以 descriptor 资源为核心,提供 open-at、read-via-stream/write-via-stream/append-via-stream(分别对应 POSIX pread/pwrite/O_APPEND 写)、stat/stat-at、create-directory-at、rename-at、link-at、symlink-at、metadata-hash、is-same-object 等约 30 个方法,并定义了与 POSIX O_CREAT/O_EXCL/O_TRUNC 对应的 open-flags 以及 descriptor-flags(含类似 O_SYNC/O_DSYNC 的同步标志与 mutate-directory 写目录开关)。预打开目录通过 preopens.wit 的 get-directories() -> list<tuple<descriptor, string>> 提供给 guest。

wasi:cli:命令行世界与标准流

wasi:cli 是面向命令行环境的 world 提案,覆盖交互式命令行程序、使用文件系统与套接字的服务端程序,以及读写标准输入输出的流过滤器三类典型场景(见 proposals/cli/README.md)。其核心是 command.wit 中的 command world:

package wasi:cli@0.3.1;

@since(version = 0.3.0)
world command {
  include imports;
  export run;
}

command world 由两部分组成:

  • include imports:汇总了 wasi:clocks/imports、wasi:filesystem/imports、wasi:sockets/imports、wasi:random/imports,以及 environment、exit、stdin/stdout/stderr、terminal-input/terminal-output/terminal-stdin/terminal-stdout/terminal-stderr 等接口(proposals/cli/wit/imports.wit);
  • export run:guest 导出 run: async func() -> result 作为程序入口(proposals/cli/wit/run.wit)。

其中几个接口的要点:

  • environment(environment.wit):get-environment() 返回 POSIX 风格环境变量((name, value) 对),get-arguments() 返回命令行参数列表,get-initial-cwd() 返回初始工作目录路径;
  • stdio(stdio.wit):stdin 通过 read-via-stream() -> tuple<stream<u8>, future<result<_, error-code>>> 提供读取流;stdout/stderr 通过 write-via-stream(data: stream<u8>) -> future<result<_, error-code>> 写入,错误码包括 io、illegal-byte-sequence、pipe(断管);
  • exit(exit.wit):exit(status: result) 与 exit-with-code(status-code: u8) 退出当前实例及任何链接实例,exit-with-code 不返回,效果类似 trap 但无"出错"含义,0 通常表示成功。

设计取舍上,stdout/stderr 仍作为 output-stream 处理而未单独提供"永不失败"的打印 API,是考虑到云/边缘场景应迁移到更专用的 world;环境变量单独作为 import 而非 command 参数,是为了让非 CLI world 也能复用。

wasi:http:service 与 middleware 两类 world

wasi:http 以组件模型 world 的方式同时覆盖 HTTP 服务与客户端。proposals/http/wit/worlds.wit 定义了三个关键构件:

  • service world:面向 web 应用、API 服务与代理的广义 HTTP 服务,include 时钟与随机数导入,导入 wasi:cli/stdout、stderr(以及为兼容工具链而临时保留的 stdin)、client 接口,并导出 handler 接口——宿主通过调用组件导出的 handler.handle(request) -> result<response, error-code> 将入站请求投递给组件,组件需能处理 0..N 次 handle 调用;
  • middleware world:include service 并额外导入 handler,使组件可参与"请求沿 handler 链流动至末端 service、响应反向流回"的中间件链;
  • client 接口:send 的签名与 handler.handle 相同,既可发往网络也可直连另一组件的 handle 导出绕过网络。

类型层面,proposals/http/wit/types.wit 定义了 method(含 other(string) 扩展)、scheme、status-code = u16、fields/headers/trailers 资源(支持 get/set/append/delete/clone 等操作,区分可变与不可变)、request 与 response 资源(body 以 option<stream<u8>> 表达,经 consume-body 消费)、request-options(可配置连接、首字节、字节间三个传输层超时)以及一套精细的 error-code(从 DNS-error 到 TLS-alert-received、HTTP-response-timeout 等,涵盖代理场景的 IANA 错误类型灵感)。HTTP 中间件链的更完整讨论可参考 middleware.md 与 service.md。

版本脉络:0.2.x 到 0.3.x 的演进

将 specifications/wasi-0.2.2/Overview.md 与相邻版本对比,可以看清演进节奏:

  • wasi-0.2.0、wasi-0.2.1、wasi-0.2.2 三个版本结构完全一致,均为七个提案 + OCI 发布声明,差异体现在 OCI tag 版本号上(0.2.1/0.2.2 属修订性发布);
  • 从 wasi-0.3.0 开始,规范不再包含 wasi:io,并新增 "Component Model features" 章节,明确实现该版本需在默认(非门控)组件模型特性之上,再加已采纳的门控特性(async lift/lower、future、stream,见 specifications/wasi-0.3.0/Overview.md);
  • wasi-0.3.1 进一步引入 map<K,V> 类型与 implements/external-id 注解等门控特性,完整的采纳记录见 docs/ComponentModelFeatures.md。

这也解释了为什么本仓库 proposals/ 目录下各提案的 WIT 文件包版本为 0.3.x(如 package wasi:cli@0.3.1):提案目录反映的是当前在推进的最新定义,而历史规范快照(0.2.x)的 WIT 包则通过 OCI artifact 以对应 tag 分发。

总结:如何在仓库中继续深入

本文基于 specifications/wasi-0.2.2/Overview.md 展开。若要深入每个提案的实现细节,建议按以下路径在仓库中继续阅读:

WASI 0.2.2 是 Preview 2 世代中的一个稳定快照:以 Component Model 为骨架,以 OCI artifact 为分发通道,将 io、random、clocks、sockets、filesystem、cli、http 七大能力集成为一个可版本化、可组合、可沙箱化的系统接口体系——这也是后续 0.3 世代迈向原生异步组件模型的基础。

登录后查看全文
WASI