Add a new -Sp3 option to the CLI (bytecodealliance#11423)

alexcrichton · bongjunj · commit 22b4939fae45 · 2025-10-20T08:05:02.000Z
* Add a new `-Sp3` option to the CLI

This commit adds a new WASI-specific CLI option dubbed "p3" which
controls whether WASIp3 interfaces are added to the component linker and
whether WASIp3 exports are searched for. Integration here is only added
with `wasmtime run` and support for `wasmtime serve` will come once
wasi:http is migrated to this repository from the p3-prototyping
repository.

The `-Sp3` option is off-by-default at this time but this is structured
to enable it by default in the future. A test is added to ensure that
WASIp3 is usable and a basic "hello world" works.

Some internal refactoring was done to share more code between `run` and
`serve` with respect to adding WASI interfaces to a linker.

* Use a normal blocking test

* Fix warning
diff --git a/Cargo.toml b/Cargo.toml
@@ -485,7 +485,11 @@ wmemcheck = ["wasmtime/wmemcheck"]
 trace-log = ["wasmtime/trace-log"]
 memory-protection-keys = ["wasmtime-cli-flags/memory-protection-keys"]
 profile-pulley = ["wasmtime/profile-pulley"]
-component-model-async = ["wasmtime-cli-flags/component-model-async", "component-model"]
+component-model-async = [
+  "wasmtime-cli-flags/component-model-async",
+  "component-model",
+  "wasmtime-wasi?/p3",
+]
 
 # This feature, when enabled, will statically compile out all logging statements
 # throughout Wasmtime and its dependencies.
diff --git a/crates/cli-flags/src/lib.rs b/crates/cli-flags/src/lib.rs
@@ -477,6 +477,8 @@ wasmtime_option_group! {
         /// Preset data for the In-Memory provider of WASI key-value API.
         #[serde(skip)]
         pub keyvalue_in_memory_data: Vec<KeyValuePair>,
+        /// Enable support for WASIp3 APIs.
+        pub p3: Option<bool>,
     }
 
     enum Wasi {
diff --git a/crates/test-programs/src/bin/cli_p3_hello_stdout.rs b/crates/test-programs/src/bin/cli_p3_hello_stdout.rs
@@ -0,0 +1,18 @@
+use test_programs::p3::*;
+
+struct Component;
+
+export!(Component);
+
+impl exports::wasi::cli::run::Guest for Component {
+    async fn run() -> Result<(), ()> {
+        let (mut tx, rx) = wit_stream::new();
+        wasi::cli::stdout::set_stdout(rx);
+        tx.write(b"hello, world\n".to_vec()).await;
+        Ok(())
+    }
+}
+
+fn main() {
+    panic!("should call p3 entrypoint");
+}
diff --git a/src/commands/run.rs b/src/commands/run.rs
@@ -493,30 +493,13 @@ impl RunCommand {
             #[cfg(feature = "component-model")]
             CliLinker::Component(linker) => {
                 let component = main_target.unwrap_component();
-                if self.invoke.is_some() {
+                let result = if self.invoke.is_some() {
                     self.invoke_component(&mut *store, component, linker).await
                 } else {
-                    let command = wasmtime_wasi::p2::bindings::Command::instantiate_async(
-                        &mut *store,
-                        component,
-                        linker,
-                    )
-                    .await?;
-
-                    let result = command
-                        .wasi_cli_run()
-                        .call_run(&mut *store)
+                    self.run_command_component(&mut *store, component, linker)
                         .await
-                        .context("failed to invoke `run` function")
-                        .map_err(|e| self.handle_core_dump(&mut *store, e));
-
-                    // Translate the `Result<(),()>` produced by wasm into a feigned
-                    // explicit exit here with status 1 if `Err(())` is returned.
-                    result.and_then(|wasm_result| match wasm_result {
-                        Ok(()) => Ok(()),
-                        Err(()) => Err(wasmtime_wasi::I32Exit(1).into()),
-                    })
-                }
+                };
+                result.map_err(|e| self.handle_core_dump(&mut *store, e))
             }
         };
         finish_epoch_handler(store);
@@ -596,6 +579,56 @@ impl RunCommand {
         Ok(())
     }
 
+    /// Execute the default behavior for components on the CLI, looking for
+    /// `wasi:cli`-based commands and running their exported `run` function.
+    #[cfg(feature = "component-model")]
+    async fn run_command_component(
+        &self,
+        store: &mut Store<Host>,
+        component: &wasmtime::component::Component,
+        linker: &wasmtime::component::Linker<Host>,
+    ) -> Result<()> {
+        let instance = linker.instantiate_async(&mut *store, component).await?;
+
+        let mut result = None;
+        let _ = &mut result;
+
+        // If WASIp3 is enabled at compile time, enabled at runtime, and found
+        // in this component then use that to generate the result.
+        #[cfg(feature = "component-model-async")]
+        if self.run.common.wasi.p3.unwrap_or(crate::common::P3_DEFAULT) {
+            if let Ok(command) = wasmtime_wasi::p3::bindings::Command::new(&mut *store, &instance) {
+                result = Some(
+                    instance
+                        .run_concurrent(&mut *store, async |store| {
+                            command.wasi_cli_run().call_run(store).await
+                        })
+                        .await?,
+                );
+            }
+        }
+
+        let result = match result {
+            Some(result) => result,
+            // If WASIp3 wasn't found then fall back to requiring WASIp2 and
+            // this'll report an error if the right export doesn't exist.
+            None => {
+                wasmtime_wasi::p2::bindings::Command::new(&mut *store, &instance)?
+                    .wasi_cli_run()
+                    .call_run(&mut *store)
+                    .await
+            }
+        };
+        let wasm_result = result.context("failed to invoke `run` function")?;
+
+        // Translate the `Result<(),()>` produced by wasm into a feigned
+        // explicit exit here with status 1 if `Err(())` is returned.
+        match wasm_result {
+            Ok(()) => Ok(()),
+            Err(()) => Err(wasmtime_wasi::I32Exit(1).into()),
+        }
+    }
+
     #[cfg(feature = "component-model")]
     fn search_component(
         engine: &Engine,
@@ -756,20 +789,8 @@ impl RunCommand {
         store: &mut Store<Host>,
         module: &RunTarget,
     ) -> Result<()> {
-        let mut cli = self.run.common.wasi.cli;
-
-        // Accept -Scommon as a deprecated alias for -Scli.
-        if let Some(common) = self.run.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);
-            }
-        }
+        self.run.validate_p3_option()?;
+        let cli = self.run.validate_cli_enabled()?;
 
         if cli != Some(false) {
             match linker {
@@ -801,8 +822,7 @@ impl RunCommand {
                 }
                 #[cfg(feature = "component-model")]
                 CliLinker::Component(linker) => {
-                    let link_options = self.run.compute_wasi_features();
-                    wasmtime_wasi::p2::add_to_linker_with_options_async(linker, &link_options)?;
+                    self.run.add_wasmtime_wasi_to_linker(linker)?;
                     self.set_wasi_ctx(store)?;
                 }
             }
diff --git a/src/commands/serve.rs b/src/commands/serve.rs
@@ -256,20 +256,8 @@ impl ServeCommand {
     }
 
     fn add_to_linker(&self, linker: &mut Linker<Host>) -> Result<()> {
-        let mut cli = self.run.common.wasi.cli;
-
-        // Accept -Scommon as a deprecated alias for -Scli.
-        if let Some(common) = self.run.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);
-            }
-        }
+        self.run.validate_p3_option()?;
+        let cli = self.run.validate_cli_enabled()?;
 
         // Repurpose the `-Scli` flag of `wasmtime run` for `wasmtime serve`
         // to serve as a signal to enable all WASI interfaces instead of just
