kobako 0.26.0-aarch64-linux → 0.28.0-aarch64-linux

data/lib/kobako/payload.rb

@@ -3,17 +3,9 @@
 require_relative "payload/arguments"
 
 module Kobako
-  # The payload shapes that ride inside a core envelope's opaque payload
-  # field. The envelope routes a message and the native side decodes it;
-  # this layer decides what the resolved method receives, and the byte-level
-  # encoding of that shape belongs to +Kobako::Codec+ beneath it.
-  #
-  # Keeping the two apart is what lets an endpoint with its own schema
-  # replace this layer and keep the envelope, so nothing here may reach for
-  # a routing field.
-  #
-  # +Kobako::Payload::Arguments+ is the wire-symmetric peer of
-  # +kobako_codec::payload::Arguments+.
-  module Payload
+  # What the resolved method receives, kept apart from the envelope so an
+  # endpoint with its own schema can replace it; nothing here reads a
+  # routing field.
+  module Payload # :nodoc:
   end
 end

data/lib/kobako/pool.rb

@@ -4,29 +4,21 @@ require_relative "errors"
 require_relative "sandbox"
 
 module Kobako
-  # Kobako::Pool — a bounded set of warm, identically set-up Sandboxes
-  # handed out one exclusive holder at a time.
-  #
-  # Construction forwards every +Kobako::Sandbox.new+ keyword verbatim
-  # and holds the optional block as the per-Sandbox setup hook; a
-  # checkout prefers an idle Sandbox and constructs a new one only when
-  # none is idle and fewer than +slots+ exist. +#with+ blocks up
-  # to +checkout_timeout+ seconds when every slot is held, applies
-  # the +TrapError+ discard-and-recreate contract at checkin, and
-  # the Pool releases everything with its own reachability — there is no
-  # teardown verb.
+  # A bounded set of warm, identically set-up Sandboxes, handed out to one
+  # holder at a time. Every Sandbox it builds is kept: an invocation leaves
+  # nothing behind, whatever ended it.
   class Pool
-    # The +#with+ wait bound applied when +checkout_timeout+ is not given.
+    # The default +checkout_timeout+: 5 seconds.
     DEFAULT_CHECKOUT_TIMEOUT_SECONDS = 5.0
 
-    # Build a Pool of up to +slots+ Sandboxes. +slots+ is
-    # a positive Integer; +checkout_timeout+ bounds the +#with+ wait in
-    # seconds (+nil+ waits indefinitely); every other keyword is
-    # forwarded verbatim to +Kobako::Sandbox.new+. The optional block
-    # runs exactly once per constructed Sandbox — it is the setup window
-    # for +#bind+ / +#preload+ before that Sandbox's first checkout.
-    # No Sandbox is constructed here. Raises +ArgumentError+ for an
-    # invalid +slots+ / +checkout_timeout+.
+    # Build a Pool of up to +slots+ Sandboxes, built on first demand with the
+    # other keywords as Sandbox.new takes them. +checkout_timeout+ bounds how
+    # many seconds #with waits, and +nil+ waits indefinitely. The block, if
+    # given, sets up each Sandbox once, as with Sandbox#bind and
+    # Sandbox#preload.
+    #
+    # Raises ArgumentError when +slots+ is not a positive Integer or
+    # +checkout_timeout+ is not a positive finite number.
     def initialize(slots:, checkout_timeout: DEFAULT_CHECKOUT_TIMEOUT_SECONDS, **sandbox_options, &setup)
       validate_slots!(slots)
       @slots = slots
@@ -40,29 +32,20 @@ module Kobako
     end
 
     # Yield one exclusively-held Sandbox to the block and return the
-    # block's value. Blocks while every slot is held; raises
-    # +Kobako::PoolTimeoutError+ once the wait exceeds +checkout_timeout+.
-    # The Sandbox returns to the pool at block exit — unless the block raised
-    # +Kobako::TrapError+, in which case the unrecoverable Sandbox is
-    # discarded and its slot refills by a fresh construction on next
-    # demand.
+    # block's value; the Sandbox returns to the pool however the block
+    # exits. Raises PoolTimeoutError once every slot has stayed held past
+    # +checkout_timeout+.
     def with
       sandbox = acquire
       begin
         yield sandbox
