Crate wasmtime_wasi

Source
Expand description

§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 access to WasiCtx, which defines the configuration for WASI. The WasiView trait imples IoView, which provides access to a common ResourceTable, which owns all host-defined component model resources.

The wasmtime-wasi-io crate contains implementations of the following interfaces, and this crate reuses those implementations:

These traits are implemented in terms of a IoView trait, which only provides access to a common ResourceTable. All aspects of wasmtime-wasi-io that are used by this crate are re-exported. Unless you are implementing other host functionality that needs to interact with the WASI scheduler and don’t want to use other functionality provided by wasmtime-wasi, you don’t need to take a direct dependency on wasmtime-wasi-io.

§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>. WasiView implies the IoView trait, which provides access to common ResourceTable which owns all host-implemented component model resources.

For all of the generated bindings in this crate (Host traits), implementations are provided looking 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 and IoView trait you will first select a T to put in Store<T> (typically, by defining your own struct). Somewhere within T you’ll store:

You’ll then write implementations of the IoView and WasiView traits to access those items in your T. For example:

use wasmtime::component::ResourceTable;
use wasmtime_wasi::{WasiCtx, IoView, WasiView};
struct MyCtx {
    table: ResourceTable,
    wasi: WasiCtx,
}
impl IoView for MyCtx {
    fn table(&mut self) -> &mut ResourceTable {
        &mut self.table
    }
}
impl WasiView for MyCtx {
    fn ctx(&mut self) -> &mut WasiCtx {
        &mut self.wasi
    }
}

§Async and Sync

As of WASI0.2, WASI functions are not blocking from WebAssembly’s point of view: a WebAssembly call into these functions returns when they are complete.

This crate provides an implementation of those functions in the host, where for some functions, it is appropriate to implement them using async Rust and the Tokio executor, so that the host implementation can be nonblocking when Wasmtime’s Config::async_support is set. Synchronous wrappers are provided for all async implementations, which creates a private Tokio executor.

Users can choose between these modes of implementation using variants of the add_to_linker functions:

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 IoView and 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.

Re-exports§

  • pub use async_trait::async_trait;
  • pub use cap_fs_ext::SystemTimeSpec;
  • pub use cap_rand::RngCore;
  • pub use wasmtime::component::ResourceTable;
  • pub use wasmtime::component::ResourceTableError;

Modules§

  • bindings
    Auto-generated bindings for WASI interfaces.
  • pipe
    Virtual pipes.
  • preview0preview1
    Bindings for WASIp0 aka Preview 0 aka wasi_unstable.
  • preview1preview1
    Bindings for WASIp1 aka Preview 1 aka wasi_snapshot_preview1.
  • runtime
    This module provides an “ambient Tokio runtime” with_ambient_tokio_runtime. Embedders of wasmtime-wasi may do so from synchronous Rust, and not use tokio directly. The implementation of wasmtime-wasi requires a tokio executor in a way that is deeply tied to its design. When used from a synchronous wasmtime context, this module provides the wrapper function in_tokio used throughout the shim implementations of synchronous component binding Host traits in terms of the async ones.

Structs§

  • AsyncStdinStream
    An impl of StdinStream built on top of crate::pipe::AsyncReadStream.
  • AsyncStdoutStream
    A wrapper of crate::pipe::AsyncWriteStream that implements StdoutStream. Note that the OutputStream impl for this is not correct when used for interleaved async IO.
  • Deterministic
    Implement insecure-random using a deterministic cycle of bytes.
  • DirPerms
    Permission bits for operating on a directory.
  • DynPollable
    The host representation of the wasi:io/poll.pollable resource.
  • FileInputStream
  • FilePerms
  • I32Exit
    An error returned from the proc_exit host syscall.
  • IoImpl
    A small newtype wrapper which serves as the basis for implementations of Host WASI traits in this crate.
  • Network
  • OutputFile
    This implementation will yield output streams that block on writes, and output directly to a file. If truly async output is required, AsyncStdoutStream should be used instead.
  • Stderr
    This implementation will yield output streams that block on writes, as they inherit the implementation directly from the rust std library. A different implementation of StdoutStream will be necessary if truly async output streams are required.
  • Stdin
    Only public interface is the InputStream impl.
  • Stdout
    This implementation will yield output streams that block on writes, as they inherit the implementation directly from the rust std library. A different implementation of StdoutStream will be necessary if truly async output streams are required.
  • TrappableError
    A helper error type used by many other modules through type aliases.
  • WasiCtx
    Per-Store state which holds state necessary to implement WASI from this crate.
  • WasiCtxBuilder
    Builder-style structure used to create a WasiCtx.
  • WasiImpl
    A small newtype wrapper which serves as the basis for implementations of Host WASI traits in this crate.

Enums§

Traits§

Functions§

Type Aliases§