kobako 0.27.0 → 0.29.0

data/lib/kobako/codec/utils.rb

@@ -4,45 +4,17 @@ require_relative "error"
 
 module Kobako
   module Codec
-    # Byte-boundary helpers shared by the host-side encoder and decoder.
-    # Two concerns live here:
-    #
-    #   - UTF-8 assertion at the codec boundary
-    #     ({docs/wire-codec.md}[link:../../../docs/wire-codec.md]
-    #     § str/bin Encoding Rules and § Ext Types → ext 0x00). Used by
-    #     Decoder when walking +str+ family payloads and by ExtTypes
-    #     when validating the +ext 0x00+ Symbol payload.
-    #   - +ArgumentError+ translation at the codec boundary
-    #     (#with_boundary) so the public taxonomy stays
-    #     Kobako::Codec::Error.
-    #
-    # Both helpers are pure — they only inspect inputs, never mutate them.
-    # The host↔guest Handle substitution walk lives in HandleWalk.
-    module Utils
-      module_function
-
-      # Raise InvalidEncodingError unless +string+'s bytes are valid under
-      # its current encoding tag. +label+ is the caller-supplied prefix
-      # for the error message (e.g. +"str payload"+, +"Symbol payload"+).
-      def assert_utf8!(string, label)
+    module Utils # :nodoc:
+      def self.assert_utf8!(string, label)
         return if string.valid_encoding?
 
         raise InvalidEncodingError, "#{label} is not valid UTF-8"
       end
 
-      # Run +block+ at the codec boundary: a value object raises
-      # +ArgumentError+ when an invariant is violated at construction, and
-      # this helper surfaces that as InvalidTypeError so the public taxonomy
-      # stays Kobako::Codec::Error and never leaks +ArgumentError+ from
-      # the Ruby standard library.
-      #
-      # Reach for this only where a value object is constructed outside a
-      # Decoder.decode block, whose rescue already performs the same
-      # mapping (worked example: ExtTypes#unpack_handle building
-      # +Handle.restore+ from a raw fixext payload). Do not use it for
-      # general-purpose validation outside the codec boundary —
-      # host-layer +ArgumentError+ values should propagate unchanged.
-      def with_boundary
+      # Only for a value object built outside a Decoder.decode block, whose
+      # rescue already maps the same way; a host-layer +ArgumentError+
+      # elsewhere should propagate unchanged.
+      def self.with_boundary
         yield
       rescue ::ArgumentError => e
         raise InvalidTypeError, e.message

