kobako 0.27.0 → 0.29.0

data/lib/kobako/errors.rb

@@ -1,103 +1,49 @@
 # frozen_string_literal: true
 
-# Top-level Kobako namespace.
 module Kobako
-  # Error taxonomy.
-  #
-  # Every +Kobako::Sandbox+ invocation (+#eval+ or +#run+) either returns a
-  # value or raises exactly one of TrapError, SandboxError, or ServiceError.
-  # Attribution is decided after the guest binary returns control to the
-  # host: first the Wasm-trap layer, then the outcome-envelope tag.
-  # SetupError and PoolTimeoutError sit outside the invocation taxonomy and
-  # never pass through that attribution decision. Each class below
-  # documents its own layer.
-
-  # Base for all kobako-raised errors so callers that want to ignore the
-  # taxonomy can rescue a single class.
+  # Every Sandbox#eval or Sandbox#run returns, or raises exactly one of
+  # TrapError, SandboxError, or ServiceError. SetupError and PoolTimeoutError
+  # arise outside any invocation.
+
+  # The base of every error kobako raises.
   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
+  module Recorded # :nodoc:
     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)
+    def with_execution(execution) # :nodoc:
       @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 (an
-  # outcome the core envelope cannot frame, an absent one included).
-  #
-  # Two named subclasses cover the configured per-invocation caps:
-  #
-  #   * TimeoutError     — wall-clock +timeout+ exceeded.
-  #   * MemoryLimitError — guest +memory.grow+ would exceed
-  #                          +memory_limit+.
-  #
-  # Host Apps that only care about "guest is unrecoverable, discard the
-  # Sandbox" can rescue +TrapError+ and ignore the subclass; Host Apps that
-  # want to surface a specific reason to operators can rescue the subclass
-  # first.
+  # The engine stopped the guest: a trap, a cap reached, or an outcome that
+  # could not be read. The next invocation on the same Sandbox runs as usual.
+  # +execution+ is the failed run's Execution, so a rescue reads its captures
+  # and usage as a successful caller would; it is +nil+ when the failure came
+  # before the guest ran.
   class TrapError < Error
-    include CarriesExecution
+    include Recorded
   end
 
-  # Wall-clock timeout cap exhausted: the absolute deadline
-  # +entry_time + timeout+ passed and the next guest wasm safepoint
-  # trapped. The Sandbox is unrecoverable after this point; discard and
-  # recreate before another execution.
+  # The invocation ran past its +timeout+.
   class TimeoutError < TrapError; end
 
-  # Linear-memory cap exhausted: a guest +memory.grow+ would have pushed
-  # linear memory past the configured +memory_limit+. The Sandbox is
-  # unrecoverable after this point; discard and recreate before another
-  # execution.
+  # The invocation grew guest memory past its +memory_limit+.
   class MemoryLimitError < TrapError; end
 
-  # Construction-layer error raised by +Kobako::Sandbox.new+ /
-  # +Kobako::Runtime.from_path+ when the wasm runtime cannot be built
-  # from the configured +wasm_path+ before any invocation runs —
-  # an unreadable artifact, bytes that are not a valid Wasm module, or
-  # engine / linker / instantiation setup failure. Construction
-  # is not an invocation, so +SetupError+ sits beside the invocation
-  # taxonomy under +Kobako::Error+ rather than under +TrapError+: no
-  # Sandbox is produced, so the +TrapError+ "discard and recreate"
-  # recovery contract does not apply.
+  # A Sandbox could not be built: the Guest Binary is unreadable or not a
+  # valid module, the runtime failed to start, or it provides less isolation
+  # than +profile+ asks for.
   class SetupError < Error; end
 
-  # The named +SetupError+ subclass for the common, actionable case:
-  # the Guest Binary artifact is absent at +wasm_path+ — the pre-build
-  # state on a fresh clone before +bundle exec rake compile+. Host Apps
-  # that only need "the Sandbox could not be set up" rescue +SetupError+;
-  # those wanting to special-case the unbuilt-artifact state rescue
-  # +ModuleNotBuiltError+ first.
+  # The Guest Binary is missing at +wasm_path+.
   class ModuleNotBuiltError < SetupError; end
 
-  # The structured attribution the two invocation-failure classes carry
-  # from a decoded guest exception — its +origin+, original +klass+, and
-  # +backtrace_lines+ — so a Host App can inspect a failure 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+.
-  #
-  # Data specific to one kind of failure rides a named reader on the
-  # subclass that failure raises, the way Ruby pairs NameError#name with
-  # +NameError#local_variables+ — see UndefinedEntrypointError.
-  module Diagnosable
+  module Diagnosable # :nodoc:
     attr_reader :origin, :klass, :backtrace_lines
 
-    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil)
+    def initialize(message, origin: nil, klass: nil, backtrace_lines: nil) # :nodoc:
       super(message)
       @origin = origin
       @klass = klass
