Struct WasiEnvBuilder

pub struct WasiEnvBuilder { /* private fields */ }

Builder API for configuring a WasiEnv environment needed to run WASI modules.

Usage:

let mut state_builder = WasiEnv::builder("wasi-prog-name");
state_builder
   .env("ENV_VAR", "ENV_VAL")
   .arg("--verbose")
   .preopen_dir("src")?
   .map_dir("name_wasi_sees", "path/on/host/fs")?
   .build_init()?;

Implementations

impl WasiEnvBuilder

pub fn new(program_name: impl Into<String>) -> Self

Creates an empty WasiEnvBuilder.

pub fn env<Key, Value>(self, key: Key, value: Value) -> Self

where Key: AsRef<[u8]>, Value: AsRef<[u8]>,

Add an environment variable pair.

Both the key and value of an environment variable must not contain a nul byte (0x0), and the key must not contain the = byte (0x3d).

pub fn attach_ctrl_c(self) -> Self

Available on crate feature ctrlc only.

Attaches a ctrl-c handler which will send signals to the process rather than immediately termiante it

pub fn add_env<Key, Value>(&mut self, key: Key, value: Value)

where Key: AsRef<[u8]>, Value: AsRef<[u8]>,

Add an environment variable pair.

Both the key and value of an environment variable must not contain a nul byte (0x0), and the key must not contain the = byte (0x3d).

pub fn envs<I, Key, Value>(self, env_pairs: I) -> Self

where I: IntoIterator<Item = (Key, Value)>, Key: AsRef<[u8]>, Value: AsRef<[u8]>,

Add multiple environment variable pairs.

Both the key and value of the environment variables must not contain a nul byte (0x0), and the key must not contain the = byte (0x3d).

pub fn add_envs<I, Key, Value>(&mut self, env_pairs: I)

where I: IntoIterator<Item = (Key, Value)>, Key: AsRef<[u8]>, Value: AsRef<[u8]>,

Add multiple environment variable pairs.

Both the key and value of the environment variables must not contain a nul byte (0x0), and the key must not contain the = byte (0x3d).

pub fn get_env(&self) -> &[(String, Vec<u8>)]

Get a reference to the configured environment variables.

pub fn get_env_mut(&mut self) -> &mut Vec<(String, Vec<u8>)>

Get a mutable reference to the configured environment variables.

pub fn entry_function<S>(self, entry_function: S) -> Self

where S: AsRef<str>,

pub fn set_entry_function<S>(&mut self, entry_function: S)

where S: AsRef<str>,

pub fn arg<V>(self, arg: V) -> Self

where V: AsRef<[u8]>,

Add an argument.

Arguments must not contain the nul (0x0) byte

pub fn add_arg<V>(&mut self, arg: V)

where V: AsRef<[u8]>,

Add an argument.

Arguments must not contain the nul (0x0) byte.

pub fn args<I, Arg>(self, args: I) -> Self

where I: IntoIterator<Item = Arg>, Arg: AsRef<[u8]>,

Add multiple arguments.

Arguments must not contain the nul (0x0) byte

pub fn add_args<I, Arg>(&mut self, args: I)

where I: IntoIterator<Item = Arg>, Arg: AsRef<[u8]>,

Add multiple arguments.

Arguments must not contain the nul (0x0) byte

pub fn get_args(&self) -> &[String]

Get a reference to the configured arguments.

pub fn get_args_mut(&mut self) -> &mut Vec<String>

Get a mutable reference to the configured arguments.

pub fn use_webc(self, pkg: BinaryPackage) -> Self

Adds a container this module inherits from.

This will make all of the container’s files and commands available to the resulting WASI instance.

pub fn set_module_hash(&mut self, hash: ModuleHash) -> &mut Self

Sets the module hash for the running process. This ensures that the journal can restore the records for the right module. If no module hash is supplied then the process will start with a random module hash.

pub fn add_webc(&mut self, pkg: BinaryPackage) -> &mut Self

Adds a container this module inherits from.

This will make all of the container’s files and commands available to the resulting WASI instance.

pub fn include_package(&mut self, pkg_id: PackageId) -> &mut Self

Adds a package that is already included in the WasiEnvBuilder filesystem. These packages will not be merged to the final filesystem since they are already included.

pub fn include_packages( &mut self, pkg_ids: impl IntoIterator<Item = PackageId>, ) -> &mut Self

Adds packages that is already included in the WasiEnvBuilder filesystem. These packages will not be merged to the final filesystem since they are already included.

pub fn uses<I>(self, uses: I) -> Self

