kobako 0.3.0 → 0.5.0

data/lib/kobako/transport/yielder.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+require_relative "yield"
+
+module Kobako
+  # See lib/kobako/transport.rb for the umbrella module doc; this file
+  # owns the host-side object that materialises a guest-supplied block as
+  # a Ruby callable the Service method can yield into.
+  module Transport
+    # Host-side stand-in for a guest-supplied block (B-23).
+    #
+    # Each guest call that carries +block_given: true+ gets a Yielder
+    # that the Dispatcher hands to the Service method as +&block+. The
+    # Service method observes it as an ordinary Ruby Proc through
+    # {#to_proc}; +yield val+ / +block.call(val)+ invokes {#yield}, which
+    # serialises the positional args, re-enters the guest via the injected
+    # +yield_to_guest+ lambda
+    # ({docs/behavior.md B-24}[link:../../../docs/behavior.md]), and
+    # reifies the +YieldResponse+ into Ruby control flow:
+    #
+    #   * +tag 0x01+ ok    — return the decoded value to +yield+'s caller
+    #   * +tag 0x02+ break — +throw break_tag, value+ so the Dispatcher's
+    #     +catch+ frame unwinds the Service method
+    #     ({docs/behavior.md B-25}[link:../../../docs/behavior.md])
+    #   * +tag 0x04+ error — raise the +{class, message}+ payload at the
+    #     Service's yield site
+    #
+    # The Dispatcher calls {#invalidate!} from its +ensure+ block once
+    # dispatch completes; any later call to a stashed Yielder then raises
+    # +LocalJumpError+ — the observable shape of
+    # {docs/behavior.md E-23}[link:../../../docs/behavior.md] (escaped
+    # Yielder).
+    class Yielder
+      # +yield_to_guest+ is a +String → String+ callable (typically
+      # +Runtime#yield_to_active_invocation+ bound through a lambda) that
+      # {#yield} invokes to re-enter the guest; +break_tag+ is the +catch+
+      # throw tag the Dispatcher matches against to unwind the Service on
+      # +tag 0x02+.
+      def initialize(yield_to_guest, break_tag)
+        @yield_to_guest = yield_to_guest
+        @break_tag = break_tag
+        @active = true
+      end
+
+      # Re-enter the guest with +args+ and reify the YieldResponse into
+      # Ruby control flow. Raises +LocalJumpError+ if called after
+      # {#invalidate!} (E-23).
+      def yield(*args)
+        raise LocalJumpError, "guest block invoked after host dispatch frame returned" unless @active
+
+        response = Kobako::Transport::Yield.decode(@yield_to_guest.call(Kobako::Codec::Encoder.encode(args)))
+        return response.value if response.ok?
+
+        throw @break_tag, response.value if response.break?
+
+        raise yield_failure(response.value, default: "yield error")
+      end
+
+      # The Proc the Dispatcher passes as +&block+, binding {#yield} so a
+      # Service method's +yield+ / +block.call+ drives the round-trip.
+      def to_proc
+        method(:yield).to_proc
+      end
+
+      # Mark this Yielder dead. Called by the Dispatcher's +ensure+ block
+      # when the originating dispatch frame returns; any later {#yield}
+      # call then raises +LocalJumpError+ (E-23).
+      def invalidate!
+        @active = false
+      end
+
+      private
+
+      # Reify a +YieldResponse+ tag 0x04 payload into a +RuntimeError+ the
+      # Service method observes at its +yield+ site. The +{class, message,
+      # backtrace}+ shape mirrors the +Kobako::Transport::Yield+ tag 0x04
+      # payload; +default+ provides a fallback when the payload is not a
+      # Hash.
+      def yield_failure(payload, default:)
+        return RuntimeError.new(default) unless payload.is_a?(Hash)
+
+        klass = payload["class"] || "RuntimeError"
+        message = payload["message"] || default
+        RuntimeError.new("#{klass}: #{message}")
+      end
+    end
+  end
+end

data/lib/kobako/transport.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "transport/request"
+require_relative "transport/response"
+require_relative "transport/run"
+require_relative "transport/yield"
+require_relative "transport/yielder"
+require_relative "transport/error"
+require_relative "transport/dispatcher"
+
+module Kobako
+  # Kobako::Transport — host↔guest message transport namespace.
+  # Houses the envelope value objects (Request / Response / Run / Yield),
+  # the guest→host +Dispatcher+, and the host→guest +Yielder+.
+  # +Sandbox#initialize+ composes them onto the
+  # +Runtime+ as a dispatch +Proc+ + +yield_to_guest+ lambda pair
+  # ({docs/behavior.md B-12}[link:../../docs/behavior.md]). "RPC" was
+  # deliberately not chosen — it implies a cross-process boundary that
+  # kobako does not have, since host and guest share one OS thread and
+  # one wasm linear memory. See
+  # {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md].
+  module Transport
+  end
+end

