A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
//! Common functionality shared between command implementations.
use clap::Parser;
use std::net::TcpListener;
use std::num::NonZeroUsize;
use std::{fs::File, path::Path, time::Duration};
use wasmtime::{
Engine, Module, Precompiled, Result, Store, StoreLimits, StoreLimitsBuilder, bail,
error::Context as _, format_err,
};
use wasmtime_cli_flags::{CommonOptions, opt::WasmtimeOptionValue};
use wasmtime_wasi::WasiCtxBuilder;
#[cfg(feature = "component-model")]
use wasmtime::component::Component;
/// Whether or not WASIp3 is enabled by default.
pub const P3_DEFAULT: bool = cfg!(feature = "component-model-async");
#[derive(Clone)]
pub enum RunTarget {
Core(Module),
#[cfg(feature = "component-model")]
Component(Component),
}
impl RunTarget {
pub fn unwrap_core(&self) -> &Module {
match self {
RunTarget::Core(module) => module,
#[cfg(feature = "component-model")]
RunTarget::Component(_) => panic!("expected a core wasm module, not a component"),
}
}
#[cfg(feature = "component-model")]
pub fn unwrap_component(&self) -> &Component {
match self {
RunTarget::Component(c) => c,
RunTarget::Core(_) => panic!("expected a component, not a core wasm module"),
}
}
}
/// Common command line arguments for run commands.
#[derive(Parser)]
pub struct RunCommon {
#[command(flatten)]
pub common: CommonOptions,
/// Allow executing precompiled WebAssembly modules as `*.cwasm` files.
///
/// Note that this option is not safe to pass if the module being passed in
/// is arbitrary user input. Only `wasmtime`-precompiled modules generated
/// via the `wasmtime compile` command or equivalent should be passed as an
/// argument with this option specified.
#[arg(long = "allow-precompiled")]
pub allow_precompiled: bool,
/// Profiling strategy (valid options are: perfmap, jitdump, vtune, guest)
///
/// The perfmap, jitdump, and vtune profiling strategies integrate Wasmtime
/// with external profilers such as `perf`. The guest profiling strategy
/// enables in-process sampling and will write the captured profile to
/// `wasmtime-guest-profile.json` by default which can be viewed at
/// https://profiler.firefox.com/.
///
/// The `guest` option can be additionally configured as:
///
/// --profile=guest[,path[,interval]]
///
/// where `path` is where to write the profile and `interval` is the
/// duration between samples. When used with `--wasm-timeout` the timeout
/// will be rounded up to the nearest multiple of this interval.
#[arg(
long,
value_name = "STRATEGY",
value_parser = Profile::parse,
)]
pub profile: Option<Profile>,
/// Grant access of a host directory to a guest.
///
/// If specified as just `HOST_DIR` then the same directory name on the
/// host is made available within the guest. If specified as `HOST::GUEST`
/// then the `HOST` directory is opened and made available as the name
/// `GUEST` in the guest.
#[arg(long = "dir", value_name = "HOST_DIR[::GUEST_DIR]", value_parser = parse_dirs)]
pub dirs: Vec<(String, String)>,
/// Pass an environment variable to the program.
///
/// The `--env FOO=BAR` form will set the environment variable named `FOO`
/// to the value `BAR` for the guest program using WASI. The `--env FOO`
/// form will set the environment variable named `FOO` to the same value it
/// has in the calling process for the guest, or in other words it will
/// cause the environment variable `FOO` to be inherited.
#[arg(long = "env", number_of_values = 1, value_name = "NAME[=VAL]", value_parser = parse_env_var)]
pub vars: Vec<(String, Option<String>)>,
/// Attach the built-in gdbstub debugger component, listening on
/// the given TCP address. Accepts a port number (e.g. `1234`) or
/// a full `address:port`. A bare port number will bind on
/// localhost only (`127.0.0.1`). A port number of `0` indicates
/// that any free port should be chosen; the port is printed on startup.
///
/// A debugger (e.g. LLDB) can then connect via `process connect
/// --plugin=wasm connect://<ADDR>:<PORT>`.
#[cfg(feature = "gdbstub")]
#[arg(short = 'g', long = "gdbstub", value_name = "[ADDR:]PORT")]
pub gdbstub: Option<String>,
}
fn parse_env_var(s: &str) -> Result<(String, Option<String>)> {
let mut parts = s.splitn(2, '=');
Ok((
parts.next().unwrap().to_string(),
parts.next().map(|s| s.to_string()),
))
}
fn parse_dirs(s: &str) -> Result<(String, String)> {
let mut parts = s.split("::");
let host = parts.next().unwrap();
let guest = match parts.next() {
Some(guest) => guest,
None => host,
};
Ok((host.into(), guest.into()))
}
impl std::fmt::Display for RunCommon {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.common)?;
if self.allow_precompiled {
write!(f, "--allow-precompiled ")?;
}
if let Some(profile) = &self.profile {
write!(f, "--profile={profile} ")?;
}
for (host, guest) in &self.dirs {
write!(f, "--dir={host}::{guest} ")?;
}
for (key, value) in &self.vars {
match value {
Some(val) => write!(f, "--env={key}={val} ")?,
None => write!(f, "--env={key} ")?,
}
}
Ok(())
}
}
impl RunCommon {
pub fn store_limits(&self) -> StoreLimits {
let mut limits = StoreLimitsBuilder::new();
if let Some(max) = self.common.wasm.max_memory_size {
limits = limits.memory_size(max);
}
if let Some(max) = self.common.wasm.max_table_elements {
limits = limits.table_elements(max);
}
if let Some(max) = self.common.wasm.max_instances {
limits = limits.instances(max);
}
if let Some(max) = self.common.wasm.max_tables {
limits = limits.tables(max);
}
if let Some(max) = self.common.wasm.max_memories {
limits = limits.memories(max);
}
if let Some(enable) = self.common.wasm.trap_on_grow_failure {
limits = limits.trap_on_grow_failure(enable);
}
limits.build()
}
pub fn ensure_allow_precompiled(&self) -> Result<()> {
if self.allow_precompiled {
Ok(())
} else {
bail!("running a precompiled module requires the `--allow-precompiled` flag")
}
}
#[cfg(feature = "component-model")]
fn ensure_allow_components(&self) -> Result<()> {
if self.common.wasm.component_model == Some(false) {
bail!("cannot execute a component without `--wasm component-model`");
}
Ok(())
}
pub fn load_module(
&self,
engine: &Engine,
path: &Path,
preloaded_bytes: Option<&[u8]>,
) -> Result<RunTarget> {
let path = match path.to_str() {
#[cfg(unix)]
Some("-") => "/dev/stdin".as_ref(),
_ => path,
};
if let Some(bytes) = preloaded_bytes {
self.load_module_contents(
engine,
path,
&bytes,
|| unsafe { Module::deserialize(engine, &bytes) },
#[cfg(feature = "component-model")]
|| unsafe { Component::deserialize(engine, &bytes) },
)
} else {
let file =
File::open(path).with_context(|| format!("failed to open wasm module {path:?}"))?;
// First attempt to load the module as an mmap. If this succeeds then
// detection can be done with the contents of the mmap and if a
// precompiled module is detected then `deserialize_file` can be used
// which is a slightly more optimal version than `deserialize` since we
// can leave most of the bytes on disk until they're referenced.
//
// If the mmap fails, for example if stdin is a pipe, then fall back to
// `std::fs::read` to load the contents. At that point precompiled
// modules must go through the `deserialize` functions.
//
// Note that this has the unfortunate side effect for precompiled
// modules on disk that they're opened once to detect what they are and
// then again internally in Wasmtime as part of the `deserialize_file`
// API. Currently there's no way to pass the `MmapVec` here through to
// Wasmtime itself (that'd require making `MmapVec` a public type, both
// which isn't ready to happen at this time). It's hoped though that
// opening a file twice isn't too bad in the grand scheme of things with
// respect to the CLI.
match wasmtime::_internal::MmapVec::from_file(file) {
Ok(map) => self.load_module_contents(
engine,
path,
&map,
|| unsafe { Module::deserialize_file(engine, path) },
#[cfg(feature = "component-model")]
|| unsafe { Component::deserialize_file(engine, path) },
),
Err(_) => {
let bytes = std::fs::read(path)
.with_context(|| format!("failed to read file: {}", path.display()))?;
self.load_module_contents(
engine,
path,
&bytes,
|| unsafe { Module::deserialize(engine, &bytes) },
#[cfg(feature = "component-model")]
|| unsafe { Component::deserialize(engine, &bytes) },
)
}
}
}
}
pub fn load_module_contents(
&self,
engine: &Engine,
path: &Path,
bytes: &[u8],
deserialize_module: impl FnOnce() -> Result<Module>,
#[cfg(feature = "component-model")] deserialize_component: impl FnOnce() -> Result<Component>,
) -> Result<RunTarget> {
Ok(match Engine::detect_precompiled(bytes) {
Some(Precompiled::Module) => {
self.ensure_allow_precompiled()?;
RunTarget::Core(deserialize_module()?)
}
#[cfg(feature = "component-model")]
Some(Precompiled::Component) => {
self.ensure_allow_precompiled()?;
self.ensure_allow_components()?;
RunTarget::Component(deserialize_component()?)
}
#[cfg(not(feature = "component-model"))]
Some(Precompiled::Component) => {
bail!("support for components was not enabled at compile time");
}
#[cfg(any(feature = "cranelift", feature = "winch"))]
None => {
let mut code = wasmtime::CodeBuilder::new(engine);
code.wasm_binary_or_text(bytes, Some(path))?;
crate::code_builder::configure_code_builder(&self.common, &mut code)?;
match code.hint() {
Some(wasmtime::CodeHint::Component) => {
#[cfg(feature = "component-model")]
{
self.ensure_allow_components()?;
RunTarget::Component(code.compile_component()?)
}
#[cfg(not(feature = "component-model"))]
{
bail!("support for components was not enabled at compile time");
}
}
Some(wasmtime::CodeHint::Module) | None => {
RunTarget::Core(code.compile_module()?)
}
}
}
#[cfg(not(any(feature = "cranelift", feature = "winch")))]
None => {
let _ = (path, engine);
bail!("support for compiling modules was disabled at compile time");
}
})
}
/// Configures `builder` from this command's WASI options.
///
/// `allow_blocking_current_thread` is passed on to
/// [`WasiCtxBuilder::allow_blocking_current_thread`].
pub fn configure_wasip2(
&self,
builder: &mut WasiCtxBuilder,
allow_blocking_current_thread: bool,
) -> Result<()> {
builder.allow_blocking_current_thread(allow_blocking_current_thread);
if self.common.wasi.inherit_env == Some(true) {
for (k, v) in std::env::vars_os() {
let k = k.to_str().ok_or_else(|| {
format_err!("environment variable name {k:?} not valid utf-8")
})?;
let v = v.to_str().ok_or_else(|| {
format_err!("environment variable {k:?} value {v:?} not valid utf-8")
})?;
builder.env(&k, &v);
}
}
for (key, value) in self.vars.iter() {
let value = match value {
Some(value) => value.clone(),
None => match std::env::var_os(key) {
Some(val) => val
.into_string()
.map_err(|_| format_err!("environment variable `{key}` not valid utf-8"))?,
None => {
// leave the env var un-set in the guest
continue;
}
},
};
builder.env(key, &value);
}
for (host, guest) in self.dirs.iter() {
builder.preopened_dir(host, guest, wasmtime_wasi::FsPerms::ReadWrite)?;
}
if let Some(cwd) = &self.common.wasi.cwd {
builder.initial_cwd(cwd);
}
for _ in self.compute_preopen_sockets()? {
bail!("components do not support --tcplisten");
}
if self.common.wasi.inherit_network == Some(true) {
builder.inherit_network();
// Implicitly enable TCP/UDP if the entire network is being
// inherited to avoid the need to also pass `-Stcp,udp`.
builder.allow_tcp(true).allow_udp(true);
}
if let Some(enable) = self.common.wasi.allow_ip_name_lookup {
builder.allow_ip_name_lookup(enable);
}
// The default of 64KiB for this value is a bit small for a CLI
// embedding which has more leeway with resources and just a single
// guest, so raise it by default if no configuration is otherwise
// applied.
builder.max_io_size(
self.common
.wasi
.max_io_size
.unwrap_or(NonZeroUsize::new(2 << 20).unwrap()),
);
if let Some(enable) = self.common.wasi.tcp {
builder.allow_tcp(enable);
}
if let Some(enable) = self.common.wasi.udp {
builder.allow_udp(enable);
}
if let Some(max_size) = self.common.wasi.max_random_size {
builder.max_random_size(max_size);
}
Ok(())
}
#[cfg(feature = "wasi-http")]
pub fn wasi_http_ctx(&self) -> Result<wasmtime_wasi_http::WasiHttpCtx> {
let mut http = wasmtime_wasi_http::WasiHttpCtx::new();
if let Some(limit) = self.common.wasi.max_http_fields_size {
http.set_field_size_limit(limit);
}
Ok(http)
}
#[cfg(feature = "wasi-http")]
pub fn wasi_http_hooks(&self) -> HttpHooks {
HttpHooks {
p2_outgoing_body_buffer_chunks: self
.common
.wasi
.http_outgoing_body_buffer_chunks
.map(|n| n.get())
.unwrap_or(wasmtime_wasi_http::p2::DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS),
p2_outgoing_body_chunk_size: self
.common
.wasi
.http_outgoing_body_chunk_size
.map(|n| n.get())
.unwrap_or(wasmtime_wasi_http::p2::DEFAULT_OUTGOING_BODY_CHUNK_SIZE),
#[cfg(feature = "component-model-async")]
p3_outgoing_body_buffer_chunks: self
.common
.wasi
.http_outgoing_body_buffer_chunks
.map(|n| n.get())
.unwrap_or(wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS),
#[cfg(feature = "component-model-async")]
p3_outgoing_body_chunk_size: self
.common
.wasi
.http_outgoing_body_chunk_size
.map(|n| n.get())
.unwrap_or(wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_CHUNK_SIZE),
}
}
pub fn compute_preopen_sockets(&self) -> Result<Vec<TcpListener>> {
let mut listeners = vec![];
for address in &self.common.wasi.tcplisten {
let stdlistener = std::net::TcpListener::bind(address)
.with_context(|| format!("failed to bind to address '{address}'"))?;
let _ = stdlistener.set_nonblocking(true)?;
listeners.push(stdlistener)
}
Ok(listeners)
}
pub fn validate_p3_option(&self) -> Result<()> {
let p3 = self.common.wasi.p3.unwrap_or(P3_DEFAULT);
if p3 && !cfg!(feature = "component-model-async") {
bail!("support for WASIp3 disabled at compile time");
}
Ok(())
}
pub fn validate_cli_enabled(&self) -> Result<Option<bool>> {
let mut cli = self.common.wasi.cli;
// Accept -Scommon as a deprecated alias for -Scli.
if let Some(common) = self.common.wasi.common {
if cli.is_some() {
bail!(
"The -Scommon option should not be use with -Scli as it is a deprecated alias"
);
} else {
// In the future, we may add a warning here to tell users to use
// `-S cli` instead of `-S common`.
cli = Some(common);
}
}
Ok(cli)
}
/// Adds `wasmtime-wasi` interfaces (dubbed "-Scli" in the flags to the
/// `wasmtime` command) to the `linker` provided.
///
/// This will handle adding various WASI standard versions to the linker
/// internally.
#[cfg(feature = "component-model")]
pub fn add_wasmtime_wasi_to_linker<T>(
&self,
linker: &mut wasmtime::component::Linker<T>,
) -> Result<()>
where
T: wasmtime_wasi::WasiView,
{
let mut p2_options = wasmtime_wasi::p2::bindings::LinkOptions::default();
if self.common.wasi.cli_exit_with_code == Some(false) {
eprintln!("warning: cannot disable `-Scli-exit-with-code` any more");
}
p2_options.network_error_code(self.common.wasi.network_error_code.unwrap_or(false));
wasmtime_wasi::p2::add_to_linker_with_options_async(linker, &p2_options)?;
#[cfg(feature = "component-model-async")]
if self.common.wasi.p3.unwrap_or(P3_DEFAULT) {
let p3_options = wasmtime_wasi::p3::bindings::LinkOptions::default();
wasmtime_wasi::p3::add_to_linker_with_options(linker, &p3_options)
.context("failed to link `wasi:[email protected]`")?;
}
Ok(())
}
pub fn configure_store<T>(
&self,
store: &mut Store<T>,
limits: fn(&mut T) -> &mut StoreLimits,
) -> Result<()>
where
T: wasmtime_wasi::WasiView,
{
if let Some(max) = self.common.wasi.max_resources {
if self.common.wasi.cli != Some(false) {
store.data_mut().ctx().table.set_max_capacity(max);
}
#[cfg(feature = "component-model-async")]
if let Some(table) = store.concurrent_resource_table() {
table.set_max_capacity(max);
}
}
self.common.configure_store(store)?;
*limits(store.data_mut()) = self.store_limits();
store.limiter(move |t| limits(t));
Ok(())
}
}
#[derive(Clone, PartialEq)]
pub enum Profile {
Native(wasmtime::ProfilingStrategy),
Guest { path: String, interval: Duration },
}
impl std::fmt::Display for Profile {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Profile::Native(strategy) => match strategy {
wasmtime::ProfilingStrategy::PerfMap => write!(f, "perfmap"),
wasmtime::ProfilingStrategy::JitDump => write!(f, "jitdump"),
wasmtime::ProfilingStrategy::VTune => write!(f, "vtune"),
wasmtime::ProfilingStrategy::Pulley => write!(f, "pulley"),
other => write!(f, "{other:?}"),
},
Profile::Guest { path, interval } => {
write!(f, "guest,{path},{}", interval.as_millis())?;
Ok(())
}
}
}
}
impl Profile {
/// Parse the `profile` argument to either the `run` or `serve` commands.
pub fn parse(s: &str) -> Result<Profile> {
let parts = s.split(',').collect::<Vec<_>>();
match &parts[..] {
["perfmap"] => Ok(Profile::Native(wasmtime::ProfilingStrategy::PerfMap)),
["jitdump"] => Ok(Profile::Native(wasmtime::ProfilingStrategy::JitDump)),
["vtune"] => Ok(Profile::Native(wasmtime::ProfilingStrategy::VTune)),
["pulley"] => Ok(Profile::Native(wasmtime::ProfilingStrategy::Pulley)),
["guest"] => Ok(Profile::Guest {
path: "wasmtime-guest-profile.json".to_string(),
interval: Duration::from_millis(10),
}),
["guest", path] => Ok(Profile::Guest {
path: path.to_string(),
interval: Duration::from_millis(10),
}),
["guest", path, dur] => Ok(Profile::Guest {
path: path.to_string(),
interval: WasmtimeOptionValue::parse(Some(dur))?,
}),
_ => bail!("unknown profiling strategy: {s}"),
}
}
}
#[derive(Copy, Clone, Debug)]
#[cfg(feature = "wasi-http")]
pub struct HttpHooks {
p2_outgoing_body_buffer_chunks: usize,
p2_outgoing_body_chunk_size: usize,
#[cfg(feature = "component-model-async")]
p3_outgoing_body_buffer_chunks: usize,
#[cfg(feature = "component-model-async")]
p3_outgoing_body_chunk_size: usize,
}
#[cfg(feature = "wasi-http")]
impl Default for HttpHooks {
fn default() -> Self {
Self {
p2_outgoing_body_buffer_chunks:
wasmtime_wasi_http::p2::DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS,
p2_outgoing_body_chunk_size: wasmtime_wasi_http::p2::DEFAULT_OUTGOING_BODY_CHUNK_SIZE,
#[cfg(feature = "component-model-async")]
p3_outgoing_body_buffer_chunks:
wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS,
#[cfg(feature = "component-model-async")]
p3_outgoing_body_chunk_size: wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_CHUNK_SIZE,
}
}
}
#[cfg(feature = "wasi-http")]
impl wasmtime_wasi_http::WasiHttpHooks for HttpHooks {
fn p2_outgoing_body_buffer_chunks(&mut self) -> usize {
self.p2_outgoing_body_buffer_chunks
}
fn p2_outgoing_body_chunk_size(&mut self) -> usize {
self.p2_outgoing_body_chunk_size
}
#[cfg(feature = "component-model-async")]
fn p3_outgoing_body_buffer_chunks(&mut self) -> usize {
self.p3_outgoing_body_buffer_chunks
}
#[cfg(feature = "component-model-async")]
fn p3_outgoing_body_chunk_size(&mut self) -> usize {
self.p3_outgoing_body_chunk_size
}
}
#[cfg(all(test, feature = "wasi-http", feature = "component-model-async"))]
mod tests {
use super::RunCommon;
use clap::Parser as _;
use std::num::NonZeroUsize;
use wasmtime_wasi_http::WasiHttpHooks as _;
/// `-Shttp-outgoing-body-*` lands in `CommonWasiOptions`; from there it has
/// to reach both the p2 and the p3 hooks.
#[test]
fn p3_outgoing_body_options_reach_hooks() {
let mut cli = RunCommon::try_parse_from(["wasmtime"]).expect("failed to parse options");
cli.common.wasi.http_outgoing_body_buffer_chunks = NonZeroUsize::new(3);
cli.common.wasi.http_outgoing_body_chunk_size = NonZeroUsize::new(1024);
let mut hooks = cli.wasi_http_hooks();
assert_eq!(hooks.p2_outgoing_body_buffer_chunks(), 3);
assert_eq!(hooks.p3_outgoing_body_buffer_chunks(), 3);
assert_eq!(hooks.p2_outgoing_body_chunk_size(), 1024);
assert_eq!(hooks.p3_outgoing_body_chunk_size(), 1024);
// Without the options set, both sides keep their documented defaults.
let cli = RunCommon::try_parse_from(["wasmtime"]).expect("failed to parse options");
let mut hooks = cli.wasi_http_hooks();
assert_eq!(
hooks.p3_outgoing_body_buffer_chunks(),
wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_BUFFER_CHUNKS,
);
assert_eq!(
hooks.p3_outgoing_body_chunk_size(),
wasmtime_wasi_http::p3::DEFAULT_OUTGOING_BODY_CHUNK_SIZE,
);
}
}