where I: IntoIterator<Item = BinaryPackage>,

Adds a list of other containers this module inherits from.

This will make all of the container’s files and commands available to the resulting WASI instance.

pub fn map_command<Name, Target>(self, name: Name, target: Target) -> Self

where Name: AsRef<str>, Target: AsRef<str>,

Map an atom to a local binary

pub fn add_mapped_command<Name, Target>(&mut self, name: Name, target: Target)

where Name: AsRef<str>, Target: AsRef<str>,

Map an atom to a local binary

pub fn map_commands<I, Name, Target>(self, map_commands: I) -> Self

where I: IntoIterator<Item = (Name, Target)>, Name: AsRef<str>, Target: AsRef<str>,

Maps a series of atoms to the local binaries

pub fn add_mapped_commands<I, Name, Target>(&mut self, map_commands: I)

where I: IntoIterator<Item = (Name, Target)>, Name: AsRef<str>, Target: AsRef<str>,

Maps a series of atoms to local binaries.

pub fn preopen_dir<P>(self, po_dir: P) -> Result<Self, WasiStateCreationError>

where P: AsRef<Path>,

Preopen a directory

This opens the given directory at the virtual root, /, and allows the WASI module to read and write to the given directory.

pub fn add_preopen_dir<P>( &mut self, po_dir: P, ) -> Result<(), WasiStateCreationError>

where P: AsRef<Path>,

Adds a preopen a directory

This opens the given directory at the virtual root, /, and allows the WASI module to read and write to the given directory.

pub fn preopen_dirs<I, P>(self, dirs: I) -> Result<Self, WasiStateCreationError>

where I: IntoIterator<Item = P>, P: AsRef<Path>,

Preopen multiple directories.

This opens the given directories at the virtual root, /, and allows the WASI module to read and write to the given directory.

pub fn preopen_build<F>(self, inner: F) -> Result<Self, WasiStateCreationError>

where F: Fn(&mut PreopenDirBuilder) -> &mut PreopenDirBuilder,

Preopen a directory and configure it.

Usage:

WasiEnv::builder("program_name")
   .preopen_build(|p| p.directory("src").read(true).write(true).create(true))?
   .preopen_build(|p| p.directory(".").alias("dot").read(true))?
   .build_init()?;

pub fn add_preopen_build<F>( &mut self, inner: F, ) -> Result<(), WasiStateCreationError>

where F: Fn(&mut PreopenDirBuilder) -> &mut PreopenDirBuilder,

Preopen a directory and configure it.

Usage:

WasiEnv::builder("program_name")
   .preopen_build(|p| p.directory("src").read(true).write(true).create(true))?
   .preopen_build(|p| p.directory(".").alias("dot").read(true))?
   .build_init()?;

pub fn preopen_vfs_dirs<I>( &mut self, po_dirs: I, ) -> Result<&mut Self, WasiStateCreationError>

where I: IntoIterator<Item = String>,

Preopen the given directories from the Virtual FS.

pub fn map_dir<P>( self, alias: &str, po_dir: P, ) -> Result<Self, WasiStateCreationError>

where P: AsRef<Path>,

Preopen a directory with a different name exposed to the WASI.

pub fn add_map_dir<P>( &mut self, alias: &str, po_dir: P, ) -> Result<(), WasiStateCreationError>

where P: AsRef<Path>,

Preopen a directory with a different name exposed to the WASI.

pub fn map_dirs<I, P>( self, mapped_dirs: I, ) -> Result<Self, WasiStateCreationError>

where I: IntoIterator<Item = (String, P)>, P: AsRef<Path>,

Preopen directorys with a different names exposed to the WASI.

pub fn add_journal(&mut self, journal: Arc<DynJournal>)

Available on crate feature journal only.

Specifies one or more journal files that Wasmer will use to restore the state of the WASM process.

The state of the WASM process and its sandbox will be reapplied use the journals in the order that you specify here.

The last journal file specified will be created if it does not exist and opened for read and write. New journal events will be written to this file

pub fn set_current_dir(&mut self, dir: impl Into<PathBuf>)

pub fn current_dir(self, dir: impl Into<PathBuf>) -> Self

pub fn stdout( self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, ) -> Self

Overwrite the default WASI stdout, if you want to hold on to the original stdout use WasiFs::swap_file after building.

pub fn set_stdout( &mut self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, )

Overwrite the default WASI stdout, if you want to hold on to the original stdout use WasiFs::swap_file after building.

pub fn stderr( self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, ) -> Self

Overwrite the default WASI stderr, if you want to hold on to the original stderr use WasiFs::swap_file after building.

