kobako 0.18.0-aarch64-linux → 0.20.0-aarch64-linux

data/lib/kobako/context.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "codec"
+require_relative "errors"
+require_relative "execution"
+require_relative "unresolved"
+require_relative "outcome"
+require_relative "usage"
+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.
+  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:)
+      @runtime = runtime
+      @services = services
+      @snippets = snippets
+      @extensions = extensions
+      @resolved = {} # : Hash[String, untyped]
+      @overrides = {} # : Hash[String, untyped]
+      @spent = false
+      @handler = 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+.
+    def bind(path, object)
+      raise ArgumentError, "Kobako::Context is spent; ctx.bind is only valid inside the #eval / #run block" if @spent
+
+      key = path.to_s
+      raise ArgumentError, "cannot override undeclared path #{key.inspect}" unless @services.bound?(key)
+
+      @overrides[key] = object
+      self
+    end
+
+    # Resolve a Service +path+ to the object 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)
+      key = path.to_s
+      object = @overrides.fetch(key) { @resolved.fetch(key) { @services.lookup(path) } }
+      raise KeyError, "service #{path} is declared but unresolved this invocation" if Unresolved.equal?(object)
+
+      object
+    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)
+      collect_overrides(&block) if block
+      invoke!(:eval) do
+        @runtime.eval(dispatch_handler, @services.encode, code.b, @snippets.encode)
+      end
+    end
+
+    # Dispatch a +Transport::Run+ envelope 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(run_envelope, &block)
+      collect_overrides(&block) if block
+      invoke!(:run) do
+        @runtime.run(dispatch_handler, @services.encode, @snippets.encode, run_envelope.encode(@handler))
+      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.
+    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.
+    def dispatch_handler
+      lambda do |request_bytes, guest_yielder|
+        Transport::Dispatcher.dispatch(request_bytes, self, @handler, 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)
+      @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}")
+    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.
+    def build_execution(value, failed:)
+      Execution.new(value: value, usage: @usage, stdout: @stdout_capture, stderr: @stderr_capture, failed: failed)
+    end
+
+    # Decode a completed run's outcome into its +Execution+. A Capability
+    # Handle in the result is restored to its host object first. Decode sits in
+    # the rescue so a wire-violation trap or a Panic envelope both attach this
+    # run's Execution, just like a guest-call trap does.
+    def settle_outcome(snapshot, verb)
+      value, carried = Codec.track_handles { Outcome.decode(snapshot.outcome) }
+      value = Codec::HandleWalk.deep_restore(value, @handler) 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))
+    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.
+    def invoke!(verb)
+      @resolved = @extensions.resolve
+      begin
+        snapshot = yield
+      rescue Kobako::TrapError => e
+        raise trap_class_for(e), "Sandbox##{verb} failed: #{e.message}"
+      end
+      populate_observability!(snapshot)
+      return settle_outcome(snapshot, verb) unless snapshot.trapped?
+
+      raise trap_error_for(snapshot, verb).with_execution(build_execution(nil, failed: true))
+    end
+  end
+end

data/lib/kobako/errors.rb

@@ -16,6 +16,24 @@ module Kobako
   # taxonomy can rescue a single class.
   class Error < StandardError; end
 
+  # Carries the frozen +Kobako::Execution+ of the run that failed, so a
+  # rescue reads its captures and usage exactly as a successful caller reads
+  # them off the return value. Mixed only into the three invocation-outcome
+  # classes (+TrapError+ / +SandboxError+ / +ServiceError+ and their
+  # subclasses); +SetupError+ and +PoolTimeoutError+ arise outside any
+  # invocation and carry no Execution. Defaults to +nil+ — a pre-flight
+  # failure that ran no invocation leaves it unset.
+  module CarriesExecution
+    attr_reader :execution
+
+    # Attach the failed run's +Kobako::Execution+ and return +self+ so the
+    # raise site reads +raise error.with_execution(execution)+.
+    def with_execution(execution)
+      @execution = execution
+      self
+    end
+  end
+
   # Wasm engine layer. Raised when the Wasm execution engine crashed
   # (trap, OOM, unreachable) or when the wire layer detected a structural
   # violation that signals a corrupted guest execution environment
@@ -31,7 +49,9 @@ module Kobako
   # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
   # want to surface a specific reason to operators can rescue the subclass
   # first.
-  class TrapError < Error; end
+  class TrapError < Error
+    include CarriesExecution
+  end
 
   # Wall-clock timeout cap exhausted: the absolute deadline
   # +entry_time + timeout+ passed and the next guest wasm safepoint
@@ -70,7 +90,7 @@ module Kobako
   # beyond its message. Mixed into both rather than promoted to a shared
   # superclass because +SandboxError+ and +ServiceError+ sit in distinct
   # branches of the invocation-outcome taxonomy under +Kobako::Error+.
-  module StructuredError
+  module Diagnosable
     attr_reader :origin, :klass, :backtrace_lines, :details
 
     def initialize(message, origin: nil, klass: nil, backtrace_lines: nil, details: nil)
@@ -86,14 +106,16 @@ module Kobako
   # execution failed due to a mruby script error, a protocol fault, or a
   # host-side wire decode failure on an otherwise valid outcome tag.
   class SandboxError < Error
