kobako 0.27.0 → 0.28.0

data/lib/kobako/extension.rb

@@ -1,48 +1,32 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Kobako::Extension — a guest idiom paired with an optional host backend,
-  # installed on a Sandbox via +Sandbox#install+. It composes the existing
-  # +#preload+ (the guest +source+) and +#bind+ (the +backend+) verbs into
-  # one setup unit, so guest code sees a native-style constant whose pure
-  # methods run in-guest and whose privileged methods dispatch to the
-  # backend.
+  # Guest source paired with an optional host backend, installed with
+  # Sandbox#install: the guest sees one constant whose pure methods run in the
+  # guest and whose privileged ones call the backend. Any object answering the
+  # same four readers installs the same way.
   #
-  # The four readers form the contract +#install+ duck-types on:
-  #
-  #   * +name+ — a Symbol matching +/\A[A-Z]\w*\z/+, the preloaded snippet's
-  #     canonical backtrace name and the +depends_on+ match key. Independent
-  #     of any bound path.
-  #   * +source+ — the mruby idiom as a String; always present, since an
-  #     Extension always carries a guest idiom. A host object with no idiom
-  #     is bound with +#bind+ directly.
-  #   * +backend+ — an +Extension::Backend+ or +nil+ for a pure-guest
-  #     Extension.
-  #   * +depends_on+ — Symbol names of Extensions that must also be
-  #     installed, checked for presence at the first invocation.
-  #
-  # +Kobako::Extension+ is the bundled value type; any object exposing the
-  # four readers is equally valid, so a Host App or gem may supply its own.
+  # [+name+]        A constant-form Symbol: the snippet's backtrace name, and
+  #                 what another Extension's +depends_on+ names.
+  # [+source+]      The mruby source, a String. A host object with no source
+  #                 is bound with Sandbox#bind instead.
+  # [+backend+]     A Backend, or +nil+ for an Extension that runs entirely in
+  #                 the guest.
+  # [+depends_on+]  Names of Extensions that must also be installed, checked
+  #                 at the first invocation.
   class Extension < Data.define(:name, :source, :backend, :depends_on)
-    # Kobako::Extension::Backend — the host attachment of an Extension,
-    # pairing +path+ (the constant path the backend binds at, single-segment
-    # +"File"+ or nested +"MyApp::Store"+, spelling the guest constant the
-    # idiom routes to) with the source of the bound object, declared by
-    # explicit keyword:
+    # The host object an Extension's constant at +path+ calls, such as
+    # <tt>"MyApp::Store"</tt>, given by keyword:
     #
-    #   * +object:+ — a static object, fixed for the Sandbox's life.
-    #   * +provider:+ — a no-argument callable invoked once per invocation to
-    #     yield that invocation's object, so a fresh object backs the path
-    #     every invocation. A provider that raises propagates its exception to
-    #     the invocation caller and leaves the guest unrun; the next
-    #     invocation resolves it afresh.
-    #   * neither — a fillable, defaulting to +Kobako::Unresolved+ until the
-    #     host supplies the invocation's object.
+    # [+object:+]   One object for the Sandbox's life.
+    # [+provider:+] A callable taking no arguments, called once per invocation
+    #               for that invocation's object. If it raises, the exception
+    #               reaches the caller and the guest does not run.
+    # [neither]     A fillable Service, supplied per invocation through
+    #               Context#bind.
     #
-    # The kind is chosen by keyword, never inferred from whether the value is
-    # callable, so a static object that is itself callable is expressed
-    # directly with +object:+. Giving both +object:+ and +provider:+ raises
-    # +ArgumentError+.
+    # The keyword decides the kind, so a callable object meant as itself is
+    # given as +object:+. Giving both raises ArgumentError.
     class Backend < Data.define(:path, :object, :provider)
       def initialize(path:, object: nil, provider: nil)
         if !object.nil? && !provider.nil?
@@ -54,8 +38,7 @@ module Kobako
       end
     end
 
