kobako 0.1.0

data/lib/kobako/errors.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+# Top-level Kobako namespace.
+module Kobako
+  # Three-class error taxonomy (SPEC.md → Error Scenarios).
+  #
+  # Every `Kobako::Sandbox#run` invocation either returns a value or raises
+  # exactly one of these three classes. Attribution is decided after the
+  # guest binary returns control to the host (SPEC "Step 1 — Wasm trap"
+  # then "Step 2 — Outcome envelope tag").
+  #
+  # Three top-level 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).
+  #
+  # Subclasses pinned by SPEC "Error Classes":
+  #
+  #   * {HandleTableExhausted} < {SandboxError}    — id cap hit (B-21).
+  #   * {ServiceError::Disconnected} < {ServiceError} — `:disconnected`
+  #                       sentinel hit on the HandleTable (E-14).
+
+  # Base for all kobako-raised errors so callers that want to ignore the
+  # taxonomy can rescue a single class.
+  class Error < StandardError; end
+
+  # Wasm engine layer. Raised when the Wasm execution engine crashed
+  # (trap, OOM, unreachable) or when the wire layer detected a structural
+  # violation that signals a corrupted guest execution environment
+  # (zero-length OUTCOME_BUFFER, unknown outcome tag — SPEC E-02 / E-03).
+  class TrapError < Error; 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.
+  class SandboxError < Error
+    attr_reader :origin, :klass, :backtrace_lines, :details
+
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
+      super(message)
+      @origin = origin
+      @klass = klass
+      @backtrace_lines = backtrace_lines
+      @details = details
+    end
+  end
+
+  # Service layer. Raised when a Service capability call inside a mruby
+  # script reported an application-level failure that the script did not
+  # rescue.
+  class ServiceError < Error
+    attr_reader :origin, :klass, :backtrace_lines, :details
+
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
+      super(message)
+      @origin = origin
+      @klass = klass
+      @backtrace_lines = backtrace_lines
+      @details = details
+    end
+
+    # SPEC "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.err
+  # 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
+
+  # SPEC "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
+end

