Skip to content

Commit 65e758c

Browse files
yoshuawuytsyoshuawuyts
authored
Blog post: Announcing WASI 0.2.1 (#97)
* Create 2024-08-02-WASI-0.2.1.md * Update 2024-08-02-WASI-0.2.1.md
1 parent 0d3a4f9 commit 65e758c

1 file changed

Lines changed: 142 additions & 0 deletions

File tree

‎_posts/2024-08-02-WASI-0.2.1.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Announcing WASI 0.2.1
3+
author: "Yosh Wuyts"
4+
github_name: yoshuawuyts
5+
---
6+
7+
_Welcome to the Bytecode Alliance blog. The Bytecode Alliance is a nonprofit
8+
organization dedicated to creating secure new software foundations, building on
9+
standards such as [WebAssembly](https://webassembly.org/) and [WebAssembly
10+
System Interface (WASI)](https://wasi.dev/)._
11+
12+
Yesterday the W3C WASI Sub-Group (WASI SG) released [WASI
13+
0.2.1](https://github.com/WebAssembly/WASI/releases). This is a non-breaking
14+
release, following the WASI 0.2.0 release in February of this year. In this post
15+
we'll explain what's included in this release, as well as explain how WASI
16+
releases will happen going forward.
17+
18+
For those unfamiliar with WebAssembly (Wasm) components and WASI 0.2, here is a quick, simplified primer:
19+
20+
* **Core Wasm** is a (virtual) instruction format for programs to be
21+
compiled into (think: x86-64).
22+
* **Wasm components** are a container format and type
23+
system that wrap Core Wasm instructions into typed, hermetic binaries and libraries (think: ELF).
24+
* **WASI** is a reserved namespace for a collection of standardized Wasm component interfaces (think: POSIX header files).
25+
26+
For a more detailed explanation see the [WASI 0.2 announcement post](https://bytecodealliance.org/articles/WASI-0.2).
27+
28+
## Shipping a release process
29+
30+
In February of this year WASI 0.2.0 was released, nearly five years after the
31+
release of WASI 0.1 (2019). Since then the WASI SG has aimed to both
32+
increase the frequency of WASI releases and reduce the scope of each
33+
release. The idea is that by shipping smaller releases, new features and fixes
34+
can be shipped more quickly, as well as making it easier for both language
35+
toolchain and runtime implementers to stay up to date.
36+
37+
WASI 0.2.1 is the first release in a series. As a point release, it is entirely
38+
backwards-compatible with all previous versions in the WASI 0.2.x range. It was
39+
released yesterday, August 1st, 2024, which is the first Thursday of the month.
40+
The schedule going forward is to release a new version of WASI every two months,
41+
on the first Thursday of that month. The release schedule for WASI through the
42+
remainder of 2024 is as follows:
43+
44+
| WASI version | Date |
45+
|--------------|-------------|
46+
| 0.2.1 | 2024-08-01 |
47+
| 0.2.2 | 2024-10-03 |
48+
| 0.2.3 | 2024-12-05 |
49+
50+
The release process so far only covers non-breaking releases of WASI. The WASI
51+
SG intends to eventually release a forever-stable WASI 1.0 release, and at least
52+
one more breaking release before then (WASI 0.3). By shipping smaller features
53+
and bug fixes as part of point releases, the scope of the major versions will be
54+
reduced, which in turn should make them easier to implement and adopt.
55+
56+
## Adopting the `@since` gate notation in WIT
57+
58+
WASI interfaces are defined using Wasm Interface Types (WIT): a versioned,
59+
human-readable format that describes which APIs a Wasm component depends on
60+
(imports) and which APIs it provides (exports). WIT recently added the
61+
capability to annotate which version of a document an API was added in using the
62+
new `@since` gate notation.
63+
64+
WASI 0.2.1 has adopted the `@since` notation for its WIT documents, making them
65+
easier to version over time. Take, for example, the `wasi:random` interface,
66+
which can be used to generate random numbers. In version 0.2.0 of WASI
67+
`wasi:random/random` looked like this:
68+
69+
```wit
70+
package wasi:random@0.2.0;
71+
72+
interface random {
73+
get-random-bytes: func(len: u64) -> list<u8>;
74+
get-random-u64: func() -> u64;
75+
}
76+
```
77+
78+
In version 0.2.1 of WASI, each API is now annotated with an additional `@since`
79+
gate, which describes which version the API was introduced in. With those
80+
annotations, the interface now looks like this:
81+
82+
```wit
83+
package wasi:random@0.2.1;
84+
85+
@since(version = "0.2.0")
86+
interface random {
87+
@since(version = "0.2.0")
88+
get-random-bytes: func(len: u64) -> list<u8>;
89+
90+
@since(version = "0.2.0")
91+
get-random-u64: func() -> u64;
92+
}
93+
```
94+
95+
This feature makes it possible for tooling to provide actionable diagnostics and
96+
explainers when dealing with inevitable version mismatches. Since anyone is free
97+
to implement WASI APIs, it's expected that host runtimes and language toolchains
98+
might update to newer versions at a different pace.
99+
100+
Versioning using `@since` is not the only feature being introduced: WASI APIs
101+
are now also making use of an `@unstable` annotation while being developed but
102+
not yet stable. This includes APIs such as CLI: Exit with Code, and Clocks:
103+
Timezone. Landing these APIs as `@unstable` is a required step towards
104+
stability, so it's likely you can expect these APIs to be stabilized in future
105+
WASI releases.
106+
107+
Finally the introduction of `@since` also paves the way for an `@deprecated`
108+
annotation. The WASI 0.2.x family of APIs promises strict
109+
backwards-compatibility, so there needs to be a way to fix mistakes without
110+
breaking any existing users. `@deprecated` has landed in the Wasm Component
111+
model, but is not yet being used by WASI 0.2.1. WASI 0.2.2 (October 2024) will
112+
likely be the first release to make use of `@deprecated`. For more information on how WIT's feature gates work, [see the WIT documentation](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates).
113+
114+
## WASI interfaces are now available as OCI images
115+
116+
The WebAssembly Working Group in the CNCF recently published a specification for
117+
how to package up [WebAssembly Components as OCI
118+
Images](https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/).
119+
This makes it possible to encode, publish, and fetch WebAssembly Components from
120+
OCI-compliant registries such as GitHub Packages, Azure Container Registry, and
121+
Google Artifact Registry. WASI 0.2.1 has been released with packages available
122+
to download from the [WebAssembly GitHub
123+
organization](https://github.com/orgs/WebAssembly/packages).
124+
125+
OCI tooling for WebAssembly is still developing, our hope is to make this
126+
integrate seamlessly with both language-native toolchains as well as in
127+
WebAssembly host runtimes. If you'd like to follow the development of our work
128+
on this, you can check out our implementations in
129+
[bytecodealliance/wasm-pkg-tools](https://github.com/bytecodealliance/wasm-pkg-tools)
130+
or get involved by joining the [Bytecode Alliance Packaging Interest
131+
Group](https://github.com/bytecodealliance/meetings/tree/main/SIG-Packaging).
132+
133+
## Conclusion
134+
135+
In addition to the highlights mentioned in this post, WASI 0.2.1 also includes
136+
six months worth of bug fixes and clarifications in the documentation. The
137+
Bytecode Alliance is excited for this first release of WASI on the release
138+
train, and we're looking forward to the next set of releases.
139+
140+
Thanks to everyone who has contributed to the specifications, implementations,
141+
and especially to everyone using WebAssembly. This wouldn't have been possible
142+
without you. Happy release day!

0 commit comments

Comments
 (0)