data/lib/kobako/codec/value_budget.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Kobako
+  module Codec
+    # Counts the values a payload holds before the decoder builds any, so a
+    # guest cannot make the host build more objects than its budget allows
+    # (docs/wire/payload-msgpack.md § Value Budget). Every value takes at
+    # least one byte, so a payload no longer than the budget needs no count.
+    #
+    # The count stops at the first byte it cannot frame and leaves that
+    # payload for the decoder to refuse in its own words.
+    module ValueBudget # :nodoc:
+      # Marker to the body width of a scalar with no length field.
+      SCALARS = {
+        0xc0 => 0, 0xc2 => 0, 0xc3 => 0, 0xca => 4, 0xcb => 8,
+        0xcc => 1, 0xcd => 2, 0xce => 4, 0xcf => 8,
+        0xd0 => 1, 0xd1 => 2, 0xd2 => 4, 0xd3 => 8,
+        0xd4 => 2, 0xd5 => 3, 0xd6 => 5, 0xd7 => 9, 0xd8 => 17
+      }.freeze
+      # Marker to a container's count width and the values each entry holds.
+      COUNTS = { 0xdc => [2, 1], 0xdd => [4, 1], 0xde => [2, 2], 0xdf => [4, 2] }.freeze
+      # Marker to a str, bin, or ext's length width and type tag width.
+      LENGTHS = {
+        0xc4 => [1, 0], 0xc5 => [2, 0], 0xc6 => [4, 0],
+        0xd9 => [1, 0], 0xda => [2, 0], 0xdb => [4, 0],
+        0xc7 => [1, 1], 0xc8 => [2, 1], 0xc9 => [4, 1]
+      }.freeze
+      UINT = { 1 => "C", 2 => "n", 4 => "N" }.freeze
+      private_constant :SCALARS, :COUNTS, :LENGTHS, :UINT
+
+      def self.assert_within!(bytes, budget)
+        return if budget.nil? || bytes.bytesize <= budget
+
+        remaining = budget
+        pending = 1
+        pos = 0
+        while pending.positive?
+          pos, children = step(bytes, pos)
+          return if pos.nil?
+          raise InvalidTypeError, "payload holds more than #{budget} values" if (remaining -= 1).negative?
+
+          pending += children - 1
+        end
+      end
+
+      # The position after the value at +pos+, nil for one the payload
+      # cannot frame, and the values it holds directly.
+      def self.step(bytes, pos)
+        marker = bytes.getbyte(pos) or return [nil, 0]
+        pos += 1
+        case marker
+        when 0x00..0x7f, 0xe0..0xff then [pos, 0]
+        when 0x80..0x8f then [pos, (marker & 0x0f) * 2]
+        when 0x90..0x9f then [pos, marker & 0x0f]
+        when 0xa0..0xbf then [pos + (marker & 0x1f), 0]
+        else step_framed(bytes, pos, marker)
+        end
+      end
+
+      def self.step_framed(bytes, pos, marker)
+        return [pos + SCALARS.fetch(marker), 0] if SCALARS.key?(marker)
+
+        width, per = COUNTS[marker]
+        return [pos + width, uint(bytes, pos, width) * per] if width && per
+
+        width, tag = LENGTHS[marker]
+        return [nil, 0] unless width && tag
+
+        [pos + width + tag + uint(bytes, pos, width), 0]
+      end
+
+      # A length cut short reads as zero, so the count runs off the end and
+      # stops there.
+      def self.uint(bytes, pos, width)
+        slice = bytes.byteslice(pos, width).to_s
+        return 0 if slice.bytesize < width
+
+        slice.unpack1(UINT.fetch(width)) # : Integer
+      end
+
+      private_class_method :step, :step_framed, :uint
+    end
+  end
+end

data/lib/kobako/codec.rb

@@ -5,29 +5,13 @@ require_relative "codec/utils"
 require_relative "codec/handle_walk"
 require_relative "codec/nesting"
 require_relative "codec/state"
+require_relative "codec/value_budget"
 require_relative "codec/ext_types"
 require_relative "codec/encoder"
 require_relative "codec/decoder"
 
 module Kobako
-  # Host-side MessagePack codec for the kobako wire contract — the
-  # byte-level layer ({docs/wire-codec.md}[link:../../docs/wire-codec.md]).
-  # This is the payload codec: the core envelope is framed natively, so
-  # what reaches here is one codec document — an invocation's arguments
-  # (+Kobako::Payload::Arguments+), a dispatch or yield value, or an
-  # invocation's value and a Panic's diagnostics
-  # (+Kobako::Outcome+). The ext-type leaves this layer
-  # carries — +Kobako::Handle+ (0x01) — lives at the kobako root so the
-  # codec can register it without depending upward on Transport.
-  #
-  # Backed by the official +msgpack+ gem: ExtTypes registers the two
-  # kobako-specific ext types (0x00 Symbol, 0x01 Capability Handle) on
-  # one process-wide +MessagePack::Factory+,
-  # and Encoder / Decoder are thin wrappers over it. The Rust side
-  # mirrors this layer as the +codec+ module in the +kobako-codec+ crate;
-  # the ext-code constants live as module-private values on ExtTypes
-  # alongside +codec::EXT_SYMBOL+ / +codec::EXT_HANDLE+ on that side.
-  module Codec
+  module Codec # :nodoc:
     # The maximum structural nesting depth the wire represents (the
     # MessagePack ecosystem's bound), shared with the guest +kobako_codec+
     # so both sides cap identically. The host refuses a value nesting past
