kobako 0.9.2-aarch64-linux → 0.11.0-aarch64-linux

data/lib/kobako/errors.rb

@@ -2,12 +2,12 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Error taxonomy (docs/behavior.md § Error Scenarios).
+  # Error taxonomy.
   #
   # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
   # exactly one of three invocation-outcome classes. Attribution is decided after the
-  # guest binary returns control to the host (docs/behavior.md
-  # "Step 1 — Wasm trap" then "Step 2 — Outcome envelope tag").
+  # guest binary returns control to the host: first the Wasm-trap layer, then
+  # the outcome-envelope tag.
   #
   # Three invocation-outcome branches:
   #
@@ -21,20 +21,21 @@ module Kobako
   #                       call that failed and was not rescued inside the
   #                       script).
   #
-  # A fourth branch sits outside the invocation taxonomy:
+  # Two further branches sit outside the invocation taxonomy:
   #
   #   * {SetupError}    — construction layer. Raised by `Kobako::Sandbox.new`
   #                       when the wasm runtime cannot be built from the
-  #                       configured +wasm_path+ before any invocation runs
-  #                       ({docs/behavior.md E-40 / E-41}[link:../../docs/behavior.md]).
+  #                       configured +wasm_path+ before any invocation runs.
   #                       Not an invocation outcome, so it never passes
   #                       through the two-step attribution decision.
+  #   * {PoolTimeoutError} — pool checkout layer. Raised by `Kobako::Pool#with`
+  #                       when the checkout wait exceeds +checkout_timeout+.
   #
-  # Subclasses pinned by docs/behavior.md Error Classes:
+  # Named subclasses:
   #
   #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
-  #                       at +wasm_path+ (E-40).
-  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit (B-21).
+  #                       at +wasm_path+.
+  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit.
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -43,13 +44,13 @@ module Kobako
   # Wasm engine layer. Raised when the Wasm execution engine crashed
   # (trap, OOM, unreachable) or when the wire layer detected a structural
   # violation that signals a corrupted guest execution environment
-  # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
+  # (zero-length OUTCOME_BUFFER, unknown outcome tag).
   #
-  # Two named subclasses cover the configured per-invocation caps from B-01:
+  # Two named subclasses cover the configured per-invocation caps:
   #
-  #   * {TimeoutError}     — wall-clock +timeout+ exceeded (E-19).
+  #   * {TimeoutError}     — wall-clock +timeout+ exceeded.
   #   * {MemoryLimitError} — guest +memory.grow+ would exceed
-  #                          +memory_limit+ (E-20).
+  #                          +memory_limit+.
   #
   # Host Apps that only care about "guest is unrecoverable, discard the
   # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
@@ -57,24 +58,23 @@ module Kobako
   # first.
   class TrapError < Error; end
 
-  # Wall-clock timeout cap exhausted. {docs/behavior.md E-19}[link:../../docs/behavior.md]:
-  # the absolute deadline +entry_time + timeout+ passed and the next guest
-  # wasm safepoint trapped. The Sandbox is unrecoverable after this point;
-  # discard and recreate before another execution.
+  # Wall-clock timeout cap exhausted: the absolute deadline
+  # +entry_time + timeout+ passed and the next guest wasm safepoint
+  # trapped. The Sandbox is unrecoverable after this point; discard and
+  # recreate before another execution.
   class TimeoutError < TrapError; end
 
-  # Linear-memory cap exhausted. {docs/behavior.md E-20}[link:../../docs/behavior.md]:
-  # a guest +memory.grow+ would have pushed linear memory past the
-  # configured +memory_limit+. The Sandbox is unrecoverable after this
-  # point; discard and recreate before another execution.
+  # Linear-memory cap exhausted: a guest +memory.grow+ would have pushed
+  # linear memory past the configured +memory_limit+. The Sandbox is
+  # unrecoverable after this point; discard and recreate before another
+  # execution.
   class MemoryLimitError < TrapError; end
 
   # Construction-layer error raised by +Kobako::Sandbox.new+ /
   # +Kobako::Runtime.from_path+ when the wasm runtime cannot be built
   # from the configured +wasm_path+ before any invocation runs —
   # an unreadable artifact, bytes that are not a valid Wasm module, or
