kobako 0.27.0 → 0.29.0

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

@@ -1,4 +1,4 @@
-//! Per-`Driver` execution configuration.
+//! The caps a `Driver` applies to every invocation.
 //!
 //! Every cap a frontend forwards into `Driver::new`. A plain value carrier
 //! owned by the `Driver` — distinct from the process-wide engine/module
@@ -17,24 +17,78 @@ use kobako_runtime::profile::Profile;
 
 /// The caps and requested isolation profile for one `Driver`. `None` on
 /// any cap field disables that cap.
+#[non_exhaustive]
 pub struct Config {
-    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
-    /// per-run `Instant` deadline by `Driver::prime_caps`.
+    /// Wall-clock cap for one guest `#eval` / `#run`; the invocation traps
+    /// once it passes.
     pub timeout: Option<Duration>,
-    /// Guest linear-memory cap, in bytes. Threaded into each fresh
-    /// `Invocation`, where the wasmtime `ResourceLimiter` callback
-    /// consumes it from inside the engine.
+    /// Wall-clock cap for setting the Guest Binary up the first time its
+    /// path is loaded; past it, construction fails.
+    pub setup_timeout: Option<Duration>,
+    /// Guest linear-memory cap, in bytes, charged to what one invocation
+    /// grows beyond the image it starts from.
     pub memory_limit: Option<usize>,
-    /// Byte cap for guest stdout capture.
-    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
-    /// flag in `Driver::build_snapshot`.
+    /// Byte cap for guest stdout capture; output past it is dropped and
+    /// the capture marked truncated.
     pub stdout_limit: Option<usize>,
-    /// Byte cap for guest stderr capture. Mirror of `stdout_limit`.
+    /// Byte cap for guest stderr capture, the same as `stdout_limit`.
     pub stderr_limit: Option<usize>,
-    /// Isolation posture the frontend requested. The per-invocation
-    /// WASI context is built to this rung — `Hermetic` freezes ambient
-    /// time and entropy (`crate::ambient`), `Permissive` leaves the
-    /// live WASI sources — and `Driver::profile` declares it back as
-    /// the built posture.
+    /// Descriptors one invocation may hold open, the standard ones and
+    /// each Mount's preopen included; an open past it answers `MFILE`.
+    pub open_file_limit: Option<usize>,
+    /// Isolation posture the frontend requested. `Hermetic` freezes
+    /// ambient time and entropy, `Permissive` leaves the live WASI
+    /// sources, and `Driver::profile` declares it back as the built
+    /// posture.
     pub profile: Profile,
 }