@@ -35,12 +19,16 @@ module Kobako
     # packer.
     MAX_NESTING_DEPTH = 128
 
-    # Bracket a decode and return the block's result together with whether
-    # the decoded tree carried an ext 0x01 Capability Handle — the signal a
-    # dispatch path uses to skip an all-identity Handle-resolution walk.
-    # The tracking state is codec-internal; this is its only readout.
+    # Answers the block's result with whether the decode carried a
+    # Capability Handle, so a caller can skip an all-identity restore walk.
     def self.track_handles(&block)
       State.current.track_handles(&block)
     end
+
+    # Holds every decode the block runs on this thread to +budget+ values,
+    # or to none when +budget+ is nil.
+    def self.within_value_budget(budget, &block)
+      State.current.within_value_budget(budget, &block)
+    end
   end
 end

data/lib/kobako/constant_name.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Kobako
+  # A bind-path segment, a snippet name and a #run entrypoint all take the
+  # constant-name form, so they are refused alike. The guest interns each
+  # one, and mruby holds a symbol of at most 65534 bytes.
+  CONSTANT_NAME = /\A[A-Z]\w{0,65533}\z/ # :nodoc:
+end

data/lib/kobako/context.rb

@@ -11,41 +11,30 @@ require_relative "transport"
 require_relative "catalog"
 
 module Kobako
-  # Kobako::Context — the per-invocation driver behind a single +Sandbox#eval+
-  # / +#run+. Each Context owns a fresh +Catalog::Handles+ table and drives one
-  # guest invocation: it builds the dispatch handler, runs the guest, records
-  # the run's captures and usage, and decodes the outcome. One Context per
-  # invocation owns all per-invocation state, so the reusable +Sandbox+ holds
-  # none and overlapping evals never touch each other's state.
+  # One invocation, as the block given to Sandbox#eval or Sandbox#run sees it.
+  # The block runs before the guest does, so it can choose the objects this
+  # invocation alone reaches:
+  #
+  #   sandbox.eval("Req::Current.user_id") { |ctx| ctx.bind("Req::Current", request) }
   class Context
-    # Build a Context over the Sandbox-owned config — the +Runtime+, the
-    # sealed +Catalog::Services+ / +Catalog::Snippets+ registries, and the
-    # +Catalog::Extensions+ whose callable backends this Context resolves for
-    # its own run. The +Catalog::Handles+ table is this invocation's own, so
-    # guest→host dispatch and host→guest auto-wrap share one allocator scoped
-    # to the run; the resolved provider map is likewise per-invocation, so
-    # concurrent invocations never share mutable state.
-    def initialize(runtime:, services:, snippets:, extensions:)
+    def initialize(runtime:, services:, extensions:, grants:, preamble:) # :nodoc:
       @runtime = runtime
       @services = services
-      @snippets = snippets
       @extensions = extensions
+      @grants = grants
+      @preamble = preamble
       @resolved = {} # : Hash[String, Transport::Exposure]
       @overrides = {} # : Hash[String, Transport::Exposure]
-      @spent = false
-      @handler = Catalog::Handles.new
+      @handles = Catalog::Handles.new
       @stdout_capture = @stderr_capture = Capture::EMPTY
       @usage = Usage::EMPTY
     end
 
