kobako 0.9.2 → 0.10.0

data/lib/kobako/catalog/handles.rb

@@ -30,13 +30,6 @@ module Kobako
     #     +0x7fff_ffff+ (2³¹ − 1). Allocation beyond the cap raises
     #     immediately — no silent truncation, no wrap, no ID reuse.
     class Handles
-      # Reflective gadget types that are never minted as a Capability Handle
-      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): wrapping a
-      # +Binding+ / +Method+ / +UnboundMethod+ would hand the guest a callable
-      # proxy onto host reflection (a returned +Binding+ reaches +Binding#eval+).
-      UNWRAPPABLE_TYPES = [Binding, Method, UnboundMethod].freeze
-      private_constant :UNWRAPPABLE_TYPES
-
       # Build a fresh, empty table. +next_id+ is an internal seam that
       # sets the starting value of the monotonic counter (defaults to 1 per
       # B-15); tests pass a value near +Kobako::Handle::MAX_ID+ to exercise
@@ -97,13 +90,16 @@ module Kobako
       private
 
       # Refuse to mint a Capability Handle for a reflective gadget
-      # ({UNWRAPPABLE_TYPES}, B-43). Raising here keeps the rule at the single
-      # mint point, so it holds on both the Service-return (B-14) and the
-      # +#run+ host→guest auto-wrap (B-34) paths.
+      # ({docs/behavior.md B-43}[link:../../../docs/behavior.md]): a +Binding+ /
+      # +Method+ / +UnboundMethod+ would hand the guest a callable proxy onto
+      # host reflection (a returned +Binding+ reaches +Binding#eval+). Raising
+      # here keeps the rule at the single mint point, so it holds on both the
+      # Service-return (B-14) and the +#run+ host→guest auto-wrap (B-34) paths.
       def reject_unwrappable!(object)
-        return unless UNWRAPPABLE_TYPES.any? { |type| object.is_a?(type) }
-
-        raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        case object
+        when Binding, Method, UnboundMethod
+          raise SandboxError, "a #{object.class} cannot cross as a Capability Handle"
+        end
       end
 
       # Guard {#alloc} against issuing an ID past the B-21 cap. Returns +nil+

data/lib/kobako/catalog/namespaces.rb

@@ -37,6 +37,7 @@ module Kobako
         @namespaces = {} # : Hash[String, Kobako::Namespace]
         @handler = handler
         @sealed = false
+        @encoded = nil # : String?
       end
 
       # Declare or retrieve the Namespace named +name+ (idempotent —
@@ -80,14 +81,32 @@ module Kobako
       # Arrays, so none of the kobako ext types actually fire. Structure:
       # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
       # +String+ of msgpack bytes.
+      #
+      # Once sealed, the bytes are computed once and reused for every
+      # subsequent invocation: B-33 seals Service registration (B-07 /
+      # B-08) at the first invocation, so the preamble is exactly the
+      # bindings that existed at that moment — a bind reaching a
+      # +Kobako::Namespace+ after the seal raises +ArgumentError+ (E-45)
+      # and never alters Frame 1.
       def encode
-        Codec::Encoder.encode(@namespaces.values.map(&:to_preamble))
+        return @encoded if @encoded
+
+        bytes = Codec::Encoder.encode(@namespaces.values.map(&:to_preamble)).freeze
+        @encoded = bytes if @sealed
+        bytes
       end
 
-      # Mark the registry as sealed. Called by +Sandbox+ on the first
-      # invocation. After sealing, #define raises ArgumentError. Idempotent.
+      # Mark the registry as sealed and propagate the seal to every
+      # declared +Kobako::Namespace+
+      # ({docs/behavior.md B-33}[link:../../../docs/behavior.md]). Called
+      # by +Sandbox+ on the first invocation. After sealing, #define
+      # raises ArgumentError (E-18) and +Namespace#bind+ raises
+      # ArgumentError (E-45). Idempotent.
       def seal!
+        return self if @sealed
+
         @sealed = true
+        @namespaces.each_value(&:seal!)
         self
       end
 

data/lib/kobako/catalog/snippets.rb

@@ -31,6 +31,7 @@ module Kobako
 
       def initialize
         @entries = [] # : Array[Kobako::Snippet::Source | Kobako::Snippet::Binary]
+        @encoded = nil # : String?
       end
 
       # Serialize the registered snippets to wire bytes. Each entry
@@ -42,8 +43,14 @@ module Kobako
       # carriers — this collection-tier method reads their attributes
       # externally via +entry_payload+ rather than asking each entry to
       # self-encode.
+      #
+      # The bytes are memoized — the table is replayed verbatim on every
+      # invocation after B-33 seals it, so Frame 3 never changes between
+      # encodes; {#register} drops the memo while the table is still open.
       def encode
-        Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) })
+        return @encoded if @encoded
+
+        @encoded = Codec::Encoder.encode(@entries.map { |entry| entry_payload(entry) }).freeze
       end
 
       # Register one preloaded snippet in either of two forms
