kobako 0.14.0 → 0.15.0

data/sig/kobako/transport.rbs

@@ -10,10 +10,10 @@ module Kobako
     end
 
     # The Service registry a dispatch resolves constant-path targets
-    # against. The Sandbox's Kobako::Catalog::Namespaces is the
+    # against. The Sandbox's Kobako::Catalog::Services is the
     # production conformer; modelled structurally so the Transport
     # layer needs no upward dependency on Catalog.
-    interface _NamespaceRegistry
+    interface _ServiceRegistry
       def lookup: (String target) -> untyped
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -92,19 +92,19 @@ files:
 - lib/kobako/capture.rb
 - lib/kobako/catalog.rb
 - lib/kobako/catalog/handles.rb
-- lib/kobako/catalog/namespaces.rb
+- lib/kobako/catalog/services.rb
 - lib/kobako/catalog/snippets.rb
 - lib/kobako/codec.rb
 - lib/kobako/codec/decoder.rb
 - lib/kobako/codec/encoder.rb
 - lib/kobako/codec/error.rb
-- lib/kobako/codec/factory.rb
+- lib/kobako/codec/ext_types.rb
 - lib/kobako/codec/handle_walk.rb
+- lib/kobako/codec/state.rb
 - lib/kobako/codec/utils.rb
 - lib/kobako/errors.rb
 - lib/kobako/fault.rb
 - lib/kobako/handle.rb
-- lib/kobako/namespace.rb
 - lib/kobako/outcome.rb
 - lib/kobako/outcome/panic.rb
 - lib/kobako/pool.rb
@@ -130,19 +130,19 @@ files:
 - sig/kobako/capture.rbs
 - sig/kobako/catalog.rbs
 - sig/kobako/catalog/handles.rbs
-- sig/kobako/catalog/namespaces.rbs
+- sig/kobako/catalog/services.rbs
 - sig/kobako/catalog/snippets.rbs
 - sig/kobako/codec.rbs
 - sig/kobako/codec/decoder.rbs
 - sig/kobako/codec/encoder.rbs
 - sig/kobako/codec/error.rbs
-- sig/kobako/codec/factory.rbs
+- sig/kobako/codec/ext_types.rbs
 - sig/kobako/codec/handle_walk.rbs
+- sig/kobako/codec/state.rbs
 - sig/kobako/codec/utils.rbs
 - sig/kobako/errors.rbs
 - sig/kobako/fault.rbs
 - sig/kobako/handle.rbs
-- sig/kobako/namespace.rbs
 - sig/kobako/outcome.rbs
 - sig/kobako/outcome/panic.rbs
 - sig/kobako/pool.rbs

data/lib/kobako/catalog/namespaces.rb

