kobako 0.3.0 → 0.5.0

data/lib/kobako/codec/factory.rb

@@ -6,8 +6,8 @@ require "msgpack"
 
 require_relative "error"
 require_relative "utils"
-require_relative "../rpc/handle"
-require_relative "../rpc/fault"
+require_relative "../handle"
+require_relative "../fault"
 
 module Kobako
   module Codec
@@ -89,16 +89,18 @@ module Kobako
       # binary-encoding fallback that msgpack-gem's default unpacker
       # would otherwise apply. The re-tag step lives here because the
       # msgpack ext-type unpacker hands us binary bytes; the assertion
-      # itself is shared with {Decoder} via {Utils.assert_utf8!}.
+      # itself is shared with {Decoder} via {Utils.assert_utf8!}. The
+      # +"Symbol"+ label keeps the error message in Ruby vocabulary
+      # rather than wire-ext-code vocabulary.
       def unpack_symbol(payload)
         name = payload.b.force_encoding(Encoding::UTF_8)
-        Utils.assert_utf8!(name, "ext 0x00 payload")
+        Utils.assert_utf8!(name, "Symbol payload")
         name.to_sym
       end
 
       def register_handle
         @factory.register_type(
-          EXT_HANDLE, RPC::Handle,
+          EXT_HANDLE, Kobako::Handle,
           packer: ->(handle) { [handle.id].pack("N") },
           unpacker: ->(payload) { unpack_handle(payload) }
         )
@@ -106,23 +108,24 @@ module Kobako
 
       def register_fault
         @factory.register_type(
-          EXT_ERRENV, RPC::Fault,
+          EXT_ERRENV, Kobako::Fault,
           packer: ->(fault) { pack_fault(fault) },
           unpacker: ->(payload) { unpack_fault(payload) }
         )
       end
 
-      # Peel off the fixext-4 frame, hand the bytes to +RPC::Handle.new+, and
-      # translate the +ArgumentError+ raised by Handle's invariants into
-      # a wire-layer +InvalidType+ via {Codec::Utils.wire_boundary}.
+      # Peel off the fixext-4 frame, hand the bytes to the
+      # Host-Gem-internal +Kobako::Handle.restore+ factory, and
+      # translate the +ArgumentError+ raised by Handle's invariants
+      # into a wire-layer +InvalidType+ via {Codec::Utils.with_boundary}.
       # The Value Object owns the id-range contract; this method only
       # owns the frame shape.
       def unpack_handle(payload)
         bytes = payload.b
-        raise InvalidType, "ext 0x01 payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
+        raise InvalidType, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
 
         id = bytes.unpack1("N") # : Integer
-        Codec::Utils.wire_boundary { RPC::Handle.new(id) }
+        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
       end
 
       # Encode the inner ext-0x02 map via {Encoder} (not +factory.dump+) so
@@ -133,9 +136,10 @@ module Kobako
         Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
       end
 
-      # Peel the embedded msgpack map and hand it to +RPC::Fault.new+;
-      # translate the value-object's +ArgumentError+ into +InvalidType+
-      # at the wire boundary. Inner decode goes through {Decoder} (not
+      # Peel the embedded msgpack map and hand it to +Kobako::Fault.new+
+      # inside {Decoder.decode}'s block form, so the value-object's
+      # +ArgumentError+ invariants surface as +InvalidType+ through the
+      # decoder boundary. Inner decode goes through {Decoder} (not
       # +factory.load+) so the embedded +str+ payloads flow through the
       # same UTF-8 validation as a top-level decode.
       #
@@ -147,11 +151,10 @@ module Kobako
       # +factory.load+ to "simplify": that path bypasses UTF-8 validation
       # and re-opens the Decoder's special case for Fault (removed in M5).
       def unpack_fault(payload)
-        map = Decoder.decode(payload)
-        raise InvalidType, "ext 0x02 payload must be a map" unless map.is_a?(Hash)
+        Decoder.decode(payload) do |map|
+          raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
 