data/lib/kobako/registry/dispatcher.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Kobako
+  class Registry
+    # Pure-function dispatcher for guest-initiated RPC calls. Decodes a
+    # msgpack-encoded Request envelope, resolves the target object through the
+    # Registry (path lookup or HandleTable lookup), invokes the method, and
+    # returns a msgpack-encoded Response envelope.
+    #
+    # The module is stateless — all mutable state is threaded through the
+    # +registry+ argument so Dispatcher has no instance variables and no side
+    # effects beyond mutating the HandleTable via +alloc+ when a non-wire-
+    # representable return value must be wrapped ({SPEC.md B-14}[link:../../../SPEC.md]).
+    #
+    # Entry point:
+    #
+    #   Kobako::Registry::Dispatcher.dispatch(request_bytes, registry)
+    #   # => msgpack-encoded Response bytes (never raises)
+    module Dispatcher
+      module_function
+
+      # Internal sentinel raised when target resolution fails. Mapped to
+      # Response.err with type="undefined". Contained at the wire boundary —
+      # not part of the public Kobako error taxonomy
+      # ({SPEC.md E-xx}[link:../../../SPEC.md]).
+      class UndefinedTargetError < StandardError; end
+
+      # Internal sentinel raised when a Handle target resolves to the
+      # +:disconnected+ sentinel in the HandleTable (ABA protection,
+      # {SPEC.md E-14}[link:../../../SPEC.md]). Mapped to Response.err with
+      # type="disconnected". Contained at the wire boundary.
+      class DisconnectedTargetError < StandardError; end
+
+      # Dispatch a single RPC request and return the encoded response bytes.
+      # Called by +Kobako::Registry#dispatch+ which is invoked from the Rust
+      # ext inside +__kobako_rpc_call+. +request_bytes+ is the msgpack-encoded
+      # Request envelope. +registry+ is the live registry for this run, used
+      # to resolve path-based targets via +#lookup+ and to access the
+      # +#handle_table+ for Handle-based targets and return-value wrapping.
+      # Always returns a binary String — never raises. Any failure during
+      # decode, lookup, or method invocation is reified as a Response.err
+      # envelope so the guest sees the failure as a normal RPC error rather
+      # than a wasm trap
+      # ({SPEC.md B-12}[link:../../../SPEC.md]).
+      def dispatch(request_bytes, registry)
+        value = perform_dispatch(request_bytes, registry)
+        encode_ok_or_wrap(value, registry)
+      rescue StandardError => e
+        encode_dispatch_error(e)
+      end
+
+      # Map an error raised during dispatch to a Response.err envelope.
+      # +error+ is the +StandardError+ caught at the dispatch boundary. Returns
+      # a msgpack-encoded Response envelope (binary). Four error buckets
+      # ({SPEC.md B-12}[link:../../../SPEC.md]): +Wire::Codec::Error+ →
+      # type="runtime" (wire decode failed); +DisconnectedTargetError+ →
+      # type="disconnected" (E-14); +UndefinedTargetError+ → type="undefined"
+      # (E-13); +ArgumentError+ → type="argument" (B-12 arity mismatch);
+      # everything else → type="runtime".
+      def encode_dispatch_error(error)
+        case error
+        when Kobako::Wire::Codec::Error then encode_err("runtime", "wire decode failed: #{error.message}")
+        when DisconnectedTargetError then encode_err("disconnected", error.message)
+        when UndefinedTargetError    then encode_err("undefined", error.message)
+        when ArgumentError           then encode_err("argument", error.message)
+        else                              encode_err("runtime", "#{error.class}: #{error.message}")
+        end
+      end
+
+      def perform_dispatch(request_bytes, registry)
+        request = Kobako::Wire::Envelope.decode_request(request_bytes)
+        handle_table = registry.handle_table
+        target_object = resolve_target(request.target, registry, handle_table)
+        args = request.args.map { |v| resolve_arg(v, handle_table) }
+        kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handle_table) }
+        invoke(target_object, request.method_name, args, kwargs)
+      end
+
+      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
+      # (the +Envelope::Request+ invariant pins it). The empty-kwargs
+      # branch omits the +**+ splat so Ruby 3.x's strict kwargs
+      # separation does not reject calls to no-kwarg methods when the
+      # wire carries the uniform empty-map shape.
+      def invoke(target, method, args, kwargs)
+        if kwargs.empty?
+          target.public_send(method.to_sym, *args)
+        else
+          target.public_send(method.to_sym, *args, **kwargs)
+        end
+      end
+
+      # {SPEC.md B-16}[link:../../../SPEC.md] — A Wire::Handle arriving as a positional or keyword
+      # argument identifies a host-side object previously allocated by a prior
+      # RPC's Handle wrap (B-14). Resolve it back to the Ruby object before
+      # the dispatch reaches +public_send+. A Handle whose entry is the
+      # +:disconnected+ sentinel (E-14) raises DisconnectedTargetError so
+      # the dispatcher emits a Response.err with type="disconnected".
+      def resolve_arg(value, handle_table)
+        case value
+        when Kobako::Wire::Handle
+          fetch_live_object(value.id, handle_table)
+        else
+          value
+        end
+      end
+
+      # Resolve a Request target to the Ruby object the Registry (or
+      # HandleTable) holds. String targets go through the Registry;
+      # Handle targets (ext 0x01) go through the HandleTable.
+      #
+      # Target type is already validated by +Wire::Envelope.decode_request+
+      # before this method is reached, so no else-branch is needed here —
+      # the wire layer is the system boundary that enforces the invariant.
+      def resolve_target(target, registry, handle_table)
+        case target
+        when String
+          resolve_path(target, registry)
+        when Kobako::Wire::Handle
+          resolve_handle(target, handle_table)
+        end
+      end
+
+      def resolve_path(path, registry)
+        registry.lookup(path)
+      rescue KeyError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      def resolve_handle(handle, handle_table)
+        fetch_live_object(handle.id, handle_table)
+      end
+
+      # Resolve +id+ through the HandleTable, distinguishing the
+      # +:disconnected+ sentinel (E-14) from an unknown id (E-13).
+      def fetch_live_object(id, handle_table)
+        object = handle_table.fetch(id)
+        raise DisconnectedTargetError, "Handle id #{id} is disconnected" if object == :disconnected
+
+        object
+      rescue Kobako::HandleTableError => e
+        raise UndefinedTargetError, e.message
+      end
+
+      # Encode +value+ as a +Response.ok+ envelope. When the value is not
+      # wire-representable per {SPEC.md B-13}[link:../../../SPEC.md]'s type
+      # mapping, the +UnsupportedType+ rescue routes it through the
+      # HandleTable and re-encodes with the Capability Handle in place
+      # ({SPEC.md B-14}[link:../../../SPEC.md]). The happy path encodes
+      # exactly once.
+      def encode_ok_or_wrap(value, registry)
+        encode_ok(value)
+      rescue Kobako::Wire::Codec::UnsupportedType
+        encode_ok(Kobako::Wire::Handle.new(registry.handle_table.alloc(value)))
+      end
+
+      def encode_ok(value)
+        response = Kobako::Wire::Envelope::Response.ok(value)
+        Kobako::Wire::Envelope.encode_response(response)
+      end
+
+      def encode_err(type, message)
+        exception = Kobako::Wire::Exception.new(type: type, message: message)
+        response = Kobako::Wire::Envelope::Response.err(exception)
+        Kobako::Wire::Envelope.encode_response(response)
+      end
+    end
+  end
+end