@@ -1,115 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "handles"
-require_relative "../codec"
-require_relative "../errors"
-require_relative "../namespace"
-
-module Kobako
-  module Catalog
-    # Kobako::Catalog::Namespaces — per-Sandbox registry of
-    # +Kobako::Namespace+ entities. Holds the Namespace / Member bindings
-    # and the preamble emitted on Frame 1.
-    #
-    # Public API:
-    #
-    #   namespaces = Kobako::Catalog::Namespaces.new
-    #   namespace = namespaces.define(:MyService)  # => Kobako::Namespace
-    #   namespace.bind(:KV, kv_object)             # => namespace (chainable)
-    #   namespaces.encode                          # => msgpack bytes for Frame 1
-    #   namespaces.lookup("MyService::KV")         # => kv_object
-    #
-    # Namespaces live at +Kobako::Namespace+. Per-dispatch routing is
-    # +Kobako::Transport::Dispatcher+'s responsibility — the Dispatcher
-    # receives this registry and the +Catalog::Handles+ as arguments from
-    # the +Runtime#on_dispatch+ Proc that +Kobako::Sandbox#initialize+
-    # installs. The registry holds an injected +Catalog::Handles+ reference so
-    # dispatch target resolution and host→guest auto-wrap share the same
-    # Sandbox-owned allocator.
-    class Namespaces
-      # Build a fresh registry. +handler+ is an internal seam that injects
-      # a pre-configured +Catalog::Handles+; tests pass one whose +next_id+
-      # is pinned near +MAX_ID+ to exercise the cap-exhaustion path
-      # without 2³¹ allocations. Production callers leave it at the default.
-      def initialize(handler: Catalog::Handles.new)
-        @namespaces = {} # : Hash[String, Kobako::Namespace]
-        @handler = handler
-        @sealed = false
-        @encoded = nil # : String?
-      end
-
-      # Declare or retrieve the Namespace named +name+ (idempotent).
-      # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
-      # +Namespace::NAME_PATTERN+). Returns the +Kobako::Namespace+ for that
-      # name, creating it if it does not exist. Raises +ArgumentError+ when
-      # +name+ is malformed, or when called after the owning Sandbox has been
-      # sealed by its first invocation.
-      def define(name)
-        raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
-
-        name_str = name.to_s
-        unless Namespace::NAME_PATTERN.match?(name_str)
-          raise ArgumentError,
-                "Namespace name must match #{Namespace::NAME_PATTERN.inspect} (got #{name.inspect})"
-        end
-
-        @namespaces[name_str] ||= Namespace.new(name_str)
-      end
-
-      # Resolve a +target+ path of the form +"<Namespace>::<Member>"+
-      # (e.g. +"MyService::KV"+) to the bound Host object. +target+ is a
-      # two-level path using the +::+ separator. Returns the bound Host
-      # object. Raises +KeyError+ when the namespace or the member is not
-      # bound.
-      def lookup(target)
-        namespace_name, member_name = target.to_s.split("::", 2)
-        namespace = @namespaces[namespace_name]
-        raise KeyError, "no namespace named #{namespace_name.inspect}" if namespace.nil?
-        raise KeyError, "no member in target #{target.inspect}" unless member_name
-
-        namespace.fetch(member_name)
-      end
-
-      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery.
-      # Routes through Kobako::Codec::Encoder like every other host-side
-      # wire encode so there is a single codec path; the preamble carries
-      # only Strings and 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: sealing freezes Service registration 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+ and never alters Frame 1.
-      # The memo is gated on the seal rather than dropped per mutation (the
-      # +Catalog::Snippets#encode+ approach) because a +Member+ bind lands
-      # on a child +Kobako::Namespace+, invisible to this collection; only
-      # the seal guarantees nothing further can change.
-      def encode
-        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 and propagate the seal to every
-      # declared +Kobako::Namespace+. Called by +Sandbox+ on the first
-      # invocation. After sealing, both #define and +Namespace#bind+
-      # raise ArgumentError. Idempotent.
-      def seal!
-        return self if @sealed
-
-        @sealed = true
-        @namespaces.each_value(&:seal!)
-        self
-      end
-
-      # Returns +true+ when #seal! has been called, +false+ otherwise.
-      def sealed?
-        @sealed
-      end
-    end
-  end
-end

data/lib/kobako/codec/factory.rb

