kobako 0.27.0 → 0.29.0

data/crates/kobako-wasmtime/src/lib.rs

@@ -8,43 +8,26 @@
 //! lives behind the contract surface, so a frontend shell (the Ruby
 //! ext's `Kobako::Runtime`) sees no wasmtime type.
 //!
-//! Module layout (one responsibility per file):
-//!
-//! * `driver` — `Driver` + `impl kobako_runtime::runtime::Runtime`
-//!   (the run mechanics).
-//! * `cache` — process-wide Engine + per-path Module cache and the
-//!   process-singleton epoch ticker thread.
-//! * `config` — per-Driver caps (timeout / stdout / stderr limits).
-//! * `exports` — per-invocation `__kobako_eval` / `_run` /
-//!   `_take_outcome` / `_alloc` / `memory` handles.
-//! * `instance_pre` — host-import Linker wiring + per-path
-//!   `InstancePre` cache.
-//! * `abi` — the Guest Binary's declared ABI version check, verified
-//!   with the cached `InstancePre` it guards.
-//! * `invocation` — Invocation (per-Store context), the
-//!   `MemoryLimiter` memory cap, and the trap marker types
-//!   (`TimeoutTrap` / `MemoryLimitTrap`).
-//! * `dispatch` — `__kobako_dispatch` host-import dispatch helpers.
-//! * `frames` — stdin frame stream + WASI context assembly, `#run`
-//!   envelope write, OUTCOME_BUFFER readout.
-//! * `guest_mem` — Caller-based guest linear-memory alloc / write / read.
-//! * `capture` — stdout / stderr pipe sizing + clip helpers.
-//! * `ambient` — frozen WASI clocks + constant RNG (ambient denial).
-//! * `trap` — wasmtime-error → neutral `Trap` classification.
+//! Each module holds one responsibility and opens with its own doc.
 
 mod abi;
 mod ambient;
 mod cache;
 mod capture;
 mod config;
+mod descriptors;
 mod dispatch;
 mod driver;
 mod exports;
-mod frames;
 mod guest_mem;
+mod imports;
 mod instance_pre;
 mod invocation;
+mod io;
+mod limiter;
+mod preview1;
 mod trap;
+mod wasi;
 
 pub use config::Config;
 pub use driver::Driver;

data/crates/kobako-wasmtime/src/limiter.rs

