2afaac5181
* Return `anyhow::Error` from host functions instead of `Trap` This commit refactors how errors are modeled when returned from host functions and additionally refactors how custom errors work with `Trap`. At a high level functions in Wasmtime that previously worked with `Result<T, Trap>` now work with `Result<T>` instead where the error is `anyhow::Error`. This includes functions such as: * Host-defined functions in a `Linker<T>` * `TypedFunc::call` * Host-related callbacks like call hooks Errors are now modeled primarily as `anyhow::Error` throughout Wasmtime. This subsequently removes the need for `Trap` to have the ability to represent all host-defined errors as it previously did. Consequently the `From` implementations for any error into a `Trap` have been removed here and the only embedder-defined way to create a `Trap` is to use `Trap::new` with a custom string. After this commit the distinction between a `Trap` and a host error is the wasm backtrace that it contains. Previously all errors in host functions would flow through a `Trap` and get a wasm backtrace attached to them, but now this only happens if a `Trap` itself is created meaning that arbitrary host-defined errors flowing from a host import to the other side won't get backtraces attached. Some internals of Wasmtime itself were updated or preserved to use `Trap::new` to capture a backtrace where it seemed useful, such as when fuel runs out. The main motivation for this commit is that it now enables hosts to thread a concrete error type from a host function all the way through to where a wasm function was invoked. Previously this could not be done since the host error was wrapped in a `Trap` that didn't provide the ability to get at the internals. A consequence of this commit is that when a host error is returned that isn't a `Trap` we'll capture a backtrace and then won't have a `Trap` to attach it to. To avoid losing the contextual information this commit uses the `Error::context` method to attach the backtrace as contextual information to ensure that the backtrace is itself not lost. This is a breaking change for likely all users of Wasmtime, but it's hoped to be a relatively minor change to workaround. Most use cases can likely change `-> Result<T, Trap>` to `-> Result<T>` and otherwise explicit creation of a `Trap` is largely no longer necessary. * Fix some doc links * add some tests and make a backtrace type public (#55) * Trap: avoid a trailing newline in the Display impl which in turn ends up with three newlines between the end of the backtrace and the `Caused by` in the anyhow Debug impl * make BacktraceContext pub, and add tests showing downcasting behavior of anyhow::Error to traps or backtraces * Remove now-unnecesary `Trap` downcasts in `Linker::module` * Fix test output expectations * Remove `Trap::i32_exit` This commit removes special-handling in the `wasmtime::Trap` type for the i32 exit code required by WASI. This is now instead modeled as a specific `I32Exit` error type in the `wasmtime-wasi` crate which is returned by the `proc_exit` hostcall. Embedders which previously tested for i32 exits now downcast to the `I32Exit` value. * Remove the `Trap::new` constructor This commit removes the ability to create a trap with an arbitrary error message. The purpose of this commit is to continue the prior trend of leaning into the `anyhow::Error` type instead of trying to recreate it with `Trap`. A subsequent simplification to `Trap` after this commit is that `Trap` will simply be an `enum` of trap codes with no extra information. This commit is doubly-motivated by the desire to always use the new `BacktraceContext` type instead of sometimes using that and sometimes using `Trap`. Most of the changes here were around updating `Trap::new` calls to `bail!` calls instead. Tests which assert particular error messages additionally often needed to use the `:?` formatter instead of the `{}` formatter because the prior formats the whole `anyhow::Error` and the latter only formats the top-most error, which now contains the backtrace. * Merge `Trap` and `TrapCode` With prior refactorings there's no more need for `Trap` to be opaque or otherwise contain a backtrace. This commit parse down `Trap` to simply an `enum` which was the old `TrapCode`. All various tests and such were updated to handle this. The main consequence of this commit is that all errors have a `BacktraceContext` context attached to them. This unfortunately means that the backtrace is printed first before the error message or trap code, but given all the prior simplifications that seems worth it at this time. * Rename `BacktraceContext` to `WasmBacktrace` This feels like a better name given how this has turned out, and additionally this commit removes having both `WasmBacktrace` and `BacktraceContext`. * Soup up documentation for errors and traps * Fix build of the C API Co-authored-by: Pat Hickey <pat@moreproductive.org>
74 lines
3.6 KiB
Rust
74 lines
3.6 KiB
Rust
//! ## The `WasiFile` and `WasiDir` traits
|
|
//!
|
|
//! The WASI specification only defines one `handle` type, `fd`, on which all
|
|
//! operations on both files and directories (aka dirfds) are defined. We
|
|
//! believe this is a design mistake, and are architecting wasi-common to make
|
|
//! this straightforward to correct in future snapshots of WASI. Wasi-common
|
|
//! internally treats files and directories as two distinct resource types in
|
|
//! the table - `Box<dyn WasiFile>` and `Box<dyn WasiDir>`. The snapshot 0 and
|
|
//! 1 interfaces via `fd` will attempt to downcast a table element to one or
|
|
//! both of these interfaces depending on what is appropriate - e.g.
|
|
//! `fd_close` operates on both files and directories, `fd_read` only operates
|
|
//! on files, and `fd_readdir` only operates on directories.
|
|
|
|
//! The `WasiFile` and `WasiDir` traits are defined by `wasi-common` in terms
|
|
//! of types defined directly in the crate's source code (I decided it should
|
|
//! NOT those generated by the `wiggle` proc macros, see snapshot architecture
|
|
//! below), as well as the `cap_std::time` family of types. And, importantly,
|
|
//! `wasi-common` itself provides no implementation of `WasiDir`, and only two
|
|
//! trivial implementations of `WasiFile` on the `crate::pipe::{ReadPipe,
|
|
//! WritePipe}` types, which in turn just delegate to `std::io::{Read,
|
|
//! Write}`. In order for `wasi-common` to access the local filesystem at all,
|
|
//! you need to provide `WasiFile` and `WasiDir` impls through either the new
|
|
//! `wasi-cap-std-sync` crate found at `crates/wasi-common/cap-std-sync` - see
|
|
//! the section on that crate below - or by providing your own implementation
|
|
//! from elsewhere.
|
|
//!
|
|
//! This design makes it possible for `wasi-common` embedders to statically
|
|
//! reason about access to the local filesystem by examining what impls are
|
|
//! linked into an application. We found that this separation of concerns also
|
|
//! makes it pretty enjoyable to write alternative implementations, e.g. a
|
|
//! virtual filesystem (which will land in a future PR).
|
|
//!
|
|
//! ## Traits for the rest of WASI's features
|
|
//!
|
|
//! Other aspects of a WASI implementation are not yet considered resources
|
|
//! and accessed by `handle`. We plan to correct this design deficiency in
|
|
//! WASI in the future, but for now we have designed the following traits to
|
|
//! provide embedders with the same sort of implementation flexibility they
|
|
//! get with WasiFile/WasiDir:
|
|
//!
|
|
//! * Timekeeping: `WasiSystemClock` and `WasiMonotonicClock` provide the two
|
|
//! interfaces for a clock. `WasiSystemClock` represents time as a
|
|
//! `cap_std::time::SystemTime`, and `WasiMonotonicClock` represents time as
|
|
//! `cap_std::time::Instant`. * Randomness: we re-use the `cap_rand::RngCore`
|
|
//! trait to represent a randomness source. A trivial `Deterministic` impl is
|
|
//! provided. * Scheduling: The `WasiSched` trait abstracts over the
|
|
//! `sched_yield` and `poll_oneoff` functions.
|
|
//!
|
|
//! Users can provide implementations of each of these interfaces to the
|
|
//! `WasiCtx::builder(...)` function. The
|
|
//! `wasi_cap_std_sync::WasiCtxBuilder::new()` function uses this public
|
|
//! interface to plug in its own implementations of each of these resources.
|
|
pub mod clocks;
|
|
mod ctx;
|
|
pub mod dir;
|
|
mod error;
|
|
pub mod file;
|
|
pub mod pipe;
|
|
pub mod random;
|
|
pub mod sched;
|
|
pub mod snapshots;
|
|
mod string_array;
|
|
pub mod table;
|
|
|
|
pub use cap_rand::RngCore;
|
|
pub use clocks::{SystemTimeSpec, WasiClocks, WasiMonotonicClock, WasiSystemClock};
|
|
pub use ctx::WasiCtx;
|
|
pub use dir::WasiDir;
|
|
pub use error::{Context, Error, ErrorExt, ErrorKind, I32Exit};
|
|
pub use file::WasiFile;
|
|
pub use sched::{Poll, WasiSched};
|
|
pub use string_array::StringArrayError;
|
|
pub use table::Table;
|