kobako 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ddc9be38e5ce7f23c176bcd7be8b8683cf58d308dfedb17e91fc5841308a5c8c
-  data.tar.gz: 4a0de9e36b529010b50148ff9d904cafbe253b0c394a9a2118e6ef4d7c9e4029
+  metadata.gz: bb91cd11e954d6388b7d6c19be8b9fc77548fa1ea9d57b75f1afc7c0d450a36b
+  data.tar.gz: f84463e4b30e2ae5cb1e7d09a7c55345a419afd442613a1eb6b080682263587f
 SHA512:
-  metadata.gz: ae0e599389ce723a1c257923a5b5b760ddf94a71698e5fa990f82587494ae8ca874d11c8c1fd5eedfac0d6e953f53cfb8603fb4da34989f8f92e39425bb99fa5
-  data.tar.gz: 6cbdec819843c52c1be3d04a6694af51ae41121e159a4de12d1ebef0074d1626247c8c06db0e9f15da2deb19b4b1730c124aa027bc676ffc2b1fedf6cd68d3c7
+  metadata.gz: d622978cf22e2b30dbf8674275bbaaf39d0de68962709b40b67194d0521ca3d1e991e9a4e59853e634c111fc852d4719864c2990f2baaf35e1395efa3f67b63a
+  data.tar.gz: 3f828b5374841d0bcb8136a7c1aa078668c05c3673c794c50f86de9b1aee0bd915d090e022061b3e9636abb2dfb85a0b3bf1a7bbacff968635d9ed01c5f21edd

data/Cargo.lock

