126 releases (77 stable)

27.0.0 Nov 20, 2024
26.0.1 Nov 5, 2024
26.0.0 Oct 22, 2024
25.0.3 Nov 5, 2024
0.8.0 Nov 20, 2019

#957 in WebAssembly

Download history 17739/week @ 2024-08-17 16608/week @ 2024-08-24 17747/week @ 2024-08-31 16032/week @ 2024-09-07 16828/week @ 2024-09-14 18052/week @ 2024-09-21 15845/week @ 2024-09-28 17420/week @ 2024-10-05 14935/week @ 2024-10-12 19945/week @ 2024-10-19 19584/week @ 2024-10-26 21052/week @ 2024-11-02 17544/week @ 2024-11-09 23154/week @ 2024-11-16 17516/week @ 2024-11-23 21986/week @ 2024-11-30

83,497 downloads per month
Used in 175 crates (87 directly)

Apache-2.0 WITH LLVM-exception

3.5MB
54K SLoC

Crate defining the Wasi type for Wasmtime, which represents a WASI instance which may be added to a linker.


lib.rs:

Wasmtime's WASI Implementation

This crate provides a Wasmtime host implementation of WASI 0.2 (aka WASIp2 aka Preview 2) and WASI 0.1 (aka WASIp1 aka Preview 1). WASI is implemented with the Rust crates tokio and cap-std primarily, meaning that operations are implemented in terms of their native platform equivalents by default.

For components and WASIp2, continue reading below. For WASIp1 and core modules, see the preview1 module documentation.

WASIp2 interfaces

This crate contains implementations of the following interfaces:

All traits are implemented in terms of a WasiView trait which provides basic access to WasiCtx, configuration for WASI, and ResourceTable, the state for all host-defined component model resources.

Generated Bindings

This crate uses wasmtime::component::bindgen! to generate bindings for all WASI interfaces. Raw bindings are available in the bindings module of this crate. Downstream users can either implement these traits themselves or you can use the built-in implementations in this crate for WasiImpl<T: WasiView>.

The WasiView trait

This crate's implementation of WASI is done in terms of an implementation of WasiView. This trait provides a "view" into WASI-related state that is contained within a Store<T>. All implementations of traits look like:

impl<T: WasiView> bindings::wasi::Host for WasiImpl<T> {
    // ...
}

The add_to_linker_sync and add_to_linker_async function then require that T: WasiView with Linker<T>.

To implement the WasiView trait you will first select a T to put in Store<T>. Next you'll implement the WasiView trait for T. Somewhere within T you'll store:

These two fields are then accessed through the methods of WasiView.

Async and Sync

Many WASI functions are not blocking from WebAssembly's point of view, but for those that do they're provided in two flavors: asynchronous and synchronous. Which version you will use depends on how Config::async_support is set.

Note that bindings are generated once for async and once for sync. Most interfaces do not change, however, so only interfaces with blocking functions have bindings generated twice. Bindings are organized as:

  • bindings - default location of all bindings, blocking functions are async
  • bindings::sync - blocking interfaces have synchronous versions here.

Crate-specific traits

This crate's default implementation of WASI bindings to native primitives for the platform that it is compiled for. For example opening a TCP socket uses the native platform to open a TCP socket (so long as WasiCtxBuilder allows it). There are a few important traits, however, that are specific to this crate.

These traits enable embedders to customize small portions of WASI interfaces provided while still providing all other interfaces.

Examples

Usage of this crate is done through a few steps to get everything hooked up:

  1. First implement WasiView for your type which is the T in Store<T>.
  2. Add WASI interfaces to a wasmtime::component::Linker<T>. This is either done through top-level functions like add_to_linker_sync or through individual add_to_linker functions in generated bindings throughout this crate.
  3. Create a WasiCtx for each Store<T> through WasiCtxBuilder. Each WASI context is "null" or "empty" by default, so items must be explicitly added to get accessed by wasm (such as env vars or program arguments).
  4. Use the previous Linker<T> to instantiate a Component within a Store<T>.

For examples see each of WasiView, WasiCtx, WasiCtxBuilder, add_to_linker_sync, and bindings::Command.

Dependencies

~27–41MB
~769K SLoC