Welcome to the Bytecode Alliance blog. The Bytecode Alliance is a nonprofit organization dedicated to creating secure new software foundations, building on standards such as WebAssembly and WebAssembly System Interface (WASI).

Yesterday the W3C WASI Sub-Group (WASI SG) released WASI 0.2.1. This is a non-breaking release, following the WASI 0.2.0 release in February of this year. In this post we’ll explain what’s included in this release, as well as explain how WASI releases will happen going forward.

For those unfamiliar with WebAssembly (Wasm) components and WASI 0.2, here is a quick, simplified primer:

  • Core Wasm is a (virtual) instruction format for programs to be compiled into (think: x86-64).
  • Wasm components are a container format and type system that wrap Core Wasm instructions into typed, hermetic binaries and libraries (think: ELF).
  • WASI is a reserved namespace for a collection of standardized Wasm component interfaces (think: POSIX header files).

For a more detailed explanation see the WASI 0.2 announcement post.

Shipping a release process

In February of this year WASI 0.2.0 was released, nearly five years after the release of WASI 0.1 (2019). Since then the WASI SG has aimed to both increase the frequency of WASI releases and reduce the scope of each release. The idea is that by shipping smaller releases, new features and fixes can be shipped more quickly, as well as making it easier for both language toolchain and runtime implementers to stay up to date.

WASI 0.2.1 is the first release in a series. As a point release, it is entirely backwards-compatible with all previous versions in the WASI 0.2.x range. It was released yesterday, August 1st, 2024, which is the first Thursday of the month. The schedule going forward is to release a new version of WASI every two months, on the first Thursday of that month. The release schedule for WASI through the remainder of 2024 is as follows:

WASI version Date
0.2.1 2024-08-01
0.2.2 2024-10-03
0.2.3 2024-12-05

The release process so far only covers non-breaking releases of WASI. The WASI SG intends to eventually release a forever-stable WASI 1.0 release, and at least one more breaking release before then (WASI 0.3). By shipping smaller features and bug fixes as part of point releases, the scope of the major versions will be reduced, which in turn should make them easier to implement and adopt.

Adopting the @since gate notation in WIT

WASI interfaces are defined using Wasm Interface Types (WIT): a versioned, human-readable format that describes which APIs a Wasm component depends on (imports) and which APIs it provides (exports). WIT recently added the capability to annotate which version of a document an API was added in using the new @since gate notation.

WASI 0.2.1 has adopted the @since notation for its WIT documents, making them easier to version over time. Take, for example, the wasi:random interface, which can be used to generate random numbers. In version 0.2.0 of WASI wasi:random/random looked like this:

package wasi:random@0.2.0;

interface random {
    get-random-bytes: func(len: u64) -> list<u8>;
    get-random-u64: func() -> u64;
}

In version 0.2.1 of WASI, each API is now annotated with an additional @since gate, which describes which version the API was introduced in. With those annotations, the interface now looks like this:

package wasi:random@0.2.1;

@since(version = "0.2.0")
interface random {
    @since(version = "0.2.0")
    get-random-bytes: func(len: u64) -> list<u8>;
    
    @since(version = "0.2.0")
    get-random-u64: func() -> u64;
}

This feature makes it possible for tooling to provide actionable diagnostics and explainers when dealing with inevitable version mismatches. Since anyone is free to implement WASI APIs, it’s expected that host runtimes and language toolchains might update to newer versions at a different pace.

Versioning using @since is not the only feature being introduced: WASI APIs are now also making use of an @unstable annotation while being developed but not yet stable. This includes APIs such as CLI: Exit with Code, and Clocks: Timezone. Landing these APIs as @unstable is a required step towards stability, so it’s likely you can expect these APIs to be stabilized in future WASI releases.

Finally the introduction of @since also paves the way for an @deprecated annotation. The WASI 0.2.x family of APIs promises strict backwards-compatibility, so there needs to be a way to fix mistakes without breaking any existing users. @deprecated has landed in the Wasm Component model, but is not yet being used by WASI 0.2.1. WASI 0.2.2 (October 2024) will likely be the first release to make use of @deprecated. For more information on how WIT’s feature gates work, see the WIT documentation.

WASI interfaces are now available as OCI images

The WebAssembly Working Group in the CNCF recently published a specification for how to package up WebAssembly Components as OCI Images. This makes it possible to encode, publish, and fetch WebAssembly Components from OCI-compliant registries such as GitHub Packages, Azure Container Registry, and Google Artifact Registry. WASI 0.2.1 has been released with packages available to download from the WebAssembly GitHub organization.

OCI tooling for WebAssembly is still developing, our hope is to make this integrate seamlessly with both language-native toolchains as well as in WebAssembly host runtimes. If you’d like to follow the development of our work on this, you can check out our implementations in bytecodealliance/wasm-pkg-tools or get involved by joining the Bytecode Alliance Packaging Interest Group.

Conclusion

In addition to the highlights mentioned in this post, WASI 0.2.1 also includes six months worth of bug fixes and clarifications in the documentation. The Bytecode Alliance is excited for this first release of WASI on the release train, and we’re looking forward to the next set of releases.

Thanks to everyone who has contributed to the specifications, implementations, and especially to everyone using WebAssembly. This wouldn’t have been possible without you. Happy release day!