kobako 0.14.0 → 0.16.0

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