kobako 0.28.0-aarch64-linux → 0.29.0-aarch64-linux

data/lib/kobako/transport/dispatcher.rb

@@ -3,18 +3,20 @@
 require_relative "../codec"
 require_relative "../errors"
 require_relative "../payload"
+require_relative "block_failure"
 require_relative "call"
 require_relative "reflection"
 require_relative "yielder"
 
 module Kobako
   module Transport
-    # 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.
+    # 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:
-      # Throw tag for the Yielder's break unwind back to the
-      # dispatcher's +catch+ frame. +private_constant+ is a
+      # 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
@@ -23,15 +25,18 @@ module Kobako
 
       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
-      # 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",
@@ -40,23 +45,24 @@ module Kobako
         Kobako::Codec::Error => "internal",
         Kobako::SandboxError => "runtime"
       }.freeze
-      private_constant :OWN_FAULTS
+      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, 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?]
+      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!
+        yielder&.invalidate
       end
 
       class << self
@@ -66,7 +72,7 @@ module Kobako
           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) }
+          invoke(exposure, call.method_name, args, kwargs, yielder)
         end
 
         # A codec fault here is a request that never became a call, restated
@@ -84,21 +90,19 @@ module Kobako
            arguments.kwargs.transform_values { |v| resolve_arg(v, handles) }]
         end
 
-        # 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 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, yielder)
-          block_failure = yielder&.fault_text(error)
+        def caught_fault(error, failure)
+          block_failure = failure.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
+          bare = BARE_FAULTS.find { |klass, _| error.is_a?(klass) }
+          return fault(bare.last, error.message) if bare
 
           fault("runtime", "#{error.class}: #{error.message}")
         end

data/lib/kobako/transport/exposure.rb

@@ -68,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
@@ -78,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

data/lib/kobako/transport/reflection.rb

@@ -3,17 +3,6 @@
 module Kobako
   module Transport
     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
-      # behaviour. A guest-supplied method name resolving to one of these is
-      # rejected: only methods the bound object itself exposes as Service
-      # behaviour are reachable, and +public_send(:send, ...)+ would
-      # otherwise let a guest pivot through +send+ into the private
-      # +Kernel#eval+ / +#system+ surface (host RCE).
-      META_OWNERS = [BasicObject, Kernel, Object, Module, Class].freeze
-      private_constant :META_OWNERS
-
       # Callable gadget types whose own public methods are reflection surface
       # (+Proc#binding+ reaches +Binding#eval+, +Method#receiver+ / +#unbind+
       # hand back the underlying object) rather than Service behaviour. Only
@@ -37,11 +26,33 @@ module Kobako
           (exposure.exposes?(name) ? nil : "method #{name.inspect} is not exposed to the guest")
       end
 
+      # Whether +method+ is written in Ruby rather than built into the
+      # platform or copied from the surface every object shares. A native
+      # method has no source, and a built-in one names an +<internal:>+ file,
+      # so a copy, alias or rebinding of either keeps that mark wherever it
+      # is reached from.
+      def self.authored?(method)
+        file, = method.source_location
+        !file.nil? && !file.start_with?("<internal:") && !ambient_copy?(method)
+      end
+
       class << self
         private
 
+        # Whether +method+ is a copy, alias or rebinding of a Ruby method
+        # +Class+ inherits, such as the +name!+ alias OpenStruct makes of a
+        # mixed-in +try+. The copy is owned by the class that made it, but
+        # keeps the original's name and source.
+        def ambient_copy?(method)
+          name = method.original_name
+          Class.ancestors.any? do |owner|
+            (owner.method_defined?(name, false) || owner.private_method_defined?(name, false)) &&
+              owner.instance_method(name).source_location == method.source_location
+          end
+        end
+
         # Guard against ambient reflection methods. A public method whose
-        # owner is a META_OWNERS or GADGET_OWNERS module — or a singleton
+        # owner +Class+ inherits or a 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
@@ -55,26 +66,71 @@ module Kobako
         # +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+.