@@ -0,0 +1,253 @@
+//! The per-invocation memory cap: only the `memory.grow` delta past the
+//! linear-memory size captured at invocation entry is charged, so the
+//! image's initial allocation is outside the budget.
+
+use wasmtime::ResourceLimiter;
+
+/// Resource limiter that enforces the per-invocation `memory_limit`
+/// cap.
+///
+/// `max_memory` is the byte cap on per-invocation growth (`None` disables
+/// the cap). `baseline` is the linear-memory size captured at invocation
+/// entry by `MemoryLimiter::activate`; the limiter charges only the
+/// `memory.grow` delta past `baseline` against `max_memory`, so the
+/// mruby image's initial allocation and any high-water mark left by
+/// prior invocations on the same Sandbox do not consume the budget.
+/// `cap_active` gates whether the cap is enforced — wasmtime's
+/// `ResourceLimiter` also fires for the module's declared initial
+/// allocation at instantiation time, but the cap stays dormant until
+/// `MemoryLimiter::activate` flips the flag for one `Driver` invoke
+/// call. When `cap_active` is `false`, the limiter always allows
+/// growth.
+///
+/// When `memory.grow` would push the per-invocation delta past
+/// `max_memory`, the limiter returns `MemoryLimitTrap` from
+/// `memory_growing`; wasmtime turns that into the trap surfaced to the
+/// host as a guest invocation failure.
+#[derive(Debug, Clone, Copy)]
+pub(crate) struct MemoryLimiter {
+    max_memory: Option<usize>,
+    baseline: usize,
+    cap_active: bool,
+    peak: usize,
+}
+
+impl MemoryLimiter {
+    pub(crate) fn new(max_memory: Option<usize>) -> Self {
+        Self {
+            max_memory,
+            baseline: 0,
+            cap_active: false,
+            peak: 0,
+        }
+    }
+
+    /// The cap stays dormant until armed, because the module's declared
+    /// initial memory is allocated during instantiation and must pass.
+    pub(crate) fn activate(&mut self, baseline: usize) {
+        self.baseline = baseline;
+        self.cap_active = true;
+        self.peak = 0;
+    }
+
+    pub(crate) fn deactivate(&mut self) {
+        self.cap_active = false;
+    }
+
+    /// A grow the cap rejects never updates the peak, so the reported value
+    /// never exceeds `memory_limit`.
+    pub(crate) fn peak(&self) -> usize {
+        self.peak
+    }
+}
+
+impl ResourceLimiter for MemoryLimiter {
+    fn memory_growing(
+        &mut self,
+        _current: usize,
+        desired: usize,
+        _maximum: Option<usize>,
+    ) -> wasmtime::Result<bool> {
+        if !self.cap_active {
+            return Ok(true);
+        }
+        let delta = desired.saturating_sub(self.baseline);
+        if let Some(limit) = self.max_memory {
+            if delta > limit {
+                return Err(wasmtime::Error::new(MemoryLimitTrap { desired, limit }));
+            }
+        }
+        if delta > self.peak {
+            self.peak = delta;
+        }
+        Ok(true)
+    }
+
+    fn table_growing(
+        &mut self,
+        _current: usize,
+        _desired: usize,
+        _maximum: Option<usize>,
+    ) -> wasmtime::Result<bool> {
+        Ok(true)
+    }
+}
+
+/// Marker error returned from `MemoryLimiter::memory_growing` when the
+/// per-invocation memory cap is exceeded. Downcast from the wasmtime
+/// trap error to classify the failure as a memory-limit `Trap`. Callers
+/// use the `Display` impl below — no field is read directly — so the
+/// inner state stays private.
+#[derive(Debug)]
+pub(crate) struct MemoryLimitTrap {
+    desired: usize,
+    limit: usize,
+}
+
+impl MemoryLimitTrap {
+    #[cfg(test)]
+    pub(crate) fn new(desired: usize, limit: usize) -> Self {
+        Self { desired, limit }
+    }
+}
+
+impl std::fmt::Display for MemoryLimitTrap {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "memory usage exceeded memory_limit: \
+             requested={} bytes, limit={} bytes",
+            self.desired, self.limit
+        )
+    }
+}
+
+impl std::error::Error for MemoryLimitTrap {}
+
+#[cfg(test)]
+mod tests {
+    //! Unit tests for `MemoryLimiter` — the per-invocation memory
+    //! delta cap. The Ruby-facing E2E suite exercises the full path
+    //! through wasmtime; these tests pin the pure delta arithmetic so
+    //! a regression that breaks the baseline accounting (e.g. dropping
+    //! the `baseline` subtraction, or letting `activate` carry stale
+    //! state across invocations) is caught without spinning up a
+    //! Store.
+    use super::{MemoryLimitTrap, MemoryLimiter};
+    use wasmtime::ResourceLimiter;
+
+    fn assert_growing(limiter: &mut MemoryLimiter, desired: usize) {
+        assert!(
+            limiter.memory_growing(0, desired, None).unwrap(),
+            "expected memory_growing({desired}) to allow growth"
+        );
+    }
+
+    fn assert_trapping(limiter: &mut MemoryLimiter, desired: usize) {
+        let err = limiter
+            .memory_growing(0, desired, None)
+            .expect_err("expected memory_growing to trap");
+        assert!(
+            err.downcast_ref::<MemoryLimitTrap>().is_some(),
+            "expected MemoryLimitTrap, got {err:?}"
+        );
+    }
+
+    // @behavior S-113
+    #[test]
+    fn dormant_limiter_allows_any_growth() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        // Without `activate`, the cap is dormant — the module's
+        // declared initial allocation must pass through unconditionally.
+        assert_growing(&mut limiter, 100 << 20);
+    }
+
+    // @behavior S-114
+    #[test]
+    fn delta_below_cap_passes_after_activate() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        // baseline=2 MiB, desired=2.5 MiB → delta=0.5 MiB ≤ 1 MiB cap.
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19));
+    }
+
+    // @behavior S-121
+    #[test]
+    fn delta_past_cap_traps_with_memory_limit_trap() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        // baseline=2 MiB, desired=4 MiB → delta=2 MiB > 1 MiB cap.
+        assert_trapping(&mut limiter, 4 << 20);
+    }
+
+    // @behavior S-008
+    #[test]
+    fn activate_resets_baseline_on_each_invocation() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 20));
+        // Second invocation: linear memory has grown to 3 MiB. Re-arming
+        // must re-anchor the baseline so the next 1 MiB of growth fits
+        // the per-invocation budget rather than being charged against
+        // the prior invocation's residue.
+        limiter.activate(3 << 20);
+        assert_growing(&mut limiter, (3 << 20) + (1 << 20));
+    }
+
+    // @behavior S-009
+    #[test]
+    fn disabled_cap_ignores_delta_size() {
+        let mut limiter = MemoryLimiter::new(None);
+        limiter.activate(0);
+        assert_growing(&mut limiter, 100 << 20);
+    }
+
+    // @behavior S-116
+    #[test]
+    fn peak_starts_at_zero_before_any_grow() {
+        let limiter = MemoryLimiter::new(Some(1 << 20));
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    // @behavior S-115
+    #[test]
+    fn peak_tracks_high_water_of_delta_past_baseline() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 18)); // delta=256 KiB
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB (new peak)
+        assert_growing(&mut limiter, (2 << 20) + (1 << 17)); // delta=128 KiB (below peak)
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    // @behavior S-062
+    #[test]
+    fn trap_does_not_update_peak() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19)); // delta=512 KiB
+        assert_trapping(&mut limiter, (2 << 20) + (2 << 20)); // would be 2 MiB > 1 MiB cap
+                                                              // Peak reflects the last accepted grow, not the rejected desired.
+        assert_eq!(limiter.peak(), 1 << 19);
+    }
+
+    // @behavior S-117
+    #[test]
+    fn activate_resets_peak_for_new_invocation() {
+        let mut limiter = MemoryLimiter::new(Some(1 << 20));
+        limiter.activate(2 << 20);
+        assert_growing(&mut limiter, (2 << 20) + (1 << 19));
+        assert_eq!(limiter.peak(), 1 << 19);
+        limiter.activate(3 << 20);
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    // @behavior S-118
+    #[test]
+    fn disabled_cap_still_tracks_peak() {
+        let mut limiter = MemoryLimiter::new(None);
+        limiter.activate(1 << 20);
+        assert_growing(&mut limiter, (1 << 20) + (4 << 20));
+        assert_eq!(limiter.peak(), 4 << 20);
+    }
+}

