kobako 0.28.0 → 0.30.0

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 service_refusal(name) if name == :method_missing
+
+          klass = lookup_class(target)
+          return public_method_refusal(target, name, klass) if klass.public_method_defined?(name)
+          return "no public method #{name.inspect} on target" unless target.respond_to?(name)
+          return service_refusal(name) if klass.method_defined?(name) || klass.private_method_defined?(name)
 
-          owner = target.public_method(name).owner
+          owner_refusal(target, name, klass)
+        end
+
+        def public_method_refusal(target, name, klass)
+          method = klass.instance_method(name)
+          owner_refusal(target, name, method.owner) ||
+            (authored_for?(target, name, method, klass) ? nil : service_refusal(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 service_refusal(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)
+          service_refusal(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/run.rb

@@ -12,8 +12,8 @@ module Kobako
     class Run < Data.define(:entrypoint, :args, :kwargs) # :nodoc:
       def initialize(entrypoint:, args: [], kwargs: {})
         entrypoint = normalize_entrypoint(entrypoint)
-        validate_args!(args)
-        validate_kwargs!(kwargs)
+        validate_args(args)
+        validate_kwargs(kwargs)
         super
       end
 
@@ -21,7 +21,7 @@ module Kobako
       # invocation's table. The walk starts one level down, since +args+ and
       # +kwargs+ ride inside the payload document the wire's nesting bound
       # is counted from.
-      def payload(handles)
+      def encode_payload(handles)
         Payload::Arguments.new(
           args: Codec::HandleWalk.deep_wrap(args, handles, 1),
           kwargs: Codec::HandleWalk.deep_wrap(kwargs, handles, 1)
@@ -46,14 +46,14 @@ module Kobako
         target_str.to_sym
       end
 
-      def validate_args!(args)
+      def validate_args(args)
         raise ArgumentError, "arguments must be an Array" unless args.is_a?(Array)
         raise ArgumentError, forged_handle_message("arguments") if args.any?(Kobako::Handle)
       end
 
       # Checked here so the Host App sees the host-side message before any
       # encode boundary.
-      def validate_kwargs!(kwargs)
+      def validate_kwargs(kwargs)
         raise ArgumentError, "keyword arguments must be a Hash" unless kwargs.is_a?(Hash)
 
         bad_keys = kwargs.each_key.grep_v(Symbol)

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
 
@@ -58,18 +42,12 @@ module Kobako
       # Restated so the Service reads a refusal of its own argument rather
       # than a codec class it never named.
       def encode_args(args)
-        Kobako::Codec::Nesting.assert_within_bound!(args)
+        Kobako::Codec::Nesting.assert_within_bound(args)
         Kobako::Codec::Encoder.encode(args)
       rescue Kobako::Codec::Error => e
         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.30.0"
 end

data/lib/kobako.rb

@@ -1,5 +1,39 @@
 # frozen_string_literal: true
 
+# Inside +lib/+, the code sits in tiers: a tier may use the tiers below it
+# and never one above.
+#
+#   Orchestration   Sandbox, Pool, Runtime (+ ext), Context
+#         |
+#   Catalog         setup-time registries + the per-invocation Handle table
+#         |
+#   Transport --+   call value objects + dispatch
+#   Outcome ----+   guest-result attribution
+#         |     |
+#   Payload <---+   the [args, kwargs] shape a Call or Run carries
+#         |     |
+#   Codec <-----+   byte-level payload wire
+#         |
+#   Root            dependency-free value objects and error classes
+#
+# The Envelope has no tier here, because the native side frames and
+# decodes it.
+#
+# These rules keep the tiers acyclic:
+#
+# [A type sits at the lowest tier that needs it]
+#   Kobako::Handle sits at the root, for Codec.
+# [A native-defined handle that needs nothing in +lib/+ sits at the root]
+#   Kobako::Filesystem sits at the root, for the Catalog.
+# [Outcome may require <tt>transport/error.rb</tt>]
+#   The gem contract fixes the class name.
+# [<tt>Codec.track_handles</tt> wraps only the decode call]
+#   Wrapping more leaks its flag into re-entry.
+#
+# Namespace follows dependency direction, not which tier reads a type most.
+# Kobako::Transport::Error stays in Transport despite the lateral edge from
+# Outcome, because its file depends only on the root <tt>errors.rb</tt>.
+
 require_relative "kobako/version"
 
 begin
@@ -9,6 +43,7 @@ rescue LoadError
   require "kobako/kobako"
 end
 
+require_relative "kobako/filesystem"
 require_relative "kobako/errors"
 require_relative "kobako/unresolved"
 require_relative "kobako/extension"

data/release-please-config.json

@@ -2,6 +2,7 @@
   "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
   "release-type": "ruby",
   "bump-minor-pre-major": true,
+  "commit-search-depth": 1000,
   "last-release-sha": "98509af508988f708bf0d7a76a718bb0428a177e",
   "packages": {
     ".": {

data/sig/kobako/catalog/extensions.rbs

@@ -5,17 +5,17 @@ module Kobako
 
       def install: (untyped extension, snippets: Kobako::Catalog::Snippets, services: Kobako::Catalog::Services) -> self
 
-      def assert_dependencies!: () -> self
+      def assert_dependencies: () -> self
 
       def resolve: () -> Hash[String, untyped]
 
       private
 
-      def install_object: (untyped backend) -> untyped
+      def object_of: (untyped backend) -> untyped
 
       def resolve_backend: (untyped extension, Hash[String, untyped] resolved, Hash[untyped, untyped] by_provider) -> void
 
-      def validate!: (untyped extension) -> void
+      def validate: (untyped extension) -> void
 
       def unmet_dependency: () -> [untyped, untyped]?
 

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/handles.rbs

@@ -13,11 +13,11 @@ module Kobako
 
       private
 
-      def reject_unwrappable!: (untyped object) -> void
+      def reject_unwrappable: (untyped object) -> void
 
-      def ensure_capacity!: () -> void
+      def ensure_capacity: () -> void
 
-      def require_bound!: (Integer id) -> void
+      def require_bound: (Integer id) -> void
     end
   end
 end

data/sig/kobako/catalog/mount.rbs

@@ -0,0 +1,24 @@
+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
+    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
@@ -13,7 +15,9 @@ module Kobako
 
       private
 
-      def validate_path!: (Symbol | String path) -> String
+      def validate_path: (Symbol | String path) -> String
+
+      def reserved?: (String path) -> bool
 
       def collision?: (String path) -> bool
     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]
 
@@ -15,11 +15,11 @@ module Kobako
 
       private
 
-      def register_source!: (String? code, (Symbol | String)? name) -> nil
+      def register_source: (String? code, (Symbol | String)? name) -> nil
 
-      def ensure_source_args!: (String? code, (Symbol | String)? name) -> [String, Symbol | String]
+      def ensure_source_args: (String? code, (Symbol | String)? name) -> [String, Symbol | String]
 
-      def register_binary!: (String bytes) -> nil
+      def register_binary: (String bytes) -> nil
 
       def entry_tuple: (entry) -> tuple
 

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/decoder.rbs

@@ -6,7 +6,7 @@ module Kobako
 
       private
 
-      def self.validate_utf8!: (untyped value) -> void
+      def self.validate_utf8: (untyped value) -> void
     end
   end
 end

data/sig/kobako/codec/handle_walk.rbs

@@ -11,7 +11,7 @@ module Kobako
 
       private
 
-      def self.guard_nesting!: (Integer depth) -> void
+      def self.guard_nesting: (Integer depth) -> void
 
       def self.deep_wrap_hash: (Hash[untyped, untyped] hash, Kobako::Codec::_HandleTable handles, Integer depth) -> Hash[untyped, untyped]
 

data/sig/kobako/codec/nesting.rbs

@@ -1,9 +1,9 @@
 module Kobako
   module Codec
     module Nesting
-      def self.assert_within_bound!: (untyped value, ?Integer depth) -> void
+      def self.assert_within_bound: (untyped value, ?Integer depth) -> void
 
-      def self.assert_members_within_bound!: (Array[untyped] members, Integer depth) -> void
+      def self.assert_members_within_bound: (Array[untyped] members, Integer depth) -> void
     end
   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/utils.rbs

@@ -1,7 +1,7 @@
 module Kobako
   module Codec
     module Utils
-      def self.assert_utf8!: (String string, String label) -> void
+      def self.assert_utf8: (String string, String label) -> void
 
       def self.with_boundary: [T] () { () -> T } -> T
     end

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

@@ -2,8 +2,7 @@ module Kobako
   module Codec
     MAX_NESTING_DEPTH: Integer
 
-    # A value in the closed wire type set (docs/wire/payload-msgpack.md
-    # § Type Mapping): the scalar leaves, a Capability Handle, and Array / Hash
+    # A value in the closed wire type set: the scalar leaves, a Capability Handle, and Array / Hash
     # containers of the same. The by-value payloads that cross the wire —
     # dispatch arguments and success values — inhabit this type; a Fault is
     # an envelope shape, not a wire_value.
@@ -14,6 +13,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