@@ -68,6 +75,7 @@ module Kobako
       # missing keywords, wrong types, malformed +name+ (E-34), or
       # duplicate +code:+ +name+ (E-33).
       def register(code: nil, name: nil, binary: nil)
+        @encoded = nil
         if binary
           raise ArgumentError, "cannot combine binary: with code: / name:" if code || name
 

data/lib/kobako/codec/decoder.rb

@@ -64,7 +64,11 @@ module Kobako
           case value
           when String then Utils.assert_utf8!(value, "str payload") if value.encoding == Encoding::UTF_8
           when Array  then value.each { |v| validate_utf8!(v) }
-          when Hash   then value.each { |pair| validate_utf8!(pair) }
+          when Hash
+            value.each do |key, val|
+              validate_utf8!(key)
+              validate_utf8!(val)
+            end
           end
         end
       end

data/lib/kobako/errors.rb

@@ -21,7 +21,7 @@ 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
@@ -29,6 +29,9 @@ module Kobako
   #                       ({docs/behavior.md E-40 / E-41}[link:../../docs/behavior.md]).
   #                       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+
+  #                       ({docs/behavior.md E-46}[link:../../docs/behavior.md]).
   #
   # Subclasses pinned by docs/behavior.md Error Classes:
   #
@@ -137,4 +140,11 @@ module Kobako
   # 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 ({docs/behavior.md E-46}[link:../../docs/behavior.md]). No
+  # Sandbox state is touched — retrying succeeds as soon as a holder
+  # returns its Sandbox.
+  class PoolTimeoutError < Error; end
 end

data/lib/kobako/namespace.rb

@@ -18,15 +18,20 @@ 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 ({docs/behavior.md B-11}[link:../../docs/behavior.md]),
+    # or when the owning Sandbox's first invocation has sealed Service
+    # registration ({docs/behavior.md E-45}[link:../../docs/behavior.md]).
     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 +39,15 @@ module Kobako
       self
     end
 
+    # Mark this Namespace as sealed ({docs/behavior.md B-33}[link:../../docs/behavior.md]).
+    # Called by +Kobako::Catalog::Namespaces#seal!+ on the owning
+    # Sandbox's first invocation; afterwards {#bind} raises
+    # +ArgumentError+ (E-45). 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/pool.rb

@@ -0,0 +1,182 @@
+# 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
+  # ({docs/behavior.md B-46..B-48}[link:../../docs/behavior.md]).
+  #
+  # 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 (B-46). +#with+ blocks up
+  # to +checkout_timeout+ seconds when every slot is held (E-46), applies
+  # the +TrapError+ discard-and-recreate contract at checkin (B-47), and
+  # the Pool releases everything with its own reachability — there is no
+  # teardown verb (B-48).
+  class Pool
+    # The +#with+ wait bound applied when +checkout_timeout+ is not given
+    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]).
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS = 5.0
+
+    # Build a Pool of up to +slots+ Sandboxes
+    # ({docs/behavior.md B-46}[link:../../docs/behavior.md]). +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+
+    # ({docs/behavior.md E-47}[link:../../docs/behavior.md]).
+    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 ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
+    # Blocks while every slot is held; raises +Kobako::PoolTimeoutError+
+    # once the wait exceeds +checkout_timeout+
+    # ({docs/behavior.md E-46}[link:../../docs/behavior.md]). 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 (B-47).
+    def checkout
+      acquire.tap(&:reset_invocation_state!)
+    end
+
+    # The idle-first claim loop (B-46): 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 (E-46). 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 (B-46); 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
+
+    # E-47 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 E-39 normalisation
+    # idiom applied to E-47.
+    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

data/lib/kobako/sandbox.rb

@@ -206,6 +206,22 @@ module Kobako
       end
     end
 
+    # Reset all per-invocation observable state to its pre-invocation
+    # sentinels — both per-channel captures
+    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
+    # per-last-invocation usage record
+    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
+    # +#initialize+ (first-time setup) and +#begin_invocation!+
+    # (between-invocation reset) so both paths agree on what
+    # "pre-invocation state" means; +Kobako::Pool+ calls it at checkout
+    # so a pooled Sandbox hands over empty output buffers
+    # ({docs/behavior.md B-47}[link:../../docs/behavior.md]).
+    def reset_invocation_state!
+      @stdout_capture = Capture::EMPTY
+      @stderr_capture = Capture::EMPTY
+      @usage = Usage::EMPTY
+    end
+
     private
 
     # Configure the +Runtime+'s host↔guest dispatch wiring
@@ -237,20 +253,6 @@ module Kobako
       reset_invocation_state!
     end
 
-    # Reset all per-invocation observable state to its pre-invocation
-    # sentinels — both per-channel captures
-    # ({docs/behavior.md B-05}[link:../../docs/behavior.md]) and the
-    # per-last-invocation usage record
-    # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Shared by
-    # +#initialize+ (first-time setup) and +#begin_invocation!+
-    # (between-invocation reset) so both paths agree on what
-    # "pre-invocation state" means.
-    def reset_invocation_state!
-      @stdout_capture = Capture::EMPTY
-      @stderr_capture = Capture::EMPTY
-      @usage = Usage::EMPTY
-    end
-
     # Read the per-last-invocation +wall_time+ and +memory_peak+ from
     # the ext and wrap them as a +Kobako::Usage+ value object
     # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Runs in

