kobako 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65375590ffd16758a33fee3ef16cfd3d1e99e439c378e9652da453a601b53f8a
-  data.tar.gz: 62c134b7035649fcde436816d95618287768f7a8a09d59f330cb5e785eae8024
+  metadata.gz: ac6c01cd421449a5b87d4a21777b257a204018747d468481ff309382d08f8a89
+  data.tar.gz: 2c172f0ffb8d0cb600bc8837102e584ca4492f1f59ce8d77989169d078976bb0
 SHA512:
-  metadata.gz: cc4ad901e03f7de534c41423e3e7795a410d7201caf7a4d730b93829aceefc8ff7518320c2874a80e34978a9e38d6a430b5e03edbcd2e6868cb987c1d8ed3c91
-  data.tar.gz: 0b594e9b033b3a2d27b9f330b119ddf3f246b50f462cfb8914173d4074064ce17c3f12fb20851331f1e7c50390c39f64722820564618148de37fa06a4f603beb
+  metadata.gz: 88fb3c50f8e631dbe6139ef9f8ab5e5ad50f4ee08a2aec0b8cdbba5e70c9670fb78c24e80a59916daa23ce6e9663f73ba82ad26c78e69588f59e91c72a4b1cf9
+  data.tar.gz: 1eacade67c1ddc6de4fa8a75e5975272157ea2e08c55dcb5c790eb3528941b3b96091f3695b60389d5c93d75599b04ff99a1af530530971f2765a94b101c3f57

data/.release-please-manifest.json

