Crate wasmtime_wasi

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:

• wasi:cli/environment
• wasi:cli/exit
• wasi:cli/stderr
• wasi:cli/stdin
• wasi:cli/stdout
• wasi:cli/terminal-input
• wasi:cli/terminal-output
• wasi:cli/terminal-stderr
• wasi:cli/terminal-stdin
• wasi:cli/terminal-stdout
• wasi:clocks/monotonic-clock
• wasi:clocks/wall-clock
• wasi:filesystem/preopens
• wasi:filesystem/types
• wasi:io/error
• wasi:io/poll
• wasi:io/streams
• wasi:random/insecure-seed
• wasi:random/insecure
• wasi:random/random
• wasi:sockets/instance-network
• wasi:sockets/ip-name-lookup
• wasi:sockets/network
• wasi:sockets/tcp-create-socket
• wasi:sockets/tcp
• wasi:sockets/udp-create-socket
• wasi:sockets/udp

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:

• WasiCtx - created through WasiCtxBuilder.
• ResourceTable - created through default constructors.

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.

• For non-async users (the default of Config), use add_to_linker_sync.
• For async users, use add_to_linker_async.

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.

• HostInputStream and HostOutputStream - these are the host traits behind the WASI input-stream and output-stream types in the wasi:io/streams interface. These enable embedders to build their own custom stream and insert them into a ResourceTable to be used from wasm.

• Subscribe - this trait enables building arbitrary logic to get hooked into a pollable resource from wasi:io/poll. A pollable resource is created through the subscribe function.

• HostWallClock and HostMonotonicClock are used in conjunction with WasiCtxBuilder::wall_clock and WasiCtxBuilder::monotonic_clock if the defaults host’s clock should not be used.

• StdinStream and StdoutStream are used to provide custom stdin/stdout streams if they’re not inherited (or null, which is the default).

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.

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 sychrnonous 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 HostOutputStream 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.

FileInputStream

FilePerms

I32Exit

An error returned from the proc_exit host syscall.

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.

Pollable

A host representation of the wasi:io/poll.pollable resource.

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 HostInputStream 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

IsATTY

SocketAddrUse

The reason what a socket address is being used for.

StreamError

Traits

HostInputStream

Host trait for implementing the wasi:io/streams.input-stream resource: A bytestream which can be read from.

HostMonotonicClock

HostOutputStream

Host trait for implementing the wasi:io/streams.output-stream resource: A bytestream which can be written to.

HostWallClock

StdinStream

A trait used to represent the standard input to a guest program.

StdoutStream

Similar to StdinStream, except for output.

Subscribe

A trait used internally within a Pollable to create a pollable resource in wasi:io/poll.

WasiView

A trait which provides access to internal WASI state.

Functions

add_to_linker_async

Add all WASI interfaces from this crate into the linker provided.

add_to_linker_sync

Add all WASI interfaces from this crate into the linker provided.

add_to_linker_with_options_async

Similar to add_to_linker_async, but with the ability to enable unstable features.

add_to_linker_with_options_sync

Similar to add_to_linker_sync, but with the ability to enable unstable features.

stderr

Returns a stream that represents the host’s standard err.

stdin

Returns a stream that represents the host’s standard input.

stdout

Returns a stream that represents the host’s standard out.

subscribe

Creates a pollable resource which is subscribed to the provided resource.

thread_rng

Type Aliases

ClosureFuture

FsError

FsResult

InputStream

MakeFuture

OutputStream

PollableFuture

SocketError

SocketResult

StreamResult