-        Codec::Utils.wire_boundary do
-          RPC::Fault.new(type: map["type"], message: map["message"], details: map["details"])
+          Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
         end
       end
     end

data/lib/kobako/codec/utils.rb

@@ -1,56 +1,145 @@
 # frozen_string_literal: true
 
 require_relative "error"
+require_relative "../handle"
 
 module Kobako
   module Codec
-    # Wire-codec helpers shared by the host-side encoders and decoders.
-    # The single concern today is UTF-8 assertion at the wire boundary
-    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § str/bin
-    # Encoding Rules and § Ext Types → ext 0x00). Two call sites lean on
-    # this:
+    # Codec helpers shared by the host-side encoders and decoders.
+    # Three concerns live here today:
     #
-    #   - {Decoder} validates +str+ family payloads as it walks the
-    #     decoded value tree.
-    #   - {Factory} validates the +ext 0x00+ Symbol payload after
-    #     re-tagging the binary bytes as UTF-8.
+    #   - UTF-8 assertion at the codec boundary
+    #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
+    #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
+    #     {Decoder} when walking +str+ family payloads and by {Factory}
+    #     when validating the +ext 0x00+ Symbol payload.
+    #   - +ArgumentError+ translation at the codec boundary
+    #     ({with_boundary}) so the public taxonomy stays
+    #     {Kobako::Codec::Error}.
+    #   - Representability predicate ({representable?}) and the symmetric
+    #     host→guest +#run+ argument walk ({deep_wrap}) used by
+    #     +Kobako::Transport::Run#encode+ to route non-representable leaves
+    #     through the Sandbox's +Kobako::Catalog::Handles+
+    #     ({docs/behavior.md B-34}[link:../../../docs/behavior.md]).
     #
-    # Encoding setup (re-tagging binary as UTF-8 when needed) stays at
-    # the caller — only the assertion shape is shared. The helper does
-    # not mutate +string+; it only inspects +String#valid_encoding?+
-    # against +string+'s current encoding tag.
+    # All helpers are pure — they only inspect inputs, never mutate
+    # them — except {deep_wrap}, whose only side effect is allocating
+    # new Handle ids into the supplied table.
     module Utils
       module_function
 
       # Raise {InvalidEncoding} unless +string+'s bytes are valid under
       # its current encoding tag. +label+ is the caller-supplied prefix
-      # for the error message (e.g. +"str payload"+, +"ext 0x00 payload"+).
+      # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
       def assert_utf8!(string, label)
         return if string.valid_encoding?
 
         raise InvalidEncoding, "#{label} is not valid UTF-8"
       end
 
-      # Run +block+ at the wire boundary: every wire Value Object
-      # (Handle / Fault / Request / Response / Panic) raises
-      # +ArgumentError+ when an invariant is violated at construction,
-      # and the wire boundary surfaces those violations to callers as
-      # {InvalidType} so the public taxonomy stays
-      # {Kobako::Codec::Error} and never leaks +ArgumentError+ from the
-      # Ruby standard library.
+      # Run +block+ at the codec boundary: a value object raises
+      # +ArgumentError+ when an invariant is violated at construction, and
+      # this helper surfaces that as {InvalidType} so the public taxonomy
+      # stays {Kobako::Codec::Error} and never leaks +ArgumentError+ from
+      # the Ruby standard library.
       #
