kobako 0.27.0 → 0.29.0

data/lib/kobako/transport/block_failure.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Transport
+    # The newest failure a guest block raised to a Service during one
+    # invocation, whichever open Call carried that block: a Service may run
+    # a block stored from an earlier Call, and its failure is still the
+    # guest's own.
+    class BlockFailure # :nodoc:
+      def initialize
+        @raised = nil
+      end
+
+      # Only the newest is kept: a Service that rescued an earlier one and
+      # yielded again has already handled it.
+      def remember(error)
+        @raised = error
+      end
+
+      # Identity rather than class: a Service that rescued the block's
+      # failure and raised its own has reported something else, and the
+      # guest must hear about that instead.
+      #
+      # The class travels with the message because not every block failure
+      # is an exception the guest holds — a block value the guest refused
+      # has a class to raise under and no object to continue.
+      def fault_text(error)
+        raised = @raised
+        return if raised.nil? || !error.equal?(raised)
+
+        "#{raised.klass}: #{raised.message}"
+      end
+    end
+  end
+end

data/lib/kobako/transport/call.rb

@@ -2,20 +2,7 @@
 
 module Kobako
   module Transport
-    # One guest-initiated dispatch, as the native side decoded it off the
-    # core envelope. The routing fields arrive already decoded — a String
-    # for a bound constant's path, an Integer for a Capability Handle id —
-    # so the host resolves a target without interpreting a payload byte.
-    #
-    # +payload+ stays bytes here on purpose: routing never interprets a
-    # payload byte, and the one place that does — the Dispatcher — must
-    # decode it inside the Codec bracket that records whether a Handle
-    # crossed.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form so the class
-    # body is fully Steep-visible; see +.rubocop.yml+ for the
-    # rationale.
-    class Call < Data.define(:target, :method_name, :block_given, :payload)
+    class Call < Data.define(:target, :method_name, :block_given, :payload) # :nodoc:
     end
   end
 end

data/lib/kobako/transport/dispatcher.rb

@@ -3,259 +3,180 @@
 require_relative "../codec"
 require_relative "../errors"
 require_relative "../payload"
+require_relative "block_failure"
 require_relative "call"
 require_relative "reflection"
 require_relative "yielder"
 
 module Kobako
-  # See lib/kobako/transport.rb for the umbrella module doc; this file
-  # owns the pure-function dispatcher that answers a routed Call.
   module Transport
-    # Pure-function dispatcher for guest-initiated Calls. The native side
-    # has already decoded the core envelope, so this resolves the target
-    # through the per-invocation path +resolver+ (the +Context+, whose
-    # +#lookup+ layers per-invocation providers over the static bindings)
-    # or Catalog::Handles, decodes only the payload, invokes the method,
-    # and answers +[ok, bytes]+ — which the native side puts on the
-    # Reply's ok or fault arm. It never raises.
-    #
-    # The module is stateless — all mutable state is threaded through
-    # arguments so Dispatcher has no instance variables and no side
-    # effects beyond mutating the Catalog::Handles via +alloc+ when a
-    # non-wire-representable return value must be wrapped.
-    module Dispatcher
-      # Throw tag for the Yielder's break unwind back to the
-      # dispatcher's +catch+ frame. +private_constant+ is a
+    # Answers a routed Call with one arm per Reply variant: +[:ok, body, nil]+,
+    # +[:fault, message, fault_type]+, or +[:break, "", nil]+ — a block
+    # exit the guest kept carries nothing. It never raises, so every
+    # failure reaches the guest as a fault.
+    module Dispatcher # :nodoc:
+      # Thrown rather than raised, so a Service unwound by a block exit runs
+      # its +ensure+ and cannot +rescue+ the exit. +private_constant+ is a
       # convention boundary — not a defence.
       BREAK_THROW = :__kobako_break__
       private_constant :BREAK_THROW
 
-      module_function
+      class UndefinedTargetError < StandardError; end # :nodoc:
 
