From 255279cfa0783eaabb5f2b682124a7e7a993cc4a Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Thu, 11 Jun 2026 09:18:17 -0400 Subject: [PATCH 1/3] Promote WASI 0.3 WIT to canonical and collapse 0.3.0-rc/draft to 0.3.0 Remove the 0.2 wit/ directories, rename wit-0.3.0-draft/ to wit/ for each proposal, update deps paths, and collapse 0.3.0-rc-2026-03-15/0.3.0-draft version identifiers to 0.3.0. Update documentation to reflect WASI 0.3: - capture WASI 0.3 inclusion criteria in Proposals.md - treat WASI 0.3 streams as available, not upcoming - replace wasi:http/proxy world with service and middleware - remove obsolete streams workaround and wasi:io references - rewrite POSIX compatibility for 0.3 native async --- .gitignore | 1 - README.md | 18 +- docs/Preview2.md | 95 - docs/Proposals.md | 14 +- docs/WitInWasi.md | 29 +- proposals/cli/command.md | 3144 ----------------- proposals/cli/imports.md | 3130 ---------------- proposals/cli/wit-0.3.0-draft/command.wit | 10 - proposals/cli/wit-0.3.0-draft/deps.lock | 19 - proposals/cli/wit-0.3.0-draft/deps.toml | 4 - proposals/cli/wit-0.3.0-draft/environment.wit | 22 - proposals/cli/wit-0.3.0-draft/exit.wit | 17 - proposals/cli/wit-0.3.0-draft/imports.wit | 34 - proposals/cli/wit-0.3.0-draft/run.wit | 6 - proposals/cli/wit-0.3.0-draft/stdio.wit | 65 - proposals/cli/wit-0.3.0-draft/terminal.wit | 62 - proposals/cli/wit/command.wit | 8 +- proposals/cli/wit/deps.lock | 21 +- proposals/cli/wit/deps.toml | 7 +- proposals/cli/wit/environment.wit | 10 +- proposals/cli/wit/exit.wit | 6 +- proposals/cli/wit/imports.wit | 42 +- proposals/cli/wit/run.wit | 6 +- proposals/cli/wit/stdio.wit | 69 +- proposals/cli/wit/terminal.wit | 26 +- proposals/clocks/imports.md | 233 -- .../wit-0.3.0-draft/monotonic-clock.wit | 48 - proposals/clocks/wit-0.3.0-draft/timezone.wit | 46 - proposals/clocks/wit-0.3.0-draft/world.wit | 11 - proposals/clocks/wit/deps.lock | 4 - proposals/clocks/wit/deps.toml | 1 - proposals/clocks/wit/monotonic-clock.wit | 49 +- .../{wit-0.3.0-draft => wit}/system-clock.wit | 10 +- proposals/clocks/wit/timezone.wit | 75 +- .../clocks/{wit-0.3.0-draft => wit}/types.wit | 6 +- proposals/clocks/wit/wall-clock.wit | 46 - proposals/clocks/wit/world.wit | 10 +- proposals/filesystem/imports.md | 1334 ------- .../filesystem/wit-0.3.0-draft/deps.lock | 4 - .../filesystem/wit-0.3.0-draft/deps.toml | 1 - .../filesystem/wit-0.3.0-draft/preopens.wit | 11 - .../filesystem/wit-0.3.0-draft/types.wit | 658 ---- .../filesystem/wit-0.3.0-draft/world.wit | 9 - proposals/filesystem/wit/deps.lock | 9 +- proposals/filesystem/wit/deps.toml | 1 - proposals/filesystem/wit/preopens.wit | 8 +- proposals/filesystem/wit/types.wit | 280 +- proposals/filesystem/wit/world.wit | 8 +- proposals/http/README.md | 30 +- proposals/http/imports.md | 1541 -------- proposals/http/proxy.md | 1574 --------- proposals/http/wit-0.3.0-draft/deps.lock | 24 - proposals/http/wit-0.3.0-draft/deps.toml | 5 - proposals/http/wit-0.3.0-draft/types.wit | 472 --- proposals/http/wit/deps.lock | 25 +- proposals/http/wit/deps.toml | 1 - proposals/http/wit/handler.wit | 49 - proposals/http/wit/proxy.wit | 50 - proposals/http/wit/types.wit | 606 +--- .../http/{wit-0.3.0-draft => wit}/worlds.wit | 20 +- proposals/io/LICENSE.md | 8 - proposals/io/README.md | 157 - proposals/io/imports.md | 398 --- proposals/io/test/README.md | 11 - proposals/io/wit/error.wit | 34 - proposals/io/wit/poll.wit | 47 - proposals/io/wit/streams.wit | 258 -- proposals/io/wit/world.wit | 10 - proposals/random/imports.md | 96 - .../random/wit-0.3.0-draft/insecure-seed.wit | 27 - proposals/random/wit-0.3.0-draft/insecure.wit | 32 - proposals/random/wit-0.3.0-draft/random.wit | 37 - proposals/random/wit-0.3.0-draft/world.wit | 13 - proposals/random/wit/insecure-seed.wit | 8 +- proposals/random/wit/insecure.wit | 19 +- proposals/random/wit/random.wit | 20 +- proposals/random/wit/world.wit | 10 +- proposals/sockets/Posix-compatibility.md | 8 +- ...pSocketOperationalSemantics-0.3.0-draft.md | 54 - .../sockets/TcpSocketOperationalSemantics.md | 87 +- proposals/sockets/imports.md | 1874 ---------- proposals/sockets/wit-0.3.0-draft/deps.lock | 4 - proposals/sockets/wit-0.3.0-draft/deps.toml | 1 - .../wit-0.3.0-draft/ip-name-lookup.wit | 61 - proposals/sockets/wit-0.3.0-draft/world.wit | 9 - proposals/sockets/wit/deps.lock | 9 +- proposals/sockets/wit/deps.toml | 1 - proposals/sockets/wit/instance-network.wit | 11 - proposals/sockets/wit/ip-name-lookup.wit | 87 +- proposals/sockets/wit/network.wit | 169 - proposals/sockets/wit/tcp-create-socket.wit | 30 - proposals/sockets/wit/tcp.wit | 387 -- .../{wit-0.3.0-draft => wit}/types.wit | 108 +- proposals/sockets/wit/udp-create-socket.wit | 30 - proposals/sockets/wit/udp.wit | 288 -- proposals/sockets/wit/world.wit | 20 +- 96 files changed, 735 insertions(+), 17812 deletions(-) delete mode 100644 docs/Preview2.md delete mode 100644 proposals/cli/command.md delete mode 100644 proposals/cli/imports.md delete mode 100644 proposals/cli/wit-0.3.0-draft/command.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/deps.lock delete mode 100644 proposals/cli/wit-0.3.0-draft/deps.toml delete mode 100644 proposals/cli/wit-0.3.0-draft/environment.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/exit.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/imports.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/run.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/stdio.wit delete mode 100644 proposals/cli/wit-0.3.0-draft/terminal.wit delete mode 100644 proposals/clocks/imports.md delete mode 100644 proposals/clocks/wit-0.3.0-draft/monotonic-clock.wit delete mode 100644 proposals/clocks/wit-0.3.0-draft/timezone.wit delete mode 100644 proposals/clocks/wit-0.3.0-draft/world.wit delete mode 100644 proposals/clocks/wit/deps.lock delete mode 100644 proposals/clocks/wit/deps.toml rename proposals/clocks/{wit-0.3.0-draft => wit}/system-clock.wit (90%) rename proposals/clocks/{wit-0.3.0-draft => wit}/types.wit (55%) delete mode 100644 proposals/clocks/wit/wall-clock.wit delete mode 100644 proposals/filesystem/imports.md delete mode 100644 proposals/filesystem/wit-0.3.0-draft/deps.lock delete mode 100644 proposals/filesystem/wit-0.3.0-draft/deps.toml delete mode 100644 proposals/filesystem/wit-0.3.0-draft/preopens.wit delete mode 100644 proposals/filesystem/wit-0.3.0-draft/types.wit delete mode 100644 proposals/filesystem/wit-0.3.0-draft/world.wit delete mode 100644 proposals/http/imports.md delete mode 100644 proposals/http/proxy.md delete mode 100644 proposals/http/wit-0.3.0-draft/deps.lock delete mode 100644 proposals/http/wit-0.3.0-draft/deps.toml delete mode 100644 proposals/http/wit-0.3.0-draft/types.wit delete mode 100644 proposals/http/wit/handler.wit delete mode 100644 proposals/http/wit/proxy.wit rename proposals/http/{wit-0.3.0-draft => wit}/worlds.wit (92%) delete mode 100644 proposals/io/LICENSE.md delete mode 100644 proposals/io/README.md delete mode 100644 proposals/io/imports.md delete mode 100644 proposals/io/test/README.md delete mode 100644 proposals/io/wit/error.wit delete mode 100644 proposals/io/wit/poll.wit delete mode 100644 proposals/io/wit/streams.wit delete mode 100644 proposals/io/wit/world.wit delete mode 100644 proposals/random/imports.md delete mode 100644 proposals/random/wit-0.3.0-draft/insecure-seed.wit delete mode 100644 proposals/random/wit-0.3.0-draft/insecure.wit delete mode 100644 proposals/random/wit-0.3.0-draft/random.wit delete mode 100644 proposals/random/wit-0.3.0-draft/world.wit delete mode 100644 proposals/sockets/TcpSocketOperationalSemantics-0.3.0-draft.md delete mode 100644 proposals/sockets/imports.md delete mode 100644 proposals/sockets/wit-0.3.0-draft/deps.lock delete mode 100644 proposals/sockets/wit-0.3.0-draft/deps.toml delete mode 100644 proposals/sockets/wit-0.3.0-draft/ip-name-lookup.wit delete mode 100644 proposals/sockets/wit-0.3.0-draft/world.wit delete mode 100644 proposals/sockets/wit/instance-network.wit delete mode 100644 proposals/sockets/wit/network.wit delete mode 100644 proposals/sockets/wit/tcp-create-socket.wit delete mode 100644 proposals/sockets/wit/tcp.wit rename proposals/sockets/{wit-0.3.0-draft => wit}/types.wit (94%) delete mode 100644 proposals/sockets/wit/udp-create-socket.wit delete mode 100644 proposals/sockets/wit/udp.wit diff --git a/.gitignore b/.gitignore index a94effbf9..6cc6db52b 100644 --- a/.gitignore +++ b/.gitignore @@ -3,7 +3,6 @@ tmp/ # wit-deps vendored dependencies proposals/*/wit/deps/ -proposals/*/wit-0.3.0-draft/deps/ # Lock files wkg.lock \ No newline at end of file diff --git a/README.md b/README.md index 27365e258..edfa93f4f 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ # WebAssembly System Interface [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4323447.svg)](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 @@ -13,14 +13,18 @@ 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 Preview 2] is now stable, and is a modular collection of -APIs defined with the [Wit IDL], and it incorporates many of the lessons -learned from Preview 1, including adding support for a wider range of -source languages, modularity, a more expressive type system, -virtualizability, and more. +[WASI 0.2] is a modular collection of APIs defined with the [Wit IDL], +incorporating many of the lessons learned from Preview 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 Preview 2]: https://github.com/WebAssembly/WASI/blob/main/docs/Preview2.md +[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 diff --git a/docs/Preview2.md b/docs/Preview2.md deleted file mode 100644 index 3ff1b003b..000000000 --- a/docs/Preview2.md +++ /dev/null @@ -1,95 +0,0 @@ -# WASI Preview 2 - -## Introduction - -WASI Preview 2 represents a major milestone for WASI. It marks the moment -when WASI has fully rebased on the [Wit IDL] and the [component model] -type system and semantics, making it modular, fully virtualizable, and -accessible to a wide variety of source languages. - -WASI Preview 2 is also known as “WASI 0.2”, and corresponds to versions -numbered `0.2.x` in Wit packages and related identifiers. It is also known as -“WASIp2”, where the “p” stands for either “preview” or “point”. - -[Wit IDL]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md -[component model]: https://github.com/WebAssembly/component-model - -## WASI Preview 2 Contents - -WASI Preview 2 contains the following APIs: - -| Proposal | Version | -|-------------------|---------| -| [wasi-io] | 0.2.8 | -| [wasi-clocks] | 0.2.8 | -| [wasi-random] | 0.2.8 | -| [wasi-filesystem] | 0.2.8 | -| [wasi-sockets] | 0.2.8 | -| [wasi-cli] | 0.2.8 | -| [wasi-http] | 0.2.8 | - -[wasi-io]: https://github.com/WebAssembly/wasi-io -[wasi-clocks]: https://github.com/WebAssembly/wasi-clocks -[wasi-random]: https://github.com/WebAssembly/wasi-random -[wasi-filesystem]: https://github.com/WebAssembly/wasi-filesystem -[wasi-sockets]: https://github.com/WebAssembly/wasi-sockets -[wasi-cli]: https://github.com/WebAssembly/wasi-cli -[wasi-http]: https://github.com/WebAssembly/wasi-http - -## WASI Preview 2 Implementations - -The portability criteria of the WASI Preview 2 proposals were met by the -following implementations, which were demonstrated to be interoperable by -each passing [Wasmtime's WASI Preview 2 test suite][test-suite]. - -[test-suite]: https://github.com/bytecodealliance/wasmtime/blob/main/crates/test-programs/README.md - -* [Wasmtime] -* [JCO] - -[Wasmtime]: https://github.com/BytecodeAlliance/wasmtime -[JCO]: https://github.com/BytecodeAlliance/jco - -We plan to promote the Preview 2 test suite to live in the [wasi-testsuite] -project soon, and add more interoperable implementations to this list when -they are complete. - -[wasi-testsuite]: https://github.com/WebAssembly/wasi-testsuite - -## Proposal requirements for inclusion in WASI Preview 2. - -To be included in Preview 2, a proposal must: - - - Reach phase 3 in the [WASI Subgroup Phase Process] - - Satisfy its own [portability criteria] - - Be voted for inclusion by the WASI Subgroup - -Proposals may be added to WASI Preview 2 at any time until WASI Preview 3 -is launched. - -## Witx and Wit - -Witx files can be derived from Wit files according to the Canonical ABI. Wasm -engines can implement single-module components using just these derived Witx files -and their existing Witx machinery. - -## Looking forward to Preview 3 - -The component model is expected to add `future` and `stream` keywords, which -will provide integrated and composable `async` functionality. WASI Preview 3 is -planned to be a major revision of the Preview 2 APIs using these new features -in place of wasi-io's streams and polling interfaces. It's also expected to -incorporate lessons learned from implementation and user experience with -Preview 2. - -When Preview 3 is launched, implementations may continue to support Preview 2, -either by implementing Preview 3 along side it, or by virtualizing (polyfilling) -Preview 2 in terms of Preview 3. - -The release criteria of Preview 3 will include that performance will be measured -and addressed. - -[WASI Subgroup Phase Process]: https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md#the-phase-process -[portability criteria]: https://github.com/WebAssembly/WASI/blob/main/CONTRIBUTING.md#2-feature-description-available-wasi-subgroup -[worlds]: https://github.com/WebAssembly/component-model/blob/main/design/mvp/WIT.md#wit-worlds -[launch criteria]: #wasi-preview-2-launch-criteria diff --git a/docs/Proposals.md b/docs/Proposals.md index aeeeb3619..0694d2ddc 100644 --- a/docs/Proposals.md +++ b/docs/Proposals.md @@ -23,7 +23,6 @@ You can learn more about contributing new proposals (and other ways to contribut | Proposal | Champion | Versions | | ----------------------------- | --------------------------------------------------------------------- | -------- | -| [I/O][wasi-io] | Dan Gohman | | | [Clocks][wasi-clocks] | Dan Gohman, Colin Murphy | | | [Random][wasi-random] | Dan Gohman, Roman Volosatovs | | | [Filesystem][wasi-filesystem] | Dan Gohman, Victor Adossi | | @@ -73,6 +72,17 @@ You can learn more about contributing new proposals (and other ways to contribut | -------------------------------------------------------------------------------- | ------------- | -------- | | [proxy-wasm/spec][wasi-proxy-wasm] (will advance as multiple, smaller proposals) | Piotr Sikora | | | +## 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. @@ -83,6 +93,7 @@ For some APIs, it makes sense to add new features after the API itself has reach 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 @@ -95,7 +106,6 @@ Some APIs may require backwards-incompatible changes over time. In these cases, [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 diff --git a/docs/WitInWasi.md b/docs/WitInWasi.md index 59e8e09e8..f6605f86a 100644 --- a/docs/WitInWasi.md +++ b/docs/WitInWasi.md @@ -23,33 +23,6 @@ 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. -### Streams - -Streams are expected to be available in the Preview 3 timeframe, as part of the -[Component Model async proposal]. - -As a temporary workaround for use cases that need byte streams, [use] the -`input-stream` and `output-stream` types defined in [wasi-io]. - -```wit -use io.streams.{input-stream, output-stream} -``` - -For use cases that need typed streams, another option is to define a [resource] -with a function returning `option` or `result, E>` for returning -the elements with `none` indicating the end of the stream. - -This resource-based workaround can be used for asynchronous I/O by using -[wasi-io] to poll for multiple streams, however it doesn't support -composing asynchronous work across multiple components, and it has some scaling -limitations. These limitations will be fixed when built in `stream` types are -available. - -[Component Model async proposal]: https://docs.google.com/presentation/d/1MNVOZ8hdofO3tI0szg_i-Yoy0N2QPU2C--LzVuoGSlE/edit#slide=id.g1270ef7d5b6_0_662 -[use]: #Dependencies -[wasi-io]: https://github.com/WebAssembly/wasi-io -[resource]: #Resources - ### Value Imports As a temporary workaround for the lack of value imports, link-time authority @@ -100,7 +73,7 @@ depending on dynamic keys. To use types from one package in another, use a `use` declaration: ```wit -use io.streams.{input-stream, output-stream} +use clocks.monotonic-clock.{instant, duration} ``` For now, the tooling requires the wit files defining types to be colocated with diff --git a/proposals/cli/command.md b/proposals/cli/command.md deleted file mode 100644 index 28c498c2d..000000000 --- a/proposals/cli/command.md +++ /dev/null @@ -1,3144 +0,0 @@ -

World command

- -

Import interface wasi:cli/environment@0.2.12

-
-

Functions

-

get-environment: func

-

Get the POSIX-style environment variables.

-

Each environment variable is provided as a pair of string variable names -and string value.

-

Morally, these are a value import, but until value imports are available -in the component model, this import function should return the same -values each time it is called.

-
Return values
-
    -
  • list<(string, string)>
    • -
-

get-arguments: func

-

Get the POSIX-style arguments to the program.

-
Return values
-
    -
  • list<string>
    • -
-

initial-cwd: func

-

Return a path that programs should use as their initial current working -directory, interpreting . as shorthand for this.

-
Return values
-
    -
  • option<string>
    • -
-

Import interface wasi:cli/exit@0.2.12

-
-

Functions

-

exit: func

-

Exit the current instance and any linked instances.

-
Params
-
    -
  • status: result
    • -
-

exit-with-code: func

-

Exit the current instance and any linked instances, reporting the -specified status code to the host.

-

The meaning of the code depends on the context, with 0 usually meaning -"success", and other values indicating various types of failure.

-

This function does not return; the effect is analogous to a trap, but -without the connotation that something bad has happened.

-
Params
-
    -
  • status-code: u8
    • -
-

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:cli/stdin@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

-

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:cli/stdout@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stderr: func

-
Return values
- -

Import interface wasi:cli/terminal-input@0.2.12

-

Terminal input.

-

In the future, this may include functions for disabling echoing, -disabling input buffering so that keyboard events are sent through -immediately, querying supported features, and so on.

-
-

Types

-

resource terminal-input

-

The input side of a terminal.

-

Import interface wasi:cli/terminal-output@0.2.12

-

Terminal output.

-

In the future, this may include functions for querying the terminal -size, being notified of terminal size changes, querying supported -features, and so on.

-
-

Types

-

resource terminal-output

-

The output side of a terminal.

-

Import interface wasi:cli/terminal-stdin@0.2.12

-

An interface providing an optional terminal-input for stdin as a -link-time authority.

-
-

Types

-

type terminal-input

-

terminal-input

-

-

-

Functions

-

get-terminal-stdin: func

-

If stdin is connected to a terminal, return a terminal-input handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:cli/terminal-stdout@0.2.12

-

An interface providing an optional terminal-output for stdout as a -link-time authority.

-
-

Types

-

type terminal-output

-

terminal-output

-

-

-

Functions

-

get-terminal-stdout: func

-

If stdout is connected to a terminal, return a terminal-output handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:cli/terminal-stderr@0.2.12

-

An interface providing an optional terminal-output for stderr as a -link-time authority.

-
-

Types

-

type terminal-output

-

terminal-output

-

-

-

Functions

-

get-terminal-stderr: func

-

If stderr is connected to a terminal, return a terminal-output handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:clocks/timezone@0.2.12

-
-

Types

-

type datetime

-

datetime

-

-

record timezone-display

-

Information useful for displaying the timezone of a specific datetime.

-

This information may vary within a single timezone to reflect daylight -saving time adjustments.

-
Record Fields
-
    -
  • -

    utc-offset: s32

    -

    The number of seconds difference between UTC time and the local -time of the timezone. -

    The returned value will always be less than 86400 which is the -number of seconds in a day (246060).

    -

    In implementations that do not expose an actual time zone, this -should return 0.

    -
    • -
  • -

    name: string

    -

    The abbreviated name of the timezone to display to a user. The name -`UTC` indicates Coordinated Universal Time. Otherwise, this should -reference local standards for the name of the time zone. -

    In implementations that do not expose an actual time zone, this -should be the string UTC.

    -

    In time zones that do not have an applicable name, a formatted -representation of the UTC offset may be returned, such as -04:00.

    -
    • -
  • -

    in-daylight-saving-time: bool

    -

    Whether daylight saving time is active. -

    In implementations that do not expose an actual time zone, this -should return false.

    -
    • -
-
-

Functions

-

display: func

-

Return information needed to display the given datetime. This includes -the UTC offset, the time zone name, and a flag indicating whether -daylight saving time is active.

-

If the timezone cannot be determined for the given datetime, return a -timezone-display for UTC with a utc-offset of 0 and no daylight -saving time.

-
Params
- -
Return values
- -

utc-offset: func

-

The same as display, but only return the UTC offset.

-
Params
- -
Return values
-
    -
  • s32
    • -
-

Import interface wasi:filesystem/types@0.2.12

-

WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.

-

It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.

-

Paths are passed as interface-type strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.

-

The directory separator in WASI is always the forward-slash (/).

-

All paths in WASI are relative paths, and are interpreted relative to a -descriptor referring to a base directory. If a path argument to any WASI -function starts with /, or if any step of resolving a path, including -.. and symbolic link steps, reaches a directory outside of the base -directory, or reaches a symlink to an absolute or rooted path in the -underlying filesystem, the function fails with error-code::not-permitted.

-

For more information about WASI path resolution and sandboxing, see -WASI filesystem path resolution.

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type error

-

error

-

-

type datetime

-

datetime

-

-

type filesize

-

u64

-

File size or length of a region within a file. -

enum descriptor-type

-

The type of a filesystem object referenced by a descriptor.

-

Note: This was called filetype in earlier versions of WASI.

-
Enum Cases
-
    -
  • -

    unknown

    -

    The type of the descriptor or file is unknown or is different from -any of the other types specified. -

    • -
  • -

    block-device

    -

    The descriptor refers to a block device inode. -

    • -
  • -

    character-device

    -

    The descriptor refers to a character device inode. -

    • -
  • -

    directory

    -

    The descriptor refers to a directory inode. -

    • -
  • -

    fifo

    -

    The descriptor refers to a named pipe. -

    • -
  • -

    symbolic-link

    -

    The file refers to a symbolic link inode. -

    • -
  • -

    regular-file

    -

    The descriptor refers to a regular file inode. -

    • -
  • -

    socket

    -

    The descriptor refers to a socket. -

    • -
-

flags descriptor-flags

-

Descriptor flags.

-

Note: This was called fdflags in earlier versions of WASI.

-
Flags members
-
    -
  • -

    read:

    -

    Read mode: Data can be read. -

    • -
  • -

    write:

    -

    Write mode: Data can be written to. -

    • -
  • -

    file-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O file -integrity completion. The data stored in the file and the file's -metadata are synchronized. This is similar to `O_SYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    data-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O data -integrity completion. Only the data stored in the file is -synchronized. This is similar to `O_DSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    requested-write-sync:

    -

    Requests that reads be performed at the same level of integrity -requested for writes. This is similar to `O_RSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    mutate-directory:

    -

    Mutating directories mode: Directory contents may be mutated. -

    When this flag is unset on a descriptor, operations using the -descriptor which would create, rename, delete, modify the data or -metadata of filesystem objects, or obtain another handle which -would permit any of those, shall fail with error-code::read-only if -they would otherwise succeed.

    -

    This may only be set on directories.

    -
    • -
-

flags path-flags

-

Flags determining the method of how paths are resolved.

-
Flags members
-
    -
  • symlink-follow:

    As long as the resolved path corresponds to a symbolic link, it is -expanded. -

    • -
-

flags open-flags

-

Open flags used by open-at.

-
Flags members
-
    -
  • -

    create:

    -

    Create file if it does not exist, similar to `O_CREAT` in POSIX. -

    • -
  • -

    directory:

    -

    Fail if not a directory, similar to `O_DIRECTORY` in POSIX. -

    • -
  • -

    exclusive:

    -

    Fail if file already exists, similar to `O_EXCL` in POSIX. -

    • -
  • -

    truncate:

    -

    Truncate file to size 0, similar to `O_TRUNC` in POSIX. -

    • -
-

type link-count

-

u64

-

Number of hard links to an inode. -

record descriptor-stat

-

File attributes.

-

Note: This was called filestat in earlier versions of WASI.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    File type. -

    • -
  • -

    link-count: link-count

    -

    Number of hard links to the file. -

    • -
  • -

    size: filesize

    -

    For regular files, the file size in bytes. For symbolic links, the -length in bytes of the pathname contained in the symbolic link. -

    • -
  • -

    data-access-timestamp: option<datetime>

    -

    Last data access timestamp. -

    If the option is none, the platform doesn't maintain an access -timestamp for this file.

    -
    • -
  • -

    data-modification-timestamp: option<datetime>

    -

    Last data modification timestamp. -

    If the option is none, the platform doesn't maintain a -modification timestamp for this file.

    -
    • -
  • -

    status-change-timestamp: option<datetime>

    -

    Last file status-change timestamp. -

    If the option is none, the platform doesn't maintain a -status-change timestamp for this file.

    -
    • -
-

variant new-timestamp

-

When setting a timestamp, this gives the value to set it to.

-
Variant Cases
-
    -
  • -

    no-change

    -

    Leave the timestamp set to its previous value. -

    • -
  • -

    now

    -

    Set the timestamp to the current time of the system clock associated -with the filesystem. -

    • -
  • -

    timestamp: datetime

    -

    Set the timestamp to the given value. -

    • -
-

record directory-entry

-

A directory entry.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    The type of the file referred to by this directory entry. -

    • -
  • -

    name: string

    -

    The name of the object. -

    • -
-

enum error-code

-

Error codes returned by functions, similar to errno in POSIX. -Not all of these error codes are returned by the functions provided by this -API; some are used in higher-level library layers, and others are provided -merely for alignment with POSIX.

-
Enum Cases
-
    -
  • -

    access

    -

    Permission denied, similar to `EACCES` in POSIX. -

    • -
  • -

    would-block

    -

    Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX. -

    • -
  • -

    already

    -

    Connection already in progress, similar to `EALREADY` in POSIX. -

    • -
  • -

    bad-descriptor

    -

    Bad descriptor, similar to `EBADF` in POSIX. -

    • -
  • -

    busy

    -

    Device or resource busy, similar to `EBUSY` in POSIX. -

    • -
  • -

    deadlock

    -

    Resource deadlock would occur, similar to `EDEADLK` in POSIX. -

    • -
  • -

    quota

    -

    Storage quota exceeded, similar to `EDQUOT` in POSIX. -

    • -
  • -

    exist

    -

    File exists, similar to `EEXIST` in POSIX. -

    • -
  • -

    file-too-large

    -

    File too large, similar to `EFBIG` in POSIX. -

    • -
  • -

    illegal-byte-sequence

    -

    Illegal byte sequence, similar to `EILSEQ` in POSIX. -

    • -
  • -

    in-progress

    -

    Operation in progress, similar to `EINPROGRESS` in POSIX. -

    • -
  • -

    interrupted

    -

    Interrupted function, similar to `EINTR` in POSIX. -

    • -
  • -

    invalid

    -

    Invalid argument, similar to `EINVAL` in POSIX. -

    • -
  • -

    io

    -

    I/O error, similar to `EIO` in POSIX. -

    • -
  • -

    is-directory

    -

    Is a directory, similar to `EISDIR` in POSIX. -

    • -
  • -

    loop

    -

    Too many levels of symbolic links, similar to `ELOOP` in POSIX. -

    • -
  • -

    too-many-links

    -

    Too many links, similar to `EMLINK` in POSIX. -

    • -
  • -

    message-size

    -

    Message too large, similar to `EMSGSIZE` in POSIX. -

    • -
  • -

    name-too-long

    -

    Filename too long, similar to `ENAMETOOLONG` in POSIX. -

    • -
  • -

    no-device

    -

    No such device, similar to `ENODEV` in POSIX. -

    • -
  • -

    no-entry

    -

    No such file or directory, similar to `ENOENT` in POSIX. -

    • -
  • -

    no-lock

    -

    No locks available, similar to `ENOLCK` in POSIX. -

    • -
  • -

    insufficient-memory

    -

    Not enough space, similar to `ENOMEM` in POSIX. -

    • -
  • -

    insufficient-space

    -

    No space left on device, similar to `ENOSPC` in POSIX. -

    • -
  • -

    not-directory

    -

    Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. -

    • -
  • -

    not-empty

    -

    Directory not empty, similar to `ENOTEMPTY` in POSIX. -

    • -
  • -

    not-recoverable

    -

    State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. -

    • -
  • -

    unsupported

    -

    Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. -

    • -
  • -

    no-tty

    -

    Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. -

    • -
  • -

    no-such-device

    -

    No such device or address, similar to `ENXIO` in POSIX. -

    • -
  • -

    overflow

    -

    Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. -

    • -
  • -

    not-permitted

    -

    Operation not permitted, similar to `EPERM` in POSIX. -

    • -
  • -

    pipe

    -

    Broken pipe, similar to `EPIPE` in POSIX. -

    • -
  • -

    read-only

    -

    Read-only file system, similar to `EROFS` in POSIX. -

    • -
  • -

    invalid-seek

    -

    Invalid seek, similar to `ESPIPE` in POSIX. -

    • -
  • -

    text-file-busy

    -

    Text file busy, similar to `ETXTBSY` in POSIX. -

    • -
  • -

    cross-device

    -

    Cross-device link, similar to `EXDEV` in POSIX. -

    • -
-

enum advice

-

File or memory access pattern advisory information.

-
Enum Cases
-
    -
  • -

    normal

    -

    The application has no advice to give on its behavior with respect -to the specified data. -

    • -
  • -

    sequential

    -

    The application expects to access the specified data sequentially -from lower offsets to higher offsets. -

    • -
  • -

    random

    -

    The application expects to access the specified data in a random -order. -

    • -
  • -

    will-need

    -

    The application expects to access the specified data in the near -future. -

    • -
  • -

    dont-need

    -

    The application expects that it will not access the specified data -in the near future. -

    • -
  • -

    no-reuse

    -

    The application expects to access the specified data once and then -not reuse it thereafter. -

    • -
-

record metadata-hash-value

-

A 128-bit hash value, split into parts because wasm doesn't have a -128-bit integer type.

-
Record Fields
-
    -
  • -

    lower: u64

    -

    64 bits of a 128-bit hash value. -

    • -
  • -

    upper: u64

    -

    Another 64 bits of a 128-bit hash value. -

    • -
-

resource descriptor

-

A descriptor is a reference to a filesystem object, which may be a file, -directory, named pipe, special file, or other object on which filesystem -calls may be made.

-

resource directory-entry-stream

-

A stream of directory entries.

-

Functions

-

[method]descriptor.read-via-stream: func

-

Return a stream for reading from a file, if available.

-

May fail with an error-code describing why the file cannot be read.

-

Multiple read, write, and append streams may be active on the same open -file and they do not interfere with each other.

-

Note: This allows using read-stream, which is similar to read in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write-via-stream: func

-

Return a stream for writing to a file, if available.

-

May fail with an error-code describing why the file cannot be written.

-

Note: This allows using write-stream, which is similar to write in -POSIX.

-
Params
- -
Return values
- -

[method]descriptor.append-via-stream: func

-

Return a stream for appending to a file, if available.

-

May fail with an error-code describing why the file cannot be appended.

-

Note: This allows using write-stream, which is similar to write with -O_APPEND in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.advise: func

-

Provide file advisory information on a descriptor.

-

This is similar to posix_fadvise in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.sync-data: func

-

Synchronize the data of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fdatasync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.get-flags: func

-

Get flags associated with a descriptor.

-

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

-

Note: This returns the value that was the fs_flags value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.get-type: func

-

Get the dynamic type of a descriptor.

-

Note: This returns the same value as the type field of the fd-stat -returned by stat, stat-at and similar.

-

Note: This returns similar flags to the st_mode & S_IFMT value provided -by fstat in POSIX.

-

Note: This returns the value that was the fs_filetype value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-size: func

-

Adjust the size of an open file. If this increases the file's size, the -extra bytes are filled with zeros.

-

Note: This was called fd_filestat_set_size in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times: func

-

Adjust the timestamps of an open file or directory.

-

Note: This is similar to futimens in POSIX.

-

Note: This was called fd_filestat_set_times in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.read: func

-

Read from a descriptor, without using and updating the descriptor's offset.

-

This function returns a list of bytes containing the data that was -read, along with a bool which, when true, indicates that the end of the -file was reached. The returned list will contain up to length bytes; it -may return fewer than requested, if the end of the file is reached or -if the I/O operation is interrupted.

-

In the future, this may change to return a stream<u8, error-code>.

-

Note: This is similar to pread in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write: func

-

Write to a descriptor, without using and updating the descriptor's offset.

-

It is valid to write past the end of a file; the file is extended to the -extent of the write, with bytes between the previous end and the start of -the write set to zero.

-

In the future, this may change to take a stream<u8, error-code>.

-

Note: This is similar to pwrite in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.read-directory: func

-

Read directory entries from a directory.

-

On filesystems where directories contain entries referring to themselves -and their parents, often named . and .. respectively, these entries -are omitted.

-

This always returns a new stream which starts at the beginning of the -directory. Multiple streams may be active on the same directory, and they -do not interfere with each other.

-
Params
- -
Return values
- -

[method]descriptor.sync: func

-

Synchronize the data and metadata of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fsync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.create-directory-at: func

-

Create a directory.

-

Note: This is similar to mkdirat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.stat: func

-

Return the attributes of an open file or directory.

-

Note: This is similar to fstat in POSIX, except that it does not return -device and inode information. For testing whether two descriptors refer to -the same underlying filesystem object, use is-same-object. To obtain -additional data that can be used do determine whether a file has been -modified, use metadata-hash.

-

Note: This was called fd_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.stat-at: func

-

Return the attributes of a file or directory.

-

Note: This is similar to fstatat in POSIX, except that it does not -return device and inode information. See the stat description for a -discussion of alternatives.

-

Note: This was called path_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times-at: func

-

Adjust the timestamps of a file or directory.

-

Note: This is similar to utimensat in POSIX.

-

Note: This was called path_filestat_set_times in earlier versions of -WASI.

-
Params
- -
Return values
- -

[method]descriptor.link-at: func

-

Create a hard link.

-

Fails with error-code::no-entry if the old path does not exist, -with error-code::exist if the new path already exists, and -error-code::not-permitted if the old path is not a file.

-

Note: This is similar to linkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.open-at: func

-

Open a file or directory.

-

If flags contains descriptor-flags::mutate-directory, and the base -descriptor doesn't have descriptor-flags::mutate-directory set, -open-at fails with error-code::read-only.

-

If flags contains write or mutate-directory, or open-flags -contains truncate or create, and the base descriptor doesn't have -descriptor-flags::mutate-directory set, open-at fails with -error-code::read-only.

-

Note: This is similar to openat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.readlink-at: func

-

Read the contents of a symbolic link.

-

If the contents contain an absolute or rooted path in the underlying -filesystem, this function fails with error-code::not-permitted.

-

Note: This is similar to readlinkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.remove-directory-at: func

-

Remove a directory.

-

Return error-code::not-empty if the directory is not empty.

-

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.rename-at: func

-

Rename a filesystem object.

-

Note: This is similar to renameat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-descriptor: borrow<descriptor>
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.symlink-at: func

-

Create a symbolic link (also known as a "symlink").

-

If old-path starts with /, the function fails with -error-code::not-permitted.

-

Note: This is similar to symlinkat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.unlink-file-at: func

-

Unlink a filesystem object that is not a directory.

-

Return error-code::is-directory if the path refers to a directory. -Note: This is similar to unlinkat(fd, path, 0) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.is-same-object: func

-

Test whether two descriptors refer to the same filesystem object.

-

In POSIX, this corresponds to testing whether the two descriptors have the -same device (st_dev) and inode (st_ino or d_ino) numbers. -wasi-filesystem does not expose device and inode numbers, so this function -may be used instead.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]descriptor.metadata-hash: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a descriptor.

-

This returns a hash of the last-modification timestamp and file size, and -may also include the inode number, device number, birth timestamp, and -other metadata fields that may change when the file is modified or -replaced. It may also include a secret value chosen by the -implementation and not otherwise exposed.

-

Implementations are encouraged to provide the following properties:

-
    -
  • If the file is not modified or replaced, the computed hash value should -usually not change.
    • -
  • If the object is modified or replaced, the computed hash value should -usually change.
    • -
  • The inputs to the hash should not be easily computable from the -computed hash.
    • -
-

However, none of these is required.

-
Params
- -
Return values
- -

[method]descriptor.metadata-hash-at: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a directory descriptor and a relative path.

-

This performs the same hash computation as metadata-hash.

-
Params
- -
Return values
- -

[method]directory-entry-stream.read-directory-entry: func

-

Read a single directory entry from a directory-entry-stream.

-
Params
- -
Return values
- -

filesystem-error-code: func

-

Attempts to extract a filesystem-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -filesystem-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are filesystem-related errors.

-
Params
- -
Return values
- -

Import interface wasi:filesystem/preopens@0.2.12

-
-

Types

-

type descriptor

-

descriptor

-

-

-

Functions

-

get-directories: func

-

Return the set of preopened directories, and their paths.

-
Return values
- -

Import interface wasi:sockets/network@0.2.12

-
-

Types

-

type error

-

error

-

-

resource network

-

An opaque resource that represents access to (a subset of) the network. -This enables context-based security for networking. -There is no need for this to map 1:1 to a physical network interface.

-

enum error-code

-

Error codes.

-

In theory, every API can return any error code. -In practice, API's typically only return the errors documented per API -combined with a couple of errors that are always possible:

-
    -
  • unknown
    • -
  • access-denied
    • -
  • not-supported
    • -
  • out-of-memory
    • -
  • concurrency-conflict
    • -
-

See each individual API for what the POSIX equivalents are. They sometimes differ per API.

-
Enum Cases
-
    -
  • -

    unknown

    -

    Unknown error -

    • -
  • -

    access-denied

    -

    Access denied. -

    POSIX equivalent: EACCES, EPERM

    -
    • -
  • -

    not-supported

    -

    The operation is not supported. -

    POSIX equivalent: EOPNOTSUPP

    -
    • -
  • -

    invalid-argument

    -

    One of the arguments is invalid. -

    POSIX equivalent: EINVAL

    -
    • -
  • -

    out-of-memory

    -

    Not enough memory to complete the operation. -

    POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY

    -
    • -
  • -

    timeout

    -

    The operation timed out before it could finish completely. -

    • -
  • -

    concurrency-conflict

    -

    This operation is incompatible with another asynchronous operation that is already in progress. -

    POSIX equivalent: EALREADY

    -
    • -
  • -

    not-in-progress

    -

    Trying to finish an asynchronous operation that: -- has not been started yet, or: -- was already finished by a previous `finish-*` call. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    would-block

    -

    The operation has been aborted because it could not be completed immediately. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    invalid-state

    -

    The operation is not valid in the socket's current state. -

    • -
  • -

    new-socket-limit

    -

    A new socket resource could not be created because of a system limit. -

    • -
  • -

    address-not-bindable

    -

    A bind operation failed because the provided address is not an address that the `network` can bind to. -

    • -
  • -

    address-in-use

    -

    A bind operation failed because the provided address is already in use or because there are no ephemeral ports available. -

    • -
  • -

    remote-unreachable

    -

    The remote address is not reachable -

    • -
  • -

    connection-refused

    -

    The TCP connection was forcefully rejected -

    • -
  • -

    connection-reset

    -

    The TCP connection was reset. -

    • -
  • -

    connection-aborted

    -

    A TCP connection was aborted. -

    • -
  • -

    datagram-too-large

    -

    The size of a datagram sent to a UDP socket exceeded the maximum -supported size. -

    • -
  • -

    name-unresolvable

    -

    Name does not exist or has no suitable associated IP addresses. -

    • -
  • -

    temporary-resolver-failure

    -

    A temporary failure in name resolution occurred. -

    • -
  • -

    permanent-resolver-failure

    -

    A permanent failure in name resolution occurred. -

    • -
-

enum ip-address-family

-
Enum Cases
-
    -
  • -

    ipv4

    -

    Similar to `AF_INET` in POSIX. -

    • -
  • -

    ipv6

    -

    Similar to `AF_INET6` in POSIX. -

    • -
-

tuple ipv4-address

-
Tuple Fields
-
    -
  • 0: u8
    • -
  • 1: u8
    • -
  • 2: u8
    • -
  • 3: u8
    • -
-

tuple ipv6-address

-
Tuple Fields
-
    -
  • 0: u16
    • -
  • 1: u16
    • -
  • 2: u16
    • -
  • 3: u16
    • -
  • 4: u16
    • -
  • 5: u16
    • -
  • 6: u16
    • -
  • 7: u16
    • -
-

variant ip-address

-
Variant Cases
- -

record ipv4-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin_port -

    • -
  • -

    address: ipv4-address

    -

    sin_addr -

    • -
-

record ipv6-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin6_port -

    • -
  • -

    flow-info: u32

    -

    sin6_flowinfo -

    • -
  • -

    address: ipv6-address

    -

    sin6_addr -

    • -
  • -

    scope-id: u32

    -

    sin6_scope_id -

    • -
-

variant ip-socket-address

-
Variant Cases
- -
-

Functions

-

network-error-code: func

-

Attempts to extract a network-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -network-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are network-related errors.

-
Params
- -
Return values
- -

Import interface wasi:sockets/instance-network@0.2.12

-

This interface provides a value-export of the default network handle..

-
-

Types

-

type network

-

network

-

-

-

Functions

-

instance-network: func

-

Get a handle to the default network.

-
Return values
- -

Import interface wasi:sockets/udp@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

record incoming-datagram

-

A received datagram.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.

    -
    • -
  • -

    remote-address: ip-socket-address

    -

    The source address. -

    This field is guaranteed to match the remote address the stream was initialized with, if any.

    -

    Equivalent to the src_addr out parameter of recvfrom.

    -
    • -
-

record outgoing-datagram

-

A datagram to be sent out.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    • -
  • -

    remote-address: option<ip-socket-address>

    -

    The destination address. -

    The requirements on this field depend on how the stream was initialized:

    -
      -
    • with a remote address: this field must be None or match the stream's remote address exactly.
      • -
    • without a remote address: this field is required.
      • -
    -

    If this value is None, the send operation is equivalent to send in POSIX. Otherwise it is equivalent to sendto.

    -
    • -
-

resource udp-socket

-

A UDP socket handle.

-

resource incoming-datagram-stream

-

resource outgoing-datagram-stream

-
-

Functions

-

[method]udp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the port is zero, the socket will be bound to a random free port.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]udp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]udp-socket.stream: func

-

Set up inbound & outbound communication channels, optionally to a specific peer.

-

This function only changes the local socket configuration and does not generate any network traffic. -On success, the remote-address of the socket is updated. The local-address may be updated as well, -based on the best network path to remote-address.

-

When a remote-address is provided, the returned streams are limited to communicating with that specific peer:

-
    -
  • send can only be used to send to this destination.
    • -
  • receive will only return datagrams sent from the provided remote-address.
    • -
-

This method may be called multiple times on the same socket to change its association, but -only the most recently returned pair of streams will be operational. Implementations may trap if -the streams returned by a previous invocation haven't been dropped yet before calling stream again.

-

The POSIX equivalent in pseudo-code is:

-
if (was previously connected) {
-  connect(s, AF_UNSPEC)
-}
-if (remote_address is Some) {
-  connect(s, remote_address)
-}
-
-

Unlike in POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-state: The socket is not bound.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.local-address: func

-

Get the current bound address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.remote-address: func

-

Get the address the socket is currently streaming to.

-

Typical errors

-
    -
  • invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]udp-socket.unicast-hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-unicast-hop-limit: func

-
Params
- -
Return values
- -

[method]udp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.subscribe: func

-

Create a pollable which will resolve once the socket is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]incoming-datagram-stream.receive: func

-

Receive messages on the socket.

-

This function attempts to receive up to max-results datagrams on the socket without blocking. -The returned list may contain fewer elements than requested, but never more.

-

This function returns successfully with an empty list when either:

-
    -
  • max-results is 0, or:
    • -
  • max-results is greater than 0, but no results are immediately available. -This function never returns error(would-block).
    • -
-

Typical errors

-
    -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]incoming-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to receive again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.check-send: func

-

Check readiness for sending. This function never blocks.

-

Returns the number of datagrams permitted for the next call to send, -or an error. Calling send with more datagrams than this function has -permitted will trap.

-

When this function returns ok(0), the subscribe pollable will -become ready when this function will report at least ok(1), or an -error.

-

Never returns would-block.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.send: func

-

Send messages on the socket.

-

This function attempts to send all provided datagrams on the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -returns error(would-block). If none of the datagrams were able to be sent, ok(0) is returned.

-

This function semantically behaves the same as iterating the datagrams list and sequentially -sending each individual datagram until either the end of the list has been reached or the first error occurred. -If at least one datagram has been sent successfully, this function never returns an error.

-

If the input list is empty, the function returns ok(0).

-

Each call to send must be permitted by a preceding check-send. Implementations must trap if -either check-send was not called or datagrams contains more items than check-send permitted.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)
    • -
  • invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
  • datagram-too-large: The datagram is too large. (EMSGSIZE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]outgoing-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to send again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

Import interface wasi:sockets/udp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type udp-socket

-

udp-socket

-

-

-

Functions

-

create-udp-socket: func

-

Create a new UDP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind is called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References:

- -
Params
- -
Return values
- -

Import interface wasi:sockets/tcp@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type pollable

-

pollable

-

-

type duration

-

duration

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

enum shutdown-type

-
Enum Cases
-
    -
  • -

    receive

    -

    Similar to `SHUT_RD` in POSIX. -

    • -
  • -

    send

    -

    Similar to `SHUT_WR` in POSIX. -

    • -
  • -

    both

    -

    Similar to `SHUT_RDWR` in POSIX. -

    • -
-

resource tcp-socket

-

A TCP socket resource.

-

The socket can be in one of the following states:

- -

Note: Except where explicitly mentioned, whenever this documentation uses -the term "bound" without backticks it actually means: in the bound state or higher. -(i.e. bound, listen-in-progress, listening, connect-in-progress or connected)

-

In addition to the general error codes documented on the -network::error-code type, TCP socket methods may always return -error(invalid-state) when in the closed state.

-

Functions

-

[method]tcp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the TCP/UDP port is zero, the socket will be bound to a random free port.

-

Bind can be attempted multiple times on the same socket, even with -different arguments on each iteration. But never concurrently and -only as long as the previous bind failed. Once a bind succeeds, the -binding can't be changed anymore.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • -
  • invalid-argument: local-address is an IPv4-mapped IPv6 address. (EINVAL)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT -state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR -socket option should be set implicitly on all platforms, except on Windows where this is the default behavior -and SO_REUSEADDR performs something different entirely.

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-connect: func

-

Connect to a remote endpoint.

-

On success:

-
    -
  • the socket is transitioned into the connected state.
    • -
  • a pair of streams is returned that can be used to read & write to the connection
    • -
-

After a failed connection attempt, the socket will be in the closed -state and the only valid action left is to drop the socket. A single -socket can not be used to connect more than once.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • -
  • invalid-argument: remote-address is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN)
    • -
  • invalid-state: The socket is already in the listening state. (EOPNOTSUPP, EINVAL on Windows)
    • -
  • timeout: Connection timed out. (ETIMEDOUT)
    • -
  • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • -
  • connection-reset: The connection was reset. (ECONNRESET)
    • -
  • connection-aborted: The connection was aborted. (ECONNABORTED)
    • -
  • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • not-in-progress: A connect operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

The POSIX equivalent of start-connect is the regular connect syscall. -Because all WASI sockets are non-blocking this is expected to return -EINPROGRESS, which should be translated to ok() in WASI.

-

The POSIX equivalent of finish-connect is a poll for event POLLOUT -with a timeout of 0 on the socket descriptor. Followed by a check for -the SO_ERROR socket option, in case the poll signaled readiness.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-connect: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-listen: func

-

Start listening for new connections.

-

Transitions the socket into the listening state.

-

Unlike POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address. (EDESTADDRREQ)
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN, EINVAL on BSD)
    • -
  • invalid-state: The socket is already in the listening state.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
    • -
  • not-in-progress: A listen operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the listen operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -listen as part of either start-listen or finish-listen.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-listen: func

-
Params
- -
Return values
- -

[method]tcp-socket.accept: func

-

Accept a new client socket.

-

The returned socket is bound and in the connected state. The following properties are inherited from the listener socket:

-
    -
  • address-family
    • -
  • keep-alive-enabled
    • -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count
    • -
  • hop-limit
    • -
  • receive-buffer-size
    • -
  • send-buffer-size
    • -
-

On success, this function returns the newly accepted client socket along with -a pair of streams that can be used to read & write to the connection.

-

Typical errors

-
    -
  • invalid-state: Socket is not in the listening state. (EINVAL)
    • -
  • would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
    • -
  • connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.local-address: func

-

Get the bound local address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.remote-address: func

-

Get the remote address.

-

Typical errors

-
    -
  • invalid-state: The socket is not connected to a remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.is-listening: func

-

Whether the socket is in the listening state.

-

Equivalent to the SO_ACCEPTCONN socket option.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]tcp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-listen-backlog-size: func

-

Hints the desired listen queue size. Implementations are free to ignore this.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded.

-

Typical errors

-
    -
  • not-supported: (set) The platform does not support changing the backlog size after the initial listen.
    • -
  • invalid-argument: (set) The provided value was 0.
    • -
  • invalid-state: (set) The socket is in the connect-in-progress or connected state.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-enabled: func

-

Enables or disables keepalive.

-

The keepalive behavior can be adjusted using:

-
    -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count -These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.
    • -
-

Equivalent to the SO_KEEPALIVE socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-enabled: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-idle-time: func

-

Amount of time the connection has to be idle before TCP starts sending keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-idle-time: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-interval: func

-

The time between keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPINTVL socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-interval: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-count: func

-

The maximum amount of keepalive packets TCP should send before aborting the connection.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPCNT socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-count: func

-
Params
- -
Return values
- -

[method]tcp-socket.hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-hop-limit: func

-
Params
- -
Return values
- -

[method]tcp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.subscribe: func

-

Create a pollable which can be used to poll for, or block on, -completion of any of the asynchronous operations of this socket.

-

When finish-bind, finish-listen, finish-connect or accept -return error(would-block), this pollable can be used to wait for -their success or failure, after which the method can be retried.

-

The pollable is not limited to the async operation that happens to be -in progress at the time of calling subscribe (if any). Theoretically, -subscribe only has to be called once per socket and can then be -(re)used for the remainder of the socket's lifetime.

-

See https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/TcpSocketOperationalSemantics.md#pollable-readiness -for more information.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]tcp-socket.shutdown: func

-

Initiate a graceful shutdown.

-
    -
  • receive: The socket is not expecting to receive any data from -the peer. The input-stream associated with this socket will be -closed. Any data still in the receive queue at time of calling -this method will be discarded.
    • -
  • send: The socket has no more data to send to the peer. The output-stream -associated with this socket will be closed and a FIN packet will be sent.
    • -
  • both: Same effect as receive & send combined.
    • -
-

This function is idempotent; shutting down a direction more than once -has no effect and returns ok.

-

The shutdown function does not close (drop) the socket.

-

Typical errors

-
    -
  • invalid-state: The socket is not in the connected state. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/tcp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type tcp-socket

-

tcp-socket

-

-

-

Functions

-

create-tcp-socket: func

-

Create a new TCP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect -is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/ip-name-lookup@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address

-

ip-address

-

-

resource resolve-address-stream

-
-

Functions

-

resolve-addresses: func

-

Resolve an internet host name to a list of IP addresses.

-

Unicode domain names are automatically converted to ASCII using IDNA encoding. -If the input is an IP address string, the address is parsed and returned -as-is without making any external requests.

-

See the wasi-socket proposal README.md for a comparison with getaddrinfo.

-

This function never blocks. It either immediately fails or immediately -returns successfully with a resolve-address-stream that can be used -to (asynchronously) fetch the results.

-

Typical errors

-
    -
  • invalid-argument: name is a syntactically invalid domain name or IP address.
    • -
-

References:

- -
Params
- -
Return values
- -

[method]resolve-address-stream.resolve-next-address: func

-

Returns the next address from the resolver.

-

This function should be called multiple times. On each call, it will -return the next address in connection order preference. If all -addresses have been exhausted, this function returns none.

-

This function never returns IPv4-mapped IPv6 addresses.

-

Typical errors

-
    -
  • name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
    • -
  • temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)
    • -
  • permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)
    • -
  • would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)
    • -
-
Params
- -
Return values
- -

[method]resolve-address-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

Import interface wasi:random/random@0.2.12

-

WASI Random is a random data API.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-random-bytes: func

-

Return len cryptographically-secure random or pseudo-random bytes.

-

This function must produce data at least as cryptographically secure and -fast as an adequately seeded cryptographically-secure pseudo-random -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-random-u64: func

-

Return a cryptographically-secure random or pseudo-random u64 value.

-

This function returns the same type of data as get-random-bytes, -represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure@0.2.12

-

The insecure interface for insecure pseudo-random numbers.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-insecure-random-bytes: func

-

Return len insecure pseudo-random bytes.

-

This function is not cryptographically secure. Do not use it for -anything related to security.

-

There are no requirements on the values of the returned bytes, however -implementations are encouraged to return evenly distributed values with -a long period.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-insecure-random-u64: func

-

Return an insecure pseudo-random u64 value.

-

This function returns the same type of pseudo-random data as -get-insecure-random-bytes, represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure-seed@0.2.12

-

The insecure-seed interface for seeding hash-map DoS resistance.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

insecure-seed: func

-

Return a 128-bit value that may contain a pseudo-random value.

-

The returned value is not required to be computed from a CSPRNG, and may -even be entirely deterministic. Host implementations are encouraged to -provide pseudo-random values to any program exposed to -attacker-controlled content, to enable DoS protection built into many -languages' hash-map implementations.

-

This function is intended to only be called once, by a source language -to initialize Denial Of Service (DoS) protection in its hash-map -implementation.

-

Expected future evolution

-

This will likely be changed to a value import, to prevent it from being -called multiple times and potentially used for purposes other than DoS -protection.

-
Return values
-
    -
  • (u64, u64)
    • -
-

Export interface wasi:cli/run@0.2.12

-
-

Functions

-

run: func

-

Run the program.

-
Return values
-
    -
  • result
    • -
diff --git a/proposals/cli/imports.md b/proposals/cli/imports.md deleted file mode 100644 index c550091fa..000000000 --- a/proposals/cli/imports.md +++ /dev/null @@ -1,3130 +0,0 @@ -

World imports

- -

Import interface wasi:cli/environment@0.2.12

-
-

Functions

-

get-environment: func

-

Get the POSIX-style environment variables.

-

Each environment variable is provided as a pair of string variable names -and string value.

-

Morally, these are a value import, but until value imports are available -in the component model, this import function should return the same -values each time it is called.

-
Return values
-
    -
  • list<(string, string)>
    • -
-

get-arguments: func

-

Get the POSIX-style arguments to the program.

-
Return values
-
    -
  • list<string>
    • -
-

initial-cwd: func

-

Return a path that programs should use as their initial current working -directory, interpreting . as shorthand for this.

-
Return values
-
    -
  • option<string>
    • -
-

Import interface wasi:cli/exit@0.2.12

-
-

Functions

-

exit: func

-

Exit the current instance and any linked instances.

-
Params
-
    -
  • status: result
    • -
-

exit-with-code: func

-

Exit the current instance and any linked instances, reporting the -specified status code to the host.

-

The meaning of the code depends on the context, with 0 usually meaning -"success", and other values indicating various types of failure.

-

This function does not return; the effect is analogous to a trap, but -without the connotation that something bad has happened.

-
Params
-
    -
  • status-code: u8
    • -
-

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:cli/stdin@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

-

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:cli/stdout@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stderr: func

-
Return values
- -

Import interface wasi:cli/terminal-input@0.2.12

-

Terminal input.

-

In the future, this may include functions for disabling echoing, -disabling input buffering so that keyboard events are sent through -immediately, querying supported features, and so on.

-
-

Types

-

resource terminal-input

-

The input side of a terminal.

-

Import interface wasi:cli/terminal-output@0.2.12

-

Terminal output.

-

In the future, this may include functions for querying the terminal -size, being notified of terminal size changes, querying supported -features, and so on.

-
-

Types

-

resource terminal-output

-

The output side of a terminal.

-

Import interface wasi:cli/terminal-stdin@0.2.12

-

An interface providing an optional terminal-input for stdin as a -link-time authority.

-
-

Types

-

type terminal-input

-

terminal-input

-

-

-

Functions

-

get-terminal-stdin: func

-

If stdin is connected to a terminal, return a terminal-input handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:cli/terminal-stdout@0.2.12

-

An interface providing an optional terminal-output for stdout as a -link-time authority.

-
-

Types

-

type terminal-output

-

terminal-output

-

-

-

Functions

-

get-terminal-stdout: func

-

If stdout is connected to a terminal, return a terminal-output handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:cli/terminal-stderr@0.2.12

-

An interface providing an optional terminal-output for stderr as a -link-time authority.

-
-

Types

-

type terminal-output

-

terminal-output

-

-

-

Functions

-

get-terminal-stderr: func

-

If stderr is connected to a terminal, return a terminal-output handle -allowing further interaction with it.

-
Return values
- -

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:clocks/timezone@0.2.12

-
-

Types

-

type datetime

-

datetime

-

-

record timezone-display

-

Information useful for displaying the timezone of a specific datetime.

-

This information may vary within a single timezone to reflect daylight -saving time adjustments.

-
Record Fields
-
    -
  • -

    utc-offset: s32

    -

    The number of seconds difference between UTC time and the local -time of the timezone. -

    The returned value will always be less than 86400 which is the -number of seconds in a day (246060).

    -

    In implementations that do not expose an actual time zone, this -should return 0.

    -
    • -
  • -

    name: string

    -

    The abbreviated name of the timezone to display to a user. The name -`UTC` indicates Coordinated Universal Time. Otherwise, this should -reference local standards for the name of the time zone. -

    In implementations that do not expose an actual time zone, this -should be the string UTC.

    -

    In time zones that do not have an applicable name, a formatted -representation of the UTC offset may be returned, such as -04:00.

    -
    • -
  • -

    in-daylight-saving-time: bool

    -

    Whether daylight saving time is active. -

    In implementations that do not expose an actual time zone, this -should return false.

    -
    • -
-
-

Functions

-

display: func

-

Return information needed to display the given datetime. This includes -the UTC offset, the time zone name, and a flag indicating whether -daylight saving time is active.

-

If the timezone cannot be determined for the given datetime, return a -timezone-display for UTC with a utc-offset of 0 and no daylight -saving time.

-
Params
- -
Return values
- -

utc-offset: func

-

The same as display, but only return the UTC offset.

-
Params
- -
Return values
-
    -
  • s32
    • -
-

Import interface wasi:filesystem/types@0.2.12

-

WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.

-

It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.

-

Paths are passed as interface-type strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.

-

The directory separator in WASI is always the forward-slash (/).

-

All paths in WASI are relative paths, and are interpreted relative to a -descriptor referring to a base directory. If a path argument to any WASI -function starts with /, or if any step of resolving a path, including -.. and symbolic link steps, reaches a directory outside of the base -directory, or reaches a symlink to an absolute or rooted path in the -underlying filesystem, the function fails with error-code::not-permitted.

-

For more information about WASI path resolution and sandboxing, see -WASI filesystem path resolution.

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type error

-

error

-

-

type datetime

-

datetime

-

-

type filesize

-

u64

-

File size or length of a region within a file. -

enum descriptor-type

-

The type of a filesystem object referenced by a descriptor.

-

Note: This was called filetype in earlier versions of WASI.

-
Enum Cases
-
    -
  • -

    unknown

    -

    The type of the descriptor or file is unknown or is different from -any of the other types specified. -

    • -
  • -

    block-device

    -

    The descriptor refers to a block device inode. -

    • -
  • -

    character-device

    -

    The descriptor refers to a character device inode. -

    • -
  • -

    directory

    -

    The descriptor refers to a directory inode. -

    • -
  • -

    fifo

    -

    The descriptor refers to a named pipe. -

    • -
  • -

    symbolic-link

    -

    The file refers to a symbolic link inode. -

    • -
  • -

    regular-file

    -

    The descriptor refers to a regular file inode. -

    • -
  • -

    socket

    -

    The descriptor refers to a socket. -

    • -
-

flags descriptor-flags

-

Descriptor flags.

-

Note: This was called fdflags in earlier versions of WASI.

-
Flags members
-
    -
  • -

    read:

    -

    Read mode: Data can be read. -

    • -
  • -

    write:

    -

    Write mode: Data can be written to. -

    • -
  • -

    file-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O file -integrity completion. The data stored in the file and the file's -metadata are synchronized. This is similar to `O_SYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    data-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O data -integrity completion. Only the data stored in the file is -synchronized. This is similar to `O_DSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    requested-write-sync:

    -

    Requests that reads be performed at the same level of integrity -requested for writes. This is similar to `O_RSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    mutate-directory:

    -

    Mutating directories mode: Directory contents may be mutated. -

    When this flag is unset on a descriptor, operations using the -descriptor which would create, rename, delete, modify the data or -metadata of filesystem objects, or obtain another handle which -would permit any of those, shall fail with error-code::read-only if -they would otherwise succeed.

    -

    This may only be set on directories.

    -
    • -
-

flags path-flags

-

Flags determining the method of how paths are resolved.

-
Flags members
-
    -
  • symlink-follow:

    As long as the resolved path corresponds to a symbolic link, it is -expanded. -

    • -
-

flags open-flags

-

Open flags used by open-at.

-
Flags members
-
    -
  • -

    create:

    -

    Create file if it does not exist, similar to `O_CREAT` in POSIX. -

    • -
  • -

    directory:

    -

    Fail if not a directory, similar to `O_DIRECTORY` in POSIX. -

    • -
  • -

    exclusive:

    -

    Fail if file already exists, similar to `O_EXCL` in POSIX. -

    • -
  • -

    truncate:

    -

    Truncate file to size 0, similar to `O_TRUNC` in POSIX. -

    • -
-

type link-count

-

u64

-

Number of hard links to an inode. -

record descriptor-stat

-

File attributes.

-

Note: This was called filestat in earlier versions of WASI.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    File type. -

    • -
  • -

    link-count: link-count

    -

    Number of hard links to the file. -

    • -
  • -

    size: filesize

    -

    For regular files, the file size in bytes. For symbolic links, the -length in bytes of the pathname contained in the symbolic link. -

    • -
  • -

    data-access-timestamp: option<datetime>

    -

    Last data access timestamp. -

    If the option is none, the platform doesn't maintain an access -timestamp for this file.

    -
    • -
  • -

    data-modification-timestamp: option<datetime>

    -

    Last data modification timestamp. -

    If the option is none, the platform doesn't maintain a -modification timestamp for this file.

    -
    • -
  • -

    status-change-timestamp: option<datetime>

    -

    Last file status-change timestamp. -

    If the option is none, the platform doesn't maintain a -status-change timestamp for this file.

    -
    • -
-

variant new-timestamp

-

When setting a timestamp, this gives the value to set it to.

-
Variant Cases
-
    -
  • -

    no-change

    -

    Leave the timestamp set to its previous value. -

    • -
  • -

    now

    -

    Set the timestamp to the current time of the system clock associated -with the filesystem. -

    • -
  • -

    timestamp: datetime

    -

    Set the timestamp to the given value. -

    • -
-

record directory-entry

-

A directory entry.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    The type of the file referred to by this directory entry. -

    • -
  • -

    name: string

    -

    The name of the object. -

    • -
-

enum error-code

-

Error codes returned by functions, similar to errno in POSIX. -Not all of these error codes are returned by the functions provided by this -API; some are used in higher-level library layers, and others are provided -merely for alignment with POSIX.

-
Enum Cases
-
    -
  • -

    access

    -

    Permission denied, similar to `EACCES` in POSIX. -

    • -
  • -

    would-block

    -

    Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX. -

    • -
  • -

    already

    -

    Connection already in progress, similar to `EALREADY` in POSIX. -

    • -
  • -

    bad-descriptor

    -

    Bad descriptor, similar to `EBADF` in POSIX. -

    • -
  • -

    busy

    -

    Device or resource busy, similar to `EBUSY` in POSIX. -

    • -
  • -

    deadlock

    -

    Resource deadlock would occur, similar to `EDEADLK` in POSIX. -

    • -
  • -

    quota

    -

    Storage quota exceeded, similar to `EDQUOT` in POSIX. -

    • -
  • -

    exist

    -

    File exists, similar to `EEXIST` in POSIX. -

    • -
  • -

    file-too-large

    -

    File too large, similar to `EFBIG` in POSIX. -

    • -
  • -

    illegal-byte-sequence

    -

    Illegal byte sequence, similar to `EILSEQ` in POSIX. -

    • -
  • -

    in-progress

    -

    Operation in progress, similar to `EINPROGRESS` in POSIX. -

    • -
  • -

    interrupted

    -

    Interrupted function, similar to `EINTR` in POSIX. -

    • -
  • -

    invalid

    -

    Invalid argument, similar to `EINVAL` in POSIX. -

    • -
  • -

    io

    -

    I/O error, similar to `EIO` in POSIX. -

    • -
  • -

    is-directory

    -

    Is a directory, similar to `EISDIR` in POSIX. -

    • -
  • -

    loop

    -

    Too many levels of symbolic links, similar to `ELOOP` in POSIX. -

    • -
  • -

    too-many-links

    -

    Too many links, similar to `EMLINK` in POSIX. -

    • -
  • -

    message-size

    -

    Message too large, similar to `EMSGSIZE` in POSIX. -

    • -
  • -

    name-too-long

    -

    Filename too long, similar to `ENAMETOOLONG` in POSIX. -

    • -
  • -

    no-device

    -

    No such device, similar to `ENODEV` in POSIX. -

    • -
  • -

    no-entry

    -

    No such file or directory, similar to `ENOENT` in POSIX. -

    • -
  • -

    no-lock

    -

    No locks available, similar to `ENOLCK` in POSIX. -

    • -
  • -

    insufficient-memory

    -

    Not enough space, similar to `ENOMEM` in POSIX. -

    • -
  • -

    insufficient-space

    -

    No space left on device, similar to `ENOSPC` in POSIX. -

    • -
  • -

    not-directory

    -

    Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. -

    • -
  • -

    not-empty

    -

    Directory not empty, similar to `ENOTEMPTY` in POSIX. -

    • -
  • -

    not-recoverable

    -

    State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. -

    • -
  • -

    unsupported

    -

    Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. -

    • -
  • -

    no-tty

    -

    Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. -

    • -
  • -

    no-such-device

    -

    No such device or address, similar to `ENXIO` in POSIX. -

    • -
  • -

    overflow

    -

    Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. -

    • -
  • -

    not-permitted

    -

    Operation not permitted, similar to `EPERM` in POSIX. -

    • -
  • -

    pipe

    -

    Broken pipe, similar to `EPIPE` in POSIX. -

    • -
  • -

    read-only

    -

    Read-only file system, similar to `EROFS` in POSIX. -

    • -
  • -

    invalid-seek

    -

    Invalid seek, similar to `ESPIPE` in POSIX. -

    • -
  • -

    text-file-busy

    -

    Text file busy, similar to `ETXTBSY` in POSIX. -

    • -
  • -

    cross-device

    -

    Cross-device link, similar to `EXDEV` in POSIX. -

    • -
-

enum advice

-

File or memory access pattern advisory information.

-
Enum Cases
-
    -
  • -

    normal

    -

    The application has no advice to give on its behavior with respect -to the specified data. -

    • -
  • -

    sequential

    -

    The application expects to access the specified data sequentially -from lower offsets to higher offsets. -

    • -
  • -

    random

    -

    The application expects to access the specified data in a random -order. -

    • -
  • -

    will-need

    -

    The application expects to access the specified data in the near -future. -

    • -
  • -

    dont-need

    -

    The application expects that it will not access the specified data -in the near future. -

    • -
  • -

    no-reuse

    -

    The application expects to access the specified data once and then -not reuse it thereafter. -

    • -
-

record metadata-hash-value

-

A 128-bit hash value, split into parts because wasm doesn't have a -128-bit integer type.

-
Record Fields
-
    -
  • -

    lower: u64

    -

    64 bits of a 128-bit hash value. -

    • -
  • -

    upper: u64

    -

    Another 64 bits of a 128-bit hash value. -

    • -
-

resource descriptor

-

A descriptor is a reference to a filesystem object, which may be a file, -directory, named pipe, special file, or other object on which filesystem -calls may be made.

-

resource directory-entry-stream

-

A stream of directory entries.

-

Functions

-

[method]descriptor.read-via-stream: func

-

Return a stream for reading from a file, if available.

-

May fail with an error-code describing why the file cannot be read.

-

Multiple read, write, and append streams may be active on the same open -file and they do not interfere with each other.

-

Note: This allows using read-stream, which is similar to read in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write-via-stream: func

-

Return a stream for writing to a file, if available.

-

May fail with an error-code describing why the file cannot be written.

-

Note: This allows using write-stream, which is similar to write in -POSIX.

-
Params
- -
Return values
- -

[method]descriptor.append-via-stream: func

-

Return a stream for appending to a file, if available.

-

May fail with an error-code describing why the file cannot be appended.

-

Note: This allows using write-stream, which is similar to write with -O_APPEND in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.advise: func

-

Provide file advisory information on a descriptor.

-

This is similar to posix_fadvise in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.sync-data: func

-

Synchronize the data of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fdatasync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.get-flags: func

-

Get flags associated with a descriptor.

-

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

-

Note: This returns the value that was the fs_flags value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.get-type: func

-

Get the dynamic type of a descriptor.

-

Note: This returns the same value as the type field of the fd-stat -returned by stat, stat-at and similar.

-

Note: This returns similar flags to the st_mode & S_IFMT value provided -by fstat in POSIX.

-

Note: This returns the value that was the fs_filetype value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-size: func

-

Adjust the size of an open file. If this increases the file's size, the -extra bytes are filled with zeros.

-

Note: This was called fd_filestat_set_size in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times: func

-

Adjust the timestamps of an open file or directory.

-

Note: This is similar to futimens in POSIX.

-

Note: This was called fd_filestat_set_times in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.read: func

-

Read from a descriptor, without using and updating the descriptor's offset.

-

This function returns a list of bytes containing the data that was -read, along with a bool which, when true, indicates that the end of the -file was reached. The returned list will contain up to length bytes; it -may return fewer than requested, if the end of the file is reached or -if the I/O operation is interrupted.

-

In the future, this may change to return a stream<u8, error-code>.

-

Note: This is similar to pread in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write: func

-

Write to a descriptor, without using and updating the descriptor's offset.

-

It is valid to write past the end of a file; the file is extended to the -extent of the write, with bytes between the previous end and the start of -the write set to zero.

-

In the future, this may change to take a stream<u8, error-code>.

-

Note: This is similar to pwrite in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.read-directory: func

-

Read directory entries from a directory.

-

On filesystems where directories contain entries referring to themselves -and their parents, often named . and .. respectively, these entries -are omitted.

-

This always returns a new stream which starts at the beginning of the -directory. Multiple streams may be active on the same directory, and they -do not interfere with each other.

-
Params
- -
Return values
- -

[method]descriptor.sync: func

-

Synchronize the data and metadata of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fsync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.create-directory-at: func

-

Create a directory.

-

Note: This is similar to mkdirat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.stat: func

-

Return the attributes of an open file or directory.

-

Note: This is similar to fstat in POSIX, except that it does not return -device and inode information. For testing whether two descriptors refer to -the same underlying filesystem object, use is-same-object. To obtain -additional data that can be used do determine whether a file has been -modified, use metadata-hash.

-

Note: This was called fd_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.stat-at: func

-

Return the attributes of a file or directory.

-

Note: This is similar to fstatat in POSIX, except that it does not -return device and inode information. See the stat description for a -discussion of alternatives.

-

Note: This was called path_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times-at: func

-

Adjust the timestamps of a file or directory.

-

Note: This is similar to utimensat in POSIX.

-

Note: This was called path_filestat_set_times in earlier versions of -WASI.

-
Params
- -
Return values
- -

[method]descriptor.link-at: func

-

Create a hard link.

-

Fails with error-code::no-entry if the old path does not exist, -with error-code::exist if the new path already exists, and -error-code::not-permitted if the old path is not a file.

-

Note: This is similar to linkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.open-at: func

-

Open a file or directory.

-

If flags contains descriptor-flags::mutate-directory, and the base -descriptor doesn't have descriptor-flags::mutate-directory set, -open-at fails with error-code::read-only.

-

If flags contains write or mutate-directory, or open-flags -contains truncate or create, and the base descriptor doesn't have -descriptor-flags::mutate-directory set, open-at fails with -error-code::read-only.

-

Note: This is similar to openat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.readlink-at: func

-

Read the contents of a symbolic link.

-

If the contents contain an absolute or rooted path in the underlying -filesystem, this function fails with error-code::not-permitted.

-

Note: This is similar to readlinkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.remove-directory-at: func

-

Remove a directory.

-

Return error-code::not-empty if the directory is not empty.

-

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.rename-at: func

-

Rename a filesystem object.

-

Note: This is similar to renameat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-descriptor: borrow<descriptor>
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.symlink-at: func

-

Create a symbolic link (also known as a "symlink").

-

If old-path starts with /, the function fails with -error-code::not-permitted.

-

Note: This is similar to symlinkat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.unlink-file-at: func

-

Unlink a filesystem object that is not a directory.

-

Return error-code::is-directory if the path refers to a directory. -Note: This is similar to unlinkat(fd, path, 0) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.is-same-object: func

-

Test whether two descriptors refer to the same filesystem object.

-

In POSIX, this corresponds to testing whether the two descriptors have the -same device (st_dev) and inode (st_ino or d_ino) numbers. -wasi-filesystem does not expose device and inode numbers, so this function -may be used instead.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]descriptor.metadata-hash: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a descriptor.

-

This returns a hash of the last-modification timestamp and file size, and -may also include the inode number, device number, birth timestamp, and -other metadata fields that may change when the file is modified or -replaced. It may also include a secret value chosen by the -implementation and not otherwise exposed.

-

Implementations are encouraged to provide the following properties:

-
    -
  • If the file is not modified or replaced, the computed hash value should -usually not change.
    • -
  • If the object is modified or replaced, the computed hash value should -usually change.
    • -
  • The inputs to the hash should not be easily computable from the -computed hash.
    • -
-

However, none of these is required.

-
Params
- -
Return values
- -

[method]descriptor.metadata-hash-at: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a directory descriptor and a relative path.

-

This performs the same hash computation as metadata-hash.

-
Params
- -
Return values
- -

[method]directory-entry-stream.read-directory-entry: func

-

Read a single directory entry from a directory-entry-stream.

-
Params
- -
Return values
- -

filesystem-error-code: func

-

Attempts to extract a filesystem-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -filesystem-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are filesystem-related errors.

-
Params
- -
Return values
- -

Import interface wasi:filesystem/preopens@0.2.12

-
-

Types

-

type descriptor

-

descriptor

-

-

-

Functions

-

get-directories: func

-

Return the set of preopened directories, and their paths.

-
Return values
- -

Import interface wasi:sockets/network@0.2.12

-
-

Types

-

type error

-

error

-

-

resource network

-

An opaque resource that represents access to (a subset of) the network. -This enables context-based security for networking. -There is no need for this to map 1:1 to a physical network interface.

-

enum error-code

-

Error codes.

-

In theory, every API can return any error code. -In practice, API's typically only return the errors documented per API -combined with a couple of errors that are always possible:

-
    -
  • unknown
    • -
  • access-denied
    • -
  • not-supported
    • -
  • out-of-memory
    • -
  • concurrency-conflict
    • -
-

See each individual API for what the POSIX equivalents are. They sometimes differ per API.

-
Enum Cases
-
    -
  • -

    unknown

    -

    Unknown error -

    • -
  • -

    access-denied

    -

    Access denied. -

    POSIX equivalent: EACCES, EPERM

    -
    • -
  • -

    not-supported

    -

    The operation is not supported. -

    POSIX equivalent: EOPNOTSUPP

    -
    • -
  • -

    invalid-argument

    -

    One of the arguments is invalid. -

    POSIX equivalent: EINVAL

    -
    • -
  • -

    out-of-memory

    -

    Not enough memory to complete the operation. -

    POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY

    -
    • -
  • -

    timeout

    -

    The operation timed out before it could finish completely. -

    • -
  • -

    concurrency-conflict

    -

    This operation is incompatible with another asynchronous operation that is already in progress. -

    POSIX equivalent: EALREADY

    -
    • -
  • -

    not-in-progress

    -

    Trying to finish an asynchronous operation that: -- has not been started yet, or: -- was already finished by a previous `finish-*` call. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    would-block

    -

    The operation has been aborted because it could not be completed immediately. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    invalid-state

    -

    The operation is not valid in the socket's current state. -

    • -
  • -

    new-socket-limit

    -

    A new socket resource could not be created because of a system limit. -

    • -
  • -

    address-not-bindable

    -

    A bind operation failed because the provided address is not an address that the `network` can bind to. -

    • -
  • -

    address-in-use

    -

    A bind operation failed because the provided address is already in use or because there are no ephemeral ports available. -

    • -
  • -

    remote-unreachable

    -

    The remote address is not reachable -

    • -
  • -

    connection-refused

    -

    The TCP connection was forcefully rejected -

    • -
  • -

    connection-reset

    -

    The TCP connection was reset. -

    • -
  • -

    connection-aborted

    -

    A TCP connection was aborted. -

    • -
  • -

    datagram-too-large

    -

    The size of a datagram sent to a UDP socket exceeded the maximum -supported size. -

    • -
  • -

    name-unresolvable

    -

    Name does not exist or has no suitable associated IP addresses. -

    • -
  • -

    temporary-resolver-failure

    -

    A temporary failure in name resolution occurred. -

    • -
  • -

    permanent-resolver-failure

    -

    A permanent failure in name resolution occurred. -

    • -
-

enum ip-address-family

-
Enum Cases
-
    -
  • -

    ipv4

    -

    Similar to `AF_INET` in POSIX. -

    • -
  • -

    ipv6

    -

    Similar to `AF_INET6` in POSIX. -

    • -
-

tuple ipv4-address

-
Tuple Fields
-
    -
  • 0: u8
    • -
  • 1: u8
    • -
  • 2: u8
    • -
  • 3: u8
    • -
-

tuple ipv6-address

-
Tuple Fields
-
    -
  • 0: u16
    • -
  • 1: u16
    • -
  • 2: u16
    • -
  • 3: u16
    • -
  • 4: u16
    • -
  • 5: u16
    • -
  • 6: u16
    • -
  • 7: u16
    • -
-

variant ip-address

-
Variant Cases
- -

record ipv4-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin_port -

    • -
  • -

    address: ipv4-address

    -

    sin_addr -

    • -
-

record ipv6-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin6_port -

    • -
  • -

    flow-info: u32

    -

    sin6_flowinfo -

    • -
  • -

    address: ipv6-address

    -

    sin6_addr -

    • -
  • -

    scope-id: u32

    -

    sin6_scope_id -

    • -
-

variant ip-socket-address

-
Variant Cases
- -
-

Functions

-

network-error-code: func

-

Attempts to extract a network-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -network-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are network-related errors.

-
Params
- -
Return values
- -

Import interface wasi:sockets/instance-network@0.2.12

-

This interface provides a value-export of the default network handle..

-
-

Types

-

type network

-

network

-

-

-

Functions

-

instance-network: func

-

Get a handle to the default network.

-
Return values
- -

Import interface wasi:sockets/udp@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

record incoming-datagram

-

A received datagram.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.

    -
    • -
  • -

    remote-address: ip-socket-address

    -

    The source address. -

    This field is guaranteed to match the remote address the stream was initialized with, if any.

    -

    Equivalent to the src_addr out parameter of recvfrom.

    -
    • -
-

record outgoing-datagram

-

A datagram to be sent out.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    • -
  • -

    remote-address: option<ip-socket-address>

    -

    The destination address. -

    The requirements on this field depend on how the stream was initialized:

    -
      -
    • with a remote address: this field must be None or match the stream's remote address exactly.
      • -
    • without a remote address: this field is required.
      • -
    -

    If this value is None, the send operation is equivalent to send in POSIX. Otherwise it is equivalent to sendto.

    -
    • -
-

resource udp-socket

-

A UDP socket handle.

-

resource incoming-datagram-stream

-

resource outgoing-datagram-stream

-
-

Functions

-

[method]udp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the port is zero, the socket will be bound to a random free port.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]udp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]udp-socket.stream: func

-

Set up inbound & outbound communication channels, optionally to a specific peer.

-

This function only changes the local socket configuration and does not generate any network traffic. -On success, the remote-address of the socket is updated. The local-address may be updated as well, -based on the best network path to remote-address.

-

When a remote-address is provided, the returned streams are limited to communicating with that specific peer:

-
    -
  • send can only be used to send to this destination.
    • -
  • receive will only return datagrams sent from the provided remote-address.
    • -
-

This method may be called multiple times on the same socket to change its association, but -only the most recently returned pair of streams will be operational. Implementations may trap if -the streams returned by a previous invocation haven't been dropped yet before calling stream again.

-

The POSIX equivalent in pseudo-code is:

-
if (was previously connected) {
-  connect(s, AF_UNSPEC)
-}
-if (remote_address is Some) {
-  connect(s, remote_address)
-}
-
-

Unlike in POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-state: The socket is not bound.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.local-address: func

-

Get the current bound address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.remote-address: func

-

Get the address the socket is currently streaming to.

-

Typical errors

-
    -
  • invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]udp-socket.unicast-hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-unicast-hop-limit: func

-
Params
- -
Return values
- -

[method]udp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.subscribe: func

-

Create a pollable which will resolve once the socket is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]incoming-datagram-stream.receive: func

-

Receive messages on the socket.

-

This function attempts to receive up to max-results datagrams on the socket without blocking. -The returned list may contain fewer elements than requested, but never more.

-

This function returns successfully with an empty list when either:

-
    -
  • max-results is 0, or:
    • -
  • max-results is greater than 0, but no results are immediately available. -This function never returns error(would-block).
    • -
-

Typical errors

-
    -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]incoming-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to receive again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.check-send: func

-

Check readiness for sending. This function never blocks.

-

Returns the number of datagrams permitted for the next call to send, -or an error. Calling send with more datagrams than this function has -permitted will trap.

-

When this function returns ok(0), the subscribe pollable will -become ready when this function will report at least ok(1), or an -error.

-

Never returns would-block.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.send: func

-

Send messages on the socket.

-

This function attempts to send all provided datagrams on the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -returns error(would-block). If none of the datagrams were able to be sent, ok(0) is returned.

-

This function semantically behaves the same as iterating the datagrams list and sequentially -sending each individual datagram until either the end of the list has been reached or the first error occurred. -If at least one datagram has been sent successfully, this function never returns an error.

-

If the input list is empty, the function returns ok(0).

-

Each call to send must be permitted by a preceding check-send. Implementations must trap if -either check-send was not called or datagrams contains more items than check-send permitted.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)
    • -
  • invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
  • datagram-too-large: The datagram is too large. (EMSGSIZE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]outgoing-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to send again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

Import interface wasi:sockets/udp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type udp-socket

-

udp-socket

-

-

-

Functions

-

create-udp-socket: func

-

Create a new UDP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind is called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References:

- -
Params
- -
Return values
- -

Import interface wasi:sockets/tcp@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type pollable

-

pollable

-

-

type duration

-

duration

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

enum shutdown-type

-
Enum Cases
-
    -
  • -

    receive

    -

    Similar to `SHUT_RD` in POSIX. -

    • -
  • -

    send

    -

    Similar to `SHUT_WR` in POSIX. -

    • -
  • -

    both

    -

    Similar to `SHUT_RDWR` in POSIX. -

    • -
-

resource tcp-socket

-

A TCP socket resource.

-

The socket can be in one of the following states:

- -

Note: Except where explicitly mentioned, whenever this documentation uses -the term "bound" without backticks it actually means: in the bound state or higher. -(i.e. bound, listen-in-progress, listening, connect-in-progress or connected)

-

In addition to the general error codes documented on the -network::error-code type, TCP socket methods may always return -error(invalid-state) when in the closed state.

-

Functions

-

[method]tcp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the TCP/UDP port is zero, the socket will be bound to a random free port.

-

Bind can be attempted multiple times on the same socket, even with -different arguments on each iteration. But never concurrently and -only as long as the previous bind failed. Once a bind succeeds, the -binding can't be changed anymore.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • -
  • invalid-argument: local-address is an IPv4-mapped IPv6 address. (EINVAL)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT -state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR -socket option should be set implicitly on all platforms, except on Windows where this is the default behavior -and SO_REUSEADDR performs something different entirely.

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-connect: func

-

Connect to a remote endpoint.

-

On success:

-
    -
  • the socket is transitioned into the connected state.
    • -
  • a pair of streams is returned that can be used to read & write to the connection
    • -
-

After a failed connection attempt, the socket will be in the closed -state and the only valid action left is to drop the socket. A single -socket can not be used to connect more than once.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • -
  • invalid-argument: remote-address is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN)
    • -
  • invalid-state: The socket is already in the listening state. (EOPNOTSUPP, EINVAL on Windows)
    • -
  • timeout: Connection timed out. (ETIMEDOUT)
    • -
  • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • -
  • connection-reset: The connection was reset. (ECONNRESET)
    • -
  • connection-aborted: The connection was aborted. (ECONNABORTED)
    • -
  • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • not-in-progress: A connect operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

The POSIX equivalent of start-connect is the regular connect syscall. -Because all WASI sockets are non-blocking this is expected to return -EINPROGRESS, which should be translated to ok() in WASI.

-

The POSIX equivalent of finish-connect is a poll for event POLLOUT -with a timeout of 0 on the socket descriptor. Followed by a check for -the SO_ERROR socket option, in case the poll signaled readiness.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-connect: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-listen: func

-

Start listening for new connections.

-

Transitions the socket into the listening state.

-

Unlike POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address. (EDESTADDRREQ)
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN, EINVAL on BSD)
    • -
  • invalid-state: The socket is already in the listening state.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
    • -
  • not-in-progress: A listen operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the listen operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -listen as part of either start-listen or finish-listen.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-listen: func

-
Params
- -
Return values
- -

[method]tcp-socket.accept: func

-

Accept a new client socket.

-

The returned socket is bound and in the connected state. The following properties are inherited from the listener socket:

-
    -
  • address-family
    • -
  • keep-alive-enabled
    • -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count
    • -
  • hop-limit
    • -
  • receive-buffer-size
    • -
  • send-buffer-size
    • -
-

On success, this function returns the newly accepted client socket along with -a pair of streams that can be used to read & write to the connection.

-

Typical errors

-
    -
  • invalid-state: Socket is not in the listening state. (EINVAL)
    • -
  • would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
    • -
  • connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.local-address: func

-

Get the bound local address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.remote-address: func

-

Get the remote address.

-

Typical errors

-
    -
  • invalid-state: The socket is not connected to a remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.is-listening: func

-

Whether the socket is in the listening state.

-

Equivalent to the SO_ACCEPTCONN socket option.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]tcp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-listen-backlog-size: func

-

Hints the desired listen queue size. Implementations are free to ignore this.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded.

-

Typical errors

-
    -
  • not-supported: (set) The platform does not support changing the backlog size after the initial listen.
    • -
  • invalid-argument: (set) The provided value was 0.
    • -
  • invalid-state: (set) The socket is in the connect-in-progress or connected state.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-enabled: func

-

Enables or disables keepalive.

-

The keepalive behavior can be adjusted using:

-
    -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count -These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.
    • -
-

Equivalent to the SO_KEEPALIVE socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-enabled: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-idle-time: func

-

Amount of time the connection has to be idle before TCP starts sending keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-idle-time: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-interval: func

-

The time between keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPINTVL socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-interval: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-count: func

-

The maximum amount of keepalive packets TCP should send before aborting the connection.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPCNT socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-count: func

-
Params
- -
Return values
- -

[method]tcp-socket.hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-hop-limit: func

-
Params
- -
Return values
- -

[method]tcp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.subscribe: func

-

Create a pollable which can be used to poll for, or block on, -completion of any of the asynchronous operations of this socket.

-

When finish-bind, finish-listen, finish-connect or accept -return error(would-block), this pollable can be used to wait for -their success or failure, after which the method can be retried.

-

The pollable is not limited to the async operation that happens to be -in progress at the time of calling subscribe (if any). Theoretically, -subscribe only has to be called once per socket and can then be -(re)used for the remainder of the socket's lifetime.

-

See https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/TcpSocketOperationalSemantics.md#pollable-readiness -for more information.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]tcp-socket.shutdown: func

-

Initiate a graceful shutdown.

-
    -
  • receive: The socket is not expecting to receive any data from -the peer. The input-stream associated with this socket will be -closed. Any data still in the receive queue at time of calling -this method will be discarded.
    • -
  • send: The socket has no more data to send to the peer. The output-stream -associated with this socket will be closed and a FIN packet will be sent.
    • -
  • both: Same effect as receive & send combined.
    • -
-

This function is idempotent; shutting down a direction more than once -has no effect and returns ok.

-

The shutdown function does not close (drop) the socket.

-

Typical errors

-
    -
  • invalid-state: The socket is not in the connected state. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/tcp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type tcp-socket

-

tcp-socket

-

-

-

Functions

-

create-tcp-socket: func

-

Create a new TCP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect -is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/ip-name-lookup@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address

-

ip-address

-

-

resource resolve-address-stream

-
-

Functions

-

resolve-addresses: func

-

Resolve an internet host name to a list of IP addresses.

-

Unicode domain names are automatically converted to ASCII using IDNA encoding. -If the input is an IP address string, the address is parsed and returned -as-is without making any external requests.

-

See the wasi-socket proposal README.md for a comparison with getaddrinfo.

-

This function never blocks. It either immediately fails or immediately -returns successfully with a resolve-address-stream that can be used -to (asynchronously) fetch the results.

-

Typical errors

-
    -
  • invalid-argument: name is a syntactically invalid domain name or IP address.
    • -
-

References:

- -
Params
- -
Return values
- -

[method]resolve-address-stream.resolve-next-address: func

-

Returns the next address from the resolver.

-

This function should be called multiple times. On each call, it will -return the next address in connection order preference. If all -addresses have been exhausted, this function returns none.

-

This function never returns IPv4-mapped IPv6 addresses.

-

Typical errors

-
    -
  • name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
    • -
  • temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)
    • -
  • permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)
    • -
  • would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)
    • -
-
Params
- -
Return values
- -

[method]resolve-address-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

Import interface wasi:random/random@0.2.12

-

WASI Random is a random data API.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-random-bytes: func

-

Return len cryptographically-secure random or pseudo-random bytes.

-

This function must produce data at least as cryptographically secure and -fast as an adequately seeded cryptographically-secure pseudo-random -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-random-u64: func

-

Return a cryptographically-secure random or pseudo-random u64 value.

-

This function returns the same type of data as get-random-bytes, -represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure@0.2.12

-

The insecure interface for insecure pseudo-random numbers.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-insecure-random-bytes: func

-

Return len insecure pseudo-random bytes.

-

This function is not cryptographically secure. Do not use it for -anything related to security.

-

There are no requirements on the values of the returned bytes, however -implementations are encouraged to return evenly distributed values with -a long period.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-insecure-random-u64: func

-

Return an insecure pseudo-random u64 value.

-

This function returns the same type of pseudo-random data as -get-insecure-random-bytes, represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure-seed@0.2.12

-

The insecure-seed interface for seeding hash-map DoS resistance.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

insecure-seed: func

-

Return a 128-bit value that may contain a pseudo-random value.

-

The returned value is not required to be computed from a CSPRNG, and may -even be entirely deterministic. Host implementations are encouraged to -provide pseudo-random values to any program exposed to -attacker-controlled content, to enable DoS protection built into many -languages' hash-map implementations.

-

This function is intended to only be called once, by a source language -to initialize Denial Of Service (DoS) protection in its hash-map -implementation.

-

Expected future evolution

-

This will likely be changed to a value import, to prevent it from being -called multiple times and potentially used for purposes other than DoS -protection.

-
Return values
-
    -
  • (u64, u64)
    • -
diff --git a/proposals/cli/wit-0.3.0-draft/command.wit b/proposals/cli/wit-0.3.0-draft/command.wit deleted file mode 100644 index 12cdb1044..000000000 --- a/proposals/cli/wit-0.3.0-draft/command.wit +++ /dev/null @@ -1,10 +0,0 @@ -package wasi:cli@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world command { - @since(version = 0.3.0-rc-2026-03-15) - include imports; - - @since(version = 0.3.0-rc-2026-03-15) - export run; -} diff --git a/proposals/cli/wit-0.3.0-draft/deps.lock b/proposals/cli/wit-0.3.0-draft/deps.lock deleted file mode 100644 index c3eb59ccc..000000000 --- a/proposals/cli/wit-0.3.0-draft/deps.lock +++ /dev/null @@ -1,19 +0,0 @@ -[clocks] -path = "../../clocks/wit-0.3.0-draft" -sha256 = "a8702c42e23c22a458207d0efa38cc1b64c8c6299b0e3152aa84327a7c1c952b" -sha512 = "da69a5d498b6afe0facf77ec3d21f6e8a2a4d4661ebfec310a2ce6f943cb01f92131a746765648febf96563ddac788e9f218941d3db2b905f3746dc8e05cf54d" - -[filesystem] -path = "../../filesystem/wit-0.3.0-draft" -sha256 = "d9db43c43b4e09899a9e54c76544eef17439fb42e2f730ed96d40eac994b0dfd" -sha512 = "3b7a1bef322ba36b1e9df768d740e4238f58d3c15d3e4c51fe899b93cf1e6641a79b5a8665ae71d38a80e1e0f852b30b023ecf318f4cbeacb36dd1ae0ac7e37b" - -[random] -path = "../../random/wit-0.3.0-draft" -sha256 = "d44de4e427505fdfd584a23479dba5899ad80aa8e174dc0528df840db8ae9a43" -sha512 = "6b08b32a197aee74076d0cdca6a09f78da9040eedd9ab3f64e5f14901ad5a0c5bbc592ad46a0d575dc6705249b3e10a413e09835616f753788aa598af605c776" - -[sockets] -path = "../../sockets/wit-0.3.0-draft" -sha256 = "ee64b45d3826b6ff2cd27f6ac24fe23c41e65ba4d155294671dc7d0a0b47ddfe" -sha512 = "dd797ab47b899aee52799f797497fa286f5e217307e8a451a7ba89bd05b7b9bfe2a6e0cf39c0e609ed4c76ed102487adff6e73156340f14baf70a9cc9e48ecbc" diff --git a/proposals/cli/wit-0.3.0-draft/deps.toml b/proposals/cli/wit-0.3.0-draft/deps.toml deleted file mode 100644 index e66b87555..000000000 --- a/proposals/cli/wit-0.3.0-draft/deps.toml +++ /dev/null @@ -1,4 +0,0 @@ -clocks = "../../clocks/wit-0.3.0-draft" -sockets = "../../sockets/wit-0.3.0-draft" -random = "../../random/wit-0.3.0-draft" -filesystem = "../../filesystem/wit-0.3.0-draft" diff --git a/proposals/cli/wit-0.3.0-draft/environment.wit b/proposals/cli/wit-0.3.0-draft/environment.wit deleted file mode 100644 index 7abda6b60..000000000 --- a/proposals/cli/wit-0.3.0-draft/environment.wit +++ /dev/null @@ -1,22 +0,0 @@ -@since(version = 0.3.0-rc-2026-03-15) -interface environment { - /// Get the POSIX-style environment variables. - /// - /// Each environment variable is provided as a pair of string variable names - /// and string value. - /// - /// Morally, these are a value import, but until value imports are available - /// in the component model, this import function should return the same - /// values each time it is called. - @since(version = 0.3.0-rc-2026-03-15) - get-environment: func() -> list>; - - /// Get the POSIX-style arguments to the program. - @since(version = 0.3.0-rc-2026-03-15) - get-arguments: func() -> list; - - /// Return a path that programs should use as their initial current working - /// directory, interpreting `.` as shorthand for this. - @since(version = 0.3.0-rc-2026-03-15) - get-initial-cwd: func() -> option; -} diff --git a/proposals/cli/wit-0.3.0-draft/exit.wit b/proposals/cli/wit-0.3.0-draft/exit.wit deleted file mode 100644 index 24e337d5b..000000000 --- a/proposals/cli/wit-0.3.0-draft/exit.wit +++ /dev/null @@ -1,17 +0,0 @@ -@since(version = 0.3.0-rc-2026-03-15) -interface exit { - /// Exit the current instance and any linked instances. - @since(version = 0.3.0-rc-2026-03-15) - exit: func(status: result); - - /// Exit the current instance and any linked instances, reporting the - /// specified status code to the host. - /// - /// The meaning of the code depends on the context, with 0 usually meaning - /// "success", and other values indicating various types of failure. - /// - /// This function does not return; the effect is analogous to a trap, but - /// without the connotation that something bad has happened. - @since(version = 0.3.0-rc-2026-03-15) - exit-with-code: func(status-code: u8); -} diff --git a/proposals/cli/wit-0.3.0-draft/imports.wit b/proposals/cli/wit-0.3.0-draft/imports.wit deleted file mode 100644 index 398b632d8..000000000 --- a/proposals/cli/wit-0.3.0-draft/imports.wit +++ /dev/null @@ -1,34 +0,0 @@ -package wasi:cli@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world imports { - @since(version = 0.3.0-rc-2026-03-15) - include wasi:clocks/imports@0.3.0-rc-2026-03-15; - @since(version = 0.3.0-rc-2026-03-15) - include wasi:filesystem/imports@0.3.0-rc-2026-03-15; - @since(version = 0.3.0-rc-2026-03-15) - include wasi:sockets/imports@0.3.0-rc-2026-03-15; - @since(version = 0.3.0-rc-2026-03-15) - include wasi:random/imports@0.3.0-rc-2026-03-15; - - @since(version = 0.3.0-rc-2026-03-15) - import environment; - @since(version = 0.3.0-rc-2026-03-15) - import exit; - @since(version = 0.3.0-rc-2026-03-15) - import stdin; - @since(version = 0.3.0-rc-2026-03-15) - import stdout; - @since(version = 0.3.0-rc-2026-03-15) - import stderr; - @since(version = 0.3.0-rc-2026-03-15) - import terminal-input; - @since(version = 0.3.0-rc-2026-03-15) - import terminal-output; - @since(version = 0.3.0-rc-2026-03-15) - import terminal-stdin; - @since(version = 0.3.0-rc-2026-03-15) - import terminal-stdout; - @since(version = 0.3.0-rc-2026-03-15) - import terminal-stderr; -} diff --git a/proposals/cli/wit-0.3.0-draft/run.wit b/proposals/cli/wit-0.3.0-draft/run.wit deleted file mode 100644 index d65831096..000000000 --- a/proposals/cli/wit-0.3.0-draft/run.wit +++ /dev/null @@ -1,6 +0,0 @@ -@since(version = 0.3.0-rc-2026-03-15) -interface run { - /// Run the program. - @since(version = 0.3.0-rc-2026-03-15) - run: async func() -> result; -} diff --git a/proposals/cli/wit-0.3.0-draft/stdio.wit b/proposals/cli/wit-0.3.0-draft/stdio.wit deleted file mode 100644 index a46ee6da0..000000000 --- a/proposals/cli/wit-0.3.0-draft/stdio.wit +++ /dev/null @@ -1,65 +0,0 @@ -@since(version = 0.3.0-rc-2026-03-15) -interface types { - @since(version = 0.3.0-rc-2026-03-15) - enum error-code { - /// Input/output error - io, - /// Invalid or incomplete multibyte or wide character - illegal-byte-sequence, - /// Broken pipe - pipe, - } -} - -@since(version = 0.3.0-rc-2026-03-15) -interface stdin { - use types.{error-code}; - - /// Return a stream for reading from stdin. - /// - /// This function returns a stream which provides data read from stdin, - /// and a future to signal read results. - /// - /// If the stream's readable end is dropped the future will resolve to success. - /// - /// If the stream's writable end is dropped the future will either resolve to - /// success if stdin was closed by the writer or to an error-code if reading - /// failed for some other reason. - /// - /// Multiple streams may be active at the same time. The behavior of concurrent - /// reads is implementation-specific. - @since(version = 0.3.0-rc-2026-03-15) - read-via-stream: func() -> tuple, future>>; -} - -@since(version = 0.3.0-rc-2026-03-15) -interface stdout { - use types.{error-code}; - - /// Write the given stream to stdout. - /// - /// If the stream's writable end is dropped this function will either return - /// success once the entire contents of the stream have been written or an - /// error-code representing a failure. - /// - /// Otherwise if there is an error the readable end of the stream will be - /// dropped and this function will return an error-code. - @since(version = 0.3.0-rc-2026-03-15) - write-via-stream: func(data: stream) -> future>; -} - -@since(version = 0.3.0-rc-2026-03-15) -interface stderr { - use types.{error-code}; - - /// Write the given stream to stderr. - /// - /// If the stream's writable end is dropped this function will either return - /// success once the entire contents of the stream have been written or an - /// error-code representing a failure. - /// - /// Otherwise if there is an error the readable end of the stream will be - /// dropped and this function will return an error-code. - @since(version = 0.3.0-rc-2026-03-15) - write-via-stream: func(data: stream) -> future>; -} diff --git a/proposals/cli/wit-0.3.0-draft/terminal.wit b/proposals/cli/wit-0.3.0-draft/terminal.wit deleted file mode 100644 index 3ae61915b..000000000 --- a/proposals/cli/wit-0.3.0-draft/terminal.wit +++ /dev/null @@ -1,62 +0,0 @@ -/// Terminal input. -/// -/// In the future, this may include functions for disabling echoing, -/// disabling input buffering so that keyboard events are sent through -/// immediately, querying supported features, and so on. -@since(version = 0.3.0-rc-2026-03-15) -interface terminal-input { - /// The input side of a terminal. - @since(version = 0.3.0-rc-2026-03-15) - resource terminal-input; -} - -/// Terminal output. -/// -/// In the future, this may include functions for querying the terminal -/// size, being notified of terminal size changes, querying supported -/// features, and so on. -@since(version = 0.3.0-rc-2026-03-15) -interface terminal-output { - /// The output side of a terminal. - @since(version = 0.3.0-rc-2026-03-15) - resource terminal-output; -} - -/// An interface providing an optional `terminal-input` for stdin as a -/// link-time authority. -@since(version = 0.3.0-rc-2026-03-15) -interface terminal-stdin { - @since(version = 0.3.0-rc-2026-03-15) - use terminal-input.{terminal-input}; - - /// If stdin is connected to a terminal, return a `terminal-input` handle - /// allowing further interaction with it. - @since(version = 0.3.0-rc-2026-03-15) - get-terminal-stdin: func() -> option; -} - -/// An interface providing an optional `terminal-output` for stdout as a -/// link-time authority. -@since(version = 0.3.0-rc-2026-03-15) -interface terminal-stdout { - @since(version = 0.3.0-rc-2026-03-15) - use terminal-output.{terminal-output}; - - /// If stdout is connected to a terminal, return a `terminal-output` handle - /// allowing further interaction with it. - @since(version = 0.3.0-rc-2026-03-15) - get-terminal-stdout: func() -> option; -} - -/// An interface providing an optional `terminal-output` for stderr as a -/// link-time authority. -@since(version = 0.3.0-rc-2026-03-15) -interface terminal-stderr { - @since(version = 0.3.0-rc-2026-03-15) - use terminal-output.{terminal-output}; - - /// If stderr is connected to a terminal, return a `terminal-output` handle - /// allowing further interaction with it. - @since(version = 0.3.0-rc-2026-03-15) - get-terminal-stderr: func() -> option; -} diff --git a/proposals/cli/wit/command.wit b/proposals/cli/wit/command.wit index d36439418..0310e5151 100644 --- a/proposals/cli/wit/command.wit +++ b/proposals/cli/wit/command.wit @@ -1,10 +1,10 @@ -package wasi:cli@0.2.12; +package wasi:cli@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world command { - @since(version = 0.2.0) + @since(version = 0.3.0) include imports; - @since(version = 0.2.0) + @since(version = 0.3.0) export run; } diff --git a/proposals/cli/wit/deps.lock b/proposals/cli/wit/deps.lock index 0b1fda9bd..705b4f278 100644 --- a/proposals/cli/wit/deps.lock +++ b/proposals/cli/wit/deps.lock @@ -1,24 +1,19 @@ [clocks] path = "../../clocks/wit" -sha256 = "85b95504b5f627086433c75a634ef86cc5a346f000acd158b94cb01d508b1992" -sha512 = "b2ba12c17a022788a9ed0d1a11bd605c579ab9614edd6ba02ba6ae59e4265ed02dff718b374181be4fc7c60e0e44d0ef65ab9ddda559f2b75ccc5ca2bb6d7b9f" +sha256 = "2d288cb781c60ae462537b39e4699de38f88072b501fc7f97d3f20984d550bcf" +sha512 = "1563eeeacbfea89e44f668b8588ef95b31feac7d9ec3bb5dad932320478b1aff1448031f44afa15ed926981855ac5bd504126389ddb7802f79c63b81b3c5ede7" [filesystem] path = "../../filesystem/wit" -sha256 = "1833958cf47f63ea6ff67cc5ff82ac64069d794007d7c69ce493febce5309962" -sha512 = "be1ba82a942f15bcde1834f8d4889ea65879d4ec69ec474937ed7740ea805aa21eb8aabf145d8d7f1110e9b286e339530ee468e947942f6da1586abbae888a72" - -[io] -path = "../../io/wit" -sha256 = "b45dcb3986b694bd2de3b4c092ee3cc3b0e7c654a93e5dee0c5b32e349d1b0d8" -sha512 = "08ab049d3887d12bd5ae650703b325fd5d26a340e7e6f53c77c5ecfefa79d3b9c61801b6eb00872ecd91f74572ef5684b0850721c715b4062158e00fae6c1dc2" +sha256 = "2c804c867e34eabd75171119f062a49a1b9758d1ec1956535e467b7353e61dd3" +sha512 = "db25d5306dc671c7a7db6a273318d056d6e544567636b3759db48ab4e81a06bc5c1fc3aa2d1522d4187a116730b1a8ecc57a4f974925fda6deaaf06d237da6df" [random] path = "../../random/wit" -sha256 = "11a4642d55267644bd11f302661c044f6cb1c43a6aea5c4f919fdc1e49840551" -sha512 = "dc1d74031ee032388ad410d82daae9b2dd052624f7b542ac2912ffec647fb507fb534b4506b337a8f993faf6aefecc57795537b63c41cdd927efd745ffb60cbc" +sha256 = "607700294fdbd7de5c4771628db8830b05ae53c48e66c7645feae98f298a5feb" +sha512 = "a059c887a04b2927df93b8eb83e0843d9ab804e31dee060bf83b74fa6fdd24fbafbb7f9cfcbfa7838cbf6c7e684de8fd4c0b338f3006db1077dd338bf01445ce" [sockets] path = "../../sockets/wit" -sha256 = "2ee88acd6247b6dc8ebeddab95f43ab8a7b587c58b211e6d8022c3b8ac9ff984" -sha512 = "5dfbdf4a5548b16e9303da4ea4e0493ace30060fc67422e894f5f9da70c7c219ec848829518b6dd445675f795763a1ee4ca04fc65fc63210d75739e4850a5dd8" +sha256 = "663af53b8a4e6aa66fa24618c5d0d6dd4bfaa970121a85951e8ab52cea0b0852" +sha512 = "4faf0eb9e8f486d3dadddc7f491f87ca6b1626f0296e8e918c529f39696f61398e4c37d0dfa6529a157f65747bbd455487fe0b6bb04e075d65a8d75844225e2a" diff --git a/proposals/cli/wit/deps.toml b/proposals/cli/wit/deps.toml index cde7a0ce7..07429c736 100644 --- a/proposals/cli/wit/deps.toml +++ b/proposals/cli/wit/deps.toml @@ -1,5 +1,4 @@ -filesystem = "../../filesystem/wit" -random = "../../random/wit" -sockets = "../../sockets/wit" clocks = "../../clocks/wit" -io = "../../io/wit" +sockets = "../../sockets/wit" +random = "../../random/wit" +filesystem = "../../filesystem/wit" diff --git a/proposals/cli/wit/environment.wit b/proposals/cli/wit/environment.wit index 2f449bd7c..fb14eee67 100644 --- a/proposals/cli/wit/environment.wit +++ b/proposals/cli/wit/environment.wit @@ -1,4 +1,4 @@ -@since(version = 0.2.0) +@since(version = 0.3.0) interface environment { /// Get the POSIX-style environment variables. /// @@ -8,15 +8,15 @@ interface environment { /// Morally, these are a value import, but until value imports are available /// in the component model, this import function should return the same /// values each time it is called. - @since(version = 0.2.0) + @since(version = 0.3.0) get-environment: func() -> list>; /// Get the POSIX-style arguments to the program. - @since(version = 0.2.0) + @since(version = 0.3.0) get-arguments: func() -> list; /// Return a path that programs should use as their initial current working /// directory, interpreting `.` as shorthand for this. - @since(version = 0.2.0) - initial-cwd: func() -> option; + @since(version = 0.3.0) + get-initial-cwd: func() -> option; } diff --git a/proposals/cli/wit/exit.wit b/proposals/cli/wit/exit.wit index 3dffe9873..c412d148b 100644 --- a/proposals/cli/wit/exit.wit +++ b/proposals/cli/wit/exit.wit @@ -1,7 +1,7 @@ -@since(version = 0.2.0) +@since(version = 0.3.0) interface exit { /// Exit the current instance and any linked instances. - @since(version = 0.2.0) + @since(version = 0.3.0) exit: func(status: result); /// Exit the current instance and any linked instances, reporting the @@ -12,6 +12,6 @@ interface exit { /// /// This function does not return; the effect is analogous to a trap, but /// without the connotation that something bad has happened. - @since(version = 0.2.12) + @since(version = 0.3.0) exit-with-code: func(status-code: u8); } diff --git a/proposals/cli/wit/imports.wit b/proposals/cli/wit/imports.wit index 8d91ed270..5dbc2ede8 100644 --- a/proposals/cli/wit/imports.wit +++ b/proposals/cli/wit/imports.wit @@ -1,36 +1,34 @@ -package wasi:cli@0.2.12; +package wasi:cli@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world imports { - @since(version = 0.2.0) - include wasi:clocks/imports@0.2.12; - @since(version = 0.2.0) - include wasi:filesystem/imports@0.2.12; - @since(version = 0.2.0) - include wasi:sockets/imports@0.2.12; - @since(version = 0.2.0) - include wasi:random/imports@0.2.12; - @since(version = 0.2.0) - include wasi:io/imports@0.2.12; + @since(version = 0.3.0) + include wasi:clocks/imports@0.3.0; + @since(version = 0.3.0) + include wasi:filesystem/imports@0.3.0; + @since(version = 0.3.0) + include wasi:sockets/imports@0.3.0; + @since(version = 0.3.0) + include wasi:random/imports@0.3.0; - @since(version = 0.2.0) + @since(version = 0.3.0) import environment; - @since(version = 0.2.0) + @since(version = 0.3.0) import exit; - @since(version = 0.2.0) + @since(version = 0.3.0) import stdin; - @since(version = 0.2.0) + @since(version = 0.3.0) import stdout; - @since(version = 0.2.0) + @since(version = 0.3.0) import stderr; - @since(version = 0.2.0) + @since(version = 0.3.0) import terminal-input; - @since(version = 0.2.0) + @since(version = 0.3.0) import terminal-output; - @since(version = 0.2.0) + @since(version = 0.3.0) import terminal-stdin; - @since(version = 0.2.0) + @since(version = 0.3.0) import terminal-stdout; - @since(version = 0.2.0) + @since(version = 0.3.0) import terminal-stderr; } diff --git a/proposals/cli/wit/run.wit b/proposals/cli/wit/run.wit index 655346efb..10b6e49f3 100644 --- a/proposals/cli/wit/run.wit +++ b/proposals/cli/wit/run.wit @@ -1,6 +1,6 @@ -@since(version = 0.2.0) +@since(version = 0.3.0) interface run { /// Run the program. - @since(version = 0.2.0) - run: func() -> result; + @since(version = 0.3.0) + run: async func() -> result; } diff --git a/proposals/cli/wit/stdio.wit b/proposals/cli/wit/stdio.wit index 2fe15f75b..56eebe4ea 100644 --- a/proposals/cli/wit/stdio.wit +++ b/proposals/cli/wit/stdio.wit @@ -1,26 +1,65 @@ -@since(version = 0.2.0) +@since(version = 0.3.0) +interface types { + @since(version = 0.3.0) + enum error-code { + /// Input/output error + io, + /// Invalid or incomplete multibyte or wide character + illegal-byte-sequence, + /// Broken pipe + pipe, + } +} + +@since(version = 0.3.0) interface stdin { - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{input-stream}; + use types.{error-code}; - @since(version = 0.2.0) - get-stdin: func() -> input-stream; + /// Return a stream for reading from stdin. + /// + /// This function returns a stream which provides data read from stdin, + /// and a future to signal read results. + /// + /// If the stream's readable end is dropped the future will resolve to success. + /// + /// If the stream's writable end is dropped the future will either resolve to + /// success if stdin was closed by the writer or to an error-code if reading + /// failed for some other reason. + /// + /// Multiple streams may be active at the same time. The behavior of concurrent + /// reads is implementation-specific. + @since(version = 0.3.0) + read-via-stream: func() -> tuple, future>>; } -@since(version = 0.2.0) +@since(version = 0.3.0) interface stdout { - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{output-stream}; + use types.{error-code}; - @since(version = 0.2.0) - get-stdout: func() -> output-stream; + /// Write the given stream to stdout. + /// + /// If the stream's writable end is dropped this function will either return + /// success once the entire contents of the stream have been written or an + /// error-code representing a failure. + /// + /// Otherwise if there is an error the readable end of the stream will be + /// dropped and this function will return an error-code. + @since(version = 0.3.0) + write-via-stream: func(data: stream) -> future>; } -@since(version = 0.2.0) +@since(version = 0.3.0) interface stderr { - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{output-stream}; + use types.{error-code}; - @since(version = 0.2.0) - get-stderr: func() -> output-stream; + /// Write the given stream to stderr. + /// + /// If the stream's writable end is dropped this function will either return + /// success once the entire contents of the stream have been written or an + /// error-code representing a failure. + /// + /// Otherwise if there is an error the readable end of the stream will be + /// dropped and this function will return an error-code. + @since(version = 0.3.0) + write-via-stream: func(data: stream) -> future>; } diff --git a/proposals/cli/wit/terminal.wit b/proposals/cli/wit/terminal.wit index d305498c6..c37184f4c 100644 --- a/proposals/cli/wit/terminal.wit +++ b/proposals/cli/wit/terminal.wit @@ -3,10 +3,10 @@ /// In the future, this may include functions for disabling echoing, /// disabling input buffering so that keyboard events are sent through /// immediately, querying supported features, and so on. -@since(version = 0.2.0) +@since(version = 0.3.0) interface terminal-input { /// The input side of a terminal. - @since(version = 0.2.0) + @since(version = 0.3.0) resource terminal-input; } @@ -15,48 +15,48 @@ interface terminal-input { /// In the future, this may include functions for querying the terminal /// size, being notified of terminal size changes, querying supported /// features, and so on. -@since(version = 0.2.0) +@since(version = 0.3.0) interface terminal-output { /// The output side of a terminal. - @since(version = 0.2.0) + @since(version = 0.3.0) resource terminal-output; } /// An interface providing an optional `terminal-input` for stdin as a /// link-time authority. -@since(version = 0.2.0) +@since(version = 0.3.0) interface terminal-stdin { - @since(version = 0.2.0) + @since(version = 0.3.0) use terminal-input.{terminal-input}; /// If stdin is connected to a terminal, return a `terminal-input` handle /// allowing further interaction with it. - @since(version = 0.2.0) + @since(version = 0.3.0) get-terminal-stdin: func() -> option; } /// An interface providing an optional `terminal-output` for stdout as a /// link-time authority. -@since(version = 0.2.0) +@since(version = 0.3.0) interface terminal-stdout { - @since(version = 0.2.0) + @since(version = 0.3.0) use terminal-output.{terminal-output}; /// If stdout is connected to a terminal, return a `terminal-output` handle /// allowing further interaction with it. - @since(version = 0.2.0) + @since(version = 0.3.0) get-terminal-stdout: func() -> option; } /// An interface providing an optional `terminal-output` for stderr as a /// link-time authority. -@since(version = 0.2.0) +@since(version = 0.3.0) interface terminal-stderr { - @since(version = 0.2.0) + @since(version = 0.3.0) use terminal-output.{terminal-output}; /// If stderr is connected to a terminal, return a `terminal-output` handle /// allowing further interaction with it. - @since(version = 0.2.0) + @since(version = 0.3.0) get-terminal-stderr: func() -> option; } diff --git a/proposals/clocks/imports.md b/proposals/clocks/imports.md deleted file mode 100644 index 1f4be5063..000000000 --- a/proposals/clocks/imports.md +++ /dev/null @@ -1,233 +0,0 @@ -

World imports

- -

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:clocks/timezone@0.2.12

-
-

Types

-

type datetime

-

datetime

-

-

record timezone-display

-

Information useful for displaying the timezone of a specific datetime.

-

This information may vary within a single timezone to reflect daylight -saving time adjustments.

-
Record Fields
-
    -
  • -

    utc-offset: s32

    -

    The number of seconds difference between UTC time and the local -time of the timezone. -

    The returned value will always be less than 86400 which is the -number of seconds in a day (246060).

    -

    In implementations that do not expose an actual time zone, this -should return 0.

    -
    • -
  • -

    name: string

    -

    The abbreviated name of the timezone to display to a user. The name -`UTC` indicates Coordinated Universal Time. Otherwise, this should -reference local standards for the name of the time zone. -

    In implementations that do not expose an actual time zone, this -should be the string UTC.

    -

    In time zones that do not have an applicable name, a formatted -representation of the UTC offset may be returned, such as -04:00.

    -
    • -
  • -

    in-daylight-saving-time: bool

    -

    Whether daylight saving time is active. -

    In implementations that do not expose an actual time zone, this -should return false.

    -
    • -
-
-

Functions

-

display: func

-

Return information needed to display the given datetime. This includes -the UTC offset, the time zone name, and a flag indicating whether -daylight saving time is active.

-

If the timezone cannot be determined for the given datetime, return a -timezone-display for UTC with a utc-offset of 0 and no daylight -saving time.

-
Params
- -
Return values
- -

utc-offset: func

-

The same as display, but only return the UTC offset.

-
Params
- -
Return values
-
    -
  • s32
    • -
diff --git a/proposals/clocks/wit-0.3.0-draft/monotonic-clock.wit b/proposals/clocks/wit-0.3.0-draft/monotonic-clock.wit deleted file mode 100644 index 786ae103b..000000000 --- a/proposals/clocks/wit-0.3.0-draft/monotonic-clock.wit +++ /dev/null @@ -1,48 +0,0 @@ -package wasi:clocks@0.3.0-rc-2026-03-15; -/// WASI Monotonic Clock is a clock API intended to let users measure elapsed -/// time. -/// -/// It is intended to be portable at least between Unix-family platforms and -/// Windows. -/// -/// A monotonic clock is a clock which has an unspecified initial value, and -/// successive reads of the clock will produce non-decreasing values. -@since(version = 0.3.0-rc-2026-03-15) -interface monotonic-clock { - use types.{duration}; - - /// A mark on a monotonic clock is a number of nanoseconds since an - /// unspecified initial value, and can only be compared to instances from - /// the same monotonic-clock. - @since(version = 0.3.0-rc-2026-03-15) - type mark = u64; - - /// Read the current value of the clock. - /// - /// The clock is monotonic, therefore calling this function repeatedly will - /// produce a sequence of non-decreasing values. - /// - /// For completeness, this function traps if it's not possible to represent - /// the value of the clock in a `mark`. Consequently, implementations - /// should ensure that the starting time is low enough to avoid the - /// possibility of overflow in practice. - @since(version = 0.3.0-rc-2026-03-15) - now: func() -> mark; - - /// Query the resolution of the clock. Returns the duration of time - /// corresponding to a clock tick. - @since(version = 0.3.0-rc-2026-03-15) - get-resolution: func() -> duration; - - /// Wait until the specified mark has occurred. - @since(version = 0.3.0-rc-2026-03-15) - wait-until: async func( - when: mark, - ); - - /// Wait for the specified duration to elapse. - @since(version = 0.3.0-rc-2026-03-15) - wait-for: async func( - how-long: duration, - ); -} diff --git a/proposals/clocks/wit-0.3.0-draft/timezone.wit b/proposals/clocks/wit-0.3.0-draft/timezone.wit deleted file mode 100644 index 8b2e3e835..000000000 --- a/proposals/clocks/wit-0.3.0-draft/timezone.wit +++ /dev/null @@ -1,46 +0,0 @@ -package wasi:clocks@0.3.0-rc-2026-03-15; - -@unstable(feature = clocks-timezone) -interface timezone { - @unstable(feature = clocks-timezone) - use system-clock.{instant}; - - /// Return the IANA identifier of the currently configured timezone. This - /// should be an identifier from the IANA Time Zone Database. - /// - /// For displaying to a user, the identifier should be converted into a - /// localized name by means of an internationalization API. - /// - /// If the implementation does not expose an actual timezone, or is unable - /// to provide mappings from times to deltas between the configured timezone - /// and UTC, or determining the current timezone fails, or the timezone does - /// not have an IANA identifier, this returns nothing. - @unstable(feature = clocks-timezone) - iana-id: func() -> option; - - /// The number of nanoseconds difference between UTC time and the local - /// time of the currently configured timezone, at the exact time of - /// `instant`. - /// - /// The magnitude of the returned value will always be less than - /// 86,400,000,000,000 which is the number of nanoseconds in a day - /// (24*60*60*1e9). - /// - /// If the implementation does not expose an actual timezone, or is unable - /// to provide mappings from times to deltas between the configured timezone - /// and UTC, or determining the current timezone fails, this returns - /// nothing. - @unstable(feature = clocks-timezone) - utc-offset: func(when: instant) -> option; - - /// Returns a string that is suitable to assist humans in debugging whether - /// any timezone is available, and if so, which. This may be the same string - /// as `iana-id`, or a formatted representation of the UTC offset such as - /// `-04:00`, or something else. - /// - /// WARNING: The returned string should not be consumed mechanically! It may - /// change across platforms, hosts, or other implementation details. Parsing - /// this string is a major platform-compatibility hazard. - @unstable(feature = clocks-timezone) - to-debug-string: func() -> string; -} diff --git a/proposals/clocks/wit-0.3.0-draft/world.wit b/proposals/clocks/wit-0.3.0-draft/world.wit deleted file mode 100644 index ac51f7fc9..000000000 --- a/proposals/clocks/wit-0.3.0-draft/world.wit +++ /dev/null @@ -1,11 +0,0 @@ -package wasi:clocks@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world imports { - @since(version = 0.3.0-rc-2026-03-15) - import monotonic-clock; - @since(version = 0.3.0-rc-2026-03-15) - import system-clock; - @unstable(feature = clocks-timezone) - import timezone; -} diff --git a/proposals/clocks/wit/deps.lock b/proposals/clocks/wit/deps.lock deleted file mode 100644 index 1c5934b5e..000000000 --- a/proposals/clocks/wit/deps.lock +++ /dev/null @@ -1,4 +0,0 @@ -[io] -path = "../../io/wit" -sha256 = "b45dcb3986b694bd2de3b4c092ee3cc3b0e7c654a93e5dee0c5b32e349d1b0d8" -sha512 = "08ab049d3887d12bd5ae650703b325fd5d26a340e7e6f53c77c5ecfefa79d3b9c61801b6eb00872ecd91f74572ef5684b0850721c715b4062158e00fae6c1dc2" diff --git a/proposals/clocks/wit/deps.toml b/proposals/clocks/wit/deps.toml deleted file mode 100644 index 1d001d91e..000000000 --- a/proposals/clocks/wit/deps.toml +++ /dev/null @@ -1 +0,0 @@ -io = "../../io/wit" diff --git a/proposals/clocks/wit/monotonic-clock.wit b/proposals/clocks/wit/monotonic-clock.wit index 5c299ced2..a750a5cd8 100644 --- a/proposals/clocks/wit/monotonic-clock.wit +++ b/proposals/clocks/wit/monotonic-clock.wit @@ -1,4 +1,4 @@ -package wasi:clocks@0.2.12; +package wasi:clocks@0.3.0; /// WASI Monotonic Clock is a clock API intended to let users measure elapsed /// time. /// @@ -7,20 +7,15 @@ package wasi:clocks@0.2.12; /// /// A monotonic clock is a clock which has an unspecified initial value, and /// successive reads of the clock will produce non-decreasing values. -@since(version = 0.2.0) +@since(version = 0.3.0) interface monotonic-clock { - @since(version = 0.2.0) - use wasi:io/poll@0.2.12.{pollable}; + use types.{duration}; - /// An instant in time, in nanoseconds. An instant is relative to an + /// A mark on a monotonic clock is a number of nanoseconds since an /// unspecified initial value, and can only be compared to instances from /// the same monotonic-clock. - @since(version = 0.2.0) - type instant = u64; - - /// A duration of time, in nanoseconds. - @since(version = 0.2.0) - type duration = u64; + @since(version = 0.3.0) + type mark = u64; /// Read the current value of the clock. /// @@ -28,28 +23,26 @@ interface monotonic-clock { /// produce a sequence of non-decreasing values. /// /// For completeness, this function traps if it's not possible to represent - /// the value of the clock in an `instant`. Consequently, implementations + /// the value of the clock in a `mark`. Consequently, implementations /// should ensure that the starting time is low enough to avoid the /// possibility of overflow in practice. - @since(version = 0.2.0) - now: func() -> instant; + @since(version = 0.3.0) + now: func() -> mark; /// Query the resolution of the clock. Returns the duration of time /// corresponding to a clock tick. - @since(version = 0.2.0) - resolution: func() -> duration; + @since(version = 0.3.0) + get-resolution: func() -> duration; - /// Create a `pollable` which will resolve once the specified instant - /// has occurred. - @since(version = 0.2.0) - subscribe-instant: func( - when: instant, - ) -> pollable; + /// Wait until the specified mark has occurred. + @since(version = 0.3.0) + wait-until: async func( + when: mark, + ); - /// Create a `pollable` that will resolve after the specified duration has - /// elapsed from the time this function is invoked. - @since(version = 0.2.0) - subscribe-duration: func( - when: duration, - ) -> pollable; + /// Wait for the specified duration to elapse. + @since(version = 0.3.0) + wait-for: async func( + how-long: duration, + ); } diff --git a/proposals/clocks/wit-0.3.0-draft/system-clock.wit b/proposals/clocks/wit/system-clock.wit similarity index 90% rename from proposals/clocks/wit-0.3.0-draft/system-clock.wit rename to proposals/clocks/wit/system-clock.wit index f8c16611d..92dfc051e 100644 --- a/proposals/clocks/wit-0.3.0-draft/system-clock.wit +++ b/proposals/clocks/wit/system-clock.wit @@ -1,4 +1,4 @@ -package wasi:clocks@0.3.0-rc-2026-03-15; +package wasi:clocks@0.3.0; /// WASI System Clock is a clock API intended to let users query the current /// time. The clock is not necessarily monotonic as it may be reset. /// @@ -9,7 +9,7 @@ package wasi:clocks@0.3.0-rc-2026-03-15; /// monotonic, making it unsuitable for measuring elapsed time. /// /// It is intended for reporting the current date and time for humans. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) interface system-clock { use types.{duration}; @@ -29,7 +29,7 @@ interface system-clock { /// /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) record instant { seconds: s64, nanoseconds: u32, @@ -41,11 +41,11 @@ interface system-clock { /// will not necessarily produce a sequence of non-decreasing values. /// /// The nanoseconds field of the output is always less than 1000000000. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) now: func() -> instant; /// Query the resolution of the clock. Returns the smallest duration of time /// that the implementation permits distinguishing. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-resolution: func() -> duration; } diff --git a/proposals/clocks/wit/timezone.wit b/proposals/clocks/wit/timezone.wit index 22f3f6698..e0b84ec54 100644 --- a/proposals/clocks/wit/timezone.wit +++ b/proposals/clocks/wit/timezone.wit @@ -1,55 +1,46 @@ -package wasi:clocks@0.2.12; +package wasi:clocks@0.3.0; @unstable(feature = clocks-timezone) interface timezone { @unstable(feature = clocks-timezone) - use wall-clock.{datetime}; + use system-clock.{instant}; - /// Return information needed to display the given `datetime`. This includes - /// the UTC offset, the time zone name, and a flag indicating whether - /// daylight saving time is active. + /// Return the IANA identifier of the currently configured timezone. This + /// should be an identifier from the IANA Time Zone Database. /// - /// If the timezone cannot be determined for the given `datetime`, return a - /// `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight - /// saving time. + /// For displaying to a user, the identifier should be converted into a + /// localized name by means of an internationalization API. + /// + /// If the implementation does not expose an actual timezone, or is unable + /// to provide mappings from times to deltas between the configured timezone + /// and UTC, or determining the current timezone fails, or the timezone does + /// not have an IANA identifier, this returns nothing. @unstable(feature = clocks-timezone) - display: func(when: datetime) -> timezone-display; + iana-id: func() -> option; - /// The same as `display`, but only return the UTC offset. + /// The number of nanoseconds difference between UTC time and the local + /// time of the currently configured timezone, at the exact time of + /// `instant`. + /// + /// The magnitude of the returned value will always be less than + /// 86,400,000,000,000 which is the number of nanoseconds in a day + /// (24*60*60*1e9). + /// + /// If the implementation does not expose an actual timezone, or is unable + /// to provide mappings from times to deltas between the configured timezone + /// and UTC, or determining the current timezone fails, this returns + /// nothing. @unstable(feature = clocks-timezone) - utc-offset: func(when: datetime) -> s32; + utc-offset: func(when: instant) -> option; - /// Information useful for displaying the timezone of a specific `datetime`. + /// Returns a string that is suitable to assist humans in debugging whether + /// any timezone is available, and if so, which. This may be the same string + /// as `iana-id`, or a formatted representation of the UTC offset such as + /// `-04:00`, or something else. /// - /// This information may vary within a single `timezone` to reflect daylight - /// saving time adjustments. + /// WARNING: The returned string should not be consumed mechanically! It may + /// change across platforms, hosts, or other implementation details. Parsing + /// this string is a major platform-compatibility hazard. @unstable(feature = clocks-timezone) - record timezone-display { - /// The number of seconds difference between UTC time and the local - /// time of the timezone. - /// - /// The returned value will always be less than 86400 which is the - /// number of seconds in a day (24*60*60). - /// - /// In implementations that do not expose an actual time zone, this - /// should return 0. - utc-offset: s32, - - /// The abbreviated name of the timezone to display to a user. The name - /// `UTC` indicates Coordinated Universal Time. Otherwise, this should - /// reference local standards for the name of the time zone. - /// - /// In implementations that do not expose an actual time zone, this - /// should be the string `UTC`. - /// - /// In time zones that do not have an applicable name, a formatted - /// representation of the UTC offset may be returned, such as `-04:00`. - name: string, - - /// Whether daylight saving time is active. - /// - /// In implementations that do not expose an actual time zone, this - /// should return false. - in-daylight-saving-time: bool, - } + to-debug-string: func() -> string; } diff --git a/proposals/clocks/wit-0.3.0-draft/types.wit b/proposals/clocks/wit/types.wit similarity index 55% rename from proposals/clocks/wit-0.3.0-draft/types.wit rename to proposals/clocks/wit/types.wit index 0da1a6cb9..e82be54dc 100644 --- a/proposals/clocks/wit-0.3.0-draft/types.wit +++ b/proposals/clocks/wit/types.wit @@ -1,8 +1,8 @@ -package wasi:clocks@0.3.0-rc-2026-03-15; +package wasi:clocks@0.3.0; /// This interface common types used throughout wasi:clocks. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) interface types { /// A duration of time, in nanoseconds. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) type duration = u64; } diff --git a/proposals/clocks/wit/wall-clock.wit b/proposals/clocks/wit/wall-clock.wit deleted file mode 100644 index a11bc9a93..000000000 --- a/proposals/clocks/wit/wall-clock.wit +++ /dev/null @@ -1,46 +0,0 @@ -package wasi:clocks@0.2.12; -/// WASI Wall Clock is a clock API intended to let users query the current -/// time. The name "wall" makes an analogy to a "clock on the wall", which -/// is not necessarily monotonic as it may be reset. -/// -/// It is intended to be portable at least between Unix-family platforms and -/// Windows. -/// -/// A wall clock is a clock which measures the date and time according to -/// some external reference. -/// -/// External references may be reset, so this clock is not necessarily -/// monotonic, making it unsuitable for measuring elapsed time. -/// -/// It is intended for reporting the current date and time for humans. -@since(version = 0.2.0) -interface wall-clock { - /// A time and date in seconds plus nanoseconds. - @since(version = 0.2.0) - record datetime { - seconds: u64, - nanoseconds: u32, - } - - /// Read the current value of the clock. - /// - /// This clock is not monotonic, therefore calling this function repeatedly - /// will not necessarily produce a sequence of non-decreasing values. - /// - /// The returned timestamps represent the number of seconds since - /// 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch], - /// also known as [Unix Time]. - /// - /// The nanoseconds field of the output is always less than 1000000000. - /// - /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 - /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time - @since(version = 0.2.0) - now: func() -> datetime; - - /// Query the resolution of the clock. - /// - /// The nanoseconds field of the output is always less than 1000000000. - @since(version = 0.2.0) - resolution: func() -> datetime; -} diff --git a/proposals/clocks/wit/world.wit b/proposals/clocks/wit/world.wit index 19feacabf..c68c4ae37 100644 --- a/proposals/clocks/wit/world.wit +++ b/proposals/clocks/wit/world.wit @@ -1,11 +1,11 @@ -package wasi:clocks@0.2.12; +package wasi:clocks@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world imports { - @since(version = 0.2.0) + @since(version = 0.3.0) import monotonic-clock; - @since(version = 0.2.0) - import wall-clock; + @since(version = 0.3.0) + import system-clock; @unstable(feature = clocks-timezone) import timezone; } diff --git a/proposals/filesystem/imports.md b/proposals/filesystem/imports.md deleted file mode 100644 index 5d87e09b0..000000000 --- a/proposals/filesystem/imports.md +++ /dev/null @@ -1,1334 +0,0 @@ -

World imports

- -

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:filesystem/types@0.2.12

-

WASI filesystem is a filesystem API primarily intended to let users run WASI -programs that access their files on their existing filesystems, without -significant overhead.

-

It is intended to be roughly portable between Unix-family platforms and -Windows, though it does not hide many of the major differences.

-

Paths are passed as interface-type strings, meaning they must consist of -a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -paths which are not accessible by this API.

-

The directory separator in WASI is always the forward-slash (/).

-

All paths in WASI are relative paths, and are interpreted relative to a -descriptor referring to a base directory. If a path argument to any WASI -function starts with /, or if any step of resolving a path, including -.. and symbolic link steps, reaches a directory outside of the base -directory, or reaches a symlink to an absolute or rooted path in the -underlying filesystem, the function fails with error-code::not-permitted.

-

For more information about WASI path resolution and sandboxing, see -WASI filesystem path resolution.

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type error

-

error

-

-

type datetime

-

datetime

-

-

type filesize

-

u64

-

File size or length of a region within a file. -

enum descriptor-type

-

The type of a filesystem object referenced by a descriptor.

-

Note: This was called filetype in earlier versions of WASI.

-
Enum Cases
-
    -
  • -

    unknown

    -

    The type of the descriptor or file is unknown or is different from -any of the other types specified. -

    • -
  • -

    block-device

    -

    The descriptor refers to a block device inode. -

    • -
  • -

    character-device

    -

    The descriptor refers to a character device inode. -

    • -
  • -

    directory

    -

    The descriptor refers to a directory inode. -

    • -
  • -

    fifo

    -

    The descriptor refers to a named pipe. -

    • -
  • -

    symbolic-link

    -

    The file refers to a symbolic link inode. -

    • -
  • -

    regular-file

    -

    The descriptor refers to a regular file inode. -

    • -
  • -

    socket

    -

    The descriptor refers to a socket. -

    • -
-

flags descriptor-flags

-

Descriptor flags.

-

Note: This was called fdflags in earlier versions of WASI.

-
Flags members
-
    -
  • -

    read:

    -

    Read mode: Data can be read. -

    • -
  • -

    write:

    -

    Write mode: Data can be written to. -

    • -
  • -

    file-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O file -integrity completion. The data stored in the file and the file's -metadata are synchronized. This is similar to `O_SYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    data-integrity-sync:

    -

    Request that writes be performed according to synchronized I/O data -integrity completion. Only the data stored in the file is -synchronized. This is similar to `O_DSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    requested-write-sync:

    -

    Requests that reads be performed at the same level of integrity -requested for writes. This is similar to `O_RSYNC` in POSIX. -

    The precise semantics of this operation have not yet been defined for -WASI. At this time, it should be interpreted as a request, and not a -requirement.

    -
    • -
  • -

    mutate-directory:

    -

    Mutating directories mode: Directory contents may be mutated. -

    When this flag is unset on a descriptor, operations using the -descriptor which would create, rename, delete, modify the data or -metadata of filesystem objects, or obtain another handle which -would permit any of those, shall fail with error-code::read-only if -they would otherwise succeed.

    -

    This may only be set on directories.

    -
    • -
-

flags path-flags

-

Flags determining the method of how paths are resolved.

-
Flags members
-
    -
  • symlink-follow:

    As long as the resolved path corresponds to a symbolic link, it is -expanded. -

    • -
-

flags open-flags

-

Open flags used by open-at.

-
Flags members
-
    -
  • -

    create:

    -

    Create file if it does not exist, similar to `O_CREAT` in POSIX. -

    • -
  • -

    directory:

    -

    Fail if not a directory, similar to `O_DIRECTORY` in POSIX. -

    • -
  • -

    exclusive:

    -

    Fail if file already exists, similar to `O_EXCL` in POSIX. -

    • -
  • -

    truncate:

    -

    Truncate file to size 0, similar to `O_TRUNC` in POSIX. -

    • -
-

type link-count

-

u64

-

Number of hard links to an inode. -

record descriptor-stat

-

File attributes.

-

Note: This was called filestat in earlier versions of WASI.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    File type. -

    • -
  • -

    link-count: link-count

    -

    Number of hard links to the file. -

    • -
  • -

    size: filesize

    -

    For regular files, the file size in bytes. For symbolic links, the -length in bytes of the pathname contained in the symbolic link. -

    • -
  • -

    data-access-timestamp: option<datetime>

    -

    Last data access timestamp. -

    If the option is none, the platform doesn't maintain an access -timestamp for this file.

    -
    • -
  • -

    data-modification-timestamp: option<datetime>

    -

    Last data modification timestamp. -

    If the option is none, the platform doesn't maintain a -modification timestamp for this file.

    -
    • -
  • -

    status-change-timestamp: option<datetime>

    -

    Last file status-change timestamp. -

    If the option is none, the platform doesn't maintain a -status-change timestamp for this file.

    -
    • -
-

variant new-timestamp

-

When setting a timestamp, this gives the value to set it to.

-
Variant Cases
-
    -
  • -

    no-change

    -

    Leave the timestamp set to its previous value. -

    • -
  • -

    now

    -

    Set the timestamp to the current time of the system clock associated -with the filesystem. -

    • -
  • -

    timestamp: datetime

    -

    Set the timestamp to the given value. -

    • -
-

record directory-entry

-

A directory entry.

-
Record Fields
-
    -
  • -

    type: descriptor-type

    -

    The type of the file referred to by this directory entry. -

    • -
  • -

    name: string

    -

    The name of the object. -

    • -
-

enum error-code

-

Error codes returned by functions, similar to errno in POSIX. -Not all of these error codes are returned by the functions provided by this -API; some are used in higher-level library layers, and others are provided -merely for alignment with POSIX.

-
Enum Cases
-
    -
  • -

    access

    -

    Permission denied, similar to `EACCES` in POSIX. -

    • -
  • -

    would-block

    -

    Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX. -

    • -
  • -

    already

    -

    Connection already in progress, similar to `EALREADY` in POSIX. -

    • -
  • -

    bad-descriptor

    -

    Bad descriptor, similar to `EBADF` in POSIX. -

    • -
  • -

    busy

    -

    Device or resource busy, similar to `EBUSY` in POSIX. -

    • -
  • -

    deadlock

    -

    Resource deadlock would occur, similar to `EDEADLK` in POSIX. -

    • -
  • -

    quota

    -

    Storage quota exceeded, similar to `EDQUOT` in POSIX. -

    • -
  • -

    exist

    -

    File exists, similar to `EEXIST` in POSIX. -

    • -
  • -

    file-too-large

    -

    File too large, similar to `EFBIG` in POSIX. -

    • -
  • -

    illegal-byte-sequence

    -

    Illegal byte sequence, similar to `EILSEQ` in POSIX. -

    • -
  • -

    in-progress

    -

    Operation in progress, similar to `EINPROGRESS` in POSIX. -

    • -
  • -

    interrupted

    -

    Interrupted function, similar to `EINTR` in POSIX. -

    • -
  • -

    invalid

    -

    Invalid argument, similar to `EINVAL` in POSIX. -

    • -
  • -

    io

    -

    I/O error, similar to `EIO` in POSIX. -

    • -
  • -

    is-directory

    -

    Is a directory, similar to `EISDIR` in POSIX. -

    • -
  • -

    loop

    -

    Too many levels of symbolic links, similar to `ELOOP` in POSIX. -

    • -
  • -

    too-many-links

    -

    Too many links, similar to `EMLINK` in POSIX. -

    • -
  • -

    message-size

    -

    Message too large, similar to `EMSGSIZE` in POSIX. -

    • -
  • -

    name-too-long

    -

    Filename too long, similar to `ENAMETOOLONG` in POSIX. -

    • -
  • -

    no-device

    -

    No such device, similar to `ENODEV` in POSIX. -

    • -
  • -

    no-entry

    -

    No such file or directory, similar to `ENOENT` in POSIX. -

    • -
  • -

    no-lock

    -

    No locks available, similar to `ENOLCK` in POSIX. -

    • -
  • -

    insufficient-memory

    -

    Not enough space, similar to `ENOMEM` in POSIX. -

    • -
  • -

    insufficient-space

    -

    No space left on device, similar to `ENOSPC` in POSIX. -

    • -
  • -

    not-directory

    -

    Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. -

    • -
  • -

    not-empty

    -

    Directory not empty, similar to `ENOTEMPTY` in POSIX. -

    • -
  • -

    not-recoverable

    -

    State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. -

    • -
  • -

    unsupported

    -

    Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. -

    • -
  • -

    no-tty

    -

    Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. -

    • -
  • -

    no-such-device

    -

    No such device or address, similar to `ENXIO` in POSIX. -

    • -
  • -

    overflow

    -

    Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. -

    • -
  • -

    not-permitted

    -

    Operation not permitted, similar to `EPERM` in POSIX. -

    • -
  • -

    pipe

    -

    Broken pipe, similar to `EPIPE` in POSIX. -

    • -
  • -

    read-only

    -

    Read-only file system, similar to `EROFS` in POSIX. -

    • -
  • -

    invalid-seek

    -

    Invalid seek, similar to `ESPIPE` in POSIX. -

    • -
  • -

    text-file-busy

    -

    Text file busy, similar to `ETXTBSY` in POSIX. -

    • -
  • -

    cross-device

    -

    Cross-device link, similar to `EXDEV` in POSIX. -

    • -
-

enum advice

-

File or memory access pattern advisory information.

-
Enum Cases
-
    -
  • -

    normal

    -

    The application has no advice to give on its behavior with respect -to the specified data. -

    • -
  • -

    sequential

    -

    The application expects to access the specified data sequentially -from lower offsets to higher offsets. -

    • -
  • -

    random

    -

    The application expects to access the specified data in a random -order. -

    • -
  • -

    will-need

    -

    The application expects to access the specified data in the near -future. -

    • -
  • -

    dont-need

    -

    The application expects that it will not access the specified data -in the near future. -

    • -
  • -

    no-reuse

    -

    The application expects to access the specified data once and then -not reuse it thereafter. -

    • -
-

record metadata-hash-value

-

A 128-bit hash value, split into parts because wasm doesn't have a -128-bit integer type.

-
Record Fields
-
    -
  • -

    lower: u64

    -

    64 bits of a 128-bit hash value. -

    • -
  • -

    upper: u64

    -

    Another 64 bits of a 128-bit hash value. -

    • -
-

resource descriptor

-

A descriptor is a reference to a filesystem object, which may be a file, -directory, named pipe, special file, or other object on which filesystem -calls may be made.

-

resource directory-entry-stream

-

A stream of directory entries.

-

Functions

-

[method]descriptor.read-via-stream: func

-

Return a stream for reading from a file, if available.

-

May fail with an error-code describing why the file cannot be read.

-

Multiple read, write, and append streams may be active on the same open -file and they do not interfere with each other.

-

Note: This allows using read-stream, which is similar to read in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write-via-stream: func

-

Return a stream for writing to a file, if available.

-

May fail with an error-code describing why the file cannot be written.

-

Note: This allows using write-stream, which is similar to write in -POSIX.

-
Params
- -
Return values
- -

[method]descriptor.append-via-stream: func

-

Return a stream for appending to a file, if available.

-

May fail with an error-code describing why the file cannot be appended.

-

Note: This allows using write-stream, which is similar to write with -O_APPEND in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.advise: func

-

Provide file advisory information on a descriptor.

-

This is similar to posix_fadvise in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.sync-data: func

-

Synchronize the data of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fdatasync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.get-flags: func

-

Get flags associated with a descriptor.

-

Note: This returns similar flags to fcntl(fd, F_GETFL) in POSIX.

-

Note: This returns the value that was the fs_flags value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.get-type: func

-

Get the dynamic type of a descriptor.

-

Note: This returns the same value as the type field of the fd-stat -returned by stat, stat-at and similar.

-

Note: This returns similar flags to the st_mode & S_IFMT value provided -by fstat in POSIX.

-

Note: This returns the value that was the fs_filetype value returned -from fdstat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-size: func

-

Adjust the size of an open file. If this increases the file's size, the -extra bytes are filled with zeros.

-

Note: This was called fd_filestat_set_size in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times: func

-

Adjust the timestamps of an open file or directory.

-

Note: This is similar to futimens in POSIX.

-

Note: This was called fd_filestat_set_times in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.read: func

-

Read from a descriptor, without using and updating the descriptor's offset.

-

This function returns a list of bytes containing the data that was -read, along with a bool which, when true, indicates that the end of the -file was reached. The returned list will contain up to length bytes; it -may return fewer than requested, if the end of the file is reached or -if the I/O operation is interrupted.

-

In the future, this may change to return a stream<u8, error-code>.

-

Note: This is similar to pread in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.write: func

-

Write to a descriptor, without using and updating the descriptor's offset.

-

It is valid to write past the end of a file; the file is extended to the -extent of the write, with bytes between the previous end and the start of -the write set to zero.

-

In the future, this may change to take a stream<u8, error-code>.

-

Note: This is similar to pwrite in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.read-directory: func

-

Read directory entries from a directory.

-

On filesystems where directories contain entries referring to themselves -and their parents, often named . and .. respectively, these entries -are omitted.

-

This always returns a new stream which starts at the beginning of the -directory. Multiple streams may be active on the same directory, and they -do not interfere with each other.

-
Params
- -
Return values
- -

[method]descriptor.sync: func

-

Synchronize the data and metadata of a file to disk.

-

This function succeeds with no effect if the file descriptor is not -opened for writing.

-

Note: This is similar to fsync in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.create-directory-at: func

-

Create a directory.

-

Note: This is similar to mkdirat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.stat: func

-

Return the attributes of an open file or directory.

-

Note: This is similar to fstat in POSIX, except that it does not return -device and inode information. For testing whether two descriptors refer to -the same underlying filesystem object, use is-same-object. To obtain -additional data that can be used do determine whether a file has been -modified, use metadata-hash.

-

Note: This was called fd_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.stat-at: func

-

Return the attributes of a file or directory.

-

Note: This is similar to fstatat in POSIX, except that it does not -return device and inode information. See the stat description for a -discussion of alternatives.

-

Note: This was called path_filestat_get in earlier versions of WASI.

-
Params
- -
Return values
- -

[method]descriptor.set-times-at: func

-

Adjust the timestamps of a file or directory.

-

Note: This is similar to utimensat in POSIX.

-

Note: This was called path_filestat_set_times in earlier versions of -WASI.

-
Params
- -
Return values
- -

[method]descriptor.link-at: func

-

Create a hard link.

-

Fails with error-code::no-entry if the old path does not exist, -with error-code::exist if the new path already exists, and -error-code::not-permitted if the old path is not a file.

-

Note: This is similar to linkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.open-at: func

-

Open a file or directory.

-

If flags contains descriptor-flags::mutate-directory, and the base -descriptor doesn't have descriptor-flags::mutate-directory set, -open-at fails with error-code::read-only.

-

If flags contains write or mutate-directory, or open-flags -contains truncate or create, and the base descriptor doesn't have -descriptor-flags::mutate-directory set, open-at fails with -error-code::read-only.

-

Note: This is similar to openat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.readlink-at: func

-

Read the contents of a symbolic link.

-

If the contents contain an absolute or rooted path in the underlying -filesystem, this function fails with error-code::not-permitted.

-

Note: This is similar to readlinkat in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.remove-directory-at: func

-

Remove a directory.

-

Return error-code::not-empty if the directory is not empty.

-

Note: This is similar to unlinkat(fd, path, AT_REMOVEDIR) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.rename-at: func

-

Rename a filesystem object.

-

Note: This is similar to renameat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-descriptor: borrow<descriptor>
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.symlink-at: func

-

Create a symbolic link (also known as a "symlink").

-

If old-path starts with /, the function fails with -error-code::not-permitted.

-

Note: This is similar to symlinkat in POSIX.

-
Params
-
    -
  • self: borrow<descriptor>
    • -
  • old-path: string
    • -
  • new-path: string
    • -
-
Return values
- -

[method]descriptor.unlink-file-at: func

-

Unlink a filesystem object that is not a directory.

-

Return error-code::is-directory if the path refers to a directory. -Note: This is similar to unlinkat(fd, path, 0) in POSIX.

-
Params
- -
Return values
- -

[method]descriptor.is-same-object: func

-

Test whether two descriptors refer to the same filesystem object.

-

In POSIX, this corresponds to testing whether the two descriptors have the -same device (st_dev) and inode (st_ino or d_ino) numbers. -wasi-filesystem does not expose device and inode numbers, so this function -may be used instead.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]descriptor.metadata-hash: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a descriptor.

-

This returns a hash of the last-modification timestamp and file size, and -may also include the inode number, device number, birth timestamp, and -other metadata fields that may change when the file is modified or -replaced. It may also include a secret value chosen by the -implementation and not otherwise exposed.

-

Implementations are encouraged to provide the following properties:

-
    -
  • If the file is not modified or replaced, the computed hash value should -usually not change.
    • -
  • If the object is modified or replaced, the computed hash value should -usually change.
    • -
  • The inputs to the hash should not be easily computable from the -computed hash.
    • -
-

However, none of these is required.

-
Params
- -
Return values
- -

[method]descriptor.metadata-hash-at: func

-

Return a hash of the metadata associated with a filesystem object referred -to by a directory descriptor and a relative path.

-

This performs the same hash computation as metadata-hash.

-
Params
- -
Return values
- -

[method]directory-entry-stream.read-directory-entry: func

-

Read a single directory entry from a directory-entry-stream.

-
Params
- -
Return values
- -

filesystem-error-code: func

-

Attempts to extract a filesystem-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -filesystem-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are filesystem-related errors.

-
Params
- -
Return values
- -

Import interface wasi:filesystem/preopens@0.2.12

-
-

Types

-

type descriptor

-

descriptor

-

-

-

Functions

-

get-directories: func

-

Return the set of preopened directories, and their paths.

-
Return values
- diff --git a/proposals/filesystem/wit-0.3.0-draft/deps.lock b/proposals/filesystem/wit-0.3.0-draft/deps.lock deleted file mode 100644 index a780d3df7..000000000 --- a/proposals/filesystem/wit-0.3.0-draft/deps.lock +++ /dev/null @@ -1,4 +0,0 @@ -[clocks] -path = "../../clocks/wit-0.3.0-draft" -sha256 = "a8702c42e23c22a458207d0efa38cc1b64c8c6299b0e3152aa84327a7c1c952b" -sha512 = "da69a5d498b6afe0facf77ec3d21f6e8a2a4d4661ebfec310a2ce6f943cb01f92131a746765648febf96563ddac788e9f218941d3db2b905f3746dc8e05cf54d" diff --git a/proposals/filesystem/wit-0.3.0-draft/deps.toml b/proposals/filesystem/wit-0.3.0-draft/deps.toml deleted file mode 100644 index c54398c1a..000000000 --- a/proposals/filesystem/wit-0.3.0-draft/deps.toml +++ /dev/null @@ -1 +0,0 @@ -clocks = "../../clocks/wit-0.3.0-draft" diff --git a/proposals/filesystem/wit-0.3.0-draft/preopens.wit b/proposals/filesystem/wit-0.3.0-draft/preopens.wit deleted file mode 100644 index 2c4560af9..000000000 --- a/proposals/filesystem/wit-0.3.0-draft/preopens.wit +++ /dev/null @@ -1,11 +0,0 @@ -package wasi:filesystem@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -interface preopens { - @since(version = 0.3.0-rc-2026-03-15) - use types.{descriptor}; - - /// Return the set of preopened directories, and their paths. - @since(version = 0.3.0-rc-2026-03-15) - get-directories: func() -> list>; -} diff --git a/proposals/filesystem/wit-0.3.0-draft/types.wit b/proposals/filesystem/wit-0.3.0-draft/types.wit deleted file mode 100644 index d02ce7353..000000000 --- a/proposals/filesystem/wit-0.3.0-draft/types.wit +++ /dev/null @@ -1,658 +0,0 @@ -package wasi:filesystem@0.3.0-rc-2026-03-15; -/// WASI filesystem is a filesystem API primarily intended to let users run WASI -/// programs that access their files on their existing filesystems, without -/// significant overhead. -/// -/// Paths are passed as interface-type `string`s, meaning they must consist of -/// a sequence of Unicode Scalar Values (USVs). Some filesystems may contain -/// paths which are not accessible by this API. -/// -/// The directory separator in WASI is always the forward-slash (`/`). -/// -/// All paths in WASI are relative paths, and are interpreted relative to a -/// `descriptor` referring to a base directory. If a `path` argument to any WASI -/// function starts with `/`, or if any step of resolving a `path`, including -/// `..` and symbolic link steps, reaches a directory outside of the base -/// directory, or reaches a symlink to an absolute or rooted path in the -/// underlying filesystem, the function fails with `error-code::not-permitted`. -/// -/// For more information about WASI path resolution and sandboxing, see -/// [WASI filesystem path resolution]. -/// -/// Though this package presents a portable interface modelled on POSIX, it -/// prioritizes compatibility over portability: allowing users to access their -/// files on their machine is more important than exposing a single semantics -/// across all platforms. Notably, depending on the underlying operating system -/// and file system: -/// * Paths may be case-folded or not. -/// * Deleting (unlinking) a file may fail if there are other file descriptors -/// open. -/// * Durability and atomicity of changes to underlying files when there are -/// concurrent writers. -/// -/// Users that need well-defined, portable semantics should use a key-value -/// store or a database instead. -/// -/// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md -@since(version = 0.3.0-rc-2026-03-15) -interface types { - @since(version = 0.3.0-rc-2026-03-15) - use wasi:clocks/system-clock@0.3.0-rc-2026-03-15.{instant}; - - /// File size or length of a region within a file. - @since(version = 0.3.0-rc-2026-03-15) - type filesize = u64; - - /// The type of a filesystem object referenced by a descriptor. - /// - /// Note: This was called `filetype` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - variant descriptor-type { - /// The descriptor refers to a block device inode. - block-device, - /// The descriptor refers to a character device inode. - character-device, - /// The descriptor refers to a directory inode. - directory, - /// The descriptor refers to a named pipe. - fifo, - /// The file refers to a symbolic link inode. - symbolic-link, - /// The descriptor refers to a regular file inode. - regular-file, - /// The descriptor refers to a socket. - socket, - /// The type of the descriptor or file is different from any of the - /// other types specified. - other(option), - } - - /// Descriptor flags. - /// - /// Note: This was called `fdflags` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - flags descriptor-flags { - /// Read mode: Data can be read. - read, - /// Write mode: Data can be written to. - write, - /// Request that writes be performed according to synchronized I/O file - /// integrity completion. The data stored in the file and the file's - /// metadata are synchronized. This is similar to `O_SYNC` in POSIX. - /// - /// The precise semantics of this operation have not yet been defined for - /// WASI. At this time, it should be interpreted as a request, and not a - /// requirement. - file-integrity-sync, - /// Request that writes be performed according to synchronized I/O data - /// integrity completion. Only the data stored in the file is - /// synchronized. This is similar to `O_DSYNC` in POSIX. - /// - /// The precise semantics of this operation have not yet been defined for - /// WASI. At this time, it should be interpreted as a request, and not a - /// requirement. - data-integrity-sync, - /// Requests that reads be performed at the same level of integrity - /// requested for writes. This is similar to `O_RSYNC` in POSIX. - /// - /// The precise semantics of this operation have not yet been defined for - /// WASI. At this time, it should be interpreted as a request, and not a - /// requirement. - requested-write-sync, - /// Mutating directories mode: Directory contents may be mutated. - /// - /// When this flag is unset on a descriptor, operations using the - /// descriptor which would create, rename, delete, modify the data or - /// metadata of filesystem objects, or obtain another handle which - /// would permit any of those, shall fail with `error-code::read-only` if - /// they would otherwise succeed. - /// - /// This may only be set on directories. - mutate-directory, - } - - /// File attributes. - /// - /// Note: This was called `filestat` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - record descriptor-stat { - /// File type. - %type: descriptor-type, - /// Number of hard links to the file. - link-count: link-count, - /// For regular files, the file size in bytes. For symbolic links, the - /// length in bytes of the pathname contained in the symbolic link. - size: filesize, - /// Last data access timestamp. - /// - /// If the `option` is none, the platform doesn't maintain an access - /// timestamp for this file. - data-access-timestamp: option, - /// Last data modification timestamp. - /// - /// If the `option` is none, the platform doesn't maintain a - /// modification timestamp for this file. - data-modification-timestamp: option, - /// Last file status-change timestamp. - /// - /// If the `option` is none, the platform doesn't maintain a - /// status-change timestamp for this file. - status-change-timestamp: option, - } - - /// Flags determining the method of how paths are resolved. - @since(version = 0.3.0-rc-2026-03-15) - flags path-flags { - /// As long as the resolved path corresponds to a symbolic link, it is - /// expanded. - symlink-follow, - } - - /// Open flags used by `open-at`. - @since(version = 0.3.0-rc-2026-03-15) - flags open-flags { - /// Create file if it does not exist, similar to `O_CREAT` in POSIX. - create, - /// Fail if not a directory, similar to `O_DIRECTORY` in POSIX. - directory, - /// Fail if file already exists, similar to `O_EXCL` in POSIX. - exclusive, - /// Truncate file to size 0, similar to `O_TRUNC` in POSIX. - truncate, - } - - /// Number of hard links to an inode. - @since(version = 0.3.0-rc-2026-03-15) - type link-count = u64; - - /// When setting a timestamp, this gives the value to set it to. - @since(version = 0.3.0-rc-2026-03-15) - variant new-timestamp { - /// Leave the timestamp set to its previous value. - no-change, - /// Set the timestamp to the current time of the system clock associated - /// with the filesystem. - now, - /// Set the timestamp to the given value. - timestamp(instant), - } - - /// A directory entry. - @since(version = 0.3.0-rc-2026-03-15) - record directory-entry { - /// The type of the file referred to by this directory entry. - %type: descriptor-type, - - /// The name of the object. - name: string, - } - - /// Error codes returned by functions, similar to `errno` in POSIX. - /// Not all of these error codes are returned by the functions provided by this - /// API; some are used in higher-level library layers, and others are provided - /// merely for alignment with POSIX. - @since(version = 0.3.0-rc-2026-03-15) - variant error-code { - /// Permission denied, similar to `EACCES` in POSIX. - access, - /// Connection already in progress, similar to `EALREADY` in POSIX. - already, - /// Bad descriptor, similar to `EBADF` in POSIX. - bad-descriptor, - /// Device or resource busy, similar to `EBUSY` in POSIX. - busy, - /// Resource deadlock would occur, similar to `EDEADLK` in POSIX. - deadlock, - /// Storage quota exceeded, similar to `EDQUOT` in POSIX. - quota, - /// File exists, similar to `EEXIST` in POSIX. - exist, - /// File too large, similar to `EFBIG` in POSIX. - file-too-large, - /// Illegal byte sequence, similar to `EILSEQ` in POSIX. - illegal-byte-sequence, - /// Operation in progress, similar to `EINPROGRESS` in POSIX. - in-progress, - /// Interrupted function, similar to `EINTR` in POSIX. - interrupted, - /// Invalid argument, similar to `EINVAL` in POSIX. - invalid, - /// I/O error, similar to `EIO` in POSIX. - io, - /// Is a directory, similar to `EISDIR` in POSIX. - is-directory, - /// Too many levels of symbolic links, similar to `ELOOP` in POSIX. - loop, - /// Too many links, similar to `EMLINK` in POSIX. - too-many-links, - /// Message too large, similar to `EMSGSIZE` in POSIX. - message-size, - /// Filename too long, similar to `ENAMETOOLONG` in POSIX. - name-too-long, - /// No such device, similar to `ENODEV` in POSIX. - no-device, - /// No such file or directory, similar to `ENOENT` in POSIX. - no-entry, - /// No locks available, similar to `ENOLCK` in POSIX. - no-lock, - /// Not enough space, similar to `ENOMEM` in POSIX. - insufficient-memory, - /// No space left on device, similar to `ENOSPC` in POSIX. - insufficient-space, - /// Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. - not-directory, - /// Directory not empty, similar to `ENOTEMPTY` in POSIX. - not-empty, - /// State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. - not-recoverable, - /// Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. - unsupported, - /// Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. - no-tty, - /// No such device or address, similar to `ENXIO` in POSIX. - no-such-device, - /// Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. - overflow, - /// Operation not permitted, similar to `EPERM` in POSIX. - not-permitted, - /// Broken pipe, similar to `EPIPE` in POSIX. - pipe, - /// Read-only file system, similar to `EROFS` in POSIX. - read-only, - /// Invalid seek, similar to `ESPIPE` in POSIX. - invalid-seek, - /// Text file busy, similar to `ETXTBSY` in POSIX. - text-file-busy, - /// Cross-device link, similar to `EXDEV` in POSIX. - cross-device, - /// A catch-all for errors not captured by the existing variants. - /// Implementations can use this to extend the error type without - /// breaking existing code. - other(option), - } - - /// File or memory access pattern advisory information. - @since(version = 0.3.0-rc-2026-03-15) - enum advice { - /// The application has no advice to give on its behavior with respect - /// to the specified data. - normal, - /// The application expects to access the specified data sequentially - /// from lower offsets to higher offsets. - sequential, - /// The application expects to access the specified data in a random - /// order. - random, - /// The application expects to access the specified data in the near - /// future. - will-need, - /// The application expects that it will not access the specified data - /// in the near future. - dont-need, - /// The application expects to access the specified data once and then - /// not reuse it thereafter. - no-reuse, - } - - /// A 128-bit hash value, split into parts because wasm doesn't have a - /// 128-bit integer type. - @since(version = 0.3.0-rc-2026-03-15) - record metadata-hash-value { - /// 64 bits of a 128-bit hash value. - lower: u64, - /// Another 64 bits of a 128-bit hash value. - upper: u64, - } - - /// A descriptor is a reference to a filesystem object, which may be a file, - /// directory, named pipe, special file, or other object on which filesystem - /// calls may be made. - @since(version = 0.3.0-rc-2026-03-15) - resource descriptor { - /// Return a stream for reading from a file. - /// - /// Multiple read, write, and append streams may be active on the same open - /// file and they do not interfere with each other. - /// - /// This function returns a `stream` which provides the data received from the - /// file, and a `future` providing additional error information in case an - /// error is encountered. - /// - /// If no error is encountered, `stream.read` on the `stream` will return - /// `read-status::closed` with no `error-context` and the future resolves to - /// the value `ok`. If an error is encountered, `stream.read` on the - /// `stream` returns `read-status::closed` with an `error-context` and the future - /// resolves to `err` with an `error-code`. - /// - /// Note: This is similar to `pread` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - read-via-stream: func( - /// The offset within the file at which to start reading. - offset: filesize, - ) -> tuple, future>>; - - /// Return a stream for writing to a file, if available. - /// - /// May fail with an error-code describing why the file cannot be written. - /// - /// It is valid to write past the end of a file; the file is extended to the - /// extent of the write, with bytes between the previous end and the start of - /// the write set to zero. - /// - /// This function returns once either full contents of the stream are - /// written or an error is encountered. - /// - /// Note: This is similar to `pwrite` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - write-via-stream: func( - /// Data to write - data: stream, - /// The offset within the file at which to start writing. - offset: filesize, - ) -> future>; - - /// Return a stream for appending to a file, if available. - /// - /// May fail with an error-code describing why the file cannot be appended. - /// - /// This function returns once either full contents of the stream are - /// written or an error is encountered. - /// - /// Note: This is similar to `write` with `O_APPEND` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - append-via-stream: func(data: stream) -> future>; - - /// Provide file advisory information on a descriptor. - /// - /// This is similar to `posix_fadvise` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - advise: async func( - /// The offset within the file to which the advisory applies. - offset: filesize, - /// The length of the region to which the advisory applies. - length: filesize, - /// The advice. - advice: advice - ) -> result<_, error-code>; - - /// Synchronize the data of a file to disk. - /// - /// This function succeeds with no effect if the file descriptor is not - /// opened for writing. - /// - /// Note: This is similar to `fdatasync` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - sync-data: async func() -> result<_, error-code>; - - /// Get flags associated with a descriptor. - /// - /// Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX. - /// - /// Note: This returns the value that was the `fs_flags` value returned - /// from `fdstat_get` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - get-flags: async func() -> result; - - /// Get the dynamic type of a descriptor. - /// - /// Note: This returns the same value as the `type` field of the `fd-stat` - /// returned by `stat`, `stat-at` and similar. - /// - /// Note: This returns similar flags to the `st_mode & S_IFMT` value provided - /// by `fstat` in POSIX. - /// - /// Note: This returns the value that was the `fs_filetype` value returned - /// from `fdstat_get` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - get-type: async func() -> result; - - /// Adjust the size of an open file. If this increases the file's size, the - /// extra bytes are filled with zeros. - /// - /// Note: This was called `fd_filestat_set_size` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - set-size: async func(size: filesize) -> result<_, error-code>; - - /// Adjust the timestamps of an open file or directory. - /// - /// Note: This is similar to `futimens` in POSIX. - /// - /// Note: This was called `fd_filestat_set_times` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - set-times: async func( - /// The desired values of the data access timestamp. - data-access-timestamp: new-timestamp, - /// The desired values of the data modification timestamp. - data-modification-timestamp: new-timestamp, - ) -> result<_, error-code>; - - /// Read directory entries from a directory. - /// - /// On filesystems where directories contain entries referring to themselves - /// and their parents, often named `.` and `..` respectively, these entries - /// are omitted. - /// - /// This always returns a new stream which starts at the beginning of the - /// directory. Multiple streams may be active on the same directory, and they - /// do not interfere with each other. - /// - /// This function returns a future, which will resolve to an error code if - /// reading full contents of the directory fails. - @since(version = 0.3.0-rc-2026-03-15) - read-directory: func() -> tuple, future>>; - - /// Synchronize the data and metadata of a file to disk. - /// - /// This function succeeds with no effect if the file descriptor is not - /// opened for writing. - /// - /// Note: This is similar to `fsync` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - sync: async func() -> result<_, error-code>; - - /// Create a directory. - /// - /// Note: This is similar to `mkdirat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - create-directory-at: async func( - /// The relative path at which to create the directory. - path: string, - ) -> result<_, error-code>; - - /// Return the attributes of an open file or directory. - /// - /// Note: This is similar to `fstat` in POSIX, except that it does not return - /// device and inode information. For testing whether two descriptors refer to - /// the same underlying filesystem object, use `is-same-object`. To obtain - /// additional data that can be used do determine whether a file has been - /// modified, use `metadata-hash`. - /// - /// Note: This was called `fd_filestat_get` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - stat: async func() -> result; - - /// Return the attributes of a file or directory. - /// - /// Note: This is similar to `fstatat` in POSIX, except that it does not - /// return device and inode information. See the `stat` description for a - /// discussion of alternatives. - /// - /// Note: This was called `path_filestat_get` in earlier versions of WASI. - @since(version = 0.3.0-rc-2026-03-15) - stat-at: async func( - /// Flags determining the method of how the path is resolved. - path-flags: path-flags, - /// The relative path of the file or directory to inspect. - path: string, - ) -> result; - - /// Adjust the timestamps of a file or directory. - /// - /// Note: This is similar to `utimensat` in POSIX. - /// - /// Note: This was called `path_filestat_set_times` in earlier versions of - /// WASI. - @since(version = 0.3.0-rc-2026-03-15) - set-times-at: async func( - /// Flags determining the method of how the path is resolved. - path-flags: path-flags, - /// The relative path of the file or directory to operate on. - path: string, - /// The desired values of the data access timestamp. - data-access-timestamp: new-timestamp, - /// The desired values of the data modification timestamp. - data-modification-timestamp: new-timestamp, - ) -> result<_, error-code>; - - /// Create a hard link. - /// - /// Fails with `error-code::no-entry` if the old path does not exist, - /// with `error-code::exist` if the new path already exists, and - /// `error-code::not-permitted` if the old path is not a file. - /// - /// Note: This is similar to `linkat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - link-at: async func( - /// Flags determining the method of how the path is resolved. - old-path-flags: path-flags, - /// The relative source path from which to link. - old-path: string, - /// The base directory for `new-path`. - new-descriptor: borrow, - /// The relative destination path at which to create the hard link. - new-path: string, - ) -> result<_, error-code>; - - /// Open a file or directory. - /// - /// If `flags` contains `descriptor-flags::mutate-directory`, and the base - /// descriptor doesn't have `descriptor-flags::mutate-directory` set, - /// `open-at` fails with `error-code::read-only`. - /// - /// If `flags` contains `write` or `mutate-directory`, or `open-flags` - /// contains `truncate` or `create`, and the base descriptor doesn't have - /// `descriptor-flags::mutate-directory` set, `open-at` fails with - /// `error-code::read-only`. - /// - /// Note: This is similar to `openat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - open-at: async func( - /// Flags determining the method of how the path is resolved. - path-flags: path-flags, - /// The relative path of the object to open. - path: string, - /// The method by which to open the file. - open-flags: open-flags, - /// Flags to use for the resulting descriptor. - %flags: descriptor-flags, - ) -> result; - - /// Read the contents of a symbolic link. - /// - /// If the contents contain an absolute or rooted path in the underlying - /// filesystem, this function fails with `error-code::not-permitted`. - /// - /// Note: This is similar to `readlinkat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - readlink-at: async func( - /// The relative path of the symbolic link from which to read. - path: string, - ) -> result; - - /// Remove a directory. - /// - /// Return `error-code::not-empty` if the directory is not empty. - /// - /// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - remove-directory-at: async func( - /// The relative path to a directory to remove. - path: string, - ) -> result<_, error-code>; - - /// Rename a filesystem object. - /// - /// Note: This is similar to `renameat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - rename-at: async func( - /// The relative source path of the file or directory to rename. - old-path: string, - /// The base directory for `new-path`. - new-descriptor: borrow, - /// The relative destination path to which to rename the file or directory. - new-path: string, - ) -> result<_, error-code>; - - /// Create a symbolic link (also known as a "symlink"). - /// - /// If `old-path` starts with `/`, the function fails with - /// `error-code::not-permitted`. - /// - /// Note: This is similar to `symlinkat` in POSIX. - @since(version = 0.3.0-rc-2026-03-15) - symlink-at: async func( - /// The contents of the symbolic link. - old-path: string, - /// The relative destination path at which to create the symbolic link. - new-path: string, - ) -> result<_, error-code>; - - /// Unlink a filesystem object that is not a directory. - /// - /// This is similar to `unlinkat(fd, path, 0)` in POSIX. - /// - /// Error returns are as specified by POSIX. - /// - /// If the filesystem object is a directory, `error-code::access` or - /// `error-code::is-directory` may be returned instead of the - /// POSIX-specified `error-code::not-permitted`. - @since(version = 0.3.0-rc-2026-03-15) - unlink-file-at: async func( - /// The relative path to a file to unlink. - path: string, - ) -> result<_, error-code>; - - /// Test whether two descriptors refer to the same filesystem object. - /// - /// In POSIX, this corresponds to testing whether the two descriptors have the - /// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers. - /// wasi-filesystem does not expose device and inode numbers, so this function - /// may be used instead. - @since(version = 0.3.0-rc-2026-03-15) - is-same-object: async func(other: borrow) -> bool; - - /// Return a hash of the metadata associated with a filesystem object referred - /// to by a descriptor. - /// - /// This returns a hash of the last-modification timestamp and file size, and - /// may also include the inode number, device number, birth timestamp, and - /// other metadata fields that may change when the file is modified or - /// replaced. It may also include a secret value chosen by the - /// implementation and not otherwise exposed. - /// - /// Implementations are encouraged to provide the following properties: - /// - /// - If the file is not modified or replaced, the computed hash value should - /// usually not change. - /// - If the object is modified or replaced, the computed hash value should - /// usually change. - /// - The inputs to the hash should not be easily computable from the - /// computed hash. - /// - /// However, none of these is required. - @since(version = 0.3.0-rc-2026-03-15) - metadata-hash: async func() -> result; - - /// Return a hash of the metadata associated with a filesystem object referred - /// to by a directory descriptor and a relative path. - /// - /// This performs the same hash computation as `metadata-hash`. - @since(version = 0.3.0-rc-2026-03-15) - metadata-hash-at: async func( - /// Flags determining the method of how the path is resolved. - path-flags: path-flags, - /// The relative path of the file or directory to inspect. - path: string, - ) -> result; - } -} diff --git a/proposals/filesystem/wit-0.3.0-draft/world.wit b/proposals/filesystem/wit-0.3.0-draft/world.wit deleted file mode 100644 index b4fef32ce..000000000 --- a/proposals/filesystem/wit-0.3.0-draft/world.wit +++ /dev/null @@ -1,9 +0,0 @@ -package wasi:filesystem@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world imports { - @since(version = 0.3.0-rc-2026-03-15) - import types; - @since(version = 0.3.0-rc-2026-03-15) - import preopens; -} diff --git a/proposals/filesystem/wit/deps.lock b/proposals/filesystem/wit/deps.lock index a3b6ab01e..7e6404b9a 100644 --- a/proposals/filesystem/wit/deps.lock +++ b/proposals/filesystem/wit/deps.lock @@ -1,9 +1,4 @@ [clocks] path = "../../clocks/wit" -sha256 = "85b95504b5f627086433c75a634ef86cc5a346f000acd158b94cb01d508b1992" -sha512 = "b2ba12c17a022788a9ed0d1a11bd605c579ab9614edd6ba02ba6ae59e4265ed02dff718b374181be4fc7c60e0e44d0ef65ab9ddda559f2b75ccc5ca2bb6d7b9f" - -[io] -path = "../../io/wit" -sha256 = "b45dcb3986b694bd2de3b4c092ee3cc3b0e7c654a93e5dee0c5b32e349d1b0d8" -sha512 = "08ab049d3887d12bd5ae650703b325fd5d26a340e7e6f53c77c5ecfefa79d3b9c61801b6eb00872ecd91f74572ef5684b0850721c715b4062158e00fae6c1dc2" +sha256 = "2d288cb781c60ae462537b39e4699de38f88072b501fc7f97d3f20984d550bcf" +sha512 = "1563eeeacbfea89e44f668b8588ef95b31feac7d9ec3bb5dad932320478b1aff1448031f44afa15ed926981855ac5bd504126389ddb7802f79c63b81b3c5ede7" diff --git a/proposals/filesystem/wit/deps.toml b/proposals/filesystem/wit/deps.toml index ab3e8dd1f..942f72d1c 100644 --- a/proposals/filesystem/wit/deps.toml +++ b/proposals/filesystem/wit/deps.toml @@ -1,2 +1 @@ -io = "../../io/wit" clocks = "../../clocks/wit" diff --git a/proposals/filesystem/wit/preopens.wit b/proposals/filesystem/wit/preopens.wit index 20bd3f020..0b29aae33 100644 --- a/proposals/filesystem/wit/preopens.wit +++ b/proposals/filesystem/wit/preopens.wit @@ -1,11 +1,11 @@ -package wasi:filesystem@0.2.12; +package wasi:filesystem@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) interface preopens { - @since(version = 0.2.0) + @since(version = 0.3.0) use types.{descriptor}; /// Return the set of preopened directories, and their paths. - @since(version = 0.2.0) + @since(version = 0.3.0) get-directories: func() -> list>; } diff --git a/proposals/filesystem/wit/types.wit b/proposals/filesystem/wit/types.wit index 821070492..fede686b4 100644 --- a/proposals/filesystem/wit/types.wit +++ b/proposals/filesystem/wit/types.wit @@ -1,11 +1,8 @@ -package wasi:filesystem@0.2.12; +package wasi:filesystem@0.3.0; /// WASI filesystem is a filesystem API primarily intended to let users run WASI /// programs that access their files on their existing filesystems, without /// significant overhead. /// -/// It is intended to be roughly portable between Unix-family platforms and -/// Windows, though it does not hide many of the major differences. -/// /// Paths are passed as interface-type `string`s, meaning they must consist of /// a sequence of Unicode Scalar Values (USVs). Some filesystems may contain /// paths which are not accessible by this API. @@ -22,26 +19,35 @@ package wasi:filesystem@0.2.12; /// For more information about WASI path resolution and sandboxing, see /// [WASI filesystem path resolution]. /// +/// Though this package presents a portable interface modelled on POSIX, it +/// prioritizes compatibility over portability: allowing users to access their +/// files on their machine is more important than exposing a single semantics +/// across all platforms. Notably, depending on the underlying operating system +/// and file system: +/// * Paths may be case-folded or not. +/// * Deleting (unlinking) a file may fail if there are other file descriptors +/// open. +/// * Durability and atomicity of changes to underlying files when there are +/// concurrent writers. +/// +/// Users that need well-defined, portable semantics should use a key-value +/// store or a database instead. +/// /// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md -@since(version = 0.2.0) +@since(version = 0.3.0) interface types { - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{input-stream, output-stream, error}; - @since(version = 0.2.0) - use wasi:clocks/wall-clock@0.2.12.{datetime}; + @since(version = 0.3.0) + use wasi:clocks/system-clock@0.3.0.{instant}; /// File size or length of a region within a file. - @since(version = 0.2.0) + @since(version = 0.3.0) type filesize = u64; /// The type of a filesystem object referenced by a descriptor. /// /// Note: This was called `filetype` in earlier versions of WASI. - @since(version = 0.2.0) - enum descriptor-type { - /// The type of the descriptor or file is unknown or is different from - /// any of the other types specified. - unknown, + @since(version = 0.3.0) + variant descriptor-type { /// The descriptor refers to a block device inode. block-device, /// The descriptor refers to a character device inode. @@ -56,12 +62,15 @@ interface types { regular-file, /// The descriptor refers to a socket. socket, + /// The type of the descriptor or file is different from any of the + /// other types specified. + other(option), } /// Descriptor flags. /// /// Note: This was called `fdflags` in earlier versions of WASI. - @since(version = 0.2.0) + @since(version = 0.3.0) flags descriptor-flags { /// Read mode: Data can be read. read, @@ -105,7 +114,7 @@ interface types { /// File attributes. /// /// Note: This was called `filestat` in earlier versions of WASI. - @since(version = 0.2.0) + @since(version = 0.3.0) record descriptor-stat { /// File type. %type: descriptor-type, @@ -118,21 +127,21 @@ interface types { /// /// If the `option` is none, the platform doesn't maintain an access /// timestamp for this file. - data-access-timestamp: option, + data-access-timestamp: option, /// Last data modification timestamp. /// /// If the `option` is none, the platform doesn't maintain a /// modification timestamp for this file. - data-modification-timestamp: option, + data-modification-timestamp: option, /// Last file status-change timestamp. /// /// If the `option` is none, the platform doesn't maintain a /// status-change timestamp for this file. - status-change-timestamp: option, + status-change-timestamp: option, } /// Flags determining the method of how paths are resolved. - @since(version = 0.2.0) + @since(version = 0.3.0) flags path-flags { /// As long as the resolved path corresponds to a symbolic link, it is /// expanded. @@ -140,7 +149,7 @@ interface types { } /// Open flags used by `open-at`. - @since(version = 0.2.0) + @since(version = 0.3.0) flags open-flags { /// Create file if it does not exist, similar to `O_CREAT` in POSIX. create, @@ -153,11 +162,11 @@ interface types { } /// Number of hard links to an inode. - @since(version = 0.2.0) + @since(version = 0.3.0) type link-count = u64; /// When setting a timestamp, this gives the value to set it to. - @since(version = 0.2.0) + @since(version = 0.3.0) variant new-timestamp { /// Leave the timestamp set to its previous value. no-change, @@ -165,11 +174,11 @@ interface types { /// with the filesystem. now, /// Set the timestamp to the given value. - timestamp(datetime), + timestamp(instant), } /// A directory entry. - @since(version = 0.2.0) + @since(version = 0.3.0) record directory-entry { /// The type of the file referred to by this directory entry. %type: descriptor-type, @@ -182,12 +191,10 @@ interface types { /// Not all of these error codes are returned by the functions provided by this /// API; some are used in higher-level library layers, and others are provided /// merely for alignment with POSIX. - @since(version = 0.2.0) - enum error-code { + @since(version = 0.3.0) + variant error-code { /// Permission denied, similar to `EACCES` in POSIX. access, - /// Resource unavailable, or operation would block, similar to `EAGAIN` and `EWOULDBLOCK` in POSIX. - would-block, /// Connection already in progress, similar to `EALREADY` in POSIX. already, /// Bad descriptor, similar to `EBADF` in POSIX. @@ -258,10 +265,14 @@ interface types { text-file-busy, /// Cross-device link, similar to `EXDEV` in POSIX. cross-device, + /// A catch-all for errors not captured by the existing variants. + /// Implementations can use this to extend the error type without + /// breaking existing code. + other(option), } /// File or memory access pattern advisory information. - @since(version = 0.2.0) + @since(version = 0.3.0) enum advice { /// The application has no advice to give on its behavior with respect /// to the specified data. @@ -285,7 +296,7 @@ interface types { /// A 128-bit hash value, split into parts because wasm doesn't have a /// 128-bit integer type. - @since(version = 0.2.0) + @since(version = 0.3.0) record metadata-hash-value { /// 64 bits of a 128-bit hash value. lower: u64, @@ -296,48 +307,66 @@ interface types { /// A descriptor is a reference to a filesystem object, which may be a file, /// directory, named pipe, special file, or other object on which filesystem /// calls may be made. - @since(version = 0.2.0) + @since(version = 0.3.0) resource descriptor { - /// Return a stream for reading from a file, if available. - /// - /// May fail with an error-code describing why the file cannot be read. + /// Return a stream for reading from a file. /// /// Multiple read, write, and append streams may be active on the same open /// file and they do not interfere with each other. /// - /// Note: This allows using `read-stream`, which is similar to `read` in POSIX. - @since(version = 0.2.0) + /// This function returns a `stream` which provides the data received from the + /// file, and a `future` providing additional error information in case an + /// error is encountered. + /// + /// If no error is encountered, `stream.read` on the `stream` will return + /// `read-status::closed` with no `error-context` and the future resolves to + /// the value `ok`. If an error is encountered, `stream.read` on the + /// `stream` returns `read-status::closed` with an `error-context` and the future + /// resolves to `err` with an `error-code`. + /// + /// Note: This is similar to `pread` in POSIX. + @since(version = 0.3.0) read-via-stream: func( /// The offset within the file at which to start reading. offset: filesize, - ) -> result; + ) -> tuple, future>>; /// Return a stream for writing to a file, if available. /// /// May fail with an error-code describing why the file cannot be written. /// - /// Note: This allows using `write-stream`, which is similar to `write` in - /// POSIX. - @since(version = 0.2.0) + /// It is valid to write past the end of a file; the file is extended to the + /// extent of the write, with bytes between the previous end and the start of + /// the write set to zero. + /// + /// This function returns once either full contents of the stream are + /// written or an error is encountered. + /// + /// Note: This is similar to `pwrite` in POSIX. + @since(version = 0.3.0) write-via-stream: func( + /// Data to write + data: stream, /// The offset within the file at which to start writing. offset: filesize, - ) -> result; + ) -> future>; /// Return a stream for appending to a file, if available. /// /// May fail with an error-code describing why the file cannot be appended. /// - /// Note: This allows using `write-stream`, which is similar to `write` with - /// `O_APPEND` in POSIX. - @since(version = 0.2.0) - append-via-stream: func() -> result; + /// This function returns once either full contents of the stream are + /// written or an error is encountered. + /// + /// Note: This is similar to `write` with `O_APPEND` in POSIX. + @since(version = 0.3.0) + append-via-stream: func(data: stream) -> future>; /// Provide file advisory information on a descriptor. /// /// This is similar to `posix_fadvise` in POSIX. - @since(version = 0.2.0) - advise: func( + @since(version = 0.3.0) + advise: async func( /// The offset within the file to which the advisory applies. offset: filesize, /// The length of the region to which the advisory applies. @@ -352,8 +381,8 @@ interface types { /// opened for writing. /// /// Note: This is similar to `fdatasync` in POSIX. - @since(version = 0.2.0) - sync-data: func() -> result<_, error-code>; + @since(version = 0.3.0) + sync-data: async func() -> result<_, error-code>; /// Get flags associated with a descriptor. /// @@ -361,8 +390,8 @@ interface types { /// /// Note: This returns the value that was the `fs_flags` value returned /// from `fdstat_get` in earlier versions of WASI. - @since(version = 0.2.0) - get-flags: func() -> result; + @since(version = 0.3.0) + get-flags: async func() -> result; /// Get the dynamic type of a descriptor. /// @@ -374,65 +403,29 @@ interface types { /// /// Note: This returns the value that was the `fs_filetype` value returned /// from `fdstat_get` in earlier versions of WASI. - @since(version = 0.2.0) - get-type: func() -> result; + @since(version = 0.3.0) + get-type: async func() -> result; /// Adjust the size of an open file. If this increases the file's size, the /// extra bytes are filled with zeros. /// /// Note: This was called `fd_filestat_set_size` in earlier versions of WASI. - @since(version = 0.2.0) - set-size: func(size: filesize) -> result<_, error-code>; + @since(version = 0.3.0) + set-size: async func(size: filesize) -> result<_, error-code>; /// Adjust the timestamps of an open file or directory. /// /// Note: This is similar to `futimens` in POSIX. /// /// Note: This was called `fd_filestat_set_times` in earlier versions of WASI. - @since(version = 0.2.0) - set-times: func( + @since(version = 0.3.0) + set-times: async func( /// The desired values of the data access timestamp. data-access-timestamp: new-timestamp, /// The desired values of the data modification timestamp. data-modification-timestamp: new-timestamp, ) -> result<_, error-code>; - /// Read from a descriptor, without using and updating the descriptor's offset. - /// - /// This function returns a list of bytes containing the data that was - /// read, along with a bool which, when true, indicates that the end of the - /// file was reached. The returned list will contain up to `length` bytes; it - /// may return fewer than requested, if the end of the file is reached or - /// if the I/O operation is interrupted. - /// - /// In the future, this may change to return a `stream`. - /// - /// Note: This is similar to `pread` in POSIX. - @since(version = 0.2.0) - read: func( - /// The maximum number of bytes to read. - length: filesize, - /// The offset within the file at which to read. - offset: filesize, - ) -> result, bool>, error-code>; - - /// Write to a descriptor, without using and updating the descriptor's offset. - /// - /// It is valid to write past the end of a file; the file is extended to the - /// extent of the write, with bytes between the previous end and the start of - /// the write set to zero. - /// - /// In the future, this may change to take a `stream`. - /// - /// Note: This is similar to `pwrite` in POSIX. - @since(version = 0.2.0) - write: func( - /// Data to write - buffer: list, - /// The offset within the file at which to write. - offset: filesize, - ) -> result; - /// Read directory entries from a directory. /// /// On filesystems where directories contain entries referring to themselves @@ -442,8 +435,11 @@ interface types { /// This always returns a new stream which starts at the beginning of the /// directory. Multiple streams may be active on the same directory, and they /// do not interfere with each other. - @since(version = 0.2.0) - read-directory: func() -> result; + /// + /// This function returns a future, which will resolve to an error code if + /// reading full contents of the directory fails. + @since(version = 0.3.0) + read-directory: func() -> tuple, future>>; /// Synchronize the data and metadata of a file to disk. /// @@ -451,14 +447,14 @@ interface types { /// opened for writing. /// /// Note: This is similar to `fsync` in POSIX. - @since(version = 0.2.0) - sync: func() -> result<_, error-code>; + @since(version = 0.3.0) + sync: async func() -> result<_, error-code>; /// Create a directory. /// /// Note: This is similar to `mkdirat` in POSIX. - @since(version = 0.2.0) - create-directory-at: func( + @since(version = 0.3.0) + create-directory-at: async func( /// The relative path at which to create the directory. path: string, ) -> result<_, error-code>; @@ -472,8 +468,8 @@ interface types { /// modified, use `metadata-hash`. /// /// Note: This was called `fd_filestat_get` in earlier versions of WASI. - @since(version = 0.2.0) - stat: func() -> result; + @since(version = 0.3.0) + stat: async func() -> result; /// Return the attributes of a file or directory. /// @@ -482,8 +478,8 @@ interface types { /// discussion of alternatives. /// /// Note: This was called `path_filestat_get` in earlier versions of WASI. - @since(version = 0.2.0) - stat-at: func( + @since(version = 0.3.0) + stat-at: async func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, /// The relative path of the file or directory to inspect. @@ -496,8 +492,8 @@ interface types { /// /// Note: This was called `path_filestat_set_times` in earlier versions of /// WASI. - @since(version = 0.2.0) - set-times-at: func( + @since(version = 0.3.0) + set-times-at: async func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, /// The relative path of the file or directory to operate on. @@ -515,8 +511,8 @@ interface types { /// `error-code::not-permitted` if the old path is not a file. /// /// Note: This is similar to `linkat` in POSIX. - @since(version = 0.2.0) - link-at: func( + @since(version = 0.3.0) + link-at: async func( /// Flags determining the method of how the path is resolved. old-path-flags: path-flags, /// The relative source path from which to link. @@ -539,8 +535,8 @@ interface types { /// `error-code::read-only`. /// /// Note: This is similar to `openat` in POSIX. - @since(version = 0.2.0) - open-at: func( + @since(version = 0.3.0) + open-at: async func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, /// The relative path of the object to open. @@ -557,8 +553,8 @@ interface types { /// filesystem, this function fails with `error-code::not-permitted`. /// /// Note: This is similar to `readlinkat` in POSIX. - @since(version = 0.2.0) - readlink-at: func( + @since(version = 0.3.0) + readlink-at: async func( /// The relative path of the symbolic link from which to read. path: string, ) -> result; @@ -568,8 +564,8 @@ interface types { /// Return `error-code::not-empty` if the directory is not empty. /// /// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. - @since(version = 0.2.0) - remove-directory-at: func( + @since(version = 0.3.0) + remove-directory-at: async func( /// The relative path to a directory to remove. path: string, ) -> result<_, error-code>; @@ -577,8 +573,8 @@ interface types { /// Rename a filesystem object. /// /// Note: This is similar to `renameat` in POSIX. - @since(version = 0.2.0) - rename-at: func( + @since(version = 0.3.0) + rename-at: async func( /// The relative source path of the file or directory to rename. old-path: string, /// The base directory for `new-path`. @@ -593,8 +589,8 @@ interface types { /// `error-code::not-permitted`. /// /// Note: This is similar to `symlinkat` in POSIX. - @since(version = 0.2.0) - symlink-at: func( + @since(version = 0.3.0) + symlink-at: async func( /// The contents of the symbolic link. old-path: string, /// The relative destination path at which to create the symbolic link. @@ -603,10 +599,15 @@ interface types { /// Unlink a filesystem object that is not a directory. /// - /// Return `error-code::is-directory` if the path refers to a directory. - /// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. - @since(version = 0.2.0) - unlink-file-at: func( + /// This is similar to `unlinkat(fd, path, 0)` in POSIX. + /// + /// Error returns are as specified by POSIX. + /// + /// If the filesystem object is a directory, `error-code::access` or + /// `error-code::is-directory` may be returned instead of the + /// POSIX-specified `error-code::not-permitted`. + @since(version = 0.3.0) + unlink-file-at: async func( /// The relative path to a file to unlink. path: string, ) -> result<_, error-code>; @@ -617,8 +618,8 @@ interface types { /// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers. /// wasi-filesystem does not expose device and inode numbers, so this function /// may be used instead. - @since(version = 0.2.0) - is-same-object: func(other: borrow) -> bool; + @since(version = 0.3.0) + is-same-object: async func(other: borrow) -> bool; /// Return a hash of the metadata associated with a filesystem object referred /// to by a descriptor. @@ -639,40 +640,19 @@ interface types { /// computed hash. /// /// However, none of these is required. - @since(version = 0.2.0) - metadata-hash: func() -> result; + @since(version = 0.3.0) + metadata-hash: async func() -> result; /// Return a hash of the metadata associated with a filesystem object referred /// to by a directory descriptor and a relative path. /// /// This performs the same hash computation as `metadata-hash`. - @since(version = 0.2.0) - metadata-hash-at: func( + @since(version = 0.3.0) + metadata-hash-at: async func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, /// The relative path of the file or directory to inspect. path: string, ) -> result; } - - /// A stream of directory entries. - @since(version = 0.2.0) - resource directory-entry-stream { - /// Read a single directory entry from a `directory-entry-stream`. - @since(version = 0.2.0) - read-directory-entry: func() -> result, error-code>; - } - - /// Attempts to extract a filesystem-related `error-code` from the stream - /// `error` provided. - /// - /// Stream operations which return `stream-error::last-operation-failed` - /// have a payload with more information about the operation that failed. - /// This payload can be passed through to this function to see if there's - /// filesystem-related information about the error to return. - /// - /// Note that this function is fallible because not all stream-related - /// errors are filesystem-related errors. - @since(version = 0.2.0) - filesystem-error-code: func(err: borrow) -> option; } diff --git a/proposals/filesystem/wit/world.wit b/proposals/filesystem/wit/world.wit index f166fb41d..c0ab32afe 100644 --- a/proposals/filesystem/wit/world.wit +++ b/proposals/filesystem/wit/world.wit @@ -1,9 +1,9 @@ -package wasi:filesystem@0.2.12; +package wasi:filesystem@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world imports { - @since(version = 0.2.0) + @since(version = 0.3.0) import types; - @since(version = 0.2.0) + @since(version = 0.3.0) import preopens; } diff --git a/proposals/http/README.md b/proposals/http/README.md index 5ed5e7f24..7b3e6bd4e 100644 --- a/proposals/http/README.md +++ b/proposals/http/README.md @@ -22,9 +22,11 @@ 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 a -[world], `wasi:http/proxy`, that circumscribes a minimal execution environment -for wasm HTTP [proxies]. +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 @@ -37,25 +39,24 @@ 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/proxy` world is meant to be implementable by a wide variety of +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/proxy` world is meant to support flexible auto-scaling +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/proxy` world is meant to allow the chaining of HTTP -intermediaries to be implemented directly in terms of [Component Model] linking. -(Fully realizing this goal will require additional features only available in -the [Preview 3] timeframe.) +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/ -[Preview 3]: https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#streams ### Non-goals @@ -66,18 +67,17 @@ environment (for this, see the [wasi-cloud-core] proposal). ### API walk-through -The proposal can be understood by first reading the comments of [`proxy.wit`], -then [`handler.wit`] and finally [`types.wit`]. +The proposal can be understood by first reading the comments of [`worlds.wit`], +then [`types.wit`]. -[`proxy.wit`]: ./wit/proxy.wit -[`handler.wit`]: ./wit/handler.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 proxy +wit-bindgen c wit/ --world service ``` and can be validated and otherwise manipulated via: ``` diff --git a/proposals/http/imports.md b/proposals/http/imports.md deleted file mode 100644 index dc10b1b9f..000000000 --- a/proposals/http/imports.md +++ /dev/null @@ -1,1541 +0,0 @@ -

World imports

-

The wasi:http/imports world imports all the APIs for HTTP proxies. -It is intended to be included in other worlds.

- -

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:random/random@0.2.12

-

WASI Random is a random data API.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-random-bytes: func

-

Return len cryptographically-secure random or pseudo-random bytes.

-

This function must produce data at least as cryptographically secure and -fast as an adequately seeded cryptographically-secure pseudo-random -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-random-u64: func

-

Return a cryptographically-secure random or pseudo-random u64 value.

-

This function returns the same type of data as get-random-bytes, -represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:cli/stdout@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stderr: func

-
Return values
- -

Import interface wasi:cli/stdin@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

-

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:http/types@0.2.12

-

This interface defines all of the types and methods for implementing -HTTP Requests and Responses, both incoming and outgoing, as well as -their headers, trailers, and bodies.

-
-

Types

-

type duration

-

duration

-

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type io-error

-

error

-

-

type pollable

-

pollable

-

-

variant method

-

This type corresponds to HTTP standard Methods.

-
Variant Cases
-
    -
  • get
    • -
  • head
    • -
  • post
    • -
  • put
    • -
  • delete
    • -
  • connect
    • -
  • options
    • -
  • trace
    • -
  • patch
    • -
  • other: string
    • -
-

variant scheme

-

This type corresponds to HTTP standard Related Schemes.

-
Variant Cases
-
    -
  • HTTP
    • -
  • HTTPS
    • -
  • other: string
    • -
-

record DNS-error-payload

-

Defines the case payload type for DNS-error above:

-
Record Fields
-
    -
  • rcode: option<string>
    • -
  • info-code: option<u16>
    • -
-

record TLS-alert-received-payload

-

Defines the case payload type for TLS-alert-received above:

-
Record Fields
-
    -
  • alert-id: option<u8>
    • -
  • alert-message: option<string>
    • -
-

record field-size-payload

-

Defines the case payload type for HTTP-response-{header,trailer}-size above:

-
Record Fields
-
    -
  • field-name: option<string>
    • -
  • field-size: option<u32>
    • -
-

variant error-code

-

These cases are inspired by the IANA HTTP Proxy Error Types: -https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

-
Variant Cases
-
    -
  • DNS-timeout
    • -
  • DNS-error: DNS-error-payload
    • -
  • destination-not-found
    • -
  • destination-unavailable
    • -
  • destination-IP-prohibited
    • -
  • destination-IP-unroutable
    • -
  • connection-refused
    • -
  • connection-terminated
    • -
  • connection-timeout
    • -
  • connection-read-timeout
    • -
  • connection-write-timeout
    • -
  • connection-limit-reached
    • -
  • TLS-protocol-error
    • -
  • TLS-certificate-error
    • -
  • TLS-alert-received: TLS-alert-received-payload
    • -
  • HTTP-request-denied
    • -
  • HTTP-request-length-required
    • -
  • HTTP-request-body-size: option<u64>
    • -
  • HTTP-request-method-invalid
    • -
  • HTTP-request-URI-invalid
    • -
  • HTTP-request-URI-too-long
    • -
  • HTTP-request-header-section-size: option<u32>
    • -
  • HTTP-request-header-size: option<field-size-payload>
    • -
  • HTTP-request-trailer-section-size: option<u32>
    • -
  • HTTP-request-trailer-size: field-size-payload
    • -
  • HTTP-response-incomplete
    • -
  • HTTP-response-header-section-size: option<u32>
    • -
  • HTTP-response-header-size: field-size-payload
    • -
  • HTTP-response-body-size: option<u64>
    • -
  • HTTP-response-trailer-section-size: option<u32>
    • -
  • HTTP-response-trailer-size: field-size-payload
    • -
  • HTTP-response-transfer-coding: option<string>
    • -
  • HTTP-response-content-coding: option<string>
    • -
  • HTTP-response-timeout
    • -
  • HTTP-upgrade-failed
    • -
  • HTTP-protocol-error
    • -
  • loop-detected
    • -
  • configuration-error
    • -
  • internal-error: option<string>

    This is a catch-all error for anything that doesn't fit cleanly into a -more specific case. It also includes an optional string for an -unstructured description of the error. Users should not depend on the -string for diagnosing errors, as it's not required to be consistent -between implementations. -

    • -
-

variant header-error

-

This type enumerates the different kinds of errors that may occur when -setting or appending to a fields resource.

-
Variant Cases
-
    -
  • -

    invalid-syntax

    -

    This error indicates that a `field-name` or `field-value` was -syntactically invalid when used with an operation that sets headers in a -`fields`. -

    • -
  • -

    forbidden

    -

    This error indicates that a forbidden `field-name` was used when trying -to set a header in a `fields`. -

    • -
  • -

    immutable

    -

    This error indicates that the operation on the `fields` was not -permitted because the fields are immutable. -

    • -
-

type field-key

-

string

-

Field keys are always strings. -

Field keys should always be treated as case insensitive by the fields -resource for the purposes of equality checking.

-

Deprecation

-

This type has been deprecated in favor of the field-name type.

-

type field-name

-

field-key

-

Field names are always strings. -

Field names should always be treated as case insensitive by the fields -resource for the purposes of equality checking.

-

type field-value

-

field-value

-

Field values should always be ASCII strings. However, in -reality, HTTP implementations often have to interpret malformed values, -so they are provided as a list of bytes. -

resource fields

-

This following block defines the fields resource which corresponds to -HTTP standard Fields. Fields are a common representation used for both -Headers and Trailers.

-

A fields may be mutable or immutable. A fields created using the -constructor, from-list, or clone will be mutable, but a fields -resource given by other means (including, but not limited to, -incoming-request.headers, outgoing-request.headers) might be -immutable. In an immutable fields, the set, append, and delete -operations will fail with header-error.immutable.

-

type headers

-

fields

-

Headers is an alias for Fields. -

type trailers

-

fields

-

Trailers is an alias for Fields. -

resource incoming-request

-

Represents an incoming HTTP Request.

-

resource outgoing-request

-

Represents an outgoing HTTP Request.

-

resource request-options

-

Parameters for making an HTTP Request. Each of these parameters is -currently an optional timeout applicable to the transport layer of the -HTTP protocol.

-

These timeouts are separate from any the user may use to bound a -blocking call to wasi:io/poll.poll.

-

resource response-outparam

-

Represents the ability to send an HTTP Response.

-

This resource is used by the wasi:http/incoming-handler interface to -allow a Response to be sent corresponding to the Request provided as the -other argument to incoming-handler.handle.

-

type status-code

-

u16

-

This type corresponds to the HTTP standard Status Code. -

resource incoming-response

-

Represents an incoming HTTP Response.

-

resource incoming-body

-

Represents an incoming HTTP Request or Response's Body.

-

A body has both its contents - a stream of bytes - and a (possibly -empty) set of trailers, indicating that the full contents of the -body have been received. This resource represents the contents as -an input-stream and the delivery of trailers as a future-trailers, -and ensures that the user of this interface may only be consuming either -the body contents or waiting on trailers at any given time.

-

resource future-trailers

-

Represents a future which may eventually return trailers, or an error.

-

In the case that the incoming HTTP Request or Response did not have any -trailers, this future will resolve to the empty set of trailers once the -complete Request or Response body has been received.

-

resource outgoing-response

-

Represents an outgoing HTTP Response.

-

resource outgoing-body

-

Represents an outgoing HTTP Request or Response's Body.

-

A body has both its contents - a stream of bytes - and a (possibly -empty) set of trailers, inducating the full contents of the body -have been sent. This resource represents the contents as an -output-stream child resource, and the completion of the body (with -optional trailers) with a static function that consumes the -outgoing-body resource, and ensures that the user of this interface -may not write to the body contents after the body has been finished.

-

If the user code drops this resource, as opposed to calling the static -method finish, the implementation should treat the body as incomplete, -and that an error has occurred. The implementation should propagate this -error to the HTTP protocol by whatever means it has available, -including: corrupting the body on the wire, aborting the associated -Request, or sending a late status code for the Response.

-

resource future-incoming-response

-

Represents a future which may eventually return an incoming HTTP -Response, or an error.

-

This resource is returned by the wasi:http/outgoing-handler interface to -provide the HTTP Response corresponding to the sent Request.

-

Functions

-

http-error-code: func

-

Attempts to extract a http-related error from the wasi:io error -provided.

-

Stream operations which return -wasi:io/stream.stream-error.last-operation-failed have a payload of -type wasi:io/error.error with more information about the operation -that failed. This payload can be passed through to this function to see -if there's http-related information about the error to return.

-

Note that this function is fallible because not all io-errors are -http-related errors.

-
Params
- -
Return values
- -

[constructor]fields: func

-

Construct an empty HTTP Fields.

-

The resulting fields is mutable.

-
Return values
- -

[static]fields.from-list: func

-

Construct an HTTP Fields.

-

The resulting fields is mutable.

-

The list represents each name-value pair in the Fields. Names -which have multiple values are represented by multiple entries in this -list with the same name.

-

The tuple is a pair of the field name, represented as a string, and -Value, represented as a list of bytes.

-

An error result will be returned if any field-name or field-value is -syntactically invalid, or if a field is forbidden.

-
Params
- -
Return values
- -

[method]fields.get: func

-

Get all of the values corresponding to a name. If the name is not present -in this fields or is syntactically invalid, an empty list is returned. -However, if the name is present but empty, this is represented by a list -with one or more empty field-values present.

-
Params
- -
Return values
- -

[method]fields.has: func

-

Returns true when the name is present in this fields. If the name is -syntactically invalid, false is returned.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]fields.set: func

-

Set all of the values for a name. Clears any existing values for that -name, if they have been set.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name or any of -the field-values are syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.delete: func

-

Delete all values for a name. Does nothing if no values for the name -exist.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name is -syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.append: func

-

Append a value for a name. Does not change or delete any existing -values for that name.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name or -field-value are syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.entries: func

-

Retrieve the full set of names and values in the Fields. Like the -constructor, the list represents each name-value pair.

-

The outer list represents each name-value pair in the Fields. Names -which have multiple values are represented by multiple entries in this -list with the same name.

-

The names and values are always returned in the original casing and in -the order in which they will be serialized for transport.

-
Params
- -
Return values
- -

[method]fields.clone: func

-

Make a deep copy of the Fields. Equivalent in behavior to calling the -fields constructor on the return value of entries. The resulting -fields is mutable.

-
Params
- -
Return values
- -

[method]incoming-request.method: func

-

Returns the method of the incoming request.

-
Params
- -
Return values
- -

[method]incoming-request.path-with-query: func

-

Returns the path with query parameters from the request, as a string.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]incoming-request.scheme: func

-

Returns the protocol scheme from the request.

-
Params
- -
Return values
- -

[method]incoming-request.authority: func

-

Returns the authority of the Request's target URI, if present.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]incoming-request.headers: func

-

Get the headers associated with the request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

The headers returned are a child resource: it must be dropped before -the parent incoming-request is dropped. Dropping this -incoming-request before all children are dropped will trap.

-
Params
- -
Return values
- -

[method]incoming-request.consume: func

-

Gives the incoming-body associated with this request. Will only -return success at most once, and subsequent calls will return error.

-
Params
- -
Return values
- -

[constructor]outgoing-request: func

-

Construct a new outgoing-request with a default method of GET, and -none values for path-with-query, scheme, and authority.

-
    -
  • headers is the HTTP Headers for the Request.
    • -
-

It is possible to construct, or manipulate with the accessor functions -below, an outgoing-request with an invalid combination of scheme -and authority, or headers which are not permitted to be sent. -It is the obligation of the outgoing-handler.handle implementation -to reject invalid constructions of outgoing-request.

-
Params
- -
Return values
- -

[method]outgoing-request.body: func

-

Returns the resource corresponding to the outgoing Body for this -Request.

-

Returns success on the first call: the outgoing-body resource for -this outgoing-request can be retrieved at most once. Subsequent -calls will return error.

-
Params
- -
Return values
- -

[method]outgoing-request.method: func

-

Get the Method for the Request.

-
Params
- -
Return values
- -

[method]outgoing-request.set-method: func

-

Set the Method for the Request. Fails if the string present in a -method.other argument is not a syntactically valid method.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.path-with-query: func

-

Get the combination of the HTTP Path and Query for the Request. -When none, this represents an empty Path and empty Query.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]outgoing-request.set-path-with-query: func

-

Set the combination of the HTTP Path and Query for the Request. -When none, this represents an empty Path and empty Query. Fails is the -string given is not a syntactically valid path and query uri component.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.scheme: func

-

Get the HTTP Related Scheme for the Request. When none, the -implementation may choose an appropriate default scheme.

-
Params
- -
Return values
- -

[method]outgoing-request.set-scheme: func

-

Set the HTTP Related Scheme for the Request. When none, the -implementation may choose an appropriate default scheme. Fails if the -string given is not a syntactically valid uri scheme.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.authority: func

-

Get the authority of the Request's target URI. A value of none may be used -with Related Schemes which do not require an authority. The HTTP and -HTTPS schemes always require an authority.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]outgoing-request.set-authority: func

-

Set the authority of the Request's target URI. A value of none may be used -with Related Schemes which do not require an authority. The HTTP and -HTTPS schemes always require an authority. Fails if the string given is -not a syntactically valid URI authority.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.headers: func

-

Get the headers associated with the Request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -outgoing-request is dropped, or its ownership is transferred to -another component by e.g. outgoing-handler.handle.

-
Params
- -
Return values
- -

[constructor]request-options: func

-

Construct a default request-options value.

-
Return values
- -

[method]request-options.connect-timeout: func

-

The timeout for the initial connect to the HTTP Server.

-
Params
- -
Return values
- -

[method]request-options.set-connect-timeout: func

-

Set the timeout for the initial connect to the HTTP Server. An error -return value indicates that this timeout is not supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]request-options.first-byte-timeout: func

-

The timeout for receiving the first byte of the Response body.

-
Params
- -
Return values
- -

[method]request-options.set-first-byte-timeout: func

-

Set the timeout for receiving the first byte of the Response body. An -error return value indicates that this timeout is not supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]request-options.between-bytes-timeout: func

-

The timeout for receiving subsequent chunks of bytes in the Response -body stream.

-
Params
- -
Return values
- -

[method]request-options.set-between-bytes-timeout: func

-

Set the timeout for receiving subsequent chunks of bytes in the Response -body stream. An error return value indicates that this timeout is not -supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]response-outparam.send-informational: func

-

Send an HTTP 1xx response.

-

Unlike response-outparam.set, this does not consume the -response-outparam, allowing the guest to send an arbitrary number of -informational responses before sending the final response using -response-outparam.set.

-

This will return an HTTP-protocol-error if status is not in the -range [100-199], or an internal-error if the implementation does not -support informational responses.

-
Params
- -
Return values
- -

[static]response-outparam.set: func

-

Set the value of the response-outparam to either send a response, -or indicate an error.

-

This method consumes the response-outparam to ensure that it is -called at most once. If it is never called, the implementation -will respond with an error.

-

The user may provide an error to response to allow the -implementation determine how to respond with an HTTP error response.

-
Params
- -

[method]incoming-response.status: func

-

Returns the status code from the incoming response.

-
Params
- -
Return values
- -

[method]incoming-response.headers: func

-

Returns the headers from the incoming response.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -incoming-response is dropped.

-
Params
- -
Return values
- -

[method]incoming-response.consume: func

-

Returns the incoming body. May be called at most once. Returns error -if called additional times.

-
Params
- -
Return values
- -

[method]incoming-body.stream: func

-

Returns the contents of the body, as a stream of bytes.

-

Returns success on first call: the stream representing the contents -can be retrieved at most once. Subsequent calls will return error.

-

The returned input-stream resource is a child: it must be dropped -before the parent incoming-body is dropped, or consumed by -incoming-body.finish.

-

This invariant ensures that the implementation can determine whether -the user is consuming the contents of the body, waiting on the -future-trailers to be ready, or neither. This allows for network -backpressure is to be applied when the user is consuming the body, -and for that backpressure to not inhibit delivery of the trailers if -the user does not read the entire body.

-
Params
- -
Return values
- -

[static]incoming-body.finish: func

-

Takes ownership of incoming-body, and returns a future-trailers. -This function will trap if the input-stream child is still alive.

-
Params
- -
Return values
- -

[method]future-trailers.subscribe: func

-

Returns a pollable which becomes ready when either the trailers have -been received, or an error has occurred. When this pollable is ready, -the get method will return some.

-
Params
- -
Return values
- -

[method]future-trailers.get: func

-

Returns the contents of the trailers, or an error which occurred, -once the future is ready.

-

The outer option represents future readiness. Users can wait on this -option to become some using the subscribe method.

-

The outer result is used to retrieve the trailers or error at most -once. It will be success on the first call in which the outer option -is some, and error on subsequent calls.

-

The inner result represents that either the HTTP Request or Response -body, as well as any trailers, were received successfully, or that an -error occurred receiving them. The optional trailers indicates whether -or not trailers were present in the body.

-

When some trailers are returned by this method, the trailers -resource is immutable, and a child. Use of the set, append, or -delete methods will return an error, and the resource must be -dropped before the parent future-trailers is dropped.

-
Params
- -
Return values
- -

[constructor]outgoing-response: func

-

Construct an outgoing-response, with a default status-code of 200. -If a different status-code is needed, it must be set via the -set-status-code method.

-
    -
  • headers is the HTTP Headers for the Response.
    • -
-
Params
- -
Return values
- -

[method]outgoing-response.status-code: func

-

Get the HTTP Status Code for the Response.

-
Params
- -
Return values
- -

[method]outgoing-response.set-status-code: func

-

Set the HTTP Status Code for the Response. Fails if the status-code -given is not a valid http status code.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-response.headers: func

-

Get the headers associated with the Request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -outgoing-request is dropped, or its ownership is transferred to -another component by e.g. outgoing-handler.handle.

-
Params
- -
Return values
- -

[method]outgoing-response.body: func

-

Returns the resource corresponding to the outgoing Body for this Response.

-

Returns success on the first call: the outgoing-body resource for -this outgoing-response can be retrieved at most once. Subsequent -calls will return error.

-
Params
- -
Return values
- -

[method]outgoing-body.write: func

-

Returns a stream for writing the body contents.

-

The returned output-stream is a child resource: it must be dropped -before the parent outgoing-body resource is dropped (or finished), -otherwise the outgoing-body drop or finish will trap.

-

Returns success on the first call: the output-stream resource for -this outgoing-body may be retrieved at most once. Subsequent calls -will return error.

-
Params
- -
Return values
- -

[static]outgoing-body.finish: func

-

Finalize an outgoing body, optionally providing trailers. This must be -called to signal that the response is complete. If the outgoing-body -is dropped without calling outgoing-body.finalize, the implementation -should treat the body as corrupted.

-

Fails if the body's outgoing-request or outgoing-response was -constructed with a Content-Length header, and the contents written -to the body (via write) does not match the value given in the -Content-Length.

-
Params
- -
Return values
- -

[method]future-incoming-response.subscribe: func

-

Returns a pollable which becomes ready when either the Response has -been received, or an error has occurred. When this pollable is ready, -the get method will return some.

-
Params
- -
Return values
- -

[method]future-incoming-response.get: func

-

Returns the incoming HTTP Response, or an error, once one is ready.

-

The outer option represents future readiness. Users can wait on this -option to become some using the subscribe method.

-

The outer result is used to retrieve the response or error at most -once. It will be success on the first call in which the outer option -is some, and error on subsequent calls.

-

The inner result represents that either the incoming HTTP Response -status and headers have received successfully, or that an error -occurred. Errors may also occur while consuming the response body, -but those will be reported by the incoming-body and its -output-stream child.

-
Params
- -
Return values
- -

Import interface wasi:http/outgoing-handler@0.2.12

-

This interface defines a handler of outgoing HTTP Requests. It should be -imported by components which wish to make HTTP Requests.

-
-

Types

-

type outgoing-request

-

outgoing-request

-

-

type request-options

-

request-options

-

-

type future-incoming-response

-

future-incoming-response

-

-

type error-code

-

error-code

-

-

-

Functions

-

handle: func

-

This function is invoked with an outgoing HTTP Request, and it returns -a resource future-incoming-response which represents an HTTP Response -which may arrive in the future.

-

The options argument accepts optional parameters for the HTTP -protocol's transport layer.

-

This function may return an error if the outgoing-request is invalid -or not allowed to be made. Otherwise, protocol errors are reported -through the future-incoming-response.

-
Params
- -
Return values
- diff --git a/proposals/http/proxy.md b/proposals/http/proxy.md deleted file mode 100644 index a2cc340e6..000000000 --- a/proposals/http/proxy.md +++ /dev/null @@ -1,1574 +0,0 @@ -

World proxy

-

The wasi:http/proxy world captures a widely-implementable intersection of -hosts that includes HTTP forward and reverse proxies. Components targeting -this world may concurrently stream in and out any number of incoming and -outgoing HTTP requests.

- -

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:clocks/wall-clock@0.2.12

-

WASI Wall Clock is a clock API intended to let users query the current -time. The name "wall" makes an analogy to a "clock on the wall", which -is not necessarily monotonic as it may be reset.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A wall clock is a clock which measures the date and time according to -some external reference.

-

External references may be reset, so this clock is not necessarily -monotonic, making it unsuitable for measuring elapsed time.

-

It is intended for reporting the current date and time for humans.

-
-

Types

-

record datetime

-

A time and date in seconds plus nanoseconds.

-
Record Fields
-
    -
  • seconds: u64
    • -
  • nanoseconds: u32
    • -
-
-

Functions

-

now: func

-

Read the current value of the clock.

-

This clock is not monotonic, therefore calling this function repeatedly -will not necessarily produce a sequence of non-decreasing values.

-

The returned timestamps represent the number of seconds since -1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, -also known as Unix Time.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

resolution: func

-

Query the resolution of the clock.

-

The nanoseconds field of the output is always less than 1000000000.

-
Return values
- -

Import interface wasi:random/random@0.2.12

-

WASI Random is a random data API.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-random-bytes: func

-

Return len cryptographically-secure random or pseudo-random bytes.

-

This function must produce data at least as cryptographically secure and -fast as an adequately seeded cryptographically-secure pseudo-random -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-random-u64: func

-

Return a cryptographically-secure random or pseudo-random u64 value.

-

This function returns the same type of data as get-random-bytes, -represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:cli/stdout@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stdout: func

-
Return values
- -

Import interface wasi:cli/stderr@0.2.12

-
-

Types

-

type output-stream

-

output-stream

-

-

-

Functions

-

get-stderr: func

-
Return values
- -

Import interface wasi:cli/stdin@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

-

Functions

-

get-stdin: func

-
Return values
- -

Import interface wasi:http/types@0.2.12

-

This interface defines all of the types and methods for implementing -HTTP Requests and Responses, both incoming and outgoing, as well as -their headers, trailers, and bodies.

-
-

Types

-

type duration

-

duration

-

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type io-error

-

error

-

-

type pollable

-

pollable

-

-

variant method

-

This type corresponds to HTTP standard Methods.

-
Variant Cases
-
    -
  • get
    • -
  • head
    • -
  • post
    • -
  • put
    • -
  • delete
    • -
  • connect
    • -
  • options
    • -
  • trace
    • -
  • patch
    • -
  • other: string
    • -
-

variant scheme

-

This type corresponds to HTTP standard Related Schemes.

-
Variant Cases
-
    -
  • HTTP
    • -
  • HTTPS
    • -
  • other: string
    • -
-

record DNS-error-payload

-

Defines the case payload type for DNS-error above:

-
Record Fields
-
    -
  • rcode: option<string>
    • -
  • info-code: option<u16>
    • -
-

record TLS-alert-received-payload

-

Defines the case payload type for TLS-alert-received above:

-
Record Fields
-
    -
  • alert-id: option<u8>
    • -
  • alert-message: option<string>
    • -
-

record field-size-payload

-

Defines the case payload type for HTTP-response-{header,trailer}-size above:

-
Record Fields
-
    -
  • field-name: option<string>
    • -
  • field-size: option<u32>
    • -
-

variant error-code

-

These cases are inspired by the IANA HTTP Proxy Error Types: -https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

-
Variant Cases
-
    -
  • DNS-timeout
    • -
  • DNS-error: DNS-error-payload
    • -
  • destination-not-found
    • -
  • destination-unavailable
    • -
  • destination-IP-prohibited
    • -
  • destination-IP-unroutable
    • -
  • connection-refused
    • -
  • connection-terminated
    • -
  • connection-timeout
    • -
  • connection-read-timeout
    • -
  • connection-write-timeout
    • -
  • connection-limit-reached
    • -
  • TLS-protocol-error
    • -
  • TLS-certificate-error
    • -
  • TLS-alert-received: TLS-alert-received-payload
    • -
  • HTTP-request-denied
    • -
  • HTTP-request-length-required
    • -
  • HTTP-request-body-size: option<u64>
    • -
  • HTTP-request-method-invalid
    • -
  • HTTP-request-URI-invalid
    • -
  • HTTP-request-URI-too-long
    • -
  • HTTP-request-header-section-size: option<u32>
    • -
  • HTTP-request-header-size: option<field-size-payload>
    • -
  • HTTP-request-trailer-section-size: option<u32>
    • -
  • HTTP-request-trailer-size: field-size-payload
    • -
  • HTTP-response-incomplete
    • -
  • HTTP-response-header-section-size: option<u32>
    • -
  • HTTP-response-header-size: field-size-payload
    • -
  • HTTP-response-body-size: option<u64>
    • -
  • HTTP-response-trailer-section-size: option<u32>
    • -
  • HTTP-response-trailer-size: field-size-payload
    • -
  • HTTP-response-transfer-coding: option<string>
    • -
  • HTTP-response-content-coding: option<string>
    • -
  • HTTP-response-timeout
    • -
  • HTTP-upgrade-failed
    • -
  • HTTP-protocol-error
    • -
  • loop-detected
    • -
  • configuration-error
    • -
  • internal-error: option<string>

    This is a catch-all error for anything that doesn't fit cleanly into a -more specific case. It also includes an optional string for an -unstructured description of the error. Users should not depend on the -string for diagnosing errors, as it's not required to be consistent -between implementations. -

    • -
-

variant header-error

-

This type enumerates the different kinds of errors that may occur when -setting or appending to a fields resource.

-
Variant Cases
-
    -
  • -

    invalid-syntax

    -

    This error indicates that a `field-name` or `field-value` was -syntactically invalid when used with an operation that sets headers in a -`fields`. -

    • -
  • -

    forbidden

    -

    This error indicates that a forbidden `field-name` was used when trying -to set a header in a `fields`. -

    • -
  • -

    immutable

    -

    This error indicates that the operation on the `fields` was not -permitted because the fields are immutable. -

    • -
-

type field-key

-

string

-

Field keys are always strings. -

Field keys should always be treated as case insensitive by the fields -resource for the purposes of equality checking.

-

Deprecation

-

This type has been deprecated in favor of the field-name type.

-

type field-name

-

field-key

-

Field names are always strings. -

Field names should always be treated as case insensitive by the fields -resource for the purposes of equality checking.

-

type field-value

-

field-value

-

Field values should always be ASCII strings. However, in -reality, HTTP implementations often have to interpret malformed values, -so they are provided as a list of bytes. -

resource fields

-

This following block defines the fields resource which corresponds to -HTTP standard Fields. Fields are a common representation used for both -Headers and Trailers.

-

A fields may be mutable or immutable. A fields created using the -constructor, from-list, or clone will be mutable, but a fields -resource given by other means (including, but not limited to, -incoming-request.headers, outgoing-request.headers) might be -immutable. In an immutable fields, the set, append, and delete -operations will fail with header-error.immutable.

-

type headers

-

fields

-

Headers is an alias for Fields. -

type trailers

-

fields

-

Trailers is an alias for Fields. -

resource incoming-request

-

Represents an incoming HTTP Request.

-

resource outgoing-request

-

Represents an outgoing HTTP Request.

-

resource request-options

-

Parameters for making an HTTP Request. Each of these parameters is -currently an optional timeout applicable to the transport layer of the -HTTP protocol.

-

These timeouts are separate from any the user may use to bound a -blocking call to wasi:io/poll.poll.

-

resource response-outparam

-

Represents the ability to send an HTTP Response.

-

This resource is used by the wasi:http/incoming-handler interface to -allow a Response to be sent corresponding to the Request provided as the -other argument to incoming-handler.handle.

-

type status-code

-

u16

-

This type corresponds to the HTTP standard Status Code. -

resource incoming-response

-

Represents an incoming HTTP Response.

-

resource incoming-body

-

Represents an incoming HTTP Request or Response's Body.

-

A body has both its contents - a stream of bytes - and a (possibly -empty) set of trailers, indicating that the full contents of the -body have been received. This resource represents the contents as -an input-stream and the delivery of trailers as a future-trailers, -and ensures that the user of this interface may only be consuming either -the body contents or waiting on trailers at any given time.

-

resource future-trailers

-

Represents a future which may eventually return trailers, or an error.

-

In the case that the incoming HTTP Request or Response did not have any -trailers, this future will resolve to the empty set of trailers once the -complete Request or Response body has been received.

-

resource outgoing-response

-

Represents an outgoing HTTP Response.

-

resource outgoing-body

-

Represents an outgoing HTTP Request or Response's Body.

-

A body has both its contents - a stream of bytes - and a (possibly -empty) set of trailers, inducating the full contents of the body -have been sent. This resource represents the contents as an -output-stream child resource, and the completion of the body (with -optional trailers) with a static function that consumes the -outgoing-body resource, and ensures that the user of this interface -may not write to the body contents after the body has been finished.

-

If the user code drops this resource, as opposed to calling the static -method finish, the implementation should treat the body as incomplete, -and that an error has occurred. The implementation should propagate this -error to the HTTP protocol by whatever means it has available, -including: corrupting the body on the wire, aborting the associated -Request, or sending a late status code for the Response.

-

resource future-incoming-response

-

Represents a future which may eventually return an incoming HTTP -Response, or an error.

-

This resource is returned by the wasi:http/outgoing-handler interface to -provide the HTTP Response corresponding to the sent Request.

-

Functions

-

http-error-code: func

-

Attempts to extract a http-related error from the wasi:io error -provided.

-

Stream operations which return -wasi:io/stream.stream-error.last-operation-failed have a payload of -type wasi:io/error.error with more information about the operation -that failed. This payload can be passed through to this function to see -if there's http-related information about the error to return.

-

Note that this function is fallible because not all io-errors are -http-related errors.

-
Params
- -
Return values
- -

[constructor]fields: func

-

Construct an empty HTTP Fields.

-

The resulting fields is mutable.

-
Return values
- -

[static]fields.from-list: func

-

Construct an HTTP Fields.

-

The resulting fields is mutable.

-

The list represents each name-value pair in the Fields. Names -which have multiple values are represented by multiple entries in this -list with the same name.

-

The tuple is a pair of the field name, represented as a string, and -Value, represented as a list of bytes.

-

An error result will be returned if any field-name or field-value is -syntactically invalid, or if a field is forbidden.

-
Params
- -
Return values
- -

[method]fields.get: func

-

Get all of the values corresponding to a name. If the name is not present -in this fields or is syntactically invalid, an empty list is returned. -However, if the name is present but empty, this is represented by a list -with one or more empty field-values present.

-
Params
- -
Return values
- -

[method]fields.has: func

-

Returns true when the name is present in this fields. If the name is -syntactically invalid, false is returned.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]fields.set: func

-

Set all of the values for a name. Clears any existing values for that -name, if they have been set.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name or any of -the field-values are syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.delete: func

-

Delete all values for a name. Does nothing if no values for the name -exist.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name is -syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.append: func

-

Append a value for a name. Does not change or delete any existing -values for that name.

-

Fails with header-error.immutable if the fields are immutable.

-

Fails with header-error.invalid-syntax if the field-name or -field-value are syntactically invalid.

-
Params
- -
Return values
- -

[method]fields.entries: func

-

Retrieve the full set of names and values in the Fields. Like the -constructor, the list represents each name-value pair.

-

The outer list represents each name-value pair in the Fields. Names -which have multiple values are represented by multiple entries in this -list with the same name.

-

The names and values are always returned in the original casing and in -the order in which they will be serialized for transport.

-
Params
- -
Return values
- -

[method]fields.clone: func

-

Make a deep copy of the Fields. Equivalent in behavior to calling the -fields constructor on the return value of entries. The resulting -fields is mutable.

-
Params
- -
Return values
- -

[method]incoming-request.method: func

-

Returns the method of the incoming request.

-
Params
- -
Return values
- -

[method]incoming-request.path-with-query: func

-

Returns the path with query parameters from the request, as a string.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]incoming-request.scheme: func

-

Returns the protocol scheme from the request.

-
Params
- -
Return values
- -

[method]incoming-request.authority: func

-

Returns the authority of the Request's target URI, if present.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]incoming-request.headers: func

-

Get the headers associated with the request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

The headers returned are a child resource: it must be dropped before -the parent incoming-request is dropped. Dropping this -incoming-request before all children are dropped will trap.

-
Params
- -
Return values
- -

[method]incoming-request.consume: func

-

Gives the incoming-body associated with this request. Will only -return success at most once, and subsequent calls will return error.

-
Params
- -
Return values
- -

[constructor]outgoing-request: func

-

Construct a new outgoing-request with a default method of GET, and -none values for path-with-query, scheme, and authority.

-
    -
  • headers is the HTTP Headers for the Request.
    • -
-

It is possible to construct, or manipulate with the accessor functions -below, an outgoing-request with an invalid combination of scheme -and authority, or headers which are not permitted to be sent. -It is the obligation of the outgoing-handler.handle implementation -to reject invalid constructions of outgoing-request.

-
Params
- -
Return values
- -

[method]outgoing-request.body: func

-

Returns the resource corresponding to the outgoing Body for this -Request.

-

Returns success on the first call: the outgoing-body resource for -this outgoing-request can be retrieved at most once. Subsequent -calls will return error.

-
Params
- -
Return values
- -

[method]outgoing-request.method: func

-

Get the Method for the Request.

-
Params
- -
Return values
- -

[method]outgoing-request.set-method: func

-

Set the Method for the Request. Fails if the string present in a -method.other argument is not a syntactically valid method.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.path-with-query: func

-

Get the combination of the HTTP Path and Query for the Request. -When none, this represents an empty Path and empty Query.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]outgoing-request.set-path-with-query: func

-

Set the combination of the HTTP Path and Query for the Request. -When none, this represents an empty Path and empty Query. Fails is the -string given is not a syntactically valid path and query uri component.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.scheme: func

-

Get the HTTP Related Scheme for the Request. When none, the -implementation may choose an appropriate default scheme.

-
Params
- -
Return values
- -

[method]outgoing-request.set-scheme: func

-

Set the HTTP Related Scheme for the Request. When none, the -implementation may choose an appropriate default scheme. Fails if the -string given is not a syntactically valid uri scheme.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.authority: func

-

Get the authority of the Request's target URI. A value of none may be used -with Related Schemes which do not require an authority. The HTTP and -HTTPS schemes always require an authority.

-
Params
- -
Return values
-
    -
  • option<string>
    • -
-

[method]outgoing-request.set-authority: func

-

Set the authority of the Request's target URI. A value of none may be used -with Related Schemes which do not require an authority. The HTTP and -HTTPS schemes always require an authority. Fails if the string given is -not a syntactically valid URI authority.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-request.headers: func

-

Get the headers associated with the Request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -outgoing-request is dropped, or its ownership is transferred to -another component by e.g. outgoing-handler.handle.

-
Params
- -
Return values
- -

[constructor]request-options: func

-

Construct a default request-options value.

-
Return values
- -

[method]request-options.connect-timeout: func

-

The timeout for the initial connect to the HTTP Server.

-
Params
- -
Return values
- -

[method]request-options.set-connect-timeout: func

-

Set the timeout for the initial connect to the HTTP Server. An error -return value indicates that this timeout is not supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]request-options.first-byte-timeout: func

-

The timeout for receiving the first byte of the Response body.

-
Params
- -
Return values
- -

[method]request-options.set-first-byte-timeout: func

-

Set the timeout for receiving the first byte of the Response body. An -error return value indicates that this timeout is not supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]request-options.between-bytes-timeout: func

-

The timeout for receiving subsequent chunks of bytes in the Response -body stream.

-
Params
- -
Return values
- -

[method]request-options.set-between-bytes-timeout: func

-

Set the timeout for receiving subsequent chunks of bytes in the Response -body stream. An error return value indicates that this timeout is not -supported.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]response-outparam.send-informational: func

-

Send an HTTP 1xx response.

-

Unlike response-outparam.set, this does not consume the -response-outparam, allowing the guest to send an arbitrary number of -informational responses before sending the final response using -response-outparam.set.

-

This will return an HTTP-protocol-error if status is not in the -range [100-199], or an internal-error if the implementation does not -support informational responses.

-
Params
- -
Return values
- -

[static]response-outparam.set: func

-

Set the value of the response-outparam to either send a response, -or indicate an error.

-

This method consumes the response-outparam to ensure that it is -called at most once. If it is never called, the implementation -will respond with an error.

-

The user may provide an error to response to allow the -implementation determine how to respond with an HTTP error response.

-
Params
- -

[method]incoming-response.status: func

-

Returns the status code from the incoming response.

-
Params
- -
Return values
- -

[method]incoming-response.headers: func

-

Returns the headers from the incoming response.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -incoming-response is dropped.

-
Params
- -
Return values
- -

[method]incoming-response.consume: func

-

Returns the incoming body. May be called at most once. Returns error -if called additional times.

-
Params
- -
Return values
- -

[method]incoming-body.stream: func

-

Returns the contents of the body, as a stream of bytes.

-

Returns success on first call: the stream representing the contents -can be retrieved at most once. Subsequent calls will return error.

-

The returned input-stream resource is a child: it must be dropped -before the parent incoming-body is dropped, or consumed by -incoming-body.finish.

-

This invariant ensures that the implementation can determine whether -the user is consuming the contents of the body, waiting on the -future-trailers to be ready, or neither. This allows for network -backpressure is to be applied when the user is consuming the body, -and for that backpressure to not inhibit delivery of the trailers if -the user does not read the entire body.

-
Params
- -
Return values
- -

[static]incoming-body.finish: func

-

Takes ownership of incoming-body, and returns a future-trailers. -This function will trap if the input-stream child is still alive.

-
Params
- -
Return values
- -

[method]future-trailers.subscribe: func

-

Returns a pollable which becomes ready when either the trailers have -been received, or an error has occurred. When this pollable is ready, -the get method will return some.

-
Params
- -
Return values
- -

[method]future-trailers.get: func

-

Returns the contents of the trailers, or an error which occurred, -once the future is ready.

-

The outer option represents future readiness. Users can wait on this -option to become some using the subscribe method.

-

The outer result is used to retrieve the trailers or error at most -once. It will be success on the first call in which the outer option -is some, and error on subsequent calls.

-

The inner result represents that either the HTTP Request or Response -body, as well as any trailers, were received successfully, or that an -error occurred receiving them. The optional trailers indicates whether -or not trailers were present in the body.

-

When some trailers are returned by this method, the trailers -resource is immutable, and a child. Use of the set, append, or -delete methods will return an error, and the resource must be -dropped before the parent future-trailers is dropped.

-
Params
- -
Return values
- -

[constructor]outgoing-response: func

-

Construct an outgoing-response, with a default status-code of 200. -If a different status-code is needed, it must be set via the -set-status-code method.

-
    -
  • headers is the HTTP Headers for the Response.
    • -
-
Params
- -
Return values
- -

[method]outgoing-response.status-code: func

-

Get the HTTP Status Code for the Response.

-
Params
- -
Return values
- -

[method]outgoing-response.set-status-code: func

-

Set the HTTP Status Code for the Response. Fails if the status-code -given is not a valid http status code.

-
Params
- -
Return values
-
    -
  • result
    • -
-

[method]outgoing-response.headers: func

-

Get the headers associated with the Request.

-

The returned headers resource is immutable: set, append, and -delete operations will fail with header-error.immutable.

-

This headers resource is a child: it must be dropped before the parent -outgoing-request is dropped, or its ownership is transferred to -another component by e.g. outgoing-handler.handle.

-
Params
- -
Return values
- -

[method]outgoing-response.body: func

-

Returns the resource corresponding to the outgoing Body for this Response.

-

Returns success on the first call: the outgoing-body resource for -this outgoing-response can be retrieved at most once. Subsequent -calls will return error.

-
Params
- -
Return values
- -

[method]outgoing-body.write: func

-

Returns a stream for writing the body contents.

-

The returned output-stream is a child resource: it must be dropped -before the parent outgoing-body resource is dropped (or finished), -otherwise the outgoing-body drop or finish will trap.

-

Returns success on the first call: the output-stream resource for -this outgoing-body may be retrieved at most once. Subsequent calls -will return error.

-
Params
- -
Return values
- -

[static]outgoing-body.finish: func

-

Finalize an outgoing body, optionally providing trailers. This must be -called to signal that the response is complete. If the outgoing-body -is dropped without calling outgoing-body.finalize, the implementation -should treat the body as corrupted.

-

Fails if the body's outgoing-request or outgoing-response was -constructed with a Content-Length header, and the contents written -to the body (via write) does not match the value given in the -Content-Length.

-
Params
- -
Return values
- -

[method]future-incoming-response.subscribe: func

-

Returns a pollable which becomes ready when either the Response has -been received, or an error has occurred. When this pollable is ready, -the get method will return some.

-
Params
- -
Return values
- -

[method]future-incoming-response.get: func

-

Returns the incoming HTTP Response, or an error, once one is ready.

-

The outer option represents future readiness. Users can wait on this -option to become some using the subscribe method.

-

The outer result is used to retrieve the response or error at most -once. It will be success on the first call in which the outer option -is some, and error on subsequent calls.

-

The inner result represents that either the incoming HTTP Response -status and headers have received successfully, or that an error -occurred. Errors may also occur while consuming the response body, -but those will be reported by the incoming-body and its -output-stream child.

-
Params
- -
Return values
- -

Import interface wasi:http/outgoing-handler@0.2.12

-

This interface defines a handler of outgoing HTTP Requests. It should be -imported by components which wish to make HTTP Requests.

-
-

Types

-

type outgoing-request

-

outgoing-request

-

-

type request-options

-

request-options

-

-

type future-incoming-response

-

future-incoming-response

-

-

type error-code

-

error-code

-

-

-

Functions

-

handle: func

-

This function is invoked with an outgoing HTTP Request, and it returns -a resource future-incoming-response which represents an HTTP Response -which may arrive in the future.

-

The options argument accepts optional parameters for the HTTP -protocol's transport layer.

-

This function may return an error if the outgoing-request is invalid -or not allowed to be made. Otherwise, protocol errors are reported -through the future-incoming-response.

-
Params
- -
Return values
- -

Export interface wasi:http/incoming-handler@0.2.12

-
-

Types

-

type incoming-request

-

incoming-request

-

-

type response-outparam

-

response-outparam

-

-

-

Functions

-

handle: func

-

This function is invoked with an incoming HTTP Request, and a resource -response-outparam which provides the capability to reply with an HTTP -Response. The response is sent by calling the response-outparam.set -method, which allows execution to continue after the response has been -sent. This enables both streaming to the response body, and performing other -work.

-

The implementor of this function must write a response to the -response-outparam before returning, or else the caller will respond -with an error on its behalf.

-
Params
- diff --git a/proposals/http/wit-0.3.0-draft/deps.lock b/proposals/http/wit-0.3.0-draft/deps.lock deleted file mode 100644 index 1abde0a7b..000000000 --- a/proposals/http/wit-0.3.0-draft/deps.lock +++ /dev/null @@ -1,24 +0,0 @@ -[cli] -path = "../../cli/wit-0.3.0-draft" -sha256 = "ba19261a3c370fcafd06b549ffb0bbcc7efa10f2dd0c1c33ed36c07a25ea6471" -sha512 = "121d0a87bdc9b4bd780a542b3efb74e6d9c972e8c537bde0bb471e06e2d9ca250a30f586d6d94c130c4b4664f9698afa452cc9650a13680c3dc1cf81318da676" - -[clocks] -path = "../../clocks/wit-0.3.0-draft" -sha256 = "a8702c42e23c22a458207d0efa38cc1b64c8c6299b0e3152aa84327a7c1c952b" -sha512 = "da69a5d498b6afe0facf77ec3d21f6e8a2a4d4661ebfec310a2ce6f943cb01f92131a746765648febf96563ddac788e9f218941d3db2b905f3746dc8e05cf54d" - -[filesystem] -path = "../../filesystem/wit-0.3.0-draft" -sha256 = "d9db43c43b4e09899a9e54c76544eef17439fb42e2f730ed96d40eac994b0dfd" -sha512 = "3b7a1bef322ba36b1e9df768d740e4238f58d3c15d3e4c51fe899b93cf1e6641a79b5a8665ae71d38a80e1e0f852b30b023ecf318f4cbeacb36dd1ae0ac7e37b" - -[random] -path = "../../random/wit-0.3.0-draft" -sha256 = "d44de4e427505fdfd584a23479dba5899ad80aa8e174dc0528df840db8ae9a43" -sha512 = "6b08b32a197aee74076d0cdca6a09f78da9040eedd9ab3f64e5f14901ad5a0c5bbc592ad46a0d575dc6705249b3e10a413e09835616f753788aa598af605c776" - -[sockets] -path = "../../sockets/wit-0.3.0-draft" -sha256 = "ee64b45d3826b6ff2cd27f6ac24fe23c41e65ba4d155294671dc7d0a0b47ddfe" -sha512 = "dd797ab47b899aee52799f797497fa286f5e217307e8a451a7ba89bd05b7b9bfe2a6e0cf39c0e609ed4c76ed102487adff6e73156340f14baf70a9cc9e48ecbc" diff --git a/proposals/http/wit-0.3.0-draft/deps.toml b/proposals/http/wit-0.3.0-draft/deps.toml deleted file mode 100644 index d16cfcda6..000000000 --- a/proposals/http/wit-0.3.0-draft/deps.toml +++ /dev/null @@ -1,5 +0,0 @@ -cli = "../../cli/wit-0.3.0-draft" -clocks = "../../clocks/wit-0.3.0-draft" -filesystem = "../../filesystem/wit-0.3.0-draft" -random = "../../random/wit-0.3.0-draft" -sockets = "../../sockets/wit-0.3.0-draft" diff --git a/proposals/http/wit-0.3.0-draft/types.wit b/proposals/http/wit-0.3.0-draft/types.wit deleted file mode 100644 index f6d9dd99b..000000000 --- a/proposals/http/wit-0.3.0-draft/types.wit +++ /dev/null @@ -1,472 +0,0 @@ -package wasi:http@0.3.0-rc-2026-03-15; - -/// This interface defines all of the types and methods for implementing HTTP -/// Requests and Responses, as well as their headers, trailers, and bodies. -@since(version = 0.3.0-rc-2026-03-15) -interface types { - use wasi:clocks/types@0.3.0-rc-2026-03-15.{duration}; - - /// This type corresponds to HTTP standard Methods. - @since(version = 0.3.0-rc-2026-03-15) - variant method { - get, - head, - post, - put, - delete, - connect, - options, - trace, - patch, - other(string) - } - - /// This type corresponds to HTTP standard Related Schemes. - @since(version = 0.3.0-rc-2026-03-15) - variant scheme { - HTTP, - HTTPS, - other(string) - } - - /// These cases are inspired by the IANA HTTP Proxy Error Types: - /// - @since(version = 0.3.0-rc-2026-03-15) - variant error-code { - DNS-timeout, - DNS-error(DNS-error-payload), - destination-not-found, - destination-unavailable, - destination-IP-prohibited, - destination-IP-unroutable, - connection-refused, - connection-terminated, - connection-timeout, - connection-read-timeout, - connection-write-timeout, - connection-limit-reached, - TLS-protocol-error, - TLS-certificate-error, - TLS-alert-received(TLS-alert-received-payload), - HTTP-request-denied, - HTTP-request-length-required, - HTTP-request-body-size(option), - HTTP-request-method-invalid, - HTTP-request-URI-invalid, - HTTP-request-URI-too-long, - HTTP-request-header-section-size(option), - HTTP-request-header-size(option), - HTTP-request-trailer-section-size(option), - HTTP-request-trailer-size(field-size-payload), - HTTP-response-incomplete, - HTTP-response-header-section-size(option), - HTTP-response-header-size(field-size-payload), - HTTP-response-body-size(option), - HTTP-response-trailer-section-size(option), - HTTP-response-trailer-size(field-size-payload), - HTTP-response-transfer-coding(option), - HTTP-response-content-coding(option), - HTTP-response-timeout, - HTTP-upgrade-failed, - HTTP-protocol-error, - loop-detected, - configuration-error, - /// This is a catch-all error for anything that doesn't fit cleanly into a - /// more specific case. It also includes an optional string for an - /// unstructured description of the error. Users should not depend on the - /// string for diagnosing errors, as it's not required to be consistent - /// between implementations. - internal-error(option) - } - - /// Defines the case payload type for `DNS-error` above: - @since(version = 0.3.0-rc-2026-03-15) - record DNS-error-payload { - rcode: option, - info-code: option - } - - /// Defines the case payload type for `TLS-alert-received` above: - @since(version = 0.3.0-rc-2026-03-15) - record TLS-alert-received-payload { - alert-id: option, - alert-message: option - } - - /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: - @since(version = 0.3.0-rc-2026-03-15) - record field-size-payload { - field-name: option, - field-size: option - } - - /// This type enumerates the different kinds of errors that may occur when - /// setting or appending to a `fields` resource. - @since(version = 0.3.0-rc-2026-03-15) - variant header-error { - /// This error indicates that a `field-name` or `field-value` was - /// syntactically invalid when used with an operation that sets headers in a - /// `fields`. - invalid-syntax, - - /// This error indicates that a forbidden `field-name` was used when trying - /// to set a header in a `fields`. - forbidden, - - /// This error indicates that the operation on the `fields` was not - /// permitted because the fields are immutable. - immutable, - - /// This error indicates that the operation would exceed an - /// implementation-defined limit on field sizes. This may apply to - /// an individual `field-value`, a single `field-name` plus all its - /// values, or the total aggregate size of all fields. - size-exceeded, - - /// This is a catch-all error for anything that doesn't fit cleanly into a - /// more specific case. Implementations can use this to extend the error - /// type without breaking existing code. It also includes an optional - /// string for an unstructured description of the error. Users should not - /// depend on the string for diagnosing errors, as it's not required to be - /// consistent between implementations. - other(option), - } - - /// This type enumerates the different kinds of errors that may occur when - /// setting fields of a `request-options` resource. - @since(version = 0.3.0-rc-2026-03-15) - variant request-options-error { - /// Indicates the specified field is not supported by this implementation. - not-supported, - - /// Indicates that the operation on the `request-options` was not permitted - /// because it is immutable. - immutable, - - /// This is a catch-all error for anything that doesn't fit cleanly into a - /// more specific case. Implementations can use this to extend the error - /// type without breaking existing code. It also includes an optional - /// string for an unstructured description of the error. Users should not - /// depend on the string for diagnosing errors, as it's not required to be - /// consistent between implementations. - other(option), - } - - /// Field names are always strings. - /// - /// Field names should always be treated as case insensitive by the `fields` - /// resource for the purposes of equality checking. - @since(version = 0.3.0-rc-2026-03-15) - type field-name = string; - - /// Field values should always be ASCII strings. However, in - /// reality, HTTP implementations often have to interpret malformed values, - /// so they are provided as a list of bytes. - @since(version = 0.3.0-rc-2026-03-15) - type field-value = list; - - /// This following block defines the `fields` resource which corresponds to - /// HTTP standard Fields. Fields are a common representation used for both - /// Headers and Trailers. - /// - /// A `fields` may be mutable or immutable. A `fields` created using the - /// constructor, `from-list`, or `clone` will be mutable, but a `fields` - /// resource given by other means (including, but not limited to, - /// `request.headers`) might be be immutable. In an immutable fields, the - /// `set`, `append`, and `delete` operations will fail with - /// `header-error.immutable`. - /// - /// A `fields` resource should store `field-name`s and `field-value`s in their - /// original casing used to construct or mutate the `fields` resource. The `fields` - /// resource should use that original casing when serializing the fields for - /// transport or when returning them from a method. - /// - /// Implementations may impose limits on individual field values and on total - /// aggregate field section size. Operations that would exceed these limits - /// fail with `header-error.size-exceeded` - @since(version = 0.3.0-rc-2026-03-15) - resource fields { - - /// Construct an empty HTTP Fields. - /// - /// The resulting `fields` is mutable. - constructor(); - - /// Construct an HTTP Fields. - /// - /// The resulting `fields` is mutable. - /// - /// The list represents each name-value pair in the Fields. Names - /// which have multiple values are represented by multiple entries in this - /// list with the same name. - /// - /// The tuple is a pair of the field name, represented as a string, and - /// Value, represented as a list of bytes. In a valid Fields, all names - /// and values are valid UTF-8 strings. However, values are not always - /// well-formed, so they are represented as a raw list of bytes. - /// - /// An error result will be returned if any header or value was - /// syntactically invalid, if a header was forbidden, or if the - /// entries would exceed an implementation size limit. - from-list: static func( - entries: list> - ) -> result; - - /// Get all of the values corresponding to a name. If the name is not present - /// in this `fields`, an empty list is returned. However, if the name is - /// present but empty, this is represented by a list with one or more - /// empty field-values present. - get: func(name: field-name) -> list; - - /// Returns `true` when the name is present in this `fields`. If the name is - /// syntactically invalid, `false` is returned. - has: func(name: field-name) -> bool; - - /// Set all of the values for a name. Clears any existing values for that - /// name, if they have been set. - /// - /// Fails with `header-error.immutable` if the `fields` are immutable. - /// - /// Fails with `header-error.size-exceeded` if the name or values would - /// exceed an implementation-defined size limit. - set: func(name: field-name, value: list) -> result<_, header-error>; - - /// Delete all values for a name. Does nothing if no values for the name - /// exist. - /// - /// Fails with `header-error.immutable` if the `fields` are immutable. - delete: func(name: field-name) -> result<_, header-error>; - - /// Delete all values for a name. Does nothing if no values for the name - /// exist. - /// - /// Returns all values previously corresponding to the name, if any. - /// - /// Fails with `header-error.immutable` if the `fields` are immutable. - get-and-delete: func(name: field-name) -> result, header-error>; - - /// Append a value for a name. Does not change or delete any existing - /// values for that name. - /// - /// Fails with `header-error.immutable` if the `fields` are immutable. - /// - /// Fails with `header-error.size-exceeded` if the value would exceed - /// an implementation-defined size limit. - append: func(name: field-name, value: field-value) -> result<_, header-error>; - - /// Retrieve the full set of names and values in the Fields. Like the - /// constructor, the list represents each name-value pair. - /// - /// The outer list represents each name-value pair in the Fields. Names - /// which have multiple values are represented by multiple entries in this - /// list with the same name. - /// - /// The names and values are always returned in the original casing and in - /// the order in which they will be serialized for transport. - copy-all: func() -> list>; - - /// Make a deep copy of the Fields. Equivalent in behavior to calling the - /// `fields` constructor on the return value of `copy-all`. The resulting - /// `fields` is mutable. - clone: func() -> fields; - } - - /// Headers is an alias for Fields. - @since(version = 0.3.0-rc-2026-03-15) - type headers = fields; - - /// Trailers is an alias for Fields. - @since(version = 0.3.0-rc-2026-03-15) - type trailers = fields; - - /// Represents an HTTP Request. - @since(version = 0.3.0-rc-2026-03-15) - resource request { - - /// Construct a new `request` with a default `method` of `GET`, and - /// `none` values for `path-with-query`, `scheme`, and `authority`. - /// - /// `headers` is the HTTP Headers for the Request. - /// - /// `contents` is the optional body content stream with `none` - /// representing a zero-length content stream. - /// Once it is closed, `trailers` future must resolve to a result. - /// If `trailers` resolves to an error, underlying connection - /// will be closed immediately. - /// - /// `options` is optional `request-options` resource to be used - /// if the request is sent over a network connection. - /// - /// It is possible to construct, or manipulate with the accessor functions - /// below, a `request` with an invalid combination of `scheme` - /// and `authority`, or `headers` which are not permitted to be sent. - /// It is the obligation of the `handler.handle` implementation - /// to reject invalid constructions of `request`. - /// - /// The returned future resolves to result of transmission of this request. - new: static func( - headers: headers, - contents: option>, - trailers: future, error-code>>, - options: option - ) -> tuple>>; - - /// Get the Method for the Request. - get-method: func() -> method; - /// Set the Method for the Request. Fails if the string present in a - /// `method.other` argument is not a syntactically valid method. - set-method: func(method: method) -> result; - - /// Get the combination of the HTTP Path and Query for the Request. When - /// `none`, this represents an empty Path and empty Query. - get-path-with-query: func() -> option; - /// Set the combination of the HTTP Path and Query for the Request. When - /// `none`, this represents an empty Path and empty Query. Fails is the - /// string given is not a syntactically valid path and query uri component. - set-path-with-query: func(path-with-query: option) -> result; - - /// Get the HTTP Related Scheme for the Request. When `none`, the - /// implementation may choose an appropriate default scheme. - get-scheme: func() -> option; - /// Set the HTTP Related Scheme for the Request. When `none`, the - /// implementation may choose an appropriate default scheme. Fails if the - /// string given is not a syntactically valid uri scheme. - set-scheme: func(scheme: option) -> result; - - /// Get the authority of the Request's target URI. A value of `none` may be used - /// with Related Schemes which do not require an authority. The HTTP and - /// HTTPS schemes always require an authority. - get-authority: func() -> option; - /// Set the authority of the Request's target URI. A value of `none` may be used - /// with Related Schemes which do not require an authority. The HTTP and - /// HTTPS schemes always require an authority. Fails if the string given is - /// not a syntactically valid URI authority. - set-authority: func(authority: option) -> result; - - /// Get the `request-options` to be associated with this request - /// - /// The returned `request-options` resource is immutable: `set-*` operations - /// will fail if invoked. - /// - /// This `request-options` resource is a child: it must be dropped before - /// the parent `request` is dropped, or its ownership is transferred to - /// another component by e.g. `handler.handle`. - get-options: func() -> option; - - /// Get the headers associated with the Request. - /// - /// The returned `headers` resource is immutable: `set`, `append`, and - /// `delete` operations will fail with `header-error.immutable`. - get-headers: func() -> headers; - - /// Get body of the Request. - /// - /// Stream returned by this method represents the contents of the body. - /// Once the stream is reported as closed, callers should await the returned - /// future to determine whether the body was received successfully. - /// The future will only resolve after the stream is reported as closed. - /// - /// This function takes a `res` future as a parameter, which can be used to - /// communicate an error in handling of the request. - /// - /// Note that function will move the `request`, but references to headers or - /// request options acquired from it previously will remain valid. - consume-body: static func(this: request, res: future>) -> tuple, future, error-code>>>; - } - - /// Parameters for making an HTTP Request. Each of these parameters is - /// currently an optional timeout applicable to the transport layer of the - /// HTTP protocol. - /// - /// These timeouts are separate from any the user may use to bound an - /// asynchronous call. - @since(version = 0.3.0-rc-2026-03-15) - resource request-options { - /// Construct a default `request-options` value. - constructor(); - - /// The timeout for the initial connect to the HTTP Server. - get-connect-timeout: func() -> option; - - /// Set the timeout for the initial connect to the HTTP Server. An error - /// return value indicates that this timeout is not supported or that this - /// handle is immutable. - set-connect-timeout: func(duration: option) -> result<_, request-options-error>; - - /// The timeout for receiving the first byte of the Response body. - get-first-byte-timeout: func() -> option; - - /// Set the timeout for receiving the first byte of the Response body. An - /// error return value indicates that this timeout is not supported or that - /// this handle is immutable. - set-first-byte-timeout: func(duration: option) -> result<_, request-options-error>; - - /// The timeout for receiving subsequent chunks of bytes in the Response - /// body stream. - get-between-bytes-timeout: func() -> option; - - /// Set the timeout for receiving subsequent chunks of bytes in the Response - /// body stream. An error return value indicates that this timeout is not - /// supported or that this handle is immutable. - set-between-bytes-timeout: func(duration: option) -> result<_, request-options-error>; - - /// Make a deep copy of the `request-options`. - /// The resulting `request-options` is mutable. - clone: func() -> request-options; - } - - /// This type corresponds to the HTTP standard Status Code. - @since(version = 0.3.0-rc-2026-03-15) - type status-code = u16; - - /// Represents an HTTP Response. - @since(version = 0.3.0-rc-2026-03-15) - resource response { - - /// Construct a new `response`, with a default `status-code` of `200`. - /// If a different `status-code` is needed, it must be set via the - /// `set-status-code` method. - /// - /// `headers` is the HTTP Headers for the Response. - /// - /// `contents` is the optional body content stream with `none` - /// representing a zero-length content stream. - /// Once it is closed, `trailers` future must resolve to a result. - /// If `trailers` resolves to an error, underlying connection - /// will be closed immediately. - /// - /// The returned future resolves to result of transmission of this response. - new: static func( - headers: headers, - contents: option>, - trailers: future, error-code>>, - ) -> tuple>>; - - /// Get the HTTP Status Code for the Response. - get-status-code: func() -> status-code; - - /// Set the HTTP Status Code for the Response. Fails if the status-code - /// given is not a valid http status code. - set-status-code: func(status-code: status-code) -> result; - - /// Get the headers associated with the Response. - /// - /// The returned `headers` resource is immutable: `set`, `append`, and - /// `delete` operations will fail with `header-error.immutable`. - get-headers: func() -> headers; - - /// Get body of the Response. - /// - /// Stream returned by this method represents the contents of the body. - /// Once the stream is reported as closed, callers should await the returned - /// future to determine whether the body was received successfully. - /// The future will only resolve after the stream is reported as closed. - /// - /// This function takes a `res` future as a parameter, which can be used to - /// communicate an error in handling of the response. - /// - /// Note that function will move the `response`, but references to headers - /// acquired from it previously will remain valid. - consume-body: static func(this: response, res: future>) -> tuple, future, error-code>>>; - } -} diff --git a/proposals/http/wit/deps.lock b/proposals/http/wit/deps.lock index 6a8937333..458587826 100644 --- a/proposals/http/wit/deps.lock +++ b/proposals/http/wit/deps.lock @@ -1,27 +1,22 @@ [cli] path = "../../cli/wit" -sha256 = "c312a448b90753dbcf351472ac1130268b763a0c6d3a0f11678e69784638bbb7" -sha512 = "14160242035fd2afcef3ec7a9bd4601e6125639740b6540453702aea371e700fc46a2c0b83a62a78750acb186f4fcd5084019b1a100a37afa590596981192ad4" +sha256 = "d9f51b8ac7fb9612ff406783658a254c7873a9ebbcfb790cfd6df74c1ef8b385" +sha512 = "38f0f890ca7d95a652d4004bb9b0b870fb883f4b90e219e155a853f1ab1f7f13b1d2331db1c986b28747df5a084dd3a0ae7a9f3067ca92167bfb3c34b5adc56b" deps = ["filesystem", "random", "sockets"] [clocks] path = "../../clocks/wit" -sha256 = "85b95504b5f627086433c75a634ef86cc5a346f000acd158b94cb01d508b1992" -sha512 = "b2ba12c17a022788a9ed0d1a11bd605c579ab9614edd6ba02ba6ae59e4265ed02dff718b374181be4fc7c60e0e44d0ef65ab9ddda559f2b75ccc5ca2bb6d7b9f" +sha256 = "2d288cb781c60ae462537b39e4699de38f88072b501fc7f97d3f20984d550bcf" +sha512 = "1563eeeacbfea89e44f668b8588ef95b31feac7d9ec3bb5dad932320478b1aff1448031f44afa15ed926981855ac5bd504126389ddb7802f79c63b81b3c5ede7" [filesystem] -sha256 = "1833958cf47f63ea6ff67cc5ff82ac64069d794007d7c69ce493febce5309962" -sha512 = "be1ba82a942f15bcde1834f8d4889ea65879d4ec69ec474937ed7740ea805aa21eb8aabf145d8d7f1110e9b286e339530ee468e947942f6da1586abbae888a72" - -[io] -path = "../../io/wit" -sha256 = "b45dcb3986b694bd2de3b4c092ee3cc3b0e7c654a93e5dee0c5b32e349d1b0d8" -sha512 = "08ab049d3887d12bd5ae650703b325fd5d26a340e7e6f53c77c5ecfefa79d3b9c61801b6eb00872ecd91f74572ef5684b0850721c715b4062158e00fae6c1dc2" +sha256 = "2c804c867e34eabd75171119f062a49a1b9758d1ec1956535e467b7353e61dd3" +sha512 = "db25d5306dc671c7a7db6a273318d056d6e544567636b3759db48ab4e81a06bc5c1fc3aa2d1522d4187a116730b1a8ecc57a4f974925fda6deaaf06d237da6df" [random] -sha256 = "11a4642d55267644bd11f302661c044f6cb1c43a6aea5c4f919fdc1e49840551" -sha512 = "dc1d74031ee032388ad410d82daae9b2dd052624f7b542ac2912ffec647fb507fb534b4506b337a8f993faf6aefecc57795537b63c41cdd927efd745ffb60cbc" +sha256 = "607700294fdbd7de5c4771628db8830b05ae53c48e66c7645feae98f298a5feb" +sha512 = "a059c887a04b2927df93b8eb83e0843d9ab804e31dee060bf83b74fa6fdd24fbafbb7f9cfcbfa7838cbf6c7e684de8fd4c0b338f3006db1077dd338bf01445ce" [sockets] -sha256 = "2ee88acd6247b6dc8ebeddab95f43ab8a7b587c58b211e6d8022c3b8ac9ff984" -sha512 = "5dfbdf4a5548b16e9303da4ea4e0493ace30060fc67422e894f5f9da70c7c219ec848829518b6dd445675f795763a1ee4ca04fc65fc63210d75739e4850a5dd8" +sha256 = "663af53b8a4e6aa66fa24618c5d0d6dd4bfaa970121a85951e8ab52cea0b0852" +sha512 = "4faf0eb9e8f486d3dadddc7f491f87ca6b1626f0296e8e918c529f39696f61398e4c37d0dfa6529a157f65747bbd455487fe0b6bb04e075d65a8d75844225e2a" diff --git a/proposals/http/wit/deps.toml b/proposals/http/wit/deps.toml index e594435ef..22b57f7b4 100644 --- a/proposals/http/wit/deps.toml +++ b/proposals/http/wit/deps.toml @@ -1,3 +1,2 @@ cli = "../../cli/wit" clocks = "../../clocks/wit" -io = "../../io/wit" diff --git a/proposals/http/wit/handler.wit b/proposals/http/wit/handler.wit deleted file mode 100644 index 6a6c62966..000000000 --- a/proposals/http/wit/handler.wit +++ /dev/null @@ -1,49 +0,0 @@ -/// This interface defines a handler of incoming HTTP Requests. It should -/// be exported by components which can respond to HTTP Requests. -@since(version = 0.2.0) -interface incoming-handler { - @since(version = 0.2.0) - use types.{incoming-request, response-outparam}; - - /// This function is invoked with an incoming HTTP Request, and a resource - /// `response-outparam` which provides the capability to reply with an HTTP - /// Response. The response is sent by calling the `response-outparam.set` - /// method, which allows execution to continue after the response has been - /// sent. This enables both streaming to the response body, and performing other - /// work. - /// - /// The implementor of this function must write a response to the - /// `response-outparam` before returning, or else the caller will respond - /// with an error on its behalf. - @since(version = 0.2.0) - handle: func( - request: incoming-request, - response-out: response-outparam - ); -} - -/// This interface defines a handler of outgoing HTTP Requests. It should be -/// imported by components which wish to make HTTP Requests. -@since(version = 0.2.0) -interface outgoing-handler { - @since(version = 0.2.0) - use types.{ - outgoing-request, request-options, future-incoming-response, error-code - }; - - /// This function is invoked with an outgoing HTTP Request, and it returns - /// a resource `future-incoming-response` which represents an HTTP Response - /// which may arrive in the future. - /// - /// The `options` argument accepts optional parameters for the HTTP - /// protocol's transport layer. - /// - /// This function may return an error if the `outgoing-request` is invalid - /// or not allowed to be made. Otherwise, protocol errors are reported - /// through the `future-incoming-response`. - @since(version = 0.2.0) - handle: func( - request: outgoing-request, - options: option - ) -> result; -} diff --git a/proposals/http/wit/proxy.wit b/proposals/http/wit/proxy.wit deleted file mode 100644 index 60b745ab5..000000000 --- a/proposals/http/wit/proxy.wit +++ /dev/null @@ -1,50 +0,0 @@ -package wasi:http@0.2.12; - -/// The `wasi:http/imports` world imports all the APIs for HTTP proxies. -/// It is intended to be `include`d in other worlds. -@since(version = 0.2.0) -world imports { - /// HTTP proxies have access to time and randomness. - @since(version = 0.2.0) - import wasi:clocks/monotonic-clock@0.2.12; - @since(version = 0.2.0) - import wasi:clocks/wall-clock@0.2.12; - @since(version = 0.2.0) - import wasi:random/random@0.2.12; - - /// Proxies have standard output and error streams which are expected to - /// terminate in a developer-facing console provided by the host. - @since(version = 0.2.0) - import wasi:cli/stdout@0.2.12; - @since(version = 0.2.0) - import wasi:cli/stderr@0.2.12; - - /// TODO: this is a temporary workaround until component tooling is able to - /// gracefully handle the absence of stdin. Hosts must return an eof stream - /// for this import, which is what wasi-libc + tooling will do automatically - /// when this import is properly removed. - @since(version = 0.2.0) - import wasi:cli/stdin@0.2.12; - - /// This is the default handler to use when user code simply wants to make an - /// HTTP request (e.g., via `fetch()`). - @since(version = 0.2.0) - import outgoing-handler; -} - -/// The `wasi:http/proxy` world captures a widely-implementable intersection of -/// hosts that includes HTTP forward and reverse proxies. Components targeting -/// this world may concurrently stream in and out any number of incoming and -/// outgoing HTTP requests. -@since(version = 0.2.0) -world proxy { - @since(version = 0.2.0) - include imports; - - /// The host delivers incoming HTTP requests to a component by calling the - /// `handle` function of this exported interface. A host may arbitrarily reuse - /// or not reuse component instance when delivering incoming HTTP requests and - /// thus a component must be able to handle 0..N calls to `handle`. - @since(version = 0.2.0) - export incoming-handler; -} diff --git a/proposals/http/wit/types.wit b/proposals/http/wit/types.wit index fa7ac221c..87fdfd7c0 100644 --- a/proposals/http/wit/types.wit +++ b/proposals/http/wit/types.wit @@ -1,19 +1,13 @@ -/// This interface defines all of the types and methods for implementing -/// HTTP Requests and Responses, both incoming and outgoing, as well as -/// their headers, trailers, and bodies. -@since(version = 0.2.0) +package wasi:http@0.3.0; + +/// This interface defines all of the types and methods for implementing HTTP +/// Requests and Responses, as well as their headers, trailers, and bodies. +@since(version = 0.3.0) interface types { - @since(version = 0.2.0) - use wasi:clocks/monotonic-clock@0.2.12.{duration}; - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{input-stream, output-stream}; - @since(version = 0.2.0) - use wasi:io/error@0.2.12.{error as io-error}; - @since(version = 0.2.0) - use wasi:io/poll@0.2.12.{pollable}; + use wasi:clocks/types@0.3.0.{duration}; /// This type corresponds to HTTP standard Methods. - @since(version = 0.2.0) + @since(version = 0.3.0) variant method { get, head, @@ -28,7 +22,7 @@ interface types { } /// This type corresponds to HTTP standard Related Schemes. - @since(version = 0.2.0) + @since(version = 0.3.0) variant scheme { HTTP, HTTPS, @@ -37,7 +31,7 @@ interface types { /// These cases are inspired by the IANA HTTP Proxy Error Types: /// - @since(version = 0.2.0) + @since(version = 0.3.0) variant error-code { DNS-timeout, DNS-error(DNS-error-payload), @@ -86,43 +80,29 @@ interface types { } /// Defines the case payload type for `DNS-error` above: - @since(version = 0.2.0) + @since(version = 0.3.0) record DNS-error-payload { rcode: option, info-code: option } /// Defines the case payload type for `TLS-alert-received` above: - @since(version = 0.2.0) + @since(version = 0.3.0) record TLS-alert-received-payload { alert-id: option, alert-message: option } /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: - @since(version = 0.2.0) + @since(version = 0.3.0) record field-size-payload { field-name: option, field-size: option } - /// Attempts to extract a http-related `error` from the wasi:io `error` - /// provided. - /// - /// Stream operations which return - /// `wasi:io/stream.stream-error.last-operation-failed` have a payload of - /// type `wasi:io/error.error` with more information about the operation - /// that failed. This payload can be passed through to this function to see - /// if there's http-related information about the error to return. - /// - /// Note that this function is fallible because not all io-errors are - /// http-related errors. - @since(version = 0.2.0) - http-error-code: func(err: borrow) -> option; - /// This type enumerates the different kinds of errors that may occur when /// setting or appending to a `fields` resource. - @since(version = 0.2.0) + @since(version = 0.3.0) variant header-error { /// This error indicates that a `field-name` or `field-value` was /// syntactically invalid when used with an operation that sets headers in a @@ -136,31 +116,53 @@ interface types { /// This error indicates that the operation on the `fields` was not /// permitted because the fields are immutable. immutable, + + /// This error indicates that the operation would exceed an + /// implementation-defined limit on field sizes. This may apply to + /// an individual `field-value`, a single `field-name` plus all its + /// values, or the total aggregate size of all fields. + size-exceeded, + + /// This is a catch-all error for anything that doesn't fit cleanly into a + /// more specific case. Implementations can use this to extend the error + /// type without breaking existing code. It also includes an optional + /// string for an unstructured description of the error. Users should not + /// depend on the string for diagnosing errors, as it's not required to be + /// consistent between implementations. + other(option), + } + + /// This type enumerates the different kinds of errors that may occur when + /// setting fields of a `request-options` resource. + @since(version = 0.3.0) + variant request-options-error { + /// Indicates the specified field is not supported by this implementation. + not-supported, + + /// Indicates that the operation on the `request-options` was not permitted + /// because it is immutable. + immutable, + + /// This is a catch-all error for anything that doesn't fit cleanly into a + /// more specific case. Implementations can use this to extend the error + /// type without breaking existing code. It also includes an optional + /// string for an unstructured description of the error. Users should not + /// depend on the string for diagnosing errors, as it's not required to be + /// consistent between implementations. + other(option), } /// Field names are always strings. /// /// Field names should always be treated as case insensitive by the `fields` /// resource for the purposes of equality checking. - @since(version = 0.2.1) - type field-name = field-key; - - /// Field keys are always strings. - /// - /// Field keys should always be treated as case insensitive by the `fields` - /// resource for the purposes of equality checking. - /// - /// # Deprecation - /// - /// This type has been deprecated in favor of the `field-name` type. - @since(version = 0.2.0) - @deprecated(version = 0.2.2) - type field-key = string; + @since(version = 0.3.0) + type field-name = string; /// Field values should always be ASCII strings. However, in /// reality, HTTP implementations often have to interpret malformed values, /// so they are provided as a list of bytes. - @since(version = 0.2.0) + @since(version = 0.3.0) type field-value = list; /// This following block defines the `fields` resource which corresponds to @@ -170,16 +172,24 @@ interface types { /// A `fields` may be mutable or immutable. A `fields` created using the /// constructor, `from-list`, or `clone` will be mutable, but a `fields` /// resource given by other means (including, but not limited to, - /// `incoming-request.headers`, `outgoing-request.headers`) might be - /// immutable. In an immutable fields, the `set`, `append`, and `delete` - /// operations will fail with `header-error.immutable`. - @since(version = 0.2.0) + /// `request.headers`) might be be immutable. In an immutable fields, the + /// `set`, `append`, and `delete` operations will fail with + /// `header-error.immutable`. + /// + /// A `fields` resource should store `field-name`s and `field-value`s in their + /// original casing used to construct or mutate the `fields` resource. The `fields` + /// resource should use that original casing when serializing the fields for + /// transport or when returning them from a method. + /// + /// Implementations may impose limits on individual field values and on total + /// aggregate field section size. Operations that would exceed these limits + /// fail with `header-error.size-exceeded` + @since(version = 0.3.0) resource fields { /// Construct an empty HTTP Fields. /// /// The resulting `fields` is mutable. - @since(version = 0.2.0) constructor(); /// Construct an HTTP Fields. @@ -191,25 +201,25 @@ interface types { /// list with the same name. /// /// The tuple is a pair of the field name, represented as a string, and - /// Value, represented as a list of bytes. + /// Value, represented as a list of bytes. In a valid Fields, all names + /// and values are valid UTF-8 strings. However, values are not always + /// well-formed, so they are represented as a raw list of bytes. /// - /// An error result will be returned if any `field-name` or `field-value` is - /// syntactically invalid, or if a field is forbidden. - @since(version = 0.2.0) + /// An error result will be returned if any header or value was + /// syntactically invalid, if a header was forbidden, or if the + /// entries would exceed an implementation size limit. from-list: static func( entries: list> ) -> result; /// Get all of the values corresponding to a name. If the name is not present - /// in this `fields` or is syntactically invalid, an empty list is returned. - /// However, if the name is present but empty, this is represented by a list - /// with one or more empty field-values present. - @since(version = 0.2.0) + /// in this `fields`, an empty list is returned. However, if the name is + /// present but empty, this is represented by a list with one or more + /// empty field-values present. get: func(name: field-name) -> list; /// Returns `true` when the name is present in this `fields`. If the name is /// syntactically invalid, `false` is returned. - @since(version = 0.2.0) has: func(name: field-name) -> bool; /// Set all of the values for a name. Clears any existing values for that @@ -217,29 +227,31 @@ interface types { /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// - /// Fails with `header-error.invalid-syntax` if the `field-name` or any of - /// the `field-value`s are syntactically invalid. - @since(version = 0.2.0) + /// Fails with `header-error.size-exceeded` if the name or values would + /// exceed an implementation-defined size limit. set: func(name: field-name, value: list) -> result<_, header-error>; /// Delete all values for a name. Does nothing if no values for the name /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. - /// - /// Fails with `header-error.invalid-syntax` if the `field-name` is - /// syntactically invalid. - @since(version = 0.2.0) delete: func(name: field-name) -> result<_, header-error>; + /// Delete all values for a name. Does nothing if no values for the name + /// exist. + /// + /// Returns all values previously corresponding to the name, if any. + /// + /// Fails with `header-error.immutable` if the `fields` are immutable. + get-and-delete: func(name: field-name) -> result, header-error>; + /// Append a value for a name. Does not change or delete any existing /// values for that name. /// /// Fails with `header-error.immutable` if the `fields` are immutable. /// - /// Fails with `header-error.invalid-syntax` if the `field-name` or - /// `field-value` are syntactically invalid. - @since(version = 0.2.0) + /// Fails with `header-error.size-exceeded` if the value would exceed + /// an implementation-defined size limit. append: func(name: field-name, value: field-value) -> result<_, header-error>; /// Retrieve the full set of names and values in the Fields. Like the @@ -251,438 +263,210 @@ interface types { /// /// The names and values are always returned in the original casing and in /// the order in which they will be serialized for transport. - @since(version = 0.2.0) - entries: func() -> list>; + copy-all: func() -> list>; /// Make a deep copy of the Fields. Equivalent in behavior to calling the - /// `fields` constructor on the return value of `entries`. The resulting + /// `fields` constructor on the return value of `copy-all`. The resulting /// `fields` is mutable. - @since(version = 0.2.0) clone: func() -> fields; } /// Headers is an alias for Fields. - @since(version = 0.2.0) + @since(version = 0.3.0) type headers = fields; /// Trailers is an alias for Fields. - @since(version = 0.2.0) + @since(version = 0.3.0) type trailers = fields; - /// Represents an incoming HTTP Request. - @since(version = 0.2.0) - resource incoming-request { - - /// Returns the method of the incoming request. - @since(version = 0.2.0) - method: func() -> method; - - /// Returns the path with query parameters from the request, as a string. - @since(version = 0.2.0) - path-with-query: func() -> option; - - /// Returns the protocol scheme from the request. - @since(version = 0.2.0) - scheme: func() -> option; + /// Represents an HTTP Request. + @since(version = 0.3.0) + resource request { - /// Returns the authority of the Request's target URI, if present. - @since(version = 0.2.0) - authority: func() -> option; - - /// Get the `headers` associated with the request. + /// Construct a new `request` with a default `method` of `GET`, and + /// `none` values for `path-with-query`, `scheme`, and `authority`. /// - /// The returned `headers` resource is immutable: `set`, `append`, and - /// `delete` operations will fail with `header-error.immutable`. + /// `headers` is the HTTP Headers for the Request. /// - /// The `headers` returned are a child resource: it must be dropped before - /// the parent `incoming-request` is dropped. Dropping this - /// `incoming-request` before all children are dropped will trap. - @since(version = 0.2.0) - headers: func() -> headers; - - /// Gives the `incoming-body` associated with this request. Will only - /// return success at most once, and subsequent calls will return error. - @since(version = 0.2.0) - consume: func() -> result; - } - - /// Represents an outgoing HTTP Request. - @since(version = 0.2.0) - resource outgoing-request { - - /// Construct a new `outgoing-request` with a default `method` of `GET`, and - /// `none` values for `path-with-query`, `scheme`, and `authority`. + /// `contents` is the optional body content stream with `none` + /// representing a zero-length content stream. + /// Once it is closed, `trailers` future must resolve to a result. + /// If `trailers` resolves to an error, underlying connection + /// will be closed immediately. /// - /// * `headers` is the HTTP Headers for the Request. + /// `options` is optional `request-options` resource to be used + /// if the request is sent over a network connection. /// /// It is possible to construct, or manipulate with the accessor functions - /// below, an `outgoing-request` with an invalid combination of `scheme` + /// below, a `request` with an invalid combination of `scheme` /// and `authority`, or `headers` which are not permitted to be sent. - /// It is the obligation of the `outgoing-handler.handle` implementation - /// to reject invalid constructions of `outgoing-request`. - @since(version = 0.2.0) - constructor( - headers: headers - ); - - /// Returns the resource corresponding to the outgoing Body for this - /// Request. - /// - /// Returns success on the first call: the `outgoing-body` resource for - /// this `outgoing-request` can be retrieved at most once. Subsequent - /// calls will return error. - @since(version = 0.2.0) - body: func() -> result; + /// It is the obligation of the `handler.handle` implementation + /// to reject invalid constructions of `request`. + /// + /// The returned future resolves to result of transmission of this request. + new: static func( + headers: headers, + contents: option>, + trailers: future, error-code>>, + options: option + ) -> tuple>>; /// Get the Method for the Request. - @since(version = 0.2.0) - method: func() -> method; + get-method: func() -> method; /// Set the Method for the Request. Fails if the string present in a /// `method.other` argument is not a syntactically valid method. - @since(version = 0.2.0) set-method: func(method: method) -> result; - /// Get the combination of the HTTP Path and Query for the Request. - /// When `none`, this represents an empty Path and empty Query. - @since(version = 0.2.0) - path-with-query: func() -> option; - /// Set the combination of the HTTP Path and Query for the Request. - /// When `none`, this represents an empty Path and empty Query. Fails is the + /// Get the combination of the HTTP Path and Query for the Request. When + /// `none`, this represents an empty Path and empty Query. + get-path-with-query: func() -> option; + /// Set the combination of the HTTP Path and Query for the Request. When + /// `none`, this represents an empty Path and empty Query. Fails is the /// string given is not a syntactically valid path and query uri component. - @since(version = 0.2.0) set-path-with-query: func(path-with-query: option) -> result; /// Get the HTTP Related Scheme for the Request. When `none`, the /// implementation may choose an appropriate default scheme. - @since(version = 0.2.0) - scheme: func() -> option; + get-scheme: func() -> option; /// Set the HTTP Related Scheme for the Request. When `none`, the /// implementation may choose an appropriate default scheme. Fails if the /// string given is not a syntactically valid uri scheme. - @since(version = 0.2.0) set-scheme: func(scheme: option) -> result; /// Get the authority of the Request's target URI. A value of `none` may be used /// with Related Schemes which do not require an authority. The HTTP and /// HTTPS schemes always require an authority. - @since(version = 0.2.0) - authority: func() -> option; + get-authority: func() -> option; /// Set the authority of the Request's target URI. A value of `none` may be used /// with Related Schemes which do not require an authority. The HTTP and /// HTTPS schemes always require an authority. Fails if the string given is /// not a syntactically valid URI authority. - @since(version = 0.2.0) set-authority: func(authority: option) -> result; + /// Get the `request-options` to be associated with this request + /// + /// The returned `request-options` resource is immutable: `set-*` operations + /// will fail if invoked. + /// + /// This `request-options` resource is a child: it must be dropped before + /// the parent `request` is dropped, or its ownership is transferred to + /// another component by e.g. `handler.handle`. + get-options: func() -> option; + /// Get the headers associated with the Request. /// /// The returned `headers` resource is immutable: `set`, `append`, and /// `delete` operations will fail with `header-error.immutable`. + get-headers: func() -> headers; + + /// Get body of the Request. /// - /// This headers resource is a child: it must be dropped before the parent - /// `outgoing-request` is dropped, or its ownership is transferred to - /// another component by e.g. `outgoing-handler.handle`. - @since(version = 0.2.0) - headers: func() -> headers; + /// Stream returned by this method represents the contents of the body. + /// Once the stream is reported as closed, callers should await the returned + /// future to determine whether the body was received successfully. + /// The future will only resolve after the stream is reported as closed. + /// + /// This function takes a `res` future as a parameter, which can be used to + /// communicate an error in handling of the request. + /// + /// Note that function will move the `request`, but references to headers or + /// request options acquired from it previously will remain valid. + consume-body: static func(this: request, res: future>) -> tuple, future, error-code>>>; } /// Parameters for making an HTTP Request. Each of these parameters is /// currently an optional timeout applicable to the transport layer of the /// HTTP protocol. /// - /// These timeouts are separate from any the user may use to bound a - /// blocking call to `wasi:io/poll.poll`. - @since(version = 0.2.0) + /// These timeouts are separate from any the user may use to bound an + /// asynchronous call. + @since(version = 0.3.0) resource request-options { /// Construct a default `request-options` value. - @since(version = 0.2.0) constructor(); /// The timeout for the initial connect to the HTTP Server. - @since(version = 0.2.0) - connect-timeout: func() -> option; + get-connect-timeout: func() -> option; /// Set the timeout for the initial connect to the HTTP Server. An error - /// return value indicates that this timeout is not supported. - @since(version = 0.2.0) - set-connect-timeout: func(duration: option) -> result; + /// return value indicates that this timeout is not supported or that this + /// handle is immutable. + set-connect-timeout: func(duration: option) -> result<_, request-options-error>; /// The timeout for receiving the first byte of the Response body. - @since(version = 0.2.0) - first-byte-timeout: func() -> option; + get-first-byte-timeout: func() -> option; /// Set the timeout for receiving the first byte of the Response body. An - /// error return value indicates that this timeout is not supported. - @since(version = 0.2.0) - set-first-byte-timeout: func(duration: option) -> result; + /// error return value indicates that this timeout is not supported or that + /// this handle is immutable. + set-first-byte-timeout: func(duration: option) -> result<_, request-options-error>; /// The timeout for receiving subsequent chunks of bytes in the Response /// body stream. - @since(version = 0.2.0) - between-bytes-timeout: func() -> option; + get-between-bytes-timeout: func() -> option; /// Set the timeout for receiving subsequent chunks of bytes in the Response /// body stream. An error return value indicates that this timeout is not - /// supported. - @since(version = 0.2.0) - set-between-bytes-timeout: func(duration: option) -> result; - } + /// supported or that this handle is immutable. + set-between-bytes-timeout: func(duration: option) -> result<_, request-options-error>; - /// Represents the ability to send an HTTP Response. - /// - /// This resource is used by the `wasi:http/incoming-handler` interface to - /// allow a Response to be sent corresponding to the Request provided as the - /// other argument to `incoming-handler.handle`. - @since(version = 0.2.0) - resource response-outparam { - /// Send an HTTP 1xx response. - /// - /// Unlike `response-outparam.set`, this does not consume the - /// `response-outparam`, allowing the guest to send an arbitrary number of - /// informational responses before sending the final response using - /// `response-outparam.set`. - /// - /// This will return an `HTTP-protocol-error` if `status` is not in the - /// range [100-199], or an `internal-error` if the implementation does not - /// support informational responses. - @unstable(feature = informational-outbound-responses) - send-informational: func( - status: u16, - headers: headers - ) -> result<_, error-code>; - - /// Set the value of the `response-outparam` to either send a response, - /// or indicate an error. - /// - /// This method consumes the `response-outparam` to ensure that it is - /// called at most once. If it is never called, the implementation - /// will respond with an error. - /// - /// The user may provide an `error` to `response` to allow the - /// implementation determine how to respond with an HTTP error response. - @since(version = 0.2.0) - set: static func( - param: response-outparam, - response: result, - ); + /// Make a deep copy of the `request-options`. + /// The resulting `request-options` is mutable. + clone: func() -> request-options; } /// This type corresponds to the HTTP standard Status Code. - @since(version = 0.2.0) + @since(version = 0.3.0) type status-code = u16; - /// Represents an incoming HTTP Response. - @since(version = 0.2.0) - resource incoming-response { - - /// Returns the status code from the incoming response. - @since(version = 0.2.0) - status: func() -> status-code; + /// Represents an HTTP Response. + @since(version = 0.3.0) + resource response { - /// Returns the headers from the incoming response. - /// - /// The returned `headers` resource is immutable: `set`, `append`, and - /// `delete` operations will fail with `header-error.immutable`. - /// - /// This headers resource is a child: it must be dropped before the parent - /// `incoming-response` is dropped. - @since(version = 0.2.0) - headers: func() -> headers; - - /// Returns the incoming body. May be called at most once. Returns error - /// if called additional times. - @since(version = 0.2.0) - consume: func() -> result; - } - - /// Represents an incoming HTTP Request or Response's Body. - /// - /// A body has both its contents - a stream of bytes - and a (possibly - /// empty) set of trailers, indicating that the full contents of the - /// body have been received. This resource represents the contents as - /// an `input-stream` and the delivery of trailers as a `future-trailers`, - /// and ensures that the user of this interface may only be consuming either - /// the body contents or waiting on trailers at any given time. - @since(version = 0.2.0) - resource incoming-body { - - /// Returns the contents of the body, as a stream of bytes. - /// - /// Returns success on first call: the stream representing the contents - /// can be retrieved at most once. Subsequent calls will return error. - /// - /// The returned `input-stream` resource is a child: it must be dropped - /// before the parent `incoming-body` is dropped, or consumed by - /// `incoming-body.finish`. - /// - /// This invariant ensures that the implementation can determine whether - /// the user is consuming the contents of the body, waiting on the - /// `future-trailers` to be ready, or neither. This allows for network - /// backpressure is to be applied when the user is consuming the body, - /// and for that backpressure to not inhibit delivery of the trailers if - /// the user does not read the entire body. - @since(version = 0.2.0) - %stream: func() -> result; - - /// Takes ownership of `incoming-body`, and returns a `future-trailers`. - /// This function will trap if the `input-stream` child is still alive. - @since(version = 0.2.0) - finish: static func(this: incoming-body) -> future-trailers; - } - - /// Represents a future which may eventually return trailers, or an error. - /// - /// In the case that the incoming HTTP Request or Response did not have any - /// trailers, this future will resolve to the empty set of trailers once the - /// complete Request or Response body has been received. - @since(version = 0.2.0) - resource future-trailers { - - /// Returns a pollable which becomes ready when either the trailers have - /// been received, or an error has occurred. When this pollable is ready, - /// the `get` method will return `some`. - @since(version = 0.2.0) - subscribe: func() -> pollable; - - /// Returns the contents of the trailers, or an error which occurred, - /// once the future is ready. - /// - /// The outer `option` represents future readiness. Users can wait on this - /// `option` to become `some` using the `subscribe` method. - /// - /// The outer `result` is used to retrieve the trailers or error at most - /// once. It will be success on the first call in which the outer option - /// is `some`, and error on subsequent calls. - /// - /// The inner `result` represents that either the HTTP Request or Response - /// body, as well as any trailers, were received successfully, or that an - /// error occurred receiving them. The optional `trailers` indicates whether - /// or not trailers were present in the body. - /// - /// When some `trailers` are returned by this method, the `trailers` - /// resource is immutable, and a child. Use of the `set`, `append`, or - /// `delete` methods will return an error, and the resource must be - /// dropped before the parent `future-trailers` is dropped. - @since(version = 0.2.0) - get: func() -> option, error-code>>>; - } - - /// Represents an outgoing HTTP Response. - @since(version = 0.2.0) - resource outgoing-response { - - /// Construct an `outgoing-response`, with a default `status-code` of `200`. + /// Construct a new `response`, with a default `status-code` of `200`. /// If a different `status-code` is needed, it must be set via the /// `set-status-code` method. /// - /// * `headers` is the HTTP Headers for the Response. - @since(version = 0.2.0) - constructor(headers: headers); + /// `headers` is the HTTP Headers for the Response. + /// + /// `contents` is the optional body content stream with `none` + /// representing a zero-length content stream. + /// Once it is closed, `trailers` future must resolve to a result. + /// If `trailers` resolves to an error, underlying connection + /// will be closed immediately. + /// + /// The returned future resolves to result of transmission of this response. + new: static func( + headers: headers, + contents: option>, + trailers: future, error-code>>, + ) -> tuple>>; /// Get the HTTP Status Code for the Response. - @since(version = 0.2.0) - status-code: func() -> status-code; + get-status-code: func() -> status-code; /// Set the HTTP Status Code for the Response. Fails if the status-code /// given is not a valid http status code. - @since(version = 0.2.0) set-status-code: func(status-code: status-code) -> result; - /// Get the headers associated with the Request. + /// Get the headers associated with the Response. /// /// The returned `headers` resource is immutable: `set`, `append`, and /// `delete` operations will fail with `header-error.immutable`. - /// - /// This headers resource is a child: it must be dropped before the parent - /// `outgoing-request` is dropped, or its ownership is transferred to - /// another component by e.g. `outgoing-handler.handle`. - @since(version = 0.2.0) - headers: func() -> headers; + get-headers: func() -> headers; - /// Returns the resource corresponding to the outgoing Body for this Response. + /// Get body of the Response. /// - /// Returns success on the first call: the `outgoing-body` resource for - /// this `outgoing-response` can be retrieved at most once. Subsequent - /// calls will return error. - @since(version = 0.2.0) - body: func() -> result; - } - - /// Represents an outgoing HTTP Request or Response's Body. - /// - /// A body has both its contents - a stream of bytes - and a (possibly - /// empty) set of trailers, inducating the full contents of the body - /// have been sent. This resource represents the contents as an - /// `output-stream` child resource, and the completion of the body (with - /// optional trailers) with a static function that consumes the - /// `outgoing-body` resource, and ensures that the user of this interface - /// may not write to the body contents after the body has been finished. - /// - /// If the user code drops this resource, as opposed to calling the static - /// method `finish`, the implementation should treat the body as incomplete, - /// and that an error has occurred. The implementation should propagate this - /// error to the HTTP protocol by whatever means it has available, - /// including: corrupting the body on the wire, aborting the associated - /// Request, or sending a late status code for the Response. - @since(version = 0.2.0) - resource outgoing-body { - - /// Returns a stream for writing the body contents. - /// - /// The returned `output-stream` is a child resource: it must be dropped - /// before the parent `outgoing-body` resource is dropped (or finished), - /// otherwise the `outgoing-body` drop or `finish` will trap. - /// - /// Returns success on the first call: the `output-stream` resource for - /// this `outgoing-body` may be retrieved at most once. Subsequent calls - /// will return error. - @since(version = 0.2.0) - write: func() -> result; - - /// Finalize an outgoing body, optionally providing trailers. This must be - /// called to signal that the response is complete. If the `outgoing-body` - /// is dropped without calling `outgoing-body.finalize`, the implementation - /// should treat the body as corrupted. - /// - /// Fails if the body's `outgoing-request` or `outgoing-response` was - /// constructed with a Content-Length header, and the contents written - /// to the body (via `write`) does not match the value given in the - /// Content-Length. - @since(version = 0.2.0) - finish: static func( - this: outgoing-body, - trailers: option - ) -> result<_, error-code>; - } - - /// Represents a future which may eventually return an incoming HTTP - /// Response, or an error. - /// - /// This resource is returned by the `wasi:http/outgoing-handler` interface to - /// provide the HTTP Response corresponding to the sent Request. - @since(version = 0.2.0) - resource future-incoming-response { - /// Returns a pollable which becomes ready when either the Response has - /// been received, or an error has occurred. When this pollable is ready, - /// the `get` method will return `some`. - @since(version = 0.2.0) - subscribe: func() -> pollable; - - /// Returns the incoming HTTP Response, or an error, once one is ready. - /// - /// The outer `option` represents future readiness. Users can wait on this - /// `option` to become `some` using the `subscribe` method. - /// - /// The outer `result` is used to retrieve the response or error at most - /// once. It will be success on the first call in which the outer option - /// is `some`, and error on subsequent calls. - /// - /// The inner `result` represents that either the incoming HTTP Response - /// status and headers have received successfully, or that an error - /// occurred. Errors may also occur while consuming the response body, - /// but those will be reported by the `incoming-body` and its - /// `output-stream` child. - @since(version = 0.2.0) - get: func() -> option>>; + /// Stream returned by this method represents the contents of the body. + /// Once the stream is reported as closed, callers should await the returned + /// future to determine whether the body was received successfully. + /// The future will only resolve after the stream is reported as closed. + /// + /// This function takes a `res` future as a parameter, which can be used to + /// communicate an error in handling of the response. + /// + /// Note that function will move the `response`, but references to headers + /// acquired from it previously will remain valid. + consume-body: static func(this: response, res: future>) -> tuple, future, error-code>>>; } } diff --git a/proposals/http/wit-0.3.0-draft/worlds.wit b/proposals/http/wit/worlds.wit similarity index 92% rename from proposals/http/wit-0.3.0-draft/worlds.wit rename to proposals/http/wit/worlds.wit index a7006e717..a6492947e 100644 --- a/proposals/http/wit-0.3.0-draft/worlds.wit +++ b/proposals/http/wit/worlds.wit @@ -1,24 +1,24 @@ -package wasi:http@0.3.0-rc-2026-03-15; +package wasi:http@0.3.0; /// The `wasi:http/service` world captures a broad category of HTTP services /// including web applications, API servers, and proxies. It may be `include`d /// in more specific worlds such as `wasi:http/middleware`. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) world service { /// HTTP services have access to time and randomness. - include wasi:clocks/imports@0.3.0-rc-2026-03-15; - include wasi:random/imports@0.3.0-rc-2026-03-15; + include wasi:clocks/imports@0.3.0; + include wasi:random/imports@0.3.0; /// Services have standard output and error streams which are expected to /// terminate in a developer-facing console provided by the host. - import wasi:cli/stdout@0.3.0-rc-2026-03-15; - import wasi:cli/stderr@0.3.0-rc-2026-03-15; + import wasi:cli/stdout@0.3.0; + import wasi:cli/stderr@0.3.0; /// TODO: this is a temporary workaround until component tooling is able to /// gracefully handle the absence of stdin. Hosts must return an eof stream /// for this import, which is what wasi-libc + tooling will do automatically /// when this import is properly removed. - import wasi:cli/stdin@0.3.0-rc-2026-03-15; + import wasi:cli/stdin@0.3.0; /// This is the default `client` to use when user code simply wants to make an /// HTTP request (e.g., via `fetch()`). @@ -72,7 +72,7 @@ world service { /// Components may implement this world to allow them to participate in handler /// "chains" where a `request` flows through handlers on its way to some terminal /// `service` and corresponding `response` flows in the opposite direction. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) world middleware { include service; import handler; @@ -85,7 +85,7 @@ world middleware { /// /// In `wasi:http/middleware` this interface is both exported and imported as /// the "downstream" and "upstream" directions of the middleware chain. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) interface handler { use types.{request, response, error-code}; @@ -106,7 +106,7 @@ interface handler { /// (including WIT itself) is unable to represent a component importing two /// instances of the same interface. A `client.send` import may be linked /// directly to a `handler.handle` export to bypass the network. -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) interface client { use types.{request, response, error-code}; diff --git a/proposals/io/LICENSE.md b/proposals/io/LICENSE.md deleted file mode 100644 index 475309577..000000000 --- a/proposals/io/LICENSE.md +++ /dev/null @@ -1,8 +0,0 @@ -Copyright © 2019-2023 the Contributors to the WASI Specification, published -by the [WebAssembly Community Group][cg] under the -[W3C Community Contributor License Agreement (CLA)][cla]. A human-readable -[summary][summary] is available. - -[cg]: https://www.w3.org/community/webassembly/ -[cla]: https://www.w3.org/community/about/agreements/cla/ -[summary]: https://www.w3.org/community/about/agreements/cla-deed/ diff --git a/proposals/io/README.md b/proposals/io/README.md deleted file mode 100644 index e8143232b..000000000 --- a/proposals/io/README.md +++ /dev/null @@ -1,157 +0,0 @@ -# WASI I/O - -A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API. - -### Current Phase - -WASI I/O 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 I/O must have host implementations which can pass the testsuite on at least Windows, macOS, and Linux. - -WASI I/O 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: copying from input to output using `read`/`write`](#use-case-copying-from-input-to-output-using-readwrite) - - [Use case: copying from input to output using `splice`](#use-case-copying-from-input-to-output-using-splice) - - [Use case: copying from input to output using `forward`](#use-case-copying-from-input-to-output-using-forward) -- [Detailed design discussion](#detailed-design-discussion) - - [Should we have support for non-blocking read/write?](#should-we-have-support-for-non-blocking-read-write) - - [Why do read/write use u64 sizes?[Tricky design choice 2]](#why-do-read-write-use-u64-sizes) - - [Why have a `forward` function when you can just `splice` in a loop?](#why-have-a-forward-function-when-you-can-just-splice-in-a-loop) -- [Stakeholder Interest & Feedback](#stakeholder-interest--feedback) -- [References & acknowledgements](#references--acknowledgements) - -### Introduction - -Wasi I/O is an API providing I/O stream abstractions. There are two -types, `input-stream`, and `output-stream`, which support `read` and -`write`, respectively, as well as a number of utility functions. - -### Goals - - - Be usable by wasi-libc to implement POSIX-like file and socket APIs. - - Support many different kinds of host streams, including files, sockets, - pipes, character devices, and more. - -### Non-goals - - - Support for async. That will be addressed in the component-model async - design, where we can have the benefit of tighter integration with language - bindings. - - Bidirectional streams. - -### API walk-through - -#### Use Case: copying from input to output using `read`/`write` - -```rust - fn copy_data(input: InputStream, output: OutputStream) -> Result<(), StreamError> { - const BUFFER_LEN: usize = 4096; - - let wait_input = [subscribe_to_input_stream(input)]; - let wait_output = [subscribe_to_output_stream(output)]; - - loop { - let (mut data, mut eos) = input.read(BUFFER_LEN)?; - - // If we didn't get any data promptly, wait for it. - if data.len() == 0 { - let _ = poll_list(&wait_input[..]); - (data, eos) = input.read(BUFFER_LEN)?; - } - - let mut remaining = &data[..]; - while !remaining.is_empty() { - let mut num_written = output.write(remaining)?; - - // If we didn't put any data promptly, wait for it. - if num_written == 0 { - let _ = poll_list(&wait_output[..]); - num_written = output.write(remaining)?; - } - - remaining = &remaining[num_written..]; - } - if eos { - break; - } - } - Ok(()) - } -``` - -#### Use case: copying from input to output using `splice` - -```rust - fn copy_data(input: InputStream, output: OutputStream) -> Result<(), StreamError> { - let wait_input = [subscribe_to_input_stream(input)]; - - loop { - let (num_copied, eos) = output.splice(input, u64::MAX)?; - if eos { - break; - } - - // If we didn't get any data promptly, wait for it. - if num_copied == 0 { - let _ = poll_list(&wait_input[..]); - } - } - Ok(()) - } -``` - -#### Use case: copying from input to output using `forward` - -```rust - fn copy_data(input: InputStream, output: OutputStream) -> Result<(), StreamError> { - output.forward(input)?; - Ok(()) - } -``` - -### Detailed design discussion - -#### Should we have support for non-blocking read/write? - -This may be something we'll need to revisit, but currently, the way -non-blocking streams work is that they perform reads or writes that -read or write fewer bytes than requested. - -#### Why do read/write use u64 sizes? - -This is to make the API independent of the address space size of -the caller. Callees are still advised to avoid using sizes that -are larger than their instances will be able to allocate. - -#### Why have a `forward` function when you can just `splice` in a loop? - -This seems like it'll be a common use case, and `forward` -addresses it in a very simple way. - -### Stakeholder Interest & Feedback - -Wasi-io is a dependency of wasi-filesystem, wasi-sockets, and wasi-http, and -is a foundational piece of WASI Preview 2. - -### References & acknowledgements - -Many thanks for valuable feedback and advice from: - -- Thanks to Luke Wagner for many design functions and the design of - the component-model async streams which inform the design here. -- Thanks to Calvin Prewitt for the idea to include a `forward` function - in this API. diff --git a/proposals/io/imports.md b/proposals/io/imports.md deleted file mode 100644 index 64c4ad6df..000000000 --- a/proposals/io/imports.md +++ /dev/null @@ -1,398 +0,0 @@ -

World imports

- -

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- diff --git a/proposals/io/test/README.md b/proposals/io/test/README.md deleted file mode 100644 index c274acd9d..000000000 --- a/proposals/io/test/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Testing guidelines - -TK fill in testing guidelines - -## Installing the tools - -TK fill in instructions - -## Running the tests - -TK fill in instructions diff --git a/proposals/io/wit/error.wit b/proposals/io/wit/error.wit deleted file mode 100644 index 4f6e4f0ca..000000000 --- a/proposals/io/wit/error.wit +++ /dev/null @@ -1,34 +0,0 @@ -package wasi:io@0.2.12; - -@since(version = 0.2.0) -interface error { - /// A resource which represents some error information. - /// - /// The only method provided by this resource is `to-debug-string`, - /// which provides some human-readable information about the error. - /// - /// In the `wasi:io` package, this resource is returned through the - /// `wasi:io/streams.stream-error` type. - /// - /// To provide more specific error information, other interfaces may - /// offer functions to "downcast" this error into more specific types. For example, - /// errors returned from streams derived from filesystem types can be described using - /// the filesystem's own error-code type. This is done using the function - /// `wasi:filesystem/types.filesystem-error-code`, which takes a `borrow` - /// parameter and returns an `option`. - /// - /// The set of functions which can "downcast" an `error` into a more - /// concrete type is open. - @since(version = 0.2.0) - resource error { - /// Returns a string that is suitable to assist humans in debugging - /// this error. - /// - /// WARNING: The returned string should not be consumed mechanically! - /// It may change across platforms, hosts, or other implementation - /// details. Parsing this string is a major platform-compatibility - /// hazard. - @since(version = 0.2.0) - to-debug-string: func() -> string; - } -} diff --git a/proposals/io/wit/poll.wit b/proposals/io/wit/poll.wit deleted file mode 100644 index 8f87632f3..000000000 --- a/proposals/io/wit/poll.wit +++ /dev/null @@ -1,47 +0,0 @@ -package wasi:io@0.2.12; - -/// A poll API intended to let users wait for I/O events on multiple handles -/// at once. -@since(version = 0.2.0) -interface poll { - /// `pollable` represents a single I/O event which may be ready, or not. - @since(version = 0.2.0) - resource pollable { - - /// Return the readiness of a pollable. This function never blocks. - /// - /// Returns `true` when the pollable is ready, and `false` otherwise. - @since(version = 0.2.0) - ready: func() -> bool; - - /// `block` returns immediately if the pollable is ready, and otherwise - /// blocks until ready. - /// - /// This function is equivalent to calling `poll.poll` on a list - /// containing only this pollable. - @since(version = 0.2.0) - block: func(); - } - - /// Poll for completion on a set of pollables. - /// - /// This function takes a list of pollables, which identify I/O sources of - /// interest, and waits until one or more of the events is ready for I/O. - /// - /// The result `list` contains one or more indices of handles in the - /// argument list that is ready for I/O. - /// - /// This function traps if either: - /// - the list is empty, or: - /// - the list contains more elements than can be indexed with a `u32` value. - /// - /// A timeout can be implemented by adding a pollable from the - /// wasi-clocks API to the list. - /// - /// This function does not return a `result`; polling in itself does not - /// do any I/O so it doesn't fail. If any of the I/O sources identified by - /// the pollables has an error, it is indicated by marking the source as - /// being ready for I/O. - @since(version = 0.2.0) - poll: func(in: list>) -> list; -} diff --git a/proposals/io/wit/streams.wit b/proposals/io/wit/streams.wit deleted file mode 100644 index c7baafbc9..000000000 --- a/proposals/io/wit/streams.wit +++ /dev/null @@ -1,258 +0,0 @@ -package wasi:io@0.2.12; - -/// WASI I/O is an I/O abstraction API which is currently focused on providing -/// stream types. -/// -/// In the future, the component model is expected to add built-in stream types; -/// when it does, they are expected to subsume this API. -@since(version = 0.2.0) -interface streams { - @since(version = 0.2.0) - use error.{error}; - @since(version = 0.2.0) - use poll.{pollable}; - - /// An error for input-stream and output-stream operations. - @since(version = 0.2.0) - variant stream-error { - /// The last operation (a write or flush) failed before completion. - /// - /// More information is available in the `error` payload. - /// - /// After this, the stream will be closed. All future operations return - /// `stream-error::closed`. - last-operation-failed(error), - /// The stream is closed: no more input will be accepted by the - /// stream. A closed output-stream will return this error on all - /// future operations. - closed - } - - /// An input bytestream. - /// - /// `input-stream`s are *non-blocking* to the extent practical on underlying - /// platforms. I/O operations always return promptly; if fewer bytes are - /// promptly available than requested, they return the number of bytes promptly - /// available, which could even be zero. To wait for data to be available, - /// use the `subscribe` function to obtain a `pollable` which can be polled - /// for using `wasi:io/poll`. - @since(version = 0.2.0) - resource input-stream { - /// Perform a non-blocking read from the stream. - /// - /// When the source of a `read` is binary data, the bytes from the source - /// are returned verbatim. When the source of a `read` is known to the - /// implementation to be text, bytes containing the UTF-8 encoding of the - /// text are returned. - /// - /// This function returns a list of bytes containing the read data, - /// when successful. The returned list will contain up to `len` bytes; - /// it may return fewer than requested, but not more. The list is - /// empty when no bytes are available for reading at this time. The - /// pollable given by `subscribe` will be ready when more bytes are - /// available. - /// - /// This function fails with a `stream-error` when the operation - /// encounters an error, giving `last-operation-failed`, or when the - /// stream is closed, giving `closed`. - /// - /// When the caller gives a `len` of 0, it represents a request to - /// read 0 bytes. If the stream is still open, this call should - /// succeed and return an empty list, or otherwise fail with `closed`. - /// - /// The `len` parameter is a `u64`, which could represent a list of u8 which - /// is not possible to allocate in wasm32, or not desirable to allocate as - /// as a return value by the callee. The callee may return a list of bytes - /// less than `len` in size while more bytes are available for reading. - @since(version = 0.2.0) - read: func( - /// The maximum number of bytes to read - len: u64 - ) -> result, stream-error>; - - /// Read bytes from a stream, after blocking until at least one byte can - /// be read. Except for blocking, behavior is identical to `read`. - @since(version = 0.2.0) - blocking-read: func( - /// The maximum number of bytes to read - len: u64 - ) -> result, stream-error>; - - /// Skip bytes from a stream. Returns number of bytes skipped. - /// - /// Behaves identical to `read`, except instead of returning a list - /// of bytes, returns the number of bytes consumed from the stream. - @since(version = 0.2.0) - skip: func( - /// The maximum number of bytes to skip. - len: u64, - ) -> result; - - /// Skip bytes from a stream, after blocking until at least one byte - /// can be skipped. Except for blocking behavior, identical to `skip`. - @since(version = 0.2.0) - blocking-skip: func( - /// The maximum number of bytes to skip. - len: u64, - ) -> result; - - /// Create a `pollable` which will resolve once either the specified stream - /// has bytes available to read or the other end of the stream has been - /// closed. - /// The created `pollable` is a child resource of the `input-stream`. - /// Implementations may trap if the `input-stream` is dropped before - /// all derived `pollable`s created with this function are dropped. - @since(version = 0.2.0) - subscribe: func() -> pollable; - } - - - /// An output bytestream. - /// - /// `output-stream`s are *non-blocking* to the extent practical on - /// underlying platforms. Except where specified otherwise, I/O operations also - /// always return promptly, after the number of bytes that can be written - /// promptly, which could even be zero. To wait for the stream to be ready to - /// accept data, the `subscribe` function to obtain a `pollable` which can be - /// polled for using `wasi:io/poll`. - /// - /// Dropping an `output-stream` while there's still an active write in - /// progress may result in the data being lost. Before dropping the stream, - /// be sure to fully flush your writes. - @since(version = 0.2.0) - resource output-stream { - /// Check readiness for writing. This function never blocks. - /// - /// Returns the number of bytes permitted for the next call to `write`, - /// or an error. Calling `write` with more bytes than this function has - /// permitted will trap. - /// - /// When this function returns 0 bytes, the `subscribe` pollable will - /// become ready when this function will report at least 1 byte, or an - /// error. - @since(version = 0.2.0) - check-write: func() -> result; - - /// Perform a write. This function never blocks. - /// - /// When the destination of a `write` is binary data, the bytes from - /// `contents` are written verbatim. When the destination of a `write` is - /// known to the implementation to be text, the bytes of `contents` are - /// transcoded from UTF-8 into the encoding of the destination and then - /// written. - /// - /// Precondition: check-write gave permit of Ok(n) and contents has a - /// length of less than or equal to n. Otherwise, this function will trap. - /// - /// returns Err(closed) without writing if the stream has closed since - /// the last call to check-write provided a permit. - @since(version = 0.2.0) - write: func( - contents: list - ) -> result<_, stream-error>; - - /// Perform a write of up to 4096 bytes, and then flush the stream. Block - /// until all of these operations are complete, or an error occurs. - /// - /// Returns success when all of the contents written are successfully - /// flushed to output. If an error occurs at any point before all - /// contents are successfully flushed, that error is returned as soon as - /// possible. If writing and flushing the complete contents causes the - /// stream to become closed, this call should return success, and - /// subsequent calls to check-write or other interfaces should return - /// stream-error::closed. - @since(version = 0.2.0) - blocking-write-and-flush: func( - contents: list - ) -> result<_, stream-error>; - - /// Request to flush buffered output. This function never blocks. - /// - /// This tells the output-stream that the caller intends any buffered - /// output to be flushed. the output which is expected to be flushed - /// is all that has been passed to `write` prior to this call. - /// - /// Upon calling this function, the `output-stream` will not accept any - /// writes (`check-write` will return `ok(0)`) until the flush has - /// completed. The `subscribe` pollable will become ready when the - /// flush has completed and the stream can accept more writes. - @since(version = 0.2.0) - flush: func() -> result<_, stream-error>; - - /// Request to flush buffered output, and block until flush completes - /// and stream is ready for writing again. - @since(version = 0.2.0) - blocking-flush: func() -> result<_, stream-error>; - - /// Create a `pollable` which will resolve once the output-stream - /// is ready for more writing, or an error has occurred. When this - /// pollable is ready, `check-write` will return `ok(n)` with n>0, or an - /// error. - /// - /// If the stream is closed, this pollable is always ready immediately. - /// - /// The created `pollable` is a child resource of the `output-stream`. - /// Implementations may trap if the `output-stream` is dropped before - /// all derived `pollable`s created with this function are dropped. - @since(version = 0.2.0) - subscribe: func() -> pollable; - - /// Write zeroes to a stream. - /// - /// This should be used precisely like `write` with the exact same - /// preconditions (must use check-write first), but instead of - /// passing a list of bytes, you simply pass the number of zero-bytes - /// that should be written. - @since(version = 0.2.0) - write-zeroes: func( - /// The number of zero-bytes to write - len: u64 - ) -> result<_, stream-error>; - - /// Perform a write of up to 4096 zeroes, and then flush the stream. - /// Block until all of these operations are complete, or an error - /// occurs. - /// - /// Functionality is equivelant to `blocking-write-and-flush` with - /// contents given as a list of len containing only zeroes. - @since(version = 0.2.0) - blocking-write-zeroes-and-flush: func( - /// The number of zero-bytes to write - len: u64 - ) -> result<_, stream-error>; - - /// Read from one stream and write to another. - /// - /// The behavior of splice is equivalent to: - /// 1. calling `check-write` on the `output-stream` - /// 2. calling `read` on the `input-stream` with the smaller of the - /// `check-write` permitted length and the `len` provided to `splice` - /// 3. calling `write` on the `output-stream` with that read data. - /// - /// Any error reported by the call to `check-write`, `read`, or - /// `write` ends the splice and reports that error. - /// - /// This function returns the number of bytes transferred; it may be less - /// than `len`. - @since(version = 0.2.0) - splice: func( - /// The stream to read from - src: borrow, - /// The number of bytes to splice - len: u64, - ) -> result; - - /// Read from one stream and write to another, with blocking. - /// - /// This is similar to `splice`, except that it blocks until the - /// `output-stream` is ready for writing, and the `input-stream` - /// is ready for reading, before performing the `splice`. - @since(version = 0.2.0) - blocking-splice: func( - /// The stream to read from - src: borrow, - /// The number of bytes to splice - len: u64, - ) -> result; - } -} diff --git a/proposals/io/wit/world.wit b/proposals/io/wit/world.wit deleted file mode 100644 index a3fb21e7e..000000000 --- a/proposals/io/wit/world.wit +++ /dev/null @@ -1,10 +0,0 @@ -package wasi:io@0.2.12; - -@since(version = 0.2.0) -world imports { - @since(version = 0.2.0) - import streams; - - @since(version = 0.2.0) - import poll; -} diff --git a/proposals/random/imports.md b/proposals/random/imports.md deleted file mode 100644 index bd83ae669..000000000 --- a/proposals/random/imports.md +++ /dev/null @@ -1,96 +0,0 @@ -

World imports

- -

Import interface wasi:random/random@0.2.12

-

WASI Random is a random data API.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-random-bytes: func

-

Return len cryptographically-secure random or pseudo-random bytes.

-

This function must produce data at least as cryptographically secure and -fast as an adequately seeded cryptographically-secure pseudo-random -number generator (CSPRNG). It must not block, from the perspective of -the calling program, under any circumstances, including on the first -request and on requests for numbers of bytes. The returned data must -always be unpredictable.

-

This function must always return fresh data. Deterministic environments -must omit this function, rather than implementing it with deterministic -data.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-random-u64: func

-

Return a cryptographically-secure random or pseudo-random u64 value.

-

This function returns the same type of data as get-random-bytes, -represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure@0.2.12

-

The insecure interface for insecure pseudo-random numbers.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

get-insecure-random-bytes: func

-

Return len insecure pseudo-random bytes.

-

This function is not cryptographically secure. Do not use it for -anything related to security.

-

There are no requirements on the values of the returned bytes, however -implementations are encouraged to return evenly distributed values with -a long period.

-
Params
-
    -
  • len: u64
    • -
-
Return values
-
    -
  • list<u8>
    • -
-

get-insecure-random-u64: func

-

Return an insecure pseudo-random u64 value.

-

This function returns the same type of pseudo-random data as -get-insecure-random-bytes, represented as a u64.

-
Return values
-
    -
  • u64
    • -
-

Import interface wasi:random/insecure-seed@0.2.12

-

The insecure-seed interface for seeding hash-map DoS resistance.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-
-

Functions

-

insecure-seed: func

-

Return a 128-bit value that may contain a pseudo-random value.

-

The returned value is not required to be computed from a CSPRNG, and may -even be entirely deterministic. Host implementations are encouraged to -provide pseudo-random values to any program exposed to -attacker-controlled content, to enable DoS protection built into many -languages' hash-map implementations.

-

This function is intended to only be called once, by a source language -to initialize Denial Of Service (DoS) protection in its hash-map -implementation.

-

Expected future evolution

-

This will likely be changed to a value import, to prevent it from being -called multiple times and potentially used for purposes other than DoS -protection.

-
Return values
-
    -
  • (u64, u64)
    • -
diff --git a/proposals/random/wit-0.3.0-draft/insecure-seed.wit b/proposals/random/wit-0.3.0-draft/insecure-seed.wit deleted file mode 100644 index dc9100f78..000000000 --- a/proposals/random/wit-0.3.0-draft/insecure-seed.wit +++ /dev/null @@ -1,27 +0,0 @@ -package wasi:random@0.3.0-rc-2026-03-15; -/// The insecure-seed interface for seeding hash-map DoS resistance. -/// -/// It is intended to be portable at least between Unix-family platforms and -/// Windows. -@since(version = 0.3.0-rc-2026-03-15) -interface insecure-seed { - /// Return a 128-bit value that may contain a pseudo-random value. - /// - /// The returned value is not required to be computed from a CSPRNG, and may - /// even be entirely deterministic. Host implementations are encouraged to - /// provide pseudo-random values to any program exposed to - /// attacker-controlled content, to enable DoS protection built into many - /// languages' hash-map implementations. - /// - /// This function is intended to only be called once, by a source language - /// to initialize Denial Of Service (DoS) protection in its hash-map - /// implementation. - /// - /// # Expected future evolution - /// - /// This will likely be changed to a value import, to prevent it from being - /// called multiple times and potentially used for purposes other than DoS - /// protection. - @since(version = 0.3.0-rc-2026-03-15) - get-insecure-seed: func() -> tuple; -} diff --git a/proposals/random/wit-0.3.0-draft/insecure.wit b/proposals/random/wit-0.3.0-draft/insecure.wit deleted file mode 100644 index ee3fef733..000000000 --- a/proposals/random/wit-0.3.0-draft/insecure.wit +++ /dev/null @@ -1,32 +0,0 @@ -package wasi:random@0.3.0-rc-2026-03-15; -/// The insecure interface for insecure pseudo-random numbers. -/// -/// It is intended to be portable at least between Unix-family platforms and -/// Windows. -@since(version = 0.3.0-rc-2026-03-15) -interface insecure { - /// Return up to `max-len` insecure pseudo-random bytes. - /// - /// This function is not cryptographically secure. Do not use it for - /// anything related to security. - /// - /// There are no requirements on the values of the returned bytes, however - /// implementations are encouraged to return evenly distributed values with - /// a long period. - /// - /// Implementations MAY return fewer bytes than requested (a short read). - /// Callers that require exactly `max-len` bytes MUST call this function in - /// a loop until the desired number of bytes has been accumulated. - /// Implementations MUST return at least 1 byte when `max-len` is greater - /// than zero. When `max-len` is zero, implementations MUST return an empty - /// list without trapping. - @since(version = 0.3.0-rc-2026-03-15) - get-insecure-random-bytes: func(max-len: u64) -> list; - - /// Return an insecure pseudo-random `u64` value. - /// - /// This function returns the same type of pseudo-random data as - /// `get-insecure-random-bytes`, represented as a `u64`. - @since(version = 0.3.0-rc-2026-03-15) - get-insecure-random-u64: func() -> u64; -} diff --git a/proposals/random/wit-0.3.0-draft/random.wit b/proposals/random/wit-0.3.0-draft/random.wit deleted file mode 100644 index e40b97d7c..000000000 --- a/proposals/random/wit-0.3.0-draft/random.wit +++ /dev/null @@ -1,37 +0,0 @@ -package wasi:random@0.3.0-rc-2026-03-15; -/// WASI Random is a random data API. -/// -/// It is intended to be portable at least between Unix-family platforms and -/// Windows. -@since(version = 0.3.0-rc-2026-03-15) -interface random { - /// Return up to `max-len` cryptographically-secure random or pseudo-random - /// bytes. - /// - /// This function must produce data at least as cryptographically secure and - /// fast as an adequately seeded cryptographically-secure pseudo-random - /// number generator (CSPRNG). It must not block, from the perspective of - /// the calling program, under any circumstances, including on the first - /// request and on requests for numbers of bytes. The returned data must - /// always be unpredictable. - /// - /// Implementations MAY return fewer bytes than requested (a short read). - /// Callers that require exactly `max-len` bytes MUST call this function in - /// a loop until the desired number of bytes has been accumulated. - /// Implementations MUST return at least 1 byte when `max-len` is greater - /// than zero. When `max-len` is zero, implementations MUST return an empty - /// list without trapping. - /// - /// This function must always return fresh data. Deterministic environments - /// must omit this function, rather than implementing it with deterministic - /// data. - @since(version = 0.3.0-rc-2026-03-15) - get-random-bytes: func(max-len: u64) -> list; - - /// Return a cryptographically-secure random or pseudo-random `u64` value. - /// - /// This function returns the same type of data as `get-random-bytes`, - /// represented as a `u64`. - @since(version = 0.3.0-rc-2026-03-15) - get-random-u64: func() -> u64; -} diff --git a/proposals/random/wit-0.3.0-draft/world.wit b/proposals/random/wit-0.3.0-draft/world.wit deleted file mode 100644 index 590691347..000000000 --- a/proposals/random/wit-0.3.0-draft/world.wit +++ /dev/null @@ -1,13 +0,0 @@ -package wasi:random@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world imports { - @since(version = 0.3.0-rc-2026-03-15) - import random; - - @since(version = 0.3.0-rc-2026-03-15) - import insecure; - - @since(version = 0.3.0-rc-2026-03-15) - import insecure-seed; -} diff --git a/proposals/random/wit/insecure-seed.wit b/proposals/random/wit/insecure-seed.wit index ae2c38376..86c988c2e 100644 --- a/proposals/random/wit/insecure-seed.wit +++ b/proposals/random/wit/insecure-seed.wit @@ -1,9 +1,9 @@ -package wasi:random@0.2.12; +package wasi:random@0.3.0; /// The insecure-seed interface for seeding hash-map DoS resistance. /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. -@since(version = 0.2.0) +@since(version = 0.3.0) interface insecure-seed { /// Return a 128-bit value that may contain a pseudo-random value. /// @@ -22,6 +22,6 @@ interface insecure-seed { /// This will likely be changed to a value import, to prevent it from being /// called multiple times and potentially used for purposes other than DoS /// protection. - @since(version = 0.2.0) - insecure-seed: func() -> tuple; + @since(version = 0.3.0) + get-insecure-seed: func() -> tuple; } diff --git a/proposals/random/wit/insecure.wit b/proposals/random/wit/insecure.wit index 25d4b7b27..73026f7ea 100644 --- a/proposals/random/wit/insecure.wit +++ b/proposals/random/wit/insecure.wit @@ -1,11 +1,11 @@ -package wasi:random@0.2.12; +package wasi:random@0.3.0; /// The insecure interface for insecure pseudo-random numbers. /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. -@since(version = 0.2.0) +@since(version = 0.3.0) interface insecure { - /// Return `len` insecure pseudo-random bytes. + /// Return up to `max-len` insecure pseudo-random bytes. /// /// This function is not cryptographically secure. Do not use it for /// anything related to security. @@ -13,13 +13,20 @@ interface insecure { /// There are no requirements on the values of the returned bytes, however /// implementations are encouraged to return evenly distributed values with /// a long period. - @since(version = 0.2.0) - get-insecure-random-bytes: func(len: u64) -> list; + /// + /// Implementations MAY return fewer bytes than requested (a short read). + /// Callers that require exactly `max-len` bytes MUST call this function in + /// a loop until the desired number of bytes has been accumulated. + /// Implementations MUST return at least 1 byte when `max-len` is greater + /// than zero. When `max-len` is zero, implementations MUST return an empty + /// list without trapping. + @since(version = 0.3.0) + get-insecure-random-bytes: func(max-len: u64) -> list; /// Return an insecure pseudo-random `u64` value. /// /// This function returns the same type of pseudo-random data as /// `get-insecure-random-bytes`, represented as a `u64`. - @since(version = 0.2.0) + @since(version = 0.3.0) get-insecure-random-u64: func() -> u64; } diff --git a/proposals/random/wit/random.wit b/proposals/random/wit/random.wit index 2763ba4ae..a7fdee94a 100644 --- a/proposals/random/wit/random.wit +++ b/proposals/random/wit/random.wit @@ -1,11 +1,12 @@ -package wasi:random@0.2.12; +package wasi:random@0.3.0; /// WASI Random is a random data API. /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. -@since(version = 0.2.0) +@since(version = 0.3.0) interface random { - /// Return `len` cryptographically-secure random or pseudo-random bytes. + /// Return up to `max-len` cryptographically-secure random or pseudo-random + /// bytes. /// /// This function must produce data at least as cryptographically secure and /// fast as an adequately seeded cryptographically-secure pseudo-random @@ -14,16 +15,23 @@ interface random { /// request and on requests for numbers of bytes. The returned data must /// always be unpredictable. /// + /// Implementations MAY return fewer bytes than requested (a short read). + /// Callers that require exactly `max-len` bytes MUST call this function in + /// a loop until the desired number of bytes has been accumulated. + /// Implementations MUST return at least 1 byte when `max-len` is greater + /// than zero. When `max-len` is zero, implementations MUST return an empty + /// list without trapping. + /// /// This function must always return fresh data. Deterministic environments /// must omit this function, rather than implementing it with deterministic /// data. - @since(version = 0.2.0) - get-random-bytes: func(len: u64) -> list; + @since(version = 0.3.0) + get-random-bytes: func(max-len: u64) -> list; /// Return a cryptographically-secure random or pseudo-random `u64` value. /// /// This function returns the same type of data as `get-random-bytes`, /// represented as a `u64`. - @since(version = 0.2.0) + @since(version = 0.3.0) get-random-u64: func() -> u64; } diff --git a/proposals/random/wit/world.wit b/proposals/random/wit/world.wit index 180f0bab0..838d38023 100644 --- a/proposals/random/wit/world.wit +++ b/proposals/random/wit/world.wit @@ -1,13 +1,13 @@ -package wasi:random@0.2.12; +package wasi:random@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world imports { - @since(version = 0.2.0) + @since(version = 0.3.0) import random; - @since(version = 0.2.0) + @since(version = 0.3.0) import insecure; - @since(version = 0.2.0) + @since(version = 0.3.0) import insecure-seed; } diff --git a/proposals/sockets/Posix-compatibility.md b/proposals/sockets/Posix-compatibility.md index 02bd67343..340562363 100644 --- a/proposals/sockets/Posix-compatibility.md +++ b/proposals/sockets/Posix-compatibility.md @@ -6,11 +6,11 @@ This document provides an overview of the POSIX interface along with common non- ## General ### I/O completion polling (`poll`, `select`, `pselect`, `epoll_*` (non-standard), `kqueue` (non-standard)) -Use the various `subscribe` methods to obtain a `pollable` handle. Then use that to wait for IO events using the [wasi:io/poll][poll] interface. +WASI sockets use the Component Model's native `async` support. Operations such as `connect`, `send` and `receive` are `async func`s, and inbound connections and data are delivered as `stream` values. A task awaits these directly, so there is no separate readiness-polling interface to drive. ### Non-blocking mode (`FIONBIO`, `SOCK_NONBLOCK`, `O_NONBLOCK`) All WASI sockets are non-blocking and can not be configured to block. -Blocking behaviour can be recreated in userland (or in wasi-libc) by calling [pollable::block][poll] on the relevant pollable. +Blocking behaviour can be recreated in userland (or in wasi-libc) by awaiting the relevant `async` call, `stream`, or `future`. ### TCP urgent data (`sockatmark`, `MSG_OOB`, `SO_OOBINLINE`, `SIOCATMARK`) Out-of-band (OOB) data is currently not included in this proposal. Application-level usage of the TCP "urgent" flag is rare in practice and discouraged in general. Including it in WASI would probably interfere with the ability to use WASI/ComponentModel `stream`s. @@ -97,7 +97,7 @@ None of the flags are directly present in WASI Sockets: Sending ancillary messages: None supported as of yet. ### `sendfile` (non-standard) -- TCP: Part of the [wasi:io/streams][streams] proposal as `output-stream::splice` +- TCP: Achieved by passing the source `stream` directly to `tcp-socket`'s `send`. - UDP: N/A ### `shutdown` @@ -603,6 +603,4 @@ Legend: [tcp]: https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/wit/tcp.wit [udp-create-socket]: https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/wit/udp-create-socket.wit [udp]: https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/wit/udp.wit -[poll]: https://github.com/WebAssembly/wasi-poll/blob/main/wit/poll.wit -[streams]: https://github.com/WebAssembly/wasi-io/blob/main/wit/streams.wit **** diff --git a/proposals/sockets/TcpSocketOperationalSemantics-0.3.0-draft.md b/proposals/sockets/TcpSocketOperationalSemantics-0.3.0-draft.md deleted file mode 100644 index 51555c72f..000000000 --- a/proposals/sockets/TcpSocketOperationalSemantics-0.3.0-draft.md +++ /dev/null @@ -1,54 +0,0 @@ -# Operational semantics of WASI TCP sockets - -WASI TCP sockets must behave [as-if](https://en.wikipedia.org/wiki/As-if_rule) they are implemented using the state machine described in this document. - -## States -> Note: These refer to the states of the TCP socket, not the [TCP connection](https://datatracker.ietf.org/doc/html/rfc9293#name-state-machine-overview) - -In pseudo code: - -```wit -interface tcp { - variant state { - unbound, - bound, - listening(accept-stream), - connecting(connect-future), - connected, - closed(option), - } -} -``` - -## Transitions -The following diagram describes the exhaustive set of all possible state transitions: - -```mermaid -stateDiagram-v2 - state "unbound" as Unbound - state "bound" as Bound - state "connecting" as Connecting - state "connected" as Connected - state "listening" as Listening - state "closed" as Closed - - - [*] --> Unbound: create() -> ok - Unbound --> Bound: bind() -> ok - Unbound --> Connecting: connect() - - Connecting --> Connected: «task resolves successfully» - Connecting --> Closed: «task resolves with error» - - Connected --> Closed: «connection terminated» - - Bound --> Connecting: connect() - Bound --> Listening: listen() -> ok - Unbound --> Listening: listen() -> ok -``` - -- Transitions annotated with `-> ok` only apply when the method returns successfully. -- Calling a method from the wrong state returns `error(invalid-state)` and does not affect the state of the socket. -- This diagram only includes the methods that impact the socket's state. For an overview of all methods and their required states, see [tcp.wit](./wit/tcp.wit) -- Client sockets returned by `listen()` are immediately in the `connected` state. -- A socket resource can be dropped in any state. diff --git a/proposals/sockets/TcpSocketOperationalSemantics.md b/proposals/sockets/TcpSocketOperationalSemantics.md index dd66880b2..51555c72f 100644 --- a/proposals/sockets/TcpSocketOperationalSemantics.md +++ b/proposals/sockets/TcpSocketOperationalSemantics.md @@ -11,42 +11,11 @@ In pseudo code: interface tcp { variant state { unbound, - bind-in-progress(bind-future), bound, - listen-in-progress(listen-future), listening(accept-stream), - connect-in-progress(connect-future), + connecting(connect-future), connected, - closed, - } - - type bind-future = future>; - type listen-future = future>; - type connect-future = future, error-code>>; - type accept-stream = stream, error-code>>; -} -``` - -## Pollable readiness -As seen above, there can be at most one asynchronous operation in progress at any time. The socket's pollable ready state can therefore be unambiguously derived as follows: - -```rs -fn ready() -> bool { - match state { - unbound => true, - bound => true, - connected => true, // To poll for I/O readiness, subscribe to the input and output streams. - closed => true, - - // Assuming that `f.is-resolved` returns true when the - // future has completed, either successfully or with failure. - bind-in-progress(f) => f.is-resolved, - listen-in-progress(f) => f.is-resolved, - connect-in-progress(f) => f.is-resolved, - - // Assuming that `s.has-pending-items` returns true when - // there is an item ready to be read from the stream. - listening(s) => s.has-pending-items, + closed(option), } } ``` @@ -57,55 +26,29 @@ The following diagram describes the exhaustive set of all possible state transit ```mermaid stateDiagram-v2 state "unbound" as Unbound - state "bind-in-progress" as BindInProgress state "bound" as Bound - state "listen-in-progress" as ListenInProgress - state "listening" as Listening - state "connect-in-progress" as ConnectInProgress + state "connecting" as Connecting state "connected" as Connected + state "listening" as Listening state "closed" as Closed - [*] --> Unbound: create-tcp-socket()\n#ok - Unbound --> BindInProgress: start-bind()\n#ok - Unbound --> Unbound: start-bind()\n#error - Unbound --> ConnectInProgress: start-connect()\n#ok - Unbound --> Closed: start-connect()\n#error + [*] --> Unbound: create() -> ok + Unbound --> Bound: bind() -> ok + Unbound --> Connecting: connect() - ConnectInProgress --> ConnectInProgress: finish-connect()\n#error(would-block) - ConnectInProgress --> Closed: finish-connect()\n#error(NOT would-block) - ConnectInProgress --> Connected: finish-connect()\n#ok + Connecting --> Connected: «task resolves successfully» + Connecting --> Closed: «task resolves with error» - Connected --> Connected: shutdown() Connected --> Closed: «connection terminated» - - BindInProgress --> BindInProgress: finish-bind()\n#error(would-block) - BindInProgress --> Unbound: finish-bind()\n#error(NOT would-block) - BindInProgress --> Bound: finish-bind()\n#ok - Bound --> ConnectInProgress: start-connect()\n#ok - Bound --> Closed: start-connect()\n#error - Bound --> ListenInProgress: start-listen()\n#ok - Bound --> Closed: start-listen()\n#error - - ListenInProgress --> ListenInProgress: finish-listen()\n#error(would-block) - ListenInProgress --> Closed: finish-listen()\n#error(NOT would-block) - ListenInProgress --> Listening: finish-listen()\n#ok - - Listening --> Listening: accept() + Bound --> Connecting: connect() + Bound --> Listening: listen() -> ok + Unbound --> Listening: listen() -> ok ``` -Most transitions are dependent on the result of the method. Legend: -- `#ok`: this transition only applies when the method returns successfully. -- `#error`: this transition only applies when the method returns a failure. -- `#error(would-block)`: this transition only applies when the method returns the `would-block` error specifically. -- `#error(NOT would-block)`: this transition only applies when the method returns an error other than `would-block`. -- _(no annotation)_: Transition in unconditional. - -#### Not shown in the diagram: -- All state transitions shown above are driven by the caller and occur synchronously during the method invocations. There's one exception: the `«connection terminated»` transition from `connected` to `closed`. This can happen when: the peer closed the connection, a network failure occurred, the connection timed out, etc. -- While `shutdown` immediately closes the input and/or output streams associated with the socket, it does not affect the socket's own state as it just _initiates_ a shutdown. Only after the full shutdown sequence has been completed will the `«connection terminated»` transition be activated. (See previous item) -- Calling a method from the wrong state returns `error(invalid-state)` and does not affect the state of the socket. A special case are the `finish-*` methods; those return `error(not-in-progress)` when the socket is not in the corresponding `*-in-progress` state. +- Transitions annotated with `-> ok` only apply when the method returns successfully. +- Calling a method from the wrong state returns `error(invalid-state)` and does not affect the state of the socket. - This diagram only includes the methods that impact the socket's state. For an overview of all methods and their required states, see [tcp.wit](./wit/tcp.wit) -- Client sockets returned by `accept()` are in immediately in the `connected` state. +- Client sockets returned by `listen()` are immediately in the `connected` state. - A socket resource can be dropped in any state. diff --git a/proposals/sockets/imports.md b/proposals/sockets/imports.md deleted file mode 100644 index 6e52d4df9..000000000 --- a/proposals/sockets/imports.md +++ /dev/null @@ -1,1874 +0,0 @@ -

World imports

- -

Import interface wasi:io/error@0.2.12

-
-

Types

-

resource error

-

A resource which represents some error information.

-

The only method provided by this resource is to-debug-string, -which provides some human-readable information about the error.

-

In the wasi:io package, this resource is returned through the -wasi:io/streams.stream-error type.

-

To provide more specific error information, other interfaces may -offer functions to "downcast" this error into more specific types. For example, -errors returned from streams derived from filesystem types can be described using -the filesystem's own error-code type. This is done using the function -wasi:filesystem/types.filesystem-error-code, which takes a borrow<error> -parameter and returns an option<wasi:filesystem/types.error-code>.

-

The set of functions which can "downcast" an error into a more -concrete type is open.

-

Functions

-

[method]error.to-debug-string: func

-

Returns a string that is suitable to assist humans in debugging -this error.

-

WARNING: The returned string should not be consumed mechanically! -It may change across platforms, hosts, or other implementation -details. Parsing this string is a major platform-compatibility -hazard.

-
Params
- -
Return values
-
    -
  • string
    • -
-

Import interface wasi:sockets/network@0.2.12

-
-

Types

-

type error

-

error

-

-

resource network

-

An opaque resource that represents access to (a subset of) the network. -This enables context-based security for networking. -There is no need for this to map 1:1 to a physical network interface.

-

enum error-code

-

Error codes.

-

In theory, every API can return any error code. -In practice, API's typically only return the errors documented per API -combined with a couple of errors that are always possible:

-
    -
  • unknown
    • -
  • access-denied
    • -
  • not-supported
    • -
  • out-of-memory
    • -
  • concurrency-conflict
    • -
-

See each individual API for what the POSIX equivalents are. They sometimes differ per API.

-
Enum Cases
-
    -
  • -

    unknown

    -

    Unknown error -

    • -
  • -

    access-denied

    -

    Access denied. -

    POSIX equivalent: EACCES, EPERM

    -
    • -
  • -

    not-supported

    -

    The operation is not supported. -

    POSIX equivalent: EOPNOTSUPP

    -
    • -
  • -

    invalid-argument

    -

    One of the arguments is invalid. -

    POSIX equivalent: EINVAL

    -
    • -
  • -

    out-of-memory

    -

    Not enough memory to complete the operation. -

    POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY

    -
    • -
  • -

    timeout

    -

    The operation timed out before it could finish completely. -

    • -
  • -

    concurrency-conflict

    -

    This operation is incompatible with another asynchronous operation that is already in progress. -

    POSIX equivalent: EALREADY

    -
    • -
  • -

    not-in-progress

    -

    Trying to finish an asynchronous operation that: -- has not been started yet, or: -- was already finished by a previous `finish-*` call. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    would-block

    -

    The operation has been aborted because it could not be completed immediately. -

    Note: this is scheduled to be removed when futures are natively supported.

    -
    • -
  • -

    invalid-state

    -

    The operation is not valid in the socket's current state. -

    • -
  • -

    new-socket-limit

    -

    A new socket resource could not be created because of a system limit. -

    • -
  • -

    address-not-bindable

    -

    A bind operation failed because the provided address is not an address that the `network` can bind to. -

    • -
  • -

    address-in-use

    -

    A bind operation failed because the provided address is already in use or because there are no ephemeral ports available. -

    • -
  • -

    remote-unreachable

    -

    The remote address is not reachable -

    • -
  • -

    connection-refused

    -

    The TCP connection was forcefully rejected -

    • -
  • -

    connection-reset

    -

    The TCP connection was reset. -

    • -
  • -

    connection-aborted

    -

    A TCP connection was aborted. -

    • -
  • -

    datagram-too-large

    -

    The size of a datagram sent to a UDP socket exceeded the maximum -supported size. -

    • -
  • -

    name-unresolvable

    -

    Name does not exist or has no suitable associated IP addresses. -

    • -
  • -

    temporary-resolver-failure

    -

    A temporary failure in name resolution occurred. -

    • -
  • -

    permanent-resolver-failure

    -

    A permanent failure in name resolution occurred. -

    • -
-

enum ip-address-family

-
Enum Cases
-
    -
  • -

    ipv4

    -

    Similar to `AF_INET` in POSIX. -

    • -
  • -

    ipv6

    -

    Similar to `AF_INET6` in POSIX. -

    • -
-

tuple ipv4-address

-
Tuple Fields
-
    -
  • 0: u8
    • -
  • 1: u8
    • -
  • 2: u8
    • -
  • 3: u8
    • -
-

tuple ipv6-address

-
Tuple Fields
-
    -
  • 0: u16
    • -
  • 1: u16
    • -
  • 2: u16
    • -
  • 3: u16
    • -
  • 4: u16
    • -
  • 5: u16
    • -
  • 6: u16
    • -
  • 7: u16
    • -
-

variant ip-address

-
Variant Cases
- -

record ipv4-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin_port -

    • -
  • -

    address: ipv4-address

    -

    sin_addr -

    • -
-

record ipv6-socket-address

-
Record Fields
-
    -
  • -

    port: u16

    -

    sin6_port -

    • -
  • -

    flow-info: u32

    -

    sin6_flowinfo -

    • -
  • -

    address: ipv6-address

    -

    sin6_addr -

    • -
  • -

    scope-id: u32

    -

    sin6_scope_id -

    • -
-

variant ip-socket-address

-
Variant Cases
- -
-

Functions

-

network-error-code: func

-

Attempts to extract a network-related error-code from the stream -error provided.

-

Stream operations which return stream-error::last-operation-failed -have a payload with more information about the operation that failed. -This payload can be passed through to this function to see if there's -network-related information about the error to return.

-

Note that this function is fallible because not all stream-related -errors are network-related errors.

-
Params
- -
Return values
- -

Import interface wasi:sockets/instance-network@0.2.12

-

This interface provides a value-export of the default network handle..

-
-

Types

-

type network

-

network

-

-

-

Functions

-

instance-network: func

-

Get a handle to the default network.

-
Return values
- -

Import interface wasi:io/poll@0.2.12

-

A poll API intended to let users wait for I/O events on multiple handles -at once.

-
-

Types

-

resource pollable

-

pollable represents a single I/O event which may be ready, or not.

-

Functions

-

[method]pollable.ready: func

-

Return the readiness of a pollable. This function never blocks.

-

Returns true when the pollable is ready, and false otherwise.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]pollable.block: func

-

block returns immediately if the pollable is ready, and otherwise -blocks until ready.

-

This function is equivalent to calling poll.poll on a list -containing only this pollable.

-
Params
- -

poll: func

-

Poll for completion on a set of pollables.

-

This function takes a list of pollables, which identify I/O sources of -interest, and waits until one or more of the events is ready for I/O.

-

The result list<u32> contains one or more indices of handles in the -argument list that is ready for I/O.

-

This function traps if either:

-
    -
  • the list is empty, or:
    • -
  • the list contains more elements than can be indexed with a u32 value.
    • -
-

A timeout can be implemented by adding a pollable from the -wasi-clocks API to the list.

-

This function does not return a result; polling in itself does not -do any I/O so it doesn't fail. If any of the I/O sources identified by -the pollables has an error, it is indicated by marking the source as -being ready for I/O.

-
Params
- -
Return values
-
    -
  • list<u32>
    • -
-

Import interface wasi:sockets/udp@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

record incoming-datagram

-

A received datagram.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.

    -
    • -
  • -

    remote-address: ip-socket-address

    -

    The source address. -

    This field is guaranteed to match the remote address the stream was initialized with, if any.

    -

    Equivalent to the src_addr out parameter of recvfrom.

    -
    • -
-

record outgoing-datagram

-

A datagram to be sent out.

-
Record Fields
-
    -
  • -

    data: list<u8>

    -

    The payload. -

    • -
  • -

    remote-address: option<ip-socket-address>

    -

    The destination address. -

    The requirements on this field depend on how the stream was initialized:

    -
      -
    • with a remote address: this field must be None or match the stream's remote address exactly.
      • -
    • without a remote address: this field is required.
      • -
    -

    If this value is None, the send operation is equivalent to send in POSIX. Otherwise it is equivalent to sendto.

    -
    • -
-

resource udp-socket

-

A UDP socket handle.

-

resource incoming-datagram-stream

-

resource outgoing-datagram-stream

-
-

Functions

-

[method]udp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the port is zero, the socket will be bound to a random free port.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]udp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]udp-socket.stream: func

-

Set up inbound & outbound communication channels, optionally to a specific peer.

-

This function only changes the local socket configuration and does not generate any network traffic. -On success, the remote-address of the socket is updated. The local-address may be updated as well, -based on the best network path to remote-address.

-

When a remote-address is provided, the returned streams are limited to communicating with that specific peer:

-
    -
  • send can only be used to send to this destination.
    • -
  • receive will only return datagrams sent from the provided remote-address.
    • -
-

This method may be called multiple times on the same socket to change its association, but -only the most recently returned pair of streams will be operational. Implementations may trap if -the streams returned by a previous invocation haven't been dropped yet before calling stream again.

-

The POSIX equivalent in pseudo-code is:

-
if (was previously connected) {
-  connect(s, AF_UNSPEC)
-}
-if (remote_address is Some) {
-  connect(s, remote_address)
-}
-
-

Unlike in POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-state: The socket is not bound.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.local-address: func

-

Get the current bound address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.remote-address: func

-

Get the address the socket is currently streaming to.

-

Typical errors

-
    -
  • invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]udp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]udp-socket.unicast-hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-unicast-hop-limit: func

-
Params
- -
Return values
- -

[method]udp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]udp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]udp-socket.subscribe: func

-

Create a pollable which will resolve once the socket is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]incoming-datagram-stream.receive: func

-

Receive messages on the socket.

-

This function attempts to receive up to max-results datagrams on the socket without blocking. -The returned list may contain fewer elements than requested, but never more.

-

This function returns successfully with an empty list when either:

-
    -
  • max-results is 0, or:
    • -
  • max-results is greater than 0, but no results are immediately available. -This function never returns error(would-block).
    • -
-

Typical errors

-
    -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
-

References

- -
Params
- -
Return values
- -

[method]incoming-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to receive again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.check-send: func

-

Check readiness for sending. This function never blocks.

-

Returns the number of datagrams permitted for the next call to send, -or an error. Calling send with more datagrams than this function has -permitted will trap.

-

When this function returns ok(0), the subscribe pollable will -become ready when this function will report at least ok(1), or an -error.

-

Never returns would-block.

-
Params
- -
Return values
- -

[method]outgoing-datagram-stream.send: func

-

Send messages on the socket.

-

This function attempts to send all provided datagrams on the socket without blocking and -returns how many messages were actually sent (or queued for sending). This function never -returns error(would-block). If none of the datagrams were able to be sent, ok(0) is returned.

-

This function semantically behaves the same as iterating the datagrams list and sequentially -sending each individual datagram until either the end of the list has been reached or the first error occurred. -If at least one datagram has been sent successfully, this function never returns an error.

-

If the input list is empty, the function returns ok(0).

-

Each call to send must be permitted by a preceding check-send. Implementations must trap if -either check-send was not called or datagrams contains more items than check-send permitted.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
    • -
  • invalid-argument: The socket is in "connected" mode and remote-address is some value that does not match the address passed to stream. (EISCONN)
    • -
  • invalid-argument: The socket is not "connected" and no value for remote-address was provided. (EDESTADDRREQ)
    • -
  • remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • connection-refused: The connection was refused. (ECONNREFUSED)
    • -
  • datagram-too-large: The datagram is too large. (EMSGSIZE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]outgoing-datagram-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready to send again.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

Import interface wasi:sockets/udp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type udp-socket

-

udp-socket

-

-

-

Functions

-

create-udp-socket: func

-

Create a new UDP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind is called, -the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References:

- -
Params
- -
Return values
- -

Import interface wasi:io/streams@0.2.12

-

WASI I/O is an I/O abstraction API which is currently focused on providing -stream types.

-

In the future, the component model is expected to add built-in stream types; -when it does, they are expected to subsume this API.

-
-

Types

-

type error

-

error

-

-

type pollable

-

pollable

-

-

variant stream-error

-

An error for input-stream and output-stream operations.

-
Variant Cases
-
    -
  • -

    last-operation-failed: own<error>

    -

    The last operation (a write or flush) failed before completion. -

    More information is available in the error payload.

    -

    After this, the stream will be closed. All future operations return -stream-error::closed.

    -
    • -
  • -

    closed

    -

    The stream is closed: no more input will be accepted by the -stream. A closed output-stream will return this error on all -future operations. -

    • -
-

resource input-stream

-

An input bytestream.

-

input-streams are non-blocking to the extent practical on underlying -platforms. I/O operations always return promptly; if fewer bytes are -promptly available than requested, they return the number of bytes promptly -available, which could even be zero. To wait for data to be available, -use the subscribe function to obtain a pollable which can be polled -for using wasi:io/poll.

-

resource output-stream

-

An output bytestream.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe function to obtain a pollable which can be -polled for using wasi:io/poll.

-

Dropping an output-stream while there's still an active write in -progress may result in the data being lost. Before dropping the stream, -be sure to fully flush your writes.

-

Functions

-

[method]input-stream.read: func

-

Perform a non-blocking read from the stream.

-

When the source of a read is binary data, the bytes from the source -are returned verbatim. When the source of a read is known to the -implementation to be text, bytes containing the UTF-8 encoding of the -text are returned.

-

This function returns a list of bytes containing the read data, -when successful. The returned list will contain up to len bytes; -it may return fewer than requested, but not more. The list is -empty when no bytes are available for reading at this time. The -pollable given by subscribe will be ready when more bytes are -available.

-

This function fails with a stream-error when the operation -encounters an error, giving last-operation-failed, or when the -stream is closed, giving closed.

-

When the caller gives a len of 0, it represents a request to -read 0 bytes. If the stream is still open, this call should -succeed and return an empty list, or otherwise fail with closed.

-

The len parameter is a u64, which could represent a list of u8 which -is not possible to allocate in wasm32, or not desirable to allocate as -as a return value by the callee. The callee may return a list of bytes -less than len in size while more bytes are available for reading.

-
Params
- -
Return values
- -

[method]input-stream.blocking-read: func

-

Read bytes from a stream, after blocking until at least one byte can -be read. Except for blocking, behavior is identical to read.

-
Params
- -
Return values
- -

[method]input-stream.skip: func

-

Skip bytes from a stream. Returns number of bytes skipped.

-

Behaves identical to read, except instead of returning a list -of bytes, returns the number of bytes consumed from the stream.

-
Params
- -
Return values
- -

[method]input-stream.blocking-skip: func

-

Skip bytes from a stream, after blocking until at least one byte -can be skipped. Except for blocking behavior, identical to skip.

-
Params
- -
Return values
- -

[method]input-stream.subscribe: func

-

Create a pollable which will resolve once either the specified stream -has bytes available to read or the other end of the stream has been -closed. -The created pollable is a child resource of the input-stream. -Implementations may trap if the input-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.check-write: func

-

Check readiness for writing. This function never blocks.

-

Returns the number of bytes permitted for the next call to write, -or an error. Calling write with more bytes than this function has -permitted will trap.

-

When this function returns 0 bytes, the subscribe pollable will -become ready when this function will report at least 1 byte, or an -error.

-
Params
- -
Return values
- -

[method]output-stream.write: func

-

Perform a write. This function never blocks.

-

When the destination of a write is binary data, the bytes from -contents are written verbatim. When the destination of a write is -known to the implementation to be text, the bytes of contents are -transcoded from UTF-8 into the encoding of the destination and then -written.

-

Precondition: check-write gave permit of Ok(n) and contents has a -length of less than or equal to n. Otherwise, this function will trap.

-

returns Err(closed) without writing if the stream has closed since -the last call to check-write provided a permit.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-and-flush: func

-

Perform a write of up to 4096 bytes, and then flush the stream. Block -until all of these operations are complete, or an error occurs.

-

Returns success when all of the contents written are successfully -flushed to output. If an error occurs at any point before all -contents are successfully flushed, that error is returned as soon as -possible. If writing and flushing the complete contents causes the -stream to become closed, this call should return success, and -subsequent calls to check-write or other interfaces should return -stream-error::closed.

-
Params
- -
Return values
- -

[method]output-stream.flush: func

-

Request to flush buffered output. This function never blocks.

-

This tells the output-stream that the caller intends any buffered -output to be flushed. the output which is expected to be flushed -is all that has been passed to write prior to this call.

-

Upon calling this function, the output-stream will not accept any -writes (check-write will return ok(0)) until the flush has -completed. The subscribe pollable will become ready when the -flush has completed and the stream can accept more writes.

-
Params
- -
Return values
- -

[method]output-stream.blocking-flush: func

-

Request to flush buffered output, and block until flush completes -and stream is ready for writing again.

-
Params
- -
Return values
- -

[method]output-stream.subscribe: func

-

Create a pollable which will resolve once the output-stream -is ready for more writing, or an error has occurred. When this -pollable is ready, check-write will return ok(n) with n>0, or an -error.

-

If the stream is closed, this pollable is always ready immediately.

-

The created pollable is a child resource of the output-stream. -Implementations may trap if the output-stream is dropped before -all derived pollables created with this function are dropped.

-
Params
- -
Return values
- -

[method]output-stream.write-zeroes: func

-

Write zeroes to a stream.

-

This should be used precisely like write with the exact same -preconditions (must use check-write first), but instead of -passing a list of bytes, you simply pass the number of zero-bytes -that should be written.

-
Params
- -
Return values
- -

[method]output-stream.blocking-write-zeroes-and-flush: func

-

Perform a write of up to 4096 zeroes, and then flush the stream. -Block until all of these operations are complete, or an error -occurs.

-

Functionality is equivelant to blocking-write-and-flush with -contents given as a list of len containing only zeroes.

-
Params
- -
Return values
- -

[method]output-stream.splice: func

-

Read from one stream and write to another.

-

The behavior of splice is equivalent to:

-
    -
  1. calling check-write on the output-stream
    2. -
  2. calling read on the input-stream with the smaller of the -check-write permitted length and the len provided to splice
    3. -
  3. calling write on the output-stream with that read data.
    4. -
-

Any error reported by the call to check-write, read, or -write ends the splice and reports that error.

-

This function returns the number of bytes transferred; it may be less -than len.

-
Params
- -
Return values
- -

[method]output-stream.blocking-splice: func

-

Read from one stream and write to another, with blocking.

-

This is similar to splice, except that it blocks until the -output-stream is ready for writing, and the input-stream -is ready for reading, before performing the splice.

-
Params
- -
Return values
- -

Import interface wasi:clocks/monotonic-clock@0.2.12

-

WASI Monotonic Clock is a clock API intended to let users measure elapsed -time.

-

It is intended to be portable at least between Unix-family platforms and -Windows.

-

A monotonic clock is a clock which has an unspecified initial value, and -successive reads of the clock will produce non-decreasing values.

-
-

Types

-

type pollable

-

pollable

-

-

type instant

-

u64

-

An instant in time, in nanoseconds. An instant is relative to an -unspecified initial value, and can only be compared to instances from -the same monotonic-clock. -

type duration

-

u64

-

A duration of time, in nanoseconds. -

-

Functions

-

now: func

-

Read the current value of the clock.

-

The clock is monotonic, therefore calling this function repeatedly will -produce a sequence of non-decreasing values.

-

For completeness, this function traps if it's not possible to represent -the value of the clock in an instant. Consequently, implementations -should ensure that the starting time is low enough to avoid the -possibility of overflow in practice.

-
Return values
- -

resolution: func

-

Query the resolution of the clock. Returns the duration of time -corresponding to a clock tick.

-
Return values
- -

subscribe-instant: func

-

Create a pollable which will resolve once the specified instant -has occurred.

-
Params
- -
Return values
- -

subscribe-duration: func

-

Create a pollable that will resolve after the specified duration has -elapsed from the time this function is invoked.

-
Params
- -
Return values
- -

Import interface wasi:sockets/tcp@0.2.12

-
-

Types

-

type input-stream

-

input-stream

-

-

type output-stream

-

output-stream

-

-

type pollable

-

pollable

-

-

type duration

-

duration

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-socket-address

-

ip-socket-address

-

-

type ip-address-family

-

ip-address-family

-

-

enum shutdown-type

-
Enum Cases
-
    -
  • -

    receive

    -

    Similar to `SHUT_RD` in POSIX. -

    • -
  • -

    send

    -

    Similar to `SHUT_WR` in POSIX. -

    • -
  • -

    both

    -

    Similar to `SHUT_RDWR` in POSIX. -

    • -
-

resource tcp-socket

-

A TCP socket resource.

-

The socket can be in one of the following states:

- -

Note: Except where explicitly mentioned, whenever this documentation uses -the term "bound" without backticks it actually means: in the bound state or higher. -(i.e. bound, listen-in-progress, listening, connect-in-progress or connected)

-

In addition to the general error codes documented on the -network::error-code type, TCP socket methods may always return -error(invalid-state) when in the closed state.

-

Functions

-

[method]tcp-socket.start-bind: func

-

Bind the socket to a specific network on the provided IP address and port.

-

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which -network interface(s) to bind to. -If the TCP/UDP port is zero, the socket will be bound to a random free port.

-

Bind can be attempted multiple times on the same socket, even with -different arguments on each iteration. But never concurrently and -only as long as the previous bind failed. Once a bind succeeds, the -binding can't be changed anymore.

-

Typical errors

-
    -
  • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • -
  • invalid-argument: local-address is not a unicast address. (EINVAL)
    • -
  • invalid-argument: local-address is an IPv4-mapped IPv6 address. (EINVAL)
    • -
  • invalid-state: The socket is already bound. (EINVAL)
    • -
  • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • -
  • address-in-use: Address is already in use. (EADDRINUSE)
    • -
  • address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
    • -
  • not-in-progress: A bind operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT -state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR -socket option should be set implicitly on all platforms, except on Windows where this is the default behavior -and SO_REUSEADDR performs something different entirely.

-

Unlike in POSIX, in WASI the bind operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -bind as part of either start-bind or finish-bind.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-bind: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-connect: func

-

Connect to a remote endpoint.

-

On success:

-
    -
  • the socket is transitioned into the connected state.
    • -
  • a pair of streams is returned that can be used to read & write to the connection
    • -
-

After a failed connection attempt, the socket will be in the closed -state and the only valid action left is to drop the socket. A single -socket can not be used to connect more than once.

-

Typical errors

-
    -
  • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • -
  • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • -
  • invalid-argument: remote-address is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
    • -
  • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • -
  • invalid-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN)
    • -
  • invalid-state: The socket is already in the listening state. (EOPNOTSUPP, EINVAL on Windows)
    • -
  • timeout: Connection timed out. (ETIMEDOUT)
    • -
  • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • -
  • connection-reset: The connection was reset. (ECONNRESET)
    • -
  • connection-aborted: The connection was aborted. (ECONNABORTED)
    • -
  • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
    • -
  • not-in-progress: A connect operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

The POSIX equivalent of start-connect is the regular connect syscall. -Because all WASI sockets are non-blocking this is expected to return -EINPROGRESS, which should be translated to ok() in WASI.

-

The POSIX equivalent of finish-connect is a poll for event POLLOUT -with a timeout of 0 on the socket descriptor. Followed by a check for -the SO_ERROR socket option, in case the poll signaled readiness.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-connect: func

-
Params
- -
Return values
- -

[method]tcp-socket.start-listen: func

-

Start listening for new connections.

-

Transitions the socket into the listening state.

-

Unlike POSIX, the socket must already be explicitly bound.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address. (EDESTADDRREQ)
    • -
  • invalid-state: The socket is already in the connected state. (EISCONN, EINVAL on BSD)
    • -
  • invalid-state: The socket is already in the listening state.
    • -
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
    • -
  • not-in-progress: A listen operation is not in progress.
    • -
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
    • -
-

Implementors note

-

Unlike in POSIX, in WASI the listen operation is async. This enables -interactive WASI hosts to inject permission prompts. Runtimes that -don't want to make use of this ability can simply call the native -listen as part of either start-listen or finish-listen.

-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.finish-listen: func

-
Params
- -
Return values
- -

[method]tcp-socket.accept: func

-

Accept a new client socket.

-

The returned socket is bound and in the connected state. The following properties are inherited from the listener socket:

-
    -
  • address-family
    • -
  • keep-alive-enabled
    • -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count
    • -
  • hop-limit
    • -
  • receive-buffer-size
    • -
  • send-buffer-size
    • -
-

On success, this function returns the newly accepted client socket along with -a pair of streams that can be used to read & write to the connection.

-

Typical errors

-
    -
  • invalid-state: Socket is not in the listening state. (EINVAL)
    • -
  • would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
    • -
  • connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.local-address: func

-

Get the bound local address.

-

POSIX mentions:

-
-

If the socket has not been bound to a local name, the value -stored in the object pointed to by address is unspecified.

-
-

WASI is stricter and requires local-address to return invalid-state when the socket hasn't been bound yet.

-

Typical errors

-
    -
  • invalid-state: The socket is not bound to any local address.
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.remote-address: func

-

Get the remote address.

-

Typical errors

-
    -
  • invalid-state: The socket is not connected to a remote address. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

[method]tcp-socket.is-listening: func

-

Whether the socket is in the listening state.

-

Equivalent to the SO_ACCEPTCONN socket option.

-
Params
- -
Return values
-
    -
  • bool
    • -
-

[method]tcp-socket.address-family: func

-

Whether this is a IPv4 or IPv6 socket.

-

Equivalent to the SO_DOMAIN socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-listen-backlog-size: func

-

Hints the desired listen queue size. Implementations are free to ignore this.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded.

-

Typical errors

-
    -
  • not-supported: (set) The platform does not support changing the backlog size after the initial listen.
    • -
  • invalid-argument: (set) The provided value was 0.
    • -
  • invalid-state: (set) The socket is in the connect-in-progress or connected state.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-enabled: func

-

Enables or disables keepalive.

-

The keepalive behavior can be adjusted using:

-
    -
  • keep-alive-idle-time
    • -
  • keep-alive-interval
    • -
  • keep-alive-count -These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.
    • -
-

Equivalent to the SO_KEEPALIVE socket option.

-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-enabled: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-idle-time: func

-

Amount of time the connection has to be idle before TCP starts sending keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-idle-time: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-interval: func

-

The time between keepalive packets.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPINTVL socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-interval: func

-
Params
- -
Return values
- -

[method]tcp-socket.keep-alive-count: func

-

The maximum amount of keepalive packets TCP should send before aborting the connection.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the TCP_KEEPCNT socket option.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-keep-alive-count: func

-
Params
- -
Return values
- -

[method]tcp-socket.hop-limit: func

-

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

-

If the provided value is 0, an invalid-argument error is returned.

-

Typical errors

-
    -
  • invalid-argument: (set) The TTL value must be 1 or higher.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-hop-limit: func

-
Params
- -
Return values
- -

[method]tcp-socket.receive-buffer-size: func

-

The kernel buffer space reserved for sends/receives on this socket.

-

If the provided value is 0, an invalid-argument error is returned. -Any other value will never cause an error, but it might be silently clamped and/or rounded. -I.e. after setting a value, reading the same setting back may return a different value.

-

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

-

Typical errors

-
    -
  • invalid-argument: (set) The provided value was 0.
    • -
-
Params
- -
Return values
- -

[method]tcp-socket.set-receive-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.set-send-buffer-size: func

-
Params
- -
Return values
- -

[method]tcp-socket.subscribe: func

-

Create a pollable which can be used to poll for, or block on, -completion of any of the asynchronous operations of this socket.

-

When finish-bind, finish-listen, finish-connect or accept -return error(would-block), this pollable can be used to wait for -their success or failure, after which the method can be retried.

-

The pollable is not limited to the async operation that happens to be -in progress at the time of calling subscribe (if any). Theoretically, -subscribe only has to be called once per socket and can then be -(re)used for the remainder of the socket's lifetime.

-

See https://github.com/WebAssembly/WASI/blob/main/proposals/sockets/TcpSocketOperationalSemantics.md#pollable-readiness -for more information.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- -

[method]tcp-socket.shutdown: func

-

Initiate a graceful shutdown.

-
    -
  • receive: The socket is not expecting to receive any data from -the peer. The input-stream associated with this socket will be -closed. Any data still in the receive queue at time of calling -this method will be discarded.
    • -
  • send: The socket has no more data to send to the peer. The output-stream -associated with this socket will be closed and a FIN packet will be sent.
    • -
  • both: Same effect as receive & send combined.
    • -
-

This function is idempotent; shutting down a direction more than once -has no effect and returns ok.

-

The shutdown function does not close (drop) the socket.

-

Typical errors

-
    -
  • invalid-state: The socket is not in the connected state. (ENOTCONN)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/tcp-create-socket@0.2.12

-
-

Types

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address-family

-

ip-address-family

-

-

type tcp-socket

-

tcp-socket

-

-

-

Functions

-

create-tcp-socket: func

-

Create a new TCP socket.

-

Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. -On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

-

This function does not require a network capability handle. This is considered to be safe because -at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect -is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

-

All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

-

Typical errors

-
    -
  • not-supported: The specified address-family is not supported. (EAFNOSUPPORT)
    • -
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
    • -
-

References

- -
Params
- -
Return values
- -

Import interface wasi:sockets/ip-name-lookup@0.2.12

-
-

Types

-

type pollable

-

pollable

-

-

type network

-

network

-

-

type error-code

-

error-code

-

-

type ip-address

-

ip-address

-

-

resource resolve-address-stream

-
-

Functions

-

resolve-addresses: func

-

Resolve an internet host name to a list of IP addresses.

-

Unicode domain names are automatically converted to ASCII using IDNA encoding. -If the input is an IP address string, the address is parsed and returned -as-is without making any external requests.

-

See the wasi-socket proposal README.md for a comparison with getaddrinfo.

-

This function never blocks. It either immediately fails or immediately -returns successfully with a resolve-address-stream that can be used -to (asynchronously) fetch the results.

-

Typical errors

-
    -
  • invalid-argument: name is a syntactically invalid domain name or IP address.
    • -
-

References:

- -
Params
- -
Return values
- -

[method]resolve-address-stream.resolve-next-address: func

-

Returns the next address from the resolver.

-

This function should be called multiple times. On each call, it will -return the next address in connection order preference. If all -addresses have been exhausted, this function returns none.

-

This function never returns IPv4-mapped IPv6 addresses.

-

Typical errors

-
    -
  • name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
    • -
  • temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)
    • -
  • permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)
    • -
  • would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)
    • -
-
Params
- -
Return values
- -

[method]resolve-address-stream.subscribe: func

-

Create a pollable which will resolve once the stream is ready for I/O.

-

Note: this function is here for WASI 0.2 only. -It's planned to be removed when future is natively supported in Preview3.

-
Params
- -
Return values
- diff --git a/proposals/sockets/wit-0.3.0-draft/deps.lock b/proposals/sockets/wit-0.3.0-draft/deps.lock deleted file mode 100644 index a780d3df7..000000000 --- a/proposals/sockets/wit-0.3.0-draft/deps.lock +++ /dev/null @@ -1,4 +0,0 @@ -[clocks] -path = "../../clocks/wit-0.3.0-draft" -sha256 = "a8702c42e23c22a458207d0efa38cc1b64c8c6299b0e3152aa84327a7c1c952b" -sha512 = "da69a5d498b6afe0facf77ec3d21f6e8a2a4d4661ebfec310a2ce6f943cb01f92131a746765648febf96563ddac788e9f218941d3db2b905f3746dc8e05cf54d" diff --git a/proposals/sockets/wit-0.3.0-draft/deps.toml b/proposals/sockets/wit-0.3.0-draft/deps.toml deleted file mode 100644 index c54398c1a..000000000 --- a/proposals/sockets/wit-0.3.0-draft/deps.toml +++ /dev/null @@ -1 +0,0 @@ -clocks = "../../clocks/wit-0.3.0-draft" diff --git a/proposals/sockets/wit-0.3.0-draft/ip-name-lookup.wit b/proposals/sockets/wit-0.3.0-draft/ip-name-lookup.wit deleted file mode 100644 index 2e9c9fe0a..000000000 --- a/proposals/sockets/wit-0.3.0-draft/ip-name-lookup.wit +++ /dev/null @@ -1,61 +0,0 @@ -@since(version = 0.3.0-rc-2026-03-15) -interface ip-name-lookup { - @since(version = 0.3.0-rc-2026-03-15) - use types.{ip-address}; - - /// Lookup error codes. - @since(version = 0.3.0-rc-2026-03-15) - variant error-code { - /// Access denied. - /// - /// POSIX equivalent: EACCES, EPERM - access-denied, - - /// `name` is a syntactically invalid domain name or IP address. - /// - /// POSIX equivalent: EINVAL - invalid-argument, - - /// Name does not exist or has no suitable associated IP addresses. - /// - /// POSIX equivalent: EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY - name-unresolvable, - - /// A temporary failure in name resolution occurred. - /// - /// POSIX equivalent: EAI_AGAIN - temporary-resolver-failure, - - /// A permanent failure in name resolution occurred. - /// - /// POSIX equivalent: EAI_FAIL - permanent-resolver-failure, - - /// A catch-all for errors not captured by the existing variants. - /// Implementations can use this to extend the error type without - /// breaking existing code. - other(option), - } - - /// Resolve an internet host name to a list of IP addresses. - /// - /// Unicode domain names are automatically converted to ASCII using IDNA - /// encoding. If the input is an IP address string, the address is parsed - /// and returned as-is without making any external requests. - /// - /// See the wasi-socket proposal README.md for a comparison with getaddrinfo. - /// - /// The results are returned in connection order preference. - /// - /// This function never succeeds with 0 results. It either fails or succeeds - /// with at least one address. Additionally, this function never returns - /// IPv4-mapped IPv6 addresses. - /// - /// # References: - /// - - /// - - /// - - /// - - @since(version = 0.3.0-rc-2026-03-15) - resolve-addresses: async func(name: string) -> result, error-code>; -} diff --git a/proposals/sockets/wit-0.3.0-draft/world.wit b/proposals/sockets/wit-0.3.0-draft/world.wit deleted file mode 100644 index 227662dab..000000000 --- a/proposals/sockets/wit-0.3.0-draft/world.wit +++ /dev/null @@ -1,9 +0,0 @@ -package wasi:sockets@0.3.0-rc-2026-03-15; - -@since(version = 0.3.0-rc-2026-03-15) -world imports { - @since(version = 0.3.0-rc-2026-03-15) - import types; - @since(version = 0.3.0-rc-2026-03-15) - import ip-name-lookup; -} diff --git a/proposals/sockets/wit/deps.lock b/proposals/sockets/wit/deps.lock index a3b6ab01e..7e6404b9a 100644 --- a/proposals/sockets/wit/deps.lock +++ b/proposals/sockets/wit/deps.lock @@ -1,9 +1,4 @@ [clocks] path = "../../clocks/wit" -sha256 = "85b95504b5f627086433c75a634ef86cc5a346f000acd158b94cb01d508b1992" -sha512 = "b2ba12c17a022788a9ed0d1a11bd605c579ab9614edd6ba02ba6ae59e4265ed02dff718b374181be4fc7c60e0e44d0ef65ab9ddda559f2b75ccc5ca2bb6d7b9f" - -[io] -path = "../../io/wit" -sha256 = "b45dcb3986b694bd2de3b4c092ee3cc3b0e7c654a93e5dee0c5b32e349d1b0d8" -sha512 = "08ab049d3887d12bd5ae650703b325fd5d26a340e7e6f53c77c5ecfefa79d3b9c61801b6eb00872ecd91f74572ef5684b0850721c715b4062158e00fae6c1dc2" +sha256 = "2d288cb781c60ae462537b39e4699de38f88072b501fc7f97d3f20984d550bcf" +sha512 = "1563eeeacbfea89e44f668b8588ef95b31feac7d9ec3bb5dad932320478b1aff1448031f44afa15ed926981855ac5bd504126389ddb7802f79c63b81b3c5ede7" diff --git a/proposals/sockets/wit/deps.toml b/proposals/sockets/wit/deps.toml index 741861bee..942f72d1c 100644 --- a/proposals/sockets/wit/deps.toml +++ b/proposals/sockets/wit/deps.toml @@ -1,2 +1 @@ clocks = "../../clocks/wit" -io = "../../io/wit" diff --git a/proposals/sockets/wit/instance-network.wit b/proposals/sockets/wit/instance-network.wit deleted file mode 100644 index 5f6e6c1cc..000000000 --- a/proposals/sockets/wit/instance-network.wit +++ /dev/null @@ -1,11 +0,0 @@ - -/// This interface provides a value-export of the default network handle.. -@since(version = 0.2.0) -interface instance-network { - @since(version = 0.2.0) - use network.{network}; - - /// Get a handle to the default network. - @since(version = 0.2.0) - instance-network: func() -> network; -} diff --git a/proposals/sockets/wit/ip-name-lookup.wit b/proposals/sockets/wit/ip-name-lookup.wit index 119b731af..2cc6cea99 100644 --- a/proposals/sockets/wit/ip-name-lookup.wit +++ b/proposals/sockets/wit/ip-name-lookup.wit @@ -1,56 +1,61 @@ -@since(version = 0.2.0) +@since(version = 0.3.0) interface ip-name-lookup { - @since(version = 0.2.0) - use wasi:io/poll@0.2.12.{pollable}; - @since(version = 0.2.0) - use network.{network, error-code, ip-address}; + @since(version = 0.3.0) + use types.{ip-address}; + + /// Lookup error codes. + @since(version = 0.3.0) + variant error-code { + /// Access denied. + /// + /// POSIX equivalent: EACCES, EPERM + access-denied, + + /// `name` is a syntactically invalid domain name or IP address. + /// + /// POSIX equivalent: EINVAL + invalid-argument, + + /// Name does not exist or has no suitable associated IP addresses. + /// + /// POSIX equivalent: EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY + name-unresolvable, + + /// A temporary failure in name resolution occurred. + /// + /// POSIX equivalent: EAI_AGAIN + temporary-resolver-failure, + + /// A permanent failure in name resolution occurred. + /// + /// POSIX equivalent: EAI_FAIL + permanent-resolver-failure, + + /// A catch-all for errors not captured by the existing variants. + /// Implementations can use this to extend the error type without + /// breaking existing code. + other(option), + } /// Resolve an internet host name to a list of IP addresses. /// - /// Unicode domain names are automatically converted to ASCII using IDNA encoding. - /// If the input is an IP address string, the address is parsed and returned - /// as-is without making any external requests. + /// Unicode domain names are automatically converted to ASCII using IDNA + /// encoding. If the input is an IP address string, the address is parsed + /// and returned as-is without making any external requests. /// /// See the wasi-socket proposal README.md for a comparison with getaddrinfo. /// - /// This function never blocks. It either immediately fails or immediately - /// returns successfully with a `resolve-address-stream` that can be used - /// to (asynchronously) fetch the results. + /// The results are returned in connection order preference. /// - /// # Typical errors - /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address. + /// This function never succeeds with 0 results. It either fails or succeeds + /// with at least one address. Additionally, this function never returns + /// IPv4-mapped IPv6 addresses. /// /// # References: /// - /// - /// - /// - - @since(version = 0.2.0) - resolve-addresses: func(network: borrow, name: string) -> result; - - @since(version = 0.2.0) - resource resolve-address-stream { - /// Returns the next address from the resolver. - /// - /// This function should be called multiple times. On each call, it will - /// return the next address in connection order preference. If all - /// addresses have been exhausted, this function returns `none`. - /// - /// This function never returns IPv4-mapped IPv6 addresses. - /// - /// # Typical errors - /// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY) - /// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN) - /// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL) - /// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN) - @since(version = 0.2.0) - resolve-next-address: func() -> result, error-code>; - - /// Create a `pollable` which will resolve once the stream is ready for I/O. - /// - /// Note: this function is here for WASI 0.2 only. - /// It's planned to be removed when `future` is natively supported in Preview3. - @since(version = 0.2.0) - subscribe: func() -> pollable; - } + @since(version = 0.3.0) + resolve-addresses: async func(name: string) -> result, error-code>; } diff --git a/proposals/sockets/wit/network.wit b/proposals/sockets/wit/network.wit deleted file mode 100644 index fd6138fca..000000000 --- a/proposals/sockets/wit/network.wit +++ /dev/null @@ -1,169 +0,0 @@ -@since(version = 0.2.0) -interface network { - @unstable(feature = network-error-code) - use wasi:io/error@0.2.12.{error}; - - /// An opaque resource that represents access to (a subset of) the network. - /// This enables context-based security for networking. - /// There is no need for this to map 1:1 to a physical network interface. - @since(version = 0.2.0) - resource network; - - /// Error codes. - /// - /// In theory, every API can return any error code. - /// In practice, API's typically only return the errors documented per API - /// combined with a couple of errors that are always possible: - /// - `unknown` - /// - `access-denied` - /// - `not-supported` - /// - `out-of-memory` - /// - `concurrency-conflict` - /// - /// See each individual API for what the POSIX equivalents are. They sometimes differ per API. - @since(version = 0.2.0) - enum error-code { - /// Unknown error - unknown, - - /// Access denied. - /// - /// POSIX equivalent: EACCES, EPERM - access-denied, - - /// The operation is not supported. - /// - /// POSIX equivalent: EOPNOTSUPP - not-supported, - - /// One of the arguments is invalid. - /// - /// POSIX equivalent: EINVAL - invalid-argument, - - /// Not enough memory to complete the operation. - /// - /// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY - out-of-memory, - - /// The operation timed out before it could finish completely. - timeout, - - /// This operation is incompatible with another asynchronous operation that is already in progress. - /// - /// POSIX equivalent: EALREADY - concurrency-conflict, - - /// Trying to finish an asynchronous operation that: - /// - has not been started yet, or: - /// - was already finished by a previous `finish-*` call. - /// - /// Note: this is scheduled to be removed when `future`s are natively supported. - not-in-progress, - - /// The operation has been aborted because it could not be completed immediately. - /// - /// Note: this is scheduled to be removed when `future`s are natively supported. - would-block, - - - /// The operation is not valid in the socket's current state. - invalid-state, - - /// A new socket resource could not be created because of a system limit. - new-socket-limit, - - /// A bind operation failed because the provided address is not an address that the `network` can bind to. - address-not-bindable, - - /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available. - address-in-use, - - /// The remote address is not reachable - remote-unreachable, - - - /// The TCP connection was forcefully rejected - connection-refused, - - /// The TCP connection was reset. - connection-reset, - - /// A TCP connection was aborted. - connection-aborted, - - - /// The size of a datagram sent to a UDP socket exceeded the maximum - /// supported size. - datagram-too-large, - - - /// Name does not exist or has no suitable associated IP addresses. - name-unresolvable, - - /// A temporary failure in name resolution occurred. - temporary-resolver-failure, - - /// A permanent failure in name resolution occurred. - permanent-resolver-failure, - } - - /// Attempts to extract a network-related `error-code` from the stream - /// `error` provided. - /// - /// Stream operations which return `stream-error::last-operation-failed` - /// have a payload with more information about the operation that failed. - /// This payload can be passed through to this function to see if there's - /// network-related information about the error to return. - /// - /// Note that this function is fallible because not all stream-related - /// errors are network-related errors. - @unstable(feature = network-error-code) - network-error-code: func(err: borrow) -> option; - - @since(version = 0.2.0) - enum ip-address-family { - /// Similar to `AF_INET` in POSIX. - ipv4, - - /// Similar to `AF_INET6` in POSIX. - ipv6, - } - - @since(version = 0.2.0) - type ipv4-address = tuple; - @since(version = 0.2.0) - type ipv6-address = tuple; - - @since(version = 0.2.0) - variant ip-address { - ipv4(ipv4-address), - ipv6(ipv6-address), - } - - @since(version = 0.2.0) - record ipv4-socket-address { - /// sin_port - port: u16, - /// sin_addr - address: ipv4-address, - } - - @since(version = 0.2.0) - record ipv6-socket-address { - /// sin6_port - port: u16, - /// sin6_flowinfo - flow-info: u32, - /// sin6_addr - address: ipv6-address, - /// sin6_scope_id - scope-id: u32, - } - - @since(version = 0.2.0) - variant ip-socket-address { - ipv4(ipv4-socket-address), - ipv6(ipv6-socket-address), - } -} diff --git a/proposals/sockets/wit/tcp-create-socket.wit b/proposals/sockets/wit/tcp-create-socket.wit deleted file mode 100644 index eedbd3076..000000000 --- a/proposals/sockets/wit/tcp-create-socket.wit +++ /dev/null @@ -1,30 +0,0 @@ -@since(version = 0.2.0) -interface tcp-create-socket { - @since(version = 0.2.0) - use network.{network, error-code, ip-address-family}; - @since(version = 0.2.0) - use tcp.{tcp-socket}; - - /// Create a new TCP socket. - /// - /// Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX. - /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise. - /// - /// This function does not require a network capability handle. This is considered to be safe because - /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`connect` - /// is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world. - /// - /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations. - /// - /// # Typical errors - /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT) - /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - create-tcp-socket: func(address-family: ip-address-family) -> result; -} diff --git a/proposals/sockets/wit/tcp.wit b/proposals/sockets/wit/tcp.wit deleted file mode 100644 index c9c58cb42..000000000 --- a/proposals/sockets/wit/tcp.wit +++ /dev/null @@ -1,387 +0,0 @@ -@since(version = 0.2.0) -interface tcp { - @since(version = 0.2.0) - use wasi:io/streams@0.2.12.{input-stream, output-stream}; - @since(version = 0.2.0) - use wasi:io/poll@0.2.12.{pollable}; - @since(version = 0.2.0) - use wasi:clocks/monotonic-clock@0.2.12.{duration}; - @since(version = 0.2.0) - use network.{network, error-code, ip-socket-address, ip-address-family}; - - @since(version = 0.2.0) - enum shutdown-type { - /// Similar to `SHUT_RD` in POSIX. - receive, - - /// Similar to `SHUT_WR` in POSIX. - send, - - /// Similar to `SHUT_RDWR` in POSIX. - both, - } - - /// A TCP socket resource. - /// - /// The socket can be in one of the following states: - /// - `unbound` - /// - `bind-in-progress` - /// - `bound` (See note below) - /// - `listen-in-progress` - /// - `listening` - /// - `connect-in-progress` - /// - `connected` - /// - `closed` - /// See - /// for more information. - /// - /// Note: Except where explicitly mentioned, whenever this documentation uses - /// the term "bound" without backticks it actually means: in the `bound` state *or higher*. - /// (i.e. `bound`, `listen-in-progress`, `listening`, `connect-in-progress` or `connected`) - /// - /// In addition to the general error codes documented on the - /// `network::error-code` type, TCP socket methods may always return - /// `error(invalid-state)` when in the `closed` state. - @since(version = 0.2.0) - resource tcp-socket { - /// Bind the socket to a specific network on the provided IP address and port. - /// - /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which - /// network interface(s) to bind to. - /// If the TCP/UDP port is zero, the socket will be bound to a random free port. - /// - /// Bind can be attempted multiple times on the same socket, even with - /// different arguments on each iteration. But never concurrently and - /// only as long as the previous bind failed. Once a bind succeeds, the - /// binding can't be changed anymore. - /// - /// # Typical errors - /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows) - /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL) - /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL) - /// - `invalid-state`: The socket is already bound. (EINVAL) - /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows) - /// - `address-in-use`: Address is already in use. (EADDRINUSE) - /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL) - /// - `not-in-progress`: A `bind` operation is not in progress. - /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN) - /// - /// # Implementors note - /// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT - /// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR - /// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior - /// and SO_REUSEADDR performs something different entirely. - /// - /// Unlike in POSIX, in WASI the bind operation is async. This enables - /// interactive WASI hosts to inject permission prompts. Runtimes that - /// don't want to make use of this ability can simply call the native - /// `bind` as part of either `start-bind` or `finish-bind`. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - start-bind: func(network: borrow, local-address: ip-socket-address) -> result<_, error-code>; - @since(version = 0.2.0) - finish-bind: func() -> result<_, error-code>; - - /// Connect to a remote endpoint. - /// - /// On success: - /// - the socket is transitioned into the `connected` state. - /// - a pair of streams is returned that can be used to read & write to the connection - /// - /// After a failed connection attempt, the socket will be in the `closed` - /// state and the only valid action left is to `drop` the socket. A single - /// socket can not be used to connect more than once. - /// - /// # Typical errors - /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT) - /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS) - /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos) - /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows) - /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows) - /// - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`. - /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN) - /// - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows) - /// - `timeout`: Connection timed out. (ETIMEDOUT) - /// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED) - /// - `connection-reset`: The connection was reset. (ECONNRESET) - /// - `connection-aborted`: The connection was aborted. (ECONNABORTED) - /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET) - /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD) - /// - `not-in-progress`: A connect operation is not in progress. - /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN) - /// - /// # Implementors note - /// The POSIX equivalent of `start-connect` is the regular `connect` syscall. - /// Because all WASI sockets are non-blocking this is expected to return - /// EINPROGRESS, which should be translated to `ok()` in WASI. - /// - /// The POSIX equivalent of `finish-connect` is a `poll` for event `POLLOUT` - /// with a timeout of 0 on the socket descriptor. Followed by a check for - /// the `SO_ERROR` socket option, in case the poll signaled readiness. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - start-connect: func(network: borrow, remote-address: ip-socket-address) -> result<_, error-code>; - @since(version = 0.2.0) - finish-connect: func() -> result, error-code>; - - /// Start listening for new connections. - /// - /// Transitions the socket into the `listening` state. - /// - /// Unlike POSIX, the socket must already be explicitly bound. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ) - /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD) - /// - `invalid-state`: The socket is already in the `listening` state. - /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE) - /// - `not-in-progress`: A listen operation is not in progress. - /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN) - /// - /// # Implementors note - /// Unlike in POSIX, in WASI the listen operation is async. This enables - /// interactive WASI hosts to inject permission prompts. Runtimes that - /// don't want to make use of this ability can simply call the native - /// `listen` as part of either `start-listen` or `finish-listen`. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - start-listen: func() -> result<_, error-code>; - @since(version = 0.2.0) - finish-listen: func() -> result<_, error-code>; - - /// Accept a new client socket. - /// - /// The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket: - /// - `address-family` - /// - `keep-alive-enabled` - /// - `keep-alive-idle-time` - /// - `keep-alive-interval` - /// - `keep-alive-count` - /// - `hop-limit` - /// - `receive-buffer-size` - /// - `send-buffer-size` - /// - /// On success, this function returns the newly accepted client socket along with - /// a pair of streams that can be used to read & write to the connection. - /// - /// # Typical errors - /// - `invalid-state`: Socket is not in the `listening` state. (EINVAL) - /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN) - /// - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED) - /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - accept: func() -> result, error-code>; - - /// Get the bound local address. - /// - /// POSIX mentions: - /// > If the socket has not been bound to a local name, the value - /// > stored in the object pointed to by `address` is unspecified. - /// - /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not bound to any local address. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - local-address: func() -> result; - - /// Get the remote address. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - remote-address: func() -> result; - - /// Whether the socket is in the `listening` state. - /// - /// Equivalent to the SO_ACCEPTCONN socket option. - @since(version = 0.2.0) - is-listening: func() -> bool; - - /// Whether this is a IPv4 or IPv6 socket. - /// - /// Equivalent to the SO_DOMAIN socket option. - @since(version = 0.2.0) - address-family: func() -> ip-address-family; - - /// Hints the desired listen queue size. Implementations are free to ignore this. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// - /// # Typical errors - /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen. - /// - `invalid-argument`: (set) The provided value was 0. - /// - `invalid-state`: (set) The socket is in the `connect-in-progress` or `connected` state. - @since(version = 0.2.0) - set-listen-backlog-size: func(value: u64) -> result<_, error-code>; - - /// Enables or disables keepalive. - /// - /// The keepalive behavior can be adjusted using: - /// - `keep-alive-idle-time` - /// - `keep-alive-interval` - /// - `keep-alive-count` - /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true. - /// - /// Equivalent to the SO_KEEPALIVE socket option. - @since(version = 0.2.0) - keep-alive-enabled: func() -> result; - @since(version = 0.2.0) - set-keep-alive-enabled: func(value: bool) -> result<_, error-code>; - - /// Amount of time the connection has to be idle before TCP starts sending keepalive packets. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// I.e. after setting a value, reading the same setting back may return a different value. - /// - /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS) - /// - /// # Typical errors - /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.2.0) - keep-alive-idle-time: func() -> result; - @since(version = 0.2.0) - set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>; - - /// The time between keepalive packets. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// I.e. after setting a value, reading the same setting back may return a different value. - /// - /// Equivalent to the TCP_KEEPINTVL socket option. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.2.0) - keep-alive-interval: func() -> result; - @since(version = 0.2.0) - set-keep-alive-interval: func(value: duration) -> result<_, error-code>; - - /// The maximum amount of keepalive packets TCP should send before aborting the connection. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// I.e. after setting a value, reading the same setting back may return a different value. - /// - /// Equivalent to the TCP_KEEPCNT socket option. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.2.0) - keep-alive-count: func() -> result; - @since(version = 0.2.0) - set-keep-alive-count: func(value: u32) -> result<_, error-code>; - - /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The TTL value must be 1 or higher. - @since(version = 0.2.0) - hop-limit: func() -> result; - @since(version = 0.2.0) - set-hop-limit: func(value: u8) -> result<_, error-code>; - - /// The kernel buffer space reserved for sends/receives on this socket. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// I.e. after setting a value, reading the same setting back may return a different value. - /// - /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.2.0) - receive-buffer-size: func() -> result; - @since(version = 0.2.0) - set-receive-buffer-size: func(value: u64) -> result<_, error-code>; - @since(version = 0.2.0) - send-buffer-size: func() -> result; - @since(version = 0.2.0) - set-send-buffer-size: func(value: u64) -> result<_, error-code>; - - /// Create a `pollable` which can be used to poll for, or block on, - /// completion of any of the asynchronous operations of this socket. - /// - /// When `finish-bind`, `finish-listen`, `finish-connect` or `accept` - /// return `error(would-block)`, this pollable can be used to wait for - /// their success or failure, after which the method can be retried. - /// - /// The pollable is not limited to the async operation that happens to be - /// in progress at the time of calling `subscribe` (if any). Theoretically, - /// `subscribe` only has to be called once per socket and can then be - /// (re)used for the remainder of the socket's lifetime. - /// - /// See - /// for more information. - /// - /// Note: this function is here for WASI 0.2 only. - /// It's planned to be removed when `future` is natively supported in Preview3. - @since(version = 0.2.0) - subscribe: func() -> pollable; - - /// Initiate a graceful shutdown. - /// - /// - `receive`: The socket is not expecting to receive any data from - /// the peer. The `input-stream` associated with this socket will be - /// closed. Any data still in the receive queue at time of calling - /// this method will be discarded. - /// - `send`: The socket has no more data to send to the peer. The `output-stream` - /// associated with this socket will be closed and a FIN packet will be sent. - /// - `both`: Same effect as `receive` & `send` combined. - /// - /// This function is idempotent; shutting down a direction more than once - /// has no effect and returns `ok`. - /// - /// The shutdown function does not close (drop) the socket. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>; - } -} diff --git a/proposals/sockets/wit-0.3.0-draft/types.wit b/proposals/sockets/wit/types.wit similarity index 94% rename from proposals/sockets/wit-0.3.0-draft/types.wit rename to proposals/sockets/wit/types.wit index fe2c0448b..7beaf7f8d 100644 --- a/proposals/sockets/wit-0.3.0-draft/types.wit +++ b/proposals/sockets/wit/types.wit @@ -1,7 +1,7 @@ -@since(version = 0.3.0-rc-2026-03-15) +@since(version = 0.3.0) interface types { - @since(version = 0.3.0-rc-2026-03-15) - use wasi:clocks/types@0.3.0-rc-2026-03-15.{duration}; + @since(version = 0.3.0) + use wasi:clocks/types@0.3.0.{duration}; /// Error codes. /// @@ -14,7 +14,7 @@ interface types { /// - `out-of-memory` /// /// See each individual API for what the POSIX equivalents are. They sometimes differ per API. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) variant error-code { /// Access denied. /// @@ -92,7 +92,7 @@ interface types { other(option), } - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) enum ip-address-family { /// Similar to `AF_INET` in POSIX. ipv4, @@ -101,18 +101,18 @@ interface types { ipv6, } - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) type ipv4-address = tuple; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) type ipv6-address = tuple; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) variant ip-address { ipv4(ipv4-address), ipv6(ipv6-address), } - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) record ipv4-socket-address { /// sin_port port: u16, @@ -120,7 +120,7 @@ interface types { address: ipv4-address, } - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) record ipv6-socket-address { /// sin6_port port: u16, @@ -132,7 +132,7 @@ interface types { scope-id: u32, } - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) variant ip-socket-address { ipv4(ipv4-socket-address), ipv6(ipv6-socket-address), @@ -147,7 +147,7 @@ interface types { /// - `connecting` /// - `connected` /// - `closed` - /// See + /// See /// for more information. /// /// Note: Except where explicitly mentioned, whenever this documentation uses @@ -170,7 +170,7 @@ interface types { /// In addition to the general error codes documented on the /// `types::error-code` type, TCP socket methods may always return /// `error(invalid-state)` when in the `closed` state. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) resource tcp-socket { /// Create a new TCP socket. @@ -191,7 +191,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) create: static func(address-family: ip-address-family) -> result; /// Bind the socket to the provided IP address and port. @@ -227,7 +227,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) bind: func(local-address: ip-socket-address) -> result<_, error-code>; /// Connect to a remote endpoint. @@ -264,7 +264,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) connect: async func(remote-address: ip-socket-address) -> result<_, error-code>; /// Start listening and return a stream of new inbound connections. @@ -337,7 +337,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) listen: func() -> result, error-code>; /// Transmit data to peer. @@ -362,7 +362,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) send: func(data: stream) -> future>; /// Read data from peer. @@ -392,7 +392,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) receive: func() -> tuple, future>>; /// Get the bound local address. @@ -412,7 +412,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-local-address: func() -> result; /// Get the remote address. @@ -425,13 +425,13 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-remote-address: func() -> result; /// Whether the socket is in the `listening` state. /// /// Equivalent to the SO_ACCEPTCONN socket option. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-is-listening: func() -> bool; /// Whether this is a IPv4 or IPv6 socket. @@ -439,7 +439,7 @@ interface types { /// This is the value passed to the constructor. /// /// Equivalent to the SO_DOMAIN socket option. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-address-family: func() -> ip-address-family; /// Hints the desired listen queue size. Implementations are free to @@ -453,7 +453,7 @@ interface types { /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen. /// - `invalid-argument`: (set) The provided value was 0. /// - `invalid-state`: (set) The socket is in the `connecting` or `connected` state. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-listen-backlog-size: func(value: u64) -> result<_, error-code>; /// Enables or disables keepalive. @@ -466,9 +466,9 @@ interface types { /// false, but only come into effect when `keep-alive-enabled` is true. /// /// Equivalent to the SO_KEEPALIVE socket option. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-keep-alive-enabled: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-keep-alive-enabled: func(value: bool) -> result<_, error-code>; /// Amount of time the connection has to be idle before TCP starts @@ -483,9 +483,9 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-keep-alive-idle-time: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>; /// The time between keepalive packets. @@ -499,9 +499,9 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-keep-alive-interval: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-keep-alive-interval: func(value: duration) -> result<_, error-code>; /// The maximum amount of keepalive packets TCP should send before @@ -516,9 +516,9 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-keep-alive-count: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-keep-alive-count: func(value: u32) -> result<_, error-code>; /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. @@ -527,9 +527,9 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The TTL value must be 1 or higher. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-hop-limit: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-hop-limit: func(value: u8) -> result<_, error-code>; /// Kernel buffer space reserved for sending/receiving on this socket. @@ -553,18 +553,18 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-receive-buffer-size: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-receive-buffer-size: func(value: u64) -> result<_, error-code>; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-send-buffer-size: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-send-buffer-size: func(value: u64) -> result<_, error-code>; } /// A UDP socket handle. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) resource udp-socket { /// Create a new UDP socket. @@ -582,7 +582,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) create: static func(address-family: ip-address-family) -> result; /// Bind the socket to the provided IP address and port. @@ -604,7 +604,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) bind: func(local-address: ip-socket-address) -> result<_, error-code>; /// Associate this socket with a specific peer address. @@ -643,7 +643,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) connect: func(remote-address: ip-socket-address) -> result<_, error-code>; /// Dissociate this socket from its peer address. @@ -661,7 +661,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) disconnect: func() -> result<_, error-code>; /// Send a message on the socket to a particular peer. @@ -706,7 +706,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) send: async func(data: list, remote-address: option) -> result<_, error-code>; /// Receive a message on the socket. @@ -732,7 +732,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) receive: async func() -> result, ip-socket-address>, error-code>; /// Get the current bound address. @@ -752,7 +752,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-local-address: func() -> result; /// Get the address the socket is currently "connected" to. @@ -765,7 +765,7 @@ interface types { /// - /// - /// - - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-remote-address: func() -> result; /// Whether this is a IPv4 or IPv6 socket. @@ -773,7 +773,7 @@ interface types { /// This is the value passed to the constructor. /// /// Equivalent to the SO_DOMAIN socket option. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-address-family: func() -> ip-address-family; /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. @@ -782,9 +782,9 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The TTL value must be 1 or higher. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-unicast-hop-limit: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-unicast-hop-limit: func(value: u8) -> result<_, error-code>; /// Kernel buffer space reserved for sending/receiving on this socket. @@ -800,13 +800,13 @@ interface types { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-receive-buffer-size: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-receive-buffer-size: func(value: u64) -> result<_, error-code>; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) get-send-buffer-size: func() -> result; - @since(version = 0.3.0-rc-2026-03-15) + @since(version = 0.3.0) set-send-buffer-size: func(value: u64) -> result<_, error-code>; } } diff --git a/proposals/sockets/wit/udp-create-socket.wit b/proposals/sockets/wit/udp-create-socket.wit deleted file mode 100644 index e8eeacbfe..000000000 --- a/proposals/sockets/wit/udp-create-socket.wit +++ /dev/null @@ -1,30 +0,0 @@ -@since(version = 0.2.0) -interface udp-create-socket { - @since(version = 0.2.0) - use network.{network, error-code, ip-address-family}; - @since(version = 0.2.0) - use udp.{udp-socket}; - - /// Create a new UDP socket. - /// - /// Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX. - /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise. - /// - /// This function does not require a network capability handle. This is considered to be safe because - /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind` is called, - /// the socket is effectively an in-memory configuration object, unable to communicate with the outside world. - /// - /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations. - /// - /// # Typical errors - /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT) - /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE) - /// - /// # References: - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - create-udp-socket: func(address-family: ip-address-family) -> result; -} diff --git a/proposals/sockets/wit/udp.wit b/proposals/sockets/wit/udp.wit deleted file mode 100644 index 279ff1d00..000000000 --- a/proposals/sockets/wit/udp.wit +++ /dev/null @@ -1,288 +0,0 @@ -@since(version = 0.2.0) -interface udp { - @since(version = 0.2.0) - use wasi:io/poll@0.2.12.{pollable}; - @since(version = 0.2.0) - use network.{network, error-code, ip-socket-address, ip-address-family}; - - /// A received datagram. - @since(version = 0.2.0) - record incoming-datagram { - /// The payload. - /// - /// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes. - data: list, - - /// The source address. - /// - /// This field is guaranteed to match the remote address the stream was initialized with, if any. - /// - /// Equivalent to the `src_addr` out parameter of `recvfrom`. - remote-address: ip-socket-address, - } - - /// A datagram to be sent out. - @since(version = 0.2.0) - record outgoing-datagram { - /// The payload. - data: list, - - /// The destination address. - /// - /// The requirements on this field depend on how the stream was initialized: - /// - with a remote address: this field must be None or match the stream's remote address exactly. - /// - without a remote address: this field is required. - /// - /// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`. - remote-address: option, - } - - /// A UDP socket handle. - @since(version = 0.2.0) - resource udp-socket { - /// Bind the socket to a specific network on the provided IP address and port. - /// - /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which - /// network interface(s) to bind to. - /// If the port is zero, the socket will be bound to a random free port. - /// - /// # Typical errors - /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows) - /// - `invalid-state`: The socket is already bound. (EINVAL) - /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows) - /// - `address-in-use`: Address is already in use. (EADDRINUSE) - /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL) - /// - `not-in-progress`: A `bind` operation is not in progress. - /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN) - /// - /// # Implementors note - /// Unlike in POSIX, in WASI the bind operation is async. This enables - /// interactive WASI hosts to inject permission prompts. Runtimes that - /// don't want to make use of this ability can simply call the native - /// `bind` as part of either `start-bind` or `finish-bind`. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - start-bind: func(network: borrow, local-address: ip-socket-address) -> result<_, error-code>; - @since(version = 0.2.0) - finish-bind: func() -> result<_, error-code>; - - /// Set up inbound & outbound communication channels, optionally to a specific peer. - /// - /// This function only changes the local socket configuration and does not generate any network traffic. - /// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well, - /// based on the best network path to `remote-address`. - /// - /// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer: - /// - `send` can only be used to send to this destination. - /// - `receive` will only return datagrams sent from the provided `remote-address`. - /// - /// This method may be called multiple times on the same socket to change its association, but - /// only the most recently returned pair of streams will be operational. Implementations may trap if - /// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again. - /// - /// The POSIX equivalent in pseudo-code is: - /// ```text - /// if (was previously connected) { - /// connect(s, AF_UNSPEC) - /// } - /// if (remote_address is Some) { - /// connect(s, remote_address) - /// } - /// ``` - /// - /// Unlike in POSIX, the socket must already be explicitly bound. - /// - /// # Typical errors - /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT) - /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL) - /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL) - /// - `invalid-state`: The socket is not bound. - /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD) - /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET) - /// - `connection-refused`: The connection was refused. (ECONNREFUSED) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - %stream: func(remote-address: option) -> result, error-code>; - - /// Get the current bound address. - /// - /// POSIX mentions: - /// > If the socket has not been bound to a local name, the value - /// > stored in the object pointed to by `address` is unspecified. - /// - /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not bound to any local address. - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - local-address: func() -> result; - - /// Get the address the socket is currently streaming to. - /// - /// # Typical errors - /// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN) - /// - /// # References - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - remote-address: func() -> result; - - /// Whether this is a IPv4 or IPv6 socket. - /// - /// Equivalent to the SO_DOMAIN socket option. - @since(version = 0.2.0) - address-family: func() -> ip-address-family; - - /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The TTL value must be 1 or higher. - @since(version = 0.2.0) - unicast-hop-limit: func() -> result; - @since(version = 0.2.0) - set-unicast-hop-limit: func(value: u8) -> result<_, error-code>; - - /// The kernel buffer space reserved for sends/receives on this socket. - /// - /// If the provided value is 0, an `invalid-argument` error is returned. - /// Any other value will never cause an error, but it might be silently clamped and/or rounded. - /// I.e. after setting a value, reading the same setting back may return a different value. - /// - /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options. - /// - /// # Typical errors - /// - `invalid-argument`: (set) The provided value was 0. - @since(version = 0.2.0) - receive-buffer-size: func() -> result; - @since(version = 0.2.0) - set-receive-buffer-size: func(value: u64) -> result<_, error-code>; - @since(version = 0.2.0) - send-buffer-size: func() -> result; - @since(version = 0.2.0) - set-send-buffer-size: func(value: u64) -> result<_, error-code>; - - /// Create a `pollable` which will resolve once the socket is ready for I/O. - /// - /// Note: this function is here for WASI 0.2 only. - /// It's planned to be removed when `future` is natively supported in Preview3. - @since(version = 0.2.0) - subscribe: func() -> pollable; - } - - @since(version = 0.2.0) - resource incoming-datagram-stream { - /// Receive messages on the socket. - /// - /// This function attempts to receive up to `max-results` datagrams on the socket without blocking. - /// The returned list may contain fewer elements than requested, but never more. - /// - /// This function returns successfully with an empty list when either: - /// - `max-results` is 0, or: - /// - `max-results` is greater than 0, but no results are immediately available. - /// This function never returns `error(would-block)`. - /// - /// # Typical errors - /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET) - /// - `connection-refused`: The connection was refused. (ECONNREFUSED) - /// - /// # References - /// - - /// - - /// - - /// - - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - receive: func(max-results: u64) -> result, error-code>; - - /// Create a `pollable` which will resolve once the stream is ready to receive again. - /// - /// Note: this function is here for WASI 0.2 only. - /// It's planned to be removed when `future` is natively supported in Preview3. - @since(version = 0.2.0) - subscribe: func() -> pollable; - } - - @since(version = 0.2.0) - resource outgoing-datagram-stream { - /// Check readiness for sending. This function never blocks. - /// - /// Returns the number of datagrams permitted for the next call to `send`, - /// or an error. Calling `send` with more datagrams than this function has - /// permitted will trap. - /// - /// When this function returns ok(0), the `subscribe` pollable will - /// become ready when this function will report at least ok(1), or an - /// error. - /// - /// Never returns `would-block`. - check-send: func() -> result; - - /// Send messages on the socket. - /// - /// This function attempts to send all provided `datagrams` on the socket without blocking and - /// returns how many messages were actually sent (or queued for sending). This function never - /// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned. - /// - /// This function semantically behaves the same as iterating the `datagrams` list and sequentially - /// sending each individual datagram until either the end of the list has been reached or the first error occurred. - /// If at least one datagram has been sent successfully, this function never returns an error. - /// - /// If the input list is empty, the function returns `ok(0)`. - /// - /// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if - /// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted. - /// - /// # Typical errors - /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT) - /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL) - /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL) - /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN) - /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ) - /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET) - /// - `connection-refused`: The connection was refused. (ECONNREFUSED) - /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE) - /// - /// # References - /// - - /// - - /// - - /// - - /// - - /// - - /// - - /// - - @since(version = 0.2.0) - send: func(datagrams: list) -> result; - - /// Create a `pollable` which will resolve once the stream is ready to send again. - /// - /// Note: this function is here for WASI 0.2 only. - /// It's planned to be removed when `future` is natively supported in Preview3. - @since(version = 0.2.0) - subscribe: func() -> pollable; - } -} diff --git a/proposals/sockets/wit/world.wit b/proposals/sockets/wit/world.wit index a309aadb2..6c9951d1c 100644 --- a/proposals/sockets/wit/world.wit +++ b/proposals/sockets/wit/world.wit @@ -1,19 +1,9 @@ -package wasi:sockets@0.2.12; +package wasi:sockets@0.3.0; -@since(version = 0.2.0) +@since(version = 0.3.0) world imports { - @since(version = 0.2.0) - import instance-network; - @since(version = 0.2.0) - import network; - @since(version = 0.2.0) - import udp; - @since(version = 0.2.0) - import udp-create-socket; - @since(version = 0.2.0) - import tcp; - @since(version = 0.2.0) - import tcp-create-socket; - @since(version = 0.2.0) + @since(version = 0.3.0) + import types; + @since(version = 0.3.0) import ip-name-lookup; } From fd0c228ad214af63080d22da5aff4ac061828613 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Thu, 11 Jun 2026 09:38:31 -0400 Subject: [PATCH 2/3] ci: drop WASI 0.2 and RC paths - ci.yml/validate-proposals.js: single wit/ filter (WIT_FILES) - release.yml/release.sh: single 0.3.x release flow - always regenerate proposal markdown docs from wit/ - publish.yml/publish-proposal.yml: publish from wit/, drop io and the wit-0.3.0-draft/prerelease branches - RELEASE.md/scripts/README.md: update docs to the 0.3 flow --- .github/RELEASE.md | 19 ++--- .github/labeler.yml | 4 -- .github/scripts/README.md | 10 +-- .github/scripts/release.sh | 72 +++++-------------- .github/scripts/validate-proposals.js | 40 +++++------ .github/scripts/validate-since.js | 2 +- .github/workflows/ci.yml | 13 ++-- .github/workflows/publish-proposal.yml | 2 +- .github/workflows/publish.yml | 61 +++------------- .github/workflows/release.yml | 98 +++++--------------------- CONTRIBUTING.md | 1 - 11 files changed, 78 insertions(+), 244 deletions(-) diff --git a/.github/RELEASE.md b/.github/RELEASE.md index 4c2be4208..3c889c024 100644 --- a/.github/RELEASE.md +++ b/.github/RELEASE.md @@ -12,22 +12,17 @@ │ ┌──────────────────────┼──────────────────────┐ ▼ ▼ ▼ - ┌─────────┐ ┌─────────┐ ┌─────────┐ - │ wasi:io │ │wasi:cli │ ... │wasi:http│ - │ → GHCR │ │ → GHCR │ │ → GHCR │ - └─────────┘ └─────────┘ └─────────┘ + ┌───────────┐ ┌─────────┐ ┌─────────┐ + │wasi:random│ │wasi:cli │ ... │wasi:http│ + │ → GHCR │ │ → GHCR │ │ → GHCR │ + └───────────┘ └─────────┘ └─────────┘ ## Usage -The unified `release.sh` script in `.github/scripts/` handles both patch and RC releases: +The `release.sh` script in `.github/scripts/` cuts a WASI 0.3.x release: ```bash -# Patch release (0.2.x stable) -.github/scripts/release.sh --type patch --prev 0.2.8 --next 0.2.9 - -# RC release (0.3.0-rc-YYYY-MM-DD) -.github/scripts/release.sh --type rc --prev-rc-date 2025-09-16 -.github/scripts/release.sh --type rc # First RC, no previous date +.github/scripts/release.sh --prev 0.3.0 --next 0.3.1 ``` ## What the Script Does @@ -37,6 +32,6 @@ The script automates the entire release process: 1. Triggers `release.yml` to bump version numbers and create a PR 2. Waits for the PR to be created and CI to pass 3. Awaits manual review and merge of the PR -4. Creates a GitHub release (with `--prerelease` flag for RC) +4. Creates a GitHub release 5. Waits for `publish.yml` to publish packages to GHCR 6. Validates all packages were published successfully diff --git a/.github/labeler.yml b/.github/labeler.yml index 00f10f364..6cae27585 100644 --- a/.github/labeler.yml +++ b/.github/labeler.yml @@ -21,10 +21,6 @@ P-http: - changed-files: - any-glob-to-any-file: 'proposals/http/**' -P-io: - - changed-files: - - any-glob-to-any-file: 'proposals/io/**' - P-random: - changed-files: - any-glob-to-any-file: 'proposals/random/**' diff --git a/.github/scripts/README.md b/.github/scripts/README.md index e55a05ef9..5cafc8909 100644 --- a/.github/scripts/README.md +++ b/.github/scripts/README.md @@ -14,21 +14,17 @@ Validates WIT definitions for changed proposals. Used by the CI workflow. ```bash # Validate specific proposals by simulating changed files -WIT_02_FILES='["proposals/cli/wit/cli.wit"]' node .github/scripts/validate-proposals.js - -# Validate 0.3 proposals -WIT_03_FILES='["proposals/http/wit-0.3.0-draft/handler.wit"]' node .github/scripts/validate-proposals.js +WIT_FILES='["proposals/cli/wit/command.wit"]' node .github/scripts/validate-proposals.js # Validate multiple proposals -WIT_02_FILES='["proposals/cli/wit/cli.wit", "proposals/http/wit/proxy.wit"]' node .github/scripts/validate-proposals.js +WIT_FILES='["proposals/cli/wit/command.wit", "proposals/http/wit/worlds.wit"]' node .github/scripts/validate-proposals.js ``` ### Environment Variables | Variable | Description | |----------|-------------| -| `WIT_02_FILES` | JSON array of changed files in `proposals/*/wit/**` | -| `WIT_03_FILES` | JSON array of changed files in `proposals/*/wit-0.3.0-draft/**` | +| `WIT_FILES` | JSON array of changed files in `proposals/*/wit/**` | ### What it validates diff --git a/.github/scripts/release.sh b/.github/scripts/release.sh index edbca9994..4c75df6c4 100755 --- a/.github/scripts/release.sh +++ b/.github/scripts/release.sh @@ -1,8 +1,8 @@ #!/bin/bash -# Unified release script for WASI releases +# Release script for WASI 0.3.x releases # -# This script automates the release process for both patch (0.2.x) and RC (0.3.0-rc) releases: +# This script automates the release process: # 1. Triggers the release.yml workflow to update versions and create PR # 2. Waits for PR to be filed and CI to pass # 3. Waits for manual PR review and merge @@ -10,33 +10,25 @@ # 5. Waits for publish workflow to complete (validates packages in CI) # # Usage: -# Patch release: ./release.sh --type patch --prev 0.2.8 --next 0.2.9 -# RC release: ./release.sh --type rc [--prev-rc-date 2025-09-16] +# ./release.sh --prev 0.3.0 --next 0.3.1 set -e set -x # Parse arguments -RELEASE_TYPE="" PREV_VERSION="" NEXT_VERSION="" -PREV_RC_DATE="" while [[ $# -gt 0 ]]; do case $1 in - --type) RELEASE_TYPE="$2"; shift 2 ;; --prev) PREV_VERSION="$2"; shift 2 ;; --next) NEXT_VERSION="$2"; shift 2 ;; - --prev-rc-date) PREV_RC_DATE="$2"; shift 2 ;; -h|--help) echo "Usage:" - echo " Patch release: $0 --type patch --prev --next " - echo " RC release: $0 --type rc [--prev-rc-date ]" + echo " $0 --prev --next " echo "" - echo "Examples:" - echo " $0 --type patch --prev 0.2.8 --next 0.2.9" - echo " $0 --type rc --prev-rc-date 2025-09-16" - echo " $0 --type rc # First RC, no previous date" + echo "Example:" + echo " $0 --prev 0.3.0 --next 0.3.1" exit 0 ;; *) @@ -51,35 +43,17 @@ done DATE="$(date +'%Y-%m-%d')" REPO="WebAssembly/WASI" -# Configure based on release type -if [ "$RELEASE_TYPE" == "patch" ]; then - if [ -z "$PREV_VERSION" ] || [ -z "$NEXT_VERSION" ]; then - echo "Error: Patch release requires --prev and --next" - echo "Example: $0 --type patch --prev 0.2.8 --next 0.2.9" - exit 1 - fi - TAG="v$NEXT_VERSION" - PRERELEASE_FLAG="" - RELEASE_LABEL="Patch" -elif [ "$RELEASE_TYPE" == "rc" ]; then - NEXT_VERSION="0.3.0-rc-$DATE" - TAG="v$NEXT_VERSION" - PRERELEASE_FLAG="--prerelease" - RELEASE_LABEL="RC" -else - echo "Error: --type must be 'patch' or 'rc'" - echo "Use --help for usage information" +if [ -z "$PREV_VERSION" ] || [ -z "$NEXT_VERSION" ]; then + echo "Error: release requires --prev and --next" + echo "Example: $0 --prev 0.3.0 --next 0.3.1" exit 1 fi +TAG="v$NEXT_VERSION" echo "============================================" -echo "WASI $RELEASE_LABEL Release" +echo "WASI Release" echo "============================================" -if [ "$RELEASE_TYPE" == "patch" ]; then - echo "Previous version: $PREV_VERSION" -else - echo "Previous RC date: ${PREV_RC_DATE:-'(none/first RC)'}" -fi +echo "Previous version: $PREV_VERSION" echo "Next version: $NEXT_VERSION" echo "Tag: $TAG" echo "Repository: $REPO" @@ -100,21 +74,9 @@ fi echo "" echo "Step 1: Triggering release.yml workflow..." -if [ "$RELEASE_TYPE" == "patch" ]; then - gh workflow run "release.yml" \ - -f release_type="patch" \ - -f prev_version="$PREV_VERSION" \ - -f next_version="$NEXT_VERSION" -else - if [ -n "$PREV_RC_DATE" ]; then - gh workflow run "release.yml" \ - -f release_type="rc" \ - -f prev_rc_date="$PREV_RC_DATE" - else - gh workflow run "release.yml" \ - -f release_type="rc" - fi -fi +gh workflow run "release.yml" \ + -f prev_version="$PREV_VERSION" \ + -f next_version="$NEXT_VERSION" # Wait for workflow to start echo "Waiting for workflow to start..." @@ -180,7 +142,7 @@ echo "" echo "Step 4: Creating GitHub release $TAG..." sleep 5 -gh release create "$TAG" --generate-notes $PRERELEASE_FLAG +gh release create "$TAG" --generate-notes gh release view "$TAG" # Step 5: Wait for publish workflow @@ -206,5 +168,5 @@ fi echo "" echo "============================================" -echo "✓ Release $NEXT_VERSION ($RELEASE_LABEL) completed successfully!" +echo "✓ Release $NEXT_VERSION completed successfully!" echo "============================================" diff --git a/.github/scripts/validate-proposals.js b/.github/scripts/validate-proposals.js index a6a85b598..15c2feb8b 100644 --- a/.github/scripts/validate-proposals.js +++ b/.github/scripts/validate-proposals.js @@ -4,11 +4,7 @@ const { execSync } = require('child_process'); const fs = require('fs'); const { validateDirectory, formatErrors } = require('./validate-since'); -const witPath = (proposal, version) => { - if (version === '0.2') return `proposals/${proposal}/wit`; - if (version === '0.3') return `proposals/${proposal}/wit-0.3.0-draft`; - throw new Error(`Unknown version: ${version}`); -}; +const witPath = (proposal) => `proposals/${proposal}/wit`; const parseFiles = (filesJson) => { if (!filesJson || filesJson === 'null') return []; @@ -45,17 +41,7 @@ const run = (cmd) => { }; // Collect proposals to validate from changed files -const toValidate = []; -const filesByVersion = [ - [process.env.WIT_02_FILES, '0.2'], - [process.env.WIT_03_FILES, '0.3'], -]; - -for (const [filesJson, version] of filesByVersion) { - for (const proposal of extractProposals(parseFiles(filesJson))) { - toValidate.push({ proposal, version }); - } -} +const toValidate = extractProposals(parseFiles(process.env.WIT_FILES)); if (toValidate.length === 0) { console.log('No proposals to validate'); @@ -64,18 +50,26 @@ if (toValidate.length === 0) { let failed = false; -for (const { proposal, version } of toValidate) { - const witDir = witPath(proposal, version); - console.log(`::group::Validating ${proposal} v${version}`); +for (const proposal of toValidate) { + const witDir = witPath(proposal); + console.log(`::group::Validating ${proposal}`); try { console.log(` Path: ${witDir}`); + // Skip proposals whose wit/ directory no longer exists. A PR that removes a + // proposal still surfaces its deleted files in the changed-file list, but + // there is nothing left to validate. + if (!fs.existsSync(witDir)) { + console.log(` Skipping ${proposal}: ${witDir} no longer exists (proposal removed)`); + continue; + } + // Check wit-deps lock if deps.toml exists if (fs.existsSync(`${witDir}/deps.toml`)) { console.log(' Checking dependencies...'); if (!run(`wit-deps -m "${witDir}"/deps.toml -l "${witDir}"/deps.lock -d "${witDir}"/deps lock --check`)) { - console.log(`::error::wit-deps lock check failed for ${proposal} v${version}`); + console.log(`::error::wit-deps lock check failed for ${proposal}`); failed = true; } } @@ -83,14 +77,14 @@ for (const { proposal, version } of toValidate) { // Validate WIT syntax console.log(' Validating WIT...'); if (!run(`wasm-tools component wit "${witDir}" -o /dev/null`)) { - console.log(`::error::WIT validation failed for ${proposal} v${version}`); + console.log(`::error::WIT validation failed for ${proposal}`); failed = true; } // Validate wasm encoding console.log(' Validating wasm encoding...'); if (!run(`wasm-tools component wit "${witDir}" --wasm -o /dev/null`)) { - console.log(`::error::wasm encoding failed for ${proposal} v${version}`); + console.log(`::error::wasm encoding failed for ${proposal}`); failed = true; } @@ -99,7 +93,7 @@ for (const { proposal, version } of toValidate) { const sinceErrors = validateDirectory(witDir); if (sinceErrors.length > 0) { console.log(formatErrors(sinceErrors)); - console.log(`::error::@since validation failed for ${proposal} v${version}: ${sinceErrors.length} missing annotation(s)`); + console.log(`::error::@since validation failed for ${proposal}: ${sinceErrors.length} missing annotation(s)`); failed = true; } } finally { diff --git a/.github/scripts/validate-since.js b/.github/scripts/validate-since.js index 383d94053..caf1f01ea 100644 --- a/.github/scripts/validate-since.js +++ b/.github/scripts/validate-since.js @@ -171,7 +171,7 @@ if (require.main === module) { if (args.length === 0) { console.log('Usage: node validate-since.js '); - console.log('Example: node validate-since.js proposals/io/wit'); + console.log('Example: node validate-since.js proposals/clocks/wit'); process.exit(1); } diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e7fe618c4..73be9a99f 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,14 +5,12 @@ on: branches: [main] paths: - 'proposals/**/wit/**' - - 'proposals/**/wit-0.3.0-draft/**' - '.github/scripts/**' - '.github/workflows/ci.yml' pull_request: branches: [main] paths: - 'proposals/**/wit/**' - - 'proposals/**/wit-0.3.0-draft/**' - '.github/scripts/**' - '.github/workflows/ci.yml' @@ -28,18 +26,15 @@ jobs: with: list-files: json filters: | - wit-02: + wit: - 'proposals/*/wit/**' - wit-03: - - 'proposals/*/wit-0.3.0-draft/**' - name: Install tools - if: steps.changes.outputs.wit-02 == 'true' || steps.changes.outputs.wit-03 == 'true' + if: steps.changes.outputs.wit == 'true' uses: ./.github/actions/install-tools - name: Validate changed proposals - if: steps.changes.outputs.wit-02 == 'true' || steps.changes.outputs.wit-03 == 'true' + if: steps.changes.outputs.wit == 'true' run: node .github/scripts/validate-proposals.js env: - WIT_02_FILES: ${{ steps.changes.outputs.wit-02_files }} - WIT_03_FILES: ${{ steps.changes.outputs.wit-03_files }} + WIT_FILES: ${{ steps.changes.outputs.wit_files }} diff --git a/.github/workflows/publish-proposal.yml b/.github/workflows/publish-proposal.yml index d516e1e24..092cfd4a8 100644 --- a/.github/workflows/publish-proposal.yml +++ b/.github/workflows/publish-proposal.yml @@ -18,7 +18,7 @@ on: required: true type: string wit_dir: - description: 'WIT directory (wit or wit-0.3.0-draft)' + description: 'WIT directory' required: true type: string wkg_version: diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index ad80d26fc..0782b493a 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -13,14 +13,6 @@ on: description: 'Version to publish (without the v)' required: true type: string - wit_dir: - description: 'WIT directory to publish from (wit or wit-0.3.0-draft)' - required: true - type: choice - options: - - wit - - wit-0.3.0-draft - default: wit jobs: # Determine version and configuration @@ -29,7 +21,6 @@ jobs: outputs: version: ${{ steps.version.outputs.version }} wit_dir: ${{ steps.config.outputs.wit_dir }} - is_prerelease: ${{ steps.config.outputs.is_prerelease }} proposals: ${{ steps.config.outputs.proposals }} steps: - name: Get version from release tag @@ -48,49 +39,19 @@ jobs: - name: Determine configuration id: config run: | - VERSION="${{ steps.version.outputs.version }}" - - # Determine configuration based on version: - # - RC versions always use wit-0.3.0-draft - # - Stable versions use wit (or workflow_dispatch input if provided) - if [[ "$VERSION" == *"-rc-"* ]]; then - IS_PRERELEASE="true" - WIT_DIR="wit-0.3.0-draft" - PROPOSALS="random clocks filesystem sockets cli http" - elif [ "${{ github.event_name }}" == "workflow_dispatch" ] && [ -n "${{ inputs.wit_dir }}" ]; then - IS_PRERELEASE="false" - WIT_DIR="${{ inputs.wit_dir }}" - PROPOSALS="io random clocks filesystem sockets cli http" - else - IS_PRERELEASE="false" - WIT_DIR="wit" - PROPOSALS="io random clocks filesystem sockets cli http" - fi + PROPOSALS="random clocks filesystem sockets cli http" { - echo "is_prerelease=$IS_PRERELEASE" - echo "wit_dir=$WIT_DIR" + echo "wit_dir=wit" echo "proposals=$PROPOSALS" } >> "$GITHUB_OUTPUT" # Publish proposals sequentially in dependency order: - # 1. io, random (no WASI dependencies) - # 2. clocks (depends on io) - # 3. filesystem, sockets (depend on io, clocks) - # 4. cli (depends on io, clocks, filesystem, random, sockets) - # 5. http (depends on cli, clocks, io) - - publish-io: - needs: setup - # Skip io for P3 prereleases (no wit-0.3.0-draft directory) - if: needs.setup.outputs.is_prerelease != 'true' - uses: ./.github/workflows/publish-proposal.yml - with: - proposal: io - description: "WASI I/O interfaces for streams and poll" - version: ${{ needs.setup.outputs.version }} - wit_dir: ${{ needs.setup.outputs.wit_dir }} - secrets: inherit + # 1. random (no WASI dependencies) + # 2. clocks (depends on random) + # 3. filesystem, sockets (depend on clocks) + # 4. cli (depends on clocks, filesystem, random, sockets) + # 5. http (depends on cli, clocks) publish-random: needs: setup @@ -103,8 +64,7 @@ jobs: secrets: inherit publish-clocks: - needs: [setup, publish-io, publish-random] - # For prereleases, only wait on random (io is skipped) + needs: [setup, publish-random] if: always() && !failure() && !cancelled() uses: ./.github/workflows/publish-proposal.yml with: @@ -160,7 +120,7 @@ jobs: # Validate all packages were published successfully validate: - needs: [setup, publish-io, publish-random, publish-clocks, publish-filesystem, publish-sockets, publish-cli, publish-http] + needs: [setup, publish-random, publish-clocks, publish-filesystem, publish-sockets, publish-cli, publish-http] if: always() && !failure() && !cancelled() runs-on: ubuntu-latest steps: @@ -251,7 +211,6 @@ jobs: create-specification: needs: [setup, validate] runs-on: ubuntu-latest - if: needs.setup.outputs.is_prerelease == 'false' permissions: contents: write pull-requests: write @@ -278,7 +237,6 @@ jobs: version of the specification are pushed to OCI based on the [Wasm OCI Artifact layout][wasm-oci]: - - [wasi:io@${VERSION}](https://github.com/WebAssembly/WASI/pkgs/container/wasi%2Fio?tag=${VERSION}) - [wasi:random@${VERSION}](https://github.com/WebAssembly/WASI/pkgs/container/wasi%2Frandom?tag=${VERSION}) - [wasi:clocks@${VERSION}](https://github.com/WebAssembly/WASI/pkgs/container/wasi%2Fclocks?tag=${VERSION}) - [wasi:sockets@${VERSION}](https://github.com/WebAssembly/WASI/pkgs/container/wasi%2Fsockets?tag=${VERSION}) @@ -304,7 +262,6 @@ jobs: This PR adds the specification entry for WASI v${{ needs.setup.outputs.version }}. The following packages have been published to GHCR: - - `ghcr.io/webassembly/wasi/io:${{ needs.setup.outputs.version }}` - `ghcr.io/webassembly/wasi/random:${{ needs.setup.outputs.version }}` - `ghcr.io/webassembly/wasi/clocks:${{ needs.setup.outputs.version }}` - `ghcr.io/webassembly/wasi/sockets:${{ needs.setup.outputs.version }}` diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 7d6c271dd..215c00c2c 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,24 +9,13 @@ name: Release WASI on: workflow_dispatch: inputs: - release_type: - description: 'Type of release' - required: true - type: choice - options: - - patch # 0.2.x patch release - - rc # 0.3.0-rc-YYYY-MM-DD release candidate prev_version: - description: 'Previous version (for patch releases, e.g., 0.2.8)' - required: false + description: 'Previous version (e.g., 0.3.0)' + required: true type: string next_version: - description: 'Next version (for patch releases, e.g., 0.2.9). For RC, leave empty to auto-generate date.' - required: false - type: string - prev_rc_date: - description: 'Previous RC date (for RC releases, e.g., 2025-09-16). Leave empty for first RC.' - required: false + description: 'Next version (e.g., 0.3.1)' + required: true type: string permissions: @@ -39,9 +28,7 @@ jobs: outputs: prev_version: ${{ steps.versions.outputs.prev_version }} next_version: ${{ steps.versions.outputs.next_version }} - wit_dir: ${{ steps.versions.outputs.wit_dir }} tag: ${{ steps.versions.outputs.tag }} - is_prerelease: ${{ steps.versions.outputs.is_prerelease }} steps: - name: Checkout repository @@ -50,59 +37,32 @@ jobs: - name: Determine versions id: versions run: | - DATE="$(date +'%Y-%m-%d')" - - if [ "${{ inputs.release_type }}" == "patch" ]; then - # Patch release (0.2.x) - PREV_VERSION="${{ inputs.prev_version }}" - NEXT_VERSION="${{ inputs.next_version }}" - WIT_DIR="wit" - TAG="v$NEXT_VERSION" - IS_PRERELEASE="false" - - if [ -z "$PREV_VERSION" ] || [ -z "$NEXT_VERSION" ]; then - echo "Error: prev_version and next_version are required for patch releases" - exit 1 - fi - else - # RC release (0.3.0-rc-YYYY-MM-DD) - if [ -n "${{ inputs.prev_rc_date }}" ]; then - # Strip any accidental "0.3.0-rc-" or "v" prefix from the input - PREV_RC_DATE="${{ inputs.prev_rc_date }}" - PREV_RC_DATE="${PREV_RC_DATE#v}" - PREV_RC_DATE="${PREV_RC_DATE#0.3.0-rc-}" - PREV_VERSION="0.3.0-rc-$PREV_RC_DATE" - else - # First RC or unknown previous - PREV_VERSION="0.3.0-draft" - fi - NEXT_VERSION="0.3.0-rc-$DATE" - WIT_DIR="wit-0.3.0-draft" - TAG="v$NEXT_VERSION" - IS_PRERELEASE="true" + PREV_VERSION="${{ inputs.prev_version }}" + NEXT_VERSION="${{ inputs.next_version }}" + + if [ -z "$PREV_VERSION" ] || [ -z "$NEXT_VERSION" ]; then + echo "Error: prev_version and next_version are required" + exit 1 fi + TAG="v$NEXT_VERSION" + { echo "prev_version=$PREV_VERSION" echo "next_version=$NEXT_VERSION" - echo "wit_dir=$WIT_DIR" echo "tag=$TAG" - echo "is_prerelease=$IS_PRERELEASE" } >> "$GITHUB_OUTPUT" echo "Release configuration:" echo " Previous version: $PREV_VERSION" echo " Next version: $NEXT_VERSION" - echo " WIT directory: $WIT_DIR" echo " Tag: $TAG" - echo " Is prerelease: $IS_PRERELEASE" update-versions: needs: prepare-release runs-on: ubuntu-latest env: - # io is excluded for 0.3.0-rc (no wit-0.3.0-draft directory) - PROPOSALS: ${{ inputs.release_type == 'patch' && 'io random clocks filesystem sockets cli http' || 'random clocks filesystem sockets cli http' }} + PROPOSALS: random clocks filesystem sockets cli http steps: - name: Checkout repository uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 @@ -117,40 +77,31 @@ jobs: - name: Update WIT versions run: | - WIT_DIR="${{ needs.prepare-release.outputs.wit_dir }}" PREV="${{ needs.prepare-release.outputs.prev_version }}" NEXT="${{ needs.prepare-release.outputs.next_version }}" - echo "Updating from $PREV to $NEXT in $WIT_DIR" + echo "Updating from $PREV to $NEXT" for proposal in $PROPOSALS; do - wit_path="proposals/$proposal/$WIT_DIR" + wit_path="proposals/$proposal/wit" if [ -d "$wit_path" ]; then echo "Updating $proposal..." # Update package declarations and use/import statements find "$wit_path" -type f -name "*.wit" -exec sed -i \ "s/\(wasi:[a-zA-Z0-9_\/-]*@\)$PREV/\1$NEXT/g" {} + || true - - # Only update @since annotations if they contain an RC version (-rc-). - # Stable @since versions (e.g., @since(version = 0.2.0)) mark when a feature - # was released and must not be changed. - # Exclude deps/ - those are pulled packages with their own versions. - find "$wit_path" -type f -name "*.wit" ! -path "*/deps/*" -exec sed -i \ - "s/\(@since(version = \)\([0-9.]*-rc-[^)]*\))/\1$NEXT)/g" {} + || true fi done - name: Stabilize gated features run: | - WIT_DIR="${{ needs.prepare-release.outputs.wit_dir }}" NEXT="${{ needs.prepare-release.outputs.next_version }}" # Promote any feature gate marked `// @stabilize-next` to # @since(version = NEXT). This runs after the package version is # bumped to NEXT, which is the point at which @since(NEXT) is legal. for proposal in $PROPOSALS; do - wit_path="proposals/$proposal/$WIT_DIR" + wit_path="proposals/$proposal/wit" if [ -d "$wit_path" ]; then node .github/scripts/stabilize-features.js "$wit_path" "$NEXT" fi @@ -158,10 +109,8 @@ jobs: - name: Update wit-deps run: | - WIT_DIR="${{ needs.prepare-release.outputs.wit_dir }}" - for proposal in $PROPOSALS; do - wit_path="proposals/$proposal/$WIT_DIR" + wit_path="proposals/$proposal/wit" deps_file="$wit_path/deps.toml" if [ -f "$deps_file" ]; then @@ -170,14 +119,10 @@ jobs: fi done - # Generate markdown documentation (only for 0.2.x patch releases) - name: Generate markdown documentation - if: inputs.release_type == 'patch' run: | - WIT_DIR="${{ needs.prepare-release.outputs.wit_dir }}" - for proposal in $PROPOSALS; do - wit_path="proposals/$proposal/$WIT_DIR" + wit_path="proposals/$proposal/wit" if [ -d "$wit_path" ]; then echo "Generating docs for $proposal..." @@ -203,16 +148,11 @@ jobs: This PR updates all WASI proposals to version `${{ needs.prepare-release.outputs.next_version }}`. - ### Release Type - ${{ inputs.release_type == 'patch' && '**Patch Release** (stable 0.2.x)' || '**Release Candidate** (0.3.0-rc)' }} - ### Version Changes - Previous: `${{ needs.prepare-release.outputs.prev_version }}` - Next: `${{ needs.prepare-release.outputs.next_version }}` - - WIT directory: `${{ needs.prepare-release.outputs.wit_dir }}` ### Proposals Updated - ${{ inputs.release_type == 'patch' && '- io' || '' }} - random - clocks - filesystem @@ -225,7 +165,7 @@ jobs: After this PR is merged, create a GitHub release with tag `${{ needs.prepare-release.outputs.tag }}` to trigger publishing to GHCR. ```bash - gh release create "${{ needs.prepare-release.outputs.tag }}" --generate-notes ${{ needs.prepare-release.outputs.is_prerelease == 'true' && '--prerelease' || '' }} + gh release create "${{ needs.prepare-release.outputs.tag }}" --generate-notes ``` base: main delete-branch: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af857396a..fa64ae8a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -21,7 +21,6 @@ pull request relates to. | `P-clocks` | [clocks](proposals/clocks/) | | `P-filesystem` | [filesystem](proposals/filesystem/) | | `P-http` | [http](proposals/http/) | -| `P-io` | [io](proposals/io/) | | `P-random` | [random](proposals/random/) | | `P-sockets` | [sockets](proposals/sockets/) | From 8ff84c8320ef873faec189974cd2fe8db615dee9 Mon Sep 17 00:00:00 2001 From: Bailey Hayes Date: Thu, 11 Jun 2026 12:50:04 -0400 Subject: [PATCH 3/3] fix: code review suggestions --- .github/scripts/validate-proposals.js | 4 +--- README.md | 4 ++-- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/.github/scripts/validate-proposals.js b/.github/scripts/validate-proposals.js index 15c2feb8b..724e83d81 100644 --- a/.github/scripts/validate-proposals.js +++ b/.github/scripts/validate-proposals.js @@ -4,8 +4,6 @@ const { execSync } = require('child_process'); const fs = require('fs'); const { validateDirectory, formatErrors } = require('./validate-since'); -const witPath = (proposal) => `proposals/${proposal}/wit`; - const parseFiles = (filesJson) => { if (!filesJson || filesJson === 'null') return []; try { @@ -51,7 +49,7 @@ if (toValidate.length === 0) { let failed = false; for (const proposal of toValidate) { - const witDir = witPath(proposal); + const witDir = ((proposal) => `proposals/${proposal}/wit`)(proposal); console.log(`::group::Validating ${proposal}`); try { diff --git a/README.md b/README.md index edfa93f4f..cbe2f6dd8 100644 --- a/README.md +++ b/README.md @@ -13,8 +13,8 @@ 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] is a modular collection of APIs defined with the [Wit IDL], -incorporating many of the lessons learned from Preview 1, including support for +[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.