+        # which resolves through the +respond_to?+ opt-in, never by naming
+        # +method_missing+.
+        #
+        # A public method must also be authored, so a Service narrowing itself
+        # never reaches a built-in or ambient method by a copy, alias or
+        # rebinding an owner check cannot see; a non-public one is never
+        # reached through a dynamic opt-in either.
+        #
+        # A name with no method never reaches +instance_method+, which would
+        # keep a guest-chosen name as a Symbol for the life of the process.
         def ambient_refusal(target, name)
-          return "method #{name.inspect} is not a Service method" if name == :method_missing
+          return refused(name) if name == :method_missing
+
+          klass = lookup_class(target)
+          return defined_refusal(target, name, klass) if klass.public_method_defined?(name)
+          return "no public method #{name.inspect} on target" unless target.respond_to?(name)
+          return refused(name) if klass.method_defined?(name) || klass.private_method_defined?(name)
 
-          owner = target.public_method(name).owner
+          owner_refusal(target, name, klass)
+        end
+
+        def defined_refusal(target, name, klass)
+          method = klass.instance_method(name)
+          owner_refusal(target, name, method.owner) ||
+            (authored_for?(target, name, method, klass) ? nil : refused(name))
+        end
+
+        # A bound callable keeps its callable names and a record its member
+        # readers, though the platform defines both.
+        def authored_for?(target, name, method, klass)
+          return true if Reflection.authored?(method)
+          return true if GADGET_OWNERS.include?(method.owner) && CALLABLE_ALLOW.include?(name)
+
+          (klass <= Struct || klass <= Data) && target.members.include?(name)
+        end
+
+        def refused(name)
+          "method #{name.inspect} is not a Service method"
+        end
+
+        def owner_refusal(target, name, owner)
           return nil unless ambient_owner?(owner, target)
           return nil if GADGET_OWNERS.include?(owner) && CALLABLE_ALLOW.include?(name)
 
-          "method #{name.inspect} is not a Service method"
-        rescue NameError
-          return nil if target.respond_to?(name)
+          refused(name)
+        end
+
+        # The class a method lookup on +target+ starts at. A plain object's
+        # singleton class is taken only when it already holds a public
+        # method, since asking for it otherwise would create one.
+        def lookup_class(target)
+          return target.singleton_class if target.is_a?(Module) || target.singleton_methods.any?
 
-          "no public method #{name.inspect} on target"
+          target.class
         end
 
-        # A plain object's own singleton method (+def obj.x+) stays reachable,
-        # since only a Module target counts its singleton class as ambient.
+        # Whatever +Class+ inherits is surface every object shares rather
+        # than Service behaviour: the reflection +BasicObject+ through +Class+
+        # define (+send+ pivots into +Kernel#eval+, a host RCE), and every
+        # module a library mixes into them, such as a +try+ dispatching by
+        # name or a +to_json+ dumping instance variables. 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) ||
+          owner >= Class ||
             GADGET_OWNERS.include?(owner) ||
             (target.is_a?(Module) && owner.singleton_class?)
         end

data/lib/kobako/transport/yielder.rb

@@ -6,50 +6,34 @@ require_relative "../errors"
 module Kobako
   module Transport
     class Yielder # :nodoc:
-      def initialize(guest_yielder, break_tag, handles)
+      def initialize(guest_yielder, break_tag, handles, failure)
         @guest_yielder = guest_yielder
         @break_tag = break_tag
         @handles = handles
+        @failure = failure
         @active = true
-        @raised = nil
-      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
 
       # The ok value is consumed by the host Service, so a Capability Handle
-      # in it is restored. The break value unwinds back to the guest, so it
-      # passes through verbatim and rides back on the same id rather than
-      # churning a new one.
+      # in it is restored. A block exit stays in the guest, so the Service
+      # is only unwound.
       def yield(*args)
         raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
 
         arm, body, klass = @guest_yielder.call(encode_args(args))
         raise UnsupportedError, "the Sandbox runtime does not support yielding to a block" if arm == :unsupported
-        raise remember(BlockError.new(body, klass: klass)) if arm == :error
+        raise @failure.remember(BlockError.new(body, klass: klass)) if arm == :error
 
-        value, carried_handle = decode_body(body)
-        throw @break_tag, value if arm == :break
+        throw @break_tag if arm == :break
 
-        restore(value, carried_handle)
+        restore(*decode_body(body))
       end
 
       def to_proc
         method(:yield).to_proc
       end
 
