diff --git a/docs/contribute.md b/docs/contribute.md index b0703c9..4aa8333 100644 --- a/docs/contribute.md +++ b/docs/contribute.md @@ -1,6 +1,6 @@ --- title: "Contribute" -sidebar_position: 4 +sidebar_position: 6 --- This site is a community effort supported by volunteers through the Bytecode Alliance's Special Interest Group for Documentation. diff --git a/docs/interfaces.md b/docs/interfaces.md deleted file mode 100644 index dea848d..0000000 --- a/docs/interfaces.md +++ /dev/null @@ -1,187 +0,0 @@ ---- -title: "Interfaces" -sidebar_position: 2 ---- - -## Modules and components - -WebAssembly binaries may be **components** built according to the [Component Model](https://component-model.bytecodealliance.org/) or **modules** built to the core WebAssembly specification. - -As you begin writing a Wasm application using WASI APIs, one of your first decisions will be which type of binary you want to produce—a decision typically guided by your use-case and the runtime you wish to use. Check to see which WASI releases your runtime supports. - -* **Components** can use WASI 0.2 and the Component Model for composability and interoperability, meaning that a WebAssembly component compiled from one language (Rust, for example) can communicate or be combined with a component compiled from another language (such as Go). WASI 0.2 sets the stage for the future of WASI. - -* **Modules** can use APIs from WASI 0.1, an earlier stage of WASI's development. Since WASI 0.2 was released in February 2024, WASI 0.1 support is more widespread among Wasm runtimes, and it is widely used in production today. - -## WASI 0.3 - -WASI 0.3 is a forthcoming WASI release. Where WASI 0.2 represented a major departure from WASI 0.1, WASI 0.3 is a more iterative progression from WASI 0.2. The following draft interfaces are proposed for WASI 0.3: - -| API | Repository | -| ------------ | ---------------------------------------------------------------------------------- | -| Clocks | https://github.com/WebAssembly/WASI/tree/main/proposals/clocks/wit-0.3.0-draft | -| Random | https://github.com/WebAssembly/WASI/tree/main/proposals/random/wit-0.3.0-draft | -| Filesystem | https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem/wit-0.3.0-draft | -| Sockets | https://github.com/WebAssembly/WASI/tree/main/proposals/sockets/wit-0.3.0-draft | -| CLI | https://github.com/WebAssembly/WASI/tree/main/proposals/cli/wit-0.3.0-draft | -| HTTP | https://github.com/WebAssembly/WASI/tree/main/proposals/http/wit-0.3.0-draft | - -For more information on the forthcoming WASI 0.3 release, see the [Roadmap](roadmap.md). - -## WASI 0.2 - -### Presentation - -WASI 0.2 is the most recent WASI release. APIs designed for WASI 0.2 and the Component Model are defined with the [**WebAssembly Interface Type (WIT)**](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) Interface Description Language (IDL). WIT API definitions are made in `.wit` files which are composed into Wasm component binaries. The following interfaces are included in WASI P2: - -| API | Repository | -| ------------ | ------------------------------------------------------------------ | -| Clocks | https://github.com/WebAssembly/WASI/tree/main/proposals/clocks | -| Random | https://github.com/WebAssembly/WASI/tree/main/proposals/random | -| Filesystem | https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem | -| Sockets | https://github.com/WebAssembly/WASI/tree/main/proposals/sockets | -| CLI | https://github.com/WebAssembly/WASI/tree/main/proposals/cli | -| HTTP | https://github.com/WebAssembly/WASI/tree/main/proposals/http | - -You can explore the types and definitions for a given WASI 0.2 API in its WIT files. When you're ready to start using the API, you will typically generate bindings between the WIT definitions and the language you will be compiling to Wasm. For more information on WIT, see the [WIT section of the Component Model documentation](https://component-model.bytecodealliance.org/design/wit.html). - -### Versions - -WASI 0.2 includes several patch releases: - -| Version | Changelog | -| ------------------------------------------------------------------ | --------- | -| [0.2.9](https://github.com/WebAssembly/WASI/releases/tag/v0.2.9) | This release includes a variety of organizational and documentation updates. | -| [0.2.8](https://github.com/WebAssembly/WASI/releases/tag/v0.2.8) | This is a regular release with no major changes. | -| [0.2.7](https://github.com/WebAssembly/WASI/releases/tag/v0.2.7) | This release adds a caveat about support for sync flags. | -| [0.2.6](https://github.com/WebAssembly/WASI/releases/tag/v0.2.6) | This release adds wasi-otel as a phase 0 proposal as well as a release workflow. | -| [0.2.5](https://github.com/WebAssembly/WASI/releases/tag/v0.2.5) | This release includes minor documentation updates. | -| [0.2.4](https://github.com/WebAssembly/WASI/releases/tag/v0.2.4) | This release adds `wasi-tls` in Phase 1. | -| [0.2.3](https://github.com/WebAssembly/WASI/releases/tag/v0.2.3) | This release includes minor documentation updates. | -| [0.2.2](https://github.com/WebAssembly/WASI/releases/tag/v0.2.2) | This release includes new WIT features for `@deprecated` feature gates and is exercised in the [wasi:http/proxy](https://github.com/WebAssembly/wasi-http/blob/main/wit/types.wit#L148-L158) world. For more information, see [component-model/WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates). | -| [0.2.1](https://github.com/WebAssembly/WASI/releases/tag/v0.2.1) | This release includes new WIT features for `@since` and `@unstable` feature gates. For more information, see [component-model/WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates). | -| [0.2.0](https://github.com/WebAssembly/WASI/releases/tag/v0.2.0) | This version officially launched with the vote in the WASI Subgroup January 24th, 2024. | - -For more information on the release model for WASI, see the [Roadmap](roadmap.md). - -## WASI 0.1 - -WASI P1 APIs were defined with WITX Interface Description Language (IDL), which was an iterative step toward WIT but bears notable differences, including that it was developed as a lower-level derivation of WebAssembly Text Format (a human-readable source format for Wasm modules). Documentation for WASI 0.1 and WITX can be found on the [`wasi-0.1` branch of the WASI GitHub repository](https://github.com/WebAssembly/WASI/tree/wasi-0.1), along with a [complete list of 0.1 types and modules](https://github.com/WebAssembly/WASI/blob/wasi-0.1/preview1/docs.md). - -## Proposals for the standard - -All WASI APIs are **proposals** for standardization by the WASI Subgroup. The API proposals in WASI 0.1 and 0.2 met implementation and portability criteria for inclusion at the time of those releases. A proposal advances through the following stages as defined in the [WASI Subgroup's Phase Process](https://github.com/WebAssembly/WASI/blob/main/Contributing.md#the-phase-process): - -* **Phase 0 - Pre-proposal**: The pre-proposal phase serves as a way to share ideas. At this phase, the WASI subgroup has not yet decided that the pre-proposal is in scope for WASI, and there may be overlap between pre-proposals. -* **Phase 1 - Feature proposal**: In this phase, the proposal is added to the proposal list and a new fork of the spec repo is created. -* **Phase 2 - Feature description available**: During this phase, one or more implementations prototype the feature and a test suite is added. -* **Phase 3 - Implementation phase**: At this phase, project champions create releases following the conventions of semantic versioning (semver). -* **Phase 4 - Standardize the feature:** At this point, the feature is fully handed off to the Working Group, where edge cases are considered and only minor changes occur. -* **Phase 5 - The feature is standardized**: Once the Working Group reaches consensus that the feature is complete, editors perform final editorial tweaks and merge the feature into the main branch of the primary spec repo. - -Proposals are first made to the **WASI Subgroup** of the [WebAssembly Community Group](https://www.w3.org/community/webassembly/). (See the [WASI Subgroup's meeting schedule](https://github.com/WebAssembly/meetings/tree/main/wasi).) - -All active WASI API proposals can be found on the [WASI GitHub repository](https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md). See the [Contributing to WASI page](https://github.com/WebAssembly/WASI/blob/main/Contributing.md) for information about submitting a new proposal. - -## Active proposals - -### Phase 5 - The Feature is Standardized (WG) - -| API Proposal | Repository | -| ----------------------------------------------------------------------| -------------------------------------- | - -### Phase 4 - Standardize the Feature (WG) - -| API Proposal | Repository | -| ----------------------------------------------------------------------| -------------------------------------- | - -### Phase 3 - Implementation Phase (CG + WG) - -| API Proposal | Repository | -| --------------------------------------------------------------------- | -------------------------------------- | -| [I/O][wasi-io] | https://github.com/WebAssembly/wasi-io | -| [Clocks][wasi-clocks] | https://github.com/WebAssembly/wasi-clocks | -| [Random][wasi-random] | https://github.com/WebAssembly/wasi-random | -| [Filesystem][wasi-filesystem] | https://github.com/WebAssembly/wasi-filesystem | -| [Sockets][wasi-sockets] | https://github.com/WebAssembly/wasi-sockets | -| [CLI][wasi-cli] | https://github.com/WebAssembly/wasi-cli | -| [HTTP][wasi-http] | https://github.com/WebAssembly/wasi-http | - -### Phase 2 - Proposed Spec Text Available (CG + WG) - -| API Proposal | Repository | -| ----------------------------------------------------- | -------------------------------------------- | -| [Machine Learning (wasi-nn)][wasi-nn] | https://github.com/WebAssembly/wasi-nn | -| [Clocks: Timezone][wasi-clocks] | https://github.com/WebAssembly/wasi-clocks | -| [GFX][wasi-gfx] | https://github.com/WebAssembly/wasi-gfx | - -### Phase 1 - Feature Proposal (CG) - -| API Proposal | Repository | -| ------------------------------------------------------------------------ | -------------------------------------- | -| [Blob Store][wasi-blob-store] | https://github.com/WebAssembly/wasi-blob-store | -| [Crypto][wasi-crypto] | https://github.com/WebAssembly/wasi-crypto | -| [Digital I/O][wasi-digital-io] | https://github.com/WebAssembly/wasi-digital-io | -| [Distributed Lock Service][wasi-distributed-lock-service] | https://github.com/WebAssembly/wasi-distributed-lock-service | -| [I2C][wasi-i2c] | https://github.com/WebAssembly/wasi-i2c | -| [Key-value Store][wasi-kv-store] | https://github.com/WebAssembly/wasi-kv-store | -| [Logging][wasi-logging] | https://github.com/WebAssembly/wasi-logging | -| [Messaging][wasi-messaging] | https://github.com/WebAssembly/wasi-messaging | -| [Observe][wasi-observe] | https://github.com/dylibso/wasi-observe | -| [Parallel][wasi-parallel] | https://github.com/WebAssembly/wasi-parallel | -| [Pattern Match][wasi-pattern-match] | https://github.com/WebAssembly/wasi-pattern-match | -| [Runtime Config][wasi-runtime-config] | https://github.com/WebAssembly/wasi-runtime-config | -| [SPI][wasi-spi] | https://github.com/WebAssembly/wasi-spi | -| [SQL][wasi-sql] | https://github.com/WebAssembly/wasi-sql | -| [SQL Embed][wasi-sql-embed] | https://github.com/WebAssembly/wasi-sql-embed | -| [Threads][wasi-threads] | https://github.com/WebAssembly/wasi-native-threads | -| [URL][wasi-url] | https://github.com/WebAssembly/wasi-url | -| [USB][wasi-usb] | https://github.com/WebAssembly/wasi-usb | - -### Phase 0 - Pre-Proposal (CG) - -| Proposal | Repository | -| -------------------------------------------------------------------------------- | -------------------------------------- | -| [proxy-wasm/spec][wasi-proxy-wasm] (will advance as multiple, smaller proposals) | https://github.com/proxy-wasm/spec | - -## Versioning - -Proposals remain in the 0.x semver range until they reach Phase 5 and are fully standardized. At that point, a 1.0 release should be made available. - -For some APIs, it makes sense to add new features after the API itself has reached Phase 5. These feature additions should go through the same standardization process. Once they have reached Phase 5, the minor version number of the release should be incremented. - -Some APIs may require backwards-incompatible changes over time. In these cases, proposals are allowed to increment the major version number _only if_ the old API can be implmented in terms of the new API. As part of the new version, champions are expected to provide a tool that enables this backwards-compatibility. If that is not possible, then a new API proposal with a new name should be started. The original API can then be deprecated over time if it makes sense to do so. - -[WebAssembly CG Phases process]: https://github.com/WebAssembly/meetings/blob/master/process/phases.md -[witx]: https://github.com/WebAssembly/WASI/blob/main/tools/witx-docs.md -[ephemeral/snapshot/old process]: https://github.com/WebAssembly/WASI/blob/master/phases/README.md - -[wasi-blob-store]: https://github.com/WebAssembly/wasi-blob-store -[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks -[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto -[wasi-data]: https://github.com/singlestore-labs/wasi-data -[wasi-digital-io]: https://github.com/WebAssembly/wasi-digital-io -[wasi-distributed-lock-service]: https://github.com/WebAssembly/wasi-distributed-lock-service -[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem -[wasi-http]: https://github.com/WebAssembly/wasi-http -[wasi-i2c]: https://github.com/WebAssembly/wasi-i2c -[wasi-io]: https://github.com/WebAssembly/wasi-io -[wasi-kv-store]: https://github.com/WebAssembly/wasi-kv-store -[wasi-logging]: https://github.com/WebAssembly/wasi-logging -[wasi-messaging]: https://github.com/WebAssembly/wasi-messaging -[wasi-nn]: https://github.com/WebAssembly/wasi-nn -[wasi-observe]: https://github.com/WebAssembly/wasi-observe -[wasi-parallel]: https://github.com/WebAssembly/wasi-parallel -[wasi-pattern-match]: https://github.com/WebAssembly/wasi-pattern-match -[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec -[wasi-random]: https://github.com/WebAssembly/wasi-random -[wasi-runtime-config]: https://github.com/WebAssembly/wasi-runtime-config -[wasi-sockets]: https://github.com/WebAssembly/wasi-sockets -[wasi-spi]: https://github.com/WebAssembly/wasi-spi -[wasi-sql]: https://github.com/WebAssembly/wasi-sql -[wasi-sql-embed]: https://github.com/WebAssembly/wasi-sql-embed -[wasi-threads]: https://github.com/WebAssembly/wasi-native-threads -[wasi-url]: https://github.com/WebAssembly/wasi-url -[wasi-usb]: https://github.com/WebAssembly/wasi-usb -[wasi-gfx]: https://github.com/WebAssembly/wasi-gfx -[wasi-cli]: https://github.com/WebAssembly/wasi-cli diff --git a/docs/introduction.md b/docs/introduction.md index 21d4062..44c43f7 100644 --- a/docs/introduction.md +++ b/docs/introduction.md @@ -4,11 +4,11 @@ slug: / sidebar_position: 1 --- -The **WebAssembly System Interface (WASI)** is a group of standards-track API specifications for software compiled to the **[W3C WebAssembly (Wasm) standard](https://www.w3.org/TR/wasm-core-2/)**. WASI is designed to provide a secure standard interface for applications that can be compiled to Wasm from any language, and that may run anywhere—from browsers to clouds to embedded devices. +The **WebAssembly System Interface (WASI)** is a group of standards-track API specifications for software compiled to the **[W3C WebAssembly (Wasm) standard](https://www.w3.org/TR/wasm-core-2/)**. WASI is designed to provide a secure standard interface for applications that can be compiled to Wasm from any language, and that may run anywhere, from browsers to clouds to embedded devices. -By standardizing APIs for WebAssembly, WASI provides a way to compose software written in different languages—without costly and clunky interface systems like HTTP-based microservices. We believe that every project with a plugin model should be using WASI, and that WASI is ideally suited for projects with SDKs for multiple languages, e.g. client libraries. +By standardizing APIs for WebAssembly, WASI provides a way to compose software written in different languages without costly and clunky interface systems like HTTP-based microservices. We believe that every project with a plugin model should be using WASI, and that WASI is ideally suited for projects with SDKs for multiple languages, e.g. client libraries. -To date, WASI has seen two milestone releases known as **0.1** and **0.2**. (Sometimes you will see these referred to as Preview 1 and Preview 2, or P1 and P2). The concepts and vocabulary of Wasm and WASI can sometimes be opaque to newcomers, so WASI.dev serves as an introduction to WASI for users of all backgrounds. It's very much a work-in-progress, and we welcome contributions on the [GitHub repo](https://github.com/bytecodealliance/wasi.dev). +To date, WASI has seen three milestone releases known as **P1**, **P2**, and **P3**. (Sometimes you will see these referred to as Preview 1/2/3 or 0.1/0.2/0.3.) WASI P3 adds native async support to the Component Model and refactors WASI interfaces to take advantage of async primitives like `stream` and `future`. For more details, see [WASI P3](releases/wasi-p3.md). ## Who are we? @@ -16,14 +16,18 @@ WASI is an open standard under active development by the [**WASI Subgroup**](htt ## Who are you? -WASI and Wasm are tools for any type of software developer: whether you're writing web apps, plugins, serverless functions, User-Defined Functions (UDFs) in a database, embedded controller components, sidecar networking filters, or something completely different. This site is intended to make WASI understandable regardless of your background, use-case, or familiarity with the WebAssembly ecosystem. +WASI and Wasm are tools for any type of software developer: whether you're writing web apps, plugins, serverless functions, User-Defined Functions (UDFs) in a database, embedded controller components, sidecar networking filters, or something completely different. This site is intended to introduce the concepts and vocabulary of WASI regardless of your background, use-case, or familiarity with the WebAssembly ecosystem. ## How to get started There are many different runtimes that support WASI including [Wasmtime](https://wasmtime.dev/), [WAMR](https://bytecodealliance.github.io/wamr.dev/), [WasmEdge](https://wasmedge.org/), [wazero](https://wazero.io/), [Wasmer](https://wasmer.io/), [wasmi](https://github.com/wasmi-labs/wasmi), [wasm3](https://github.com/wasm3/wasm3), [jco](https://github.com/bytecodealliance/jco) and [pywasm](https://github.com/mohanson/pywasm). Many of these runtimes have different areas of focus (i.e., IoT, embedded devices, and edge for WAMR, server-side and non-web embeddings with components for Wasmtime, and running in JS environments and browsers for Jco). The introductory documentation for each is a great place to start. -WASI can be implemented by both core Wasm modules and applications built according to the **Component Model**, a specification for Wasm applications that are interoperable and composable. You can learn more about components in the Bytecode Alliance's **[WebAssembly Component Model](https://component-model.bytecodealliance.org/)** documentation. +WASI can be implemented by both core Wasm modules and applications built according to the **Component Model**, a specification for Wasm applications that are interoperable and composable. You can learn more about components in the Bytecode Alliance's **[WebAssembly Component Model](https://component-model.bytecodealliance.org/)** documentation. -[Continue reading](./interfaces.md) to learn more about WASI interfaces, including available APIs and how they are defined. +WASI applications run in a **capability-based** sandbox: a Wasm module or component starts with no ambient authority and can only do what the host explicitly grants. See the [Security](./security.md) page for more. + +When you're ready to start building, the [Component Model documentation](https://component-model.bytecodealliance.org/) walks through compiling a first component and running it on Wasmtime or jco, with tutorials for Rust, JavaScript, Python, Go, C, C#, and MoonBit. + +[Continue reading](./releases/) to learn more about WASI releases, including available APIs and how they are defined. diff --git a/docs/languages.md b/docs/languages.md index 96636df..a03b09a 100644 --- a/docs/languages.md +++ b/docs/languages.md @@ -25,10 +25,10 @@ The languages below can be compiled to WebAssembly with WASI support. Some toolc ### Notes -- **Modules vs components.** A Wasm **module** is a single binary in the core WebAssembly format and can use WASI 0.1. A **component** is built to the Component Model and can use WASI 0.2 or 0.3, gaining composability, cross-language interoperability, and richer interface types. See the [Interfaces](interfaces.md) and [Roadmap](roadmap.md) pages for more on the WASI releases. +- **Modules vs components.** A Wasm **module** is a single binary in the core WebAssembly format and can use WASI 0.1. A **component** is built to the Component Model and can use WASI 0.2 or 0.3, gaining composability, cross-language interoperability, and richer interface types. See the [Releases](releases/index.md) and [Roadmap](roadmap.md) pages for more on the WASI releases. - **Adapting modules to components.** Several toolchains produce core modules today and wrap them into components using [`wasm-tools component new`](https://github.com/bytecodealliance/wasm-tools) with a P1-to-P2 adapter. This is the path for C/C++ and MoonBit. - **WASI 0.3 ecosystem state.** Broad language-level P3 support is still landing. The Rust `wasm32-wasip3` target is Tier 3 (nightly only). `jco` ships a `preview3-shim` package with streams support landed and futures support following. Other toolchains have not yet shipped P3 support. -- **Snapshot pinning.** When working with WASI 0.3, all WIT-aware tools must target the same snapshot (currently `0.3.0-rc-2026-03-15`). Mismatches surface as confusing `wrong type` errors at instantiation. +- **Version pinning.** The Component Model defines [canonical interface names](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#-canonical-interface-name) so that components can link across compatible versions, but not all tools support this version-aware linking yet. Until they do, target the same version (`0.3.0`) across all WIT-aware tools. Mismatches surface as confusing `wrong type` errors at instantiation. ### Building guides @@ -44,7 +44,7 @@ For hands-on guides covering setup and a "hello world" per language, see the Com ### Bindings generators -The bindings generators below provide a way to make Wasm function calls using [interfaces](interfaces.md) in a given language. +The bindings generators below provide a way to make Wasm function calls using [interfaces](releases/index.md) in a given language. | From | To | Name | | -------------------- | -------------------- | ------------------------------------------------------------------------------------------------- | diff --git a/docs/releases/index.md b/docs/releases/index.md new file mode 100644 index 0000000..dca3798 --- /dev/null +++ b/docs/releases/index.md @@ -0,0 +1,143 @@ +--- +title: "Releases" +sidebar_position: 2 +--- + +## Modules and components + +WebAssembly binaries may be **components** built according to the [Component Model](https://component-model.bytecodealliance.org/) or **modules** built to the core WebAssembly specification. + +As you begin writing a Wasm application using WASI APIs, one of your first decisions will be which type of binary you want to produce. This decision is typically guided by your use case and the runtime you wish to use. Check to see which WASI releases your runtime supports. + +* **Components** can use WASI P2 or P3 and the Component Model for composability and interoperability, meaning that a WebAssembly component compiled from one language (Rust, for example) can communicate or be combined with a component compiled from another language (such as Go). WASI P3 adds native async support, building on the foundation established in WASI P2. + +* **Modules** can use APIs from WASI P1, an earlier stage of WASI's development. Since WASI P2 was released end of January 2024, WASI P1 support is more widespread among Wasm runtimes, and it is widely used in production today. + +## WASI releases + +| Release | Status | Description | +| ------- | ------ | ----------- | +| [WASI P3](wasi-p3.md) | Stable | Native async support with `async func`, `stream`, and `future` | +| [WASI P2](wasi-p2.md) | Stable | Component Model foundation with WIT interfaces, composability, and cross-language interoperability | +| [WASI P1](wasi-p1.md) | Legacy | POSIX-inspired module API with broad runtime support | + +For more information on release timelines and plans, see the [Roadmap](../roadmap.md). + +## Proposals for the standard + +All WASI APIs are **proposals** for standardization by the WASI Subgroup. The API proposals in WASI P1 and P2 met implementation and portability criteria for inclusion at the time of those releases. A proposal advances through the following stages as defined in the [WASI Subgroup's Phase Process](https://github.com/WebAssembly/WASI/blob/main/Contributing.md#the-phase-process): + +* **Phase 0 - Pre-proposal**: The pre-proposal phase serves as a way to share ideas. At this phase, the WASI subgroup has not yet decided that the pre-proposal is in scope for WASI, and there may be overlap between pre-proposals. +* **Phase 1 - Feature proposal**: In this phase, the proposal is added to the proposal list and a new fork of the spec repo is created. +* **Phase 2 - Feature description available**: During this phase, one or more implementations prototype the feature and a test suite is added. +* **Phase 3 - Implementation phase**: At this phase, project champions create releases following the conventions of semantic versioning (semver). +* **Phase 4 - Standardize the feature:** At this point, the feature is fully handed off to the Working Group, where edge cases are considered and only minor changes occur. +* **Phase 5 - The feature is standardized**: Once the Working Group reaches consensus that the feature is complete, editors perform final editorial tweaks and merge the feature into the main branch of the primary spec repo. + +Proposals are first made to the **WASI Subgroup** of the [WebAssembly Community Group](https://www.w3.org/community/webassembly/). (See the [WASI Subgroup's meeting schedule](https://github.com/WebAssembly/meetings/tree/main/wasi).) + +All active WASI proposals can be found on the [WASI GitHub repository](https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md). See the [Contributing to WASI page](https://github.com/WebAssembly/WASI/blob/main/Contributing.md) for information about submitting a new proposal. + +## WASI test suite + +WASI runtimes are tested against a shared test suite, [`wasi-testsuite`](https://github.com/WebAssembly/wasi-testsuite), which exercises interfaces from WASI P1 and WASI P3 across runtime implementations. The repository includes a test runner with adapters for the major runtimes (Wasmtime, jco, WAMR, and others), and is the shared reference for verifying runtime conformance. + +## Active proposals + +### Phase 5 - The Feature is Standardized (WG) + +| API Proposal | Description | Repository | +| ------------ | ----------- | ---------- | + +### Phase 4 - Standardize the Feature (WG) + +| API Proposal | Description | Repository | +| ------------ | ----------- | ---------- | + +### Phase 3 - Implementation Phase (SG) + +| API Proposal | Description | Repository | +| ----------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------- | +| [I/O][wasi-io] | Streams, pollables, and async wait primitives; removed in WASI P3 | https://github.com/WebAssembly/WASI/tree/main/proposals/io | +| [Clocks][wasi-clocks] | Wall-clock and monotonic-clock access | https://github.com/WebAssembly/WASI/tree/main/proposals/clocks | +| [Random][wasi-random] | Cryptographically secure and insecure random byte generation | https://github.com/WebAssembly/WASI/tree/main/proposals/random | +| [Filesystem][wasi-filesystem] | File and directory operations on preopened directories | https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem | +| [Sockets][wasi-sockets] | TCP and UDP networking, plus DNS resolution | https://github.com/WebAssembly/WASI/tree/main/proposals/sockets | +| [CLI][wasi-cli] | Environment variables, command-line arguments, stdio, and process exit | https://github.com/WebAssembly/WASI/tree/main/proposals/cli | +| [HTTP][wasi-http] | Incoming and outgoing HTTP request and response handling | https://github.com/WebAssembly/WASI/tree/main/proposals/http | + +### Phase 2 - Proposed Spec Text Available (CG + WG) + +| API Proposal | Description | Repository | +| -------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------- | +| [Clocks: Timezone][wasi-clocks] | Timezone-aware datetime conversions and UTC offsets | https://github.com/WebAssembly/WASI/tree/main/proposals/clocks | +| [HTTP: Informational Outbound Response][wasi-http] | 1xx informational response support for outbound HTTP | https://github.com/WebAssembly/WASI/tree/main/proposals/http | +| [I2C][wasi-i2c] | Inter-Integrated Circuit bus access for embedded peripherals| https://github.com/WebAssembly/wasi-i2c | +| [Key-value Store][wasi-kv-store] | CRUD operations against a key-value backend | https://github.com/WebAssembly/wasi-kv-store | +| [Machine Learning (wasi-nn)][wasi-nn] | Inference against pre-trained ML models | https://github.com/WebAssembly/wasi-nn | +| [Runtime Config][wasi-runtime-config] | Read-only access to host-provided configuration values | https://github.com/WebAssembly/wasi-runtime-config | +| [GFX][wasi-gfx] | Cross-platform graphics primitives for surfaces and frames | https://github.com/WebAssembly/wasi-gfx | +| [Messaging][wasi-messaging] | Publish/subscribe and request/reply messaging primitives | https://github.com/WebAssembly/wasi-messaging | + +### Phase 1 - Feature Proposal (CG) + +| API Proposal | Description | Repository | +| --------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------ | +| [Blob Store][wasi-blob-store] | Object-storage operations on containers and blobs | https://github.com/WebAssembly/wasi-blob-store | +| [Crypto][wasi-crypto] | Signatures, hashing, and symmetric encryption primitives | https://github.com/WebAssembly/wasi-crypto | +| [GPIO][wasi-gpio] | General-purpose digital I/O pin control for embedded devices | https://github.com/WebAssembly/wasi-gpio | +| [Distributed Lock Service][wasi-distributed-lock-service] | Distributed locking primitives for coordinating across nodes | https://github.com/WebAssembly/wasi-distributed-lock-service | +| [Logging][wasi-logging] | Structured logging with severity levels | https://github.com/WebAssembly/wasi-logging | +| [Observe][wasi-observe] | Application telemetry plumbing for observability tooling | https://github.com/dylibso/wasi-observe | +| [OTel][wasi-otel] | OpenTelemetry traces, metrics, and logs | https://github.com/calebschoepp/wasi-otel | +| [Parallel][wasi-parallel] | Parallel computation primitives such as map and reduce | https://github.com/WebAssembly/wasi-parallel | +| [Pattern Match][wasi-pattern-match] | Pattern matching against strings using regex-style expressions | https://github.com/WebAssembly/wasi-pattern-match | +| [SPI][wasi-spi] | Serial Peripheral Interface bus access for embedded peripherals | https://github.com/WebAssembly/wasi-spi | +| [SQL][wasi-sql] | Connection-oriented SQL database operations | https://github.com/WebAssembly/wasi-sql | +| [SQL Embed][wasi-sql-embed] | Embedded SQL execution against in-process databases | https://github.com/WebAssembly/wasi-sql-embed | +| [Threads][wasi-threads] | Native thread spawning and synchronization for components | https://github.com/WebAssembly/wasi-native-threads | +| [TLS][wasi-tls] | Transport Layer Security for sockets and other byte streams | https://github.com/WebAssembly/wasi-tls | +| [URL][wasi-url] | URL parsing, construction, and manipulation | https://github.com/WebAssembly/wasi-url | +| [USB][wasi-usb] | USB device enumeration and host communication | https://github.com/WebAssembly/wasi-usb | + +### Phase 0 - Pre-Proposal (CG) + +| Proposal | Description | Repository | +| ------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------- | +| [proxy-wasm/spec][wasi-proxy-wasm] | Plugin interface for proxies and gateways; will advance as multiple smaller proposals | https://github.com/proxy-wasm/spec | + +## Versioning + +Proposals remain in the 0.x semver range until they reach Phase 5 and are fully standardized. At that point, a 1.0 release should be made available. + +[wasi-blob-store]: https://github.com/WebAssembly/wasi-blob-store +[wasi-clocks]: https://github.com/WebAssembly/WASI/tree/main/proposals/clocks +[wasi-crypto]: https://github.com/WebAssembly/wasi-crypto +[wasi-data]: https://github.com/singlestore-labs/wasi-data +[wasi-distributed-lock-service]: https://github.com/WebAssembly/wasi-distributed-lock-service +[wasi-filesystem]: https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem +[wasi-gpio]: https://github.com/WebAssembly/wasi-gpio +[wasi-http]: https://github.com/WebAssembly/WASI/tree/main/proposals/http +[wasi-i2c]: https://github.com/WebAssembly/wasi-i2c +[wasi-io]: https://github.com/WebAssembly/WASI/tree/main/proposals/io +[wasi-kv-store]: https://github.com/WebAssembly/wasi-kv-store +[wasi-logging]: https://github.com/WebAssembly/wasi-logging +[wasi-messaging]: https://github.com/WebAssembly/wasi-messaging +[wasi-nn]: https://github.com/WebAssembly/wasi-nn +[wasi-observe]: https://github.com/WebAssembly/wasi-observe +[wasi-otel]: https://github.com/calebschoepp/wasi-otel +[wasi-parallel]: https://github.com/WebAssembly/wasi-parallel +[wasi-pattern-match]: https://github.com/WebAssembly/wasi-pattern-match +[wasi-proxy-wasm]: https://github.com/proxy-wasm/spec +[wasi-random]: https://github.com/WebAssembly/WASI/tree/main/proposals/random +[wasi-runtime-config]: https://github.com/WebAssembly/wasi-runtime-config +[wasi-sockets]: https://github.com/WebAssembly/WASI/tree/main/proposals/sockets +[wasi-spi]: https://github.com/WebAssembly/wasi-spi +[wasi-sql]: https://github.com/WebAssembly/wasi-sql +[wasi-sql-embed]: https://github.com/WebAssembly/wasi-sql-embed +[wasi-threads]: https://github.com/WebAssembly/wasi-native-threads +[wasi-tls]: https://github.com/WebAssembly/wasi-tls +[wasi-url]: https://github.com/WebAssembly/wasi-url +[wasi-usb]: https://github.com/WebAssembly/wasi-usb +[wasi-gfx]: https://github.com/WebAssembly/wasi-gfx +[wasi-cli]: https://github.com/WebAssembly/WASI/tree/main/proposals/cli diff --git a/docs/releases/wasi-p1.md b/docs/releases/wasi-p1.md new file mode 100644 index 0000000..fc629ad --- /dev/null +++ b/docs/releases/wasi-p1.md @@ -0,0 +1,48 @@ +--- +title: "WASI P1" +sidebar_position: 3 +--- + +WASI P1 (also known as Preview 1, 0.1, or `wasi_snapshot_preview1`) is the original stable WASI release. It provides a POSIX-inspired system interface for core WebAssembly modules and has the broadest runtime support of any WASI version. While WASI 0.2 and now WASI 0.3 represent the future of the standard, WASI P1 remains widely used in production. + +## Overview + +WASI P1 is characterized by three defining features: + +* **POSIX-inspired design.** WASI P1 functions map closely to POSIX equivalents, and error codes are aligned with POSIX errno values. The API uses a global file descriptor table with preopened directories for capability-based sandboxing. + +* **Module-level API.** WASI P1 targets core WebAssembly modules (not components). It is defined as a single flat module (`wasi_snapshot_preview1`) with 45 functions. Callees access the caller's linear memory directly, using raw pointers and a C-like type system. + +* **WITX IDL.** APIs are defined with the WITX Interface Description Language, an iterative step toward WIT that was developed as a lower-level derivation of WebAssembly Text Format. + +## API surface + +WASI P1 provides functions in the following areas: + +| Area | Functions | Description | +| ---- | --------- | ----------- | +| Arguments and environment | `args_get`, `args_sizes_get`, `environ_get`, `environ_sizes_get` | Access to command-line arguments and environment variables | +| Clocks | `clock_res_get`, `clock_time_get` | Wall clock and monotonic clock access | +| File descriptors | `fd_read`, `fd_write`, `fd_seek`, `fd_close`, `fd_sync`, `fd_advise`, `fd_allocate`, `fd_pread`, `fd_pwrite`, `fd_readdir`, `fd_prestat_get`, and others | Reading, writing, and managing open file descriptors | +| Paths | `path_open`, `path_create_directory`, `path_rename`, `path_unlink_file`, `path_symlink`, `path_link`, `path_readlink`, `path_remove_directory` | Filesystem path operations on preopened directories | +| Polling and process | `poll_oneoff`, `proc_exit`, `sched_yield` | Non-blocking I/O polling and process lifecycle | +| Random | `random_get` | Cryptographically secure random bytes | +| Sockets | `sock_accept`, `sock_recv`, `sock_send`, `sock_shutdown` | Limited socket operations (accept only, no listen or connect) | + +## Limitations + +Compared to WASI 0.2 and later releases, WASI P1 has several limitations: + +- **No Component Model support.** WASI P1 targets core Wasm modules, so components cannot use WASI P1 APIs. Modules lack the composability and cross-language interoperability that the Component Model provides. +- **C-oriented type system.** The raw pointer and linear memory approach works naturally for C/C++ and Rust but creates friction for higher-level languages like Python, JavaScript, and Go. +- **Limited networking.** Socket support covers `accept`, `recv`, `send`, and `shutdown`, but does not include `listen` or `connect`. There is no HTTP support. +- **No modularity.** All functions live in a single flat namespace. APIs cannot be versioned or composed independently. + +## Runtime support + +WASI P1 has the broadest runtime support of any WASI version: [Wasmtime](https://wasmtime.dev/), [Wasmer](https://wasmer.io/), [WasmEdge](https://wasmedge.org/), [WAMR](https://bytecodealliance.github.io/wamr.dev/), [wazero](https://wazero.io/), [wasmi](https://github.com/wasmi-labs/wasmi), [wasm3](https://github.com/wasm3/wasm3), Node.js (via the [WASI module](https://nodejs.org/api/wasi.html)), and Deno all provide WASI P1 support. + +## Further reading + +- [WASI P1 documentation](https://github.com/WebAssembly/WASI/tree/wasi-0.1) +- [WASI P1 types and modules](https://github.com/WebAssembly/WASI/blob/wasi-0.1/preview1/docs.md) diff --git a/docs/releases/wasi-p2.md b/docs/releases/wasi-p2.md new file mode 100644 index 0000000..fa16ab0 --- /dev/null +++ b/docs/releases/wasi-p2.md @@ -0,0 +1,68 @@ +--- +title: "WASI P2" +sidebar_position: 2 +--- + +WASI P2 is the most recent stable WASI release. It marked the full rebase of WASI onto the [Component Model](https://component-model.bytecodealliance.org/) and the [WebAssembly Interface Type (WIT)](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md) Interface Description Language, replacing the C-like WITX IDL used in WASI P1. + +## Overview + +The WASI P2 release is characterized by the following key features: + +* **Component Model foundation.** WASI P2 APIs are defined in WIT and consumed as WebAssembly components. This enables modularity, virtualizability (polyfilling one implementation with another), and cross-language interoperability. A component compiled from Rust can communicate or be combined with a component compiled from Go, JavaScript, Python, or any other language with component tooling. + +* **Worlds.** WASI P2 defines two standard worlds: + - `wasi:cli/command` targets command-line programs that export a `run` function, with access to filesystem, environment variables, stdin/stdout/stderr, and other CLI capabilities. + - `wasi:http/proxy` targets HTTP proxies that export an `incoming-handler`, with support for concurrent streaming of multiple HTTP requests. + +* **The `wasi:io` package.** Asynchronous I/O in WASI P2 is modeled through the `wasi:io` package, which provides: + - A `pollable` resource for non-blocking I/O polling across multiple handles + - `input-stream` and `output-stream` abstractions for reading and writing byte data + - A `poll` function for waiting on multiple pollables simultaneously + The `wasi:io` package underpins all other WASI P2 interfaces that perform I/O. In [WASI 0.3](wasi-p3.md), `wasi:io` is removed and replaced by the Component Model's native `stream`, `future`, and `async func` primitives. + +## Interfaces + +APIs designed for WASI P2 are defined in `.wit` files. The following interfaces are included: + +| API | WIT definitions | Description | +| ------------ | ------------------------------------------------------------------ | ----------- | +| I/O | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/io/wit) | Pollable resources, input/output streams, error handling | +| Clocks | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/clocks/wit) | Wall clock and monotonic clock access | +| Random | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/random/wit) | Cryptographically secure and insecure random number generation | +| Filesystem | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/filesystem/wit) | File and directory operations on preopened directories | +| Sockets | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/sockets/wit) | TCP and UDP networking, DNS resolution | +| CLI | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/cli/wit) | Environment variables, arguments, stdin/stdout/stderr, process exit | +| HTTP | [wit](https://github.com/WebAssembly/WASI/tree/main/proposals/http/wit) | HTTP request/response handling for clients and servers | + +You can explore the types and definitions for a given WASI P2 API in its WIT files. When you're ready to start using the API, you will typically generate bindings between the WIT definitions and the language you will be compiling to Wasm. For more information on WIT, see the [WIT section of the Component Model documentation](https://component-model.bytecodealliance.org/design/wit.html). + +## Runtime support + +WASI P2 portability criteria were met by [Wasmtime](https://wasmtime.dev/) and [jco](https://github.com/bytecodealliance/jco), both of which passed the WASI P2 test suite at the time of certification. Other runtimes including [WAMR](https://bytecodealliance.github.io/wamr.dev/) and [WasmEdge](https://wasmedge.org/) have varying levels of WASI P2 support. + +## Patch releases + +WASI P2 includes several patch releases: + +| Version | Changelog | +| ------------------------------------------------------------------ | --------- | +| [0.2.12](https://github.com/WebAssembly/WASI/releases/tag/v0.2.12) | This release stabilizes interfaces for the next release train and removes `CLI: Exit With Code` from Phase 2. | +| [0.2.11](https://github.com/WebAssembly/WASI/releases/tag/v0.2.11) | This release includes filesystem and sockets documentation updates, including specifying `unlink-file-at` in terms of POSIX. | +| [0.2.10](https://github.com/WebAssembly/WASI/releases/tag/v0.2.10) | This release includes documentation updates and release automation tooling. | +| [0.2.9](https://github.com/WebAssembly/WASI/releases/tag/v0.2.9) | This release includes a variety of organizational and documentation updates. | +| [0.2.8](https://github.com/WebAssembly/WASI/releases/tag/v0.2.8) | This is a regular release with no major changes. | +| [0.2.7](https://github.com/WebAssembly/WASI/releases/tag/v0.2.7) | This release adds a caveat about support for sync flags. | +| [0.2.6](https://github.com/WebAssembly/WASI/releases/tag/v0.2.6) | This release adds wasi-otel as a phase 0 proposal as well as a release workflow. | +| [0.2.5](https://github.com/WebAssembly/WASI/releases/tag/v0.2.5) | This release includes minor documentation updates. | +| [0.2.4](https://github.com/WebAssembly/WASI/releases/tag/v0.2.4) | This release adds `wasi-tls` in Phase 1. | +| [0.2.3](https://github.com/WebAssembly/WASI/releases/tag/v0.2.3) | This release includes minor documentation updates. | +| [0.2.2](https://github.com/WebAssembly/WASI/releases/tag/v0.2.2) | This release includes new WIT features for `@deprecated` feature gates and is exercised in the [wasi:http/proxy](https://github.com/WebAssembly/wasi-http/blob/main/wit/types.wit#L148-L158) world. For more information, see [component-model/WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates). | +| [0.2.1](https://github.com/WebAssembly/WASI/releases/tag/v0.2.1) | This release includes new WIT features for `@since` and `@unstable` feature gates. For more information, see [component-model/WIT.md](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#feature-gates). | +| [0.2.0](https://github.com/WebAssembly/WASI/releases/tag/v0.2.0) | This version officially launched with the vote in the WASI Subgroup January 24th, 2024. | + +## Further reading + +- [WASI P2 GitHub repository](https://github.com/WebAssembly/WASI/blob/main/wasip2/README.md) +- [Component Model documentation](https://component-model.bytecodealliance.org/) +- [Roadmap](../roadmap.md) diff --git a/docs/releases/wasi-p3.md b/docs/releases/wasi-p3.md new file mode 100644 index 0000000..84f80d6 --- /dev/null +++ b/docs/releases/wasi-p3.md @@ -0,0 +1,216 @@ +--- +title: "WASI P3" +sidebar_position: 1 +--- + +WASI P3 brings **native async** to WebAssembly components, moving asynchronous functionality that previously lived in the `wasi:io` package down into the Component Model itself. WASI 0.3.0 was released on June 11, 2026. This page provides an overview of what changed in WASI P3 and why. + +## Why native async? + +In WASI P2, asynchronous operations were modeled with the `wasi:io` package, which provided `pollable` resources, `input-stream` and `output-stream` types, and a `poll` function. This system worked well when a component communicated directly with a host or a single peer, but broke down when components were **composed** in a chain. + +Consider a scenario where component A calls component B, which in turn calls the host: + +``` +A → B → Host +``` + +In WASI P2, component B could not forward wake-ups from the host's `pollable` to component A, because `pollable` is a resource scoped to a single component instance. B would have to actively poll just to relay readiness signals. In practice, the wake-up chain gets dropped. This is sometimes called the **sandwich problem**: WASI P2 could express async, but could not compose it across component boundaries. + +WASI P3 solves this by pushing async into the Component Model's Canonical ABI. The runtime owns the scheduling and wake-up propagation, so async works correctly regardless of how many components sit between a producer and a consumer. + +## New primitives + +WASI P3 introduces three primitives built into the Component Model: + +### `async func` + +Functions can now be declared as asynchronous in WIT. The runtime manages scheduling and suspension. + +```wit +// A WASI P3 HTTP handler +handle: async func(request: request) -> result; +``` + +Bindings generators emit language-native async constructs: `async fn` in Rust, `Promise` in JavaScript, coroutines in Python. + +### `stream` + +A typed, asynchronous data channel. Unlike `input-stream` and `output-stream` in WASI P2, a `stream` is a **value** that can be passed across component boundaries. + +```wit +// Reading from stdin in WASI P3 +read-via-stream: func() -> tuple, future>>; +``` + +### `future` + +A single-value async completion. Where WASI P2 used `pollable` resources, WASI P3 uses `future` values. + +```wit +// Writing to stdout in WASI P3 +write-via-stream: func(data: stream) -> future>; +``` + +## Common patterns + +### The stream-plus-future pattern + +A recurring pattern in WASI P3 pairs a `stream` with a `future` that signals completion or error: + +```wit +read-via-stream: func() -> tuple, future>>; +``` + +The stream delivers data incrementally. Once the stream closes, the future resolves to indicate whether the operation completed successfully or encountered an error. This pattern appears in stdin, filesystem reads, TCP receives, and directory listings. + +### The write direction flip + +In WASI P2, write operations gave you an `output-stream` that you wrote into. In WASI P3, the direction is reversed: you **pass in** a `stream` and receive a `future` that resolves when the write completes. This applies to stdout, stderr, filesystem writes, and TCP sends. + +```wit +// WASI P2: get a stream, write to it +get-stdout: func() -> output-stream; + +// WASI P3: pass data in, get a completion future +write-via-stream: func(data: stream) -> future>; +``` + +## Worlds + +WASI P3 defines the following worlds across its core proposals: + +- `wasi:cli/command` targets command-line programs that export an `async func run()`, with access to filesystem, environment variables, stdin/stdout/stderr, exit, and clocks/random/sockets imports. +- `wasi:http/service` targets HTTP servers that export an async `handler`, with imports from clocks, random, cli stdio, and the HTTP client interface. The `service` world replaces `wasi:http/proxy` from WASI P2. +- `wasi:http/middleware` extends `service` by also importing the handler interface, providing first-class support for request-path middleware components. + +Each core proposal additionally exposes an `imports` world (`wasi:cli/imports`, `wasi:sockets/imports`, `wasi:filesystem/imports`, `wasi:clocks/imports`, `wasi:random/imports`) aggregating that package's interfaces for use by other worlds. + +## What changed in each interface + +### `wasi:io` (removed) + +The entire `wasi:io` package has been removed. Its functionality is replaced by the Component Model's native `stream`, `future`, and `async func` primitives. There is no WASI P3 version of `wasi:io`. + +| WASI P2 (`wasi:io`) | WASI P3 (Component Model) | +|------------------------------------|---------------------------------------| +| `resource pollable` | `future` | +| `resource input-stream` | `stream` | +| `resource output-stream` | `stream` (write direction) | +| `poll(list)` | `await` on a future | +| `subscribe()` on resource | return a `future` from the call | +| `start-foo` / `finish-foo` pattern | `foo: async func(...)` | + +### `wasi:http` + +HTTP saw the most dramatic restructuring in WASI P3. + +**Resources dramatically simplified.** The `incoming-request`, `outgoing-request`, `incoming-response`, `outgoing-response`, `incoming-body`, `outgoing-body`, `future-trailers`, `future-incoming-response`, and `response-outparam` resources are all gone, replaced by unified `request` and `response` resources with `stream` bodies and `future` trailers. + +**The handler is now an `async func`:** + +```wit +// WASI P3 handler +handle: async func(request: request) -> result; + +// WASI P3 client +send: async func(request: request) -> result; +``` + +**New worlds.** The `proxy` world has been replaced by `service`. A new `middleware` world both imports and exports the handler, providing first-class support for request-path middleware components. + +**New header error variant.** The `header-error` variant gains `size-exceeded` for headers that exceed the runtime's configured size limit. + +### `wasi:sockets` + +**Interfaces consolidated from 7 to 2.** The `network`, `instance-network`, `tcp`, `tcp-create-socket`, `udp`, and `udp-create-socket` interfaces are consolidated into a unified `types` interface containing both `tcp-socket` and `udp-socket` resources. A separate `ip-name-lookup` interface handles DNS resolution. + +**The `network` resource is removed.** Network access is now granted at the world level. + +**Async operations are simplified.** All `start-connect`/`finish-connect` and `start-listen`/`finish-listen` pairs are replaced with single `async func` calls: + +```wit +connect: async func(remote-address: ip-socket-address) -> result<_, error-code>; +``` + +**TCP `listen` returns a stream of sockets:** + +```wit +listen: func() -> result, error-code>; +``` + +**New error variant.** The `error-code` enum gains `connection-broken` (POSIX `EPIPE`), distinguishing writes that failed because the peer closed the connection from other reset or abort conditions. + +### `wasi:cli` + +stdin, stdout, and stderr use `stream` with the stream-plus-future pattern. The `run` function is now `async`: + +```wit +run: async func() -> result; +``` + +A new shared `types` interface defines the `error-code` enum used across CLI interfaces. + +The `wasi:cli/exit` interface now exposes both `exit(status: result)` and `exit-with-code(status-code: u8)`. The `exit-with-code` function was promoted from Phase 2 into the stable P3 interface in June 2026. + +### `wasi:filesystem` + +Nearly all `descriptor` methods are now `async func`. Streaming reads and writes use the stream-plus-future pattern, and directory listing returns `stream`: + +```wit +read-directory: func() -> tuple, future>>; +``` + +The `error-code` enum gains a catch-all `other(option)` variant for errors not captured by the existing variants. + +### `wasi:clocks` + +Interfaces and types have been renamed to align with POSIX and Rust `std::time` conventions: + +| WASI P2 | WASI P3 | +|----------------|-----------------| +| `wall-clock` | `system-clock` | +| `datetime` | `instant` | + +The `instant` record now uses `s64` for seconds (instead of `u64`), supporting pre-epoch timestamps. + +The `subscribe-instant` and `subscribe-duration` functions (which returned `pollable`) are replaced with `async func` equivalents: + +```wit +wait-until: async func(when: mark); +wait-for: async func(how-long: duration); +``` + +### `wasi:random` + +The `len` parameter is renamed to `max-len` on `get-random-bytes` and `get-insecure-random-bytes`. The rename reflects a semantic change: implementations may return fewer bytes than requested, so callers should loop until they have collected the desired amount. + +## Runtime and tooling support + +WASI P3 support is available in: + +- **[Wasmtime](https://wasmtime.dev/)** Wasmtime 45 runs the latest release candidate today, and Wasmtime 46 will ship WASI 0.3.0 with Component Model Async enabled by default. +- **[jco](https://github.com/bytecodealliance/jco)** for JavaScript environments + +Wasmtime v44 added initial `wasi:tls@0.3.0-draft` support. From v44 onward, `wasmtime serve` can serve P3 components when invoked with `-Sp3 -W component-model-async=y`, automatically falling back to the WASI P2 `wasi:http/proxy` world for components that don't export the P3 `service` world. + +Runtimes verify WASI P3 conformance against the shared [`wasi-testsuite`](https://github.com/WebAssembly/wasi-testsuite). P3 coverage is now running on Wasmtime and jco across Linux, macOS, and Windows. + +## Migrating from WASI P2 + +Migration to WASI P3 is not required in order to use a P3-capable runtime. As noted above, `wasmtime serve` runs both P3 and P2 components from the same binary, dispatching per component. The [roadmap](../roadmap.md) also notes that implementations may polyfill P2 in terms of P3, mapping P2 imports onto native P3 primitives at the host boundary. + +To migrate: + +- Pinning your toolchain to a consistent WASI P3 release. The Component Model defines [canonical interface names](https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#-canonical-interface-name) so that components can link across compatible versions, but not all tools support this version-aware linking yet. Until they do, Wasmtime and the bindings generator (`wit-bindgen` for Rust, `jco` for JavaScript, and so on) should target the same WIT version, `0.3.0`. Mismatches surface as confusing `wrong type` errors at instantiation. +- Replacing `wasi:io` types with their Component Model equivalents (see the [`wasi:io` (removed)](#wasiio-removed) section above for the mapping). +- Switching to the appropriate world: `wasi:cli/command` for CLI programs, `wasi:http/service` for HTTP servers, `wasi:http/middleware` for middleware components. +- Updating `start-foo` / `finish-foo` call sites to use the corresponding `async func` declarations. + +A detailed P2-to-P3 migration guide with working examples is forthcoming in the [Component Model documentation](https://component-model.bytecodealliance.org/). + +## Further reading + +- [WASI releases and proposals](../releases/) +- [Component Model documentation](https://component-model.bytecodealliance.org/) +- [WASI GitHub repository](https://github.com/WebAssembly/WASI) diff --git a/docs/resources.md b/docs/resources.md index f2c9da4..99bbb98 100644 --- a/docs/resources.md +++ b/docs/resources.md @@ -1,25 +1,33 @@ --- title: "Resources" -sidebar_position: 3 +sidebar_position: 5 --- - + The following resources are helpful for those wishing to learn more about WASI and the WebAssembly ecosystem: ## WASI * **[The WASI GitHub repository](https://github.com/WebAssembly/WASI)** +* **[`wasi-testsuite`](https://github.com/WebAssembly/wasi-testsuite)**: shared test suite and runner for WASI runtimes, with adapters for the major implementations and tests covering WASI P1 and WASI P3. + +## WASI P3 + +* **[WASI P3 interfaces](https://github.com/WebAssembly/WASI/tree/main/proposals)** (see the `wit` directory within each proposal) + +## WASI P2 + +* **[WASI P2 GitHub repository](https://github.com/WebAssembly/WASI/blob/main/wasip2/README.md)** -## WASI 0.2 and the Component Model +## The Component Model -* **[WASI 0.2 GitHub repository](https://github.com/WebAssembly/WASI/blob/main/wasip2/README.md)** +* **[The WebAssembly Component Model documentation](https://component-model.bytecodealliance.org/)** * **[The Component Model GitHub repository](https://github.com/WebAssembly/component-model/tree/main)** -* **[The WebAssembly Component Model documentation](https://component-model.bytecodealliance.org/)** * **[The WIT format](https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md)** -## WASI 0.1 +## WASI P1 -* **[WASI 0.1 legacy documentation](https://github.com/WebAssembly/WASI/tree/wasi-0.1)** -* **[WASI 0.1 types and modules](https://github.com/WebAssembly/WASI/blob/wasi-0.1/preview1/docs.md)** +* **[WASI P1 legacy documentation](https://github.com/WebAssembly/WASI/tree/wasi-0.1)** +* **[WASI P1 types and modules](https://github.com/WebAssembly/WASI/blob/wasi-0.1/preview1/docs.md)** ## WebAssembly diff --git a/docs/roadmap.md b/docs/roadmap.md index 2e706b8..554b0e4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,28 +1,26 @@ --- title: "Roadmap" -sidebar_position: 5 +sidebar_position: 4 --- This roadmap is a living document representing projected timelines for WASI releases. Goals and projections are provisional and subject to revision. ## WASI Releases -WASI point releases occur every two months, on the first Thursday of that month, on a **release train model**—a regular cadence in which releases are published regardless of the enhancements and fixes that are "ready for the train." Point releases include smaller features and big fixes, while major features and breaking changes are generally reserved for major versions. +WASI point releases occur every two months, on the first Thursday of that month, on a **release train model**: a regular cadence in which releases are published regardless of the enhancements and fixes that are "ready for the train." Point releases include smaller features and bug fixes, while major features and breaking changes are generally reserved for major versions. -## Upcoming WASI 0.3 releases +## WASI P3 -At this time, WASI 0.3.0 previews are [available in Wasmtime 37+](https://github.com/bytecodealliance/wasmtime) and completion is expected around February 2026. Please see the [notes](https://github.com/WebAssembly/meetings/blob/main/wasi/2025/WASI-10-02.md) from the October 2025 WASI SG meeting for more information. +WASI 0.3.0 was released on June 11, 2026. WASI P3 support is available in [Wasmtime 43+](https://github.com/bytecodealliance/wasmtime) and [jco](https://github.com/bytecodealliance/jco). -WASI 0.3.0 will add **native async support** to the Component Model and refactor WASI 0.2 interfaces to take advantage of native async. +WASI P3 adds **native async support** to the Component Model and refactors WASI P2 interfaces to take advantage of native async primitives: `async func`, `stream`, and `future`. The `wasi:io` package is removed entirely, with its functionality absorbed into the Component Model's Canonical ABI. For a full overview of changes, see [WASI P3](releases/wasi-p3.md). -Native async will enable any component-level function to be implemented and/or called asynchronously, with asynchrony implemented at the level of the [Canonical ABI](https://component-model.bytecodealliance.org/advanced/canonical-abi.html). This includes explicit `stream` and `future` types for use anywhere in function parameters and results. +Implementations may continue to support WASI P2 alongside P3, either by implementing both versions or by virtualizing (polyfilling) P2 in terms of P3. -When WASI 0.3 is launched, implementations may continue to support 0.2, either by implementing 0.3 alongside it, or by virtualizing (polyfilling) 0.2 in terms of 0.3. - -After WASI 0.3.0 is released, a series of incremental and backwards-compatible 0.3.x releases will occur on the release train model. These point releases are expected to include: +Following WASI 0.3.0, a series of incremental and backwards-compatible 0.3.x releases will occur on the release train model. These point releases are expected to include: * **Cancellation** automatically integrated with language idioms -* **Specialization** of `tuple`, `future>>` existing in 0.3.0 +* **Specialization** of `tuple, future>>` existing in 0.3.0 * **Stream optimization** with Canonical ABI built-ins for forwarding/splicing, skipping/writing-zeroes, stream data segment, and lulls * **Caller-supplied buffers** with more zero-copy in more scenarios * **Threads**: first cooperative, then preemptive @@ -33,4 +31,4 @@ You can find more information in the [WebAssembly CG presentation from February The provisional timeline for WASI releases is as follows: -![The WASI timeline projects a P3 release in early 2026](../static/img/wasi-timeline.webp) \ No newline at end of file +![The WASI timeline projects a P3 release in summer 2026](../static/img/wasi-timeline.webp) \ No newline at end of file diff --git a/docs/security.md b/docs/security.md new file mode 100644 index 0000000..52170b2 --- /dev/null +++ b/docs/security.md @@ -0,0 +1,22 @@ +--- +title: "Security" +sidebar_position: 3 +--- + +WASI is built on principles of **capability-based security**. Code running under WASI has no ambient authority: a WebAssembly module or component starts with no access to the outside world and can only perform operations that the host explicitly grants. The host decides what each Wasm binary can see and touch, and that decision is enforced at the runtime boundary. + +This contrasts with the ambient-authority model used by operating systems like Linux or Windows, where a process inherits its user's broad permissions and can reach anything the user can reach (filesystem, network, environment variables) unless additional sandboxing is layered on top. WASI is deny-by-default (or more accurately: no capability handle by default). + +## How capabilities are granted + +The mechanism for granting capabilities differs between modules and components: + +* **WASI P1 modules** import the `wasi_snapshot_preview1` functions but operate only on the resources the runtime hands them at startup, chiefly preopened file descriptors. A module can call `fd_read` but only against the descriptors it has been given, and there is no way to ask for a new one. Capability granting happens at runtime invocation, not in the module binary. +* **WASI P2 components** express capabilities directly in WIT. Each capability (filesystem access, networking, environment, clocks, randomness) is a separate import, and the host instantiates the component with only the imports it has granted. The component's interface contract is the capability surface, and it is statically inspectable in the component binary itself. +* **WASI P3 components** continue to refine this model. Capabilities that P2 required guests to thread explicitly through each call (such as the `wasi:sockets/network` handle passed into `bind`, `connect`, and DNS lookups) are implicit at the world level in P3. The host still grants network access at the world boundary; guests no longer plumb the handle through every operation. + +## What this means in practice + +A WASI binary can only do what its host has agreed to let it do. A component without a filesystem import cannot read files; a component without a network import cannot open sockets; a module without preopened file descriptors cannot reach the filesystem at all. These guarantees hold regardless of what the host process itself is permitted to do, which is what makes WASI sandboxing stronger than typical OS-level process isolation. + +For more on how capabilities are represented in WIT for WASI P2 and P3, see the [Component Model documentation](https://component-model.bytecodealliance.org/). diff --git a/static/img/wasi-timeline.webp b/static/img/wasi-timeline.webp index 6c86adf..f5c3154 100644 Binary files a/static/img/wasi-timeline.webp and b/static/img/wasi-timeline.webp differ