kobako 0.5.0-x86_64-linux

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

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

data/lib/kobako.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "kobako/version"
+require "kobako/kobako"
+require_relative "kobako/errors"
+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

@@ -0,0 +1,11 @@
+module Kobako
+  class Capture
+    EMPTY: Capture
+
+    attr_reader bytes: String
+
+    def initialize: (bytes: String, truncated: bool) -> void
+
+    def truncated?: () -> bool
+  end
+end

data/sig/kobako/catalog/handles.rbs

@@ -0,0 +1,19 @@
+module Kobako
+  module Catalog
+    class Handles
+      def initialize: (?next_id: Integer) -> void
+
+      def alloc: (untyped object) -> Kobako::Handle
+
+      def fetch: (Integer id) -> untyped
+
+      def reset!: () -> self
+
+      def size: () -> Integer
+
+      private
+
+      def require_bound!: (Integer id) -> void
+    end
+  end
+end

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/catalog/snippets.rbs

@@ -0,0 +1,27 @@
+module Kobako
+  module Catalog
+    class Snippets
+      NAME_PATTERN: Regexp
+
+      type entry = Kobako::Snippet::Source | Kobako::Snippet::Binary
+
+      def initialize: () -> void
+
+      def register: (?code: String?, ?name: (Symbol | String)?, ?binary: String?) -> (Symbol | nil)
+
+      def encode: () -> String
+
+      private
+
+      def register_source!: (String? code, (Symbol | String)? name) -> Symbol
+
+      def ensure_source_args!: (String? code, (Symbol | String)? name) -> [String, Symbol | String]
+
+      def register_binary!: (String bytes) -> nil
+
+      def entry_payload: (entry) -> Hash[String, untyped]
+
+      def normalize_name: (Symbol | String name) -> Symbol
+    end
+  end
+end

data/sig/kobako/catalog.rbs

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

data/sig/kobako/codec/decoder.rbs

@@ -0,0 +1,12 @@
+module Kobako
+  module Codec
+    module Decoder
+      def self.decode: [T] (String bytes) { (untyped value) -> T } -> T
+                     | (String bytes) -> untyped
+
+      private
+
+      def self.validate_utf8!: (untyped value) -> void
+    end
+  end
+end

data/sig/kobako/codec/encoder.rbs

@@ -0,0 +1,7 @@
+module Kobako
+  module Codec
+    module Encoder
+      def self.encode: (untyped value) -> String
+    end
+  end
+end

data/sig/kobako/codec/error.rbs

@@ -0,0 +1,18 @@
+module Kobako
+  module Codec
+    class Error < StandardError
+    end
+
+    class Truncated < Error
+    end
+
+    class InvalidType < Error
+    end
+
+    class InvalidEncoding < Error
+    end
+
+    class UnsupportedType < Error
+    end
+  end
+end

data/sig/kobako/codec/factory.rbs

@@ -0,0 +1,31 @@
+module Kobako
+  module Codec
+    class Factory
+      include Singleton
+      extend Forwardable
+      extend SingleForwardable
+
+      EXT_SYMBOL: Integer
+      EXT_HANDLE: Integer
+      EXT_ERRENV: Integer
+
+      def dump: (untyped value) -> String
+      def load: (String bytes) -> untyped
+
+      def self.dump: (untyped value) -> String
+      def self.load: (String bytes) -> untyped
+
+      private
+
+      def initialize: () -> void
+      def register_symbol: () -> void
+      def pack_symbol: (Symbol symbol) -> String
+      def unpack_symbol: (String payload) -> Symbol
+      def register_handle: () -> void
+      def register_fault: () -> void
+      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

@@ -0,0 +1,19 @@
+module Kobako
+  module Codec
+    module Utils
+      MSGPACK_INT_RANGE: Range[Integer]
+
+      def self?.assert_utf8!: (String string, String label) -> void
+
+      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