-      def invalidate!
+      def invalidate
         @active = false
       end
 
@@ -64,12 +48,6 @@ module Kobako
         raise YieldValueError, "Service yielded a value the block cannot receive: #{e.message}"
       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
-
       # The tracking bracket opens only around this decode: the guest
       # re-entry may run nested dispatches whose own brackets would
       # otherwise pollute the signal.

data/lib/kobako/transport.rb

@@ -2,6 +2,7 @@
 
 require_relative "transport/call"
 require_relative "transport/run"
+require_relative "transport/block_failure"
 require_relative "transport/yielder"
 require_relative "transport/error"
 require_relative "transport/exposure"

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.28.0"
+  VERSION = "0.29.0"
 end

data/lib/kobako.rb

@@ -9,6 +9,7 @@ rescue LoadError
   require "kobako/kobako"
 end
 
+require_relative "kobako/filesystem"
 require_relative "kobako/errors"
 require_relative "kobako/unresolved"
 require_relative "kobako/extension"

data/sig/kobako/catalog/flags.rbs

@@ -8,10 +8,6 @@ module Kobako
       def entries: () -> Array[tuple]
 
       def register: (Symbol | String name, String value, advisory: bool) -> nil
-
-      private
-
-      def utf8!: (String text, String what) -> String
     end
   end
 end

data/sig/kobako/catalog/grants.rbs

@@ -0,0 +1,13 @@
+module Kobako
+  module Catalog
+    class Grants
+      def initialize: () -> void
+
+      def register: (Mount grant) -> nil
+
+      def include?: (Mount grant) -> bool
+
+      def entries: (?Hash[String, Mount] overrides) -> Array[Mount::tuple]
+    end
+  end
+end

data/sig/kobako/catalog/mount.rbs

@@ -0,0 +1,28 @@
+module Kobako
+  module Catalog
+    class Mount < Data
+      type access = Kobako::Filesystem::access
+
+      type policy = ^(String path, access access) -> boolish
+
+      type tuple = [String, access, Kobako::Filesystem::mountable, policy?]
+
+      attr_reader at: String
+      attr_reader access: access
+      attr_reader filesystem: Kobako::Filesystem::mountable
+      attr_reader policy: policy?
+
+      def self.new: (at: untyped, access: untyped, filesystem: untyped, policy: policy?) -> Mount
+
+      def key: () -> String
+
+      def conflict: (Mount other) -> String?
+
+      def to_native: () -> tuple
+
+      private
+
+      def nested?: (String other) -> bool
+    end
+  end
+end

data/sig/kobako/catalog/services.rbs

@@ -1,6 +1,8 @@
 module Kobako
   module Catalog
     class Services
+      RESERVED_NAMESPACE: String
+
       def initialize: () -> void
 
       def bind: (Symbol | String path, untyped object) -> self
@@ -15,6 +17,8 @@ module Kobako
 
       def validate_path!: (Symbol | String path) -> String
 
+      def reserved?: (String path) -> bool
+
       def collision?: (String path) -> bool
     end
   end

data/sig/kobako/catalog/snippets.rbs

@@ -1,7 +1,7 @@
 module Kobako
   module Catalog
     class Snippets
-      type entry = Kobako::Snippet::Source | Kobako::Snippet::Binary
+      type entry = Kobako::Snippet::Source | Kobako::Snippet::Bytecode
 
       type tuple = [Symbol, String?, String]
 

data/sig/kobako/catalog.rbs

@@ -1,4 +1,5 @@
 module Kobako
   module Catalog
+    def self.to_utf8!: (String text, String what) -> String
   end
 end

data/sig/kobako/codec/state.rbs

@@ -5,8 +5,14 @@ module Kobako
 
       def self.current: () -> State
 
+      @carried_handle: bool
+      @value_budget: Integer?
+
+      attr_reader value_budget: Integer?
+
       def track_handles: [T] { () -> T } -> [T, bool]
-      def record_handle!: () -> void
+      def record_handle: () -> void
+      def within_value_budget: [T] (Integer? budget) { () -> T } -> T
 
       private
 

data/sig/kobako/codec/value_budget.rbs