data/crates/kobako-wasmtime/src/preview1/args.rs

@@ -0,0 +1,60 @@
+//! The checks preview1 makes on an enum or flags argument before a call
+//! looks at its descriptor: a value outside what the witx defines traps,
+//! as wasmtime-wasi's generated bindings refuse to convert it.
+
+use super::errno::{Answer, Errno, Failure};
+
+/// The bits of `fdflags`.
+pub(crate) const FDFLAGS: u64 = 0x1f;
+/// The bits of `rights`.
+pub(crate) const RIGHTS: u64 = (1 << 30) - 1;
+/// The bits of `lookupflags`.
+pub(crate) const LOOKUPFLAGS: u64 = 0x1;
+/// The bits of `oflags`.
+pub(crate) const OFLAGS: u64 = 0xf;
+/// The bits of `riflags`.
+pub(crate) const RIFLAGS: u64 = 0x3;
+/// The bits of `sdflags`.
+pub(crate) const SDFLAGS: u64 = 0x3;
+
+pub(crate) const FDFLAGS_APPEND: u32 = 1 << 0;
+pub(crate) const FDFLAGS_NONBLOCK: u32 = 1 << 2;
+/// The `fdflags` asking each write to be synchronized: `dsync`, `rsync`,
+/// and `sync`.
+pub(crate) const FDFLAGS_SYNCHRONIZED: u32 = (1 << 1) | (1 << 3) | (1 << 4);
+pub(crate) const RIGHTS_FD_READ: u64 = 1 << 1;
+pub(crate) const RIGHTS_FD_WRITE: u64 = 1 << 6;
+
+/// The highest `advice` variant.
+pub(crate) const ADVICE_MAX: u32 = 5;
+/// The highest `whence` variant.
+pub(crate) const WHENCE_MAX: u32 = 2;
+
+pub(crate) fn flags(value: impl Into<u64>, defined: u64) -> Answer {
+    if value.into() & !defined != 0 {
+        return Err(Failure::trap("flags value outside what the witx defines"));
+    }
+    Ok(())
+}
+
+pub(crate) fn variant(value: u32, max: u32) -> Answer {
+    if value > max {
+        return Err(Failure::trap("enum value outside what the witx defines"));
+    }
+    Ok(())
+}
+
+/// `fstflags`, where setting a timestamp and setting it to now are
+/// exclusive: a defined value asking both is `INVAL`.
+pub(crate) fn fstflags(value: u32) -> Answer {
+    const ATIM: u32 = 1 << 0;
+    const ATIM_NOW: u32 = 1 << 1;
+    const MTIM: u32 = 1 << 2;
+    const MTIM_NOW: u32 = 1 << 3;
+    flags(value, 0xf)?;
+    let both = |set, now| value & set != 0 && value & now != 0;
+    if both(ATIM, ATIM_NOW) || both(MTIM, MTIM_NOW) {
+        return Err(Errno::Inval.into());
+    }
+    Ok(())
+}