-      # Wrap any block that constructs a wire Value Object from decoded
-      # bytes with this helper to keep the five decode sites uniform —
-      # Request / Response in +Kobako::RPC+, Panic map in
-      # +Kobako::Outcome+, and the Handle / Fault ext-type unpackers in
-      # {Factory}. Do not use it for general-purpose validation outside
-      # the wire boundary — host-layer +ArgumentError+ values should
-      # propagate unchanged.
-      def wire_boundary
+      # Most construction sites no longer reach for this directly: a value
+      # object built inside a {Decoder.decode} block has its
+      # +ArgumentError+ mapped to {InvalidType} by the decoder's own
+      # rescue. The lone remaining caller is {Factory#unpack_handle}, which
+      # builds +Handle.restore+ from a raw 4-byte fixext payload without a
+      # {Decoder.decode} call. Do not use it for general-purpose validation
+      # outside the codec boundary — host-layer +ArgumentError+ values
+      # should propagate unchanged.
+      def with_boundary
         yield
       rescue ::ArgumentError => e
         raise InvalidType, e.message
       end
+
+      # Inclusive Integer range the msgpack gem encodes without raising
+      # +RangeError+ at encode time — signed +int 64+ minimum through
+      # unsigned +uint 64+ maximum
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping #3, the +fixint+ / +int 8..64+ / +uint 8..64+ union).
+      # Anchored as a +Range+ so {primitive_type?} stays a single
+      # dispatch line. This is the codec's encode domain — not to
+      # be confused with the Handle id range, which lives on
+      # +Kobako::Handle+ as +MIN_ID+ / +MAX_ID+ (1..2^31 − 1) and
+      # represents a different concept entirely.
+      MSGPACK_INT_RANGE = (-(2**63)..((2**64) - 1))
+
+      # Codec-type predicate
+      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Type
+      # Mapping). Returns +true+ when +value+ belongs to the closed
+      # 12-entry codec type set — +nil+, +TrueClass+, +FalseClass+,
+      # +Integer+ (in the +i64..u64+ value domain), +Float+, +String+,
+      # +Symbol+, +Kobako::Handle+, +Array+ whose every element is itself
+      # representable, or +Hash+ whose every key and value are
+      # representable. Integers outside the codec's signed-64 /
+      # unsigned-64 union are rejected so the predicate agrees with the
+      # msgpack gem's encode-time +RangeError+ behaviour the codec
+      # already surfaces as {UnsupportedType}.
+      def representable?(value)
+        primitive_type?(value) || container_representable?(value)
+      end
+
+      # Deep-walk Array / Hash containers in +value+ and replace every
+      # leaf that fails {representable?} with a +Kobako::Handle+
+      # allocated from +handler+
+      # ({docs/behavior.md B-34}[link:../../../docs/behavior.md]). The
+      # walk only descends through representable container shapes
+      # (Array, Hash) one structural level at a time; a non-representable
+      # leaf is wrapped as-is without inspecting its internal structure.
+      # An existing +Kobako::Handle+ is representable and passes through
+      # unchanged — auto-wrap never re-wraps a Handle.
+      #
+      # +value+ may be any Ruby value; +handler+ must respond to
+      # +#alloc(object) -> Kobako::Handle+ (a host-side
+      # +Kobako::Catalog::Handles+). Returns a structurally equivalent value
+      # whose leaves are either representable or +Kobako::Handle+
+      # tokens.
+      #
+      # The block bodies spell +Utils.deep_wrap+ explicitly rather than
+      # the unqualified +deep_wrap+ because +module_function+ makes the
+      # instance copy of these helpers private; an implicit receiver
+      # inside a block would resolve against the enclosing +self+
+      # (still +Utils+ at definition time, but the qualified form keeps
+      # the dispatch readable when the recursive call sits inside a
+      # Proc captured from elsewhere).
+      def deep_wrap(value, handler)
+        case value
+        when ::Array then value.map { |element| Utils.deep_wrap(element, handler) }
+        when ::Hash  then value.transform_values { |val| Utils.deep_wrap(val, handler) }
+        else
+          representable?(value) ? value : handler.alloc(value)
+        end
+      end
+
+      # Predicate split out of {representable?} for cyclomatic
+      # budget — the closed-set non-container branch. Returns +true+ for
+      # the scalar leaves and an existing Handle. Not part of the
+      # public surface; reach for {representable?} instead.
+      def primitive_type?(value)
+        case value
+        when ::NilClass, ::TrueClass, ::FalseClass, ::Float, ::String, ::Symbol, Kobako::Handle then true
+        when ::Integer then MSGPACK_INT_RANGE.cover?(value)
+        else false
+        end
+      end
+
+      # Predicate split out of {representable?} for cyclomatic
+      # budget — the container branch. Recurses into Array elements and
+      # Hash key+value pairs through the public {representable?}.
+      # Not part of the public surface; reach for {representable?}
+      # instead.
+      def container_representable?(value)
+        case value
+        when ::Array then value.all? { |element| Utils.representable?(element) }
+        when ::Hash  then value.all? { |key, val| Utils.representable?(key) && Utils.representable?(val) }
+        else false
+        end
+      end
     end
   end
 end