@@ -864,7 +864,7 @@ dependencies = [
 
 [[package]]
 name = "kobako"
-version = "0.3.0"
+version = "0.4.0"
 dependencies = [
  "magnus",
  "wasmtime",

data/README.md

@@ -27,10 +27,11 @@ The host (`wasmtime`) runs a precompiled `kobako.wasm` guest containing mruby an
 | Per-invocation caps | Every invocation enforces a wall-clock `timeout` (default 60 s) and a per-invocation linear-memory `memory_limit` (default 1 MiB); exhaustion raises `Kobako::TimeoutError` / `Kobako::MemoryLimitError`. |
 | Capability injection via Services | Guest scripts can only call Ruby objects you explicitly `bind` under a two-level `Namespace::Member` path. |
 | Preloaded snippets | `Sandbox#preload` registers source or RITE bytecode for setup-once dispatch via `Sandbox#run(:Entrypoint, *args, **kwargs)`. |
-| Capability Handles | Services may return stateful host objects; the guest receives an opaque `Kobako::RPC::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. |
+| Capability Handles | Services may return stateful host objects; the guest receives an opaque `Kobako::Handle` proxy it can use as the target of follow-up RPC calls, with no way to dereference it. `Sandbox#run` also accepts non-wire-representable Ruby objects as args and auto-wraps them into Handles, so the guest can use any host object the script needs. |
 | Three-class error taxonomy | Every failure is exactly one of `TrapError`, `SandboxError`, or `ServiceError`, so you can route errors without inspecting messages. |
 | Per-invocation state reset | Handles issued during one invocation are invalidated before the next; Service bindings and preloaded snippets remain. |
 | Separated stdout / stderr capture | Guest writes to `$stdout` / `$stderr` are buffered per-channel (1 MiB default cap, configurable); overflow is clipped and reported by `#stdout_truncated?` / `#stderr_truncated?`. |
+| Per-invocation usage readout | `Sandbox#usage` returns the most recent invocation's `wall_time` (Float seconds spent inside the wasm guest) and `memory_peak` (high-water `memory.grow` delta in bytes), populated on every outcome including `TrapError`, for budget diagnostics. |
 | Curated mruby stdlib | Core extensions plus `mruby-onig-regexp` for full Onigmo `Regexp` support; no mrbgem with I/O, network, or syscall access is bundled. |
 
 ## Requirements
@@ -122,6 +123,19 @@ The timeout deadline is absolute wall-clock from invocation entry and is checked
 
 The 1 MiB default targets lightweight dynamic RPC workloads — short scripts that orchestrate Service calls, return small structured values, or replace a tool-calling layer in an AI Agent's Code Mode dispatch. Bump `memory_limit` when scripts compose multi-hundred-KiB strings, hold large composite return values, or run computations that allocate substantial intermediate state. Because the cap resets every invocation, multi-call patterns on one Sandbox do not need a budget that covers their cumulative footprint — only the largest single invocation's working set.
 
+To see how much of the cap an invocation actually consumed, read `Sandbox#usage` after the call. It returns a `Kobako::Usage` value object with `wall_time` (Float seconds the guest export call spent inside wasmtime, aligned with the `timeout` accounting) and `memory_peak` (Integer high-water `memory.grow` delta in bytes, aligned with the `memory_limit` accounting). The fields are populated on every outcome, including the `TrapError` branches, so you can read them after rescuing a trap to diagnose which budget the failing invocation chewed through.
+
+```ruby
+sandbox = Kobako::Sandbox.new(timeout: 1.0, memory_limit: 4 * 1024 * 1024)
+
+begin
+  sandbox.eval("'x' * 5_000_000")
+rescue Kobako::MemoryLimitError
+  sandbox.usage.memory_peak  # => the largest delta accepted before the trap
+  sandbox.usage.wall_time    # => seconds spent before the cap fired
+end
+```
+
 ## Capturing stdout and stderr
 
 Guest output is captured into per-invocation buffers and exposed independently from the return value. The buffers cover the full Ruby IO surface — `puts`, `print`, `printf`, `p`, `<<`, and writes through `$stdout` / `$stderr` — all routed through the host-captured WASI pipe.
@@ -183,7 +197,7 @@ end
 
 ## Capability Handles
 
-When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::RPC::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
+When a Service returns a stateful host object (anything beyond `nil` / Boolean / Integer / Float / String / Symbol / Array / Hash), the wire layer transparently allocates an opaque Handle. The guest receives a `Kobako::Handle` proxy it can use as the target of further RPC calls — but cannot dereference, forge from an integer, or smuggle across runs.
 
 ```ruby
 class Greeter
@@ -194,18 +208,69 @@ end
 sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
 
 sandbox.eval(<<~RUBY)
-  g = Factory::Make.call("Bob")  # g is a Kobako::RPC::Handle proxy
+  g = Factory::Make.call("Bob")  # g is a Kobako::Handle proxy
   g.greet                         # second RPC, routed to the Greeter
 RUBY
 # => "hi, Bob"
 ```
 
+`Sandbox#run` accepts non-wire-representable host objects as args / kwargs values too: the host walks the argument tree, wraps every non-wire leaf through the same Handle path, and the guest sees a `Kobako::Handle` proxy in its place. This lets you pass framework objects (a Rack `env` Hash containing an `IO`-like body, an active record, an enumerator) into the entrypoint without first marshalling them into primitives.
+
+```ruby
+require "stringio"
+
+sandbox = Kobako::Sandbox.new
+sandbox.preload(code: "Echo = ->(body) { body.read.upcase }", name: :Echo)
+
+sandbox.run(:Echo, StringIO.new("hello world"))
+# => "HELLO WORLD"
+```
+
 Handles are scoped to a single invocation — a Handle obtained in invocation N is invalid in invocation N+1, even on the same Sandbox.
 
 ## Setup-once, run-many
 
 A single Sandbox can serve many invocations. Service bindings and preloaded snippets persist; capability state (Handles, stdout, stderr) resets between invocations.
 
+```
+   ───────────── setup phase (mutable) ─────────────
+
+     sandbox = Kobako::Sandbox.new
+     sandbox.define(:KV).bind(:Lookup, ...)
+     sandbox.preload(code: ..., name: :Adder)
+     sandbox.preload(code: ..., name: :Greeter)
+
+                          │
+                          ▼
+
+   ═════════════════ seal point ═════════════════
+   First #eval or #run freezes the Service registry
+   and snippet table. Further define / preload now
+   raise ArgumentError.
+
+                          │
+                          ▼
+
+   ──────────────── invocation N ───────────────────
+
+     1. allocate fresh mrb_state
+
+     2. replay snippets (in insertion order):
+          :Adder     → defines Adder
+          :Greeter   → defines Greeter
+
+     3. dispatch:  eval(source)  or  run(:Target, *args)
+
+     4. return value to host
+
+     5. discard mrb_state; reset per-invocation state:
+          · Handles invalidated
+          · stdout / stderr buffers cleared
+          · memory delta zeroed
+
+     Services + snippets persist; invocation N+1 repeats.
+```
+
 ```ruby
 sandbox = Kobako::Sandbox.new
 sandbox.define(:Data).bind(:Fetch, ->(id) { records[id] })
@@ -240,6 +305,21 @@ The source form trial-compiles each snippet against a fresh `mrb_state` at prelo
 
 Snippets replay in insertion order, so later snippets can reference constants defined by earlier ones. The snippet table is sealed by the first invocation alongside Service registration; additional `#preload` calls after the first `#eval` or `#run` raise `ArgumentError`.
 
+```
+   per-invocation replay (every #eval / #run, snippets in insertion order):
+
+      fresh mrb_state
+            │
+            ├──▶ replay :Adder            (defines Adder)
+            │
+            ├──▶ replay :Greeter          (defines Greeter)
+            │
+            └──▶ eval(source)  -or-  run(:Target, *args, **kwargs)
+                       │
+                       ▼
+                  return value, then mrb_state discarded
+```
+
 `#run` resolves `target` (Symbol or String, normalized to Symbol) only as a top-level `Object` constant — `::`-segmented names and lowercase forms fail at host pre-flight with `ArgumentError`. A `Kobako::SandboxError` surfaces when the constant is missing or does not respond to `#call`.
 
 ### Choosing between source and bytecode
@@ -273,9 +353,9 @@ The ~600 ms cold start dominates the first Sandbox in a process — wasmtime JIT
 
 | Allocation                                  | Cost                                                                       |
 |---------------------------------------------|----------------------------------------------------------------------------|
-| Process RSS after first `Sandbox.new`       | ~150-180 MB (one-time engine + module + first instance)                    |
+| Process RSS after first `Sandbox.new`       | ~165-195 MB (one-time engine + module + first instance)                    |
 | Per additional Sandbox                      | ~580 KB (Wasm instance + linear memory + WASI capture pipes)               |
-| 1 000 isolated tenants in one process       | ~750 MB total                                                              |
+| 1 000 isolated tenants in one process       | ~765 MB total                                                              |
 
 Use these as upper-bound budgets for capacity planning, not lower bounds — actual RSS shifts ~30% with host process load and macOS allocator state.
 

data/ext/kobako/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "kobako"
-version = "0.3.0"
+version = "0.4.0"
 edition = "2021"
 authors = ["Aotokitsuruya <contact@aotoki.me>"]
 license = "Apache-2.0"

data/ext/kobako/src/wasm/cache.rs

@@ -112,16 +112,24 @@ pub(crate) fn cached_module(path: &Path) -> Result<WtModule, MagnusError> {
         return Err(MagnusError::new(
             ruby.get_inner(&MODULE_NOT_BUILT_ERROR),
             format!(
-                "wasm module not found at {}; run `bundle exec rake wasm:build` to build it",
+                "Sandbox runtime not found at {}; run `bundle exec rake wasm:build` to build it",
                 path.display()
             ),
         ));
     }
 
-    let bytes =
-        fs::read(path).map_err(|e| wasm_err(&ruby, format!("read {}: {}", path.display(), e)))?;
+    let bytes = fs::read(path).map_err(|e| {
+        wasm_err(
+            &ruby,
+            format!(
+                "failed to read Sandbox runtime at {}: {}",
+                path.display(),
+                e
+            ),
+        )
+    })?;
     let module = WtModule::new(shared_engine()?, &bytes)
-        .map_err(|e| wasm_err(&ruby, format!("compile module: {}", e)))?;
+        .map_err(|e| wasm_err(&ruby, format!("failed to compile Sandbox runtime: {}", e)))?;
     cache
         .lock()
         .expect("module cache mutex poisoned")

data/ext/kobako/src/wasm/dispatch.rs

@@ -79,19 +79,20 @@ fn try_handle(
     req_ptr: i32,
     req_len: i32,
 ) -> Result<i64, &'static str> {
-    let req_bytes = read_caller_memory(caller, req_ptr, req_len)
-        .ok_or("guest 'memory' export missing or request slice out of bounds")?;
+    let req_bytes = read_caller_memory(caller, req_ptr, req_len).ok_or(
+        "Sandbox runtime does not export linear memory, or RPC request slice falls outside it",
+    )?;
 
-    // `Kobako::Sandbox` always installs a Server before invoking the
-    // guest, so reaching this branch indicates a misuse rather than a
-    // normal control path.
+    // `Kobako::Sandbox` always installs an RPC server before invoking
+    // the runtime, so reaching this branch indicates a misuse rather
+    // than a normal control path.
     let server = caller
         .data()
         .server()
-        .ok_or("no Ruby Server bound — Sandbox#run must precede __kobako_dispatch")?;
+        .ok_or("RPC dispatched outside an active Sandbox#run — internal wiring bug")?;
 
     let resp_bytes = invoke_server(server, &req_bytes).map_err(|_| {
-        "Ruby Server#dispatch raised — contract is to fold faults into Response.err"
+        "RPC server raised an exception instead of returning a fault — please report this as a kobako bug"
     })?;
 
     write_response(caller, &resp_bytes)
@@ -123,23 +124,23 @@ fn write_response(caller: &mut Caller<'_, HostState>, bytes: &[u8]) -> Result<i6
     let alloc = match caller.get_export("__kobako_alloc") {
         Some(Extern::Func(f)) => f
             .typed::<i32, i32>(&*caller)
-            .map_err(|_| "guest '__kobako_alloc' export has wrong signature")?,
-        _ => return Err("guest '__kobako_alloc' export missing"),
+            .map_err(|_| "Sandbox runtime's allocation hook has the wrong signature")?,
+        _ => return Err("Sandbox runtime is missing the allocation hook"),
     };
-    let len_i32 = i32::try_from(bytes.len()).map_err(|_| "response exceeds i32::MAX bytes")?;
+    let len_i32 = i32::try_from(bytes.len()).map_err(|_| "RPC response exceeds 2 GiB")?;
     let ptr = alloc
         .call(&mut *caller, len_i32)
-        .map_err(|_| "__kobako_alloc trapped")?;
+        .map_err(|_| "Sandbox allocation trapped while preparing the RPC response")?;
     if ptr == 0 {
-        return Err("__kobako_alloc returned 0 (out of memory)");
+        return Err("Sandbox is out of memory while preparing the RPC response");
     }
 
     let mem = match caller.get_export("memory") {
         Some(Extern::Memory(m)) => m,
-        _ => return Err("guest 'memory' export missing"),
+        _ => return Err("Sandbox runtime does not export linear memory"),
     };
     mem.write(&mut *caller, ptr as usize, bytes)
-        .map_err(|_| "memory.write rejected response buffer range")?;
+        .map_err(|_| "could not write the RPC response into Sandbox memory (range invalid)")?;
 
     let ptr_u32 = ptr as u32;
     let len_u32 = bytes.len() as u32;

data/ext/kobako/src/wasm/host_state.rs

@@ -17,7 +17,7 @@
 //! budget.
 
 use std::cell::{Ref, RefCell, RefMut};
-use std::time::Instant;
+use std::time::{Duration, Instant};
 
 use magnus::{value::Opaque, Value};
 use wasmtime::{ResourceLimiter, Store as WtStore};
@@ -39,6 +39,8 @@ pub(super) struct HostState {
     server: Option<Opaque<Value>>,
     deadline: Option<Instant>,
     limiter: KobakoLimiter,
+    wall_entry: Option<Instant>,
+    wall_time: Duration,
 }
 
 impl HostState {
@@ -54,6 +56,8 @@ impl HostState {
             server: None,
             deadline: None,
             limiter: KobakoLimiter::new(memory_limit),
+            wall_entry: None,
+            wall_time: Duration::ZERO,
         }
     }
 
@@ -156,6 +160,42 @@ impl HostState {
     pub(super) fn disarm_memory_cap(&mut self) {
         self.limiter.deactivate();
     }
+
+    /// Stamp the wall-clock entry instant for the docs/behavior.md
+    /// B-35 `wall_time` measurement. Called at the top of every
+    /// invocation immediately before the guest export call so the
+    /// bracket matches the `timeout` deadline accounting (B-01) and
+    /// excludes post-run host bookkeeping such as `OUTCOME_BUFFER`
+    /// decoding.
+    pub(super) fn start_wall_clock(&mut self) {
+        self.wall_entry = Some(Instant::now());
+    }
+
+    /// Close the docs/behavior.md B-35 `wall_time` measurement
+    /// started by [`HostState::start_wall_clock`]. Idempotent — a
+    /// stop with no matching start (e.g. if the guest export call
+    /// never executed because of a host-side allocation failure)
+    /// leaves the previously-recorded value untouched.
+    pub(super) fn stop_wall_clock(&mut self) {
+        if let Some(entry) = self.wall_entry.take() {
+            self.wall_time = entry.elapsed();
+        }
+    }
+
+    /// Return the wall-clock duration the most recent invocation
+    /// spent inside the guest export call (docs/behavior.md B-35).
+    /// Zero before the first invocation.
+    pub(super) fn wall_time(&self) -> Duration {
+        self.wall_time
+    }
+
+    /// Return the docs/behavior.md B-35 `memory_peak` — the high-
+    /// water mark of the per-invocation `memory.grow` delta past the
+    /// linear-memory size captured at invocation entry. Zero before
+    /// the first invocation.
+    pub(super) fn memory_peak(&self) -> usize {
+        self.limiter.peak()
+    }
 }
 
 /// Resource limiter that enforces the per-invocation `memory_limit`
@@ -183,6 +223,7 @@ pub(super) struct KobakoLimiter {
     max_memory: Option<usize>,
     baseline: usize,
     cap_active: bool,
+    peak: usize,
 }
 
 impl KobakoLimiter {
@@ -191,6 +232,7 @@ impl KobakoLimiter {
             max_memory,
             baseline: 0,
             cap_active: false,
+            peak: 0,
         }
     }
 
@@ -200,10 +242,14 @@ impl KobakoLimiter {
     /// the cap is dormant by default — the module's declared initial
     /// memory is allocated during `Linker::instantiate` and the
     /// per-invocation budget excludes anything that existed before
-    /// arming (docs/behavior.md B-01 Notes, E-20).
+    /// arming (docs/behavior.md B-01 Notes, E-20). Also clears the
+    /// per-invocation [`KobakoLimiter::peak`] high-water so the
+    /// docs/behavior.md B-35 `memory_peak` accounting restarts from
+    /// zero for the new invocation.
     fn activate(&mut self, baseline: usize) {
         self.baseline = baseline;
         self.cap_active = true;
+        self.peak = 0;
     }
 
     /// Disarm the cap so post-run host bookkeeping (e.g. fetching the
@@ -213,6 +259,18 @@ impl KobakoLimiter {
     fn deactivate(&mut self) {
         self.cap_active = false;
     }
+
+    /// Return the high-water mark of the per-invocation
+    /// `memory.grow` delta past `baseline` observed since the last
+    /// [`KobakoLimiter::activate`]. Read after the guest export
+    /// returns to populate `Kobako::Usage#memory_peak`
+    /// (docs/behavior.md B-35). Pinned to the last accepted grow —
+    /// rejected `desired` values that trip the docs/behavior.md E-20
+    /// cap never update the peak, so the reported value never exceeds
+    /// `memory_limit`.
+    pub(super) fn peak(&self) -> usize {
+        self.peak
+    }
 }
 
 impl ResourceLimiter for KobakoLimiter {
@@ -225,12 +283,15 @@ impl ResourceLimiter for KobakoLimiter {
         if !self.cap_active {
             return Ok(true);
         }
+        let delta = desired.saturating_sub(self.baseline);
         if let Some(limit) = self.max_memory {
-            let delta = desired.saturating_sub(self.baseline);
             if delta > limit {
                 return Err(wasmtime::Error::new(MemoryLimitTrap { desired, limit }));
             }
         }
+        if delta > self.peak {
+            self.peak = delta;
+        }
         Ok(true)
     }
 
@@ -270,7 +331,8 @@ impl std::fmt::Display for MemoryLimitTrap {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         write!(
             f,
-            "guest memory.grow would exceed memory_limit: desired={} bytes, limit={} bytes",
+            "linear memory growth exceeded memory_limit: \
+             desired={} bytes, limit={} bytes",
             self.desired, self.limit
         )
     }
@@ -286,7 +348,7 @@ pub(crate) struct TimeoutTrap;
 
 impl std::fmt::Display for TimeoutTrap {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        write!(f, "guest exceeded the configured wall-clock timeout")
+        write!(f, "wall-clock deadline exceeded")
     }
 }
 
@@ -420,4 +482,48 @@ mod tests {
         limiter.activate(0);
         assert_growing(&mut limiter, 100 << 20);
     }
+
+    #[test]
+    fn peak_starts_at_zero_before_any_grow() {
+        let limiter = KobakoLimiter::new(Some(1 << 20));
+        assert_eq!(limiter.peak(), 0);
+    }
+
+    #[test]
+    fn peak_tracks_high_water_of_delta_past_baseline() {
+        let mut limiter = KobakoLimiter::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);
+    }
+
+    #[test]
+    fn trap_does_not_update_peak() {
+        let mut limiter = KobakoLimiter::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);
+    }
+
+    #[test]
+    fn activate_resets_peak_for_new_invocation() {
+        let mut limiter = KobakoLimiter::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);
+    }
+
+    #[test]
+    fn disabled_cap_still_tracks_peak() {
+        let mut limiter = KobakoLimiter::new(None);
+        limiter.activate(1 << 20);
+        assert_growing(&mut limiter, (1 << 20) + (4 << 20));
+        assert_eq!(limiter.peak(), 4 << 20);
+    }
 }