A lightweight WebAssembly runtime that is fast, secure, and standards-compliant
use crate::p2;
use crate::{NamedId, WasiCtxNamedView};
use std::marker;
use std::pin::Pin;
use std::sync::Arc;
use tokio::io::{AsyncRead, AsyncWrite, empty};
use wasmtime::component::{HasData, ResourceTable};
use wasmtime_wasi_io::streams::{InputStream, OutputStream, StreamError};
mod empty;
mod file;
mod locked_async;
mod mem;
mod stdout;
mod worker_thread_stdin;
pub use self::file::{InputFile, OutputFile};
pub use self::locked_async::{AsyncStdinStream, AsyncStdoutStream};
/// Convert a host `io::Error` into a `StreamError`, matching the error-code
/// recovery that wasip1 performs via `filesystem::ErrorCode::from`.
///
/// * `BrokenPipe` is mapped to `StreamError::Closed` so that downstream
/// consumers (e.g. wasi-libc) can recover `EPIPE` rather than falling back
/// to a generic `EIO`.
///
/// * All other errors (including `IsADirectory`, permission errors, etc.) are
/// preserved as `LastOperationFailed` with the original `std::io::Error`
/// intact. This allows guests to recover the specific error code via the
/// `wasi:filesystem/types#filesystem-error-code` function, which downcasts
/// the error back to `std::io::Error` and maps it through
/// `ErrorCode::from`.
fn stream_error_from(e: std::io::Error) -> StreamError {
if e.kind() == std::io::ErrorKind::BrokenPipe {
StreamError::Closed
} else {
StreamError::LastOperationFailed(e.into())
}
}
// Convenience reexport for stdio types so tokio doesn't have to be imported
// itself.
#[doc(no_inline)]
pub use tokio::io::{Stderr, Stdin, Stdout, stderr, stdin, stdout};
/// A helper struct which implements [`HasData`] for the `wasi:cli` APIs.
///
/// This can be useful when directly calling `add_to_linker` functions directly,
/// such as [`wasmtime_wasi::p2::bindings::cli::environment::add_to_linker`] as
/// the `D` type parameter. See [`HasData`] for more information about the type
/// parameter's purpose.
///
/// When using this type you can skip the [`WasiCliView`] trait, for
/// example.
///
/// [`wasmtime_wasi::p2::bindings::cli::environment::add_to_linker`]: crate::p2::bindings::cli::environment::add_to_linker
///
/// # Examples
///
/// ```
/// use wasmtime::component::{Linker, ResourceTable};
/// use wasmtime::{Engine, Result};
/// use wasmtime_wasi::cli::*;
///
/// struct MyStoreState {
/// table: ResourceTable,
/// cli: WasiCliCtx,
/// }
///
/// fn main() -> Result<()> {
/// let engine = Engine::default();
/// let mut linker = Linker::new(&engine);
///
/// wasmtime_wasi::p2::bindings::cli::environment::add_to_linker::<MyStoreState, WasiCli>(
/// &mut linker,
/// |state| WasiCliCtxView {
/// table: &mut state.table,
/// ctx: &mut state.cli,
/// },
/// )?;
/// Ok(())
/// }
/// ```
pub struct WasiCli;
impl HasData for WasiCli {
type Data<'a> = WasiCliCtxView<'a>;
}
/// Provides a "view" of `wasi:cli`-related context used to implement host
/// traits.
pub trait WasiCliView: Send {
fn cli(&mut self) -> WasiCliCtxView<'_>;
}
pub struct WasiCliCtxView<'a> {
pub ctx: &'a mut WasiCliCtx,
pub table: &'a mut ResourceTable,
}
pub struct WasiCliCtx {
pub(crate) environment: Vec<(String, String)>,
pub(crate) arguments: Vec<String>,
pub(crate) initial_cwd: Option<String>,
pub(crate) stdin: Box<dyn StdinStream>,
pub(crate) stdout: Box<dyn StdoutStream>,
pub(crate) stderr: Box<dyn StdoutStream>,
}
impl Default for WasiCliCtx {
fn default() -> WasiCliCtx {
WasiCliCtx {
environment: Vec::new(),
arguments: Vec::new(),
initial_cwd: None,
stdin: Box::new(empty()),
stdout: Box::new(empty()),
stderr: Box::new(empty()),
}
}
}
pub trait IsTerminal {
/// Returns whether this stream is backed by a TTY.
fn is_terminal(&self) -> bool;
}
/// A trait used to represent the standard input to a guest program.
///
/// Note that there are many built-in implementations of this trait for various
/// types such as [`tokio::io::Stdin`], [`tokio::io::Empty`], and
/// [`p2::pipe::MemoryInputPipe`].
pub trait StdinStream: IsTerminal + Send {
/// Creates a fresh stream which is reading stdin.
///
/// Note that the returned stream must share state with all other streams
/// previously created. Guests may create multiple handles to the same stdin
/// and they should all be synchronized in their progress through the
/// program's input.
///
/// Note that this means that if one handle becomes ready for reading they
/// all become ready for reading. Subsequently if one is read from it may
/// mean that all the others are no longer ready for reading. This is
/// basically a consequence of the way the WIT APIs are designed today.
fn async_stream(&self) -> Box<dyn AsyncRead + Send + Sync>;
/// Same as [`Self::async_stream`] except that a WASIp2 [`InputStream`] is
/// returned.
///
/// Note that this has a default implementation which uses
/// [`p2::pipe::AsyncReadStream`] as an adapter, but this can be overridden
/// if there's a more specialized implementation available.
fn p2_stream(&self) -> Box<dyn InputStream> {
Box::new(p2::pipe::AsyncReadStream::new(Pin::from(
self.async_stream(),
)))
}
}
/// Similar to [`StdinStream`], except for output.
///
/// This is used both for a guest stdin and a guest stdout.
///
/// Note that there are many built-in implementations of this trait for various
/// types such as [`tokio::io::Stdout`], [`tokio::io::Empty`], and
/// [`p2::pipe::MemoryOutputPipe`].
pub trait StdoutStream: IsTerminal + Send {
/// Returns a fresh new stream which can write to this output stream.
///
/// Note that all output streams should output to the same logical source.
/// This means that it's possible for each independent stream to acquire a
/// separate "permit" to write and then act on that permit. Note that
/// additionally at this time once a permit is "acquired" there's no way to
/// release it, for example you can wait for readiness and then never
/// actually write in WASI. This means that acquisition of a permit for one
/// stream cannot discount the size of a permit another stream could
/// obtain.
///
/// Implementations must be able to handle this
fn async_stream(&self) -> Box<dyn AsyncWrite + Send + Sync>;
/// Same as [`Self::async_stream`] except that a WASIp2 [`OutputStream`] is
/// returned.
///
/// Note that this has a default implementation which uses
/// [`p2::pipe::AsyncWriteStream`] as an adapter, but this can be overridden
/// if there's a more specialized implementation available.
fn p2_stream(&self) -> Box<dyn OutputStream> {
Box::new(p2::pipe::AsyncWriteStream::new(
8192, // FIXME: extract this to a constant.
Pin::from(self.async_stream()),
))
}
}
// Forward `&T => T`
impl<T: ?Sized + IsTerminal> IsTerminal for &T {
fn is_terminal(&self) -> bool {
T::is_terminal(self)
}
}
impl<T: ?Sized + StdinStream + Sync> StdinStream for &T {
fn p2_stream(&self) -> Box<dyn InputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncRead + Send + Sync> {
T::async_stream(self)
}
}
impl<T: ?Sized + StdoutStream + Sync> StdoutStream for &T {
fn p2_stream(&self) -> Box<dyn OutputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncWrite + Send + Sync> {
T::async_stream(self)
}
}
// Forward `&mut T => T`
impl<T: ?Sized + IsTerminal> IsTerminal for &mut T {
fn is_terminal(&self) -> bool {
T::is_terminal(self)
}
}
impl<T: ?Sized + StdinStream + Sync> StdinStream for &mut T {
fn p2_stream(&self) -> Box<dyn InputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncRead + Send + Sync> {
T::async_stream(self)
}
}
impl<T: ?Sized + StdoutStream + Sync> StdoutStream for &mut T {
fn p2_stream(&self) -> Box<dyn OutputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncWrite + Send + Sync> {
T::async_stream(self)
}
}
// Forward `Box<T> => T`
impl<T: ?Sized + IsTerminal> IsTerminal for Box<T> {
fn is_terminal(&self) -> bool {
T::is_terminal(self)
}
}
impl<T: ?Sized + StdinStream + Sync> StdinStream for Box<T> {
fn p2_stream(&self) -> Box<dyn InputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncRead + Send + Sync> {
T::async_stream(self)
}
}
impl<T: ?Sized + StdoutStream + Sync> StdoutStream for Box<T> {
fn p2_stream(&self) -> Box<dyn OutputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncWrite + Send + Sync> {
T::async_stream(self)
}
}
// Forward `Arc<T> => T`
impl<T: ?Sized + IsTerminal> IsTerminal for Arc<T> {
fn is_terminal(&self) -> bool {
T::is_terminal(self)
}
}
impl<T: ?Sized + StdinStream + Sync> StdinStream for Arc<T> {
fn p2_stream(&self) -> Box<dyn InputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncRead + Send + Sync> {
T::async_stream(self)
}
}
impl<T: ?Sized + StdoutStream + Sync> StdoutStream for Arc<T> {
fn p2_stream(&self) -> Box<dyn OutputStream> {
T::p2_stream(self)
}
fn async_stream(&self) -> Box<dyn AsyncWrite + Send + Sync> {
T::async_stream(self)
}
}
/// A helper struct which implements [`HasData`] for the `wasi:cli` APIs when
/// used in combination with named imports.
///
/// This structure is similar in purpose to [`WasiCli`] and is used
/// when using the [`named_imports`] module for `wasi:cli`. This structure
/// serves as the `D` type parameter for `add_to_linker` functions.
///
/// [`named_imports`]: crate::p3::bindings::named_imports::wasi::cli
///
/// # Meaning of the `T` parameter
///
/// Here the `T` must be something that implements [`WasiCliNamedView`]. The
/// corresponding `Data` for this type is [`WasiCtxNamedView`] which internally
/// will contain `&mut T`.
///
/// Effectively you're going to implement [`WasiCliNamedView`] for something in
/// your embedding, and that's the `T` you'll fill in here.
///
/// # Examples
///
/// ```
/// use wasmtime::component::{Linker, Component, ResourceTable};
/// use wasmtime::{Engine, Result};
/// use wasmtime_wasi::{NamedId, WasiCtxNamedView};
/// use wasmtime_wasi::cli::*;
/// use wasmtime_wasi::p2::bindings::named_imports;
/// use std::collections::HashMap;
///
/// struct MyStoreState {
/// table: ResourceTable,
/// states: HashMap<NamedId, WasiCliCtx>,
/// }
///
/// fn main() -> Result<()> {
/// let engine = Engine::default();
/// let mut linker = Linker::new(&engine);
/// let component = Component::new(&engine, "(component)")?;
/// let mut name_map = HashMap::new();
///
/// named_imports::wasi::cli::environment::add_to_linker::<MyStoreState, WasiCliNamed<MyStoreState>>(
/// &mut linker,
/// &component,
/// |name| {
/// let len = name_map.len();
/// Ok(NamedId(*name_map.entry(name.to_string()).or_insert(len)))
/// },
/// |state| WasiCtxNamedView(state),
/// )?;
/// Ok(())
/// }
///
/// impl WasiCliNamedView for MyStoreState {
/// fn cli(&mut self, id: NamedId) -> WasiCliCtxView<'_> {
/// let ctx = self.states.get_mut(&id).expect("state for id");
/// WasiCliCtxView {
/// table: &mut self.table,
/// ctx,
/// }
/// }
/// }
/// ```
pub struct WasiCliNamed<T>(marker::PhantomData<fn() -> T>);
impl<T> HasData for WasiCliNamed<T>
where
T: WasiCliNamedView,
{
type Data<'a> = WasiCtxNamedView<'a, T>;
}
/// A trait used to look up a specific `wasi:cli` context for a named import.
///
/// This trait is used in conjunction with the [`named_imports`] bindings
/// generated for all WASI interfaces. The purpose of this trait is for
/// embedders to define how a [`NamedId`] maps to a particular `wasi:cli`
/// context, here returned as [`WasiCliCtxView`]. Embedders are responsible
/// for assigning meaning to [`NamedId`] values themselves. These IDs are
/// assigned when [`add_named_to_linker`] is called, for example, as the
/// `lookup` argument to that function.
///
/// When using [`add_named_to_linker`] it's sufficient to implement this trait
/// for the `T` in `Store<T>`. You can also instead implement the
/// [`WasiNamedView`] trait for `T` which implies an implementation of this
/// trait.
///
/// When using `add_to_linker` in the generated `bindings::named_imports`
/// module then values implementing this live within the `T` of `Store<T>`, and
/// be temporarily referenced in [`WasiCtxNamedView`] where internally that'll
/// hold `WasiCtxNamedView(&mut your_type)`.
///
/// [`named_imports`]: crate::p3::bindings::named_imports
/// [`add_named_to_linker`]: crate::p3::cli::add_named_to_linker
/// [`WasiNamedView`]: crate::WasiNamedView
///
/// # Examples
///
/// ```
/// use wasmtime::component::{Linker, Component, ResourceTable};
/// use wasmtime::{Engine, Result};
/// use wasmtime_wasi::{NamedId, WasiCtxNamedView};
/// use wasmtime_wasi::cli::*;
/// use wasmtime_wasi::p2::bindings::named_imports;
/// use std::collections::HashMap;
///
/// struct MyStoreState {
/// table: ResourceTable,
/// states: HashMap<NamedId, WasiCliCtx>,
/// }
///
/// fn main() -> Result<()> {
/// let engine = Engine::default();
/// let mut linker = Linker::new(&engine);
/// let component = Component::new(&engine, "(component)")?;
/// let mut name_map = HashMap::new();
///
/// wasmtime_wasi::p3::cli::add_named_to_linker::<MyStoreState>(
/// &mut linker,
/// &component,
/// |_, name| {
/// let len = name_map.len();
/// Ok(NamedId(*name_map.entry(name.to_string()).or_insert(len)))
/// },
/// )?;
/// Ok(())
/// }
///
/// impl WasiCliNamedView for MyStoreState {
/// fn cli(&mut self, id: NamedId) -> WasiCliCtxView<'_> {
/// let ctx = self.states.get_mut(&id).expect("state for id");
/// WasiCliCtxView {
/// table: &mut self.table,
/// ctx,
/// }
/// }
/// }
/// ```
pub trait WasiCliNamedView: Send + 'static {
/// Looks up the [`WasiCliCtxView`] for the given [`NamedId`].
///
/// This method will resolve the `id` specified to a specific CLI context
/// that is available to be used. Note that this method is specifically
/// infallible meaning that a CLI context must be returned and this cannot
/// generate a trap or panic or similar.
///
/// Embedders are responsible for allocating [`NamedId`] and assigning
/// meaning to ids. When a `Linker` is populated embedders will have the
/// ability to generate a `NamedId` for all imports found, and then that
/// embedder-allocated id is then passed back here when the corresponding
/// imported function is invoked.
///
/// It's strongly recommended, though not always required, that the
/// [`ResourceTable`] in the returned [`WasiCliCtxView`] is the same table
/// that the default context, [`WasiCliView::cli`], uses. Resources created
/// through a named import can be used through interfaces bound to the
/// default context (and vice versa), and with separate tables those lookups
/// fail or find another context's resources.
fn cli(&mut self, id: NamedId) -> WasiCliCtxView<'_>;
}
#[cfg(test)]
mod test {
use crate::cli::{AsyncStdoutStream, StdinStream, StdoutStream};
use crate::p2::{self, OutputStream};
use bytes::Bytes;
use tokio::io::AsyncReadExt;
use wasmtime::Result;
#[test]
fn memory_stdin_stream() {
// A StdinStream has the property that there are multiple
// InputStreams created, using the stream() method which are each
// views on the same shared state underneath. Consuming input on one
// stream results in consuming that input on all streams.
//
// The simplest way to measure this is to check if the MemoryInputPipe
// impl of StdinStream follows this property.
let pipe =
p2::pipe::MemoryInputPipe::new("the quick brown fox jumped over the three lazy dogs");
let mut view1 = pipe.p2_stream();
let mut view2 = pipe.p2_stream();
let read1 = view1.read(10).expect("read first 10 bytes");
assert_eq!(read1, "the quick ".as_bytes(), "first 10 bytes");
let read2 = view2.read(10).expect("read second 10 bytes");
assert_eq!(read2, "brown fox ".as_bytes(), "second 10 bytes");
let read3 = view1.read(10).expect("read third 10 bytes");
assert_eq!(read3, "jumped ove".as_bytes(), "third 10 bytes");
let read4 = view2.read(10).expect("read fourth 10 bytes");
assert_eq!(read4, "r the thre".as_bytes(), "fourth 10 bytes");
}
#[tokio::test]
async fn async_stdin_stream() {
// A StdinStream has the property that there are multiple
// InputStreams created, using the stream() method which are each
// views on the same shared state underneath. Consuming input on one
// stream results in consuming that input on all streams.
//
// AsyncStdinStream is a slightly more complex impl of StdinStream
// than the MemoryInputPipe above. We can create an AsyncReadStream
// from a file on the disk, and an AsyncStdinStream from that common
// stream, then check that the same property holds as above.
let dir = tempfile::tempdir().unwrap();
let mut path = std::path::PathBuf::from(dir.path());
path.push("file");
std::fs::write(&path, "the quick brown fox jumped over the three lazy dogs").unwrap();
let file = tokio::fs::File::open(&path)
.await
.expect("open created file");
let stdin_stream = super::AsyncStdinStream::new(file);
use super::StdinStream;
let mut view1 = stdin_stream.p2_stream();
let mut view2 = stdin_stream.p2_stream();
view1.ready().await;
let read1 = view1.read(10).expect("read first 10 bytes");
assert_eq!(read1, "the quick ".as_bytes(), "first 10 bytes");
let read2 = view2.read(10).expect("read second 10 bytes");
assert_eq!(read2, "brown fox ".as_bytes(), "second 10 bytes");
let read3 = view1.read(10).expect("read third 10 bytes");
assert_eq!(read3, "jumped ove".as_bytes(), "third 10 bytes");
let read4 = view2.read(10).expect("read fourth 10 bytes");
assert_eq!(read4, "r the thre".as_bytes(), "fourth 10 bytes");
}
#[tokio::test]
async fn async_stdout_stream_unblocks() {
let (mut read, write) = tokio::io::duplex(32);
let stdout = AsyncStdoutStream::new(32, write);
let task = tokio::task::spawn(async move {
let mut stream = stdout.p2_stream();
blocking_write_and_flush(&mut *stream, "x".into())
.await
.unwrap();
});
let mut buf = [0; 100];
let n = read.read(&mut buf).await.unwrap();
assert_eq!(&buf[..n], b"x");
task.await.unwrap();
}
async fn blocking_write_and_flush(s: &mut dyn OutputStream, mut bytes: Bytes) -> Result<()> {
while !bytes.is_empty() {
let permit = s.write_ready().await?;
let len = bytes.len().min(permit);
let chunk = bytes.split_to(len);
s.write(chunk)?;
}
s.flush()?;
s.write_ready().await?;
Ok(())
}
// Verify that the stdio OutputStream implementation reports a usable
// write permit and can successfully write + flush (exercises the full
// trait impl including the error conversion path).
#[test]
fn stdio_output_stream_write_flush() {
let mut stream: Box<dyn wasmtime_wasi_io::streams::OutputStream> =
StdoutStream::p2_stream(&std::io::stderr());
let permit = stream.check_write().expect("check_write");
assert!(permit > 0, "permit should be nonzero");
// Writing empty bytes must succeed.
stream
.write(Bytes::new())
.expect("writing empty bytes should succeed");
// Flushing must succeed.
stream.flush().expect("flush should succeed");
}
#[test]
fn stream_error_from_broken_pipe_maps_to_closed() {
use std::io;
use wasmtime_wasi_io::streams::StreamError;
let err = super::stream_error_from(io::Error::from(io::ErrorKind::BrokenPipe));
assert!(matches!(err, StreamError::Closed));
}
#[test]
fn stream_error_from_preserves_io_error() {
use std::io;
use wasmtime_wasi_io::streams::StreamError;
let err = super::stream_error_from(io::Error::from(io::ErrorKind::IsADirectory));
match err {
StreamError::LastOperationFailed(e) => {
let io_err = e.downcast::<io::Error>().expect("should downcast");
assert_eq!(io_err.kind(), io::ErrorKind::IsADirectory);
}
other => panic!("expected LastOperationFailed, got: {other:?}"),
}
}
#[cfg(unix)]
#[test]
fn stream_error_from_raw_os_eisdir() {
use rustix::io::Errno;
use std::io;
use wasmtime_wasi_io::streams::StreamError;
let err =
super::stream_error_from(io::Error::from_raw_os_error(Errno::ISDIR.raw_os_error()));
match err {
StreamError::LastOperationFailed(e) => {
let io_err = e.downcast::<io::Error>().expect("should downcast");
assert_eq!(io_err.raw_os_error(), Some(Errno::ISDIR.raw_os_error()));
}
other => panic!("expected LastOperationFailed, got: {other:?}"),
}
}
}