data/lib/kobako/registry/handle_table.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative "../wire/handle"
+
+module Kobako
+  class Registry
+    # Host-side mapping from opaque integer Handle IDs to Ruby objects
+    # (capability proxies). One table is owned per Kobako::Registry instance
+    # (and therefore per Kobako::Sandbox instance). See
+    # {SPEC.md B-15}[link:../../../SPEC.md].
+    #
+    # Lifecycle invariants ({SPEC.md}[link:../../../SPEC.md]):
+    #
+    #   - {SPEC.md B-15}[link:../../../SPEC.md] — Handle IDs are allocated by
+    #     a monotonically increasing counter scoped to a single `#run`. The
+    #     first ID issued in a run is 1; ID 0 is reserved as the invalid
+    #     sentinel and is never returned by #alloc.
+    #
+    #   - {SPEC.md B-19}[link:../../../SPEC.md] — When between `#run`
+    #     invocations (via `#reset!`), every Handle issued under the old state
+    #     becomes invalid.
+    #
+    #   - {SPEC.md B-21}[link:../../../SPEC.md] — The cap is `0x7fff_ffff`
+    #     (2³¹ − 1). Allocation beyond the cap raises immediately — no silent
+    #     truncation, no wrap, no ID reuse.
+    class HandleTable
+      # Build a fresh, empty HandleTable. +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 +Wire::Handle::MAX_ID+ to exercise
+      # the cap-exhaustion path without 2³¹ allocations.
+      def initialize(next_id: 1)
+        @entries = {}
+        @next_id = next_id
+      end
+
+      # Bind +object+ in the table and return its newly-allocated Handle ID.
+      # +object+ is any host-side Ruby object to bind. Returns a freshly-
+      # allocated Handle ID in +[1, Wire::Handle::MAX_ID]+. Raises
+      # +Kobako::HandleTableExhausted+ if the next ID would exceed the cap.
+      # The cap is anchored on +Wire::Handle+ — the wire codec and the
+      # allocator share the same invariant ({SPEC.md B-21}[link:../../../SPEC.md]).
+      def alloc(object)
+        id = @next_id
+        cap = Wire::Handle::MAX_ID
+        raise HandleTableExhausted, "HandleTable exhausted: id #{id} exceeds MAX_ID #{cap}" if id > cap
+
+        @entries[id] = object
+        @next_id = id + 1
+        id
+      end
+
+      # Resolve a Handle ID to its bound object. +id+ is a Handle ID previously
+      # returned by +#alloc+. Returns the bound object. Raises
+      # +Kobako::HandleTableError+ if +id+ is not currently bound.
+      def fetch(id)
+        require_bound!(id)
+        @entries[id]
+      end
+
+      # Remove and return the binding for +id+. +id+ is the Handle ID to
+      # release. Returns the previously-bound object. Raises
+      # +Kobako::HandleTableError+ if +id+ is not currently bound.
+      def release(id)
+        require_bound!(id)
+        @entries.delete(id)
+      end
+
+      # Clear all entries AND reset the counter to 1. Called at the per-run
+      # boundary — see {SPEC.md B-19}[link:../../../SPEC.md].
+      # Returns +self+.
+      def reset!
+        @entries.clear
+        @next_id = 1
+        self
+      end
+
+      # Mark the entry at +id+ as disconnected (ABA protection). +id+ is the
+      # Handle ID to poison; silently ignored if +id+ is not currently bound.
+      # Returns +self+ for chainability, matching the convention of +#reset!+.
+      def mark_disconnected(id)
+        @entries[id] = :disconnected if @entries.key?(id)
+        self
+      end
+
+      # Returns the number of currently-bound entries.
+      def size
+        @entries.size
+      end
+
+      # Returns +true+ when +id+ is currently bound, +false+ otherwise.
+      def include?(id)
+        @entries.key?(id)
+      end
+
+      private
+
+      # Single source of truth for the "unknown Handle id" raise shared by
+      # {#fetch} and {#release}. Returns +nil+ on success; raises
+      # +Kobako::HandleTableError+ when +id+ is not currently bound.
+      def require_bound!(id)
+        return if @entries.key?(id)
+
+        raise HandleTableError, "unknown Handle id: #{id.inspect}"
+      end
+    end
+  end
+end

