WASI 规范 0.2.10 全解析:基于 Component Model 的七个接口包与 OCI 分发机制
WASI 规范 0.2.10 全解析:基于 Component Model 的七个接口包与 OCI 分发机制
本文以 WASI 规范 0.2.10 版本(specifications/wasi-0.2.10/Overview.md)为核心,讲解 WASI(WebAssembly System Interface)0.2.x 系列快照的整体结构:它如何以 WebAssembly Component Model 为基础、由哪些 proposal(提案)组成、每个包在仓库中的 WIT 定义形态,以及 WIT 定义如何按 Wasm OCI Artifact 布局推送到 OCI 容器镜像仓库。读完本文,你将掌握 WASI 0.2.10 的包命名规范(如 wasi:cli@0.2.10)、七个接口包的职责边界、WIT 世界(world)与接口的组织方式,并能在本仓库的 proposals/ 目录中按图索骥找到每个包的完整定义。
WASI 0.2.10 在规范演进中的位置
WASI 规范以版本化快照的方式发布,本仓库的 specifications/ 目录下按版本号归档了多份 Overview 文档,从 wasi-0.2.0 一路到 wasi-0.2.12,以及后续的 wasi-0.3.0、wasi-0.3.1。wasi-0.2.10 属于 WASI 0.2 系列(即 Preview 2)的一个修订快照。
与 WASI 0.1(Preview 1,基于 witx IDL)不同,WASI 0.2 的 API 是使用 WIT(WebAssembly Interface Type)IDL 定义的模块化 API 集合。其核心特性包括:
- 支持更广泛的宿主语言;
- 模块化的包(package)结构,每个能力域独立成包;
- 更富表达力的类型系统(resource、record、variant、flags、stream、future 等);
- 可虚拟化(virtualizability):接口可以通过组件(component)在链接期被替换或衰减。
这一点可以从仓库根目录 README.md 得到印证:README 明确说明「WASI 0.2(Preview 2)是一个用 Wit IDL 定义的模块化 API 集合,吸收了 WASI 0.1 的诸多经验教训」。而 0.2.10 正是这一系列的某个具体版本号:WIT 包版本采用语义化版本(semver)管理,包名中的 0.2.10 即对应此规范快照的 WIT 定义版本(可参考 docs/Proposals.md 中「Versioning」一节的说明)。
说明:0.2.10 的 Overview 面向 WASI 0.2(Preview 2)线;仓库中还包含 0.3.x(Preview 3)的 Overview,后者额外要求组件模型的
asynclift/lower、future/stream、map<K, V>等门控特性(见 docs/ComponentModelFeatures.md),与本版本文档范围不同。
七个提案包:WIT 定义与仓库落点
0.2.10 规范包含七个提案(proposals),每个提案都有独立的 WIT 定义,且相互之间存在依赖关系。下表汇总了七个包及其在仓库中的 WIT 目录:
| OCI 包标识 | 职责概要 | 仓库 WIT 目录 |
|---|---|---|
wasi:io@0.2.10 |
流、轮询等底层 I/O 原语 | 见下方说明 |
wasi:random@0.2.10 |
密码学安全随机数 | proposals/random/wit/ |
wasi:clocks@0.2.10 |
单调时钟、系统时钟与时区 | proposals/clocks/wit/ |
wasi:sockets@0.2.10 |
TCP/UDP 网络与 IP 域名查询 | proposals/sockets/wit/ |
wasi:filesystem@0.2.10 |
沙箱化文件系统访问 | proposals/filesystem/wit/ |
wasi:cli@0.2.10 |
命令行程序世界(stdin/stdout/stderr、环境变量、退出码) | proposals/cli/wit/ |
wasi:http@0.2.10 |
HTTP 服务端与客户端接口 | proposals/http/wit/ |
各包之间的依赖关系可以从 WIT 的依赖锁定文件中读出,例如:
- proposals/cli/wit/deps.toml 声明
cli依赖clocks、sockets、random、filesystem四个包; - proposals/http/wit/deps.toml 声明
http依赖cli、clocks两个包,且从 proposals/http/wit/deps.lock 可以看到cli的传递依赖为filesystem、random、sockets; - proposals/filesystem/wit/types.wit 中
use wasi:clocks/system-clock@0.3.1.{instant},说明文件系统的时间戳类型复用了时钟包的instant类型。
依赖关系图大致为:http → cli → {clocks, filesystem, sockets, random}。这体现了 WIT 包的模块化组合设计:高层能力(CLI、HTTP)在底层能力(时钟、文件系统、网络、随机数)之上构建。
关于 wasi:io:0.2 系列的 io 包定义了 stream、pollable 等底层类型,但本仓库主分支的 proposals/ 目录已演进到 0.3.x(如 wasi:cli@0.3.1 的包声明),0.3 用组件模型原生的 future/stream 取代了 0.2 中 io 包里的显式流与轮询接口(见 README.md 对 Preview 3 的说明)。因此 wasi:io@0.2.10 的 WIT 定义需从 0.2 分支或对应的 OCI 制品获取,仓库当前工作树的 proposals/ 目录并未保留其 0.2 快照。
依赖管理的工程化:deps.toml 与 deps.lock
WIT 包的依赖不是手写的包名引用,而是通过 deps.toml + deps.lock 管理,与主流语言生态的依赖锁定思路一致:
deps.toml:声明顶层依赖及其本地路径(path = "../../clocks/wit"),用于解析时定位;deps.lock:记录每个依赖的sha256、sha512校验和及传递依赖列表,保证构建可复现。
例如 proposals/cli/wit/deps.lock 中对 clocks 包记录了完整的 SHA-256/SHA-512 摘要。这意味着在使用 WIT 工具链(如 wit-bindgen、wkg)解析这些包时,可以校验依赖内容未被篡改。
每个包的核心接口与 WIT 形态
下面按包逐一展开,介绍其 WIT 定义的核心内容(仓库当前 WIT 已标注 @since(version = 0.3.0),其接口形态是 0.2.x 的延续与后续演进,接口设计思路保持一致)。
wasi:cli:命令行世界的顶层组合
wasi:cli 是一个「世界」(world)提案,它把所有 CLI 程序需要的能力组合在一起。仓库中的 proposals/cli/wit/imports.wit 定义了 imports 世界:
world imports {
include wasi:clocks/imports@0.3.1;
include wasi:filesystem/imports@0.3.1;
include wasi:sockets/imports@0.3.1;
include wasi:random/imports@0.3.1;
import environment;
import exit;
import stdin;
import stdout;
import stderr;
import terminal-input;
import terminal-output;
import terminal-stdin;
import terminal-stdout;
import terminal-stderr;
}
而 proposals/cli/wit/command.wit 定义的 command 世界在 imports 之上再导出 run 接口:
world command {
include imports;
export run;
}
run 接口(proposals/cli/wit/run.wit)是程序入口:
interface run {
run: async func() -> result;
}
CLI 世界的核心接口包括(均在 proposals/cli/wit/ 下):
- environment(environment.wit):
get-environment返回 POSIX 风格的环境变量键值对列表,get-arguments返回命令行参数列表,get-initial-cwd返回初始工作目录(option<string>,未设置时为none)。 - exit(exit.wit):
exit(status: result)退出当前实例及所有链接的实例;exit-with-code(status-code: u8)向宿主上报退出码——语义上等效于 trap,但不暗示「出错了」,0 通常表示成功,其余值表示各类失败。 - stdio(stdio.wit):
stdin.read-via-stream返回从 stdin 读取的字节流;stdout/stderr的write-via-stream接受一个字节流写入标准输出/错误。其error-code枚举包含io、illegal-byte-sequence、pipe三种错误。 - terminal(terminal.wit):
terminal-input/terminal-output资源类型,以及get-terminal-stdin/get-terminal-stdout/get-terminal-stderr三个函数——它们以「链接期能力」的形式暴露可选的终端句柄(stdin/stdout/stderr 连接到终端时返回句柄,否则返回none)。
wasi:random:密码学安全随机数
wasi:random 的 imports 世界(proposals/random/wit/world.wit)导入三个接口:
world imports {
import random;
import insecure;
import insecure-seed;
}
- random(random.wit):
get-random-bytes(max-len: u64) -> list<u8>返回至多max-len字节的密码学安全随机数;get-random-u64() -> u64返回密码学安全的u64。WIT 注释明确了实现的硬性要求:数据必须至少与充分播种的 CSPRNG 一样安全快速、任何情况下都不得阻塞(包括首次调用与任何请求长度)、返回数据必须始终不可预测;实现可以短读(short read),需要恰好max-len字节的调用方必须循环调用;max-len大于零时至少返回 1 字节,为零时返回空列表且不 trap。确定性环境必须省略此函数而非用确定性数据实现。 - insecure(insecure.wit):
get-insecure-random-bytes/get-insecure-random-u64,非密码学安全,仅供性能敏感的非安全场景。 - insecure-seed(insecure-seed.wit):
get-insecure-seed() -> tuple<u64, u64>,返回 128 位种子,用于哈希表的 DoS 抵抗(如 Rust 的std::collections::HashMap随机种子);注释指出未来可能改为 value import,防止被多次调用或挪作他用。
wasi:clocks:单调时钟与系统时钟
wasi:clocks 的 imports 世界(proposals/clocks/wit/world.wit)导入 monotonic-clock、system-clock,以及带 @unstable(feature = clocks-timezone) 标记的 timezone。
- types(types.wit):仅定义一个
type duration = u64(纳秒)。 - monotonic-clock(monotonic-clock.wit):
type mark = u64(自某个未指定初始值以来的纳秒数);now() -> mark读取当前值,重复调用产生非递减序列;get-resolution() -> duration查询时钟分辨率;wait-until(when: mark)与wait-for(how-long: duration)用于等待到指定时刻或等待指定时长。注释特别说明:若mark无法表示当前值则 trap,因此实现应保证起始时间足够低以避免实际溢出。 - system-clock(system-clock.wit):面向「给人看的当前日期时间」。
record instant { seconds: s64, nanoseconds: u32 }表示自 POSIX 纪元(1970-01-01T00:00:00Z)以来的时刻,纳秒字段恒小于 1,000,000,000;now() -> instant读取当前时间(不保证单调,可能被重置),get-resolution() -> duration返回实现可区分的最小时间间隔。WIT 注释明确:系统时钟可能被外部参考源重置,不适合测量流逝时间。 - timezone(timezone.wit):时区查询接口,当前处于不稳定(unstable)门控状态,对应 docs/Proposals.md 中 Phase 2 的「Clocks: Timezone」提案。
wasi:filesystem:沙箱化文件访问
wasi:filesystem 的 imports 世界(proposals/filesystem/wit/world.wit)导入 types 与 preopens 两个接口:
world imports {
import types;
import preopens;
}
-
types(types.wit)是整个 WASI 中体量最大的接口之一。文件头注释界定了关键语义:
- 路径以接口类型
string传递(必须是 Unicode 标量值序列); - 目录分隔符始终是正斜杠
/; - 所有路径都是相对路径,相对于作为基准目录的
descriptor解释;若路径以/开头,或解析路径(含..与符号链接步骤)越出基准目录,或到达底层文件系统的绝对/根路径符号链接,函数以error-code::not-permitted失败。这正是 WASI 文件系统沙箱的核心机制,更多细节见 proposals/filesystem/path-resolution.md; - 该接口优先「兼容性」而非「可移植性」:允许用户访问本机文件比在所有平台上统一语义更重要,因此路径可能区分或不区分大小写、有并发写入者的文件变更的持久性与原子性因平台而异;需要精确定义可移植语义的用户应使用键值存储或数据库。
核心类型与资源包括:
type filesize = u64;variant descriptor-type(block-device、character-device、directory、fifo、symbolic-link、regular-file、socket、other)——注释注明早期版本名为filetype;flags descriptor-flags:read、write、file-integrity-sync(对应O_SYNC)、data-integrity-sync(对应O_DSYNC)、requested-write-sync(对应O_RSYNC)、mutate-directory(目录内容可变更,未设置时写类操作返回error-code::read-only);record descriptor-stat:%type、link-count、size、三个可空时间戳字段(data-access-timestamp、data-modification-timestamp、status-change-timestamp,均为option<instant>);flags path-flags { symlink-follow };flags open-flags { create, directory, exclusive, truncate }(分别对应O_CREAT/O_DIRECTORY/O_EXCL/O_TRUNC);variant new-timestamp { no-change, now, timestamp(instant) };record directory-entry { %type, name };variant error-code:约 40 个错误码,逐一标注了 POSIX 对应项(如access→EACCES、no-entry→ENOENT、not-permitted→EPERM、cross-device→EXDEV等),并保留other(option<string>)作为实现扩展的兜底;enum advice:normal、sequential、random、will-need、dont-need、no-reuse,对应posix_fadvise的访问模式建议;record metadata-hash-value { lower: u64, upper: u64 }:128 位元数据哈希,拆成两个u64是因为 wasm 没有 128 位整数类型;resource descriptor:文件系统句柄,提供约 25 个方法,全部标注了 POSIX 对应物,例如read-via-stream(类似pread)、write-via-stream(类似pwrite)、append-via-stream(类似O_APPEND的write)、advise(类似posix_fadvise)、sync-data(类似fdatasync)、sync(类似fsync)、set-size、set-times(类似futimens)、stat(类似fstat)、stat-at(类似fstatat)、open-at(类似openat)、read-directory、create-directory-at(类似mkdirat)、remove-directory-at、rename-at(类似renameat)、link-at(类似linkat)、symlink-at(类似symlinkat)、readlink-at(类似readlinkat)、unlink-file-at、is-same-object、metadata-hash/metadata-hash-at等。
- 路径以接口类型
-
preopens(preopens.wit):
get-directories() -> list<tuple<descriptor, string>>返回宿主预打开(preopened)的目录集合及其路径,这是 WASI 程序获得初始文件访问权的方式——程序能看到的根就是这些预打开目录。
wasi:sockets:TCP/UDP 网络与域名解析
wasi:sockets 的 imports 世界(proposals/sockets/wit/world.wit)导入 types 与 ip-name-lookup。其 types.wit 是另一个大型接口,核心内容包括:
variant error-code:以网络错误为主,标注了 POSIX 等价项,如access-denied(EACCES/EPERM)、timeout(ETIMEDOUT)、address-in-use(EADDRINUSE)、connection-refused(ECONNREFUSED)、connection-reset(ECONNRESET)、datagram-too-large(EMSGSIZE)等;enum ip-address-family { ipv4, ipv6 }(类似AF_INET/AF_INET6);type ipv4-address = tuple<u8, u8, u8, u8>;type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;variant ip-address { ipv4(ipv4-address), ipv6(ipv6-address) };record ipv4-socket-address { port: u16, address: ipv4-address }(sin_port/sin_addr)与对应的ipv6-socket-address(含flow-info、scope-id等字段)。
sockets 还提供两类句柄:TCP 相关的 tcp-socket 资源(监听、连接、读写、获取本端/对端地址等,语义细节见 proposals/sockets/TcpSocketOperationalSemantics.md)和 UDP 相关的 udp-socket 资源,以及 resolve-addresses 域名查询接口(ip-name-lookup.wit)。WASI 网络能力的安全模型是「显式授权」:只有宿主显式授予网络权限的组件才能创建 socket(见 proposals/sockets/GrantingAccess.md)。
wasi:http:HTTP 服务与客户端
wasi:http 的 worlds.wit 定义了三个世界与两个接口:
world service:涵盖 Web 应用、API 服务器、代理等广义 HTTP 服务。它include wasi:clocks/imports与wasi:random/imports(服务需要时间与随机数能力),导入wasi:cli/stdout、stderr(开发者控制台)、stdin(临时兼容占位,宿主必须返回 EOF 流),导入client(默认出站客户端),并export handler——宿主通过调用组件导出的handler.handle来投递入站 HTTP 请求。WIT 注释还明确了并发实例复用规则:宿主可能在之前请求未处理完时并发调用 handler,组件可借助组件模型的背压(backpressure)机制选择退出并发复用。world middleware:include service并额外import handler,用于把请求转发给下游处理器的「处理器链」场景:请求沿链正向流动、响应反向返回。interface handler:handle: async func(request: request) -> result<response, error-code>。在service中导出以响应入站请求;在middleware中同时导出(下游)与导入(上游)。interface client:send: async func(request: request) -> result<response, error-code>。签名与handler.handle相同,注释解释了这一重复的原因——当前组件模型工具链无法表达「同一接口导入两个实例」,因此client.send导入可以直接链接到handler.handle导出以绕过网络。
HTTP 的类型定义在 types.wit 中:variant method { get, head, post, put, delete, connect, options, trace, patch, other(string) }、variant scheme { HTTP, HTTPS, other(string) }、以及一个大型 variant error-code(包含 DNS-timeout、connection-refused、TLS-protocol-error、HTTP-request-URI-too-long 等细化错误,部分携带负载,如 HTTP-request-body-size(option<u64>))。request/response 资源、fields(header 集合)与 incoming-body/outgoing-body 等类型共同支撑完整的 HTTP 消息模型;更详细的服务端与中间件设计讨论可阅读 proposals/http/service.md 与 proposals/http/middleware.md。
WIT 定义如何分发:Wasm OCI Artifact 布局
0.2.10 Overview 的第二个关键信息是分发机制:该版本所有提案的 WIT 定义被「推送(pushed)」到 OCI(Open Container Initiative)镜像仓库,采用 Wasm OCI Artifact 布局。这意味着:
- WIT 定义以 OCI 制品(artifact)形式发布,可用标准 OCI 工具链(如
oras、wkg、wasi-vfs等生态工具)按 tag 拉取; - 每个包独立版本化并拥有独立 tag(如
wasi:io@0.2.10对应 tag0.2.10); - 包名使用 WIT 的
package语法:package wasi:io@0.2.10;,即namespace:package@version三段式(namespace 为wasi)。
仓库中 WIT 文件的 package 声明即体现了这一命名范式,例如 proposals/cli/wit/command.wit 顶部 package wasi:cli@0.3.1;。由于 0.2.10 快照对应的 WIT 已按 OCI 方式归档,本仓库 proposals/ 目录保留的是当前演进版本(0.3.x)的源码;要获取与 wasi-0.2.10 Overview 完全一致的 WIT 定义,应拉取对应 OCI tag 的制品。
下表汇总 0.2.10 的七个 OCI 制品标识(tag 均为 0.2.10):
| 制品 | WIT 包标识 |
|---|---|
| wasi/io | wasi:io@0.2.10 |
| wasi/random | wasi:random@0.2.10 |
| wasi/clocks | wasi:clocks@0.2.10 |
| wasi/sockets | wasi:sockets@0.2.10 |
| wasi/filesystem | wasi:filesystem@0.2.10 |
| wasi/cli | wasi:cli@0.2.10 |
| wasi/http | wasi:http@0.2.10 |
采用 OCI 分发的直接好处:运行时、工具链与构建系统可以像拉取容器镜像一样按版本拉取规范接口定义,实现跨版本的可复现构建;同时 OCI 制品天然支持摘要校验(本仓库 deps.lock 中的 SHA-256/SHA-512 正是同思路的本地实践)。
版本快照如何落地:从 Overview 到仓库提案源码
要在本仓库中把 0.2.10 的 Overview 与提案源码对应起来,可按下述路径查阅:
- 规范快照:specifications/wasi-0.2.10/Overview.md 是 0.2.10 的唯一规范文档,其余各版本 Overview 在 specifications/ 目录按版本归档。
- 提案列表与阶段:docs/Proposals.md 记录了各提案的阶段与版本策略。0.2 系列包含的 Clocks、Random、Filesystem、Sockets、CLI、HTTP 均处于 Phase 3(实现阶段),并有明确的进入条件(达到 Phase 3、满足可移植性标准、经 WASI Subgroup 投票)。
- WIT 源码:各提案的 WIT 定义在 proposals/ 下按提案目录组织,每个目录含
wit/(WIT 定义)、README.md(提案说明与 API walk-through)、LICENSE.md、以及 test 子目录。 - 关键机制文档:
- docs/Capabilities.md:能力(capability)模型——链接期能力(link-time capabilities,即实例导入)与运行时能力(runtime capabilities,即句柄/资源),并给出「何时用哪种」的决策指南(如文件系统需要同时打开多个文件,宜用句柄;时钟通常单个实例,链接期能力更方便);
- docs/ComponentModelFeatures.md:0.2.0 仅要求组件模型默认(非门控)特性,
async/future/stream、map<K,V>等门控特性由后续 0.3.x 版本采用; - proposals/filesystem/path-resolution.md:文件系统路径解析与沙箱的详细语义;
- proposals/sockets/GrantingAccess.md、proposals/sockets/Posix-compatibility.md、proposals/sockets/TcpSocketOperationalSemantics.md:socket 的授权模型、POSIX 兼容性与 TCP 操作语义;
- proposals/http/service.md、proposals/http/middleware.md:HTTP 服务与中间件设计。
小结
WASI 0.2.10 是 WASI 0.2(Preview 2)系列的一个版本化快照,其核心特征可以概括为四点:
- 基于 Component Model:全部接口用 WIT IDL 定义,包结构为
wasi:<package>@0.2.10; - 七个提案包:io、random、clocks、sockets、filesystem、cli、http,职责清晰、逐层组合(http → cli → 底层四包);
- OCI 分发:WIT 定义按 Wasm OCI Artifact 布局以独立 tag 推送到 OCI 仓库,支持按版本拉取与可复现构建;
- 沙箱与能力模型贯穿始终:文件系统路径解析相对基准目录、错误码对齐 POSIX、随机数强制 CSPRNG 语义、socket 需显式授权——这些语义都能在仓库 proposals/ 目录的 WIT 源码与配套文档中找到一手依据。
对于需要实现或接入 WASI 0.2.10 的运行时、工具链开发者,建议以 specifications/wasi-0.2.10/Overview.md 为入口,以 proposals/ 目录的 WIT 定义为权威实现依据,并以 OCI tag 拉取与版本完全一致的制品用于构建校验。