data/lib/kobako/usage.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Kobako
+  # Per-last-invocation resource accounting for a +Kobako::Sandbox+
+  # ({docs/behavior.md B-35}[link:../../docs/behavior.md]). Carries two
+  # readers populated by every +#eval+ / +#run+ invocation:
+  #
+  #   * +wall_time+ — the Float number of seconds the guest export call
+  #     spent inside wasmtime during the most recent invocation. The
+  #     measurement bracket aligns with the +timeout+ deadline
+  #     ({docs/behavior.md B-01}[link:../../docs/behavior.md]); time spent
+  #     in host Service callbacks is included, but everything that runs
+  #     after the guest export returns — the post-export
+  #     +OUTCOME_BUFFER+ fetch and decode, plus stdout / stderr capture
+  #     readout — is excluded.
+  #   * +memory_peak+ — the Integer high-water mark, in bytes, of the
+  #     per-invocation +memory.grow+ delta past the linear-memory size
+  #     captured at invocation entry. Same baseline accounting as
+  #     +memory_limit+ ({docs/behavior.md E-20}[link:../../docs/behavior.md]):
+  #     the mruby image's initial allocation and any prior-invocation
+  #     watermark sit outside the measurement. On +MemoryLimitError+
+  #     +memory_peak+ never exceeds the configured cap because the
+  #     rejected +desired+ value is not promoted into the high-water.
+  #
+  # Both readers are populated on every outcome, including +TrapError+
+  # branches, so the Host App can read +Sandbox#usage+ after rescuing a
+  # trap to diagnose how much of the budget the failing invocation
+  # consumed. Before the first invocation +Sandbox#usage+ returns the
+  # pre-invocation sentinel +Kobako::Usage::EMPTY+.
+  #
+  # Built on the +class X < Data.define(...)+ subclass form so the
+  # class body is fully Steep-visible; ruby/rbs upstream documents this
+  # as the Steep-friendly shape and the +Style/DataInheritance+ cop is
+  # disabled on that basis (see +.rubocop.yml+).
+  class Usage < Data.define(:wall_time, :memory_peak)
+    # Pre-invocation sentinel ({docs/behavior.md B-35}[link:../../docs/behavior.md]).
+    # Reused by +Sandbox+ before any invocation has run so callers do not
+    # need to handle a +nil+ +#usage+.
+    EMPTY = new(wall_time: 0.0, memory_peak: 0)
+  end
+end

data/lib/kobako/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kobako
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/kobako.rb

@@ -3,7 +3,8 @@
 require_relative "kobako/version"
 require "kobako/kobako"
 require_relative "kobako/errors"
-require_relative "kobako/rpc"
-require_relative "kobako/rpc/server"
-require_relative "kobako/wasm"
+require_relative "kobako/transport"
+require_relative "kobako/catalog"
+require_relative "kobako/runtime"
+require_relative "kobako/snapshot"
 require_relative "kobako/sandbox"

data/release-please-config.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+  "release-type": "ruby",
+  "last-release-sha": "5694da60b08931ea260e13025689b8d8c47d767a",
+  "packages": {
+    ".": {
+      "component": "kobako",
+      "include-component-in-tag": false,
+      "release-type": "ruby"
+    }
+  },
+  "extra-files": [
+    {
+      "type": "toml",
+      "path": "ext/kobako/Cargo.toml",
+      "jsonpath": "$.package.version"
+    },
+    {
+      "type": "toml",
+      "path": "Cargo.lock",
+      "jsonpath": "$.package[?(@.name=='kobako')].version"
+    }
+  ]
+}

data/sig/kobako/capture.rbs

@@ -7,7 +7,5 @@ module Kobako
     def initialize: (bytes: String, truncated: bool) -> void
 
     def truncated?: () -> bool
-
-    def self.from_ext: (String bytes, bool truncated) -> Capture
   end
 end

data/sig/kobako/{rpc/handle_table.rbs → catalog/handles.rbs}

@@ -1,22 +1,16 @@
 module Kobako
-  module RPC
-    class HandleTable
+  module Catalog
+    class Handles
       def initialize: (?next_id: Integer) -> void
 