-    # +backend+ and +depends_on+ default to absent so the common
-    # pure-idiom and single-backend shapes stay terse.
+    # +backend+ defaults to none, and +depends_on+ to no other Extension.
     def initialize(name:, source:, backend: nil, depends_on: [])
       super
     end

data/lib/kobako/handle.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
 module Kobako
-  # A Capability Handle as it crosses the wire (ext 0x01, laid out in
-  # {docs/wire-codec.md}[link:../../docs/wire-codec.md]), in either
-  # direction. Host App code cannot construct one: +.new+ is private and
-  # +#with+ removed, so no Handle is ever made from a caller-chosen id.
-  # The guest's +Kobako::Handle+ shares only the name.
+  # A guest-held reference to a host object, named by id. Host code cannot
+  # construct one, so no Handle is ever made from a caller-chosen id.
   class Handle < Data.define(:id)
-    # ID 0 is the invalid sentinel and is never allocated.
+    # The smallest id; 0 never names a Handle.
     MIN_ID = 1
-    # The positive half of a signed 32-bit integer, so an id fits either
-    # side of the wire unchanged.
+    # The largest id, the positive half of a signed 32-bit integer; an
+    # invocation needing more raises HandleExhaustedError.
     MAX_ID = 0x7fff_ffff
 
-    def initialize(id:)
+    def initialize(id:) # :nodoc:
       raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
       raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
 
@@ -23,9 +20,7 @@ module Kobako
     private_class_method :new
     undef_method :with
 
-    # The Host Gem's own constructor, for the wire decoder and the Handle
-    # allocator; it runs the same id checks +.new+ would.
-    def self.restore(id)
+    def self.restore(id) # :nodoc:
       allocate.tap { |handle| handle.send(:initialize, id: id) }
     end
   end

data/lib/kobako/outcome.rb

@@ -4,15 +4,7 @@ require_relative "codec"
 require_relative "transport/error"
 
 module Kobako
-  # Host-facing boundary for the invocation outcome the native side split
-  # off the core envelope. Takes the arm it named plus the fields that arm
-  # carries, and settles the invocation the way a host does: return the
-  # value, or raise the exception the failure attributes to.
-  #
-  # This is the two-step attribution decision. The wire framing belongs to
-  # the native side; the payload codec at +Kobako::Codec+ decodes only
-  # the one arm that carries a value.
-  module Outcome
+  module Outcome # :nodoc:
     # The two +origin+ values a Panic attributes with.
     ORIGIN_SANDBOX = "sandbox"
     ORIGIN_SERVICE = "service"
@@ -24,91 +16,70 @@ module Kobako
     SUBCLASSES = {
       "Kobako::BytecodeError" => BytecodeError,
       "Kobako::UndefinedEntrypointError" => UndefinedEntrypointError,
+      "Kobako::UnsupportedFlagError" => UnsupportedFlagError,
       "Kobako::Transport::Error" => Kobako::Transport::Error,
       "Kobako::NoServiceError" => NoServiceError,
       "Kobako::ServiceArgumentError" => ServiceArgumentError
     }.freeze
+    private_constant :ORIGIN_SANDBOX, :ORIGIN_SERVICE, :SUBCLASSES
 
-    module_function
-
-    # Settle one invocation. +kind+ names the arm, +payload+ is the
-    # codec-encoded value the +:ok+ arm carries, and +panic+ carries
-    # the Panic's fields +[origin, class, message, backtrace, available]+ —
-    # present on the panic arm and absent on every other, which is what
-    # tells the failure that has a record to attribute from apart from the
-    # two that do not. +entrypoint+ is the name this invocation asked for,
-    # which the host knows and the wire therefore never carries.
-    def reify(kind, payload, panic, entrypoint: nil)
-      return decode_value(payload) if kind == :ok
+    # +panic+ is present only on the panic arm, which is what tells it from
+    # the ok arm's +payload+. +entrypoint+ is known to the host and never
+    # carried by the wire.
+    def self.reify(payload, panic, entrypoint: nil)
+      return decode_value(payload) unless panic
 