@@ -280,8 +268,7 @@ impl ServeCommand {
         // bindings which adds just those interfaces that the proxy interface
         // uses.
         if cli == Some(true) {
-            let link_options = self.run.compute_wasi_features();
-            wasmtime_wasi::p2::add_to_linker_with_options_async(linker, &link_options)?;
+            self.run.add_wasmtime_wasi_to_linker(linker)?;
             wasmtime_wasi_http::add_only_http_to_linker_async(linker)?;
         } else {
             wasmtime_wasi_http::add_to_linker_async(linker)?;
diff --git a/src/common.rs b/src/common.rs
@@ -7,11 +7,16 @@ use std::{fs::File, path::Path, time::Duration};
 use wasmtime::{Engine, Module, Precompiled, StoreLimits, StoreLimitsBuilder};
 use wasmtime_cli_flags::{CommonOptions, opt::WasmtimeOptionValue};
 use wasmtime_wasi::WasiCtxBuilder;
-use wasmtime_wasi::p2::bindings::LinkOptions;
 
 #[cfg(feature = "component-model")]
 use wasmtime::component::Component;
 
+/// Whether or not WASIp3 is enabled by default.
+///
+/// Currently this is disabled (the `&& false`), but that'll get removed in the
+/// future.
+pub const P3_DEFAULT: bool = cfg!(feature = "component-model-async") && false;
+
 pub enum RunTarget {
     Core(Module),
 
@@ -336,11 +341,60 @@ impl RunCommon {
         Ok(listeners)
     }
 
-    pub fn compute_wasi_features(&self) -> LinkOptions {
-        let mut options = LinkOptions::default();
-        options.cli_exit_with_code(self.common.wasi.cli_exit_with_code.unwrap_or(false));
-        options.network_error_code(self.common.wasi.network_error_code.unwrap_or(false));
-        options
+    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();
+        p2_options.cli_exit_with_code(self.common.wasi.cli_exit_with_code.unwrap_or(false));
+        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 mut p3_options = wasmtime_wasi::p3::bindings::LinkOptions::default();
+            p3_options.cli_exit_with_code(self.common.wasi.cli_exit_with_code.unwrap_or(false));
+            wasmtime_wasi::p3::add_to_linker_with_options(linker, &p3_options)
+                .context("failed to link `wasi:cli@0.3.x`")?;
+        }
+
+        Ok(())
     }
 }
 
diff --git a/tests/all/cli_tests.rs b/tests/all/cli_tests.rs
@@ -2123,6 +2123,23 @@ start a print 1234
         cli_serve_guest_never_invoked_set(CLI_SERVE_TRAP_BEFORE_SET_COMPONENT).await
     }
 
+    #[test]
+    fn cli_p3_hello_stdout() -> Result<()> {
+        let output = run_wasmtime(&[
+            "run",
+            "-Wcomponent-model-async",
+            "-Sp3",
+            CLI_P3_HELLO_STDOUT_COMPONENT,
+        ]);
+        if cfg!(feature = "component-model-async") {
+            let output = output?;
+            assert_eq!(output, "hello, world\n");
+        } else {
+            assert!(output.is_err());
+        }
+        Ok(())
+    }
+
     mod invoke {
         use super::*;
 

Original file line number	Diff line number	Diff line change
`@@ -477,6 +477,8 @@ wasmtime_option_group! {`
`477`	`477`	`/// Preset data for the In-Memory provider of WASI key-value API.`
`478`	`478`	`#[serde(skip)]`
`479`	`479`	`pub keyvalue_in_memory_data: Vec<KeyValuePair>,`
	`480`	`+ /// Enable support for WASIp3 APIs.`
	`481`	`+ pub p3: Option<bool>,`
`480`	`482`	`}`
`481`	`483`
`482`	`484`	`enum Wasi {`