-      def alloc: (untyped object) -> Integer
+      def alloc: (untyped object) -> Kobako::Handle
 
       def fetch: (Integer id) -> untyped
 
-      def release: (Integer id) -> untyped
-
       def reset!: () -> self
 
-      def mark_disconnected: (Integer id) -> self
-
       def size: () -> Integer
 
-      def include?: (Integer id) -> bool
-
       private
 
       def require_bound!: (Integer id) -> void

data/sig/kobako/catalog/namespaces.rbs

@@ -0,0 +1,17 @@
+module Kobako
+  module Catalog
+    class Namespaces
+      def initialize: (?handler: Kobako::Catalog::Handles) -> void
+
+      def define: (Symbol | String name) -> Kobako::Namespace
+
+      def lookup: (String target) -> untyped
+
+      def encode: () -> String
+
+      def seal!: () -> self
+
+      def sealed?: () -> bool
+    end
+  end
+end

data/sig/kobako/{snippet/table.rbs → catalog/snippets.rbs}

@@ -1,6 +1,6 @@
 module Kobako
-  module Snippet
-    class Table
+  module Catalog
+    class Snippets
       NAME_PATTERN: Regexp
 
       type entry = Kobako::Snippet::Source | Kobako::Snippet::Binary
@@ -11,15 +11,6 @@ module Kobako
 
       def encode: () -> String
 
-      def each: () { (entry) -> void } -> Array[entry]
-              | () -> Enumerator[entry, Array[entry]]
-
-      def names: () -> Array[Symbol]
-
-      def size: () -> Integer
-
-      def empty?: () -> bool
-
       private
 
       def register_source!: (String? code, (Symbol | String)? name) -> Symbol

data/sig/kobako/{rpc.rbs → catalog.rbs}

@@ -1,4 +1,4 @@
 module Kobako
-  module RPC
+  module Catalog
   end
 end

data/sig/kobako/codec/decoder.rbs

@@ -1,7 +1,8 @@
 module Kobako
   module Codec
     module Decoder
-      def self.decode: (String bytes) -> untyped
+      def self.decode: [T] (String bytes) { (untyped value) -> T } -> T
+                     | (String bytes) -> untyped
 
       private
 

data/sig/kobako/codec/factory.rbs

@@ -23,9 +23,9 @@ module Kobako
       def unpack_symbol: (String payload) -> Symbol
       def register_handle: () -> void
       def register_fault: () -> void
-      def unpack_handle: (String payload) -> Kobako::RPC::Handle
-      def pack_fault: (Kobako::RPC::Fault fault) -> String
-      def unpack_fault: (String payload) -> Kobako::RPC::Fault
+      def unpack_handle: (String payload) -> Kobako::Handle
+      def pack_fault: (Kobako::Fault fault) -> String
+      def unpack_fault: (String payload) -> Kobako::Fault
     end
   end
 end

data/sig/kobako/codec/utils.rbs

@@ -1,9 +1,19 @@
 module Kobako
   module Codec
     module Utils
+      MSGPACK_INT_RANGE: Range[Integer]
+
       def self?.assert_utf8!: (String string, String label) -> void
 
-      def self?.wire_boundary: [T] () { () -> T } -> T
+      def self?.with_boundary: [T] () { () -> T } -> T
+
+      def self?.representable?: (untyped value) -> bool
+
+      def self?.deep_wrap: (untyped value, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.primitive_type?: (untyped value) -> bool
+
+      def self?.container_representable?: (untyped value) -> bool
     end
   end
 end

data/sig/kobako/errors.rbs

@@ -11,6 +11,12 @@ module Kobako
   class MemoryLimitError < TrapError
   end
 
+  class SetupError < Error
+  end
+
+  class ModuleNotBuiltError < SetupError
+  end
+
   class SandboxError < Error
     attr_reader origin: String?
     attr_reader klass: String?
@@ -39,15 +45,9 @@ module Kobako
       ?backtrace_lines: Array[String]?,
       ?details: untyped
     ) -> void
-
-    class Disconnected < ServiceError
-    end
-  end
-
-  class HandleTableError < SandboxError
   end
 
-  class HandleTableExhausted < HandleTableError
+  class HandlerExhaustedError < SandboxError
   end
 
   class BytecodeError < SandboxError

data/sig/kobako/fault.rbs

@@ -0,0 +1,19 @@
+module Kobako
+  class Fault < Data
+    VALID_TYPES: Array[String]
+
+    attr_reader type: String
+    attr_reader message: String
+    attr_reader details: untyped
+
+    def self.new: (type: String, message: String, ?details: untyped) -> Fault
+
+    def initialize: (type: String, message: String, ?details: untyped) -> void
+
+    def with: (?type: String, ?message: String, ?details: untyped) -> Fault
+
+    def ==: (untyped other) -> bool
+
+    def hash: () -> Integer
+  end
+end