@@ -105,93 +51,72 @@ module Kobako
     end
   end
 
-  # Sandbox / wire layer. Raised when the guest ran to completion but
-  # execution failed due to a mruby script error, a protocol fault, or a
-  # payload the host's codec could not decode out of a well-framed
-  # outcome.
+  # The guest failed: the script raised or did not compile, the Guest Binary
+  # could not start the run, or what it produced could not be read.
+  # +origin+ (<tt>"sandbox"</tt> or <tt>"service"</tt>), +klass+ and
+  # +backtrace_lines+ say where it came from, which class raised it, and its
+  # backtrace. +execution+ is the failed run's Execution, as on TrapError.
   class SandboxError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
-  # Service layer. Raised when a Service capability call inside a mruby
-  # script reported an application-level failure that the script did not
-  # rescue. The base class covers a Service that ran and raised; the two
-  # subclasses below cover the calls that never reached one, so a Host App
-  # routes them apart with +rescue+ instead of by reading the message.
+  # A Service call failed and the guest left it unrescued. It carries
+  # +origin+, +klass+, +backtrace_lines+ and +execution+ as SandboxError does.
   class ServiceError < Error
     include Diagnosable
-    include CarriesExecution
+    include Recorded
   end
 
-  # The ServiceError subclass raised when the call reached no Service
-  # method: the bound path holds nothing, the Capability Handle is not
-  # live in this invocation, or the method is absent or outside the guest
-  # surface. The causes stay indistinguishable — an opaque target must
-  # disclose nothing about which methods it defines — so what a Host App
-  # learns is that this call will not succeed by being retried.
+  # The call reached no Service method: nothing is bound there, the Handle
+  # is not live, or the guest may not call that method. The causes look the
+  # same on purpose, so a target discloses nothing about what it defines.
   class NoServiceError < ServiceError; end
 
-  # The ServiceError subclass raised when the call reached the Service
-  # method but its arguments did not fit — an unknown keyword, or an
-  # arity mismatch.
+  # The Service method refused its arguments: the call would not bind, or
+  # the method raised +ArgumentError+ over what it was given.
   class ServiceArgumentError < ServiceError; end
 
-  # Raised at a Service method's +yield+ site when the guest block it
-  # yielded to raised. A Service rescues it the way it would rescue a
-  # block's exception without a Sandbox between the two frames; leaving it
-  # unrescued returns it to the guest, which re-raises the exception it
-  # raised in the first place. It therefore never reaches the Host App as
-  # an invocation outcome and carries no Execution. +klass+ names the
-  # guest-side class, which has no host counterpart to rebuild.
+  # Raised at a Service's +yield+ when the guest block raised; rescue it as
+  # you would the block's own exception. Left unrescued, the guest sees its
+  # own exception again, so it never reaches the Host App.
   class BlockError < Error
     include Diagnosable
   end
 
-  # Raised at a Service method's +yield+ site when a yield argument has no
-  # wire representation, so the round-trip never left the host and the
-  # block never ran. As BlockError, a Service rescues it at that site and
-  # may go on, so it never reaches the Host App as an invocation outcome;
-  # unrescued, the dispatch answers as that Service having failed.
+  # Raised at a Service's +yield+ when an argument cannot cross to the guest,
+  # so the block never ran. Left unrescued, the Service call fails.
   class YieldValueError < Error; end
 