-    # Override the object bound at an already-declared +path+ for this
-    # invocation only — the per-eval hook the +#eval+ / +#run+ block uses to
-    # fill a fillable or shadow any static / per-invocation binding. +path+
-    # must name a declared (Frame 1) binding; overriding an undeclared path
-    # raises +ArgumentError+ so the Frame 1 key set stays fixed. Valid only
-    # while the block runs — the Context is spent once the block returns, so a
-    # captured +ctx+ used afterward raises +ArgumentError+ too, putting both
-    # misuses on one rescuable channel. Returns +self+.
+    # Use +object+ for the Service at +path+ during this invocation only,
+    # filling a fillable Service or shadowing a bound one. Returns +self+.
+    #
+    # Raises ArgumentError when +path+ was never bound on the Sandbox, or when
+    # called after the block has returned.
     def bind(path, object)
       raise ArgumentError, "Kobako::Context is spent; ctx.bind is only valid inside the #eval / #run block" if @spent
 
@@ -56,16 +45,29 @@ module Kobako
       self
     end
 
-    # Resolve a Service +path+ to the Exposure backing it this invocation,
-    # layering the per-eval +ctx.bind+ overrides over this Context's
-    # per-invocation provider results over the Sandbox's static base bindings.
-    # An unbound path raises +KeyError+; a fillable left unfilled resolves to
-    # +Kobako::Unresolved+ and is reported the same way, so an unresolved
-    # capability fails closed as an undefined target rather than dispatching to
-    # the sentinel. The Dispatcher maps either +KeyError+ to an
-    # undefined-target wire fault. Internal — the per-invocation dispatch
-    # handler is the sole caller.
-    def lookup(path)
+    # Use +filesystem+ for the mount at +at+ during this invocation only,
+    # with its own +access+ and block, as Sandbox#mount takes them. Returns
+    # +self+.
+    #
+    # Raises TypeError for a path that is no String or something other than
+    # a Filesystem, and ArgumentError when nothing was mounted at +at+ on the
+    # Sandbox, for a malformed path or an unknown access, or when called
+    # after the block has returned.
+    def mount(at, filesystem, access: :read, &policy)
+      raise ArgumentError, "Kobako::Context is spent; ctx.mount is only valid inside the #eval / #run block" if @spent
+
+      Runtime.validate_mount!(at, access, filesystem)
+      mount = Catalog::Mount.new(at: at, access: access, filesystem: filesystem, policy: policy)
+      raise ArgumentError, "cannot override unmounted path #{at.inspect}" unless @grants.include?(mount)
+
+      mounts = @mounts ||= {} # : Hash[String, Catalog::Mount]
+      mounts[mount.key] = mount
+      self
+    end
+
+    # A fillable left unfilled raises like an unbound path, so the guest's
+    # call fails closed instead of reaching the sentinel.
+    def lookup(path) # :nodoc:
       key = path.to_s
       exposure = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
       raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(exposure.object)
@@ -73,136 +75,100 @@ module Kobako
       exposure
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+ and return the
-    # decoded last expression. A given +block+ runs first, receiving this
-    # Context to collect +ctx.bind+ overrides before the guest drives.
-    def eval(code, &block)
+    def eval(code, &block) # :nodoc:
       collect_overrides(&block) if block
-      invoke!(:eval) do
-        @runtime.eval(dispatch_handler, @services.paths, code.b, @snippets.entries)
-      end
+      invoke!(:eval) { @runtime.eval(dispatch_handler, setup, code.b) }
     end
 
-    # Dispatch a +Transport::Run+ into a preloaded entrypoint and return the
-    # decoded result. A given +block+ runs first, receiving this Context to
-    # collect +ctx.bind+ overrides before the guest drives.
-    def run(request, &block)
+    def run(request, &block) # :nodoc:
       collect_overrides(&block) if block
       invoke!(:run, entrypoint: request.entrypoint) do
-        @runtime.run(dispatch_handler, @services.paths, @snippets.entries,
-                     request.entrypoint.to_s, request.payload(@handler))
+        @runtime.run(dispatch_handler, setup, request.entrypoint.to_s, request.payload(@handles))
       end
     end
 
     private
 