-      rescue TrapError
-        release_capacity!
-        sandbox = nil
-        raise
       ensure
-        checkin(sandbox) if sandbox
+        checkin(sandbox)
       end
     end
 
     private
 
-    # The idle-first claim loop: an idle Sandbox wins, unclaimed
-    # capacity constructs, and a full pool waits for a checkin.
     def acquire
       timeout = @checkout_timeout
       deadline = timeout && (monotonic_now + timeout)
@@ -73,11 +56,10 @@ module Kobako
       end
     end
 
-    # Single locked decision point for one claim attempt. Waiting
-    # happens inside the lock (so a checkin can wake it); construction
-    # happens outside (so a slow setup block never holds the lock) —
-    # capacity is reserved here and released by +construct_slot+ on
-    # failure.
+    # Waiting happens inside the lock (so a checkin can wake it);
+    # construction happens outside (so a slow setup block never holds the
+    # lock) — capacity is reserved here and released by +construct_slot+
+    # on failure.
     def claim_or_wait(deadline)
       @mutex.synchronize do
         return [:idle, @idle.pop] unless @idle.empty?
@@ -92,9 +74,7 @@ module Kobako
       end
     end
 
-    # Wait for a checkin or freed capacity; raises
-    # +Kobako::PoolTimeoutError+ once +deadline+ has passed. Must
-    # run while holding +@mutex+.
+    # Must run while holding +@mutex+.
     def await_slot!(deadline)
       remaining = deadline && (deadline - monotonic_now)
       if remaining && remaining <= 0
@@ -105,10 +85,8 @@ module Kobako
       @slot_freed.wait(@mutex, remaining)
     end
 
-    # Construct and set up one pooled Sandbox against the capacity
-    # reserved by +claim_or_wait+. Construction and setup-block errors
-    # propagate to the checkout caller unchanged; the reserved
-    # capacity is released so a later checkout can retry.
+    # A failed construction releases its reserved capacity so a later
+    # checkout can retry.
     def construct_slot
       done = false
       sandbox = Sandbox.new(**@sandbox_options)
@@ -119,7 +97,6 @@ module Kobako
       release_capacity! unless done
     end
 
-    # Return a Sandbox to the idle list and wake one waiting checkout.
     def checkin(sandbox)
       @mutex.synchronize do
         @idle.push(sandbox)
@@ -127,8 +104,6 @@ module Kobako
       end
     end
 
-    # Give back reserved-but-unfilled capacity — a failed construction or
-    # a discarded Sandbox — and wake one waiting checkout to claim it.
     def release_capacity!
       @mutex.synchronize do
         @constructed -= 1
@@ -142,17 +117,12 @@ module Kobako
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
-    # Pre-flight for +slots+ — no coercion, a positive Integer is
-    # the only accepted shape.
     def validate_slots!(slots)
       return if slots.is_a?(Integer) && slots.positive?
 
       raise ArgumentError, "slots must be a positive Integer, got #{slots.inspect}"
     end
 
-    # Coerce +checkout_timeout+ into the Float seconds the wait loop
-    # consumes, or +nil+ to wait indefinitely — the same normalisation
-    # idiom +SandboxOptions+ applies to +timeout+.
     def normalize_checkout_timeout(checkout_timeout)
       return nil if checkout_timeout.nil?
       unless checkout_timeout.is_a?(Numeric)

data/lib/kobako/runtime.rb

@@ -1,27 +1,13 @@
 # frozen_string_literal: true
 
 module Kobako