-      raise panic ? panic_error(panic, entrypoint) : trap_error(kind)
+      raise panic_error(panic, entrypoint)
     end
 
-    # Map a Panic's fields onto the three-layer taxonomy. The fields land
-    # on the exception verbatim — it carries the record rather than a
-    # translation of one.
-    def panic_error(panic, entrypoint)
-      origin, klass, message, backtrace, available = panic
-      selected = error_class(origin, klass)
-      attribution = { origin: origin, klass: klass, backtrace_lines: backtrace }
-      return selected.new(message, **attribution) unless selected == UndefinedEntrypointError
+    # +reify+ is the whole seam: one call settles one invocation, matching
+    # the single entry point the Rust frontend's twin exposes. Everything
+    # else here is how that decision is reached.
+    class << self
+      private
 
-      UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
-    end
+      # The fields land on the exception verbatim — it carries the record
+      # rather than a translation of one.
+      def panic_error(panic, entrypoint)
+        origin, klass, message, backtrace, available = panic
+        selected = error_class(origin, klass)
+        attribution = { origin: origin, klass: klass, backtrace_lines: backtrace }
+        return selected.new(message, **attribution) unless selected == UndefinedEntrypointError
 
-    # +origin+ picks the branch, and the guest-written class name may
-    # narrow within it so callers can rescue one path specifically. A name
-    # naming a class outside the branch its origin chose is ignored rather
-    # than honoured: what a guest calls its exception must not move the
-    # failure to a layer the attribution did not put it in.
-    def error_class(origin, klass)
-      base = origin == ORIGIN_SERVICE ? ServiceError : SandboxError
-      selected = SUBCLASSES.fetch(klass, base)
-      return base unless selected <= base
+        UndefinedEntrypointError.new(message, name: entrypoint, available: available.map(&:to_sym), **attribution)
+      end
 
-      selected
-    end
+      # +origin+ picks the branch, and the guest-written class name may
+      # narrow within it so callers can rescue one path specifically. A name
+      # naming a class outside the branch its origin chose is ignored rather
+      # than honoured: what a guest calls its exception must not move the
+      # failure to a layer the attribution did not put it in.
+      def error_class(origin, klass)
+        base = origin == ORIGIN_SERVICE ? ServiceError : SandboxError
+        selected = SUBCLASSES.fetch(klass, base)
+        return base unless selected <= base
 
-    # An arm the host cannot settle: the guest wrote nothing, or wrote
-    # bytes the envelope cannot frame. Either leaves nothing to attribute
-    # to, so both walk the trap path; only the absent-versus-present
-    # distinction selects the message.
-    def trap_error(kind)
-      return TrapError.new("Sandbox exited without producing a result") if kind == :absent
+        selected
+      end
 
-      TrapError.new(
-        "Sandbox produced an unrecognised result; the runtime is corrupted, " \
-        "discard this Sandbox before another invocation"
-      )
-    end
+      # A decode fault means the framing was fine but the carried value is
+      # unrepresentable.
+      def decode_value(payload)
+        Kobako::Codec::Decoder.decode(payload)
+      rescue Kobako::Codec::Error => e
+        raise wire_error("Sandbox produced an invalid result value", diagnostic: e.message)
+      end
 
-    # The ok arm's value — the one position a payload codec still
-    # owns on this path. A decode fault means the framing was fine but the
-    # carried value is unrepresentable.
-    def decode_value(payload)
-      Kobako::Codec::Decoder.decode(payload)
-    rescue Kobako::Codec::Error => e
-      raise wire_error("Sandbox produced an invalid result value", diagnostic: e.message)
+      # No guest class stands behind a result kobako cannot decode, so
+      # +klass+ names the host class raised.
+      def wire_error(message, diagnostic: nil)
+        Kobako::Transport::Error.new(
+          message,
+          origin: ORIGIN_SANDBOX,
+          klass: "Kobako::Transport::Error",
+          diagnostic: diagnostic
+        )
+      end
     end
