Today we’re releasing WASI 0.3.1. This is the first point release in the 0.3.x series, which we’ll be releasing every two months. See the release schedule for all planned releases through 2027.

The highlights for this release are the addition of implements and map<K, V> dependencies in the component model. That means additional expressivity to WIT interfaces. For example: with implements it allows a component to import (or export) more than one instance of the same interface under distinct names. We might want to say we aren’t just importing any key-value interface, but more specifically a valkey interface for remote storage and an in-memory cache.

map<K, V> brings a first-class associative dictionary type to WIT. This makes it possible to express dynamic sets of keys and values directly from WIT, replacing the previous pattern of needing to write list<tuple<K, V>>.

Starting with 0.3.1, WIT interfaces in WASI are allowed to make use of these features. And both runtimes and toolchains must support these features in order to be compatible with WASI 0.3.1 or later. See our process documentation for more on this.

What's Changed

• Require OCI package available for phase 2 entry by @yoshuawuyts in #938
• Update wasi-gfx to wasi-webgpu by @yoshuawuyts in #939
• Allow re-casing when serializing for transmission by @cceckman-at-fastly in #926
• Document release train by @yoshuawuyts in #945
• Add process for adopting Component Model features by @ricochet in #941
• Adopt Component Model map and implements features for 0.3.1 by @ricochet in #950

New Contributors

• @cceckman-at-fastly made their first contribution in #926

Full Changelog: v0.3.0...v0.3.1

WASI 0.3.0

WASI 0.3 is official, and async is now native to WebAssembly Components. The WASI Subgroup voted to ratify WASI 0.3.0, rebasing WASI onto the WebAssembly Component Model's async primitives. These are the detailed release notes, for a high-level overview read the announcement post.

Most of the changes in the 0.3 interfaces are entirely mechanical. WASI 0.2 had to perform some acrobatics to make async work, but now that async is native to the component model we can write the same things we did before but much more ergonomically. Here is a overview of the patterns we were encoding in WASI 0.2 with the wasi:io package, and what those patterns now look like in 0.3 with Component Model async:

wasi:cli

Structurally the files are the same (stdin.wit, stdout.wit, stderr.wit,
run.wit, exit.wit, terminal.wit, environment.wit). The interesting
change is stdio.

// WASI 0.2
interface stdin {
  use wasi:io/streams.{input-stream};
  get-stdin: func() -> input-stream;
}

interface stdout {
  use wasi:io/streams.{output-stream};
  get-stdout: func() -> output-stream;
}

// WASI 0.3
interface stdin {
  use types.{error-code};
  read-via-stream: func() -> tuple<stream<u8>, future<result<_, error-code>>>;
}

interface stdout {
  use types.{error-code};
  write-via-stream: func(data: stream<u8>) -> future<result<_, error-code>>;
}

Note the direction flip on stdout. WASI 0.2 handed you an output-stream that you wrote into imperatively. WASI 0.3 has you pass in a stream<u8> and get back a future that resolves when the write completes. A small new wasi:cli/types interface carries a shared error-code variant (io, illegal-byte-sequence, pipe).

wasi:sockets

The network resource is gone. WASI 0.2 modeled network access as a capability resource threaded through every bind/connect/lookup call. WASI 0.3 removes it entirely; network access is granted via world imports.

Every start/finish pair became one async func. The in-progress intermediate states (bind-in-progress, connect-in-progress, listen-in-progress) and the subscribe() -> pollable that drove them are gone:

// WASI 0.2
start-bind:     func(network: borrow<network>, local: ip-socket-address)
                 -> result<_, error-code>;
finish-bind:    func() -> result<_, error-code>;
start-connect:  func(network: borrow<network>, remote: ip-socket-address)
                 -> result<_, error-code>;
finish-connect: func()
                 -> result<tuple<input-stream, output-stream>, error-code>;

// WASI 0.3
bind:    async func(local-address: ip-socket-address)  -> result<_, error-code>;
connect: async func(remote-address: ip-socket-address) -> result<_, error-code>;
listen:  async func()                                  -> result<_, error-code>;
accept:  async func()
  -> result<tuple<tcp-socket, ip-socket-address>, error-code>;

Note that WASI 0.2's finish-connect returned the TCP stream pair inline. In WASI 0.3 connect returns nothing special; byte I/O lives on the socket resource's own stream methods.

UDP got the same treatment. The incoming/outgoing datagram stream resources are gone, replaced by plain async send and async receive. Error codes across TCP, UDP, and name-lookup were unified into a single error-code variant, with a new connection-broken case and an open-ended other(option<string>) tail.

Changes to wasi:http

The interface that has seen the most change is wasi:http. We haven’t just
mechanically converted poll-based interfaces to native async ones, but actually
reorganized the worlds and changed some of the core abstractions. wasi:http
now exposes two worlds: wasi:http/service and wasi:http/middleware:

interface client { /* ... */ }
interface handler { /* ... */ }

// When used by guest bindings generators, grant the
// ability to make HTTP calls through the `client` import, and
// handle incoming HTTP requests through the `handler` export.
world service {
  import client;
  export handler;
}

// The middleware world is a super-set of the service world.
world middleware {
  include service; // ← Do everything that `service` can do.
  import handler;  // ← But also pass incoming requests down to another handler.
}

The middleware world replaces the 0.2-era proxy world, and is used to define HTTP handlers which can forward requests to other handlers. What’s new in WASI 0.3 is that this can now perform service chaining: a pattern where components can be directly composed with one another. This means components acting as microservices that frequently interop with other microservices, do not need to go over the network. Instead a runtime can choose to directly compose them with each other inside the same process. For most microservices this will reduce the time for calling other microservices from milliseconds to nanoseconds: six orders of magnitude.

wasi:filesystem

Streaming reads/writes switched to the stream-plus-future shape:

// WASI 0.2
read-via-stream:  func(offset: filesize) -> result<input-stream, error-code>;
write-via-stream: func(offset: filesize) -> result<output-stream, error-code>;

// WASI 0.3
read-via-stream:  func(offset: filesize)
  -> tuple<stream<u8>, future<result<_, error-code>>>;
write-via-stream: func(data: stream<u8>, offset: filesize)
  -> future<result<_, error-code>>;

Directory iteration switched from a resource-based iterator to a stream:

// WASI 0.2
read-directory: func() -> result<directory-entry-stream, error-code>;
// plus: resource directory-entry-stream { read-directory-entry: func() -> ... }

// WASI 0.3
read-directory: func()
  -> tuple<stream<directory-entry>, future<result<_, error-code>>>;

wasi:clocks

The wasi:clocks changes are, deliberately, mostly renames. Flagging them because the churn shows up in downstream suites.

WASI#79 (Avoid nonstandard use of names for types) moved the package onto conventional names: wall-clock became system-clock, and datetime became instant. The motivation was consistency with how the rest of the ecosystem talks about clocks. "Wall clock" and "datetime" were WASI-isms that didn't match POSIX, Rust's std::time, or most other systems. wasi:filesystem timestamps followed, for the same reason.

A small types.wit was added to share the duration = u64 alias. monotonic-clock also dropped its pollable-returning subscribe-instant and subscribe-duration calls; callers now await a host-provided timer future, the same pattern used everywhere else.

Downstream impact is mostly mechanical find-and-replace. See
WebAssembly/wasi-testsuite@f13976f for a representative update across the test suite.