-  # engine / linker / instantiation setup failure
-  # ({docs/behavior.md E-41}[link:../../docs/behavior.md]). Construction
+  # engine / linker / instantiation setup failure. Construction
   # is not an invocation, so +SetupError+ sits beside the invocation
   # taxonomy under +Kobako::Error+ rather than under +TrapError+: no
   # Sandbox is produced, so the +TrapError+ "discard and recreate"
@@ -83,8 +83,7 @@ module Kobako
 
   # The named +SetupError+ subclass for the common, actionable case:
   # the Guest Binary artifact is absent at +wasm_path+ — the pre-build
-  # state on a fresh clone before +bundle exec rake compile+
-  # ({docs/behavior.md E-40}[link:../../docs/behavior.md]). Host Apps
+  # state on a fresh clone before +bundle exec rake compile+. Host Apps
   # that only need "the Sandbox could not be set up" rescue +SetupError+;
   # those wanting to special-case the unbuilt-artifact state rescue
   # +ModuleNotBuiltError+ first.
@@ -120,21 +119,26 @@ module Kobako
     end
   end
 
-  # docs/behavior.md Error Classes: HandlerExhaustedError is the canonical
-  # SandboxError subclass for the id-cap-hit path (B-21). Raised when the
-  # per-invocation Handle ID counter in Catalog::Handles reaches
-  # +0x7fff_ffff+ (2³¹ − 1) and further allocation would exceed the cap.
+  # HandlerExhaustedError is the canonical SandboxError subclass for the
+  # id-cap-hit path. Raised when the per-invocation Handle ID counter in
+  # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
+  # allocation would exceed the cap.
   class HandlerExhaustedError < SandboxError; end
 
-  # docs/behavior.md Error Classes: BytecodeError is the SandboxError
-  # subclass raised when a `#preload(binary:)` snippet fails structural
-  # validation during the first invocation's snippet replay against a
-  # fresh `mrb_state` (E-37 RITE version mismatch, E-38 corrupt body).
-  # Bytecode that loads cleanly and then raises at top level is E-36
-  # and surfaces as plain `SandboxError` with the natural mruby class
-  # preserved. Inherits from SandboxError so a single
+  # BytecodeError is the SandboxError subclass raised when a
+  # `#preload(binary:)` snippet fails structural validation during the
+  # first invocation's snippet replay against a fresh `mrb_state` (RITE
+  # version mismatch or corrupt body). Bytecode that loads cleanly and
+  # then raises at top level surfaces as plain `SandboxError` with the
+  # natural mruby class preserved. Inherits from SandboxError so a single
   # `rescue Kobako::SandboxError` covers both source and bytecode
   # snippet failures while callers wanting bytecode-specific handling
   # can `rescue Kobako::BytecodeError` directly.
   class BytecodeError < SandboxError; end
+
+  # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
+  # wait exceeded the configured +checkout_timeout+ while every slot was
+  # held. No Sandbox state is touched — retrying succeeds as soon as a holder
+  # returns its Sandbox.
+  class PoolTimeoutError < Error; end
 end

data/lib/kobako/handle.rb

@@ -3,9 +3,8 @@
 module Kobako
   # Wire-level value object for an ext-0x01 Capability Handle, used in both
   # directions across the Sandbox boundary: as a Service method's return
-  # value (guest→host return path; {docs/behavior.md B-14}[link:../../docs/behavior.md])
-  # and as a +#run+ argument auto-wrapped by the host
-  # ({docs/behavior.md B-34}[link:../../docs/behavior.md]).
+  # value (guest→host return path) and as a +#run+ argument auto-wrapped
+  # by the host.
   #
   # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
   # payload ({docs/wire-codec.md}[link:../../docs/wire-codec.md]