@@ -1 +1 @@
-{".":"0.6.1"}
+{".":"0.7.0"}

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.7.0](https://github.com/elct9620/kobako/compare/v0.6.2...v0.7.0) (2026-06-03)
+
+
+### Features
+
+* **examples/async-io:** demo single-thread I/O overlap across Sandboxes ([858a0f7](https://github.com/elct9620/kobako/commit/858a0f70bb0730e5e3ad3f49a5caadf948f6ed7d))
+* **guest:** reject construction of Handle proxies (B-39) ([bda5e2b](https://github.com/elct9620/kobako/commit/bda5e2b5e48fe25adeefac19c47f1b93585091bf))
+* **guest:** reject construction of Member proxies (B-38) ([885c281](https://github.com/elct9620/kobako/commit/885c2812da8627e4ec7c185d9e04e4056c94a7fd))
+
+
+### Bug Fixes
+
+* **ext:** surface the buried root cause on non-cap traps ([dbd1ce5](https://github.com/elct9620/kobako/commit/dbd1ce51f25ab8c83d39daee64278192d763d5ef))
+* **guest:** bound the encoder walk so cycles and deep nesting fail cleanly ([90880ff](https://github.com/elct9620/kobako/commit/90880ffe6f0ee911b3c7c076ef6c86b9e08c62e1))
+* **guest:** stop an embedded NUL in a returned value from hard-trapping ([14fbb97](https://github.com/elct9620/kobako/commit/14fbb97ecb47b4263585602754e92237bb951d46))
+* **guest:** stop named-capture regexes from hard-trapping the sandbox ([a279ea1](https://github.com/elct9620/kobako/commit/a279ea1e2f196580b396342851e4e75ff9ea5cfa))
+
+## [0.6.2](https://github.com/elct9620/kobako/compare/v0.6.1...v0.6.2) (2026-05-31)
+
+
+### Bug Fixes
+
+* **guest:** enable mruby-sprintf for printf and String#% ([1179227](https://github.com/elct9620/kobako/commit/1179227b85b861bccc82d2a258481769a13ed4d5))
+
 ## [0.6.1](https://github.com/elct9620/kobako/compare/v0.6.0...v0.6.1) (2026-05-28)
 
 

data/Cargo.lock

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

data/README.md

@@ -53,9 +53,21 @@ result # => 3
 
 The script executes inside the Wasm guest. It cannot read your filesystem, open sockets, or touch your `ENV`.
 
+## Glossary
+
+| Term | Meaning |
+|------|---------|
+| Sandbox | The runtime unit (`Kobako::Sandbox`) that runs guest code and returns a result or raises a typed error. |
+| Service | A host Ruby object injected under `<Namespace>::<Member>` — the guest's only path to host resources. |
+| Namespace / Member | A guest-visible Ruby module, and a named binding (a module constant) within it. |
+| Invocation | One `#eval` or `#run`; capability state resets between invocations. |
+| Snippet | Named mruby code (source or bytecode) replayed into a fresh state before every invocation. |
+| Handle | An opaque token the guest holds for a host object the wire cannot transmit directly. |
+| Block | A guest mruby block passed to a Service; each `yield` is a synchronous round-trip into the guest. |
+
 ## Usage
 
-### Injecting Services
+### Services
 
 Declare a Namespace, then `bind` any Ruby object as a Member; the guest reaches it as a `<Namespace>::<Member>` proxy and invokes its public methods through the Transport wire. See [`docs/behavior.md`](docs/behavior.md) B-07..B-12.
 
@@ -77,42 +89,9 @@ sandbox.eval(<<~RUBY)
 RUBY
 ```
 
-Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation; later `#define` raises `ArgumentError`.
-
-### Yielding to guest blocks
-
-A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
-
-```ruby
-sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
-
-sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
-# => [2, 4, 6]
-```
+Names must match `/\A[A-Z]\w*\z/`. Symbol kwargs travel transparently to the host method's keyword arguments. The registry seals at the first invocation (see [Invocation Lifecycle](#invocation-lifecycle)); later `#define` raises `ArgumentError`.
 
-### Per-invocation caps
-
-Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior.md`](docs/behavior.md) B-35).
-
-```ruby
-sandbox = Kobako::Sandbox.new(
-  timeout:      5.0,              # seconds, default 60.0
-  memory_limit: 10 * 1024 * 1024, # bytes,   default 1 MiB
-  stdout_limit: 64 * 1024,        # bytes,   default 1 MiB
-  stderr_limit: 64 * 1024
-)
-```
-
-| Cap            | Raises                     | Default |
-|----------------|----------------------------|---------|
-| `timeout`      | `Kobako::TimeoutError`     | 60.0 s  |
-| `memory_limit` | `Kobako::MemoryLimitError` | 1 MiB   |
-| `stdout_limit` | output clipped (no raise)  | 1 MiB   |
-| `stderr_limit` | output clipped (no raise)  | 1 MiB   |
-
-`memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
-
-### Capturing stdout / stderr
+### Output Capture
 
 Guest writes through `puts` / `print` / `p` / `$stdout` / `$stderr` are buffered per-channel and exposed independently of the return value ([`docs/behavior.md`](docs/behavior.md) B-04). Buffers clear at the start of each invocation; overflow is clipped at the cap and flagged by `#stdout_truncated?` / `#stderr_truncated?`.
 
@@ -128,7 +107,7 @@ sandbox.stdout  # => "hello\n"
 sandbox.stderr  # => "be careful\n"
 ```
 
-### Error handling
+### Error Handling
 
 Every invocation either returns a value or raises exactly one of three classes, so you can route faults without inspecting messages. The full taxonomy lives in [`lib/kobako/errors.rb`](lib/kobako/errors.rb).
 
@@ -153,25 +132,29 @@ end
 
 `SandboxError` and `ServiceError` carry structured `origin` / `klass` / `backtrace_lines` / `details` fields when the guest produced a panic envelope.
 
-### Capability Handles
+### Resource Limits
 
-A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
+Each invocation enforces a wall-clock `timeout` and a per-invocation linear-memory `memory_limit`; exhaustion raises a `TrapError` subclass. Pass `nil` to `timeout` / `memory_limit` to disable that cap. Read [`Sandbox#usage`](lib/kobako/sandbox.rb) after the call — populated on every outcome including traps — for actual consumption ([`docs/behavior.md`](docs/behavior.md) B-35).
 
 ```ruby
-class Greeter
-  def initialize(name) = @name = name
-  def greet            = "hi, #{@name}"
-end
-
-sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
-
-sandbox.eval('Factory::Make.call("Bob").greet')  # => "hi, Bob"  (Handle round-trip inside guest)
-sandbox.eval('Factory::Make.call("Bob")')        # => #<Greeter @name="Bob">  (B-37 restoration)
+sandbox = Kobako::Sandbox.new(
+  timeout:      5.0,              # seconds, default 60.0
+  memory_limit: 10 * 1024 * 1024, # bytes,   default 1 MiB
+  stdout_limit: 64 * 1024,        # bytes,   default 1 MiB
+  stderr_limit: 64 * 1024
+)
 ```
 
-A `break` value from a guest block is the one exception: it unwinds back to the guest Member call rather than to host code, so a Handle in it stays a Handle — restoring would just re-wrap the same object into a new id on the return trip.
+| Cap            | Raises                     | Default |
+|----------------|----------------------------|---------|
+| `timeout`      | `Kobako::TimeoutError`     | 60.0 s  |
+| `memory_limit` | `Kobako::MemoryLimitError` | 1 MiB   |
+| `stdout_limit` | output clipped (no raise)  | 1 MiB   |
+| `stderr_limit` | output clipped (no raise)  | 1 MiB   |
 
-### Setup-once, run-many
+`memory_limit` covers the per-invocation `memory.grow` delta from the entry baseline, so a Sandbox reused across invocations does not silently accumulate against a global budget.
+
+### Invocation Lifecycle
 
 One Sandbox serves many invocations. Service bindings and preloaded snippets persist across calls; capability state (Handles, stdout, stderr, memory delta) resets between them.
 
@@ -216,7 +199,54 @@ One Sandbox serves many invocations. Service bindings and preloaded snippets per
 
 For workloads that must be isolated from each other (one Sandbox per tenant, per student submission, per agent session), construct a fresh `Kobako::Sandbox` per scope — wasmtime's Engine and the compiled Module are cached at process scope, so additional Sandboxes amortize cold-start cost automatically.
 
-### Preloaded snippets and entrypoint dispatch
+### Service Blocks
+
+A Service method can accept a guest-supplied block via `&blk` and `yield` into it. The block body runs inside the Wasm guest; `break` / `next` / exceptions follow normal Ruby semantics, scoped to the single dispatch. See [`docs/behavior.md`](docs/behavior.md) B-23..B-30.
+
+```ruby
+sandbox.define(:Seq).bind(:Map, ->(items, &blk) { items.map(&blk) })
+
+sandbox.eval('Seq::Map.call([1, 2, 3]) { |x| x * 2 }')
+# => [2, 4, 6]
+```
+
+### Handle Management
+
+A non-wire-representable host object — returned from a Service (B-14), passed to `#run` (B-34), or handed back from the guest (B-37) — crosses the boundary as an opaque `Kobako::Handle` proxy and is restored to the original object before host code sees it; any other unrepresentable value raises `Kobako::SandboxError`. Handles are scoped to a single invocation ([`docs/behavior.md`](docs/behavior.md) B-13..B-21, B-34, B-37).
+
+```ruby
+class Greeter
+  def initialize(name) = @name = name
+  def greet            = "hi, #{@name}"
+end
+
+sandbox.define(:Factory).bind(:Make, ->(name) { Greeter.new(name) })
+
+sandbox.eval('Factory::Make.call("Bob").greet')  # => "hi, Bob"  (Handle round-trip inside guest)
+sandbox.eval('Factory::Make.call("Bob")')        # => #<Greeter @name="Bob">  (B-37 restoration)
+```
+
+A `break` value from a guest block is the one exception: it unwinds back to the guest Member call rather than to host code, so a Handle in it stays a Handle — restoring would just re-wrap the same object into a new id on the return trip.
+
+Each dispatch that hands back a non-wire-representable object allocates a *new* Handle — kobako never deduplicates by object identity (B-15, B-17). This is most visible with fluent / builder APIs. An `ActiveRecord::Relation` chain `spawn`s a fresh relation at each step, so every hop is an independent dispatch that binds its own Handle:
+
+```
+   guest chain                        host  (Catalog::Handles, one invocation)
+   ───────────                        ─────────────────────────────────────────
+   User.where(active: true)  ─call──▶ Relation #1 (fresh clone)  bound ▶ Handle 1
+                             ◀─Handle 1
+       .order(:created_at)   ─call──▶ Relation #2 (fresh clone)  bound ▶ Handle 2
+                             ◀─Handle 2
+       .limit(10)            ─call──▶ Relation #3 (fresh clone)  bound ▶ Handle 3
+                             ◀─Handle 3
+
+   3 hops ─▶ 3 dispatches ─▶ 3 distinct relations ─▶ 3 Handles
+   all stay live until the invocation ends, then reset together
+```
+
+This is deliberate, not a leak. Handle IDs run to 2³¹ − 1 per invocation and reset between invocations, so even deep chains stay far inside the range. Two consequences are worth keeping in mind: the same host object handed back twice yields two *different* Handles — the guest cannot tell they alias — and every intermediate Handle stays live until the invocation ends, since there is no per-Handle release (B-19).
+
+### Snippets & Entrypoints
 
 `Sandbox#preload` registers named mruby snippets that replay against the fresh `mrb_state` before every invocation; `Sandbox#run(:Target, *args, **kwargs)` dispatches into a top-level `Object` constant defined by those snippets ([`docs/behavior.md`](docs/behavior.md) B-31..B-33).
 

data/ext/kobako/Cargo.toml

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

data/ext/kobako/src/runtime/trap.rs

@@ -76,8 +76,9 @@ fn classify_trap(err: &wasmtime::Error) -> TrapClass {
 /// `"linear memory growth exceeded memory_limit: ..."`). The wasmtime
 /// outer wrapper at `format!("{}", err)` would otherwise surface only
 /// the `"error while executing at wasm backtrace: ..."` framing, which
-/// is operator noise on a cap trap. For `TrapClass::Other` the
-/// wasmtime wrapper IS the diagnostic (real script trap) so it stays.
+/// is operator noise on a cap trap. For `TrapClass::Other` the framing
+/// is kept but the chain's root cause is appended (see
+/// `other_trap_message`) so the real trap reason survives.
 pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
     match classify_trap(&err) {
         TrapClass::Timeout => {
@@ -94,7 +95,24 @@ pub(super) fn call_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError {
                 .unwrap_or_else(|| format!("{}", err));
             memory_limit_err(ruby, msg)
         }
-        TrapClass::Other => trap_err(ruby, format!("{}", err)),
+        TrapClass::Other => trap_err(ruby, other_trap_message(&err)),
+    }
+}
+
+/// Compose the message for a non-cap trap. wasmtime's `Display` surfaces only
+/// the `"error while executing at wasm backtrace: ..."` framing; the actual
+/// trap reason (e.g. `"wasm trap: indirect call type mismatch"`) is the
+/// chain's root cause and would otherwise be dropped, making real guest
+/// faults undiagnosable. Append the root cause unless the framing already
+/// carries it. Pure so it can be exercised from `cargo test` without the
+/// magnus surface.
+fn other_trap_message(err: &wasmtime::Error) -> String {
+    let display = format!("{}", err);
+    let root = err.root_cause().to_string();
+    if display.contains(&root) {
+        display
+    } else {
+        format!("{display}\n\n{root}")
     }
 }
 
@@ -111,7 +129,7 @@ pub(super) fn instantiate_err(ruby: &Ruby, err: wasmtime::Error) -> MagnusError
 
 #[cfg(test)]
 mod tests {
-    use super::{classify_trap, TrapClass};
+    use super::{classify_trap, other_trap_message, TrapClass};
     use crate::runtime::invocation::{MemoryLimitTrap, TimeoutTrap};
 
     #[test]
@@ -131,4 +149,30 @@ mod tests {
         let err = wasmtime::Error::msg("some other wasmtime fault");
         assert_eq!(classify_trap(&err), TrapClass::Other);
     }
+
+    // A guest hard trap reaches the host as a wasmtime error whose Display is
+    // only the backtrace framing, with the trap reason buried as the chain's
+    // root cause. The named-capture regex bug surfaced as exactly this shape.
+    #[test]
+    fn other_trap_message_surfaces_buried_trap_reason() {
+        let err = wasmtime::Error::msg("wasm trap: indirect call type mismatch")
+            .context("error while executing at wasm backtrace:\n  0: 0x1 - <unknown>");
+        let msg = other_trap_message(&err);
+        assert!(
+            msg.contains("indirect call type mismatch"),
+            "a non-cap trap surfaced through Kobako::TrapError must carry the root trap reason, not only the backtrace framing; got: {msg}"
+        );
+        assert!(
+            msg.contains("error while executing"),
+            "a non-cap trap surfaced through Kobako::TrapError must keep the wasm backtrace framing; got: {msg}"
+        );
+    }
+
+    // A flat error (no cause chain) is its own root_cause; appending it would
+    // duplicate the whole message.
+    #[test]
+    fn other_trap_message_does_not_duplicate_a_flat_error() {
+        let err = wasmtime::Error::msg("plain fault");
+        assert_eq!(other_trap_message(&err), "plain fault");
+    }
 }

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

data/rust-toolchain.toml

@@ -0,0 +1,10 @@
+# Pin the Rust toolchain so local builds and CI stay byte-identical.
+# The wasm32-wasip1 crt1-command.o references __wasi_init_tp from 1.96 onward;
+# vendored wasi-sdk 33's libc.a supplies that symbol, so the two move together.
+# Bump this in lockstep with WASI_SDK_VERSION in tasks/support/kobako_vendor.rb.
+# This file is the single source of the channel; the CI workflows read it.
+[toolchain]
+channel = "1.96.0"
+components = ["clippy", "rustfmt"]
+targets = ["wasm32-wasip1"]
+profile = "minimal"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -103,6 +103,7 @@ files:
 - lib/kobako/usage.rb
 - lib/kobako/version.rb
 - release-please-config.json
+- rust-toolchain.toml
 - sig/kobako.rbs
 - sig/kobako/capture.rbs
 - sig/kobako/catalog.rbs