@@ -1,187 +0,0 @@
-# frozen_string_literal: true
-
-require "singleton"
-require "forwardable"
-require "msgpack"
-
-require_relative "error"
-require_relative "utils"
-require_relative "../handle"
-require_relative "../fault"
-
-module Kobako
-  module Codec
-    # Cached +MessagePack::Factory+ that owns the kobako wire ext-type
-    # registration ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
-    # § Ext Types).
-    #
-    # The factory is the single place in the host gem that touches the
-    # msgpack API — both Encoder and Decoder delegate through it, so
-    # the three kobako ext codes (0x00 Symbol, 0x01 Capability Handle,
-    # 0x02 Exception envelope) are configured exactly once at first use.
-    #
-    # Lifecycle is owned by +Singleton+ from the Ruby standard library:
-    # +Factory.instance+ is lazy, thread-safe, and process-wide. Class-level
-    # +Factory.dump+ / +Factory.load+ shortcuts are exposed via
-    # +SingleForwardable+ so callers do not have to spell the +.instance+
-    # hop at every call site; the instance-level +#dump+ / +#load+ are in
-    # turn delegated to the wrapped +MessagePack::Factory+ via +Forwardable+.
-    class Factory
-      include Singleton
-      extend Forwardable
-      extend SingleForwardable
-
-      # MessagePack ext type code reserved for Symbol
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
-      # → ext 0x00). Class-private — mirrors +codec::EXT_SYMBOL+ on the
-      # Rust side.
-      EXT_SYMBOL = 0x00
-      # MessagePack ext type code reserved for Capability Handle
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
-      # → ext 0x01). Class-private — mirrors +codec::EXT_HANDLE+ on the
-      # Rust side.
-      EXT_HANDLE = 0x01
-      # MessagePack ext type code reserved for Exception envelope
-      # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
-      # → ext 0x02). Class-private — mirrors +codec::EXT_ERRENV+ on the
-      # Rust side.
-      EXT_ERRENV = 0x02
-      private_constant :EXT_SYMBOL, :EXT_HANDLE, :EXT_ERRENV
-
-      # An ext 0x02 (Fault) envelope nests through its +details+ field, and
-      # each level re-enters the codec with a fresh +MessagePack+ unpacker
-      # whose built-in stack guard resets — so ext-envelope depth is tracked
-      # here instead. The cap matches the wire's overall nesting bound and
-      # keeps a nested chain from exhausting the native stack: an over-deep
-      # chain fails as a clean wire error, never a stack-level trap.
-      MAX_EXT_DEPTH = 128
-      EXT_DEPTH_KEY = :__kobako_codec_ext_depth__
-      private_constant :MAX_EXT_DEPTH, :EXT_DEPTH_KEY
-
-      # Instance-level pass-through onto the wrapped +MessagePack::Factory+.
-      # Spelled +def_instance_delegators+ rather than +def_delegators+ because
-      # the class also extends +SingleForwardable+ (see the +extend+ block
-      # above), which defines its own +def_delegators+ that shadows
-      # +Forwardable+'s — the unambiguous forms keep both delegation tiers
-      # wired to the right scope.
-      def_instance_delegators :@factory, :dump, :load
-
-      # Class-level shortcuts so callers can write +Factory.dump(v)+ instead
-      # of +Factory.instance.dump(v)+; both resolve to the same singleton.
-      def_single_delegators :instance, :dump, :load
-
-      def initialize
-        @factory = MessagePack::Factory.new
-        register_symbol
-        register_handle
-        register_fault
-      end
-
-      private
-
-      def register_symbol
-        @factory.register_type(
-          EXT_SYMBOL, Symbol,
-          packer: method(:pack_symbol),
-          unpacker: method(:unpack_symbol)
-        )
-      end
-
-      # Symbol-to-name packer for the ext-0x00 registration.
-      def pack_symbol(symbol)
-        symbol.name
-      end
-
-      # Validate the ext-0x00 payload as UTF-8 and intern. Raises
-      # InvalidEncoding on invalid bytes — SPEC forbids the
-      # 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!. 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, "Symbol payload")
-        name.to_sym
-      end
-
-      def register_handle
-        @factory.register_type(
-          EXT_HANDLE, Kobako::Handle,
-          packer: ->(handle) { [handle.id].pack("N") },
-          unpacker: ->(payload) { unpack_handle(payload) }
-        )
-      end
-
-      def register_fault
-        @factory.register_type(
-          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 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, "Handle payload must be 4 bytes, got #{bytes.bytesize}" unless bytes.bytesize == 4
-
-        id = bytes.unpack1("N") # : Integer
-        Codec::Utils.with_boundary { Kobako::Handle.restore(id) }
-      end
-
-      # Encode the inner ext-0x02 map via Encoder (not +factory.dump+) so
-      # the embedded payload flows through the same boundary as a top-level
-      # encode — nested kobako values (Handle, nested Fault) reach the
-      # registered ext-type packers via the cached singleton. A +details+
-      # chain nested past MAX_EXT_DEPTH has no wire representation and
-      # surfaces as +UnsupportedType+.
-      def pack_fault(fault)
-        within_ext_frame(UnsupportedType) do
-          Encoder.encode("type" => fault.type, "message" => fault.message, "details" => fault.details)
-        end
-      end
-
-      # 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. A nested ext 0x02 in
-      # +details+ re-enters this method, so #within_ext_frame bounds the
-      # chain depth to keep it from exhausting the native stack.
-      def unpack_fault(payload)
-        within_ext_frame(InvalidType) do
-          Decoder.decode(payload) do |map|
-            raise InvalidType, "Fault payload must be a map" unless map.is_a?(Hash)
-
-            Kobako::Fault.new(type: map["type"], message: map["message"], details: map["details"])
-          end
-        end
-      end
-
-      # Track ext-envelope re-entry depth and refuse a chain past
-      # MAX_EXT_DEPTH, raising +over_limit+ so the failure lands in the
-      # caller's existing wire-error class. The counter is thread-scoped and
-      # balanced by the +ensure+, so a raise mid-chain still unwinds it to
-      # its entry value.
-      def within_ext_frame(over_limit)
-        depth = (Thread.current[EXT_DEPTH_KEY] || 0) + 1
-        raise over_limit, "ext envelope nesting exceeds #{MAX_EXT_DEPTH} levels" if depth > MAX_EXT_DEPTH
-
-        Thread.current[EXT_DEPTH_KEY] = depth
-        begin
-          yield
-        ensure
-          Thread.current[EXT_DEPTH_KEY] = depth - 1
-        end
-      end
-    end
-  end
-end

data/lib/kobako/namespace.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  # 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.
-    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]
-      @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, 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)
-
-      @members[member_str] = object
-      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)
-      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

