# Technical Documentation: WebAssembly/WASI > ℹī¸ **Provenance:** Multi-Tier Ingestion ¡ [CodeWiki Reference](https://codewiki.google/github.com/WebAssembly/WASI) ### Overview (`README.md`) # WebAssembly System Interface [](https://doi.org/10.5281/zenodo.4323447) The WebAssembly System Interface (WASI) is a set of APIs for WASI being developed for eventual standardization by the WASI Subgroup, which is a subgroup of the WebAssembly Community Group. WASI started with launching what is now called [Preview 1], an API using the witx IDL, and it is now widely used. Its major influences are POSIX and CloudABI. [WASI 0.2] (Preview 2) is a modular collection of APIs defined with the [Wit IDL], incorporating many of the lessons learned from WASI 0.1, including support for a wider range of source languages, modularity, a more expressive type system, and virtualizability. [WASI 0.3] (Preview 3) is the current preview. It builds on [WASI 0.2], replacing the earlier explicit streams and polling interfaces with the component model's native, composable `async` functionality via the `future` and `stream` types. [Preview 1]: https://github.com/WebAssembly/WASI/tree/wasi-0.1 [WASI 0.2]: https://github.com/WebAssembly/WASI/tree/wasi-0.2 [WASI 0.3]: docs/Proposals.md#inclusion-in-wasi-03 [Wit IDL]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md ## Find the APIs Development of each API happens in its own repo, which you can access from the [proposals list](docs/Proposals.md). This repo is for general discussion, as well as documenting how we work and high-level goals. ## Propose a new API If you would like to create a new proposal, get started with our [Contributing guide](CONTRIBUTING.md). All new API proposals should use the new format and the new repo structure that is shown in the [proposal template](https://github.com/WebAssembly/wasi-proposal-template). See the [Wit in WASI](docs/WitInWasi.md) document for more information about using Wit for WASI proposals. --- ### Overview (`.github/scripts/README.md`) # CI Scripts ## cm-features.js Reads the Component Model adoption record in `docs/ComponentModelFeatures.md`, which is the single source of truth for which gated features WASI requires. - `publish.yml` runs it to write the "Component Model features" section of each released `specifications/wasi-/Overview.md`. - `validate-proposals.js` imports `readRecord` from it to build the `wasm-tools validate` feature flags. ```bash # Print the section for a given version node .github/scripts/cm-features.js 0.3.1 ``` ## validate-proposals.js Validates WIT definitions for changed proposals. Used by the CI workflow. ### Prerequisites - Node.js - [Wasm-tools](https://github.com/bytecodealliance/Wasm-tools) - [wit-deps](https://github.com/bytecodealliance/wit-deps) ### Running Locally ```bash # Validate specific proposals by simulating changed files WIT_FILES='["proposals/cli/wit/command.wit"]' node .github/scripts/validate-proposals.js # Validate multiple proposals WIT_FILES='["proposals/cli/wit/command.wit", "proposals/http/wit/worlds.wit"]' node .github/scripts/validate-proposals.js ``` ### Environment Variables | Variable | Description | |----------|-------------| | `WIT_FILES` | JSON array of changed files in `proposals/*/wit/**` | ### What it validates 1. **wit-deps lock** - If `deps.toml` exists, checks that `deps.lock` is up to date 2. **WIT syntax** - Parses WIT files with `Wasm-tools component wit` 3. **Wasm encoding** - Validates Wasm binary encoding with `--Wasm` flag --- ### Overview (`proposals/cli/README.md`) # WASI CLI World A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase wasi-cli is currently in [Phase 3]. [Phase 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg ### Champions - Dan Gohman ### Portability Criteria WASI CLI must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux. WASI CLI must have at least two complete independent implementations. ## Table of Contents - [Introduction](#introduction) - [Goals [or Motivating Use Cases, or Scenarios]](#goals-or-motivating-use-cases-or-scenarios) - [Non-goals](#non-goals) - [API walk-through](#api-walk-through) - [Use case 1](#use-case-1) - [Use case 2](#use-case-2) - [Detailed design discussion](#detailed-design-discussion) - [Should stdout be an `output-stream`?](#should-stdout-be-an-output-stream) - [Should stderr be an `output-stream`?](#should-stderr-be-an-output-stream) - [Should environment variables be arguments to `command`?](#should-environment-variables-be-arguments-to-command) - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) - [References & acknowledgements](#references--acknowledgements) ### Introduction Wasi-cli a [World] proposal for a Command-Line Interface (CLI) environment. It provides APIs commonly available in such environments, such as filesystems and sockets, and also provides command-line facilities such as command-line arguments, environment variables, and stdio. [World]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-worlds ### Goals Wasi-cli aims to be useful for: - Interactive command-line argument programs. - Servers that use filesystems, sockets, and related APIs and expect to be started with a CLI-style command-line. - Stream filters that read from standard input and write to standard output. ### Non-goals Wasi-cli is not aiming to significantly re-imagine the concept of command-line interface programs. While WASI as a whole is exploring ideas such as [Typed Main], wasi-cli sticks to the traditional list-of-strings style command-line arguments. [Typed Main]: https://sunfishcode.github.io/typed-main-wasi-presentation/ ### API walk-through The full API documentation can be found [here](command.md). TODO [Walk through of how someone would use this API.] #### [Use case 1] [Provide example code snippets and diagrams explaining how the API would be used to solve the given problem] #### [Use case 2] [etc.] ### Detailed design discussion #### Should stdout be an `output-stream`? For server use cases, standard output (stdout) is typically used as a log, where it's typically not meaningfully blocking, async, or fallible. It's just a place for the program to send messages to and forget about them. One option would be to give such use cases a dedicated API, which would have a single function to allow printing strings that doesn't return a `result`, meaning it never fails. However, it'd only be a minor simplification in practice, and dedicated cloud or edge use cases should ideally migrate to more specialized worlds than the wasi-cli world anyway, as they can result in much greater simplifications, so this doesn't seem worthwhile. #### Should stderr be an `output-stream`? This is similar to the question for stdout, but for standard error (stderr), it's a little more tempting to do something like this because stderr is used in this logging style by many kinds of applications. However, it seems better overall to keep stderr consistent with stdout, and focus our desires for simplification toward other worlds, which can achieve even greater simplifications. #### Should environment variables be arguments to `command`? Environment variables are useful in some non-cli use cases, so leaving them as separate imports means they can be used from worlds that don't have a `command` entrypoint. ### Stakeholder Interest & Feedback TODO before entering Phase 3. [This should include a list of implementers who have expressed interest in implementing the proposal] ### References & acknowledgements The concept of wasi-cli has been in development for over a year since the proposal is posted here, and many people have contributed ideas that have influenced. Many thanks for valuable feedback and advice in particular from: - Luke Wagner - Pat Hickey --- ### Overview (`proposals/clocks/README.md`) # WASI Clocks A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase WASI-clocks is currently in [Phase 3]. [Phase 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg ### Champions - Dan Gohman ### Portability Criteria WASI clocks must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux. WASI clocks must have at least two complete independent implementations. ## Table of Contents - [WASI Clocks](#wasi-clocks) - [Current Phase](#current-phase) - [Champions](#champions) - [Portability Criteria](#portability-criteria) - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Goals](#goals) - [Non-goals](#non-goals) - [API walk-through](#api-walk-through) - [Measuring elapsed time](#measuring-elapsed-time) - [Telling the current human time:](#telling-the-current-human-time) - [Retrieving the timezone:](#retrieving-the-timezone) - [Detailed design discussion](#detailed-design-discussion) - [What should the type of a timestamp be?](#what-should-the-type-of-a-timestamp-be) - [Considered alternatives](#considered-alternatives) - [Per-process and per-thread clocks](#per-process-and-per-thread-clocks) - [Stakeholder Interest \& Feedback](#stakeholder-interest--feedback) - [References \& acknowledgements](#references--acknowledgements) - [Development](#development) - [Generating imports.md](#generating-importsmd) ### Introduction WASI Clocks is a WASI API for reading the current time and measuring elapsed time. Unlike many clock APIs, WASI Clocks is capability-oriented. Instead of having functions that implicitly reference a clock, WASI Clocks' APIs are passed a clock handle. ### Goals The primary goal of WASI Clocks is to allow users to use WASI programs to read the current time and to measure elapsed time. ### Non-goals WASI Clocks is not aiming to cover date formatting, or modifying the time of a clock. ### API walk-through #### Measuring elapsed time The monotonic clock APIs can be used to measure the elapsed time of a region of code: ```wit default-monotonic-clock: monotonic-clock ``` ```rust let start: Mark = monotonic_clock::now(clock); // some stuff let stop: Mark = monotonic_clock::now(clock); let elapsed: Duration = stop - start; ``` #### Telling the current human time: ```rust let the_current_time = system_clock::now(); println!("it has been {} seconds and {} nanoseconds since the Unix epoch!", the_current_time.seconds, the_current_time.nanoseconds); ``` #### Retrieving the timezone: ```rust let instant: Instant = system_clock::now(); let id = timezone::id(); let offset_h = timezone::utc_offset(instant) as f64 / 3600e9; println!("the timezone is {} at UTC{:+}", id, offset_h); ``` ### Detailed design discussion ### What should the type of a timestamp be? In POSIX, `clock_gettime` uses a single `timespec` type to represent timestamps from all clocks, with two fields: seconds and nanoseconds. However, in applications that just need to measure elapsed time, and don't need to care about absolute time, working with seconds and nanoseconds as separate fields adds extra code size and complexity. For these use cases, a single 64-bit nanoseconds value, which can measure up to about 584 years, is sufficient and simpler. For system time, it's still useful to have both seconds and nanoseconds, both to be able to represent dates in the far future, and to reflect the fact that code working with system time will often want to treat seconds and fractions of seconds differently. And so, this API uses different data types for different types of clocks. ### Considered alternatives #### Per-process and per-thread clocks WASI preview1 included two clocks which measured the CPU time of the current process and the current thread, respectively. These clocks are difficult to implement efficiently in WASI implementations that have multiple wasm instances in the same host process, so they've been omitted from this API. Wasi-libc has support for emulating these clocks, by using the monotonic clock instead, which isn't a technically precise replacement, but is enough to ensure minimal compatibility with existing code. ### Stakeholder Interest & Feedback TODO before entering Phase 3. Preview1 has monotonic and wall clock functions, and they're widely exposed in toolchains. ### References & acknowledgements Many thanks for valuable feedback and advice from: - [Person 1] - [Person 2] - [etc.] ### Development #### Generating imports.md The file `imports.md` is generated using [wit-bindgen](https://github.com/bytecodealliance/wit-bindgen). ```bash wit-bindgen markdown wit --html-in-md --features clocks-timezone ``` --- ### Overview (`proposals/filesystem/README.md`) # WASI filesystem A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase WASI-filesystem is currently in [Phase 3]. [Phase 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg ### Champions - Dan Gohman ### Portability Criteria WASI filesystem must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux. WASI filesystem must have at least two complete independent implementations. ## Table of Contents - [Introduction](#introduction) - [Goals](#goals) - [Non-goals](#non-goals) - [API walk-through](#api-walk-through) - [Use case 1](#use-case-1) - [Use case 2](#use-case-2) - [Detailed design discussion](#detailed-design-discussion) - [[Tricky design choice 1]](#tricky-design-choice-1) - [[Tricky design choice 2]](#tricky-design-choice-2) - [Considered alternatives](#considered-alternatives) - [[Alternative 1]](#alternative-1) - [[Alternative 2]](#alternative-2) - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) - [References & acknowledgements](#references--acknowledgements) ### Introduction WASI filesystem is a WASI API primarily for accessing host filesystems. It has functions for opening, reading, and writing files, and for working with directories. Unlike many filesystem APIs, WASI filesystem is capability-oriented. Instead of having functions that implicitly reference a filesystem namespace, WASI filesystems' APIs are passed a directory handle along with a path, and the path is looked up relative to the given handle, and sandboxed to be resolved within that directory. For more information about sandbox, see [WASI filesystem path resolution](path-resolution.md). WASI filesystem hides some of the surface differences between Windows and Unix-style filesystems, however much of its behavior, including the semantics of path lookup, and the semantics of files, directories, and symlinks, and the constraints on filesystem paths, is host-dependent. WASI filesystem is not intended to be used as a virtual API for accessing arbitrary resources. Unix's "everything is a file" philosophy is in conflict with the goals of supporting modularity and the principle of least authority. Many of the ideas related to doing capability-based filesystem sandboxing with `openat` come from [CloudABI](https://github.com/NuxiNL/cloudabi) and [Capsicum](https://wiki.freebsd.org/Capsicum). ### Goals The primary goal of WASI filesystem is to allow users to use WASI programs to access their existing filesystems in a straightforward and efficient manner. ### Non-goals WASI filesystem is not aiming for deterministic semantics. That would either require restricting it to fully controlled private filesystems, which would conflict with the goal of giving users access to their existing filesystems, or requiring implementations to do a lot of extra work to emulate specific defined behaviors, which would conflict with the goal of being efficient. ### API walk-through #### Opening a file ```rust /// Write "Hello, World" into a file called "greeting.txt" in `dir`. fn write_hello_world_to_a_file(dir: Descriptor) -> Result<(), Errno> { let at_flags = AtFlags::FollowSymlinks; let o_flags = OFlags::Create | OFlags::Trunc; let descriptor_flags = DescriptorFlags::Write; let mode = Mode::Readable; let file = dir.openat(at_flags, "greeting.txt", o_flags, descriptor_flags, mode)?; let message = b"Hello, World\n"; let mut view = &message[..]; let mut offset = 0; while !view.is_empty() { let num_written = file.pwrite(view.to_owned(), 0)?; offset += num_written; view = &view[num_written..]; } // The file descriptor is closed when it's dropped! } ``` Perhaps the biggest change from the preview1 version of openat, called `path_open`, is the removal of the *rights* flags. Preview1 associates a set of flags with every file descriptor enumerating which operations may be performed on it, such as reading, writing, appending, truncating, and many other operations. In practice, this created a lot of ambiguity about how it mapped to POSIX semantics, as it doesn't directly correspond to any feature in POSIX, or in Windows either. The other major change from preview1 is the introduction of the mode argument, which controls the permissions of the generated file. There was no way to control permissions in preview1, so this is new functionality. #### Streaming read from a file TODO #### Reading from a directory fn read_entries(dir: Descriptor) -> Result<(), Errno> { // TODO: Implement this example. } [etc. ### Detailed design discussion #### Should WASI filesystem be case-sensitive, case-insensitive, or platform-dependent? Even just among popular platforms, there are case-sensitive and case-insensitive filesystems in wide use. It would be nice to have an API which presented consistent behavior across platforms, so that applications don't have to worry about subtle differences, and subtle bugs due to those differences. However, implementing case sensitivity on a case-insensitive filesystem, or case-insensitivity on a case-sensitive filesystem, are both tricky to do. One issue is that case insensitivity depends on a Unicode version, so the details can differ between different case-insensitive platforms. Another issue is the WASI filesystem in general can't assume it has exclusive access to the filesystem, so approaches that involve checking for files with names that differ only by case can race with other processes creating new files. ### Considered alternatives #### Fully deterministic filesystem The main tradeoff with full determinism is that it makes it difficult to access existing filesystems that the Wasm runtime doesn't have full control over. This proposal is aiming to address use cases where users have existing filesystems they want to access. ### Stakeholder Interest & Feedback TODO before entering Phase 3. Preview1 has a similar filesystem API, and it's widely exposed in toolchains. ### References & acknowledgements Many thanks for valuable feedback and advice from: - [Person 1] - [Person 2] - [etc.] --- ### Overview (`proposals/http/README.md`) # WASI HTTP A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase wasi-http is currently in [Phase 3](https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg) ### Champions * Pat Hickey * Lann Martin * John VanEnk ### Portability Criteria WASI-http must have at least two complete independent implementations demonstrating embeddability in a production HTTP server context. ### Introduction The WASI-http proposal defines a collection of [interfaces] for sending and receiving HTTP requests and responses. WASI-http additionally defines two [worlds][world]: `wasi:http/service`, which circumscribes an execution environment for a broad category of HTTP services including web applications, API servers, and [proxies]; and `wasi:http/middleware`, for services that forward requests along a chain of handlers. [Interfaces]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-interfaces [World]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-worlds [Proxies]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#intermediaries ### Goals The proposal intends to abstract over HTTP version and transport protocol choices (such as HTTP/1.1, HTTP/2 or HTTP/3) by mapping directly to the abstract [HTTP Semantics], allowing hosts to (mostly) transparently use any of these. The `wasi:http/service` world is meant to be implementable by a wide variety of hosts including Web [service workers], forward- and reverse-[proxies] and [origin servers] by requiring a minimal set of additional runtime support. The `wasi:http/service` world is meant to support flexible auto-scaling ("serverless") execution by moving the core `accept()` loop into the host and allowing the host to dynamically spin up wasm instances in response to arriving requests. The `wasi:http/middleware` world is meant to allow the chaining of HTTP intermediaries to be implemented directly in terms of [Component Model] linking, letting a request flow through a series of handlers on its way to a terminal service while the corresponding response flows back in the opposite direction. [HTTP Semantics]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html [Service Workers]: https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API [Origin Servers]: https://httpwg.org/http-core/draft-ietf-httpbis-semantics-latest.html#origin.server [Component Model]: https://github.com/WebAssembly/component-model/ ### Non-goals WASI-http does not intend to define a more fully-featured cloud execution environment (for this, see the [wasi-cloud-core] proposal). [wasi-cloud-core]: https://github.com/WebAssembly/wasi-cloud-core ### API walk-through The proposal can be understood by first reading the comments of [`worlds.wit`], then [`types.wit`]. [`worlds.wit`]: ./wit/worlds.wit [`types.wit`]: ./wit/types.wit ### Working with the WIT Bindings can be generated from the `wit` directory via: ``` wit-bindgen c wit/ --world service ``` and can be validated and otherwise manipulated via: ``` wasm-tools component wit wit/ ... ``` The `wit/deps` directory contains a live snapshot of the contents of several other WASI proposals upon which this proposal depends. It is automatically updated by running [`wit-deps update`](https://crates.io/crates/wit-deps-cli) in the root directory, which fetches the live contents of the `main` branch of each proposal. As things stabilize, `wit/deps.toml` will be updated to refer to versioned releases. ### References & acknowledgements * This proposal was seeded by and developed in consultation with [proxy-wasm](https://github.com/proxy-wasm/spec). --- ### Overview (`proposals/random/README.md`) # WASI Random A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase WASI-random is currently in [Phase 3]. [Phase 3]: https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg ### Champions - Dan Gohman ### Portability Criteria WASI random must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux. WASI random must have at least two complete independent implementations. ## Table of Contents - [Introduction](#introduction) - [Goals](#goals) - [Non-goals](#non-goals) - [API walk-through](#api-walk-through) - [Use case 1](#use-case-1) - [Use case 2](#use-case-2) - [Detailed design discussion](#detailed-design-discussion) - [[Tricky design choice 1]](#tricky-design-choice-1) - [[Tricky design choice 2]](#tricky-design-choice-2) - [Considered alternatives](#considered-alternatives) - [[Alternative 1]](#alternative-1) - [[Alternative 2]](#alternative-2) - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) - [References & acknowledgements](#references--acknowledgements) ### Introduction WASI Random is a WASI API for obtaining pseudo-random data. ### Goals The primary goals of WASI Random are: - To allow users to use WASI programs to obtain high-quality low-level random data suitable for cryptography. - To allow source languages to enable DoS protection in their hash-maps in host environments that support it. ### Non-goals WASI Random is not aiming to allow programs to handle errors or to query for availability. It always succeeds (though on platforms where randomness is unavailable, programs may fail to be instantiated or may trap). WASI Random is not aiming to be a full DRBG API. Such an API could be considered in WASI, but it should be a separate proposal. WASI Random does not include facilities for feeding entropy back into the system. It is expected that most entropy that applications would observe should also be observable by the host implementation, and so there should be little need to feed it back in. There may be other uses for such an API, but they can be addressed in separate proposals. WASI Random does not have an async API. It is expected to be implemented with a CSPRNG which is expected to be sufficiently seeded. WASI Random does not have an explicit facility for domain separation or personalization messages. If such features are desired, it would make sense to define them as custom sections, rather than program data, so that they could easily be excluded from module caching and possibly also from code signing. This would make sense as a separate proposal. WASI Random does not provide an "entropy API" or a "true random" API directly. The currently expected use cases want a CSPRNG API. WASI Random does not expose an entropy estimation. It is expected to always have sufficient entropy to seed a CSPRNG. WASI Random does not provide any facility for replacing random data with deterministic data. It is intended to be usable in use cases where determinism would break application assumptions. Implementations may have debugging facilities which make this API deterministic, however these should only be used for debugging, and not production use. ### API walk-through #### Main API: getting cryptographically-secure pseudo-random bytes Return a list of cryptographically-secure pseudo-random bytes: ```rust let len: u32 = your_own_code_to_decide_how_many_bytes_you_want(); let bytes: Vec = get_random_bytes(len); ``` #### Main API: getting cryptographically-secure pseudo-random bytes faster Sometimes the bindings for `list` can have some overhead, so another function is available which returns the same data but as a `u64`: ```rust let data: u64 = get_random_u64(); ``` #### Insecure API: Hash-map DoS protection Return a pair of u64's that can be used to initialize a hash implementation: ```rust let init: (u64, u64) = insecure_random(); let combined: u128 = init.0 as u128 | (init.1 as u128 << 64); your_own_code_to_initialize_hash_map(combined); ``` ### Detailed design discussion ### What if the system lacks sufficient entropy during early boot? Randomness APIs which can fail, or which can be "nonblocking" and return incomplete results, are error prone and tend to lead applications to resort to fallbacks which don't tend to be well-tested. CSPRNGs are believed to be good enough that most systems in most situations can provide effectively unlimited random data. The main case where this isn't the case is on systems which have just booted and which have not yet collected sufficient entropy to initialize their CSPRNGs. In these cases, this API is designed with the belief that it's better for implementations to respond to the problem, rather than to pass the responsibility on to applications. ### What should happen on host platforms with weak or broken randomness APIs? It's implementations' responsibility to handle these situations. They may do so by supplementing the host platform APIs with data collected from other sources, they may refuse to run programs that use Random APIs, or if needed, they may trap programs dynamically to prevent programs from continuing to execute with poor data. Implementations are encouraged to perform regular reseeding (if the host platform doesn't already do so). ### Should there be a randomness resource, and should the API take a handle? Programs shouldn't need to be aware of *which* random generator they have, since the data is random and indistinguishable. WASI programs using the Random API will have imports specific to the Random API, because they are distinct from imports used for general-purpose `stream`. ### Should random data be provided as a `stream`? Reusing the `stream` type is tempting, however it's desirable for users of this API to be provided actually random data, and not the contents of arbitrary streams which might be substituted, so it doesn't turn out to be useful to unify this API with `stream`. This also ensures that programs using the Random API can be identified by their imports, as mentioned in the previous question. ### Should the API specify a number of bits of security? Best practices suggest that implementations should provide at least 196 bits of security. However, many host platforms' CSPRNG APIs do not currently document their bits of security, and it doesn't seem desirable to require wasm engines to run their own CSPRNG on a platform which already has one, so for now, the API does not specify a specific number. ### Why is insecure-random a fixed-sized return value? This limits the amount of data that can be obtained through it. Since it's insecure, it's not intended to be used as an alternative to `getrandom`. ### Stakeholder Interest & Feedback TODO before entering Phase 3. Preview1 has a random function, and it's widely exposed in toolchains. ### References & acknowledgements Many thanks for valuable feedback and advice from: - Zach Lym - Luke Wagner - Linux Weekly News' many articles about Linux random APIs including [this one]. [this one]: https://lwn.net/Articles/808575/ --- ### Overview (`proposals/sockets/README.md`) # WASI Sockets A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. ### Current Phase [Phase 3](https://github.com/WebAssembly/WASI/blob/main/docs/Proposals.md#phase-3---implementation-phase-cg--wg) ### Champions - Dave Bakker (@badeend) ### Portability Criteria - At least two independent production implementations. - Implementations available for at least Windows, Linux & MacOS. - A testsuite that passes on the platforms and implementations mentioned above. ## Table of Contents - [Introduction](#introduction) - [Goals](#goals) - [Non-goals](#non-goals) - [API walk-through](#api-walk-through) - [Asynchronous APIs](#asynchronous-apis) - [Use case 1](#use-case-1) - [Use case 2](#use-case-2) - [Detailed design discussion](#detailed-design-discussion) - [Dualstack sockets](#dualstack-sockets) - [Modularity](#modularity) - [POSIX compatibility](#posix-compatibility) - [Why not getaddrinfo?](#why-not-getaddrinfo) - [Security](#security) - [Deferred permission requests](#deferred-permission-requests) - [Considered alternatives](#considered-alternatives) - [[Alternative 1]](#alternative-1) - [[Alternative 2]](#alternative-2) - [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) - [References & acknowledgements](#references--acknowledgements) ### Introduction This proposal adds TCP & UDP sockets and domain name lookup to WASI. It adds the basic BSD socket interface with the intent to enable server and client networking software running on WebAssembly. Unlike BSD sockets, WASI sockets require capability handles to create sockets and perform domain name lookups. On top of capability handles, WASI Socket implementations should implement deny-by-default firewalling. The socket APIs have been split up into standalone protocol-specific WASI modules. Both current and future socket modules can then be tailored to the needs of that specific protocol and progress the standardization process independently. This proposal introduces 4 new WASI modules: - [wasi-ip-name-lookup.wit](./wasi-ip-name-lookup.wit) - [wasi-socket.wit](./wasi-socket.wit) - [wasi-socket-ip.wit](./wasi-socket-ip.wit) - [wasi-socket-tcp.wit](./wasi-socket-tcp.wit) - [wasi-socket-udp.wit](./wasi-socket-udp.wit) ### Goals - Start out as an MVP; add the bare minimum amount of APIs required to create a basic functioning TCP/UDP application. - Toolchains must be able to provide a POSIX compatible interface on top of the functions introduced in this proposal. ### Non-goals - SSL/TLS support - HTTP(S) support - Retrieving network-related information of the executing machine, like: installed network interfaces and the computer hostname. ### API walk-through [Walk through of how someone would use this API.] #### Asynchronous APIs At the moment, WIT has no built-in way of expressing asynchronous operations. To work around this limitation, we split up async functions into two parts: `start-*` and `finish-*`. Desired signature: ``` operation: func(this, the-inputs...) -> future> ``` Temporary workaround: ``` start-operation: func(this, the-inputs...) -> result<_, error-code> finish-operation: func(this) -> result ``` The semantics are as follows: - When `start-*` completes successfully: - The operation should be considered "in progress". - This is the POSIX equivalent of EINPROGRESS. - The socket can be polled for completion of the just started operation, using `wasi-poll`. - Its corresponding `finish-*` function can be called until it returns something other than the `would-block` error code. - When `finish-*` returns anything other than `would-block`: - The asynchronous operation should be considered "finished" (either successful or failed) - Future calls to `finish-*` return the `not-in-progress` error code. - The documented error codes can be returned from either the `start-*` function or the `finish-*` function. Both are equally correct. Runtimes that don't need asynchrony, can simply validate the arguments provided to the `start` function and stash them on their internal socket instance and perform the actual syscall in the `finish` function. Conveniently, sockets only allow one of these `start/finish` asynchronous operation to be active at a time. Example of how to recover blocking semantics in guest code: ```rs // Pseudo code: fn blocking-connect(sock: tcp-socket, addr: ip-socket-address) -> result, error-code> { let pollable = tcp::subscribe(tcp-socket); let start-result = tcp::start-connect(sock, addr); if (start-result is error) { return error; } while (true) { poll::poll-oneoff([ pollable ]); let finish-result = tcp::finish-connect(sock); if (finish-result is NOT error(would-block)) { return finish-result; } } } ``` #### Use case: Wasm module per connection Thanks to the low startup cost of Wasm modules, its feasible for server software with Wasm integration to spawn a Wasm module for each inbound connection. Each module instance is passed only the accepted client socket. This way, all connection handlers are completely isolated from each other. This resembles PHP's "shared nothing" architecture. #### [Use case 2] [Provide example code snippets and diagrams explaining how the API would be used to solve the given problem] ### Detailed design discussion [This section should mostly refer to the .wit.md file that specifies the API. This section is for any discussion of the choices made in the API which don't make sense to document in the spec file itself.] #### Dualstack sockets IPv6 sockets returned by this proposal are never dualstack because that can't easily be implemented in a cross platform manner. If an application wants to serve both IPv4 and IPv6 traffic, it should create two sockets; one for IPv4 traffic and one for IPv6 traffic. This behaviour is deemed acceptable because all existing applications that are truly cross-platform must already handle this scenario. Dualstack support can be part of a future proposal adding it as an opt-in feature. Related issue: [Emulate dualstack sockets in userspace](https://github.com/WebAssembly/WASI/issues/747) #### Modularity This proposal is not POSIX compatible by itself. The BSD sockets interface is highly generic. The same functions have different semantics depending on which kind of socket they're called on. The man-pages are riddled with conditional documentation. If this had been translated 1:1 into a WASI API using Interface Types, this would have resulted in a proliferation of optional parameters and result types. Instead, the sockets API has been split up into protocol-specific modules. All BSD socket functions have been pushed into these protocol-specific modules and tailored to their specific needs. Functions, parameters and flags that did not apply within a specific context have been dropped. A downside of this approach is that functions that do *not* differ per protocol (bind, local_address, connect, shutdown, ...) are duplicated as well. #### POSIX compatibility See [Posix-compatibility.md](./Posix-compatibility.md). #### Why not getaddrinfo? The proposed [wasi-ip-name-lookup](./wasi-ip-name-lookup.wit) module focuses strictly on translating internet domain names to ip addresses and nothing else. Like BSD sockets, `getaddrinfo` is very generic and multipurpose by design. The proposed WASI API is *not*. This eliminates many of the other "hats" getaddrinfo has (and potential security holes), like: - Mapping service names to port numbers (`"https"` -> `443`) - Mapping service names/ports to socket types (`"https"` -> `SOCK_STREAM`) - Network interface name translation (`%eth0` -> `1`) - IP address deserialization (`"127.0.0.1"` -> `Ipv4Address(127, 0, 0, 1)`) - IP address string canonicalization (`"0:0:0:0:0:0:0:1"` -> `"::1"`) - Constants lookup for `INADDR_ANY`, `INADDR_LOOPBACK`, `IN6ADDR_ANY_INIT` and `IN6ADDR_LOOPBACK_INIT`. Many of these functionalities can be shimmed in the libc implementation. Though some require future WASI additions. An example is network interface name translation. That requires a future `if_nametoindex`-like syscall. #### Security Wasm modules can not open sockets by themselves without a network capability handle. Even with capability handles, WASI implementations should deny all network access by default. Access should be granted at the most granular level possible. See [Granting Access](./GrantingAccess.md) for examples. Whenever access is denied, the implementation should return EACCES. This means Wasm modules will get a lot more EACCES errors compared to when running unsandboxed. This might break existing applications that, for example, don't expect creating a TCP client to require special permissions. At the moment there is no way for a Wasm modules to query which network access permissions it has. The only thing it can do, is to just call the WASI functions it needs and see if they fail. #### Deferred permission requests This proposal does not specify how wasm runtimes should handle network permissions. One method could be to let end users declare on the command line which endpoints a wasm component may connect to. Another method could be to somehow let component authors distribute a manifest alongside the component itself, containing the set of permissions that it requires. Both of these examples depend on the network permissions being known and granted upfront. This is not always feasible and that's usually where dynamic permission requests come into play. The most likely contenders for permission prompt interception are: - TCP: `connect` - TCP: `bind` - TCP: `listen` - UDP: `bind` - UDP: `connect` Now, again, this proposal does not specify if/how permission prompts should be implemented. However, it does at least facilitate the ability for runtimes to do so. Since waiting for user input takes an unknowable amount of time, the operations listed above have been made asynchronous. POSIX-compatibility layers can simply synchronously block on the returned `future`s. ### TCP State Machine See [Operational Semantics](./TcpSocketOperationalSemantics.md). ### Considered alternatives [This section is not required if you already covered considered alternatives in the design discussion above.] #### [Alternative 1] [Describe an alternative which was considered, and why you decided against it.] #### [Alternative 2] [etc.] ### Stakeholder Interest & Feedback TODO before entering Phase 3. [This should include a list of implementers who have expressed interest in implementing the proposal] ### References & acknowledgements Many thanks for valuable feedback and advice from: - [Person 1] - [Person 2] - [etc.] --- ### Overview (`proposals/cli/test/README.md`) # Testing guidelines TK fill in testing guidelines ## Installing the tools TK fill in instructions ## Running the tests TK fill in instructions --- ### Overview (`proposals/clocks/test/README.md`) # Testing guidelines TK fill in testing guidelines ## Installing the tools TK fill in instructions ## Running the tests TK fill in instructions --- ### Overview (`proposals/filesystem/test/README.md`) # Testing guidelines TK fill in testing guidelines ## Installing the tools TK fill in instructions ## Running the tests TK fill in instructions --- ### Overview (`proposals/random/test/README.md`) # Testing guidelines TK fill in testing guidelines ## Installing the tools TK fill in instructions ## Running the tests TK fill in instructions --- ### Overview (`proposals/sockets/test/README.md`) # Testing guidelines TK fill in testing guidelines ## Installing the tools TK fill in instructions ## Running the tests TK fill in instructions --- ### Capabilities (`docs/Capabilities.md`) # Capabilities in WASI What is a capability? The Wasm language has no syscall instructions or built-in I/O facilities. To let programs interact with the outside world, Wasm programs can be provided with *capabilities*. There are two main kinds of capabilities in WASI, link-time capabilities and runtime capabilities. ## Link-time capabilities In short, link-time capabilities are functions that you can import that do things. They're called link-time capabilities because the exports that satisfy the imports are chosen at link time. And if someone wants to virtualize those capabilities, or attenuate them to provide a restricted functionality, they may use a component that provides the needed exports and link them in instead, also at link time. Strictly speaking, link-time capabilities in the Wasm component model are *instance imports*. These imports request an already-instantiated instance. Being already instantiated, the instance already has some capabilities of its own that were granted to it at its own link time. Link-time capabilities may also be called *instantiation-time* capabilities, because the linking we're talking about here is the linking that happens as part of instantiation. When these imports are satisfied by the host, the host doesn't need to literally create a new Wasm instance, but from the perspective of the guest it behaves the same way. ## Runtime capabilities In short, runtime capabilities are [handles] that you can pass around that grant access to resources. Handles are first-class, so they can flow anywhere at runtime, and they're unforgeable, so they can be used to pass around access to individual resources without exposing other resources. In programming languages that can't directly manipulate unforgeable references, handles may be exposed to applications in the form of `i32` indices into per-component-instance tables, that conceptually hold the real handles, and the bindings take care of the bookkeeping when handles are passed from one instance to another. ## How should one decide when to use link-time vs. runtime capabilities? If you have use cases that need multiple distinct resources live at the same time, and the ability to dynamically distinguish between them, you'll need runtime capabilities. For example, it's common for programs using filesystem to have multiple files open at once, so files need to be exposed as handles. If you have an API where most use cases will only ever have one resource that gets used, such as a clock API with a "get the time" function where most users will just have one instance of the clock, link-time capabilities can be more convenient to use. There may eventually be situations where an API has been designed to use link-time capabilities, and someone needs to use it with runtime capabilities. In our clock API example, if someone does wish to have multiple distinct clocks at runtime, they'll want handles. In the future, the component model will hopefully help out here, by adding features to allow component instances to be usable as handles, which would allow link-time capabilities to be used as runtime capabilities. [*handles*]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#handle-types --- ### Charter (`docs/Charter.md`) # WebAssembly System Interface Subgroup Charter The System Interface Subgroup is a sub-organization of the [WebAssembly Community Group](https://www.w3.org/community/webassembly/) of the W3C. As such, it is intended that its charter align with that of the CG. In particular, the sections of the [CG charter](https://webassembly.github.io/cg-charter/) relating to [Community and Business Group Process](https://webassembly.github.io/cg-charter/#process), [Contribution Mechanics](https://webassembly.github.io/cg-charter/#contrib), [Transparency](https://webassembly.github.io/cg-charter/#transparency), and [Decision Process](https://webassembly.github.io/cg-charter/#decision) also apply to the Subgroup. ## Goals The mission of this subgroup is to provide a forum for pre-standardization collaboration on a system interface API for WebAssembly programs. ## Scope The Subgroup will consider topics related to system interface APIs, including: - APIs for host filesystems, network stacks, and other resources. - APIs for graphics, audio, input devices - APIs for encryption, format conversion, and other transformations (particularly where hardware acceleration may be available on some platforms) ## Deliverables ### Specifications The Subgroup may produce several kinds of specification-related work output: - Creation of new specifications in standards bodies or working groups (e.g. Wasm WG or TC39) - Creation of new specifications outside of standards bodies (e.g. similar to the LLVM object file format documentation in Wasm tool conventions) ### Non-normative reports The Subgroup may produce non-normative material such as requirements documents, recommendations, and use cases. ### Software The Subgroup may produce software related to Wasm system interface APIs (either as standalone libraries, tooling, or integration of interface-related functionality in existing CG software such as Binaryen or WABT). Capabilities may include: - Libraries implementing external standard APIs in terms of WebAssembly System Interface APIs - Tools for producing code that uses WebAssembly System Interface APIs - Tools for implementing WebAssembly APIs - Tools for debugging programs using WebAssembly System Interface APIs ## Amendments to this Charter and Chair Selection This charter may be amended, and Subgroup Chairs may be selected by vote of the full WebAssembly Community Group. --- ### ComponentModelFeatures (`docs/ComponentModelFeatures.md`) # Component Model features in WASI WASI APIs are defined in terms of the [Component Model], which develops new WIT syntax, types, and canonical ABI functionality behind [gated features]. Stable (`@since`-gated) WASI APIs may only depend on a gated feature after the WASI Subgroup has voted to adopt it, following the process described in [CONTRIBUTING.md](../CONTRIBUTING.md#adopting-component-model-features). This document records which features have been adopted, and the release they were adopted for. Adoption is cumulative: implementing a given WASI version requires the default (ungated) Component Model features, plus every feature adopted in that version and in all earlier ones. Adopting a feature does not mean that any WASI API uses it. It means that WASI APIs in that release and later *may* use it, and that runtimes and toolchains which implement that WASI version must implement the feature regardless of whether it is used yet. ## Adopted features This table is the source for the "Component Model features" section of each released [specification overview](../specifications). | WASI version | Gate | Feature | Adopted | | --- | --- | --- | --- | | 0.2.0 | — | The default (ungated) Component Model features | WASI 0.2 vote (predates this process) | | 0.3.0 | 🔀 | `async` lift/lower, `future` and `stream` | WASI 0.3 vote (predates this process) | | 0.3.1 | đŸ—ēī¸ | The `map` type | [2026-08-06](https://github.com/WebAssembly/meetings/blob/main/wasi/2026/WASI-08-06.md) ([#943](https://github.com/WebAssembly/WASI/issues/943)) | | 0.3.1 | 🏷ī¸ | `implements` and `external-id` annotations on plain-named interface imports and exports | [2026-08-06](https://github.com/WebAssembly/meetings/blob/main/wasi/2026/WASI-08-06.md) ([#942](https://github.com/WebAssembly/WASI/issues/942)) | Features which have not been adopted are listed under [gated features] in the Component Model Explainer. WASI proposals may experiment with them in prerelease versions (such as `0.3.0-rc-*` releases), but stable releases must remain implementable without them. CI enforces this: each changed proposal is encoded to a component and validated with the features in the table above enabled, so a proposal that depends on an un-adopted feature fails validation. [Component Model]: https://github.com/WebAssembly/component-model [gated features]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#gated-features --- ### DesignPrinciples (`docs/DesignPrinciples.md`) ## WASI Design Principles ### Capability-based security WASI is designed with capability-based security principles, using the facilities provided by the Wasm [component model]. All access to external resources is provided by capabilities. There are two kinds of capabilities: - Handles, defined in the [component-model type system], dynamically identify and provide access to resources. They are unforgeable, meaning there's no way for an instance to acquire access to a handle other than to have another instance explicitly pass one to it. - Link-time capabilities, which are functions which require no handle arguments, are used sparingly, in situations where it's not necessary to identify more than one instance of a resource at runtime. Link-time capabilities are *interposable*, so they are still refusable in a capability-based security sense. WASI has no *ambient authorities*, meaning that there are no global namespaces at runtime, and no global functions at link time. [component model]: https://github.com/WebAssembly/component-model [component-model type system]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/Explainer.md#type-definitions Note that this is a different sense of "capability" than [Linux capabilities](http://man7.org/linux/man-pages/man7/capabilities.7.html) or the withdrawn [POSIX capabilities](https://archive.org/details/posix_1003.1e-990310), which are per-process rather than per-resource. ### Interposition Interposition in the context of WASI interfaces is the ability for a Webassembly instance to implement a given WASI interface, and for a consumer WebAssembly instance to be able to use this implementation transparently. This can be used to adapt or attenuate the functionality of a WASI API without changing the code using it. Component model interfaces always support link-time interposition. While WASI APIs are often implemented in hosts, they can also be implemented in Wasm, which may itself be a wrapper around the host. This may be used to implement *attenuation*, providing filtered access to the underlying host-provided functionality. Interposition is sometimes referred to as "virtualization", however we use "interposition" here because the word "virtualization" has several related meanings. ### Compatibility Compatibility with existing applications and libraries, as well as existing host platforms, is important, but will sometimes be in conflict with overall API cleanliness, safety, performance, or portability. Where practical, WASI seeks to keep the WASI API itself free of compatibility concerns, and provides compatibility through libraries, such as WASI libc, and tools. This way, applications which don't require compatibility for compatibility's sake aren't burdened by it. ### Portability Portability is important to WASI, however the meaning of portability will be specific to each API. WASI's modular nature means that engines don't need to implement every API in WASI, so we don't need to exclude APIs just because some host environments can't implement them. We prefer APIs which can run across a wide variety of engines when feasible, but we'll ultimately decide whether something is "portable enough" on an API-by-API basis. ### Modularity WASI will include many interfaces that are not appropriate for every host environment, so WASI uses the component model's worlds mechanism to allow specific sets of APIs to be described which meet the needs of different environments. --- ### HighLevelGoals (`docs/HighLevelGoals.md`) ## WASI High Level Goals (In the spirit of [WebAssembly's High-Level Goals](https://github.com/WebAssembly/design/blob/main/HighLevelGoals.md).) 1. Define a set of portable, modular, runtime-independent, and WebAssembly-native APIs which can be used by WebAssembly code to interact with the outside world. These APIs preserve the essential sandboxed nature of WebAssembly through a [Capability-based] API design. 2. Specify and implement incrementally. Start with a Minimum Viable Product (MVP), then adding additional features, prioritized by feedback and experience. 3. Supplement API designs with documentation and tests, and, when feasible, reference implementations which can be shared between wasm engines. 4. Make a great platform: * Work with WebAssembly tool and library authors to help them provide WASI support for their users. * When being WebAssembly-native means the platform isn't directly compatible with existing applications written for other platforms, design to enable compatibility to be provided by tools and libraries. * Allow the overall API to evolve over time; to make changes to API modules that have been standardized, build implementations of them using libraries on top of new API modules to provide compatibility. [Capability-based]: https://en.wikipedia.org/wiki/Capability-based_security --- ### Proposals (`docs/Proposals.md`) # WASI proposals WASI APIs are developed as proposals. These proposals go through 5 phases of development (following [the WASI Subgroup's Phase Process]). You can learn more about contributing new proposals (and other ways to contribute) in our [Contributing] guide. [the WASI Subgroup's Phase Process]: https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md#the-phase-process [Contributing]: https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md ## Active Proposals ### Phase 5 - The Feature is Standardized (WG) | Proposal | Champion | Versions | | -------- | -------- | -------- | ### Phase 4 - Standardize the Feature (WG) | Proposal | Champion | Versions | | -------- | -------- | -------- | ### Phase 3 - Implementation Phase (CG + WG) | Proposal | Champion | Versions | | ----------------------------- | --------------------------------------------------------------------- | -------- | | [Clocks][wasi-clocks] | Dan Gohman, Colin Murphy | | | [Random][wasi-random] | Dan Gohman, Roman Volosatovs | | | [Filesystem][wasi-filesystem] | Dan Gohman, Victor Adossi | | | [Sockets][wasi-sockets] | Dave Bakker | | | [CLI][wasi-cli] | Dan Gohman, Lann Martin | | | [HTTP][wasi-http] | Pat Hickey, Lann Martin, John VanEnk | | ### Phase 2 - Proposed Spec Text Available (CG + WG) | Proposal | Champion | Versions | | -------------------------------------------------- | --------------------------------------------------------------------- | -------- | | [Clocks: Timezone][wasi-clocks] | Dan Gohman, Colin Murphy | | | [HTTP: Informational Outbound Response][wasi-http] | Pat Hickey, Lann Martin, John VanEnk | | | [I2C][wasi-i2c] | Friedrich Vandenberghe, Merlijn Sebrechts, Maximilian Seidler | | | [Key-value Store][wasi-kv-store] | Jiaxiao Zhou, Dan Chiarlone | | | [Machine Learning (wasi-nn)][wasi-nn] | Andrew Brown and Mingqiu Sun | | | [Runtime Config][wasi-runtime-config] | Jiaxiao Zhou, Dan Chiarlone | | | [WebGPU][wasi-webgpu] | Mendy Berger, Sean Isom | | | [Messaging][wasi-messaging] | Jiaxiao Zhou, Dan Chiarlone, Taylor Thomas. | | ### Phase 1 - Feature Proposal (CG) | Proposal | Champion | Versions | | --------------------------------------------------------- | ------------------------------------------------ | -------- | | [Blob Store][wasi-blob-store] | Jiaxiao Zhou, Dan Chiarlone. | | | [Crypto][wasi-crypto] | Frank Denis and Daiki Ueno | | | [GPIO][wasi-gpio] | Merlijn Sebrechts, Maximilian Seidler | | | [Distributed Lock Service][wasi-distributed-lock-service] | Jiaxiao Zhou, Dan Chiarlone. | | | [Logging][wasi-logging] | Dan Gohman | | | [Observe][wasi-observe] | Caleb Schoepp | | | [Parallel][wasi-parallel] | Andrew Brown | | | [Pattern Match][wasi-pattern-match] | Jianjun Zhu | | | [SPI][wasi-spi] | Merlijn Sebrechts | | | [SQL][wasi-sql] | Jiaxiao Zhou, Dan Chiarlone. | | | [SQL Embed][wasi-sql-embed] | Robin Brown | | | [Threads][wasi-threads] | Alexandru Ene, Marcin Kolny, Andrew Brown | | | [TLS][wasi-tls] | Joel Dice, Dave Bakker, James Sturtevant | | | [URL][wasi-url] | Radu Matei | | | [USB][wasi-usb] | Wouter Hennen, Warre Dujardin, Merlijn Sebrechts | | | [OTel][wasi-otel] | Caleb Schoepp, Andrew Steurer | | ### Phase 0 - Pre-Proposal (CG) **Note:** The pre-proposal phase is simply meant as a way to share ideas. This means that there may be overlap between pre-proposals. It also means that the WASI subgroup has not yet decided that the pre-proposal is in scope for WASI. | Proposal | Champion | Versions | | -------------------------------------------------------------------------------- | ------------- | -------- | ## Inclusion in WASI 0.3 WASI 0.3 (also known as Preview 3, or WASIp3) corresponds to versions numbered `0.3.x` in Wit packages and related identifiers. To be included in WASI 0.3, a proposal must: - Reach phase 3 in [the WASI Subgroup's Phase Process] - Satisfy its own [portability criteria] - Be voted for inclusion by the WASI Subgroup ## Versioning Once a proposal reaches Phase 3, we expect the champions to start creating releases, following the conventions of semantic versioning (semver). Releases for active proposals are linked in the chart above. 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, we allow proposals to increment the major version number _only if_ the old API can be implemented 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. [portability criteria]: https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md#2-feature-description-available-wasi-subgroup [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-gpio]: https://github.com/WebAssembly/wasi-gpio [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-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/dylibso/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-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-tls]: https://github.com/WebAssembly/wasi-tls [wasi-url]: https://github.com/WebAssembly/wasi-url [wasi-usb]: https://github.com/WebAssembly/wasi-usb [wasi-webgpu]: https://github.com/WebAssembly/wasi-webgpu [wasi-cli]: https://github.com/WebAssembly/wasi-cli --- ### Release (`docs/Release.md`) # Release New patch versions of WASI (0.3.x) are released every two months, on the second Tuesday of the month. This schedule is sometimes also referred to as "the WASI release train", since releases are determined by a fixed schedule rather than reaching some feature threshold. The one exception to the WASI 0.3 release train has been WASI 0.3.0, which was part of a one-off vote. For WASI 0.2.1-0.2.12 we also followed a two-monthly release cadence, but with releases happening on the first Tuesday of every two month rather than the second Tuesday. Once we are ready to ship WASI 1.0 we may schedule a one-off release outside the release train again. The release cadence for WASI proposals post 1.0 is still undetermined and may be subject to change. ## Scheduled WASI 0.3 releases 2026-2027 - WASI 0.3.0: 2026-06-11 (one-off release) - WASI 0.3.1: 2026-08-11 - WASI 0.3.2: 2026-10-13 - WASI 0.3.3: 2026-12-08 - WASI 0.3.4: 2027-02-09 - WASI 0.3.5: 2027-04-13 - WASI 0.3.6: 2027-06-08 - WASI 0.3.7: 2027-08-10 - WASI 0.3.8: 2027-10-12 - WASI 0.3.9: 2027-12-14 ## Creating a new release The release process is entirely automated via GitHub Actions. To create a new release, a WASI Co-chair will run the [Release WASI](https://github.com/WebAssembly/WASI/actions/workflows/release.yml) workflow which begin the release process. This process has the following steps: 1. Trigger the Release WASI workflow by running `gh workflow run release.yml -f prev_version=0.3. -f next_version=0.3.`. 1. A PR updating all version numbers is created. This is blocked on CI and review ([example](https://github.com/WebAssembly/WASI/pull/924)). 2. Create a GitHub release by running `gh release create "v0.3." --generate-notes`. If the release adopts new Component Model features, the generated notes must be edited to call them out. See [Component Model features in WASI](ComponentModelFeatures.md). 3. Once the release has been created, a second PR will be automatically created to populate the `specifications/` dir ([example](https://github.com/WebAssembly/WASI/pull/925)). 4. Once this final PR is merged the release process is complete. --- ### WitInWasi (`docs/WitInWasi.md`) # Wit in WASI Starting in Preview2, WASI APIs are defined using the [Wit IDL]. [Wit IDL]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md To set up a git repository, start by cloning the [wasi-proposal-template], renaming the wit file, and adding content and new files as needed. [wasi-proposal-template]: https://github.com/WebAssembly/wasi-proposal-template/ ## Conventions ### Getters TODO: Should we have a recommendation for whether to say `get-` or not? Or maybe even build a concept of getters into wit itself? ## Temporary workarounds The component model specification and implementations are still in development, so at this time some features or planned features in the component model are not ready for use in WASI APIs. Here's a list of those features and what to use for now in their place. ### Value Imports As a temporary workaround for the lack of value imports, link-time authority functions may be used. In place of a value import like this: ```wit /// An example value import. /// /// A description of the value import. values: list ``` Define an `instance` function, like this: ``` /// An example value import. /// /// A description of the value import. /// /// This [represents a value import](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Value_Imports). instance-values: func() -> list ``` If the value type contains any handles, for now specify that calling the function more than once creates new handles each time. It is often desirable to put these functions in their own interface, so that worlds may chose to include or exclude them independently of the rest of the APIs they're associated with. ### Star Imports TODO: Are there specific patterns we should recommend for working around star imports? And add this comment: ```wit /// This [represents a star import](https://github.com/WebAssembly/WASI/blob/main/WasiWitdocs/WitInWasi.md#Star_Imports). ``` To avoid trouble when migrating to star imports in the future, also avoid depending on dynamic keys. ### Dependencies To use types from one package in another, use a `use` declaration: ```wit use clocks.monotonic-clock.{instant, duration} ``` For now, the tooling requires the wit files defining types to be colocated with the wit files using them. The convention for now is to have a "deps" directory underneath the top-level "wit" directory containing copies of any needed wit files. In the future, wit is expected to support an identifier syntax for naming types in other packages. --- --- METRICS --- - Files Extracted: 21 - Estimated Token Budget: ~17463 tokens - Canonical Reference: https://codewiki.google/github.com/WebAssembly/WASI