-  # HandleExhaustedError is the canonical SandboxError subclass for the
-  # id-cap-hit path. Raised when the per-invocation Handle ID counter in
-  # Catalog::Handles reaches +0x7fff_ffff+ (2³¹ − 1) and further
-  # allocation would exceed the cap.
+  # Raised at a Service's +yield+ when the guest serves no block, so the
+  # block never ran. Left unrescued, the Service call fails.
+  class UnsupportedError < Error; end
+
+  # One invocation issued more Handles than an id can number (2**31 - 1).
   class HandleExhaustedError < SandboxError; end
 
-  # BytecodeError is the SandboxError subclass raised when a
-  # +#preload(binary:)+ snippet fails structural validation during the
-  # first invocation's snippet replay against a fresh +mrb_state+ (RITE
-  # version mismatch or corrupt body). Bytecode that loads cleanly and
-  # then raises at top level surfaces as plain +SandboxError+ with the
-  # natural mruby class preserved. Inherits from SandboxError so a single
-  # +rescue Kobako::SandboxError+ covers both source and bytecode
-  # snippet failures while callers wanting bytecode-specific handling
-  # can +rescue Kobako::BytecodeError+ directly.
+  # A <tt>preload(binary:)</tt> snippet failed to load. Bytecode that loads
+  # and then raises is a plain SandboxError.
   class BytecodeError < SandboxError; end
 
-  # UndefinedEntrypointError is the SandboxError subclass raised when a
-  # +#run+ target names no top-level constant in the guest. It carries the
-  # +#name+ that was asked for and the +#available+ names it could have
-  # been — the top-level constants the preloaded snippets contributed — so
-  # a caller corrects the name from the error rather than by reading the
-  # guest source. Ruby pairs NameError#name with
-  # +NameError#local_variables+ for the same reason.
+  # The Guest Binary does not support a flag the Sandbox set, so no script
+  # ran. Retrying without the flag, or on a Guest Binary that supports it,
+  # can succeed.
+  class UnsupportedFlagError < SandboxError; end
+
+  # Sandbox#run named no top-level constant.
   class UndefinedEntrypointError < SandboxError
+    # The constant asked for, and the ones the preloaded snippets define.
     attr_reader :name, :available
 
-    def initialize(message, name: nil, available: [], **)
+    def initialize(message, name: nil, available: [], **) # :nodoc:
       super(message, **)
       @name = name
       @available = available
     end
   end
 
-  # Pool checkout layer. Raised by +Kobako::Pool#with+ when the checkout
-  # wait exceeded the configured +checkout_timeout+ while every slot was
-  # held. No Sandbox state is touched — retrying succeeds as soon as a holder
-  # returns its Sandbox.
+  # Pool#with waited past +checkout_timeout+ with every slot held. Retrying
+  # succeeds once a holder returns its Sandbox.
   class PoolTimeoutError < Error; end
 end

data/lib/kobako/execution.rb

@@ -4,25 +4,20 @@ 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.
+  # The record of one Sandbox#eval or Sandbox#run: the guest's #value, its
+  # output, and its #usage. A failed run raises instead, and the error carries
+  # the same record on +execution+, where #value is +nil+.
   #
-  # +#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.
+  # #failed? tells the two apart when both #value are +nil+: a script whose
+  # last expression was +nil+ versus one that failed.
   class Execution
-    # The deserialized guest value the run produced; +nil+ on a failed run.
+    # The guest value the run produced; +nil+ on a failed run.
     attr_reader :value
 
-    # The +Kobako::Usage+ resource accounting for this run.
+    # What the run spent against its caps, as a Usage.
     attr_reader :usage
 
-    def initialize(value:, usage:, stdout:, stderr:, failed:)
+    def initialize(value:, usage:, stdout:, stderr:, failed:) # :nodoc:
       @value = value
       @usage = usage
       @stdout_capture = stdout
@@ -31,22 +26,22 @@ module Kobako
       freeze
     end
 