data/sig/kobako/catalog/namespaces.rbs

@@ -1,17 +0,0 @@
-module Kobako
-  module Catalog
-    class Namespaces
-      def initialize: (?handler: Kobako::Catalog::Handles) -> void
-
-      def define: (Symbol | String name) -> Kobako::Namespace
-
-      def lookup: (String target) -> untyped
-
-      def encode: () -> String
-
-      def seal!: () -> self
-
-      def sealed?: () -> bool
-    end
-  end
-end

data/sig/kobako/codec/factory.rbs

@@ -1,34 +0,0 @@
-module Kobako
-  module Codec
-    class Factory
-      include Singleton
-      extend Forwardable
-      extend SingleForwardable
-
-      EXT_SYMBOL: Integer
-      EXT_HANDLE: Integer
-      EXT_ERRENV: Integer
-      MAX_EXT_DEPTH: Integer
-      EXT_DEPTH_KEY: Symbol
-
-      def dump: (untyped value) -> String
-      def load: (String bytes) -> untyped
-
-      def self.dump: (untyped value) -> String
-      def self.load: (String bytes) -> untyped
-
-      private
-
-      def initialize: () -> void
-      def register_symbol: () -> void
-      def pack_symbol: (Symbol symbol) -> String
-      def unpack_symbol: (String payload) -> Symbol
-      def register_handle: () -> void
-      def register_fault: () -> void
-      def unpack_handle: (String payload) -> Kobako::Handle
-      def pack_fault: (Kobako::Fault fault) -> String
-      def unpack_fault: (String payload) -> Kobako::Fault
-      def within_ext_frame: [T] (singleton(Kobako::Codec::Error) over_limit) { () -> T } -> T
-    end
-  end
-end

data/sig/kobako/namespace.rbs

@@ -1,21 +0,0 @@
-module Kobako
-  class Namespace
-    NAME_PATTERN: Regexp
-
-    attr_reader name: String
-
-    def initialize: (String name) -> void
-
-    def bind: (Symbol | String member, untyped object) -> self
-
-    def seal!: () -> self
-
-    def fetch: (Symbol | String member) -> untyped
-
-    def to_preamble: () -> [String, Array[String]]
-
-    private
-
-    def validate_member_name!: (Symbol | String member) -> String
-  end
-end