-      # Internal sentinel raised when target resolution fails. Becomes a
-      # Fault with type="undefined". Contained at the wire boundary —
-      # not part of the public Kobako error taxonomy.
-      class UndefinedTargetError < StandardError; end
+      class UnreadableRequestError < Kobako::Codec::Error; end # :nodoc:
 
-      # The codec fault of a request that never became a call, restated in
-      # the vocabulary the guest can act on while staying inside the codec
-      # taxonomy the fault boundary sorts on.
-      class UnreadableRequestError < Kobako::Codec::Error; end
-
-      # The category kobako's own refusals answer under, keyed by the class
-      # each is raised as and ordered most specific first. A class absent
-      # here is the Service's own exception, which answers under +runtime+
-      # wearing the +<class>: <message>+ shape that says so.
+      # The category each failure answering with its message alone takes,
+      # keyed by the class raised and ordered most specific first. kobako's
+      # own refusals are worded so none reads as a Service's exception, and
+      # +ArgumentError+, raised by a Service and by a call that will not
+      # bind alike, is named by +argument+ already. A class absent here is
+      # the Service's own exception, which answers under +runtime+ wearing
+      # the +<class>: <message>+ shape that names it.
       #
       # +Kobako::Codec::Error+ is the floor rather than a path of its own:
       # a codec fault reaching the boundary unnamed is the exchange failing,
       # and must not be dressed as something a Service raised.