+
+impl Default for Config {
+    /// The caps every frontend defaults to: a 60-second deadline, 10
+    /// seconds to set the Guest Binary up, 4 MiB for memory, 1 MiB for
+    /// each output channel, 1024 open files, and the hermetic floor.
+    fn default() -> Self {
+        Config {
+            timeout: Some(Duration::from_secs(60)),
+            setup_timeout: Some(Duration::from_secs(10)),
+            memory_limit: Some(4 << 20),
+            stdout_limit: Some(1 << 20),
+            stderr_limit: Some(1 << 20),
+            open_file_limit: Some(1024),
+            profile: Profile::Hermetic,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    // Literal values, so a drift from the defaults the SDK's Options and
+    // the Ruby frontend apply fails here.
+    #[test]
+    fn a_default_config_carries_every_frontends_default_caps() {
+        let config = Config::default();
+        assert_eq!(
+            (
+                config.timeout,
+                config.setup_timeout,
+                config.memory_limit,
+                config.stdout_limit,
+                config.stderr_limit,
+                config.open_file_limit,
+                config.profile
+            ),
+            (
+                Some(Duration::from_secs(60)),
+                Some(Duration::from_secs(10)),
+                Some(4 * 1024 * 1024),
+                Some(1024 * 1024),
+                Some(1024 * 1024),
+                Some(1024),
+                Profile::Hermetic
+            ),
+            "Config::default must carry the caps every frontend defaults to"
+        );
+    }
+}

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

@@ -0,0 +1,167 @@
+//! The guest's descriptor table: what each preview1 file descriptor
+//! stands for within one invocation.
+//!
+//! kobako answers every preview1 call that reads this table, so the guest
+//! sees one table and no call falls through to a second one that
+//! disagrees. Numbering follows wasmtime-wasi's: a closed number is reused
+//! before a fresh one is taken.
+
+use std::collections::{BTreeMap, BTreeSet};
+use std::sync::Arc;
+
+use kobako_runtime::filesystem::{DirEntry, File, Hold, Metadata};
+use kobako_runtime::mount::Mount;
+use wasmtime_wasi::p2::pipe::{MemoryInputPipe, MemoryOutputPipe};
+
+/// What one descriptor stands for.
+pub(crate) enum Descriptor {
+    /// Descriptor 0, carrying the Preamble.
+    Stdin(MemoryInputPipe),
+    /// Descriptor 1 or 2, a capture pipe the guest writes a Channel into.
+    Channel(MemoryOutputPipe),
+    /// A directory beneath a Mount; a preopen is the Mount's own root.
+    Directory(OpenDirectory),
+    File(OpenFile),
+}
+
+/// What a directory is, apart from where it stands: the device and inode
+/// numbers its Filesystem names it by.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) struct Identity {
+    dev: u64,
+    ino: u64,
+}
+
+impl Identity {
+    /// The identity `metadata` names, or `None` where its inode of zero
+    /// reports none.
+    pub(crate) fn of(metadata: &Metadata) -> Option<Self> {
+        (metadata.ino != 0).then_some(Self {
+            dev: metadata.dev,
+            ino: metadata.ino,
+        })
+    }
+}
+
+pub(crate) struct OpenDirectory {
+    pub(crate) mount: Arc<Mount>,
+    /// The directory's path relative to the mount's root.
+    pub(crate) path: String,
+    /// The identity the directory had when it was opened, so one made in
+    /// its place is not taken for it; without one it follows its path.
+    pub(crate) identity: Option<Identity>,
+    /// What keeps that identity from passing to a directory made in this
+    /// one's place while the descriptor is open.
+    pub(crate) _hold: Option<Hold>,
+    pub(crate) preopen: bool,
+    /// The entries a listing began with, held until it reaches its end, so
+    /// each later call reads on without listing the directory again.
+    pub(crate) listing: Option<Vec<DirEntry>>,
+}
+
+pub(crate) struct OpenFile {
+    pub(crate) file: Box<dyn File>,
+    pub(crate) position: u64,
+    pub(crate) append: bool,
+    pub(crate) readable: bool,
+    pub(crate) writable: bool,
+    /// The Mount it was opened beneath, whose permission to write answers a
+    /// wait to write and a resize, as wasmtime-wasi answers both by its
+    /// preopen's permissions.
+    pub(crate) mount: Arc<Mount>,
+}
+
+pub(crate) struct Descriptors {
+    used: BTreeMap<u32, Descriptor>,
+    free: BTreeSet<u32>,
+    limit: Option<usize>,
+}
+
+impl Descriptors {
+    /// The table every invocation starts from: stdin, then the two
+    /// Channels, then one preopen per Mount from descriptor 3. It holds at
+    /// most `limit` descriptors, those included, as a process's
+    /// `RLIMIT_NOFILE` counts every one it holds.
+    pub(crate) fn new(
+        stdin: MemoryInputPipe,
+        stdout: MemoryOutputPipe,
+        stderr: MemoryOutputPipe,
+        mounts: Vec<Mount>,
+        limit: Option<usize>,
+    ) -> Self {
+        let mut used = BTreeMap::from([
+            (0, Descriptor::Stdin(stdin)),
+            (1, Descriptor::Channel(stdout)),
+            (2, Descriptor::Channel(stderr)),
+        ]);
+        for (fd, mount) in (3..).zip(mounts) {
+            // A root the Filesystem cannot stat or hold reports no
+            // identity, and the descriptor follows its path alone.
+            let filesystem = mount.filesystem();
+            let identity = filesystem
+                .metadata("")
+                .ok()
+                .and_then(|root| Identity::of(&root));
+            let hold = filesystem.hold_directory("").ok().flatten();
+            used.insert(
+                fd,
+                Descriptor::Directory(OpenDirectory {
+                    mount: Arc::new(mount),
+                    path: String::new(),
+                    identity,
+                    _hold: hold,
+                    preopen: true,
+                    listing: None,
+                }),
+            );
+        }
+        Self {
+            used,
+            free: BTreeSet::new(),
+            limit,
+        }
+    }
+
+    pub(crate) fn get(&self, fd: u32) -> Option<&Descriptor> {
+        self.used.get(&fd)
+    }
+
+    pub(crate) fn get_mut(&mut self, fd: u32) -> Option<&mut Descriptor> {
+        self.used.get_mut(&fd)
+    }
+
+    /// Take `fd` out of the table, freeing its number for reuse.
+    pub(crate) fn remove(&mut self, fd: u32) -> Option<Descriptor> {
+        let descriptor = self.used.remove(&fd)?;
+        self.free.insert(fd);
+        Some(descriptor)
+    }
+
+    /// Place `descriptor` at `fd`, a number the caller has just freed.
+    pub(crate) fn place(&mut self, fd: u32, descriptor: Descriptor) {
+        self.free.remove(&fd);
+        self.used.insert(fd, descriptor);
+    }
+
+    /// Whether the table holds as many descriptors as it may.
+    pub(crate) fn is_full(&self) -> bool {
+        self.limit.is_some_and(|limit| self.used.len() >= limit)
+    }
+
+    /// Add `descriptor` under the highest freed number, or the one past
+    /// the highest in use; `None` when the table is full.
+    pub(crate) fn push(&mut self, descriptor: Descriptor) -> Option<u32> {
+        if self.is_full() {
+            return None;
+        }
+        let fd = match self.free.pop_last() {
+            Some(fd) => fd,
+            None => match self.used.last_key_value() {
+                Some((last, _)) => last.checked_add(1)?,
+                None => 0,
+            },
+        };
+        self.used.insert(fd, descriptor);
+        Some(fd)
+    }
+}

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

@@ -1,89 +1,99 @@
-//! Host-side dispatch for the `__kobako_dispatch` import.
+//! Host side of the `__kobako_upcall` import: hand the guest's Call to
+//! the bound `DispatchHandler` and write its Reply back into guest memory.
+//! A request under a tag the host does not serve is answered as
+//! unsupported, so a guest asking for a later operation can fall back.
 //!
-//! When the guest invokes the wasm import declared in
-//! `wasm/kobako-core/src/abi.rs`, wasmtime calls back into the host
-//! through the closure registered by `instance_pre::build_linker`.
-//! That closure delegates here. The dispatcher:
-//!
-//!   1. Reads the Call bytes from guest linear memory.
-//!   2. Invokes the bound `DispatchHandler` (the frontend's dispatch
-//!      bridge, e.g. a Ruby Proc) and recovers Reply bytes.
-//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
-//!      through `Caller::get_export`.
-//!   4. Writes the Reply bytes into the guest buffer.
-//!   5. Returns packed `(ptr<<32)|len` for the guest to decode.
-//!
-//! Returns 0 on any step failure. `Kobako::Sandbox#initialize` always
-//! installs the dispatch handler before any invocation, so reaching the
-//! dispatcher with no handler bound is itself a wire-layer fault; the
-//! guest maps a 0 return to a trap. Failures during normal dispatch
-//! take the Reply's fault arm from
-//! `Kobako::Transport::Dispatcher.dispatch` itself — they never reach
-//! this 0-return path.
-//!
-//! ## Why this module writes to `stderr`
-//!
-//! This file is the one place in the driver that deliberately prints
-//! through `eprintln!`. The host normally surfaces faults through the
-//! contract's error channels; the dispatcher contract is the exception
-//! — it must return a packed `i64` to the guest and cannot fail, so a
-//! 0 return is the only signal the wasm side receives. The guest collapses every 0 into the same trap, so the
-//! Ruby host has no way to attribute the failure to a specific step
-//! (missing `memory` export vs. no dispatch handler bound vs. the
-//! handler raised vs. `__kobako_alloc` returned 0 vs. `memory.write`
-//! rejected).
-//!
-//! `handle` writes a single `[kobako-dispatch] <reason>` line to
-//! `stderr` on each failure path so operators have a breadcrumb to
-//! correlate the trap with the actual cause. The line is emitted in
-//! both debug and release builds on purpose: dispatcher failures are
-//! wire-layer faults rather than expected error paths (`Kobako::Sandbox`
-//! always installs the handler, the handler is contracted never to
-//! raise, etc.), so the "release-build noise" cost is bounded — under
-//! normal operation the line is never written. Operators that need to
-//! silence the stream can redirect the host process's stderr, but the
-//! kobako convention is "ext never logs" plus this single, named
-//! exception.
+//! A failure lands on whoever is answerable for it, and always says why.
+//! A trap the guest raises during a callback into it ends the invocation
+//! as that trap. A Call the host could not answer is answered as an
+//! internal failure naming why, and an answer too large for a message as
+//! the Service's own failure. Only an answer that cannot be written into
+//! guest memory at all ends the invocation, as a trap naming why.
 
 use wasmtime::Caller;
 
-use kobako_transport::envelope::Call;
+use kobako_runtime::error::Trap;
+use kobako_runtime::yielder::Yielder;
+use kobako_transport::abi::pack_ptr_len;
+use kobako_transport::envelope::{Fault, FaultKind, Reply, Unsupported, Upcall, YieldReply};
 
+use crate::guest_mem;
 use crate::invocation::Invocation;
 
-/// Drive a single `__kobako_dispatch` invocation end-to-end. Entry point
-/// from the wasmtime closure registered by `instance_pre::build_linker`.
-///
-/// Returns the packed `(ptr<<32)|len` u64 on success, 0 on any
-/// wire-layer fault. Failure paths log a `[kobako-dispatch]` line to
-/// `stderr` so operators have a breadcrumb when the guest sees a 0
-/// return and traps. The bound dispatch handler is contracted never to
-/// raise (it folds Service exceptions onto the Reply's fault arm),
-/// so reaching the failure path is always a wiring bug or wire-layer
-/// fault rather than an expected path.
-pub(crate) fn handle(caller: &mut Caller<'_, Invocation>, req_ptr: i32, req_len: i32) -> i64 {
-    match try_handle(caller, req_ptr, req_len) {
-        Ok(packed) => packed,
-        Err(reason) => {
-            eprintln!("[kobako-dispatch] {reason}");
-            0
-        }
+/// The wasmtime-backed `Yielder`: built per `__kobako_upcall` frame over
+/// that frame's `Caller`, so nested dispatch frames each carry their own and
+/// stack on the Rust call stack with no shared slot.
+struct CallerYielder<'a, 'c> {
+    caller: &'a mut Caller<'c, Invocation>,
+    frame: u32,
+}
+
+impl Yielder for CallerYielder<'_, '_> {
+    fn frame(&self) -> u32 {
+        self.frame
+    }
+
+    fn yield_to_block(&mut self, frame: u32, args: &[u8]) -> Result<YieldReply, Trap> {
+        let bytes = guest_mem::drive_yield(self.caller, frame, args)
+            .map_err(|msg| Trap::Other(msg.to_string()))?;
+        YieldReply::decode(&bytes).map_err(|err| Trap::Other(err.to_string()))
+    }
+}
+
+/// Answer one `__kobako_upcall` call with the packed `(ptr<<32)|len` of
+/// the Reply, or the trap a callback into the guest raised.
+pub(crate) fn handle(
+    caller: &mut Caller<'_, Invocation>,
+    req_ptr: i32,
+    req_len: i32,
+) -> wasmtime::Result<i64> {
+    let reply = reply_to(caller, req_ptr, req_len)
+        .unwrap_or_else(|reason| Reply::Fault(Fault::new(FaultKind::Internal, reason)));
+    let written = write_reply(caller, &fit_in_message(reply).encode());
+    if let Some(trap) = caller.data_mut().take_reentry_trap() {
+        return Err(trap);
+    }
+    if let Some(trap) = caller.data().abandonment() {
+        return Err(trap);
+    }
+    written.map_err(wasmtime::Error::msg)
+}
+
+/// An answer past the message cap is the Service's to change, as any other
+/// answer the host cannot write is.
+fn fit_in_message(reply: Reply) -> Reply {
+    let bytes = reply.encode().len();
+    match guest_mem::checked_payload_len(bytes) {
+        Ok(_) => reply,
+        Err(limit) => Reply::Fault(Fault::new(
+            FaultKind::Runtime,
+            format!("Sandbox could not write the Service's answer: {limit}"),
+        )),
     }
 }
 
-/// Result-returning core of `handle`. Pulled out so each early
-/// failure path carries a diagnostic string instead of an opaque 0.
-fn try_handle(
+fn reply_to(
     caller: &mut Caller<'_, Invocation>,
     req_ptr: i32,
     req_len: i32,
-) -> Result<i64, &'static str> {
-    let req_bytes = crate::guest_mem::read(caller, req_ptr, req_len)?;
-    // The driver decodes the core envelope so the frontend never sees a
-    // frame; the payload inside it stays bytes the whole way through.
-    let call = Call::decode(&req_bytes).map_err(|_| {
-        "the guest sent a malformed Call envelope — please report this as a kobako bug"
-    })?;
+) -> Result<Reply, &'static str> {
+    let req_bytes = guest_mem::read_request(caller, req_ptr, req_len)?;
+    // The driver decodes the core envelope, here and in `CallerYielder`, so
+    // the frontend never sees a frame; the payload inside it stays bytes
+    // the whole way through.
+    let call = match Upcall::decode(&req_bytes) {
+        Ok(Upcall::Call(call)) => call,
+        Ok(_) => {
+            return Ok(Reply::Unsupported(Unsupported::new(
+                "the host does not serve this request",
+            )))
+        }
+        Err(_) => {
+            return Err(
+                "the guest sent a malformed Call envelope — please report this as a kobako bug",
+            )
+        }
+    };
 
     // `Kobako::Sandbox` always installs the dispatch handler before
     // invoking the runtime, so reaching this branch indicates a misuse
@@ -91,27 +101,25 @@ fn try_handle(
     let handler = caller
         .data()
         .on_dispatch()
-        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
+        .ok_or("a Sandbox callback fired outside an active invocation — please report this as a kobako bug")?;
 
     // Build a frame-scoped yielder over this Caller and hand it to the
     // handler. The borrow ends with the block, freeing the Caller for
-    // `write_response`; nested dispatch frames each build their own, so
+    // `write_reply`; nested dispatch frames each build their own, so
     // the LIFO re-entry lives on the Rust stack — no shared slot.
+    let frame = caller.data_mut().open_call();
     let reply = {
-        let mut yielder = crate::guest_mem::CallerYielder::new(caller);
+        let mut yielder = CallerYielder { caller, frame };
         handler.dispatch(call, &mut yielder)
-    }
-    .ok_or(
+    };
+    caller.data_mut().close_call();
+    reply.ok_or(
         "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug",
-    )?;
-
-    write_response(caller, &reply.encode())
+    )
 }
 
-/// Allocate a guest-side buffer and copy the response bytes into it via
-/// `crate::guest_mem::alloc_and_write`, returning the packed
-/// `(ptr<<32)|len` u64 the guest's `__kobako_dispatch` import expects.
-fn write_response(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
-    let ptr = crate::guest_mem::alloc_and_write(caller, bytes)?;
-    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
+fn write_reply(caller: &mut Caller<'_, Invocation>, bytes: &[u8]) -> Result<i64, &'static str> {
+    let ptr = guest_mem::write_from_callback(caller, bytes)?;
+    // The write has already held the length to the payload cap.
+    Ok(pack_ptr_len(ptr, bytes.len() as u32) as i64)
 }