kobako 0.12.1 → 0.12.2

data/release-please-config.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "release-type": "ruby",
-  "last-release-sha": "5694da60b08931ea260e13025689b8d8c47d767a",
+  "last-release-sha": "98509af508988f708bf0d7a76a718bb0428a177e",
   "packages": {
     ".": {
       "component": "kobako",
@@ -103,13 +103,58 @@
           "path": "/wasm/kobako-baker/README.md"
         }
       ]
+    },
+    "crates/kobako-runtime": {
+      "component": "kobako-runtime",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/crates/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-runtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-runtime')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/crates/kobako-runtime/README.md"
+        }
+      ]
+    },
+    "crates/kobako-wasmtime": {
+      "component": "kobako-wasmtime",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/crates/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-wasmtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-wasmtime')].version"
+        },
+        {
+          "type": "toml",
+          "path": "/crates/kobako-wasmtime/Cargo.toml",
+          "jsonpath": "$.dependencies['kobako-runtime'].version"
+        },
+        {
+          "type": "generic",
+          "path": "/crates/kobako-wasmtime/README.md"
+        }
+      ]
     }
   },
   "plugins": [
     {
       "type": "linked-versions",
-      "groupName": "kobako guest crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker"]
+      "groupName": "kobako crates",
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-json", "kobako-regexp", "kobako-baker", "kobako-runtime", "kobako-wasmtime"]
     }
   ],
   "extra-files": [

data/sig/kobako/codec/factory.rbs

@@ -8,6 +8,8 @@ module Kobako
       EXT_SYMBOL: Integer
       EXT_HANDLE: Integer
       EXT_ERRENV: Integer
+      MAX_EXT_DEPTH: Integer
+      EXT_DEPTH_KEY: Symbol
 
       def dump: (untyped value) -> String
       def load: (String bytes) -> untyped
@@ -26,6 +28,7 @@ module Kobako
       def unpack_handle: (String payload) -> Kobako::Handle
       def pack_fault: (Kobako::Fault fault) -> String
       def unpack_fault: (String payload) -> Kobako::Fault
+      def within_ext_frame: [T] (singleton(Kobako::Codec::Error) over_limit) { () -> T } -> T
     end
   end
 end

data/sig/kobako/errors.rbs

@@ -17,7 +17,7 @@ module Kobako
   class ModuleNotBuiltError < SetupError
   end
 
-  class SandboxError < Error
+  module StructuredError : Error
     attr_reader origin: String?
     attr_reader klass: String?
     attr_reader backtrace_lines: Array[String]?
@@ -32,22 +32,15 @@ module Kobako
     ) -> void
   end
 
-  class ServiceError < Error
-    attr_reader origin: String?
-    attr_reader klass: String?
-    attr_reader backtrace_lines: Array[String]?
-    attr_reader details: untyped
+  class SandboxError < Error
+    include StructuredError
+  end
 
-    def initialize: (
-      String message,
-      ?origin: String?,
-      ?klass: String?,
-      ?backtrace_lines: Array[String]?,
-      ?details: untyped
-    ) -> void
+  class ServiceError < Error
+    include StructuredError
   end
 
-  class HandlerExhaustedError < SandboxError
+  class HandleExhaustedError < SandboxError
   end
 
   class BytecodeError < SandboxError

data/sig/kobako/runtime.rbs

@@ -10,14 +10,19 @@ module Kobako
       Integer? stderr_limit_bytes
     ) -> Runtime
 
-    def on_dispatch=: (^(String) -> String dispatch_proc) -> void
-
-    def yield_to_active_invocation: (String args_bytes) -> String
+    def on_dispatch=: (^(String, Kobako::Transport::_GuestYielder) -> String dispatch_proc) -> void
 
     def eval: (String preamble, String source, String snippets) -> Kobako::Snapshot
 
     def run: (String preamble, String snippets, String envelope) -> Kobako::Snapshot
 
     def usage: () -> [Float, Integer]