-  # Host-side wasmtime runtime, surfaced as a Ruby class by the native ext
-  # (see ext/kobako/src/runtime.rs). The +Kobako::Runtime+ class wraps the
-  # wasmtime engine + compiled module + Store; it is the only Ruby-visible
-  # wasmtime type and the foundational binding layer for +Kobako::Sandbox+.
-  #
-  # This file reopens the magnus-defined class only to add the pure-Ruby
-  # +.default_path+ helper. Every other method (+#from_path+ singleton,
-  # +#eval+ / +#run+, capture and usage readers) is registered from Rust
-  # at ext load time.
-  class Runtime
-    # Absolute path to the gem-bundled +data/kobako.wasm+ artifact. Computed
-    # from this file's location so it works for both +bundle exec+ (running
-    # from the repo) and an installed gem (running from the gem dir).
-    #
-    # Returns a String regardless of whether the file currently exists —
-    # call sites that need the file to be present should pass this through
-    # +Kobako::Runtime.from_path+, which raises
-    # +Kobako::ModuleNotBuiltError+ with a clear remediation message.
-    # Raises +Kobako::SetupError+ if +__dir__+ is unavailable so that
-    # +rescue Kobako::SetupError+ around +Kobako::Sandbox.new+ catches every
-    # construction-layer failure uniformly, including this path-resolution one.
+  # The native wasmtime runtime, defined by the ext; this file adds only the
+  # default Guest Binary path.
+  class Runtime # :nodoc:
+    # The path is answered whether or not the file exists; from_path is
+    # where a missing artifact is refused. A missing +__dir__+ raises
+    # SetupError so one rescue around Sandbox.new covers every construction
+    # failure.
     def self.default_path
       dir = __dir__ or raise Kobako::SetupError, "Kobako::Runtime.default_path requires __dir__"
       File.expand_path("../../data/kobako.wasm", dir)

data/lib/kobako/sandbox.rb

@@ -10,168 +10,129 @@ require_relative "catalog"
 require_relative "context"
 
 module Kobako
-  # Kobako::Sandbox — the user-facing entry point for executing guest mruby
-  # scripts inside a wasmtime-hosted Wasm module.
-  #
-  # The Sandbox owns the reusable configuration — the +Kobako::Runtime+ and
-  # the +Kobako::Catalog::Services+ / +Catalog::Snippets+ / +Catalog::Extensions+
-  # registries. Each +#eval+ / +#run+ seals that config on the first call and
-  # drives one guest invocation through a fresh +Kobako::Context+ — its own
-  # Handle table, dispatch +Proc+, captures, and usage — so the reusable
-  # Sandbox holds no per-invocation state. The underlying wasmtime Engine and
-  # compiled Module are cached at process scope by the native ext and never
-  # surface to Ruby — constructing many Sandboxes amortises both costs
-  # automatically.
-  #
-  # A run's observables — the captured +#stdout+ / +#stderr+ (bounded by
-  # +stdout_limit+ / +stderr_limit+, enforced inside the WASI pipe) with their
-  # +#stdout_truncated?+ / +#stderr_truncated?+ predicates, and +#usage+ — live
-  # on the +Kobako::Execution+ each +#eval+ / +#run+ returns, or on the one its
-  # raised error carries. The Sandbox itself keeps none of them, so nothing a
-  # run observes carries into the next one.
+  # Runs untrusted mruby scripts in an isolated Wasm instance. Configure it
+  # once, binding Services and preloading snippets, then call #eval or #run as
+  # often as needed: each call returns an Execution and leaves nothing behind
+  # for the next.
   class Sandbox
     extend Forwardable
 
-    attr_reader :wasm_path, :options
+    # The Guest Binary this Sandbox runs.
+    attr_reader :wasm_path
+
+    # The SandboxOptions this Sandbox was built with. Each option is also
+    # readable on the Sandbox itself, as in #timeout.
+    attr_reader :options
 
-    # Per-option accessors forward to the immutable +SandboxOptions+ Value
-    # Object so the Host App still reads them off Sandbox directly.
     def_delegators :@options, :timeout, :memory_limit, :stdout_limit, :stderr_limit, :profile, :gvl
 
-    # Build a fresh Sandbox.
+    # Build a Sandbox on the Guest Binary at +wasm_path+, the one bundled
+    # with the gem by default. The other keywords are the options
+    # SandboxOptions describes.
     #