-    include StructuredError
+    include Diagnosable
+    include CarriesExecution
   end
 
   # Service layer. Raised when a Service capability call inside a mruby
   # script reported an application-level failure that the script did not
   # rescue.
   class ServiceError < Error
-    include StructuredError
+    include Diagnosable
+    include CarriesExecution
   end
 
   # HandleExhaustedError is the canonical SandboxError subclass for the

data/lib/kobako/execution.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "capture"
+require_relative "usage"
+
+module Kobako
+  # Kobako::Execution — the frozen result of one +Sandbox#eval+ / +#run+: the
+  # decoded +#value+ plus the run's output captures and +#usage+. A successful
+  # run returns it; a failed run raises an error carrying the same frozen
+  # Execution on the error's +#execution+, so a rescue reads the captures and
+  # usage exactly as a successful caller reads them off the return value. On a
+  # failed run +#value+ is +nil+ — only the captures and usage are meaningful.
+  #
+  # +#failed?+ tells the returned Execution from the carried one even when both
+  # +#value+ are +nil+ (a run whose last expression was +nil+ versus a failed
+  # one). It holds no reference to the raising error, so the error carries the
+  # Execution but not the reverse.
+  class Execution
+    # The deserialized guest value the run produced; +nil+ on a failed run.
+    attr_reader :value
+
+    # The +Kobako::Usage+ resource accounting for this run.
+    attr_reader :usage
+
+    def initialize(value:, usage:, stdout:, stderr:, failed:)
+      @value = value
+      @usage = usage
+      @stdout_capture = stdout
+      @stderr_capture = stderr
+      @failed = failed
+      freeze
+    end
+
+    # Returns +true+ iff the run failed — +false+ on the Execution +#eval+ /
+    # +#run+ returned, +true+ on the one a raised error carries.
+    def failed? = @failed
+
+    # Bytes the guest wrote to stdout during this run as a UTF-8 String,
+    # clipped at +stdout_limit+; the content carries no truncation sentinel,
+    # so use +#stdout_truncated?+ to observe overflow.
+    def stdout = @stdout_capture.bytes
+
+    # Bytes the guest wrote to stderr during this run. Mirror of #stdout.
+    def stderr = @stderr_capture.bytes
+
+    # Returns +true+ iff stdout capture reached +stdout_limit+ during this run.
+    def stdout_truncated? = @stdout_capture.truncated?
+
+    # Returns +true+ iff stderr capture reached +stderr_limit+ during this run.
+    def stderr_truncated? = @stderr_capture.truncated?
+  end
+end

data/lib/kobako/extension.rb

@@ -27,17 +27,31 @@ module Kobako
     # Kobako::Extension::Backend — the host attachment of an Extension,
     # pairing +path+ (the constant path the backend binds at, single-segment
     # +"File"+ or nested +"MyApp::Store"+, spelling the guest constant the
-    # idiom routes to) with +provider+ (the source of the bound object).
+    # idiom routes to) with the source of the bound object, declared by
+    # explicit keyword:
     #
-    # A +provider+ that is not itself callable is the bound object, resolved
-    # once for the Sandbox's life; a callable provider is invoked once per
-    # invocation to yield that invocation's object, so a fresh object backs
-    # the path every invocation. Callability is the sole discriminator — a
-    # fixed backend that is itself callable is supplied through a
-    # non-callable wrapper. A callable provider that raises propagates its
-    # exception to the invocation caller and leaves the guest unrun; the
-    # next invocation resolves it afresh.
-    class Backend < Data.define(:path, :provider)
+    #   * +object:+ — a static object, fixed for the Sandbox's life.
+    #   * +provider:+ — a no-argument callable invoked once per invocation to
+    #     yield that invocation's object, so a fresh object backs the path
+    #     every invocation. A provider that raises propagates its exception to
+    #     the invocation caller and leaves the guest unrun; the next
+    #     invocation resolves it afresh.
+    #   * neither — a fillable, defaulting to +Kobako::Unresolved+ until the
+    #     host supplies the invocation's object.
+    #
+    # The kind is chosen by keyword, never inferred from whether the value is
+    # callable, so a static object that is itself callable is expressed
+    # directly with +object:+. Giving both +object:+ and +provider:+ raises
+    # +ArgumentError+.
+    class Backend < Data.define(:path, :object, :provider)
+      def initialize(path:, object: nil, provider: nil)
+        if !object.nil? && !provider.nil?
+          raise ArgumentError,
+                "Extension::Backend accepts object: or provider:, not both"
+        end
+
+        super
+      end
     end
 
     # +backend+ and +depends_on+ default to absent so the common

data/lib/kobako/pool.rb

@@ -47,7 +47,7 @@ module Kobako
     # discarded and its slot refills by a fresh construction on next
     # demand.
     def with
-      sandbox = checkout
+      sandbox = acquire
       begin
         yield sandbox
       rescue TrapError
@@ -61,12 +61,6 @@ module Kobako
 
     private
 
-    # Acquire a Sandbox and hand it over in pre-invocation state — empty
-    # output buffers and truncation predicates false.
-    def checkout
-      acquire.tap(&:reset_invocation_state!)
-    end
-
     # The idle-first claim loop: an idle Sandbox wins, unclaimed
     # capacity constructs, and a full pool waits for a checkin.
     def acquire