data/sig/kobako/handle.rbs

@@ -0,0 +1,18 @@
+module Kobako
+  class Handle
+    MIN_ID: Integer
+    MAX_ID: Integer
+
+    attr_reader id: Integer
+
+    def initialize: (id: Integer) -> void
+
+    def self.restore: (Integer id) -> Handle
+
+    def with: (?id: Integer) -> Handle
+
+    def ==: (untyped other) -> bool
+
+    def hash: () -> Integer
+  end
+end

data/sig/kobako/namespace.rbs

@@ -0,0 +1,19 @@
+module Kobako
+  class Namespace
+    NAME_PATTERN: Regexp
+
+    attr_reader name: String
+
+    def initialize: (String name) -> void
+
+    def bind: (Symbol | String member, untyped object) -> self
+
+    def fetch: (Symbol | String member) -> untyped
+
+    def to_preamble: () -> [String, Array[String]]
+
+    private
+
+    def validate_member_name!: (Symbol | String member) -> String
+  end
+end

data/sig/kobako/outcome.rbs

@@ -13,12 +13,12 @@ module Kobako
 
     def self?.decode_panic: (String body) -> void
 
-    def self?.parse_panic: (String body) -> Panic
+    def self?.build_panic_record: (String body) -> Panic
 
     def self?.build_panic_error: (Panic panic) -> (SandboxError | ServiceError)
 
     def self?.panic_target_class: (Panic panic) -> (singleton(SandboxError) | singleton(ServiceError))
 
-    def self?.build_wire_violation_error: (String message) -> SandboxError
+    def self?.build_transport_error: (String message, ?detail: String?) -> Transport::Error
   end
 end

data/sig/kobako/runtime.rbs

@@ -0,0 +1,23 @@
+module Kobako
+  class Runtime
+    def self.default_path: () -> String
+
+    def self.from_path: (
+      String path,
+      (Float | Integer)? timeout_seconds,
+      Integer? memory_limit,
+      Integer? stdout_limit_bytes,
+      Integer? stderr_limit_bytes
+    ) -> Runtime
+
+    def on_dispatch=: (^(String) -> String dispatch_proc) -> void
+
+    def yield_to_active_invocation: (String args_bytes) -> String
+
+    def eval: (String preamble, String source, String snippets) -> Kobako::Snapshot
+
+    def run: (String preamble, String snippets, String envelope) -> Kobako::Snapshot
+
+    def usage: () -> [Float, Integer]
+  end
+end

data/sig/kobako/sandbox.rbs

@@ -3,10 +3,7 @@ module Kobako
     extend Forwardable
 
     attr_reader wasm_path: String
-    attr_reader instance: Kobako::Wasm::Instance
     attr_reader options: Kobako::SandboxOptions
-    attr_reader services: Kobako::RPC::Server
-    attr_reader snippets: Kobako::Snippet::Table
 
     # Forwarded to @options via Forwardable#def_delegators.
     def timeout: () -> Float?
@@ -30,7 +27,9 @@ module Kobako
 
     def stderr_truncated?: () -> bool
 
-    def define: (Symbol | String name) -> Kobako::RPC::Namespace
+    attr_reader usage: Kobako::Usage
+
+    def define: (Symbol | String name) -> Kobako::Namespace
 
     def preload: (code: String, name: Symbol | String) -> Kobako::Sandbox
                | (binary: String) -> Kobako::Sandbox
@@ -41,12 +40,16 @@ module Kobako
 
     private
 
-    def clear_captures!: () -> void
+    def install_dispatch_proc!: () -> void
+
+    def reset_invocation_state!: () -> void
 
     def begin_invocation!: () -> void
 
-    def read_captures!: () -> void
+    def read_usage!: () -> void
+
+    def trap_class_for: (Kobako::TrapError err) -> singleton(Kobako::TrapError)
 
-    def invoke!: (Symbol verb) { () -> void } -> untyped
+    def invoke!: (Symbol verb) { () -> Kobako::Snapshot } -> untyped
   end
 end

data/sig/kobako/snapshot.rbs