data/lib/kobako/registry/service_group.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Kobako
+  class Registry
+    # A named namespace of Service Members for one Sandbox ({SPEC.md B-07..B-11}[link:../../../SPEC.md]).
+    class ServiceGroup
+      attr_reader :name, :members
+
+      # Build a new ServiceGroup. +name+ is an already-validated Group name
+      # (must satisfy +NAME_PATTERN+; validation is the caller's responsibility).
+      def initialize(name)
+        @name = name
+        @members = {}
+      end
+
+      # Bind +object+ under +member+ inside this group. +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 ({SPEC.md B-11}[link:../../../SPEC.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. Returns the bound object or +nil+ when missing.
+      def [](member)
+        @members[member.to_s]
+      end
+
+      # Strict variant of {#[]}; 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 group #{@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 Registry::NAME_PATTERN.match?(member_str)
+          raise ArgumentError,
+                "MemberName must match #{Registry::NAME_PATTERN.inspect} (got #{member.inspect})"
+        end
+
+        member_str
+      end
+    end
+  end
+end

data/lib/kobako/registry.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "msgpack"
+require_relative "errors"
+require_relative "wire"
+require_relative "registry/service_group"
+require_relative "registry/handle_table"
+require_relative "registry/dispatcher"
+
+module Kobako
+  # Kobako::Registry — per-Sandbox container of Service Groups and Handle
+  # state. Manages capability injection and guest-initiated RPC dispatch
+  # ({SPEC.md B-07..B-21}[link:../../SPEC.md]).
+  #
+  # Public API:
+  #
+  #   registry = Kobako::Registry.new
+  #   group = registry.define(:MyService)    # => ServiceGroup
+  #   group.bind(:KV, kv_object)             # => group (chainable)
+  #   registry.to_preamble                   # => array for Frame 1
+  #   registry.dispatch(request_bytes)       # => msgpack bytes (delegated to Dispatcher)
+  #
+  # Service Groups are defined in +Kobako::Registry::ServiceGroup+
+  # (lib/kobako/registry/service_group.rb). The opaque Handle allocator lives
+  # in +Kobako::Registry::HandleTable+ (lib/kobako/registry/handle_table.rb).
+  # Dispatch helpers live in +Kobako::Registry::Dispatcher+
+  # (lib/kobako/registry/dispatcher.rb).
+  class Registry
+    # Ruby constant-name pattern shared by Group and Member names
+    # ({SPEC.md B-07/B-08 Notes}[link:../../SPEC.md]). Referenced by both
+    # +#define+ here and +ServiceGroup#bind+ — single source of truth so
+    # the validation rule cannot drift between the two boundaries.
+    NAME_PATTERN = /\A[A-Z]\w*\z/
+
+    # Build a fresh Registry. +handle_table+ is an internal seam that
+    # injects a pre-configured +HandleTable+; tests pass one whose +next_id+
+    # is pinned near +MAX_ID+ to exercise the B-21 cap-exhaustion path
+    # without 2³¹ allocations. Production callers leave it at the default.
+    def initialize(handle_table: HandleTable.new)
+      @groups = {}
+      @handle_table = handle_table
+      @sealed = false
+    end
+
+    # Declare or retrieve the Group named +name+ (idempotent — SPEC.md B-10).
+    # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
+    # +NAME_PATTERN+). Returns the +Kobako::Registry::ServiceGroup+ 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 +#run+.
+    def define(name)
+      raise ArgumentError, "cannot define after Sandbox#run has been invoked" if @sealed
+
+      name_str = name.to_s
+      unless NAME_PATTERN.match?(name_str)
+        raise ArgumentError,
+              "GroupName must match #{NAME_PATTERN.inspect} (got #{name.inspect})"
+      end
+
+      @groups[name_str] ||= ServiceGroup.new(name_str)
+    end
+
+    # Resolve a +target+ path of the form +"GroupName::MemberName"+ to the
+    # bound Host object. +target+ is a two-level path using the +::+
+    # separator. Returns the bound Host object. Raises +KeyError+ when the
+    # group or the member is not bound.
+    def lookup(target)
+      group, member_name, group_name = resolve_pair(target)
+      raise KeyError, "no service group named #{group_name.inspect}" if group.nil?
+      raise KeyError, "no member #{target.inspect} bound in registry" unless member_name
+
+      group.fetch(member_name)
+    end
+
+    # Returns +true+ when +target+ (a +"GroupName::MemberName"+ path) resolves
+    # to a bound member, +false+ otherwise.
+    def bound?(target)
+      group, member_name, = resolve_pair(target)
+      !group.nil? && !member_name.nil? && !group[member_name].nil?
+    end
+
+    # Returns all declared +Kobako::Registry::ServiceGroup+ instances as an
+    # +Array+.
+    def groups
+      @groups.values
+    end
+
+    # Returns the number of declared groups as an +Integer+.
+    def size
+      @groups.size
+    end
+
+    # Returns +true+ when no groups have been declared, +false+ otherwise.
+    def empty?
+      @groups.empty?
+    end
+
+    # Structured Frame 1 description. Called by +Sandbox#run+ when assembling
+    # stdin Frame 1 ({SPEC.md B-02}[link:../../SPEC.md]). Returns an
+    # unencoded preamble array — an +Array+ of two-element +[name, members]+
+    # arrays, one per declared group.
+    def to_preamble
+      @groups.values.map(&:to_preamble)
+    end
+
+    # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
+    # ({SPEC.md B-02}[link:../../SPEC.md]). Uses plain MessagePack (no
+    # kobako ext types) because the preamble contains only strings — no
+    # Handles or Exception envelopes. Structure:
+    # +[["GroupName", ["MemberA", "MemberB"]], ...]+. Returns a binary
+    # +String+ of msgpack bytes.
+    def guest_preamble
+      MessagePack.pack(to_preamble)
+    end
+
+    # Mark the Registry as sealed. Called by `Sandbox#run` on first run.
+    # After sealing, #define raises ArgumentError. Idempotent.
+    def seal!
+      @sealed = true
+      self
+    end
+
+    # Returns +true+ when {#seal!} has been called, +false+ otherwise.
+    def sealed?
+      @sealed
+    end
+
+    # Reset the HandleTable for a new +#run+ boundary. Called by +Sandbox#run+
+    # before each invocation ({SPEC.md B-19}[link:../../SPEC.md]).
+    def reset_handles!
+      @handle_table.reset!
+    end
+
+    # Dispatch a single RPC request and return the encoded response bytes
+    # ({SPEC.md B-12}[link:../../SPEC.md]). +request_bytes+ is a
+    # msgpack-encoded Request envelope. Called by the Rust ext from inside
+    # +__kobako_rpc_call+. Always returns a binary +String+ — never raises.
+    # Delegates to +Dispatcher.dispatch+ which reifies any failure as a
+    # +Response.err+ envelope so the guest sees the failure as a normal RPC
+    # error rather than a wasm trap.
+    def dispatch(request_bytes)
+      Dispatcher.dispatch(request_bytes, self)
+    end
+
+    # Expose the +Kobako::Registry::HandleTable+ for tests and wire-layer
+    # Handle wrapping.
+    attr_reader :handle_table
+
+    private
+
+    # Split +target+ on the +::+ separator and resolve the group half.
+    # Returns +[group_or_nil, member_str_or_nil, group_name_str]+ so each
+    # public method ({#lookup} / {#bound?}) only owns its boundary
+    # semantics (raise vs predicate).
+    def resolve_pair(target)
+      group_name, member_name = target.to_s.split("::", 2)
+      [@groups[group_name], member_name, group_name]
+    end
+  end
+end