data/lib/kobako/codec.rb

@@ -6,9 +6,12 @@ module Kobako
   # Host-side MessagePack codec for the kobako wire contract — the
   # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
   # Two consumers sit on top:
-  # +Kobako::RPC+ pins the RPC framing (Request / Response)
-  # and +Kobako::Outcome+ owns the per-+#run+ outcome envelope (Result
-  # body / Panic map).
+  # +Kobako::Transport+ pins the host↔guest framing (Request / Response /
+  # Run / Yield) and +Kobako::Outcome+ owns the per-+#run+ outcome
+  # envelope (Result body / Panic map). The ext-type leaves this layer
+  # carries — +Kobako::Handle+ (0x01) and +Kobako::Fault+ (0x02) — live at
+  # the kobako root so the codec can register them without depending
+  # upward on Transport.
   #
   # Backed by the official +msgpack+ gem via {Factory}; {Encoder} and
   # {Decoder} are thin wrappers that register the three kobako-specific

data/lib/kobako/errors.rb

@@ -2,29 +2,39 @@
 
 # Top-level Kobako namespace.
 module Kobako
-  # Three-class error taxonomy (docs/behavior.md § Error Scenarios).
+  # Error taxonomy (docs/behavior.md § Error Scenarios).
   #
   # Every `Kobako::Sandbox` invocation (`#eval` or `#run`) either returns a value or raises
-  # exactly one of these three classes. Attribution is decided after the
+  # 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").
   #
-  # Three top-level branches:
+  # Three invocation-outcome branches:
   #
   #   * {TrapError}     — Wasm engine layer (trap, OOM, unreachable, or a
   #                       wire-violation fallback signalling a corrupted
   #                       guest runtime).
   #   * {SandboxError}  — sandbox / wire layer (mruby script error,
   #                       wire-decode failure on an otherwise valid tag,
-  #                       HandleTable exhaustion, output buffer overrun).
-  #   * {ServiceError}  — service / capability layer (a Service RPC that
-  #                       failed and was not rescued inside the script).
+  #                       Catalog::Handles exhaustion, output buffer overrun).
+  #   * {ServiceError}  — service / capability layer (a Service capability
+  #                       call that failed and was not rescued inside the
+  #                       script).
+  #
+  # A fourth branch sits 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). Not an invocation
+  #                       outcome, so it never passes through the two-step
+  #                       attribution decision.
   #
   # Subclasses pinned by docs/behavior.md Error Classes:
   #
-  #   * {HandleTableExhausted} < {SandboxError}    — id cap hit (B-21).
-  #   * {ServiceError::Disconnected} < {ServiceError} — `:disconnected`
-  #                       sentinel hit on the HandleTable (E-14).
+  #   * {ModuleNotBuiltError} < {SetupError} — Guest Binary artifact absent
+  #                       at +wasm_path+ (E-40).
+  #   * {HandlerExhaustedError} < {SandboxError} — Handle id cap hit (B-21).
 
   # Base for all kobako-raised errors so callers that want to ignore the
   # taxonomy can rescue a single class.