-    # Returns +true+ iff the run failed — +false+ on the Execution +#eval+ /
-    # +#run+ returned, +true+ on the one a raised error carries.
+    # Whether the run failed: +false+ on the Execution #eval or #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.
+    # What the guest wrote to stdout, up to +stdout_limit+ bytes: a UTF-8
+    # String, or a binary one when the bytes are not valid UTF-8. The text
+    # carries no sign it was cut; #stdout_truncated? says so.
     def stdout = @stdout_capture.bytes
 
-    # Bytes the guest wrote to stderr during this run. Mirror of #stdout.
+    # What the guest wrote to stderr; see #stdout.
     def stderr = @stderr_capture.bytes
 
-    # Returns +true+ iff stdout capture reached +stdout_limit+ during this run.
+    # Whether stdout reached +stdout_limit+.
     def stdout_truncated? = @stdout_capture.truncated?
 
-    # Returns +true+ iff stderr capture reached +stderr_limit+ during this run.
+    # Whether stderr reached +stderr_limit+.
     def stderr_truncated? = @stderr_capture.truncated?
   end
 end

data/lib/kobako/extension.rb

@@ -1,48 +1,32 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Kobako::Extension — a guest idiom paired with an optional host backend,
-  # installed on a Sandbox via +Sandbox#install+. It composes the existing
-  # +#preload+ (the guest +source+) and +#bind+ (the +backend+) verbs into
-  # one setup unit, so guest code sees a native-style constant whose pure
-  # methods run in-guest and whose privileged methods dispatch to the
-  # backend.
+  # Guest source paired with an optional host backend, installed with
+  # Sandbox#install: the guest sees one constant whose pure methods run in the
+  # guest and whose privileged ones call the backend. Any object answering the
+  # same four readers installs the same way.
   #
-  # The four readers form the contract +#install+ duck-types on:
-  #
-  #   * +name+ — a Symbol matching +/\A[A-Z]\w*\z/+, the preloaded snippet's
-  #     canonical backtrace name and the +depends_on+ match key. Independent
-  #     of any bound path.
-  #   * +source+ — the mruby idiom as a String; always present, since an
-  #     Extension always carries a guest idiom. A host object with no idiom
-  #     is bound with +#bind+ directly.
-  #   * +backend+ — an +Extension::Backend+ or +nil+ for a pure-guest
-  #     Extension.
-  #   * +depends_on+ — Symbol names of Extensions that must also be
-  #     installed, checked for presence at the first invocation.
-  #
-  # +Kobako::Extension+ is the bundled value type; any object exposing the
-  # four readers is equally valid, so a Host App or gem may supply its own.
+  # [+name+]        A constant-form Symbol: the snippet's backtrace name, and
+  #                 what another Extension's +depends_on+ names.
+  # [+source+]      The mruby source, a String. A host object with no source
+  #                 is bound with Sandbox#bind instead.
+  # [+backend+]     A Backend, or +nil+ for an Extension that runs entirely in
+  #                 the guest.
+  # [+depends_on+]  Names of Extensions that must also be installed, checked
+  #                 at the first invocation.
   class Extension < Data.define(:name, :source, :backend, :depends_on)
-    # 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 the source of the bound object, declared by
-    # explicit keyword:
+    # The host object an Extension's constant at +path+ calls, such as
+    # <tt>"MyApp::Store"</tt>, given by keyword:
     #
-    #   * +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.
+    # [+object:+]   One object for the Sandbox's life.
+    # [+provider:+] A callable taking no arguments, called once per invocation
+    #               for that invocation's object. If it raises, the exception
+    #               reaches the caller and the guest does not run.
+    # [neither]     A fillable Service, supplied per invocation through
+    #               Context#bind.
     #
-    # 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+.
+    # The keyword decides the kind, so a callable object meant as itself is
+    # given as +object:+. Giving both raises ArgumentError.
     class Backend < Data.define(:path, :object, :provider)
       def initialize(path:, object: nil, provider: nil)
         if !object.nil? && !provider.nil?
@@ -54,8 +38,7 @@ module Kobako
       end
     end
 