+
+    # Frame-scoped guest re-entry handle the ext hands the dispatch Proc as
+    # its second argument; stands in as the +String -> String+ callable the
+    # host +Transport::Yielder+ invokes for a block yield.
+    class GuestYielder
+      def call: (String args_bytes) -> String
+    end
   end
 end

data/sig/kobako/sandbox.rbs

@@ -8,8 +8,8 @@ module Kobako
     # Forwarded to @options via Forwardable#def_delegators.
     def timeout: () -> Float?
     def memory_limit: () -> Integer?
-    def stdout_limit: () -> Integer
-    def stderr_limit: () -> Integer
+    def stdout_limit: () -> Integer?
+    def stderr_limit: () -> Integer?
 
     def initialize: (
       ?wasm_path: String?,

data/sig/kobako/sandbox_options.rbs

@@ -6,8 +6,8 @@ module Kobako
 
     attr_reader timeout: Float?
     attr_reader memory_limit: Integer?
-    attr_reader stdout_limit: Integer
-    attr_reader stderr_limit: Integer
+    attr_reader stdout_limit: Integer?
+    attr_reader stderr_limit: Integer?
 
     def self.new: (
       ?timeout: (Float | Integer)?,
@@ -28,5 +28,7 @@ module Kobako
     def normalize_timeout: ((Float | Integer)? timeout) -> Float?
 
     def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+
+    def normalize_output_limit: (Integer? limit, String name) -> Integer?
   end
 end

data/sig/kobako/snapshot.rbs

@@ -5,11 +5,8 @@ module Kobako
     def stdout_truncated: () -> bool
     def stderr_bytes: () -> String
     def stderr_truncated: () -> bool
-    def wall_time: () -> Float
-    def memory_peak: () -> Integer
 
     def stdout: () -> Kobako::Capture
     def stderr: () -> Kobako::Capture
-    def usage: () -> Kobako::Usage
   end
 end

data/sig/kobako/transport/dispatcher.rbs

@@ -12,7 +12,7 @@ module Kobako
 
       CALLABLE_ALLOW: Array[Symbol]
 
-      def self?.dispatch: (String request_bytes, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler, ^(String) -> String yield_to_guest) -> String
+      def self?.dispatch: (String request_bytes, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler, Kobako::Transport::_GuestYielder yield_to_guest) -> String
 
       def self?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Catalog::Handles handler) -> [Array[untyped], Hash[Symbol, untyped]]
 

data/sig/kobako/transport/run.rbs

@@ -17,9 +17,9 @@ module Kobako
 
       def normalize_entrypoint: (Symbol | String target) -> Symbol
 
-      def validate_args!: (Array[untyped] args) -> Array[untyped]
+      def validate_args!: (Array[untyped] args) -> void
 
-      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> Hash[Symbol, untyped]
+      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> void
 
       def forged_handle_message: (String slot) -> String
     end

data/sig/kobako/transport/yielder.rbs

@@ -1,12 +1,12 @@
 module Kobako
   module Transport
     class Yielder
-      @yield_to_guest: ^(String) -> String
+      @yield_to_guest: Kobako::Transport::_GuestYielder
       @break_tag: Symbol
       @handler: Kobako::Catalog::Handles
       @active: bool
 
-      def initialize: (^(String) -> String yield_to_guest, Symbol break_tag, Kobako::Catalog::Handles handler) -> void
+      def initialize: (Kobako::Transport::_GuestYielder yield_to_guest, Symbol break_tag, Kobako::Catalog::Handles handler) -> void
 
       def yield: (*untyped args) -> untyped
 

data/sig/kobako/transport.rbs

@@ -1,4 +1,12 @@
 module Kobako
   module Transport
+    # The guest re-entry callable a dispatch hands to a Yielder: invoked
+    # with the encoded yield args, it returns the encoded YieldResponse.
+    # The ext's Kobako::Runtime::GuestYielder is the production conformer;
+    # modelled structurally so the Transport layer needs no upward
+    # dependency on Runtime.
+    interface _GuestYielder
+      def call: (String) -> String
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.2
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -54,23 +54,38 @@ files:
 - LICENSE
 - README.md
 - SECURITY.md
+- crates/kobako-runtime/CHANGELOG.md
+- crates/kobako-runtime/Cargo.toml
+- crates/kobako-runtime/README.md
+- crates/kobako-runtime/src/dispatch.rs
+- crates/kobako-runtime/src/error.rs
+- crates/kobako-runtime/src/lib.rs
+- crates/kobako-runtime/src/runtime.rs
+- crates/kobako-runtime/src/snapshot.rs
+- crates/kobako-runtime/src/yielder.rs
+- crates/kobako-wasmtime/CHANGELOG.md
+- crates/kobako-wasmtime/Cargo.toml
+- crates/kobako-wasmtime/README.md
+- crates/kobako-wasmtime/src/ambient.rs
+- crates/kobako-wasmtime/src/cache.rs
+- crates/kobako-wasmtime/src/capture.rs
+- crates/kobako-wasmtime/src/config.rs
+- crates/kobako-wasmtime/src/dispatch.rs
+- crates/kobako-wasmtime/src/driver.rs
+- crates/kobako-wasmtime/src/exports.rs
+- crates/kobako-wasmtime/src/frames.rs
+- crates/kobako-wasmtime/src/guest_mem.rs
+- crates/kobako-wasmtime/src/instance_pre.rs
+- crates/kobako-wasmtime/src/invocation.rs
+- crates/kobako-wasmtime/src/lib.rs
+- crates/kobako-wasmtime/src/trap.rs
 - data/kobako.wasm
 - ext/kobako/Cargo.toml
 - ext/kobako/extconf.rb
 - ext/kobako/src/lib.rs
 - ext/kobako/src/runtime.rs
-- ext/kobako/src/runtime/ambient.rs
-- ext/kobako/src/runtime/cache.rs
-- ext/kobako/src/runtime/capture.rs
-- ext/kobako/src/runtime/config.rs
-- ext/kobako/src/runtime/dispatch.rs
+- ext/kobako/src/runtime/bridge.rs
 - ext/kobako/src/runtime/errors.rs
-- ext/kobako/src/runtime/exports.rs
-- ext/kobako/src/runtime/frames.rs
-- ext/kobako/src/runtime/guest_mem.rs
-- ext/kobako/src/runtime/instance_pre.rs
-- ext/kobako/src/runtime/invocation.rs
-- ext/kobako/src/runtime/trap.rs
 - ext/kobako/src/snapshot.rs
 - lib/kobako.rb
 - lib/kobako/capture.rb

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

@@ -1,25 +0,0 @@
-//! Per-`Runtime` execution configuration.
-//!
-//! The wall-clock and per-channel capture caps a `Kobako::Sandbox`
-//! forwards into `Runtime::from_path`. A plain value carrier owned by the
-//! `Runtime` — distinct from the process-wide engine/module `super::cache`
-//! (which is shared across every Sandbox) and from the per-invocation
-//! `super::invocation::Invocation` (which the wasm engine mutates from
-//! inside a run). These caps are read only by `Runtime` methods between
-//! runs, so they live here.
-
-use std::time::Duration;
-
-/// Wall-clock and output caps for one `Runtime`. `None` on any field
-/// disables that cap.
-pub(crate) struct Config {
-    /// Wall-clock cap for one guest `#eval` / `#run`. Stamped into a
-    /// per-run `Instant` deadline by `Runtime::prime_caps`.
-    pub(crate) timeout: Option<Duration>,
-    /// Byte cap for guest stdout capture.
-    /// Sizes the per-run `MemoryOutputPipe` and computes the truncation
-    /// flag in `Runtime::build_snapshot`.
-    pub(crate) stdout_limit_bytes: Option<usize>,
-    /// Byte cap for guest stderr capture. Mirror of `stdout_limit_bytes`.
-    pub(crate) stderr_limit_bytes: Option<usize>,
-}

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

@@ -1,211 +0,0 @@
-//! Host-side dispatch for the `__kobako_dispatch` import.
-//!
-//! 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 Request bytes from guest linear memory.
-//!   2. Invokes the Ruby-side dispatch Proc bound via
-//!      `Runtime#on_dispatch=` and recovers Response bytes.
-//!   3. Allocates a guest buffer via `__kobako_alloc(len)` invoked
-//!      through `Caller::get_export`.
-//!   4. Writes the Response 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 Proc before any invocation, so reaching the
-//! dispatcher with no Proc bound is itself a wire-layer fault; the
-//! guest maps a 0 return to a trap. Failures during normal dispatch
-//! surface as Response.err envelopes 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 `ext/` that deliberately prints
-//! through `eprintln!`. The host normally surfaces faults by
-//! raising a `MagnusError` back into Ruby; the dispatcher contract
-//! is the exception — it must return a packed `i64` to the guest
-//! and cannot raise, 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 Proc bound vs. the Proc
-//! 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 Proc, the Proc 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.
-
-use core::cell::Cell;
-use core::ptr::NonNull;
-
-use magnus::value::{Opaque, ReprValue};
-use magnus::{Error as MagnusError, RString, Ruby, Value};
-use wasmtime::Caller;
-
-use super::invocation::Invocation;
-
-// ============================================================
-// Active-caller pointer for the per-thread Invocation slot
-// (SPEC.md Single-Invocation Slot).
-// ============================================================
-//
-// `Runtime#yield_to_active_invocation` (whose body is the
-// `__kobako_yield_to_block` guest export) runs synchronously inside a
-// Ruby Service callback that itself was invoked from inside this
-// dispatcher — at that moment we are several stack frames deep in
-// `try_handle`, with the original `&mut Caller<'_, Invocation>` parked
-// unused on the Rust stack while Ruby code is running. The yield path
-// needs the same Caller to call the guest export, but the Rust borrow
-// type is non-`'static` so it cannot be stored on the `Invocation`
-// struct directly (the `&mut Caller` outlives no struct field — its
-// lifetime ends when `handle` returns to wasmtime).
-//
-// The pointer is therefore erased to `NonNull<()>` and parked in a
-// per-thread slot — the materialised form of the SPEC.md
-// "Single-Invocation Slot" invariant. The single-threaded wasm
-// execution per Sandbox plus the LIFO re-entry shape of nested
-// dispatch frames ensures no aliasing across threads or across
-// frames; the recovery invariant lives at `current_caller`. The
-// pointer is set on entry to `handle` and restored to the outer
-// frame's value on every exit through a drop guard.
-
-thread_local! {
-    static ACTIVE_CALLER: Cell<Option<NonNull<()>>> = const { Cell::new(None) };
-}
-
-/// RAII guard that saves the previous `ACTIVE_CALLER` value on
-/// installation and restores it on drop. Nested `__kobako_dispatch`
-/// frames stack within one Invocation — the inner frame's `set`
-/// swaps in its own pointer while remembering the outer's; drop
-/// restores the outer so its continuation (e.g. iterating over another
-/// guest block) still finds a live caller.
-pub(crate) struct CallerGuard {
-    previous: Option<NonNull<()>>,
-}
-
-impl CallerGuard {
-    fn set(ptr: NonNull<()>) -> Self {
-        let previous = ACTIVE_CALLER.with(|c| c.replace(Some(ptr)));
-        Self { previous }
-    }
-}
-
-impl Drop for CallerGuard {
-    fn drop(&mut self) {
-        ACTIVE_CALLER.with(|c| c.set(self.previous));
-    }
-}
-
-/// Recover the active `&mut Caller<'_, Invocation>` set by the
-/// enclosing `handle` frame. Returns `None` when no dispatch frame is
-/// active on this thread.
-///
-/// # Safety
-///
-/// The returned reference aliases the original `&mut Caller` borrow
-/// held on the Rust stack inside `handle`'s enclosing frame. The
-/// original borrow is logically inactive while Ruby code is running
-/// (it is parked on the stack between `invoke_on_dispatch` and the
-/// eventual `funcall` return), and the SPEC.md Single-Invocation Slot
-/// invariant (one Invocation per OS thread for the duration of any
-/// invocation) guarantees no other Rust frame can observe it. Callers
-/// must not retain the returned `&mut` past the synchronous Ruby
-/// callback that requested it — i.e. only use it inside one short
-/// magnus method body and let the borrow end before the method returns.
-pub(crate) fn current_caller<'a>() -> Option<&'a mut Caller<'a, Invocation>> {
-    let raw: NonNull<()> = ACTIVE_CALLER.with(|c| c.get())?;
-    // SAFETY: see item doc.
-    Some(unsafe { &mut *raw.as_ptr().cast::<Caller<'a, 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 Proc is contracted never to
-/// raise (it folds Service exceptions into Response.err envelopes),
-/// 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 {
-    // SAFETY: lifetime erased to `NonNull<()>` per the module's
-    // Invocation-slot doc. The pointer is restored by `_caller_guard`
-    // before this function returns, and only
-    // `Runtime#yield_to_active_invocation` (running inside a Ruby
-    // callback we are about to invoke) reads it through `current_caller`.
-    let ptr: NonNull<()> = NonNull::from(&mut *caller).cast();
-    let _caller_guard = CallerGuard::set(ptr);
-
-    match try_handle(caller, req_ptr, req_len) {
-        Ok(packed) => packed,
-        Err(reason) => {
-            eprintln!("[kobako-dispatch] {}", reason);
-            0
-        }
-    }
-}
-
-/// Result-returning core of `handle`. Pulled out so each early
-/// failure path carries a diagnostic string instead of an opaque 0.
-fn try_handle(
-    caller: &mut Caller<'_, Invocation>,
-    req_ptr: i32,
-    req_len: i32,
-) -> Result<i64, &'static str> {
-    let req_bytes = super::guest_mem::read(caller, req_ptr, req_len)?;
-
-    // `Kobako::Sandbox` always installs the dispatch Proc before
-    // invoking the runtime, so reaching this branch indicates a misuse
-    // rather than a normal control path.
-    let on_dispatch = caller
-        .data()
-        .on_dispatch()
-        .ok_or("a Sandbox callback fired outside an active Sandbox#run — please report this as a kobako bug")?;
-
-    let resp_bytes = invoke_on_dispatch(on_dispatch, &req_bytes).map_err(|_| {
-        "a Sandbox callback raised an exception instead of returning a fault — please report this as a kobako bug"
-    })?;
-
-    write_response(caller, &resp_bytes)
-}
-
-/// Invoke the Ruby-side dispatch `Proc` with the request bytes and return
-/// the encoded Response bytes. The Proc is contracted to fold every
-/// dispatch failure into a `Response.err` envelope (see
-/// `Kobako::Transport::Dispatcher.dispatch`), so reaching the error
-/// branch is itself a wire-layer fault rather than a normal control path.
-fn invoke_on_dispatch(
-    on_dispatch: Opaque<Value>,
-    req_bytes: &[u8],
-) -> Result<Vec<u8>, MagnusError> {
-    // The wasmtime callback runs on the same Ruby thread that called the
-    // active Sandbox invocation (#eval or #run) — the invariant SPEC
-    // Implementation Standards Architecture pins for the host gem — so
-    // `Ruby::get()` is always available here. Panicking with `expect`
-    // localises the violation rather than letting a nonsense error
-    // propagate.
-    let ruby = Ruby::get().expect("Ruby handle unavailable in __kobako_dispatch");
-    let proc_value: Value = ruby.get_inner(on_dispatch);
-    let req_str = ruby.str_from_slice(req_bytes);
-    let resp: RString = proc_value.funcall("call", (req_str,))?;
-    Ok(super::rstring_to_vec(resp))
-}
-
-/// Allocate a guest-side buffer and copy the response bytes into it via
-/// `super::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 = super::guest_mem::alloc_and_write(caller, bytes)?;
-    Ok(((ptr as i64) << 32) | (bytes.len() as i64))
-}