rustdocs!!

crates/wasi-common/src/lib.rs

@@ -1,3 +1,55 @@
+//! ## 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;

crates/wasi-common/src/snapshots/mod.rs

@@ -1,2 +1,27 @@
+//! One goal of `wasi-common` is for multiple WASI snapshots to provide an
+//! interface to the same underlying `crate::WasiCtx`. This provides us a path
+//! to evolve WASI by allowing the same WASI Command to import functions from
+//! different snapshots - e.g. the user could use Rust's `std` which imports
+//! snapshot 1, but also depend directly on the `wasi` crate which imports
+//! some future snapshot 2. Right now, this amounts to supporting snapshot 1
+//! and "snapshot 0" aka wasi_unstable at once.
+//!
+//! The architectural rules for snapshots are:
+//!
+//! * Snapshots are arranged into modules under `crate::snapshots::`.
+//!
+//! * Each snapshot should invoke `wiggle::from_witx!` with `ctx:
+//! crate::WasiCtx` in its module, and impl all of the required traits.
+//!
+//!* Snapshots can be implemented in terms of other snapshots. For example,
+//! snapshot 0 is mostly implemented by calling the snapshot 1 implementation,
+//! and converting its own types back and forth with the snapshot 1 types. In a
+//! few cases, that is not feasible, so snapshot 0 carries its own
+//! implementations in terms of the `WasiFile` and `WasiSched` traits.
+//!
+//! * Snapshots can be implemented in terms of the `Wasi*` traits given by
+//! `WasiCtx`. No further downcasting via the `as_any` escape hatch is
+//! permitted.
+
 pub mod preview_0;
 pub mod preview_1;