@@ -0,0 +1,15 @@
+module Kobako
+  class Snapshot
+    def return_bytes: () -> String
+    def stdout_bytes: () -> String
+    def stdout_truncated: () -> bool
+    def stderr_bytes: () -> String
+    def stderr_truncated: () -> bool
+    def wall_time: () -> Float
+    def memory_peak: () -> Integer
+
+    def stdout: () -> Kobako::Capture
+    def stderr: () -> Kobako::Capture
+    def usage: () -> Kobako::Usage
+  end
+end

data/sig/kobako/transport/dispatcher.rbs

@@ -0,0 +1,34 @@
+module Kobako
+  module Transport
+    module Dispatcher
+      class UndefinedTargetError < StandardError
+      end
+
+      BREAK_THROW: Symbol
+
+      def self?.dispatch: (String request_bytes, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler, ^(String) -> String yield_to_guest) -> String
+
+      def self?.resolve_call_args: (Kobako::Transport::Request request, Kobako::Catalog::Handles handler) -> [Array[untyped], Hash[Symbol, untyped]]
+
+      def self?.encode_caught_error: (StandardError error) -> String
+
+      def self?.invoke: (untyped target, String method, Array[untyped] args, Hash[Symbol, untyped] kwargs, ?Kobako::Transport::Yielder? yielder) -> untyped
+
+      def self?.resolve_arg: (untyped value, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.resolve_target: (String | Kobako::Handle target, Kobako::Catalog::Namespaces namespaces, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.resolve_path: (String path, Kobako::Catalog::Namespaces namespaces) -> untyped
+
+      def self?.resolve_handle: (Kobako::Handle handle, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.require_live_object!: (Integer id, Kobako::Catalog::Handles handler) -> untyped
+
+      def self?.encode_ok: (untyped value, Kobako::Catalog::Handles handler) -> String
+
+      def self?.wrap_as_handle: (untyped value, Kobako::Catalog::Handles handler) -> Kobako::Handle
+
+      def self?.encode_error: (String type, String message) -> String
+    end
+  end
+end

data/sig/kobako/transport/error.rbs

@@ -0,0 +1,6 @@
+module Kobako
+  module Transport
+    class Error < Kobako::SandboxError
+    end
+  end
+end

data/sig/kobako/transport/request.rbs

@@ -0,0 +1,32 @@
+module Kobako
+  module Transport
+    STATUS_OK: Integer
+    STATUS_ERROR: Integer
+
+    class Request < Data
+      attr_reader target: String | Kobako::Handle
+      attr_reader method_name: String
+      attr_reader args: Array[untyped]
+      attr_reader kwargs: Hash[Symbol, untyped]
+      attr_reader block_given: bool
+
+      def self.new: (target: String | Kobako::Handle, method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> Request
+
+      def self.decode: (String bytes) -> Request
+
+      def initialize: (target: String | Kobako::Handle, method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> void
+
+      def encode: () -> String
+
+      def with: (?target: String | Kobako::Handle, ?method_name: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped], ?block_given: bool) -> Request
+
+      def ==: (untyped other) -> bool
+
+      def hash: () -> Integer
+
+      private
+
+      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> void
+    end
+  end
+end

data/sig/kobako/transport/response.rbs

@@ -0,0 +1,30 @@
+module Kobako
+  module Transport
+    class Response < Data
+      attr_reader status: Integer
+      attr_reader payload: untyped
+
+      def self.ok: (untyped value) -> Response
+
+      def self.error: (Kobako::Fault fault) -> Response
+
+      def self.decode: (String bytes) -> Response
+
+      def self.new: (status: Integer, payload: untyped) -> Response
+
+      def initialize: (status: Integer, payload: untyped) -> void
+
+      def with: (?status: Integer, ?payload: untyped) -> Response
+
+      def ok?: () -> bool
+
+      def error?: () -> bool
+
+      def encode: () -> String
+
+      def ==: (untyped other) -> bool
+
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/kobako/transport/run.rbs

@@ -0,0 +1,27 @@
+module Kobako
+  module Transport
+    class Run < Data
+      NAME_PATTERN: Regexp
+
+      attr_reader entrypoint: Symbol
+      attr_reader args: Array[untyped]
+      attr_reader kwargs: Hash[Symbol, untyped]
+
+      def self.new: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> Run
+
+      def initialize: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> void
+
+      def encode: (Kobako::Catalog::Handles handler) -> String
+
+      private
+
+      def normalize_entrypoint: (Symbol | String target) -> Symbol
+
+      def validate_args!: (Array[untyped] args) -> Array[untyped]
+
+      def validate_kwargs!: (Hash[untyped, untyped] kwargs) -> Hash[Symbol, untyped]
+
+      def forged_handle_message: (String slot) -> String
+    end
+  end
+end