kobako 0.27.0 → 0.29.0

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

@@ -9,7 +9,6 @@
 
 use std::path::Path;
 use std::sync::Arc;
-use std::time::Instant;
 
 use wasmtime::{
     AsContextMut, InstancePre as WtInstancePre, ResourceLimiter, Store as WtStore, TypedFunc,
@@ -17,14 +16,17 @@ use wasmtime::{
 
 use crate::cache::shared_engine;
 use crate::config::Config;
-use crate::exports::Exports;
+use crate::exports::{self, Exports};
 use crate::invocation::Invocation;
-use crate::{capture, frames, instance_pre, trap};
+use crate::wasi::Wasi;
+use crate::{capture, guest_mem, instance_pre, io, trap};
 use kobako_runtime::dispatch::DispatchHandler;
 use kobako_runtime::error::{InvokeError, SetupError, Trap};
+use kobako_runtime::grant::{Grant, GrantKind};
 use kobako_runtime::profile::Profile;
-use kobako_runtime::runtime::{Entry, Frames, Runtime as ContractRuntime};
+use kobako_runtime::runtime::{Entry, Runtime as ContractRuntime};
 use kobako_runtime::snapshot::{Capture, Completion, Snapshot, Usage};
+use kobako_transport::envelope::{CompileReply, Downcall, Preamble, Run, Snippet};
 
 /// The wasmtime execution unit behind one sandbox runtime.
 pub struct Driver {
@@ -39,49 +41,49 @@ pub struct Driver {
 }
 
 impl Driver {
-    /// Construct a Driver from a wasm file path, using the process-wide
-    /// shared Engine and per-path Module / InstancePre caches. The
-    /// artifact's ABI version is verified with the cached template
-    /// (`crate::abi`). Every failure is a `SetupError` for the frontend
-    /// to attribute — Engine and Module never leave the driver.
+    /// Load the Guest Binary at `path` and verify its ABI version. The
+    /// Engine is shared by the process and the Module cached per path;
+    /// neither leaves the driver.
     pub fn new(path: &Path, config: Config) -> Result<Self, SetupError> {
         Ok(Self {
-            instance_pre: instance_pre::cached_instance_pre(path)?,
+            instance_pre: instance_pre::cached_instance_pre(path, config.setup_timeout)?,
             config,
         })
     }
 
-    /// Build the per-invocation Store: a fresh `Invocation` wired with
-    /// the memory limiter and the epoch-deadline callback.
-    fn new_store(&self) -> Result<WtStore<Invocation>, SetupError> {
-        let mut store = WtStore::new(shared_engine()?, Invocation::new(self.config.memory_limit));
+    /// The deadline and the `wall_time` bracket open with the Store, so
+    /// instantiating the guest and writing its request count against the
+    /// `timeout` as the export call does.
+    fn new_store(&self, wasi: Wasi) -> Result<WtStore<Invocation>, SetupError> {
+        let mut store = WtStore::new(
+            shared_engine()?,
+            Invocation::new(self.config.memory_limit, wasi),
+        );
         store.limiter(|state: &mut Invocation| -> &mut dyn ResourceLimiter { state.limiter_mut() });
-        store.epoch_deadline_callback(trap::epoch_deadline_callback);
+        trap::arm_deadline(&mut store, self.config.timeout);
+        store.data_mut().start_wall_clock();
         Ok(store)
     }
 
-    /// Instantiate the per-invocation instance from the pre-linked
-    /// template and resolve its host-driven export handles. An
-    /// instantiation failure at invocation time is an engine fault —
-    /// a `Trap` — unlike the construction-time probe, whose failure is
-    /// `SetupError`.
+    /// Failing here is an engine fault — a `Trap` — unlike the
+    /// construction-time probe, whose failure is a `SetupError`.
     fn instantiate(&self, store: &mut WtStore<Invocation>) -> Result<Exports, Trap> {
         let instance = self
             .instance_pre
             .instantiate(store.as_context_mut())
-            .map_err(|e| Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}")))?;
-        Ok(Exports::resolve(&instance, store.as_context_mut()))
+            .map_err(|e| {
+                trap::cap_trap(&e).unwrap_or_else(|| {
+                    Trap::Other(format!("failed to instantiate the Sandbox runtime: {e}"))
+                })
+            })?;
+        let exports = Exports::resolve(&instance, store.as_context_mut());
+        store.data_mut().set_exports(exports.clone());
+        Ok(exports)
     }
 
-    /// Run one guest export call inside the per-invocation cap window:
-    /// `Driver::prime_caps` before, `disarm_caps` after — the shared
-    /// bracket for both run-path exports (`__kobako_eval` /
-    /// `__kobako_run`). Disarm runs whether the call returns or traps, so
-    /// the `wall_time` bracket and the memory
-    /// cap always close — that close-on-trap guarantee is the reason this
-    /// bracket lives in one place rather than inline at each call site.
-    /// The wasmtime trap is returned unmapped; the caller classifies it
-    /// through `trap::trap_from`.
+    /// Disarm runs whether the call returns or traps, so the `wall_time`
+    /// bracket and the memory cap always close; that guarantee is why the
+    /// bracket lives in one place rather than at each call site.
     fn call_with_caps<Params, Results>(
         &self,
         store: &mut WtStore<Invocation>,
@@ -93,143 +95,190 @@ impl Driver {
         Params: wasmtime::WasmParams,
         Results: wasmtime::WasmResults,
     {
-        self.prime_caps(store, exports);
+        self.arm_memory_cap(store, exports);
         let result = export.call(store.as_context_mut(), params);
         disarm_caps(store);
         result
     }
 
-    /// Stamp the per-invocation wall-clock deadline into `Invocation`
-    /// and prime the wasmtime epoch deadline so the next ticker tick
-    /// wakes the epoch-deadline callback. When `timeout` is disabled,
-    /// the deadline is set far enough in the future that the callback
-    /// effectively never fires.
-    ///
-    /// Also captures the current linear-memory size as the baseline
-    /// for the per-invocation memory delta cap —
-    /// the pre-initialized image's allocation is folded into the
-    /// baseline rather than the budget — and stamps the wall-clock
-    /// entry instant for the `wall_time`
-    /// measurement. The bracket closes in `disarm_caps` so it matches
-    /// the `timeout` deadline window and excludes `OUTCOME_BUFFER`
-    /// decoding and stdout / stderr capture readout.
-    fn prime_caps(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
-        match self.config.timeout {
-            Some(timeout) => {
-                let deadline = Instant::now() + timeout;
-                store.data_mut().set_deadline(Some(deadline));
-                store.set_epoch_deadline(1);
-            }
-            None => {
-                store.data_mut().set_deadline(None);
-                store.set_epoch_deadline(trap::NO_TIMEOUT_EPOCH_DELTA);
-            }
-        }
+    /// The pre-initialized image's allocation is folded into the memory
+    /// baseline rather than the budget, so the cap arms only once the
+    /// image is in place.
+    fn arm_memory_cap(&self, store: &mut WtStore<Invocation>, exports: &Exports) {
         let baseline = match exports.memory {
             Some(m) => m.data_size(store.as_context_mut()),
             None => 0,
         };
         store.data_mut().arm_memory_cap(baseline);
-        store.data_mut().start_wall_clock();
     }
 
-    /// Bundle one invocation's observables into a fresh `Snapshot`,
-    /// uniformly for every `completion` — the clipped captures and the
-    /// cap-bracket usage must survive a trap just as they do an outcome.
+    /// Built the same for every `completion`: captures and usage must
+    /// survive a trap just as they do an outcome.
     fn build_snapshot(&self, store: &WtStore<Invocation>, completion: Completion) -> Snapshot {
         let data = store.data();
-        let usage = Usage {
-            wall_time: data.wall_time().as_secs_f64(),
-            memory_peak: data.memory_peak(),
+        let mut usage = Usage::default();
+        usage.wall_time = data.wall_time().as_secs_f64();
+        usage.memory_peak = data.memory_peak();
+        let clip = |bytes, limit| {
+            let mut capture = Capture::default();
+            (capture.bytes, capture.truncated) = capture::clip_capture(bytes, limit);
+            capture
         };
-        let (stdout_bytes, stdout_truncated) =
-            capture::clip_capture(data.stdout_bytes(), self.config.stdout_limit);
-        let (stderr_bytes, stderr_truncated) =
-            capture::clip_capture(data.stderr_bytes(), self.config.stderr_limit);
-        Snapshot {
+        Snapshot::new(
             completion,
-            stdout: Capture {
-                bytes: stdout_bytes,
-                truncated: stdout_truncated,
-            },
-            stderr: Capture {
-                bytes: stderr_bytes,
-                truncated: stderr_truncated,
-            },
+            clip(data.wasi().stdout_bytes(), self.config.stdout_limit),
+            clip(data.wasi().stderr_bytes(), self.config.stderr_limit),
             usage,
-        }
+        )
     }
 }
 
 impl ContractRuntime for Driver {
-    /// Drive one guest invocation on a fresh instance and return its
-    /// `Snapshot`, `Ok` iff the guest export ran. Builds a fresh Store,
-    /// binds the borrowed dispatch handler, installs the stdin frames
-    /// (three for `Eval` — preamble / source / snippets; two for `Run` —
-    /// preamble / snippets, with the envelope copied into guest memory),
-    /// and primes the per-invocation caps around the export call. A fault
-    /// before the export call is the `Err` channel; once the call starts,
-    /// every fault folds into the Snapshot's `Completion` — the
-    /// configured-cap paths as `Trap::Timeout` / `Trap::MemoryLimit`,
-    /// everything else as `Trap::Other` — so captures and usage survive
-    /// it. The body touches no frontend value — the handler is only
-    /// borrowed (see the trait's safety contract).
+    /// A fault before the export call is the `Err`; once the call
+    /// starts, every fault folds into the Snapshot's `Completion` so
+    /// captures and usage survive it. The handler is only borrowed (see the
+    /// trait's safety contract).
     fn invoke(
         &self,
         entry: Entry<'_>,
-        frames: Frames<'_>,
+        preamble: &Preamble,
         handler: Option<Arc<dyn DispatchHandler>>,
+        grants: &[Grant],
     ) -> Result<Snapshot, InvokeError> {
-        let mut store = self.new_store()?;
+        let wasi = Wasi::for_invocation(&self.config, &preamble.encode(), grants)?;
+        let mut store = self.new_store(wasi)?;
         if let Some(handler) = handler {
             store.data_mut().bind_on_dispatch(handler);
         }
-        let frame_list: Vec<&[u8]> = match &entry {
-            Entry::Eval { source } => vec![frames.preamble, source, frames.snippets],
-            Entry::Run { .. } => vec![frames.preamble, frames.snippets],
-        };
-        frames::install_wasi_frames(&mut store, &self.config, &frame_list)?;
         let exports = self.instantiate(&mut store)?;
-        let called = match entry {
-            Entry::Eval { .. } => {
-                let eval = frames::require_export(exports.eval.as_ref())?;
-                self.call_with_caps(&mut store, &exports, eval, ())
-            }
-            Entry::Run { envelope } => {
-                let run = frames::require_export(exports.run.as_ref())?;
-                let (env_ptr, env_len) = frames::write_envelope(&mut store, &exports, envelope)?;
-                self.call_with_caps(&mut store, &exports, run, (env_ptr, env_len))
-            }
-        };
+        let downcall = exports::require(exports.downcall.as_ref())?;
+        let request = match entry {
+            Entry::Eval { source } => Downcall::Eval(source.to_vec()),
+            Entry::Run {
+                entrypoint,
+                payload,
+            } => Downcall::Run(Run {
+                entrypoint: entrypoint.to_owned(),
+                payload,
+            }),
+        }
+        .encode();
+        let (ptr, len) = io::write_request(&mut store, &exports, &request)?;
+        let called = self.call_with_caps(&mut store, &exports, downcall, (ptr, len));
         let completion = match called {
-            Ok(()) => match frames::fetch_outcome_bytes(&mut store, &exports) {
-                Ok(bytes) => Completion::Outcome(bytes),
+            Ok(packed) => match io::read_outcome(&store, &exports, packed) {
+                Ok(outcome) => Completion::Outcome(outcome),
                 Err(t) => Completion::Trap(t),
             },
-            Err(e) => Completion::Trap(trap::trap_from(e)),
+            Err(e) => Completion::Trap(trap::to_trap(e)),
         };
         Ok(self.build_snapshot(&store, completion))
     }
 
-    /// The posture this driver built — exactly the rung requested via
-    /// `Config`. Every per-invocation WASI context is built to it
-    /// (`frames::install_wasi_frames`): `Hermetic` freezes ambient time
-    /// and entropy (`crate::ambient`), `Permissive` leaves the live WASI
-    /// sources. Both rungs wire no filesystem, environment, or network,
-    /// and the linker adds only the wire ABI's `__kobako_dispatch`
-    /// beyond that confined WASI surface (`crate::instance_pre`).
+    /// Exactly the rung `Config` requested. `Hermetic` freezes ambient time
+    /// and entropy; both rungs wire no ambient filesystem, environment, or network,
+    /// and the linker adds only `__kobako_upcall` beyond that WASI surface.
     fn profile(&self) -> Profile {
         self.config.profile
     }
+
+    /// A Mount becomes a preopen of kobako's own descriptor table, which
+    /// answers every preview1 call beneath it.
+    fn supports(&self, kind: GrantKind) -> bool {
+        matches!(kind, GrantKind::Mount)
+    }
+
+    /// Bounded by the same caps as an invocation, on an instance of its
+    /// own that no script ever runs on, so what it answers carries
+    /// nothing a script could have written.
+    fn compile(&self, preamble: &Preamble) -> Option<Vec<Vec<u8>>> {
+        let wasi = Wasi::for_compile(&self.config, &preamble.encode()).ok()?;
+        let mut store = self.new_store(wasi).ok()?;
+        let exports = self.instantiate(&mut store).ok()?;
+        let downcall = exports::require(exports.downcall.as_ref()).ok()?;
+        let (ptr, len) =
+            io::write_request(&mut store, &exports, &Downcall::Compile.encode()).ok()?;
+        let packed = self
+            .call_with_caps(&mut store, &exports, downcall, (ptr, len))
+            .ok()?;
+        match io::read_compile_reply(&store, &exports, packed).ok()? {
+            CompileReply::Ok(bytecodes) => one_per_source(preamble, bytecodes)
+                .filter(|bytecodes| replay_fits(preamble, bytecodes)),
+            CompileReply::Error(_) | CompileReply::Unsupported(_) => None,
+        }
+    }
+}
+
+/// Each invocation sends the Preamble with every bytecode in place of its
+/// source, so an answer that would carry it past the payload cap would trap
+/// every invocation the source alone fits.
+fn replay_fits(preamble: &Preamble, bytecodes: &[Vec<u8>]) -> bool {
+    let mut replay = preamble.clone();
+    let sources = replay
+        .snippets
+        .entries
+        .iter_mut()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }));
+    for (entry, body) in sources.zip(bytecodes) {
+        *entry = Snippet::Bytecode { body: body.clone() };
+    }
+    guest_mem::checked_payload_len(replay.encode().len()).is_ok()
+}
+
+/// A frontend replays each bytecode in place of one source snippet, in
+/// order, so an answer of any other length leaves nothing to replay.
+fn one_per_source(preamble: &Preamble, bytecodes: Vec<Vec<u8>>) -> Option<Vec<Vec<u8>>> {
+    let sources = preamble
+        .snippets
+        .entries
+        .iter()
+        .filter(|entry| matches!(entry, Snippet::Source { .. }))
+        .count();
+    (bytecodes.len() == sources).then_some(bytecodes)
 }
 
-/// Drop the memory cap as soon as the guest call returns so that
-/// any post-run host bookkeeping (e.g. fetching the OUTCOME_BUFFER,
-/// which can grow guest memory transiently) is not attributed to
-/// the user script. Also closes the
-/// `wall_time` bracket opened by `Driver::prime_caps`. Paired
-/// with `Driver::prime_caps`.
 fn disarm_caps(store: &mut WtStore<Invocation>) {
     store.data_mut().stop_wall_clock();
     store.data_mut().disarm_memory_cap();
 }
+
+#[cfg(test)]
+mod tests {
+    use kobako_transport::envelope::Snippets;
+
+    use super::*;
+
+    /// One source between two bytecode snippets: a compile answers one
+    /// bytecode for it.
+    fn one_source() -> Preamble {
+        let mut preamble = Preamble::default();
+        preamble.snippets = Snippets {
+            entries: vec![
+                Snippet::Bytecode { body: vec![0xaa] },
+                Snippet::Source {
+                    name: "Only".into(),
+                    body: "1".into(),
+                },
+                Snippet::Bytecode { body: vec![0xbb] },
+            ],
+        };
+        preamble
+    }
+
+    // @behavior WE-089
+    #[test]
+    fn a_compiled_answer_of_another_length_leaves_nothing_compiled() {
+        let preamble = one_source();
+
+        assert_eq!(
+            [
+                one_per_source(&preamble, Vec::new()),
+                one_per_source(&preamble, vec![vec![0x01], vec![0x02]]),
+                one_per_source(&preamble, vec![vec![0x01]]),
+            ],
+            [None, None, Some(vec![vec![0x01]])],
+            "a compiled answer through Driver#compile must be kept only when it carries one \
+             bytecode per source snippet"
+        );
+    }
+}

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

@@ -1,56 +1,47 @@
 //! Per-invocation wasmtime export handles for the host-driven ABI
 //! surface.
 //!
-//! `Driver::instantiate` resolves the ABI exports the run path drives
-//! (`__kobako_eval` / `__kobako_run` / `__kobako_take_outcome` /
-//! `__kobako_alloc`) plus the `memory` export against each fresh
-//! per-invocation instance and bundles their
-//! typed handles here, so the invocation body passes one struct around
-//! rather than re-resolving exports by name at every step. Distinct
-//! from `crate::cache` (the process-wide Engine / Module cache): this
-//! carries *which guest function to call*, per invocation.
-//!
-//! `crate::dispatch` does not reach this struct — a host import runs
-//! against a `Caller`, so the dispatch path resolves `__kobako_alloc`
-//! and `memory` through `Caller::get_export` instead.
+//! Each ABI export is named and typed once, here, against each fresh
+//! per-invocation instance. The invocation body and the host imports
+//! running inside it both drive the guest through these handles, never
+//! by looking an export up by name. Distinct from `crate::cache` (the
+//! process-wide Engine / Module cache): this carries *which guest
+//! function to call*, per invocation.
 
 use wasmtime::{AsContextMut, Instance as WtInstance, Memory, TypedFunc};
 
+use crate::guest_mem::SANDBOX_RUNTIME_NOT_KOBAKO;
+use kobako_runtime::error::Trap;
+
+/// For a required guest export that is absent or mistyped, wherever it is
+/// looked up. Names neither the export nor a frontend's artifact path;
+/// what a caller can do is rebuild the runtime.
+pub(crate) const RUNTIME_INCOMPATIBLE: &str =
+    "the Sandbox runtime is incompatible; rebuild it against the kobako version in use";
+
 /// The resolved host-driven export handles. Each is `Option` because test
 /// fixtures (a minimal "ping" module) need not provide them; real
-/// `kobako.wasm` always does, and the run-path methods surface a `Trap`
-/// (via `require_export` / `require_memory`) when a handle is `None`.
+/// `kobako.wasm` always does, and the run path surfaces a `Trap` (via
+/// `require` / `Exports::require_memory`) when a handle is `None`.
 ///
 /// The handles are indices into the owning Store, not borrows of the
 /// `Instance` — they stay valid for the Store's lifetime, which is why
-/// no `Instance` field is kept.
+/// no `Instance` field is kept, and why a clone can ride in the Store's
+/// own data for the host imports to reach.
+#[derive(Clone)]
 pub(crate) struct Exports {
-    pub(crate) eval: Option<TypedFunc<(), ()>>,
-    pub(crate) run: Option<TypedFunc<(i32, i32), ()>>,
-    pub(crate) take_outcome: Option<TypedFunc<(), u64>>,
+    pub(crate) downcall: Option<TypedFunc<(i32, i32), u64>>,
     pub(crate) alloc: Option<TypedFunc<u32, u32>>,
     pub(crate) memory: Option<Memory>,
 }
 
 impl Exports {
-    /// Best-effort lookup of the host-driven exports against a freshly
-    /// instantiated module. Missing exports are not an error here
-    /// (the test fixture is a bare module); the host enforces presence at
-    /// invocation time. Only the SPEC ABI shapes are accepted —
-    /// `__kobako_eval` is `() -> ()`, `__kobako_run` is
-    /// `(env_ptr, env_len) -> ()`, `__kobako_take_outcome` is `() -> u64`,
-    /// `__kobako_alloc` is `(len) -> ptr`
-    /// (docs/wire-codec.md § ABI Signatures).
+    /// A missing export is not an error here, because the test fixture is a
+    /// bare module; presence is enforced at invocation time.
     pub(crate) fn resolve(instance: &WtInstance, mut ctx: impl AsContextMut) -> Self {
         Self {
-            eval: instance
-                .get_typed_func::<(), ()>(&mut ctx, "__kobako_eval")
-                .ok(),
-            run: instance
-                .get_typed_func::<(i32, i32), ()>(&mut ctx, "__kobako_run")
-                .ok(),
-            take_outcome: instance
-                .get_typed_func::<(), u64>(&mut ctx, "__kobako_take_outcome")
+            downcall: instance
+                .get_typed_func::<(i32, i32), u64>(&mut ctx, "__kobako_downcall")
                 .ok(),
             alloc: instance
                 .get_typed_func::<u32, u32>(&mut ctx, "__kobako_alloc")
@@ -58,4 +49,67 @@ impl Exports {
             memory: instance.get_memory(&mut ctx, "memory"),
         }
     }
+
+    pub(crate) fn require_memory(&self) -> Result<Memory, Trap> {
+        self.memory
+            .ok_or_else(|| Trap::Other(SANDBOX_RUNTIME_NOT_KOBAKO.to_string()))
+    }
+}
+
+pub(crate) fn require<Params, Results>(
+    export: Option<&TypedFunc<Params, Results>>,
+) -> Result<&TypedFunc<Params, Results>, Trap>
+where
+    Params: wasmtime::WasmParams,
+    Results: wasmtime::WasmResults,
+{
+    export.ok_or_else(|| Trap::Other(RUNTIME_INCOMPATIBLE.to_string()))
+}
+
+#[cfg(test)]
+mod tests {
+    //! The ABI is a closed set of guest exports, so the bundled Guest
+    //! Binary is read for what it exports rather than only for whether
+    //! `resolve` finds what it looks up — an extra entry point would pass
+    //! every lookup. A missing binary is a hard failure under
+    //! CI (which always builds it) and a silent skip locally.
+    use std::path::Path;
+
+    use wasmtime::ExternType;
+
+    use crate::cache::cached_module;
+
+    const WASM: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/../../data/kobako.wasm");
+
+    const ABI_EXPORTS: [&str; 3] = [
+        "__kobako_abi_version",
+        "__kobako_alloc",
+        "__kobako_downcall",
+    ];
+
+    // @behavior RT-068
+    #[test]
+    fn the_guest_binary_exports_the_abi_functions_and_nothing_else() {
+        let path = Path::new(WASM);
+        if !path.exists() {
+            assert!(
+                std::env::var_os("CI").is_none(),
+                "data/kobako.wasm missing under CI — run `bundle exec rake wasm:build`"
+            );
+            return;
+        }
+        let module = cached_module(path).expect("the Guest Binary must load");
+
+        let mut functions: Vec<&str> = module
+            .exports()
+            .filter(|export| matches!(export.ty(), ExternType::Func(_)))
+            .map(|export| export.name())
+            .collect();
+        functions.sort_unstable();
+
+        assert_eq!(
+            functions, ABI_EXPORTS,
+            "data/kobako.wasm read through its export section must export exactly the ABI's functions"
+        );
+    }
 }