-      OWN_FAULTS = {
+      BARE_FAULTS = {
         HandleExhaustedError => "internal",
         UndefinedTargetError => "undefined",
         ArgumentError => "argument",
         YieldValueError => "runtime",
+        UnsupportedError => "runtime",
         Kobako::Codec::Error => "internal",
         Kobako::SandboxError => "runtime"
       }.freeze
-      private_constant :OWN_FAULTS
-
-      # Answer a single routed Call with +[ok, bytes]+, which the native
-      # side puts on the Reply's ok or fault arm. Invoked from the
-      # per-invocation dispatch Proc that
-      # +Kobako::Context+ hands to +Runtime#eval+ / +#run+; +resolver+,
-      # +handler+, and +yield_to_guest+ are captured in that Proc's
-      # closure so the Dispatcher stays stateless and neither the resolver
-      # nor the Context needs to publish accessors for the per-invocation
-      # +Catalog::Handles+ or +Runtime+. +yield_to_guest+ is a +String → String+ callable
-      # (the ext's per-dispatch +Kobako::Runtime::GuestYielder+) used only
-      # when the Call carries +block_given: true+. Never raises — every
-      # failure path takes the fault arm instead, so the guest sees a
-      # transport error rather than a wasm trap.
-      #
-      # The decode runs inside +Codec.track_handles+ so #resolve_call_args
-      # can skip the argument walk when no Capability Handle crossed the
-      # wire.
-      def dispatch(call, resolver, handler, yield_to_guest)
-        yielder = Yielder.new(yield_to_guest, BREAK_THROW, handler) if call.block_given
-        [true, encode_ok(run(call, resolver, handler, yielder), handler), nil] # : [bool, String, String?]
+      private_constant :BARE_FAULTS
+
+      # The per-invocation state arrives as arguments so the Dispatcher
+      # stays stateless and neither the resolver nor the Context publishes
+      # accessors for it.
+      def self.dispatch(call, resolver, handles, failure, guest_yielder)
+        yielder = Yielder.new(guest_yielder, BREAK_THROW, handles, failure) if call.block_given
+        catch(BREAK_THROW) { return [:ok, encode_ok(run(call, resolver, handles, yielder), handles), nil] }
+        [:break, "", nil] # : [Symbol, String, String?]
       # StandardError is the boundary by intent: a Service method's
       # application fault folds into a guest-rescuable fault, while a
       # host-process failure (NoMemoryError, SignalException, a bare Exception)
       # stays uncaught and traps the invocation rather than being masked as a
       # rescuable fault.
       rescue StandardError => e
-        [false, *caught_fault(e, yielder)] # : [bool, String, String?]
+        [:fault, *caught_fault(e, failure)] # : [Symbol, String, String?]
       ensure
-        yielder&.invalidate!
-      end
-
-      # Decode the payload, resolve the receiver, and run the method inside
-      # the +catch+ frame a guest +break+ unwinds to. Split from #dispatch
-      # so the reply-shaping and the failure boundary stay one glance wide.
-      def run(call, resolver, handler, yielder)
-        arguments, carried_handle = decode_arguments(call.payload)
-        exposure = resolve_target(call.target, resolver, handler)
-        args, kwargs = resolve_call_args(arguments, handler, carried_handle)
-        catch(BREAK_THROW) { invoke(exposure, call.method_name, args, kwargs, yielder) }
-      end
-
-      # Decode the Call's payload into its arguments, reporting whether any
-      # Capability Handle crossed. A codec fault here is a request that
-      # never became a call, restated so it cannot read as an unwritable
-      # reply — the same restatement #encode_ok makes in the other
-      # direction.
-      def decode_arguments(payload)
-        Kobako::Codec.track_handles { Payload::Arguments.decode(payload) }
-      rescue Kobako::Codec::Error => e
-        raise UnreadableRequestError, "Sandbox could not read the request: #{e.message}"
+        yielder&.invalidate
       end
 
-      # Resolve positional and keyword arguments off the decoded payload in
-      # one step. +carried_handle+ reports whether the decode carried any
-      # Capability Handle; when it did not, every argument resolves to
-      # itself, so the decoded values pass straight through and the walk is
-      # skipped entirely. Otherwise both go through #resolve_arg so Handles
-      # round-trip back to the host-side Ruby object before the call reaches
-      # +public_send+.
-      def resolve_call_args(arguments, handler, carried_handle)
-        return [arguments.args, arguments.kwargs] unless carried_handle
+      class << self
+        private
 
-        [arguments.args.map { |v| resolve_arg(v, handler) },
-         arguments.kwargs.transform_values { |v| resolve_arg(v, handler) }]
-      end
+        def run(call, resolver, handles, yielder)
+          arguments, carried_handle = decode_arguments(call.payload)
+          exposure = resolve_target(call.target, resolver, handles)
+          args, kwargs = resolve_call_args(arguments, handles, carried_handle)
+          invoke(exposure, call.method_name, args, kwargs, yielder)
+        end
 
-      # Map an error caught at the dispatch boundary to the message and the
-      # category the native side frames into the Reply's fault arm. +error+
-      # is the +StandardError+ caught by #dispatch's rescue; the category
-      # tells the guest which kind of failure it was so it can raise the
-      # matching proxy-side error.
-      #
-      # The class prefix marks a Service's own exception and nothing else:
-      # it is the +<class>: <message>+ shape a Host App is told to keep
-      # secrets out of, so wearing it says the Service raised. kobako's own
-      # refusals answer under their own wording instead of borrowing that
-      # shape.
-      #
-      # The guest's own block failing is not the Service's to report at
-      # all, so the Yielder that raised it is asked first — it recognises
-      # its own by identity and words the failure the guest's way.
-      def caught_fault(error, yielder)
-        block_failure = yielder&.fault_text(error)
-        return fault("block", block_failure) if block_failure
+        # A codec fault here is a request that never became a call, restated
+        # so it cannot read as an unwritable reply.
+        def decode_arguments(payload)
+          Kobako::Codec.track_handles { Payload::Arguments.decode(payload) }
+        rescue Kobako::Codec::Error => e
+          raise UnreadableRequestError, "Sandbox could not read the request: #{e.message}"
+        end
 
-        own = OWN_FAULTS.find { |klass, _| error.is_a?(klass) }
-        return fault(own.last, error.message) if own
+        def resolve_call_args(arguments, handles, carried_handle)
+          return [arguments.args, arguments.kwargs] unless carried_handle
 
-        fault("runtime", "#{error.class}: #{error.message}")
-      end
+          [arguments.args.map { |v| resolve_arg(v, handles) },
+           arguments.kwargs.transform_values { |v| resolve_arg(v, handles) }]
+        end
 
-      # Dispatch +method+ on the object behind +exposure+, once the Exposure
-      # the guest's reference carries permits it. +kwargs+ is already
-      # Symbol-keyed (the +Payload::Arguments+ 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.
-      #
-      # +yielder+ is the host-side Yielder materialised when the guest
-      # call site supplied a block; its Yielder#to_proc
-      # rides the +&block+ slot. +&nil+ is a no-op block argument in Ruby,
-      # so the same call site handles both cases without an explicit
-      # conditional.
-      def invoke(exposure, method, args, kwargs, yielder = nil)
-        name = method.to_sym
-        reject_unreachable!(exposure, name)
-        target = exposure.object
-        block = yielder&.to_proc
-        if kwargs.empty?
-          target.public_send(name, *args, &block)
-        else
-          target.public_send(name, *args, **kwargs, &block)
+        # The class prefix marks a Service's own exception that its category
+        # does not name: it is the +<class>: <message>+ shape a Host App is
+        # told to keep secrets out of, so wearing it says the Service raised.
+        #
+        # The guest's own block failing is not the Service's to report at
+        # all, so the Yielder that raised it is asked first — it recognises
+        # its own by identity and words the failure the guest's way.
+        def caught_fault(error, failure)
+          block_failure = failure.fault_text(error)
+          return fault("block", block_failure) if block_failure
+
+          bare = BARE_FAULTS.find { |klass, _| error.is_a?(klass) }
+          return fault(bare.last, error.message) if bare
+
+          fault("runtime", "#{error.class}: #{error.message}")
         end
-      end
 
-      # Guard the +public_send+ below: Reflection decides what counts as
-      # Service behaviour through this reference, and its refusal reason
-      # becomes the guest's +undefined+ fault. Both the ambient-surface
-      # floor and the reference's Exposure answer through it, so a rejected
-      # name discloses nothing about which of the two refused.
-      def reject_unreachable!(exposure, name)
-        reason = Reflection.refusal(exposure, name)
-        raise UndefinedTargetError, reason if reason
-      end
+        # The wire always carries a keyword map, so an empty one is left
+        # unsplatted for methods that take no keywords.
+        def invoke(exposure, method, args, kwargs, yielder)
+          name = method.to_sym
+          reject_unreachable!(exposure, name)
+          target = exposure.object
+          block = yielder&.to_proc
+          if kwargs.empty?
+            target.public_send(name, *args, &block)
+          else
+            target.public_send(name, *args, **kwargs, &block)
+          end
+        end
 
-      # Resolve every Kobako::Handle in an argument — bare or nested in an
-      # Array / Hash — back to its host object before the dispatch reaches
-      # +public_send+, symmetric with the guest→host return path. A Handle id
-      # with no live entry surfaces as an unrecognized target.
-      def resolve_arg(value, handler)
-        Kobako::Codec::HandleWalk.deep_restore(value, handler)
-      rescue Kobako::SandboxError => e
-        raise UndefinedTargetError, e.message
-      end
+        # Both the ambient-surface floor and the reference's Exposure answer
+        # through Reflection, so a rejected name discloses nothing about
+        # which of the two refused.
+        def reject_unreachable!(exposure, name)
+          reason = Reflection.refusal(exposure, name)
+          raise UndefinedTargetError, reason if reason
+        end
 
-      # Resolve a Call target to the Exposure the path +resolver+ (or
-      # Catalog::Handles) holds for it. The native side already
-      # discriminated the two forms off the core envelope's +kind+ tag: a
-      # String is a bound constant's path, an Integer is a Capability Handle
-      # id. No else-branch is needed — the envelope layer is the system
-      # boundary that enforces the invariant.
-      def resolve_target(target, resolver, handler)
-        case target
-        when String
-          resolve_path(target, resolver)
-        when Integer
-          resolve_handle(target, handler)
+        def resolve_arg(value, handles)
+          Kobako::Codec::HandleWalk.deep_restore(value, handles)
+        rescue Kobako::SandboxError => e
+          raise UndefinedTargetError, e.message
         end
-      end
 
-      def resolve_path(path, resolver)
-        resolver.lookup(path)
-      rescue KeyError => e
-        raise UndefinedTargetError, e.message
-      end
+        # The envelope already discriminated the two target forms, so no
+        # else-branch is needed.
+        def resolve_target(target, resolver, handles)
+          case target
+          when String
+            resolve_path(target, resolver)
+          when Integer
+            resolve_handle(target, handles)
+          end
+        end
 
-      # Resolve +id+ to the Exposure its Handle was minted with. An unknown
-      # id surfaces as UndefinedTargetError.
-      def resolve_handle(id, handler)
-        handler.exposure(id)
-      rescue Kobako::SandboxError => e
-        raise UndefinedTargetError, e.message
-      end
+        def resolve_path(path, resolver)
+          resolver.lookup(path)
+        rescue KeyError => e
+          raise UndefinedTargetError, e.message
+        end
 
-      # Encode +value+ as the body of a Reply's ok arm — the value alone,
-      # since the envelope's tag already carries the success. A value that
-      # is not wire-representable per the codec's type mapping raises
-      # +UnsupportedTypeError+; the rescue routes it through the
-      # Catalog::Handles via #wrap_as_handle and re-encodes with the
-      # Capability Handle in place. The happy path encodes exactly once.
-      #
-      # Any other codec fault is the answer failing to encode rather than the
-      # request failing to decode, and a Service is the only side that can
-      # change what it returns — so it is named here, where the direction is
-      # known, instead of falling to the boundary's codec floor and reporting
-      # as an exchange that produced no Service outcome.
-      def encode_ok(value, handler)
-        Kobako::Codec::Nesting.assert_within_bound!(value)
-        Kobako::Codec::Encoder.encode(value)
-      rescue Kobako::Codec::UnsupportedTypeError
-        encode_ok(wrap_as_handle(value, handler), handler)
-      rescue Kobako::Codec::Error => e
-        raise Kobako::SandboxError, "Sandbox could not write the Service's answer: #{e.message}"
-      end
+        def resolve_handle(id, handles)
+          handles.exposure(id)
+        rescue Kobako::SandboxError => e
+          raise UndefinedTargetError, e.message
+        end
 
-      # Allocate +value+ in the Sandbox's Catalog::Handles and return a +Handle+
-      # that the wire codec can carry. Used as the fallback path of
-      # #encode_ok when +value+ has no wire representation.
-      def wrap_as_handle(value, handler)
-        handler.alloc(value)
-      end
+        # A value with no wire form goes back as a Capability Handle. Any
+        # other codec fault is the answer failing to encode, which only the
+        # Service can change — so it is named here, where the direction is
+        # known, instead of falling to the boundary's codec floor.
+        def encode_ok(value, handles)
+          Kobako::Codec::Nesting.assert_within_bound!(value)
+          Kobako::Codec::Encoder.encode(value)
+        rescue Kobako::Codec::UnsupportedTypeError
+          encode_ok(handles.alloc(value), handles)
+        rescue Kobako::Codec::Error => e
+          raise Kobako::SandboxError, "Sandbox could not write the Service's answer: #{e.message}"
+        end
 
-      # +message+ folds to UTF-8 first: Ruby core builds some exception
-      # messages as ASCII-8BIT (the arity ArgumentError, for one), and
-      # the envelope requires UTF-8 of the text fields it frames.
-      def fault(type, message)
-        [message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace), type] # : [String, String]
+        # Ruby core builds some exception messages as ASCII-8BIT (the arity
+        # ArgumentError, for one), and the envelope requires UTF-8 of the
+        # text fields it frames.
+        def fault(type, message)
+          [message.encode(Encoding::UTF_8, invalid: :replace, undef: :replace), type] # : [String, String]
+        end
       end
     end
   end