@@ -0,0 +1,23 @@
+module Kobako
+  module Codec
+    module ValueBudget
+      SCALARS: Hash[Integer, Integer]
+
+      COUNTS: Hash[Integer, [Integer, Integer]]
+
+      LENGTHS: Hash[Integer, [Integer, Integer]]
+
+      UINT: Hash[Integer, String]
+
+      def self.assert_within!: (String bytes, Integer? budget) -> void
+
+      private
+
+      def self.step: (String bytes, Integer pos) -> [Integer?, Integer]
+
+      def self.step_framed:(String bytes, Integer pos, Integer marker) -> [Integer?, Integer]
+
+      def self.uint: (String bytes, Integer pos, Integer width) -> Integer
+    end
+  end
+end

data/sig/kobako/codec.rbs

@@ -14,6 +14,8 @@ module Kobako
 
     def self.track_handles: [T] { () -> T } -> [T, bool]
 
+    def self.within_value_budget: [T] (Integer? budget) { () -> T } -> T
+
     # The Handle allocator/resolver a wire walk works against: alloc
     # registers a non-wire-representable object and returns its Handle,
     # fetch resolves a wire Handle id back to the live object. The

data/sig/kobako/context.rbs

@@ -1,15 +1,21 @@
 module Kobako
   class Context
+    type preamble = [Array[String], Array[Kobako::Catalog::Snippets::tuple], Array[Kobako::Catalog::Flags::tuple]]
+
+    @mounts: Hash[String, Kobako::Catalog::Mount]?
+
     def initialize: (
       runtime: Kobako::Runtime,
       services: Kobako::Catalog::Services,
-      snippets: Kobako::Catalog::Snippets,
-      flags: Kobako::Catalog::Flags,
-      extensions: Kobako::Catalog::Extensions
+      extensions: Kobako::Catalog::Extensions,
+      grants: Kobako::Catalog::Grants,
+      preamble: preamble
     ) -> void
 
     def bind: (Symbol | String path, untyped object) -> self
 
+    def mount: (String at, Kobako::Filesystem::mountable filesystem, ?access: Kobako::Filesystem::access) ?{ (String path, Kobako::Filesystem::access access) -> boolish } -> self
+
     def lookup: (Symbol | String path) -> Kobako::Transport::Exposure
 
     def eval: (String code) ?{ (Kobako::Context) -> void } -> Kobako::Execution
@@ -18,18 +24,20 @@ module Kobako
 
     private
 
+    def setup: () -> Kobako::Runtime::setup
+
     def collect_overrides: () { (Kobako::Context) -> void } -> void
 
     def dispatch_handler: () -> Kobako::Transport::dispatch_proc
 
-    def populate_observability!: (Kobako::Runtime::Snapshot snapshot) -> void
+    def populate_observability:(Kobako::Snapshot snapshot) -> void
 
     def with_verb: (Kobako::TrapError err, Symbol verb) -> Kobako::TrapError
 
     def build_execution: (untyped value, failed: bool) -> Kobako::Execution
 
-    def settle_outcome: (Kobako::Runtime::Snapshot snapshot, Symbol verb, Symbol? entrypoint) -> Kobako::Execution
+    def settle_outcome: (Kobako::Snapshot snapshot, Symbol verb, Symbol? entrypoint) -> Kobako::Execution
 
-    def invoke!: (Symbol verb, ?entrypoint: Symbol?) { () -> Kobako::Runtime::Snapshot } -> Kobako::Execution
+    def invoke!: (Symbol verb, ?entrypoint: Symbol?) { () -> Kobako::Snapshot } -> Kobako::Execution
   end
 end

data/sig/kobako/errors.rbs

@@ -2,14 +2,14 @@ module Kobako
   class Error < StandardError
   end
 
-  module CarriesExecution
+  module Recorded
     attr_reader execution: Kobako::Execution?
 
     def with_execution: (Kobako::Execution execution) -> self
   end
 
   class TrapError < Error
-    include CarriesExecution
+    include Recorded
   end
 
   class TimeoutError < TrapError
@@ -39,12 +39,12 @@ module Kobako
 
   class SandboxError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   class ServiceError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
   class NoServiceError < ServiceError