@@ -59,6 +69,27 @@ module Kobako
   # 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
+  # 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"
+  # recovery contract does not apply.
+  class SetupError < Error; end
+
+  # 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
+  # that only need "the Sandbox could not be set up" rescue +SetupError+;
+  # those wanting to special-case the unbuilt-artifact state rescue
+  # +ModuleNotBuiltError+ first.
+  class ModuleNotBuiltError < SetupError; end
+
   # Sandbox / wire layer. Raised when the guest ran to completion but
   # execution failed due to a mruby script error, a protocol fault, or a
   # host-side wire decode failure on an otherwise valid outcome tag.
@@ -87,27 +118,13 @@ module Kobako
       @backtrace_lines = backtrace_lines
       @details = details
     end
-
-    # docs/behavior.md Error Classes: ServiceError::Disconnected is raised
-    # when the RPC target Handle resolves to the `:disconnected` sentinel
-    # in the HandleTable (ABA protection rule — id exists but entry was
-    # invalidated). E-14.
-    class Disconnected < ServiceError; end
   end
 
-  # HandleTable lookup-failure error (unknown id passed to #fetch /
-  # #release). A SandboxError subclass: per the wire-layer rule, an
-  # unknown Handle id surfaces as a `type="undefined"` Response.error
-  # envelope inside RpcDispatcher and never reaches the Host App
-  # directly; outside that path (e.g. tests poking the HandleTable
-  # directly), it surfaces as a SandboxError.
-  class HandleTableError < SandboxError; end
-
-  # docs/behavior.md Error Classes: HandleTableExhausted is the canonical
-  # SandboxError subclass for the id-cap-hit path (B-21). Inherits from
-  # HandleTableError so a single `rescue Kobako::HandleTableError` covers
-  # both lookup-failure and cap-exhaustion paths.
-  class HandleTableExhausted < HandleTableError; 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.
+  class HandlerExhaustedError < SandboxError; end
 
   # docs/behavior.md Error Classes: BytecodeError is the SandboxError
   # subclass raised when a `#preload(binary:)` snippet fails structural

data/lib/kobako/fault.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Wire-level value object for an ext-0x02 Exception envelope.
+  #
+  # Top-level shared wire primitive: like +Kobako::Handle+ (ext 0x01),
+  # +Fault+ is a MessagePack ext-type leaf registered by
+  # +Kobako::Codec::Factory+ and rides nested inside other envelopes (a
+  # +Kobako::Transport::Response+ error payload, or another Fault's
+  # +details+). It lives at the kobako root rather than under +Transport+
+  # because the Codec layer must register it, and Codec must not depend
+  # upward on Transport.
+  #
+  # SPEC pins the payload
+  # ({docs/wire-codec.md}[link:../../docs/wire-codec.md] § Ext Types
+  # → ext 0x02) to a msgpack map with exactly three keys:
+  #   * "type"    — one of "runtime", "argument", "undefined"
+  #   * "message" — human-readable string
+  #   * "details" — any wire-legal value, or nil when absent
+  #
+  # This object holds the *encoded* form. Reifying the corresponding Ruby
+  # exception class (RuntimeError, ArgumentError, Kobako::ServiceError, ...)
+  # is the responsibility of the dispatch layer, not the codec.
+  #
+  # Built on the +class X < Data.define(...)+ subclass form so the
+  # class body is fully Steep-visible; ruby/rbs upstream documents
+  # this as the Steep-friendly shape and the +Style/DataInheritance+
+  # cop is disabled on that basis (see +.rubocop.yml+).
+  class Fault < Data.define(:type, :message, :details)
+    VALID_TYPES = %w[runtime argument undefined].freeze
+
+    def initialize(type:, message:, details: nil)
+      raise ArgumentError, "type must be String"    unless type.is_a?(String)
+      raise ArgumentError, "message must be String" unless message.is_a?(String)
+      raise ArgumentError, "type=#{type.inspect} not one of #{VALID_TYPES.inspect}" unless VALID_TYPES.include?(type)
+
+      super
+    end
+  end
+end