-    # +backend+ and +depends_on+ default to absent so the common
-    # pure-idiom and single-backend shapes stay terse.
+    # +backend+ defaults to none, and +depends_on+ to no other Extension.
     def initialize(name:, source:, backend: nil, depends_on: [])
       super
     end

data/lib/kobako/filesystem.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kobako
+  # The Filesystems a Sandbox can mount for the guest's +File+, each
+  # answered in Rust by the kind of the same name. Hand one to
+  # Sandbox#mount:
+  #
+  #   sandbox.mount("/data", Kobako::Filesystem::Memory.new("config.yml" => yaml))
+  #
+  # [<tt>Memory.new(files = {}, limit: 64 MiB, inodes:)</tt>]
+  #   Files held in memory for as long as the object lives, seeded from a
+  #   Hash of path to contents. Every invocation shares them.
+  # [<tt>Temporary.new(limit: 64 MiB, inodes:)</tt>]
+  #   Files held in memory that every invocation starts empty.
+  # [<tt>Directory.new(path)</tt>]
+  #   A host directory and everything beneath it. Nothing outside it is
+  #   reachable, a symbolic link pointing out included.
+  # [<tt>Overlay.new.layer(filesystem, access: :read)</tt>]
+  #   Layers stacked into one view, the first added on top, each +:read+
+  #   or +:read_write+ on its own. A change lands in a writable Layer, and
+  #   a read-only one stays as it was. Each +layer+ answers a new Overlay.
+  #
+  # A Memory or Temporary is bounded as a tmpfs mount is: its files hold
+  # at most +limit+ bytes together, and it holds at most +inodes+ files and
+  # directories, its root among them; +nil+ lifts either bound. Without
+  # +inodes+ it holds one for each 4 KiB of +limit+, and the root. Past
+  # either, the guest raises Errno::ENOSPC.
+  #
+  # Any object answering +open+ and +stat+ mounts too, as a Filesystem
+  # written in Ruby; its methods take the names of +File+, +Dir+, and +IO+.
+  # Its +stat+ answers +directory?+, +size+, and +ino+, an +ino+ naming one
+  # directory for as long as the guest holds it open. Its names match
+  # exactly, as a mount's block judges them as given. A name may hold a
+  # <tt>\\</tt>, which the guest's paths never separate on, so one joined
+  # to a Windows host path is the Filesystem's to refuse.
+  module Filesystem
+  end
+end

data/lib/kobako/handle.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
 module Kobako
-  # A Capability Handle as it crosses the wire (ext 0x01, laid out in
-  # {docs/wire-codec.md}[link:../../docs/wire-codec.md]), in either
-  # direction. Host App code cannot construct one: +.new+ is private and
-  # +#with+ removed, so no Handle is ever made from a caller-chosen id.
-  # The guest's +Kobako::Handle+ shares only the name.
+  # A guest-held reference to a host object, named by id. Host code cannot
+  # construct one, so no Handle is ever made from a caller-chosen id.
   class Handle < Data.define(:id)
-    # ID 0 is the invalid sentinel and is never allocated.
+    # The smallest id; 0 never names a Handle.
     MIN_ID = 1
-    # The positive half of a signed 32-bit integer, so an id fits either
-    # side of the wire unchanged.
+    # The largest id, the positive half of a signed 32-bit integer; an
+    # invocation needing more raises HandleExhaustedError.
     MAX_ID = 0x7fff_ffff
 
-    def initialize(id:)
+    def initialize(id:) # :nodoc:
       raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
       raise ArgumentError, "Handle id #{id} out of range [#{MIN_ID}, #{MAX_ID}]" unless id.between?(MIN_ID, MAX_ID)
 
@@ -23,9 +20,7 @@ module Kobako
     private_class_method :new
     undef_method :with
 
-    # The Host Gem's own constructor, for the wire decoder and the Handle
-    # allocator; it runs the same id checks +.new+ would.
-    def self.restore(id)
+    def self.restore(id) # :nodoc:
       allocate.tap { |handle| handle.send(:initialize, id: id) }
     end
   end