-
-    # Lift a wire violation the host detected to the real
-    # +Kobako::Transport::Error+ class so callers can +rescue+ it
-    # specifically instead of pattern-matching on +error.klass+. The
-    # +klass+ field is still populated so existing operator-side tooling
-    # that greps on the string continues to work.
-    def wire_error(message, diagnostic: nil)
-      Kobako::Transport::Error.new(
-        message,
-        origin: ORIGIN_SANDBOX,
-        klass: "Kobako::Transport::Error",
-        diagnostic: diagnostic
-      )
-    end
-
-    # +reify+ is the whole seam: one call settles one invocation, matching
-    # the single entry point the Rust frontend's twin exposes. Everything
-    # else here is how that decision is reached.
-    private_class_method :panic_error, :error_class, :trap_error, :decode_value, :wire_error
-    private_constant :ORIGIN_SANDBOX, :ORIGIN_SERVICE, :SUBCLASSES
   end
 end

data/lib/kobako/payload/arguments.rb

@@ -4,19 +4,7 @@ require_relative "../codec"
 
 module Kobako
   module Payload
-    # The invocation arguments a Call or a Run carries: a 2-element
-    # msgpack array, +args+ then +kwargs+. Both elements are always
-    # present, so field positions stay stable when either is empty.
-    #
-    # The positional-versus-keyword split lives here rather than in the
-    # core envelope because it is Ruby's call semantics, not the wire's.
-    # SPEC pins +kwargs+ keys to Symbols; the invariant is enforced at
-    # construction so the value object is the single source of truth.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form so the class
-    # body is fully Steep-visible; see +.rubocop.yml+ for the
-    # rationale.
-    class Arguments < Data.define(:args, :kwargs)
+    class Arguments < Data.define(:args, :kwargs) # :nodoc:
       def initialize(args: [], kwargs: {})
         raise ArgumentError, "payload args must be Array" unless args.is_a?(Array)
 
@@ -30,9 +18,6 @@ module Kobako
         Codec::Encoder.encode([args, kwargs])
       end
 
-      # Decode +bytes+ into an Arguments. Raises +Codec::InvalidTypeError+ when
-      # the payload is not the expected 2-element msgpack array, or when the
-      # construction invariants reject the decoded fields.
       def self.decode(bytes)
         Codec::Decoder.decode(bytes) do |frame|
           unless frame.is_a?(Array) && frame.length == 2

data/lib/kobako/payload.rb

@@ -3,17 +3,9 @@
 require_relative "payload/arguments"
 
 module Kobako
-  # The payload shapes that ride inside a core envelope's opaque payload
-  # field. The envelope routes a message and the native side decodes it;
-  # this layer decides what the resolved method receives, and the byte-level
-  # encoding of that shape belongs to +Kobako::Codec+ beneath it.
-  #
-  # Keeping the two apart is what lets an endpoint with its own schema
-  # replace this layer and keep the envelope, so nothing here may reach for
-  # a routing field.
-  #
-  # +Kobako::Payload::Arguments+ is the wire-symmetric peer of
-  # +kobako_codec::payload::Arguments+.
-  module Payload
+  # What the resolved method receives, kept apart from the envelope so an
+  # endpoint with its own schema can replace it; nothing here reads a
+  # routing field.
+  module Payload # :nodoc:
   end
 end

data/lib/kobako/pool.rb

@@ -4,29 +4,21 @@ 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.
+  # A bounded set of warm, identically set-up Sandboxes, handed out to one
+  # holder at a time. Every Sandbox it builds is kept: an invocation leaves
+  # nothing behind, whatever ended it.
   class Pool
-    # The +#with+ wait bound applied when +checkout_timeout+ is not given.
+    # The default +checkout_timeout+: 5 seconds.
     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 +#bind+ / +#preload+ before that Sandbox's first checkout.