-    # Run the per-eval override +block+, handing it this Context so it can call
-    # +ctx.bind+, then spend the Context so a captured +ctx+ used after the
-    # block raises. A block that raises propagates before the guest drives, so
-    # the guest never runs and no Execution is produced.
+    # What the Runtime builds the invocation from: the Preamble's parts,
+    # then this invocation's mounts.
+    def setup
+      paths, snippets, flags = @preamble
+      [paths, snippets, flags, @grants.entries(@mounts || {})]
+    end
+
+    # The Context is spent once the block returns, so a captured +ctx+ used
+    # later raises. A block that raises propagates before the guest drives,
+    # so the guest never runs and no Execution is produced.
     def collect_overrides
       yield self
     ensure
       @spent = true
     end
 
-    # Build this invocation's guest→host dispatch handler — a +Proc+ routing
-    # each guest→host call through the stateless +Transport::Dispatcher+,
-    # capturing this Context as the path resolver (its +#lookup+ layers the
-    # per-invocation providers over the static bindings) plus +@handler+. Handed to
-    # +Runtime#eval+ / +#run+ as a call argument, so the Runtime holds no
-    # dispatch state and the +Proc+ stays GC-rooted as a live argument for the
-    # synchronous call. The ext hands the +Proc+ a per-dispatch +guest_yielder+
-    # — a +String → String+ callable that re-enters the in-flight guest to run
-    # a yielded block — which the +Dispatcher+ forwards to the
-    # +Transport::Yielder+ it builds for the call.
+    # Handed to the Runtime as a call argument, so the Runtime holds no
+    # dispatch state and the Proc stays GC-rooted for the synchronous call.
+    # Built once per invocation, so every Call it answers shares one
+    # BlockFailure.
     def dispatch_handler
+      failure = Transport::BlockFailure.new
       lambda do |target, method_name, block_given, payload, guest_yielder|
         call = Transport::Call.new(target: target, method_name: method_name,
                                    block_given: block_given, payload: payload)
-        Transport::Dispatcher.dispatch(call, self, @handler, guest_yielder)
+        Transport::Dispatcher.dispatch(call, self, @handles, failure, guest_yielder)
       end
     end
 
-    # Record this invocation's usage and both output captures from the ext
-    # +Snapshot+. Every Snapshot carries them — value return or trap alike — so
-    # +#usage+ / +#stdout+ / +#stderr+ stay readable after a rescued trap.
-    def populate_observability!(snapshot)
+    # Every Snapshot carries usage and captures, trap or not, so they stay
+    # readable after a rescued trap.
+    def populate_observability(snapshot)
       @usage = Usage.new(wall_time: snapshot.wall_time, memory_peak: snapshot.memory_peak)
       @stdout_capture = Capture.new(bytes: snapshot.stdout, truncated: snapshot.stdout_truncated?)
       @stderr_capture = Capture.new(bytes: snapshot.stderr, truncated: snapshot.stderr_truncated?)
     end
 
-    # Pick the +TrapError+ subclass to re-raise based on +err+'s actual class.
-    # Cap-trap subclasses (+TimeoutError+ / +MemoryLimitError+) preserve their
-    # named identity; everything else collapses to the base +Kobako::TrapError+,
-    # so #invoke! can add the verb prefix without erasing the named subclass.
-    def trap_class_for(err)
-      case err
-      when TimeoutError     then TimeoutError
-      when MemoryLimitError then MemoryLimitError
-      else TrapError
-      end
-    end
-
-    # Build the +TrapError+-family exception for a trapped +Snapshot+ from its
-    # neutral trap kind, tagged with the verb — the cap subclasses
-    # (+TimeoutError+ / +MemoryLimitError+) keep their identity, every other
-    # engine fault is the base +TrapError+.
-    def trap_error_for(snapshot, verb)
-      klass = case snapshot.trap_kind
-              when :timeout      then TimeoutError
-              when :memory_limit then MemoryLimitError
-              else TrapError
-              end
-      klass.new("Sandbox##{verb} failed: #{snapshot.trap_message}")
+    # Every TrapError leaving an invocation names the verb that ran it; the
+    # cap subclasses keep their identity through the rebuild.
+    def with_verb(err, verb)
+      err.class.new("Sandbox##{verb} failed: #{err.message}")
     end
 