data/lib/kobako/transport/error.rb

@@ -4,31 +4,17 @@ require_relative "../errors"
 
 module Kobako
   module Transport
-    # +Kobako::SandboxError+ subclass raised when the host detects a
-    # structural violation of the wire contract while reading what the
-    # guest produced — an invocation value the payload codec cannot
-    # decode. Distinct from a Wasm trap (engine signalled the guest
-    # runtime is unrecoverable) and from a normal sandbox-layer failure
-    # (the script raised but the protocol was respected): a
-    # +Transport::Error+ always indicates the guest runtime is corrupted —
-    # the only safe recovery is to discard the Sandbox and start a new
-    # invocation.
-    #
-    # Inherits from +Kobako::SandboxError+ so a single
-    # +rescue Kobako::SandboxError+ still catches it; callers that want
-    # to distinguish wire-violation paths from script failures can
-    # +rescue Kobako::Transport::Error+ directly.
+    # The guest broke the exchange with the host: it produced a value that
+    # could not be decoded, or a dispatch it made could not complete. Being a
+    # SandboxError, it is caught by rescuing that too.
     class Error < Kobako::SandboxError
-      def initialize(message, diagnostic: nil, **)
+      def initialize(message, diagnostic: nil, **) # :nodoc:
         super(message, **)
         @diagnostic = diagnostic
       end
 