-    # No Sandbox is constructed here. Raises +ArgumentError+ for an
-    # invalid +slots+ / +checkout_timeout+.
+    # Build a Pool of up to +slots+ Sandboxes, built on first demand with the
+    # other keywords as Sandbox.new takes them. +checkout_timeout+ bounds how
+    # many seconds #with waits, and +nil+ waits indefinitely. The block, if
+    # given, sets up each Sandbox once, as with Sandbox#bind and
+    # Sandbox#preload.
+    #
+    # Raises ArgumentError when +slots+ is not a positive Integer or
+    # +checkout_timeout+ is not a positive finite number.
     def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
       validate_slots!(slots)
       @slots = slots
@@ -40,29 +32,20 @@ module Kobako
     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.
+    # block's value; the Sandbox returns to the pool however the block
+    # exits. Raises PoolTimeoutError once every slot has stayed held past
+    # +checkout_timeout+.
     def with
       sandbox = acquire
       begin
         yield sandbox
-      rescue TrapError
-        release_capacity!
-        sandbox = nil
-        raise
       ensure
-        checkin(sandbox) if sandbox
+        checkin(sandbox)
       end
     end
 
     private
 
-    # 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)
@@ -73,11 +56,10 @@ module Kobako
       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.
+    # 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?
@@ -92,9 +74,7 @@ module Kobako
       end
     end
 
-    # Wait for a checkin or freed capacity; raises
-    # +Kobako::PoolTimeoutError+ once +deadline+ has passed. Must
-    # run while holding +@mutex+.
+    # Must run while holding +@mutex+.
     def await_slot!(deadline)
       remaining = deadline && (deadline - monotonic_now)
       if remaining && remaining <= 0
@@ -105,10 +85,8 @@ module Kobako
       @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.
+    # A failed construction releases its reserved capacity so a later
+    # checkout can retry.
     def construct_slot
       done = false
       sandbox = Sandbox.new(**@sandbox_options)
@@ -119,7 +97,6 @@ module Kobako
       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)
@@ -127,8 +104,6 @@ module Kobako
       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
@@ -142,17 +117,12 @@ module Kobako
       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)

data/lib/kobako/runtime.rb

@@ -1,27 +1,13 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Host-side wasmtime runtime, surfaced as a Ruby class by the native ext
-  # (see ext/kobako/src/runtime.rs). The +Kobako::Runtime+ class wraps the
-  # wasmtime engine + compiled module + Store; it is the only Ruby-visible
-  # wasmtime type and the foundational binding layer for +Kobako::Sandbox+.
-  #
-  # This file reopens the magnus-defined class only to add the pure-Ruby
-  # +.default_path+ helper. Every other method (+#from_path+ singleton,
-  # +#eval+ / +#run+, capture and usage readers) is registered from Rust
-  # at ext load time.
-  class Runtime
-    # Absolute path to the gem-bundled +data/kobako.wasm+ artifact. Computed
-    # from this file's location so it works for both +bundle exec+ (running
-    # from the repo) and an installed gem (running from the gem dir).
-    #
-    # Returns a String regardless of whether the file currently exists —
-    # call sites that need the file to be present should pass this through
-    # +Kobako::Runtime.from_path+, which raises
-    # +Kobako::ModuleNotBuiltError+ with a clear remediation message.
-    # Raises +Kobako::SetupError+ if +__dir__+ is unavailable so that
-    # +rescue Kobako::SetupError+ around +Kobako::Sandbox.new+ catches every
-    # construction-layer failure uniformly, including this path-resolution one.
+  # The native wasmtime runtime, defined by the ext; this file adds only the
+  # default Guest Binary path.
+  class Runtime # :nodoc:
+    # The path is answered whether or not the file exists; from_path is
+    # where a missing artifact is refused. A missing +__dir__+ raises
+    # SetupError so one rescue around Sandbox.new covers every construction
+    # failure.
     def self.default_path
       dir = __dir__ or raise Kobako::SetupError, "Kobako::Runtime.default_path requires __dir__"
       File.expand_path("../../data/kobako.wasm", dir)