data/lib/kobako/namespace.rb

@@ -1,13 +1,11 @@
 # frozen_string_literal: true
 
 module Kobako
-  # A named grouping of Members for one Sandbox
-  # ({docs/behavior.md B-07..B-11}[link:../../docs/behavior.md]).
+  # A named grouping of Members for one Sandbox.
   # Returned by +Sandbox#define+. Each instance owns a flat name→object
   # table of Members; member binding is validated against {NAME_PATTERN}.
   class Namespace
-    # Ruby constant-name pattern shared by Namespace and Member names
-    # ({docs/behavior.md B-07/B-08 Notes}[link:../../docs/behavior.md]).
+    # Ruby constant-name pattern shared by Namespace and Member names.
     NAME_PATTERN = /\A[A-Z]\w*\z/
 
     attr_reader :name
@@ -18,15 +16,19 @@ module Kobako
     def initialize(name)
       @name = name
       @members = {} # : Hash[String, untyped]
+      @sealed = false
     end
 
     # Bind +object+ under +member+ inside this Namespace. +member+ is a
     # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
     # object that responds to the methods guest code will invoke. Returns
     # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
-    # match the constant pattern, or a Member of the same name is already
-    # bound ({docs/behavior.md B-11}[link:../../docs/behavior.md]).
+    # match the constant pattern, when a Member of the same name is
+    # already bound, or when the owning Sandbox's first invocation has
+    # sealed Service registration.
     def bind(member, object)
+      raise ArgumentError, "cannot bind after first Sandbox invocation" if @sealed
+
       member_str = validate_member_name!(member)
       raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
 
@@ -34,6 +36,15 @@ module Kobako
       self
     end
 
+    # Mark this Namespace as sealed. Called by
+    # +Kobako::Catalog::Namespaces#seal!+ on the owning Sandbox's first
+    # invocation; afterwards {#bind} raises +ArgumentError+. Idempotent;
+    # returns +self+.
+    def seal!
+      @sealed = true
+      self
+    end
+
     # Member lookup; raises +KeyError+ when no Member is registered
     # under +member+.
     def fetch(member)

data/lib/kobako/outcome.rb

@@ -7,8 +7,7 @@ module Kobako
   # Host-facing boundary for the OUTCOME_BUFFER produced by
   # +__kobako_eval+. Takes raw outcome bytes — a one-byte tag followed by
   # the msgpack-encoded body — and maps them to either the unwrapped
-  # mruby return value or a raised three-layer
-  # ({docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]) exception.
+  # mruby return value or a raised three-layer exception.
   #
   # Self-contained: this module owns the wire framing (tag bytes,
   # body decoding), and the +Panic+ wire record lives at
@@ -17,11 +16,11 @@ module Kobako
   # nothing in +Transport+ participates.
   #
   #   * tag 0x01, decode OK                 → return decoded value
-  #   * tag 0x01, decode fails              → SandboxError (E-09)
-  #   * tag 0x02, origin="service"          → ServiceError (E-13)
-  #   * tag 0x02, origin="sandbox"/missing  → SandboxError (E-04..E-07)
-  #   * tag 0x02, decode fails              → SandboxError (E-08)
-  #   * unknown tag                         → TrapError    (E-03)
+  #   * tag 0x01, decode fails              → SandboxError
+  #   * tag 0x02, origin="service"          → ServiceError
+  #   * tag 0x02, origin="sandbox"/missing  → SandboxError
+  #   * tag 0x02, decode fails              → SandboxError
+  #   * unknown tag                         → TrapError
   module Outcome
     # First byte of the OUTCOME_BUFFER for the success branch — body is
     # the bare msgpack encoding of the returned value
@@ -71,7 +70,7 @@ module Kobako
       [tag, body]
     end
 