-      # The codec fault behind this violation, appended to Ruby's own
-      # rendering. A caller cannot act on the inner "Symbol payload must
-      # be …" wording, so it stays out of #message; an operator
-      # triaging a corrupted runtime still needs it, and
-      # +detailed_message+ is where Ruby puts text of exactly that kind.
+      # Appends the codec's own reason, which an operator needs and a caller
+      # cannot act on, so #message leaves it out.
       def detailed_message(...)
         rendered = super
         return rendered if @diagnostic.nil?

data/lib/kobako/transport/exposure.rb

@@ -6,16 +6,11 @@ require_relative "reflection"
 
 module Kobako
   module Transport
-    # The methods a host object lets the guest call through one reference
-    # to it — a bound path or a Capability Handle — fixed when the reference
-    # is made. An object defining its own private +respond_to_guest?(name)+
-    # is asked on every dispatch; any other exposes only what its own class
-    # and the object itself define in source, since the methods a Host App
-    # cannot foresee handing over are the ones it never wrote.
-    #
-    # Built on the +class X < Data.define(...)+ subclass form so the class
-    # body is fully Steep-visible; see +.rubocop.yml+ for the rationale.
-    class Exposure < Data.define(:object, :names)
+    # The methods one reference lets the guest call, fixed when the reference
+    # is made. Only what the object's own class and the object define in
+    # source is exposed, since a Host App cannot foresee handing over what it
+    # never wrote.
+    class Exposure < Data.define(:object, :names) # :nodoc:
       PREDICATE = :respond_to_guest?
       private_constant :PREDICATE
 
@@ -73,7 +68,7 @@ module Kobako
         end
 
         def class_names(object, klass)
-          names = authored(klass)
+          names = authored_names(klass)
           case object
           when Struct, Data then names.concat(object.members)
           end
@@ -83,15 +78,13 @@ module Kobako
         def with_singleton(object, names)
           return names if SINGLETON_METHODS.bind_call(object, false).empty?
 
-          names.union(authored(SINGLETON_CLASS_OF.bind_call(object))).freeze
+          names.union(authored_names(SINGLETON_CLASS_OF.bind_call(object))).freeze
         end
 
-        # The public methods +owner+ itself defines in source. A method with
-        # no source, or whose source is the platform's own, is built in.
-        def authored(owner)
+        # The public methods +owner+ itself defines in Ruby source.
+        def authored_names(owner)
           owner.public_instance_methods(false).select do |name|
-            file, = owner.instance_method(name).source_location
-            file && !file.start_with?("<internal:")
+            Reflection.authored?(owner.instance_method(name))
           end
         end
       end