WebAssembly System Interface (WASI)

WASI provides a set of APIs for WebAssembly to interact with system resources. The project has evolved through several major previews:

• WASI 0.1 (Preview 1): An API using the witx IDL, influenced by POSIX and CloudABI.
• WASI 0.2 (Preview 2): A modular collection of APIs defined with the Wit IDL. It features improved modularity, a more expressive type system, and virtualizability.
• WASI 0.3 (Preview 3): The current preview. It builds on WASI 0.2 by replacing explicit streams and polling interfaces with the component model's native async functionality using future and stream types.

WASI filesystem is a capability-oriented API designed for accessing host filesystems from WebAssembly programs. Instead of using an implicit filesystem namespace, all APIs require a directory handle (Descriptor) and a path. The path is resolved relative to that handle and sandboxed within that directory.

Key characteristics:

• Capability-oriented: Access is granted via directory handles.
• Host-dependent semantics: While it hides some differences between Windows and Unix, behaviors like path lookup, symlinks, and file/directory semantics depend on the host.
• Non-deterministic: It does not aim for deterministic semantics to ensure efficiency and allow access to existing host filesystems.

WASI CLI is a proposed WebAssembly System Interface (WASI) [World] designed to provide a Command-Line Interface (CLI) environment. It provides standard APIs required for CLI programs, including:

• Filesystems and Sockets
• Command-line arguments
• Environment variables
• Standard I/O (stdio)

It is intended for interactive command-line programs, servers that expect CLI-style startup, and stream filters that process standard input and output.

WASI HTTP is a proposed WebAssembly System Interface API designed for sending and receiving HTTP requests and responses. It abstracts over HTTP versions (HTTP/1.1, HTTP/2, HTTP/3) and transport protocols by mapping to abstract HTTP Semantics.

The proposal defines two primary worlds:

• wasi:http/service: An execution environment for web applications, API servers, and proxies. It is designed for flexible auto-scaling (serverless) by allowing the host to manage the accept() loop and dynamically spin up Wasm instances.
• wasi:http/middleware: For services that forward requests along a chain of handlers, utilizing Component Model linking to flow requests through intermediaries.

The WASI sockets proposal aims to standardize specific POSIX socket options. Support for these options is categorized using the following legend:

• ✅ Included in proposal: Fully supported or planned for standardization.
• ⚠️ Partially supported: Limited or incomplete support.
• ⛔ Consciously decided NOT to include: Options explicitly excluded from the WASI specification (refer to specific notes in the proposal for reasoning).
• ❔ Not included (yet): Currently not part of the specification, with no specific exclusion reason provided.

WASI is designed to be modular and portable through the following mechanisms:

• Modularity via Worlds: WASI uses the component model's 'worlds' mechanism to define specific sets of APIs tailored to different environments. This ensures engines only implement the APIs relevant to them.
• Portability: Portability is evaluated on an API-by-API basis. WASI prefers APIs that run across a wide variety of engines.
• Compatibility: To maintain API cleanliness, WASI often provides compatibility (e.g., for existing applications or libraries) through external tools and libraries like WASI libc rather than embedding compatibility concerns directly into the core API.

WASI uses capability-based security via the WebAssembly component model. Access to external resources is granted through capabilities rather than ambient authority (global namespaces). There are two types of capabilities:

• Handles: Dynamically identify and provide access to resources. They are unforgeable; an instance can only acquire a handle if another instance explicitly passes it one.
• Link-time capabilities: Functions that require no handle arguments. These are used when it is unnecessary to identify more than one instance of a resource at runtime. They are interposable, meaning they can be refused in a security context.

Note that WASI capabilities are per-resource, unlike Linux or POSIX capabilities which are per-process.

Runtime capabilities are unforgeable [handles] that grant access to specific resources and can be passed around dynamically during program execution.

Key characteristics:

• Handles are first-class citizens and can flow anywhere at runtime.
• They allow access to individual resources without exposing the entire resource set.
• In languages unable to manipulate unforgeable references directly, handles may be exposed as i32 indices into per-component-instance tables, with bindings managing the bookkeeping.
• They are required for use cases involving multiple distinct resources live at the same time (e.g., having multiple files open simultaneously in a filesystem API).

The WASI sockets proposal aims for POSIX compatibility by addressing several key networking behaviors and flags. Developers porting POSIX-compliant networking code to WASI should be aware of how the following concepts are handled:

• I/O completion polling: Support for mechanisms like poll, select, pselect, and non-standard epoll_* or kqueue.
• Non-blocking mode: Support for FIONBIO, SOCK_NONBLOCK, and O_NONBLOCK.
• TCP urgent data: Support for sockatmark, MSG_OOB, SO_OOBINLINE, and SIOCATMARK.
• Peeking: Support for MSG_PEEK.
• Writing to closed streams: Handling of SIGPIPE and SO_NOSIGPIPE.
• Close-on-exec: Support for FD_CLOEXEC, SOCK_CLOEXEC, and O_CLOEXEC.

Core socket functions targeted for compatibility include socket, connect, and bind.

The wasi-filesystem API uses a sandboxing scheme where all filesystem operations require a pair of values: a base directory handle and a relative path.

Key constraints:

• No Absolute Paths: Absolute paths are not permitted; there is no global namespace.
• Relative Access: All path accesses must be relative to the provided base directory handle.
• No Escaping: You cannot use paths like ../../../stuff/here to step outside the sandbox, even if the final resolved path ends up inside the sandbox. This prevents leaking information about the existence of directories outside the sandbox.
• Symlink Constraints: Creating a symlink with an absolute path string will fail with a "not permitted" error.

Link-time capabilities (also known as instantiation-time capabilities) are functions that a Wasm program can import to interact with the outside world. These are satisfied by providing exports at the time the component is linked or instantiated.

Key characteristics:

• They are implemented as instance imports in the Wasm component model.
• They request an already-instantiated instance that may already possess its own capabilities.
• They are suitable for APIs where a single resource is typically used (e.g., a clock API with a single 'get the time' function).