data/lib/kobako/sandbox/outcome_decoder.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Kobako
+  class Sandbox
+    # Pure-function decoder for the OUTCOME_BUFFER bytes returned by
+    # +__kobako_run+. Maps a tagged msgpack envelope to either the unwrapped
+    # mruby return value or a raised three-layer
+    # ({SPEC.md "Error Scenarios"}[link:../../../SPEC.md]) exception.
+    #
+    #   * tag 0x01, decode OK                 → return Result.value
+    #   * tag 0x01, decode fails              → SandboxError (E-09)
+    #   * tag 0x02, origin="service"          → ServiceError (E-13)
+    #   * tag 0x02, origin="sandbox"/missing  → SandboxError (E-04..E-07)
+    #   * tag 0x02, decode fails              → SandboxError (E-08)
+    #   * unknown tag                         → TrapError    (E-03)
+    module OutcomeDecoder
+      module_function
+
+      def decode(bytes)
+        tag, body = split_outcome_tag(bytes)
+        case tag
+        when Kobako::Wire::Envelope::OUTCOME_TAG_RESULT
+          decode_result(body)
+        when Kobako::Wire::Envelope::OUTCOME_TAG_PANIC
+          decode_panic(body)
+        else
+          raise trap_for_tag(tag)
+        end
+      end
+
+      # TrapError for unknown or absent tag
+      # ({SPEC.md ABI Signatures}[link:../../../SPEC.md]: len=0 and unknown-tag
+      # both walk the trap path).
+      def trap_for_tag(tag)
+        return TrapError.new("guest exited without writing an outcome (len=0)") if tag.nil?
+
+        TrapError.new(format("unknown outcome tag 0x%<tag>02x", tag: tag))
+      end
+
+      def split_outcome_tag(bytes)
+        bytes = bytes.b
+        [bytes.getbyte(0), bytes.byteslice(1, bytes.bytesize - 1)]
+      end
+
+      # Decode failure on a known Result tag is a SandboxError (E-09): the
+      # framing was fine, but the wrapped value is unrepresentable.
+      def decode_result(body)
+        Kobako::Wire::Envelope.decode_result(body).value
+      rescue Kobako::Wire::Codec::Error => e
+        raise wire_violation_error("result envelope decode failed: #{e.message}")
+      end
+
+      # Decode failure on a known Panic tag is a SandboxError (E-08). Either
+      # path raises — on success the decoded Panic is mapped to its three-
+      # layer exception via +build_panic_error+ and raised; on wire-decode
+      # failure the rescue path raises the wire-violation +SandboxError+.
+      # Symmetric with +decode_result+ — both have signature
+      # "decode body and return value, or raise".
+      def decode_panic(body)
+        raise build_panic_error(Kobako::Wire::Envelope.decode_panic(body))
+      rescue Kobako::Wire::Codec::Error => e
+        raise wire_violation_error("panic envelope decode failed: #{e.message}")
+      end
+
+      # Map a decoded Panic envelope into the corresponding three-layer
+      # Ruby exception. +origin == "service"+ → ServiceError (with the
+      # +::Disconnected+ subclass selected when the panic carries the
+      # disconnected sentinel —
+      # {SPEC "Error Classes"}[link:../../../SPEC.md]); everything else
+      # → SandboxError.
+      def build_panic_error(panic)
+        panic_target_class(panic).new(
+          panic.message,
+          origin: panic.origin,
+          klass: panic.klass,
+          backtrace_lines: panic.backtrace,
+          details: panic.details
+        )
+      end
+
+      # {SPEC "Error Classes"}[link:../../../SPEC.md]: when
+      # +origin="service"+ and the panic +class+ field names
+      # +ServiceError::Disconnected+, surface that subclass so callers can
+      # rescue the disconnected path specifically (E-14).
+      def panic_target_class(panic)
+        return SandboxError unless panic.origin == Kobako::Wire::Envelope::Panic::ORIGIN_SERVICE
+
+        panic.klass == "Kobako::ServiceError::Disconnected" ? ServiceError::Disconnected : ServiceError
+      end
+
+      def wire_violation_error(message)
+        SandboxError.new(
+          message,
+          origin: Kobako::Wire::Envelope::Panic::ORIGIN_SANDBOX,
+          klass: "Kobako::WireError"
+        )
+      end
+    end
+  end
+end