data/lib/kobako/handle.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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]).
+  #
+  # 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]
+  # § Ext Types → ext 0x01). ID 0 is reserved as the invalid sentinel;
+  # the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+  #
+  # The constructor is internal to the Host Gem. +Kobako::Handle.new+ is
+  # privatised so Host App code cannot fabricate a Handle from a bare
+  # integer; legitimate Handle instances enter Host App code only as
+  # fields on raised error objects. The Host Gem itself constructs
+  # Handles through {.restore}, which exists at exactly two call
+  # sites: +Kobako::Codec::Factory#unpack_handle+ (wire decode) and
+  # +Kobako::Codec::Utils.deep_wrap+ / +Kobako::Transport::Dispatcher#wrap_as_handle+
+  # (allocator paths). Both live inside +lib/kobako/+ and are not part
+  # of any public surface.
+  #
+  # The mruby counterpart +Kobako::Handle+ lives inside the Wasm guest
+  # under the same canonical name and shares neither code nor instances
+  # with this host-side class.
+  class Handle < Data.define(:id)
+    # Inclusive lower bound on the wire Handle ID. ID 0 is reserved as
+    # the invalid sentinel and is never allocated.
+    MIN_ID = 1
+    # Inclusive upper bound on the wire Handle ID. The cap matches the
+    # u32 signed-positive range so Handle IDs fit in a signed integer
+    # on either side of the wire without re-encoding.
+    MAX_ID = 0x7fff_ffff
+
+    def initialize(id:)
+      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)
+
+      super
+    end
+
+    private_class_method :new
+
+    # Host Gem–internal factory. Allocates the Data instance through
+    # +Class#allocate+ and dispatches +#initialize+ explicitly so the
+    # invariant checks still run, while keeping the public +.new+
+    # privatised against Host App callers.
+    #
+    # Two collaborators call this: the codec when an ext 0x01 frame is
+    # decoded off the wire, and the allocator paths when a host-side
+    # Ruby object is registered into the Sandbox's +Catalog::Handles+. Both
+    # paths live inside +lib/kobako/+ and treat this method as a
+    # package-private constructor.
+    def self.restore(id)
+      allocate.tap { |handle| handle.send(:initialize, id: id) }
+    end
+  end
+end

data/lib/kobako/namespace.rb

@@ -0,0 +1,67 @@
+# 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]).
+  # 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]).
+    NAME_PATTERN = /\A[A-Z]\w*\z/
+
+    attr_reader :name
+
+    # Build a new Namespace. +name+ is an already-validated Namespace
+    # name (must satisfy {NAME_PATTERN}; validation is the caller's
+    # responsibility).
+    def initialize(name)
+      @name = name
+      @members = {} # : Hash[String, untyped]
+    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]).
+    def bind(member, object)
+      member_str = validate_member_name!(member)
+      raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
+
+      @members[member_str] = object
+      self
+    end
+
+    # Member lookup; raises +KeyError+ when no Member is registered
+    # under +member+.
+    def fetch(member)
+      member_str = member.to_s
+      unless @members.key?(member_str)
+        raise KeyError,
+              "no member named #{member_str.inspect} in namespace #{@name.inspect}"
+      end
+
+      @members[member_str]
+    end
+
+    # Structured description for the guest preamble (Frame 1). Returns a
+    # two-element array +[name, member_keys]+ suitable for msgpack encoding.
+    def to_preamble
+      [@name, @members.keys]
+    end
+
+    private
+
+    def validate_member_name!(member)
+      member_str = member.to_s
+      unless NAME_PATTERN.match?(member_str)
+        raise ArgumentError,
+              "MemberName must match #{NAME_PATTERN.inspect} (got #{member.inspect})"
+      end
+
+      member_str
+    end
+  end
+end