-    # +wasm_path+ is the absolute path to the Guest Binary; defaults to the
-    # gem-bundled +data/kobako.wasm+. Every other keyword — the four caps
-    # (+stdout_limit+, +stderr_limit+, +timeout+, +memory_limit+) and the
-    # requested isolation profile (+profile+) — is forwarded verbatim to
-    # +Kobako::SandboxOptions+, which owns the DEFAULT fallbacks and
-    # normalisation. The constructed +SandboxOptions+ is exposed as
-    # +#options+ and every option remains readable directly on Sandbox via
-    # +Forwardable+ delegation. The runtime builds the requested profile —
-    # +:hermetic+ (the default) denies the guest ambient time and entropy,
-    # +:permissive+ leaves them live — and construction refuses a runtime
-    # whose declared profile falls below the request, raising
-    # +Kobako::SetupError+ before any invocation entry point runs.
+    # Raises ArgumentError for an invalid option, and SetupError when the
+    # runtime cannot be built or provides less isolation than +profile+ asks
+    # for.
     def initialize(wasm_path: nil, **)
       @wasm_path = wasm_path || Kobako::Runtime.default_path
       @options = SandboxOptions.new(**)
       @services = Kobako::Catalog::Services.new
       @snippets = Catalog::Snippets.new
+      @flags = Catalog::Flags.new
       @extensions = Catalog::Extensions.new
+      @sealed = false
       @runtime = build_runtime!
     end
 
-    # Bind +object+ as the Service reachable at +path+ — a Symbol or
-    # String of one or more +::+-separated constant-form segments
-    # (+"MyService::KV"+ or a top-level +"File"+). Returns +self+ for
-    # chaining.
+    # Make +object+ reachable from the guest as the constant at +path+, a
+    # Symbol or String such as <tt>"MyService::KV"</tt>. Returns +self+.
     #
-    # The guest reaches the public methods +object+'s own class and +object+
-    # itself define in source, fixed at this call — nothing inherited, mixed
-    # in, or built into the platform. An +object+ defining a private
-    # +respond_to_guest?(name)+ decides instead, asked on every call.
+    # The guest reaches the public methods that +object+'s own class and
+    # +object+ itself define in source, nothing inherited or mixed in. An
+    # +object+ defining a private <tt>respond_to_guest?(name)</tt> decides
+    # instead, on every call.
     #
-    # Called with only a +path+, it declares a fillable Service:
-    # +bind(path)+ reserves the path for +Kobako::Unresolved+, so the guest
-    # sees the constant while the host defers the object it stands for. A
-    # guest dispatch to an unfilled fillable surfaces as
-    # +Kobako::ServiceError+ when left unrescued.
+    # Called with only +path+, it declares a fillable Service: the guest sees
+    # the constant, and Context#bind supplies the object for each invocation.
+    # A call to one left unfilled fails as a ServiceError.
     #
-    # Raises +ArgumentError+ when a segment is malformed, when +path+
-    # collides with an existing binding (a name is a bound Service or a
-    # grouping prefix, never both), or when called after the first
-    # invocation has sealed Service registration.
+    # Raises ArgumentError for a malformed path, a path that collides with an
+    # existing binding, or a call after the first invocation.
     def bind(path, object = Unresolved)
+      refuse_once_invoked!("bind")
       @services.bind(path, object)
       self
     end
 
-    # Install one or more Extensions — each a guest idiom (+source+) paired
-    # with an optional host +backend+, composed onto the Sandbox through
-    # +#preload+ and +#bind+. An Extension is any object exposing
-    # +name+ / +source+ / +backend+ / +depends_on+; +Kobako::Extension+ is
-    # the bundled value type. Returns +self+.
+    # Install Extensions, each guest source paired with an optional host
+    # backend. Any object answering +name+, +source+, +backend+ and
+    # +depends_on+ works; Extension is the bundled one. Returns +self+.
     #
-    # Raises +ArgumentError+ for a malformed Extension, a call after the
-    # first invocation seals registration, or — at that first invocation —
-    # an unmet +depends_on+.
+    # Raises ArgumentError for a malformed Extension, a call after the first
+    # invocation, or, at the first invocation, a missing dependency.
     def install(*extensions)
-      raise ArgumentError, "cannot install after first Sandbox invocation" if @services.sealed?
+      refuse_once_invoked!("install")
 
       extensions.each { |extension| @extensions.install(extension, snippets: @snippets, services: @services) }
       self
     end
 