-    # Freeze this run's observables plus +value+ (+nil+ on a failed run) into
-    # the read-only +Execution+ the caller receives or the error carries.
-    # +failed+ records the two apart so a +nil+ +value+ from a successful run
-    # stays distinct from a failed one.
+    # +failed+ keeps a +nil+ value from a successful run apart from a failed
+    # run.
     def build_execution(value, failed:)
       Execution.new(value: value, usage: @usage, stdout: @stdout_capture, stderr: @stderr_capture, failed: failed)
     end
 
-    # Settle a completed run's outcome into its +Execution+. A Capability
-    # Handle in the result is restored to its host object first. The settle
-    # sits in the rescue so a wire-violation trap or a Panic both attach this
-    # run's Execution, just like a guest-call trap does. +entrypoint+ is the
-    # name +#run+ asked for, which the host knows and the wire never carries,
-    # so an unresolved one names itself on the error it raises.
+    # The settle sits in the rescue so a wire-violation trap or a Panic both
+    # attach this run's Execution, just like a guest-call trap does.
+    # +entrypoint+ is known to the host and never carried by the wire, so an
+    # unresolved one names itself on the error it raises.
     def settle_outcome(snapshot, verb, entrypoint)
-      kind, payload, panic = snapshot.outcome
-      value, carried = Codec.track_handles { Outcome.reify(kind, payload, panic, entrypoint: entrypoint) }
-      value = Codec::HandleWalk.deep_restore(value, @handler) if carried
+      payload, panic = snapshot.outcome
+      value, carried = Codec.track_handles { Outcome.reify(payload, panic, entrypoint: entrypoint) }
+      value = Codec::HandleWalk.deep_restore(value, @handles) if carried
       build_execution(value, failed: false)
     rescue Kobako::TrapError => e
-      raise trap_class_for(e).new("Sandbox##{verb} failed: #{e.message}").with_execution(build_execution(nil,
-                                                                                                         failed: true))
+      raise with_verb(e, verb).with_execution(build_execution(nil, failed: true))
     rescue Kobako::SandboxError, Kobako::ServiceError => e
       raise e.with_execution(build_execution(nil, failed: true))
     end
 
-    # Drive one invocation and settle it into a frozen +Execution+. +verb+
-    # tags the TrapError message so the failing export is identifiable. This
-    # invocation's callable Extension backends are resolved first — before the
-    # guest runs — so a provider that raises propagates unwrapped and leaves
-    # the guest unrun. Usage and captures are recorded before the trap check,
-    # so a trapped Snapshot's error carries them just like a completed run's
-    # return value. A could-not-start fault ran no invocation at all, so it
-    # carries no Execution and gains only the verb prefix.
+    # Extension backends are resolved before the guest runs, so a provider
+    # that raises propagates unwrapped and leaves the guest unrun. A
+    # could-not-start fault ran no invocation at all, so it carries no
+    # Execution and gains only the verb prefix.
     def invoke!(verb, entrypoint: nil)
       @resolved = @extensions.resolve.transform_values { |object| Transport::Exposure.of(object) }
       begin
         snapshot = yield
       rescue Kobako::TrapError => e
-        raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+        raise with_verb(e, verb)
       end
-      populate_observability!(snapshot)
-      return settle_outcome(snapshot, verb, entrypoint) unless snapshot.trapped?
+      populate_observability(snapshot)
+      trap = snapshot.trap_error
+      return settle_outcome(snapshot, verb, entrypoint) unless trap
 
-      raise trap_error_for(snapshot, verb).with_execution(build_execution(nil, failed: true))
+      raise with_verb(trap, verb).with_execution(build_execution(nil, failed: true))
     end
   end
 end