data/lib/kobako/version.rb

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

data/lib/kobako.rb

@@ -15,3 +15,4 @@ require_relative "kobako/catalog"
 require_relative "kobako/runtime"
 require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"
+require_relative "kobako/pool"

data/release-please-config.json

@@ -73,13 +73,28 @@
           "path": "/wasm/kobako-regexp/README.md"
         }
       ]
+    },
+    "wasm/kobako-baker": {
+      "component": "kobako-baker",
+      "release-type": "rust",
+      "extra-files": [
+        {
+          "type": "toml",
+          "path": "/wasm/kobako-baker/Cargo.lock",
+          "jsonpath": "$.package[?(@.name=='kobako-baker')].version"
+        },
+        {
+          "type": "generic",
+          "path": "/wasm/kobako-baker/README.md"
+        }
+      ]
     }
   },
   "plugins": [
     {
       "type": "linked-versions",
       "groupName": "kobako guest crates",
-      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp"]
+      "components": ["kobako-core", "kobako-rs", "kobako-io", "kobako-regexp", "kobako-baker"]
     }
   ],
   "extra-files": [

data/sig/kobako/catalog/handles.rbs

@@ -1,8 +1,6 @@
 module Kobako
   module Catalog
     class Handles
-      UNWRAPPABLE_TYPES: Array[Module]
-
       def initialize: (?next_id: Integer) -> void
 
       def alloc: (untyped object) -> Kobako::Handle

data/sig/kobako/errors.rbs

@@ -52,4 +52,7 @@ module Kobako
 
   class BytecodeError < SandboxError
   end
+
+  class PoolTimeoutError < Error
+  end
 end

data/sig/kobako/namespace.rbs

@@ -8,6 +8,8 @@ module Kobako
 
     def bind: (Symbol | String member, untyped object) -> self
 
+    def seal!: () -> self
+
     def fetch: (Symbol | String member) -> untyped
 
     def to_preamble: () -> [String, Array[String]]

data/sig/kobako/pool.rbs

@@ -0,0 +1,44 @@
+module Kobako
+  class Pool
+    DEFAULT_CHECKOUT_TIMEOUT_SECONDS: Float
+
+    @slots: Integer
+    @checkout_timeout: Float?
+    @sandbox_options: Hash[Symbol, untyped]
+    @setup: ^(Kobako::Sandbox) -> void | nil
+    @idle: Array[Kobako::Sandbox]
+    @constructed: Integer
+    @mutex: Thread::Mutex
+    @slot_freed: Thread::ConditionVariable
+
+    def initialize: (
+      slots: Integer,
+      ?checkout_timeout: (Float | Integer)?,
+      **untyped sandbox_options
+    ) ?{ (Kobako::Sandbox) -> void } -> void
+
+    def with: [T] () { (Kobako::Sandbox) -> T } -> T
+
+    private
+
+    def checkout: () -> Kobako::Sandbox
+
+    def acquire: () -> Kobako::Sandbox
+
+    def claim_or_wait: (Float? deadline) -> [Symbol, Kobako::Sandbox?]
+
+    def await_slot!: (Float? deadline) -> void
+
+    def construct_slot: () -> Kobako::Sandbox
+
+    def checkin: (Kobako::Sandbox sandbox) -> void
+
+    def release_capacity!: () -> void
+
+    def monotonic_now: () -> Float
+
+    def validate_slots!: (untyped slots) -> void
+
+    def normalize_checkout_timeout: ((Float | Integer)? checkout_timeout) -> Float?
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -38,12 +38,12 @@ module Kobako
 
     def eval: (String code) -> untyped
 
+    def reset_invocation_state!: () -> void
+
     private
 
     def install_dispatch_proc!: () -> void
 
-    def reset_invocation_state!: () -> void
-
     def begin_invocation!: () -> void
 
     def read_usage!: () -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.9.2
+  version: 0.10.0
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -65,6 +65,7 @@ files:
 - ext/kobako/src/runtime/dispatch.rs
 - ext/kobako/src/runtime/exports.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
@@ -86,6 +87,7 @@ files:
 - lib/kobako/namespace.rb
 - lib/kobako/outcome.rb
 - lib/kobako/outcome/panic.rb
+- lib/kobako/pool.rb
 - lib/kobako/runtime.rb
 - lib/kobako/sandbox.rb
 - lib/kobako/sandbox_options.rb
@@ -123,6 +125,7 @@ files:
 - sig/kobako/namespace.rbs
 - sig/kobako/outcome.rbs
 - sig/kobako/outcome/panic.rbs
+- sig/kobako/pool.rbs
 - sig/kobako/runtime.rbs
 - sig/kobako/sandbox.rbs
 - sig/kobako/sandbox_options.rbs