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:
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 throughWasiCtxBuilder
.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
), useadd_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 areasync
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
andHostOutputStream
- these are the host traits behind the WASIinput-stream
andoutput-stream
types in thewasi:io/streams
interface. These enable embedders to build their own custom stream and insert them into aResourceTable
to be used from wasm. -
Subscribe
- this trait enables building arbitrary logic to get hooked into apollable
resource fromwasi:io/poll
. A pollable resource is created through thesubscribe
function. -
HostWallClock
andHostMonotonicClock
are used in conjunction withWasiCtxBuilder::wall_clock
andWasiCtxBuilder::monotonic_clock
if the defaults host’s clock should not be used. -
StdinStream
andStdoutStream
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:
- First implement
WasiView
for your type which is theT
inStore<T>
. - Add WASI interfaces to a
wasmtime::component::Linker<T>
. This is either done through top-level functions likeadd_to_linker_sync
or through individualadd_to_linker
functions in generated bindings throughout this crate. - Create a
WasiCtx
for eachStore<T>
throughWasiCtxBuilder
. 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). - Use the previous
Linker<T>
to instantiate aComponent
within aStore<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§
- Auto-generated bindings for WASI interfaces.
- Virtual pipes.
- 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 functionin_tokio
used throughout the shim implementations of synchronous component bindingHost
traits in terms of the async ones.
Structs§
- An impl of
StdinStream
built on top ofcrate::pipe::AsyncReadStream
. - A wrapper of
crate::pipe::AsyncWriteStream
that implementsStdoutStream
. Note that theHostOutputStream
impl for this is not correct when used for interleaved async IO. - Implement
insecure-random
using a deterministic cycle of bytes. - Permission bits for operating on a directory.
- An error returned from the
proc_exit
host syscall. - 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. - A host representation of the
wasi:io/poll.pollable
resource. - 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. - Only public interface is the
HostInputStream
impl. - 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. - A helper error type used by many other modules through type aliases.
- Per-
Store
state which holds state necessary to implement WASI from this crate. - Builder-style structure used to create a
WasiCtx
. - A small newtype wrapper which serves as the basis for implementations of
Host
WASI traits in this crate.
Enums§
- The reason what a socket address is being used for.
Traits§
- Host trait for implementing the
wasi:io/streams.input-stream
resource: A bytestream which can be read from. - Host trait for implementing the
wasi:io/streams.output-stream
resource: A bytestream which can be written to. - A trait used to represent the standard input to a guest program.
- Similar to
StdinStream
, except for output. - A trait which provides access to internal WASI state.
Functions§
- Add all WASI interfaces from this crate into the
linker
provided. - Add all WASI interfaces from this crate into the
linker
provided. - Returns a stream that represents the host’s standard err.
- Returns a stream that represents the host’s standard input.
- Returns a stream that represents the host’s standard out.
- Creates a
pollable
resource which is subscribed to the providedresource
.