kobako 0.27.0 → 0.28.0

data/lib/kobako/transport/dispatcher.rb

@@ -8,39 +8,20 @@ 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
+    # Answers a routed Call with +[true, body, nil]+ or
+    # +[false, message, fault_type]+ and never raises, so every failure
+    # reaches the guest as a fault.
+    module Dispatcher # :nodoc:
       # Throw tag for the Yielder's break unwind back to the
       # dispatcher's +catch+ frame. +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
-
-      # 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
+      class UnreadableRequestError < Kobako::Codec::Error; end # :nodoc:
 
       # The category kobako's own refusals answer under, keyed by the class
       # each is raised as and ordered most specific first. A class absent
@@ -55,30 +36,18 @@ module Kobako
         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?]
+      # 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, guest_yielder)
+        yielder = Yielder.new(guest_yielder, BREAK_THROW, handles) if call.block_given
+        [true, encode_ok(run(call, resolver, handles, yielder), handles), nil] # : [bool, 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)
@@ -90,172 +59,120 @@ module Kobako
         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}"
-      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)
+          catch(BREAK_THROW) { 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 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
+
+          own = OWN_FAULTS.find { |klass, _| error.is_a?(klass) }
+          return fault(own.last, error.message) if own
+
+          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
 

data/lib/kobako/transport/reflection.rb

@@ -2,15 +2,7 @@
 
 module Kobako
   module Transport
-    # The reflection floor a guest→host dispatch must clear before the
-    # Dispatcher reaches +public_send+: which method names on a resolved
-    # target count as Service behaviour, and which are Ruby's ambient
-    # metaprogramming surface.
-    #
-    # Answers with a refusal reason rather than raising, so the error
-    # taxonomy stays with the Dispatcher and this module holds only the
-    # policy.
-    module Reflection
+    module Reflection # :nodoc:
       # Modules whose instance methods are ambient Ruby reflection /
       # metaprogramming surface (+send+, +public_send+, +instance_eval+,
       # +method+, +tap+, +instance_variable_get+, ...) rather than Service
@@ -36,59 +28,56 @@ module Kobako
       # callable exposes by default, so the floor and the Exposure agree.
       CALLABLE_ALLOW = %i[call [] yield arity lambda?].freeze
 
-      module_function
-
       # The reason +name+ is unreachable through +exposure+, or +nil+ when
       # the dispatch may proceed. Composes the ambient-surface floor with the
       # reference's Exposure, in that order: the Exposure only narrows and
       # can never re-open what the floor rejects.
-      def refusal(exposure, name)
+      def self.refusal(exposure, name)
         ambient_refusal(exposure.object, name) ||
           (exposure.exposes?(name) ? nil : "method #{name.inspect} is not exposed to the guest")
       end
 
-      # Guard against ambient reflection methods. A public method whose
-      # owner is a META_OWNERS or GADGET_OWNERS module — or a singleton
-      # class, the owner of every class-level method (+File.popen+ /
-      # +Kernel.system+, unreachable via any fixed core-module list) — is
-      # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
-      # stays invocable). A name with no concrete public method is allowed
-      # only when the target opts into it via +respond_to?+ (dynamic
-      # +method_missing+ Services), since the dangerous methods are all
-      # concretely defined and therefore never reach that branch.
-      #
-      # +method_missing+ named explicitly is refused whatever its owner:
-      # it is Ruby's dynamic-dispatch hook, and a public override (a
-      # +Delegator+) binds and calls the private method the guest passes as
-      # its first argument (+Kernel#system+). A dynamic +method_missing+
-      # Service is untouched — the guest reaches it by the virtual name,
-      # which resolves through the +NameError+ branch below, never by
-      # naming +method_missing+.
-      def ambient_refusal(target, name)
-        return "method #{name.inspect} is not a Service method" if name == :method_missing
+      class << self
+        private
 
-        owner = target.public_method(name).owner
-        return nil unless ambient_owner?(owner, target)
-        return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
+        # Guard against ambient reflection methods. A public method whose
+        # owner is a META_OWNERS or GADGET_OWNERS module — or a singleton
+        # class, the owner of every class-level method (+File.popen+ /
+        # +Kernel.system+, unreachable via any fixed core-module list) — is
+        # rejected, except CALLABLE_ALLOW on a gadget target (a bound lambda
+        # stays invocable). A name with no concrete public method is allowed
+        # only when the target opts into it via +respond_to?+ (dynamic
+        # +method_missing+ Services), since the dangerous methods are all
+        # concretely defined and therefore never reach that branch.
+        #
+        # +method_missing+ named explicitly is refused whatever its owner:
+        # it is Ruby's dynamic-dispatch hook, and a public override (a
+        # +Delegator+) binds and calls the private method the guest passes as
+        # its first argument (+Kernel#system+). A dynamic +method_missing+
+        # Service is untouched — the guest reaches it by the virtual name,
+        # which resolves through the +NameError+ branch below, never by
+        # naming +method_missing+.
+        def ambient_refusal(target, name)
+          return "method #{name.inspect} is not a Service method" if name == :method_missing
 
-        "method #{name.inspect} is not a Service method"
-      rescue NameError
-        return nil if target.respond_to?(name)
+          owner = target.public_method(name).owner
+          return nil unless ambient_owner?(owner, target)
+          return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
 
-        "no public method #{name.inspect} on target"
-      end
+          "method #{name.inspect} is not a Service method"
+        rescue NameError
+          return nil if target.respond_to?(name)
+
+          "no public method #{name.inspect} on target"
+        end
 
-      # Whether +name+'s +owner+ is ambient surface rather than Service
-      # behaviour: a core meta module, a callable gadget type, or — when
-      # +target+ is itself a Class or Module bound as a Service — the
-      # singleton class that owns its class-level API (+File.popen+ /
-      # +Kernel.system+, unreachable via any fixed core-module list). A plain
-      # object's own singleton method (+def obj.x+) stays reachable, since
-      # +target+ is not a Module there.
-      def ambient_owner?(owner, target)
-        META_OWNERS.include?(owner) ||
-          GADGET_OWNERS.include?(owner) ||
-          (target.is_a?(Module) && owner.singleton_class?)
+        # A plain object's own singleton method (+def obj.x+) stays reachable,
+        # since only a Module target counts its singleton class as ambient.
+        def ambient_owner?(owner, target)
+          META_OWNERS.include?(owner) ||
+            GADGET_OWNERS.include?(owner) ||
+            (target.is_a?(Module) && owner.singleton_class?)
+        end
       end
     end
   end