pub fn set_stderr( &mut self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, )

Overwrite the default WASI stderr, if you want to hold on to the original stderr use WasiFs::swap_file after building.

pub fn stdin( self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, ) -> Self

Overwrite the default WASI stdin, if you want to hold on to the original stdin use WasiFs::swap_file after building.

pub fn set_stdin( &mut self, new_file: Box<dyn VirtualFile + Send + Sync + 'static>, )

Overwrite the default WASI stdin, if you want to hold on to the original stdin use WasiFs::swap_file after building.

pub fn fs(self, fs: Box<dyn FileSystem + Send + Sync>) -> Self

Sets the FileSystem to be used with this WASI instance.

This is usually used in case a custom virtual_fs::FileSystem is needed.

pub fn set_fs(&mut self, fs: Box<dyn FileSystem + Send + Sync>)

pub fn sandbox_fs(self, fs: TmpFileSystem) -> Self

Sets a new sandbox FileSystem to be used with this WASI instance.

This is usually used in case a custom virtual_fs::FileSystem is needed.

pub fn setup_fs( self, setup_fs_fn: Box<dyn Fn(&WasiInodes, &mut WasiFs) -> Result<(), String> + Send>, ) -> Self

Configure the WASI filesystem before running.

pub fn runtime(self, runtime: Arc<dyn Runtime + Send + Sync>) -> Self

Sets the WASI runtime implementation and overrides the default implementation

pub fn set_runtime(&mut self, runtime: Arc<dyn Runtime + Send + Sync>)

pub fn capabilities(self, capabilities: Capabilities) -> Self

pub fn capabilities_mut(&mut self) -> &mut Capabilities

pub fn set_capabilities(&mut self, capabilities: Capabilities)

pub fn add_snapshot_trigger(&mut self, on: SnapshotTrigger)

Available on crate feature journal only.

pub fn with_snapshot_interval(&mut self, interval: Duration)

Available on crate feature journal only.

pub fn import( self, namespace: impl Into<String>, name: impl Into<String>, value: impl Into<Extern>, ) -> Self

Add an item to the list of importable items provided to the instance.

pub fn add_import( &mut self, namespace: impl Into<String>, name: impl Into<String>, value: impl Into<Extern>, )

Add an item to the list of importable items provided to the instance.

pub fn add_imports<I, S1, S2, E>(&mut self, imports: I)

where I: IntoIterator<Item = ((S1, S2), E)>, S1: Into<String>, S2: Into<String>, E: Into<Extern>,

pub fn imports<I, S1, S2, E>(self, imports: I) -> Self

where I: IntoIterator<Item = ((S1, S2), E)>, S1: Into<String>, S2: Into<String>, E: Into<Extern>,

pub fn build_init(self) -> Result<WasiEnvInit, WasiStateCreationError>

Consumes the WasiEnvBuilder and produces a WasiEnvInit, which can be used to construct a new WasiEnv.

Returns the error from WasiFs::new if there’s an error

NOTE: You should prefer to not work directly with WasiEnvInit. Use WasiEnvBuilder::run or WasiEnvBuilder::run_with_store instead to ensure proper invokation of WASI modules.

pub fn build(self) -> Result<WasiEnv, WasiRuntimeError>

pub fn instantiate( self, module: Module, store: &mut impl AsStoreMut, ) -> Result<(Instance, WasiFunctionEnv), WasiRuntimeError>

Consumes the WasiEnvBuilder and produces a WasiEnvInit, which can be used to construct a new WasiEnv.

Returns the error from WasiFs::new if there’s an error

pub fn instantiate_ext( self, module: Module, module_hash: ModuleHash, store: &mut impl AsStoreMut, ) -> Result<(Instance, WasiFunctionEnv), WasiRuntimeError>

pub fn run(self, module: Module) -> Result<(), WasiRuntimeError>

pub fn run_ext( self, module: Module, module_hash: ModuleHash, ) -> Result<(), WasiRuntimeError>

pub fn run_with_store( self, module: Module, store: &mut Store, ) -> Result<(), WasiRuntimeError>

pub fn run_with_store_ext( self, module: Module, module_hash: ModuleHash, store: &mut Store, ) -> Result<(), WasiRuntimeError>

pub fn run_with_store_async( self, module: Module, module_hash: ModuleHash, store: Store, ) -> Result<(), WasiRuntimeError>

Start the WASI executable with async threads enabled.

Trait Implementations

impl Debug for WasiEnvBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for WasiEnvBuilder

fn default() -> WasiEnvBuilder

Returns the “default value” for a type.