-    # Decode failure on the success tag is a SandboxError (E-09): the
+    # Decode failure on the success tag is a SandboxError: the
     # framing was fine, but the carried value is unrepresentable. The
     # specific codec fault is stashed in +details+ rather
     # than spliced into the message — callers cannot act on the inner
@@ -86,7 +85,7 @@ module Kobako
       )
     end
 
-    # Decode failure on the panic tag is a SandboxError (E-08). Either
+    # Decode failure on the panic tag is a SandboxError. Either
     # path raises — on success the decoded Panic is mapped to its three-
     # layer exception via +build_panic_error+ and raised; on wire-decode
     # failure the rescue path raises the wire-violation +SandboxError+.
@@ -130,13 +129,12 @@ module Kobako
       )
     end
 
-    # {docs/behavior.md Error Scenarios}[link:../../docs/behavior.md]: map
-    # the panic +class+ field to the matching Ruby exception subclass so
-    # callers can rescue specific failure paths. +origin="service"+ →
+    # Map the panic +class+ field to the matching Ruby exception subclass
+    # so callers can rescue specific failure paths. +origin="service"+ →
     # +ServiceError+; +origin="sandbox"+ plus
     # +class="Kobako::BytecodeError"+ selects the +BytecodeError+
-    # subclass (E-37 / E-38). Everything else falls back to the base
-    # class for the origin.
+    # subclass. Everything else falls back to the base class for the
+    # origin.
     def panic_target_class(panic)
       case panic.origin
       when Panic::ORIGIN_SERVICE