-    # Register a snippet on this Sandbox in one of two forms:
-    #
-    #   * +preload(code: source, name: Name)+ — +source+ is mruby source
-    #     as a +String+ and +Name+ matches +/\A[A-Z]\w*\z/+. Compile
-    #     failures surface as +Kobako::SandboxError+ on the first
-    #     invocation's replay. The +name+
-    #     becomes the snippet's +(snippet:Name)+ backtrace filename and
-    #     is the dedupe key that rejects a duplicate +code:+ snippet.
-    #   * +preload(binary: bytes)+ — +bytes+ is precompiled RITE
-    #     bytecode as a +String+. The canonical name, when present,
-    #     lives in the bytecode's embedded +debug_info+ and is resolved
-    #     by the guest at load time; the host treats the bytes as
-    #     opaque. Structural failures surface as +Kobako::BytecodeError+
-    #     on the first invocation.
+    # Register a snippet that every invocation runs, in the order registered,
+    # before its own code. Returns +self+.
     #
-    # Subsequent invocations (+#eval+ or +#run+) replay every registered
-    # snippet — in insertion order — against the fresh +mrb_state+
-    # before per-invocation source or entrypoint resolution.
+    # [<tt>preload(code: source, name: Name)</tt>]
+    #   mruby source, named <tt>(snippet:Name)</tt> in backtraces.
+    # [<tt>preload(binary: bytes)</tt>]
+    #   Precompiled RITE bytecode, trusted as host code: the unmodified
+    #   compiler output of the mruby release the Guest Binary is built on.
     #
-    # Returns +self+ to allow chaining.
-    #
-    # Raises +ArgumentError+ when neither form's keyword set is
-    # supplied, when both forms are mixed (e.g., +code:+ and +binary:+
-    # together, or +binary:+ paired with +name:+), when +code+ / +bytes+
-    # is not a +String+, when +name+ does not match the constant
-    # pattern, when +name+ duplicates an already-registered +code:+ form
-    # snippet, or when called after the first invocation has sealed the
-    # snippet table.
+    # Raises ArgumentError for a malformed or duplicate snippet, or a call
+    # after the first invocation. A snippet that fails to load fails every
+    # invocation with SandboxError, or BytecodeError for bytecode.
     def preload(code: nil, name: nil, binary: nil)
-      raise ArgumentError, "cannot preload after first Sandbox invocation" if @services.sealed?
+      refuse_once_invoked!("preload")
 
       @snippets.register(code: code, name: name, binary: binary)
       self
     end
 
-    # Dispatch into a preloaded entrypoint constant. Delegates host
-    # pre-flight and argument encoding to +Kobako::Transport::Run+ /
-    # +Kobako::Transport::Run#payload+: a non-Symbol/String +target+ raises
-    # +TypeError+, while a +target+ failing the constant pattern, a forged
-    # +Kobako::Handle+ in +args+ / +kwargs+, or a non-Symbol +kwargs+ key
-    # raise +ArgumentError+. The guest resolves +target+ as a top-level
-    # constant, calls +#call+ on it with +args+ / +kwargs+, and returns the
-    # deserialized result. The first invocation seals the Service registry
-    # and snippet table. Runtime errors follow the same three-class
-    # taxonomy as +#eval+.
+    # Set the flag +name+, a Symbol or String, to +value+ for every
+    # invocation; an empty +value+ is a plain switch. A Guest Binary that
+    # does not recognise the flag fails each invocation with
+    # UnsupportedFlagError, unless +advisory+ says the guest may skip it.
+    # Mark a flag advisory only when a script cannot tell it was skipped.
+    # Returns +self+.
+    #
+    # Raises ArgumentError for a malformed or duplicate flag, or a call after
+    # the first invocation.
+    def flag(name, value = "", advisory: false)
+      refuse_once_invoked!("flag")
+
+      @flags.register(name, value, advisory: advisory)
+      self
+    end
+
+    # Call +call+ on the preloaded top-level constant +target+ with +args+
+    # and +kwargs+, and return the Execution. A given block receives the
+    # invocation's Context before the guest runs.
+    #
+    # Raises TypeError when +target+ is not a Symbol or String, and
+    # ArgumentError when it is not a constant name or the arguments carry a
+    # Handle or a non-Symbol keyword. A failed run raises as #eval does.
     def run(target, *args, **kwargs, &block)
       request = Transport::Run.new(entrypoint: target, args: args, kwargs: kwargs)
       new_invocation.run(request, &block)
     end
 