data/crates/kobako-wasmtime/src/preview1/beneath.rs

@@ -0,0 +1,188 @@
+//! Resolving a guest path beneath a directory descriptor.
+//!
+//! The runtime is the boundary: a path never climbs above the directory
+//! descriptor it is resolved beneath, as a capability never widens, and
+//! the Mount is asked what the guest may do there before the Filesystem
+//! is, so a Filesystem of a third party's need check neither.
+//! A `..` steps out of what the Filesystem holds rather than out of the
+//! path's text, as a host resolves it, so `missing/..` names nothing and
+//! a `..` out of a link is refused rather than taken from its text. A link
+//! is followed only within the directory the descriptor opened, as
+//! wasmtime-wasi's cap-std `Dir` follows one.
+
+use kobako_runtime::filesystem::{FileType, Filesystem, FilesystemError, Metadata};
+
+use super::errno::{Answer, Errno};
+use crate::descriptors::{Identity, OpenDirectory};
+
+/// Linux's limits on a path, its terminating NUL counted, and on one name
+/// within it.
+pub(crate) const PATH_MAX: usize = 4096;
+pub(crate) const NAME_MAX: usize = 255;
+
+/// A guest path resolved beneath a directory: relative to the mount's
+/// root, and whether it ended in `/` or `/.`, which only a directory
+/// satisfies.
+pub(crate) struct ResolvedPath {
+    pub(crate) path: String,
+    pub(crate) names_directory: bool,
+}
+
+impl ResolvedPath {
+    /// The path, refused as `NOTDIR` when it must name a directory and
+    /// `lookup` finds anything else there: `metadata` for a call that
+    /// follows a link at the end, `symlink_metadata` for one that acts on
+    /// the link itself.
+    pub(crate) fn check_directory(
+        self,
+        filesystem: &(dyn Filesystem + 'static),
+        lookup: fn(&(dyn Filesystem + 'static), &str) -> Result<Metadata, FilesystemError>,
+    ) -> Answer<String> {
+        if self.names_directory {
+            match lookup(filesystem, &self.path) {
+                Ok(metadata) if metadata.file_type != FileType::Directory => {
+                    return Err(Errno::Notdir.into())
+                }
+                Ok(_) | Err(FilesystemError::NotFound) => {}
+                Err(err) => return Err(err.into()),
+            }
+        }
+        Ok(self.path)
+    }
+
+    /// The path with a link standing at its end followed within the
+    /// directory `dir` opened, for a call following it. A link pointing
+    /// at nothing there is `LOOP` to a call that `creates`, since what it
+    /// would create could lie outside `dir`, and `NOENT` otherwise.
+    pub(crate) fn follow_last(self, dir: &OpenDirectory, creates: bool) -> Answer<Self> {
+        let Some(base) = bounded_base(dir) else {
+            return Ok(self);
+        };
+        let filesystem = dir.mount.filesystem();
+        let Some(rest) = beneath_base(base, &self.path) else {
+            return Ok(self);
+        };
+        match filesystem.symlink_metadata(&self.path) {
+            Ok(metadata) if metadata.file_type == FileType::Symlink => {}
+            _ => return Ok(self),
+        }
+        let path = match filesystem.canonicalize_beneath(base, rest) {
+            Ok(found) => join(base, &found),
+            Err(FilesystemError::NotFound) if creates => return Err(Errno::Loop.into()),
+            Err(err) => return Err(err.into()),
+        };
+        Ok(Self { path, ..self })
+    }
+}
+
+/// The directory a descriptor's links are kept within, or `None` where
+/// the Filesystem keeps them within the Mount's root already, or a Mount
+/// follows no link at all.
+fn bounded_base(dir: &OpenDirectory) -> Option<&str> {
+    (!dir.path.is_empty() && dir.mount.follows_links()).then_some(dir.path.as_str())
+}
+
+/// What `path` names beneath `base`, or `None` for `base` itself.
+fn beneath_base<'a>(base: &str, path: &'a str) -> Option<&'a str> {
+    path.strip_prefix(base)?.strip_prefix('/')
+}
+
+fn join(base: &str, path: &str) -> String {
+    if path.is_empty() {
+        base.to_string()
+    } else {
+        format!("{base}/{path}")
+    }
+}
+
+/// `path` with the links on its way to its last name followed within the
+/// directory `dir` opened, so none leads the call out of it. A way the
+/// Filesystem finds nothing on stays as given, for the call to answer.
+fn within(dir: &OpenDirectory, path: String) -> Answer<String> {
+    let Some(base) = bounded_base(dir) else {
+        return Ok(path);
+    };
+    let Some((way, name)) = beneath_base(base, &path).and_then(|rest| rest.rsplit_once('/')) else {
+        return Ok(path);
+    };
+    match dir.mount.filesystem().canonicalize_beneath(base, way) {
+        Ok(found) => Ok(join(&join(base, &found), name)),
+        Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => Ok(path),
+        Err(err) => Err(err.into()),
+    }
+}
+
+/// `path`, beneath `dir`. An empty path names nothing; an absolute path or
+/// a `..` above `dir` itself is not the guest's to reach; a `..` or a final `.`
+/// after a component that is missing, no directory, or a link is `NOENT`,
+/// `NOTDIR`, or `LOOP`. A
+/// name past `NAME_MAX`, or a resolved path the Filesystem could not be
+/// handed within `PATH_MAX`, is `NAMETOOLONG`.
+pub(crate) fn resolve(dir: &OpenDirectory, path: &str) -> Answer<ResolvedPath> {
+    confirm(dir)?;
+    if path.is_empty() {
+        return Err(Errno::Noent.into());
+    }
+    if path.starts_with('/') {
+        return Err(Errno::Notcapable.into());
+    }
+    let mut components: Vec<&str> = dir.path.split('/').filter(|c| !c.is_empty()).collect();
+    let opened = components.len();
+    let mut last = "";
+    for component in path.split('/') {
+        last = component;
+        match component {
+            "" | "." => {}
+            ".." => {
+                if components.len() <= opened {
+                    return Err(Errno::Notcapable.into());
+                }
+                step_out_of(dir.mount.filesystem().as_ref(), &components.join("/"))?;
+                components.pop();
+            }
+            component if component.len() > NAME_MAX => return Err(Errno::Nametoolong.into()),
+            component => components.push(component),
+        }
+    }
+    let path = components.join("/");
+    if path.len() >= PATH_MAX {
+        return Err(Errno::Nametoolong.into());
+    }
+    // A final `.` resolves through the name before it, as a `..` does.
+    if last == "." && components.len() > opened {
+        step_out_of(dir.mount.filesystem().as_ref(), &path)?;
+    }
+    Ok(ResolvedPath {
+        path: within(dir, path)?,
+        names_directory: matches!(last, "" | "."),
+    })
+}
+
+/// `dir` still stands at its path, `NOENT` once another directory or
+/// nothing does, as a POSIX descriptor never reaches a directory made in
+/// its place. A directory opened with no identity follows its path alone.
+pub(crate) fn confirm(dir: &OpenDirectory) -> Answer {
+    let Some(identity) = dir.identity else {
+        return Ok(());
+    };
+    match dir.mount.filesystem().metadata(&dir.path) {
+        Ok(found) if Identity::of(&found) == Some(identity) => Ok(()),
+        Ok(_) | Err(FilesystemError::NotFound | FilesystemError::NotADirectory) => {
+            Err(Errno::Noent.into())
+        }
+        Err(err) => Err(err.into()),
+    }
+}
+
+/// A `..` leaves `path` only when it is a directory the Filesystem holds.
+/// A host leaves a link by the parent of where it points, which no guest
+/// is told, so a link there is refused as `LOOP`, as `openat2(2)`
+/// refuses a link it may not follow.
+fn step_out_of(filesystem: &dyn Filesystem, path: &str) -> Answer {
+    match filesystem.symlink_metadata(path) {
+        Ok(metadata) if metadata.file_type == FileType::Directory => Ok(()),
+        Ok(metadata) if metadata.file_type == FileType::Symlink => Err(Errno::Loop.into()),
+        Ok(_) => Err(Errno::Notdir.into()),
+        Err(err) => Err(err.into()),
+    }
+}