data/lib/kobako/pool.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "sandbox"
+
+module Kobako
+  # Kobako::Pool — a bounded set of warm, identically set-up Sandboxes
+  # handed out one exclusive holder at a time.
+  #
+  # Construction forwards every +Kobako::Sandbox.new+ keyword verbatim
+  # and holds the optional block as the per-Sandbox setup hook; a
+  # checkout prefers an idle Sandbox and constructs a new one only when
+  # none is idle and fewer than +slots+ exist. +#with+ blocks up
+  # to +checkout_timeout+ seconds when every slot is held, applies
+  # the +TrapError+ discard-and-recreate contract at checkin, and
+  # the Pool releases everything with its own reachability — there is no
+  # teardown verb.
+  class Pool
+    # The +#with+ wait bound applied when +checkout_timeout+ is not given.
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS = 5.0
+
+    # Build a Pool of up to +slots+ Sandboxes. +slots+ is
+    # a positive Integer; +checkout_timeout+ bounds the +#with+ wait in
+    # seconds (+nil+ waits indefinitely); every other keyword is
+    # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
+    # runs exactly once per constructed Sandbox — it is the setup window
+    # for +#define+ / +#preload+ before that Sandbox's first checkout.
+    # No Sandbox is constructed here. Raises +ArgumentError+ for an
+    # invalid +slots+ / +checkout_timeout+.
+    def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
+      validate_slots!(slots)
+      @slots = slots
+      @checkout_timeout = normalize_checkout_timeout(checkout_timeout)
+      @sandbox_options = sandbox_options
+      @setup = setup
+      @idle = [] # : Array[Kobako::Sandbox]
+      @constructed = 0
+      @mutex = Mutex.new
+      @slot_freed = ConditionVariable.new
+    end
+
+    # Yield one exclusively-held Sandbox to the block and return the
+    # block's value. Blocks while every slot is held; raises
+    # +Kobako::PoolTimeoutError+ once the wait exceeds +checkout_timeout+.
+    # The Sandbox returns to the pool at block exit — unless the block raised
+    # +Kobako::TrapError+, in which case the unrecoverable Sandbox is
+    # discarded and its slot refills by a fresh construction on next
+    # demand.
+    def with
+      sandbox = checkout
+      begin
+        yield sandbox
+      rescue TrapError
+        release_capacity!
+        sandbox = nil
+        raise
+      ensure
+        checkin(sandbox) if sandbox
+      end
+    end
+
+    private
+
+    # Acquire a Sandbox and hand it over in pre-invocation state — empty
+    # output buffers and truncation predicates false.
+    def checkout
+      acquire.tap(&:reset_invocation_state!)
+    end
+
+    # The idle-first claim loop: an idle Sandbox wins, unclaimed
+    # capacity constructs, and a full pool waits for a checkin.
+    def acquire
+      timeout = @checkout_timeout
+      deadline = timeout && (monotonic_now + timeout)
+      loop do
+        action, sandbox = claim_or_wait(deadline)
+        return sandbox if action == :idle && sandbox
+        return construct_slot if action == :build
+      end
+    end
+
+    # Single locked decision point for one claim attempt. Waiting
+    # happens inside the lock (so a checkin can wake it); construction
+    # happens outside (so a slow setup block never holds the lock) —
+    # capacity is reserved here and released by +construct_slot+ on
+    # failure.
+    def claim_or_wait(deadline)
+      @mutex.synchronize do
+        return [:idle, @idle.pop] unless @idle.empty?
+
+        if @constructed < @slots
+          @constructed += 1
+          return [:build, nil]
+        end
+
+        await_slot!(deadline)
+        [:retry, nil]
+      end
+    end
+
+    # Wait for a checkin or freed capacity; raises
+    # +Kobako::PoolTimeoutError+ once +deadline+ has passed. Must
+    # run while holding +@mutex+.
+    def await_slot!(deadline)
+      remaining = deadline && (deadline - monotonic_now)
+      if remaining && remaining <= 0
+        raise PoolTimeoutError,
+              "no Sandbox returned within #{@checkout_timeout}s: all #{@slots} slots are held"
+      end
+
+      @slot_freed.wait(@mutex, remaining)
+    end
+
+    # Construct and set up one pooled Sandbox against the capacity
+    # reserved by +claim_or_wait+. Construction and setup-block errors
+    # propagate to the checkout caller unchanged; the reserved
+    # capacity is released so a later checkout can retry.
+    def construct_slot
+      done = false
+      sandbox = Sandbox.new(**@sandbox_options)
+      @setup&.call(sandbox)
+      done = true
+      sandbox
+    ensure
+      release_capacity! unless done
+    end
+
+    # Return a Sandbox to the idle list and wake one waiting checkout.
+    def checkin(sandbox)
+      @mutex.synchronize do
+        @idle.push(sandbox)
+        @slot_freed.signal
+      end
+    end
+
+    # Give back reserved-but-unfilled capacity — a failed construction or
+    # a discarded Sandbox — and wake one waiting checkout to claim it.
+    def release_capacity!
+      @mutex.synchronize do
+        @constructed -= 1
+        @slot_freed.signal
+      end
+    end
+
+    # The wait deadline runs on the monotonic clock so a wall-clock jump
+    # cannot stretch or cut the checkout wait.
+    def monotonic_now
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # Pre-flight for +slots+ — no coercion, a positive Integer is
+    # the only accepted shape.
+    def validate_slots!(slots)
+      return if slots.is_a?(Integer) && slots.positive?
+
+      raise ArgumentError, "slots must be a positive Integer, got #{slots.inspect}"
+    end
+
+    # Coerce +checkout_timeout+ into the Float seconds the wait loop
+    # consumes, or +nil+ to wait indefinitely — the same normalisation
+    # idiom +SandboxOptions+ applies to +timeout+.
+    def normalize_checkout_timeout(checkout_timeout)
+      return nil if checkout_timeout.nil?
+      unless checkout_timeout.is_a?(Numeric)
+        raise ArgumentError, "checkout_timeout must be Numeric or nil, got #{checkout_timeout.inspect}"
+      end
+
+      seconds = checkout_timeout.to_f
+      unless seconds.positive? && seconds.finite?
+        raise ArgumentError, "checkout_timeout must be > 0 and finite (got #{checkout_timeout})"
+      end
+
+      seconds
+    end
+  end
+end