-    # Execute a guest mruby source string in a fresh +mrb_state+. +code+ is
-    # the mruby source as a UTF-8 String. Returns the deserialized last
-    # expression of the source.
-    #
-    # Source delivery uses the WASI stdin three-frame protocol
-    # ({docs/wire-codec.md Invocation channels}[link:../../docs/wire-codec.md]):
-    # Frame 1 carries the preamble (Service registry snapshot), Frame 2 the
-    # user source UTF-8 bytes, and Frame 3 the snippet table registered via
-    # +#preload+. Each frame is prefixed by a 4-byte big-endian u32 length;
-    # Frame 1 and Frame 3 are mandatory-presence — an empty registry sends a
-    # present, empty frame rather than an absent one.
+    # Evaluate +code+, mruby source as a String, and return the Execution,
+    # whose +value+ is the last expression. A given block receives the
+    # invocation's Context before the guest runs.
     #
-    # The first invocation seals the Service registry and snippet table;
-    # subsequent +#bind+ / +#preload+ calls raise +ArgumentError+.
-    #
-    # Raises +Kobako::TrapError+ on a Wasm trap or wire-violation fallback;
-    # +Kobako::SandboxError+ when the guest ran to completion but failed
-    # (including when +code+ is +nil+ or not a String, or when a preloaded
-    # snippet's replay raises); +Kobako::ServiceError+ on an unrescued
-    # Service capability failure.
+    # Raises TrapError when the engine stopped the guest, a deadline or
+    # memory budget included; SandboxError when the guest failed, +code+ not
+    # being a String or the Guest Binary not starting the run included; and
+    # ServiceError when a Service call failed and the guest left it
+    # unrescued.
     def eval(code, &block)
       raise SandboxError, "code must be a String, got #{code.class}" unless code.is_a?(String)
 
@@ -180,10 +141,8 @@ module Kobako
 
     private
 
-    # Construct the +Runtime+ with the requested isolation profile and
-    # refuse one whose declared posture falls below the request —
-    # +SandboxOptions#enforce_floor!+ owns the ladder comparison, so a
-    # runtime that cannot honor the request never runs guest code.
+    # A runtime whose declared posture falls below the request never runs
+    # guest code.
     def build_runtime!
       runtime = Kobako::Runtime.from_path(@wasm_path, @options.timeout, @options.memory_limit,
                                           @options.stdout_limit, @options.stderr_limit, @options.profile,
@@ -192,23 +151,27 @@ module Kobako
       runtime
     end
 
-    # Seal the config on the first invocation and return a fresh
-    # per-invocation +Context+ for the verb to drive. The Context owns this
-    # run's Handle table, resolved Extension backends, captures, and usage, so
-    # no per-invocation state is written back onto the shared config.
+    # Per-invocation state lives on the Context, so nothing an invocation
+    # does is written back onto the shared config.
     def new_invocation
       begin_invocation!
-      Context.new(runtime: @runtime, services: @services, snippets: @snippets, extensions: @extensions)
+      Context.new(runtime: @runtime, services: @services, snippets: @snippets, flags: @flags,
+                  extensions: @extensions)
+    end
+
+    # Registration closes at the first invocation, so every invocation ships
+    # the same Services, snippets, flags and Extensions.
+    def refuse_once_invoked!(verb)
+      raise ArgumentError, "cannot #{verb} after first Sandbox invocation" if @sealed
     end
 
-    # Per-invocation prologue on the config tier: seals the Service and
-    # Extension registries on the first call (idempotent — asserting Extension
-    # dependencies then). The Service seal is the one +#bind+ / +#preload+ /
-    # +#install+ all gate on. Per-invocation provider resolution and observable
-    # state live on the +Context+, not here.
+    # Sealing before the dependency check keeps a Sandbox whose check failed
+    # closed to further registration. The sealed snippets are compiled once,
+    # before the first invocation replays them.
     def begin_invocation!
-      @services.seal!
-      @extensions.seal!
+      @sealed = true
+      @extensions.assert_dependencies!
+      @snippets.compile { |entries| @runtime.compile(@services.paths, entries, @flags.entries) }
     end
   end
 end