@@ -0,0 +1,55 @@
+module Kobako
+  class Error < StandardError
+  end
+
+  class TrapError < Error
+  end
+
+  class TimeoutError < TrapError
+  end
+
+  class MemoryLimitError < TrapError
+  end
+
+  class SetupError < Error
+  end
+
+  class ModuleNotBuiltError < SetupError
+  end
+
+  class SandboxError < Error
+    attr_reader origin: String?
+    attr_reader klass: String?
+    attr_reader backtrace_lines: Array[String]?
+    attr_reader details: untyped
+
+    def initialize: (
+      String message,
+      ?origin: String?,
+      ?klass: String?,
+      ?backtrace_lines: Array[String]?,
+      ?details: untyped
+    ) -> void
+  end
+
+  class ServiceError < Error
+    attr_reader origin: String?
+    attr_reader klass: String?
+    attr_reader backtrace_lines: Array[String]?
+    attr_reader details: untyped
+
+    def initialize: (
+      String message,
+      ?origin: String?,
+      ?klass: String?,
+      ?backtrace_lines: Array[String]?,
+      ?details: untyped
+    ) -> void
+  end
+
+  class HandlerExhaustedError < SandboxError
+  end
+
+  class BytecodeError < SandboxError
+  end
+end

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/panic.rbs

@@ -0,0 +1,34 @@
+module Kobako
+  module Outcome
+    class Panic
+      ORIGIN_SANDBOX: String
+      ORIGIN_SERVICE: String
+
+      attr_reader origin: String
+      attr_reader klass: String
+      attr_reader message: String
+      attr_reader backtrace: Array[String]
+      attr_reader details: untyped
+
+      def initialize: (
+        origin: String,
+        klass: String,
+        message: String,
+        ?backtrace: Array[String],
+        ?details: untyped
+      ) -> void
+
+      def with: (
+        ?origin: String,
+        ?klass: String,
+        ?message: String,
+        ?backtrace: Array[String],
+        ?details: untyped
+      ) -> Panic
+
+      def ==: (untyped other) -> bool
+
+      def hash: () -> Integer
+    end
+  end
+end

data/sig/kobako/outcome.rbs

@@ -0,0 +1,24 @@
+module Kobako
+  module Outcome
+    TYPE_VALUE: Integer
+    TYPE_PANIC: Integer
+
+    def self?.decode: (String bytes) -> untyped
+
+    def self?.build_trap_error: (Integer? tag) -> TrapError
+
+    def self?.split_tag: (String bytes) -> [Integer?, String]
+
+    def self?.decode_value: (String body) -> untyped
+
+    def self?.decode_panic: (String body) -> void
+
+    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_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

@@ -0,0 +1,55 @@
+module Kobako
+  class Sandbox
+    extend Forwardable
+
+    attr_reader wasm_path: String
+    attr_reader options: Kobako::SandboxOptions
+
+    # Forwarded to @options via Forwardable#def_delegators.
+    def timeout: () -> Float?
+    def memory_limit: () -> Integer?
+    def stdout_limit: () -> Integer
+    def stderr_limit: () -> Integer
+
+    def initialize: (
+      ?wasm_path: String?,
+      ?stdout_limit: Integer?,
+      ?stderr_limit: Integer?,
+      ?timeout: (Float | Integer)?,
+      ?memory_limit: Integer?
+    ) -> void
+
+    def stdout: () -> String
+
+    def stderr: () -> String
+
+    def stdout_truncated?: () -> bool
+
+    def stderr_truncated?: () -> bool
+
+    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
+
+    def run: (Symbol | String target, *untyped args, **untyped kwargs) -> untyped
+
+    def eval: (String code) -> untyped
+
+    private
+
+    def install_dispatch_proc!: () -> void
+
+    def reset_invocation_state!: () -> void
+
+    def begin_invocation!: () -> void
+
+    def read_usage!: () -> void
+
+    def trap_class_for: (Kobako::TrapError err) -> singleton(Kobako::TrapError)
+
+    def invoke!: (Symbol verb) { () -> Kobako::Snapshot } -> untyped
+  end
+end

data/sig/kobako/sandbox_options.rbs

@@ -0,0 +1,32 @@
+module Kobako
+  class SandboxOptions < Data
+    DEFAULT_TIMEOUT_SECONDS: Float
+    DEFAULT_MEMORY_LIMIT: Integer
+    DEFAULT_OUTPUT_LIMIT: Integer
+
+    attr_reader timeout: Float?
+    attr_reader memory_limit: Integer?
+    attr_reader stdout_limit: Integer
+    attr_reader stderr_limit: Integer
+
+    def self.new: (
+      ?timeout: (Float | Integer)?,
+      ?memory_limit: Integer?,
+      ?stdout_limit: Integer?,
+      ?stderr_limit: Integer?
+    ) -> SandboxOptions
+
+    def initialize: (
+      ?timeout: (Float | Integer)?,
+      ?memory_limit: Integer?,
+      ?stdout_limit: Integer?,
+      ?stderr_limit: Integer?
+    ) -> void
+
+    private
+
+    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+
+    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+  end
+end