kobako 0.3.0 → 0.5.0

data/lib/kobako/rpc/handle_table.rb

@@ -1,107 +0,0 @@
-# frozen_string_literal: true
-
-require_relative "handle"
-
-module Kobako
-  module RPC
-    # Host-side mapping from opaque integer Handle IDs to Ruby objects
-    # (capability proxies). One table is owned per +Kobako::RPC::Server+
-    # instance (and therefore per +Kobako::Sandbox+ instance). See
-    # {docs/behavior.md B-15}[link:../../../docs/behavior.md].
-    #
-    # Lifecycle invariants ({docs/behavior.md}[link:../../../docs/behavior.md]):
-    #
-    #   - {docs/behavior.md B-15}[link:../../../docs/behavior.md] — Handle IDs are allocated by
-    #     a monotonically increasing counter scoped to a single `#run`. The
-    #     first ID issued in a run is 1; ID 0 is reserved as the invalid
-    #     sentinel and is never returned by #alloc.
-    #
-    #   - {docs/behavior.md B-19}[link:../../../docs/behavior.md] — When between `#run`
-    #     invocations (via `#reset!`), every Handle issued under the old state
-    #     becomes invalid.
-    #
-    #   - {docs/behavior.md B-21}[link:../../../docs/behavior.md] — The cap is `0x7fff_ffff`
-    #     (2³¹ − 1). Allocation beyond the cap raises immediately — no silent
-    #     truncation, no wrap, no ID reuse.
-    class HandleTable
-      # Build a fresh, empty HandleTable. +next_id+ is an internal seam that
-      # sets the starting value of the monotonic counter (defaults to 1 per
-      # B-15); tests pass a value near +RPC::Handle::MAX_ID+ to exercise
-      # the cap-exhaustion path without 2³¹ allocations.
-      def initialize(next_id: 1)
-        @entries = {} # : Hash[Integer, untyped]
-        @next_id = next_id
-      end
-
-      # Bind +object+ in the table and return its newly-allocated Handle ID.
-      # +object+ is any host-side Ruby object to bind. Returns a freshly-
-      # allocated Handle ID in +[1, RPC::Handle::MAX_ID]+. Raises
-      # +Kobako::HandleTableExhausted+ if the next ID would exceed the cap.
-      # The cap is anchored on +RPC::Handle+ — the wire codec and the
-      # allocator share the same invariant ({docs/behavior.md B-21}[link:../../../docs/behavior.md]).
-      def alloc(object)
-        id = @next_id
-        cap = RPC::Handle::MAX_ID
-        raise HandleTableExhausted, "HandleTable exhausted: id #{id} exceeds MAX_ID #{cap}" if id > cap
-
-        @entries[id] = object
-        @next_id = id + 1
-        id
-      end
-
-      # Resolve a Handle ID to its bound object. +id+ is a Handle ID previously
-      # returned by +#alloc+. Returns the bound object. Raises
-      # +Kobako::HandleTableError+ if +id+ is not currently bound.
-      def fetch(id)
-        require_bound!(id)
-        @entries[id]
-      end
-
-      # Remove and return the binding for +id+. +id+ is the Handle ID to
-      # release. Returns the previously-bound object. Raises
-      # +Kobako::HandleTableError+ if +id+ is not currently bound.
-      def release(id)
-        require_bound!(id)
-        @entries.delete(id)
-      end
-
-      # Clear all entries AND reset the counter to 1. Called at the per-run
-      # boundary — see {docs/behavior.md B-19}[link:../../../docs/behavior.md].
-      # Returns +self+.
-      def reset!
-        @entries.clear
-        @next_id = 1
-        self
-      end
-
-      # Mark the entry at +id+ as disconnected (ABA protection). +id+ is the
-      # Handle ID to poison; silently ignored if +id+ is not currently bound.
-      # Returns +self+ for chainability, matching the convention of +#reset!+.
-      def mark_disconnected(id)
-        @entries[id] = :disconnected if @entries.key?(id)
-        self
-      end
-
-      # Returns the number of currently-bound entries.
-      def size
-        @entries.size
-      end
-
-      # Returns +true+ when +id+ is currently bound, +false+ otherwise.
-      def include?(id)
-        @entries.key?(id)
-      end
-
-      private
-
-      # Single source of truth for the "unknown Handle id" raise shared by
-      # {#fetch} and {#release}. Returns +nil+ on success; raises
-      # +Kobako::HandleTableError+ when +id+ is not currently bound.
-      def require_bound!(id)
-        return if @entries.key?(id)
-
-        raise HandleTableError, "unknown Handle id: #{id.inspect}"
-      end
-    end
-  end
-end

data/lib/kobako/rpc/namespace.rb

@@ -1,74 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  module RPC
-    # A named grouping of Members for one Sandbox
-    # ({docs/behavior.md B-07..B-11}[link:../../../docs/behavior.md]). Returned by
-    # +Sandbox#define+. Each instance owns a flat name→object table of
-    # Members; member binding is validated against {NAME_PATTERN}.
-    class Namespace
-      # Ruby constant-name pattern shared by Namespace and Member names
-      # ({docs/behavior.md B-07/B-08 Notes}[link:../../../docs/behavior.md]).
-      NAME_PATTERN = /\A[A-Z]\w*\z/
-
-      attr_reader :name, :members
-
-      # Build a new Namespace. +name+ is an already-validated Namespace
-      # name (must satisfy {NAME_PATTERN}; validation is the caller's
-      # responsibility).
-      def initialize(name)
-        @name = name
-        @members = {}
-      end
-
-      # Bind +object+ under +member+ inside this Namespace. +member+ is a
-      # constant-form name as a +Symbol+ or +String+. +object+ is any Ruby
-      # object that responds to the methods guest code will invoke. Returns
-      # +self+ for chaining. Raises +ArgumentError+ when +member+ does not
-      # match the constant pattern, or a Member of the same name is already
-      # bound ({docs/behavior.md B-11}[link:../../../docs/behavior.md]).
-      def bind(member, object)
-        member_str = validate_member_name!(member)
-        raise ArgumentError, "Member #{@name}::#{member_str} is already bound" if @members.key?(member_str)
-
-        @members[member_str] = object
-        self
-      end
-
-      # Member lookup. Returns the bound object or +nil+ when missing.
-      def [](member)
-        @members[member.to_s]
-      end
-
-      # Strict variant of {#[]}; raises +KeyError+ when no Member is
-      # registered under +member+.
-      def fetch(member)
-        member_str = member.to_s
-        unless @members.key?(member_str)
-          raise KeyError,
-                "no member named #{member_str.inspect} in namespace #{@name.inspect}"
-        end
-
-        @members[member_str]
-      end
-
-      # Structured description for the guest preamble (Frame 1). Returns a
-      # two-element array +[name, member_keys]+ suitable for msgpack encoding.
-      def to_preamble
-        [@name, @members.keys]
-      end
-
-      private
-
-      def validate_member_name!(member)
-        member_str = member.to_s
-        unless NAME_PATTERN.match?(member_str)
-          raise ArgumentError,
-                "MemberName must match #{NAME_PATTERN.inspect} (got #{member.inspect})"
-        end
-
-        member_str
-      end
-    end
-  end
-end

data/lib/kobako/rpc/server.rb

@@ -1,158 +0,0 @@
-# frozen_string_literal: true
-
-require "msgpack"
-require_relative "../errors"
-require_relative "envelope"
-require_relative "namespace"
-require_relative "handle_table"
-require_relative "dispatcher"
-
-module Kobako
-  module RPC
-    # Kobako::RPC::Server — per-Sandbox host-side RPC coordinator. Maintains
-    # the Namespace / Member registry, owns the HandleTable, and routes
-    # incoming Requests to the resolved Service object
-    # ({docs/behavior.md B-07..B-21}[link:../../../docs/behavior.md]).
-    #
-    # Public API:
-    #
-    #   server = Kobako::RPC::Server.new
-    #   namespace = server.define(:MyService)    # => Kobako::RPC::Namespace
-    #   namespace.bind(:KV, kv_object)           # => namespace (chainable)
-    #   server.to_preamble                       # => array for Frame 1
-    #   server.dispatch(request_bytes)           # => msgpack bytes (delegated to Dispatcher)
-    #
-    # Namespaces live at +Kobako::RPC::Namespace+
-    # (lib/kobako/rpc/namespace.rb). The opaque Handle allocator lives at
-    # +Kobako::RPC::HandleTable+
-    # (lib/kobako/rpc/handle_table.rb). Dispatch helpers live at
-    # +Kobako::RPC::Dispatcher+
-    # (lib/kobako/rpc/dispatcher.rb).
-    class Server
-      # Build a fresh Server. +handle_table+ is an internal seam that
-      # injects a pre-configured +HandleTable+; tests pass one whose +next_id+
-      # is pinned near +MAX_ID+ to exercise the B-21 cap-exhaustion path
-      # without 2³¹ allocations. Production callers leave it at the default.
-      def initialize(handle_table: HandleTable.new)
-        @namespaces = {} # : Hash[String, Kobako::RPC::Namespace]
-        @handle_table = handle_table
-        @sealed = false
-      end
-
-      # Declare or retrieve the Namespace named +name+ (idempotent — docs/behavior.md B-10).
-      # +name+ is a constant-form name as a +Symbol+ or +String+ (must satisfy
-      # +Namespace::NAME_PATTERN+). Returns the +Kobako::RPC::Namespace+ for
-      # that name, creating it if it does not exist. Raises +ArgumentError+
-      # when +name+ is malformed, or when called after the owning Sandbox has
-      # been sealed by its first invocation ({docs/behavior.md B-07}[link:../../../docs/behavior.md]).
-      def define(name)
-        raise ArgumentError, "cannot define after first Sandbox invocation" if @sealed
-
-        name_str = name.to_s
-        unless Namespace::NAME_PATTERN.match?(name_str)
-          raise ArgumentError,
-                "Namespace name must match #{Namespace::NAME_PATTERN.inspect} (got #{name.inspect})"
-        end
-
-        @namespaces[name_str] ||= Namespace.new(name_str)
-      end
-
-      # Resolve a +target+ path of the form +"Namespace::Member"+ to the
-      # bound Host object. +target+ is a two-level path using the +::+
-      # separator. Returns the bound Host object. Raises +KeyError+ when the
-      # namespace or the member is not bound.
-      def lookup(target)
-        namespace, member_name, namespace_name = parse_target(target)
-        raise KeyError, "no namespace named #{namespace_name.inspect}" if namespace.nil?
-        raise KeyError, "no member #{target.inspect} bound on server" unless member_name
-
-        namespace.fetch(member_name)
-      end
-
-      # Returns +true+ when +target+ (a +"Namespace::Member"+ path) resolves
-      # to a bound member, +false+ otherwise.
-      def bound?(target)
-        namespace, member_name, = parse_target(target)
-        !namespace.nil? && !member_name.nil? && !namespace[member_name].nil?
-      end
-
-      # Returns all declared +Kobako::RPC::Namespace+ instances as an +Array+.
-      def namespaces
-        @namespaces.values
-      end
-
-      # Returns the number of declared namespaces as an +Integer+.
-      def size
-        @namespaces.size
-      end
-
-      # Returns +true+ when no namespaces have been declared, +false+ otherwise.
-      def empty?
-        @namespaces.empty?
-      end
-
-      # Structured Frame 1 description. Called by +Sandbox#eval+ when
-      # assembling stdin Frame 1
-      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Returns an
-      # unencoded preamble array — an +Array+ of two-element +[name, members]+
-      # arrays, one per declared namespace.
-      def to_preamble
-        @namespaces.values.map(&:to_preamble)
-      end
-
-      # Encode the preamble as msgpack bytes for stdin Frame 1 delivery
-      # ({docs/behavior.md B-02}[link:../../../docs/behavior.md]). Uses plain MessagePack (no
-      # kobako ext types) because the preamble contains only strings — no
-      # Handles or Fault envelopes. Structure:
-      # +[["Namespace", ["MemberA", "MemberB"]], ...]+. Returns a binary
-      # +String+ of msgpack bytes.
-      def encoded_preamble
-        MessagePack.pack(to_preamble)
-      end
-
-      # Mark the Server as sealed. Called by +Sandbox+ on the first
-      # invocation. After sealing, #define raises ArgumentError. Idempotent.
-      def seal!
-        @sealed = true
-        self
-      end
-
-      # Returns +true+ when {#seal!} has been called, +false+ otherwise.
-      def sealed?
-        @sealed
-      end
-
-      # Reset the HandleTable for a new invocation boundary. Called by
-      # +Sandbox+ before each invocation
-      # ({docs/behavior.md B-19}[link:../../../docs/behavior.md]).
-      def reset_handles!
-        @handle_table.reset!
-      end
-
-      # Dispatch a single RPC request and return the encoded response bytes
-      # ({docs/behavior.md B-12}[link:../../../docs/behavior.md]). +request_bytes+ is a
-      # msgpack-encoded Request envelope. Called by the Rust ext from inside
-      # +__kobako_dispatch+. Always returns a binary +String+ — never raises.
-      # Delegates to +Dispatcher.dispatch+ which reifies any failure as a
-      # +Response.error+ envelope so the guest sees the failure as a normal RPC
-      # error rather than a wasm trap.
-      def dispatch(request_bytes)
-        Dispatcher.dispatch(request_bytes, self)
-      end
-
-      # Expose the +HandleTable+ for tests and wire-layer Handle wrapping.
-      attr_reader :handle_table
-
-      private
-
-      # Split +target+ on the +::+ separator and resolve the namespace half.
-      # Returns +[namespace_or_nil, member_str_or_nil, namespace_name_str]+ so
-      # each public method ({#lookup} / {#bound?}) only owns its boundary
-      # semantics (raise vs predicate).
-      def parse_target(target)
-        namespace_name, member_name = target.to_s.split("::", 2)
-        [@namespaces[namespace_name], member_name, namespace_name]
-      end
-    end
-  end
-end

data/lib/kobako/rpc.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  # Kobako::RPC — protocol namespace for host↔guest RPC. Houses the value
-  # objects that travel on the wire (+Handle+, +Request+, +Response+,
-  # +Fault+) and the host-side Server coordinator. See
-  # {SPEC.md Refinement → Internal Concepts}[link:../../SPEC.md] for the
-  # RPC role split.
-  module RPC
-  end
-end

data/lib/kobako/wasm.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  # Host-side wasmtime wrapper, surfaced as Ruby classes by the native ext
-  # (see ext/kobako/src/wasm.rs). This module is the foundational binding
-  # layer for Sandbox (#14), the run path (#16) and RPC dispatch (#18).
-  #
-  # The classes themselves (Instance) and the error hierarchy (Error /
-  # ModuleNotBuiltError) are defined from Rust at ext load time; this file
-  # only adds the pure-Ruby helpers that have no reason to live in Rust.
-  module Wasm
-    # 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::Wasm::Instance.from_path+, which raises +ModuleNotBuiltError+
-    # with a clear remediation message.
-    def self.default_path
-      dir = __dir__ or raise Error, "Kobako::Wasm.default_path requires __dir__"
-      File.expand_path("../../data/kobako.wasm", dir)
-    end
-  end
-end

data/sig/kobako/invocation.rbs

@@ -1,23 +0,0 @@
-module Kobako
-  class Invocation < 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]) -> Invocation
-
-    def initialize: (entrypoint: Symbol | String, ?args: Array[untyped], ?kwargs: Hash[untyped, untyped]) -> void
-
-    def encode: () -> 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]
-  end
-end

data/sig/kobako/rpc/dispatcher.rbs

@@ -1,33 +0,0 @@
-module Kobako
-  module RPC
-    module Dispatcher
-      class UndefinedTargetError < StandardError
-      end
-
-      class DisconnectedTargetError < StandardError
-      end
-
-      def self?.dispatch: (String request_bytes, Server server) -> String
-
-      def self?.encode_caught_error: (StandardError error) -> String
-
-      def self?.invoke: (untyped target, String method, Array[untyped] args, Hash[Symbol, untyped] kwargs) -> untyped
-
-      def self?.resolve_arg: (untyped value, HandleTable handle_table) -> untyped
-
-      def self?.resolve_target: (String | Kobako::RPC::Handle target, Server server, HandleTable handle_table) -> untyped
-
-      def self?.resolve_path: (String path, Server server) -> untyped
-
-      def self?.resolve_handle: (Kobako::RPC::Handle handle, HandleTable handle_table) -> untyped
-
-      def self?.require_live_object!: (Integer id, HandleTable handle_table) -> untyped
-
-      def self?.encode_ok: (untyped value, Server server) -> String
-
-      def self?.wrap_as_handle: (untyped value, Server server) -> Kobako::RPC::Handle
-
-      def self?.encode_error: (String type, String message) -> String
-    end
-  end
-end

data/sig/kobako/rpc/envelope.rbs

@@ -1,51 +0,0 @@
-module Kobako
-  module RPC
-    STATUS_OK: Integer
-    STATUS_ERROR: Integer
-
-    class Request
-      attr_reader target: String | Kobako::RPC::Handle
-      attr_reader method_name: String
-      attr_reader args: Array[untyped]
-      attr_reader kwargs: Hash[Symbol, untyped]
-
-      def initialize: (target: String | Kobako::RPC::Handle, method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> void
-
-      def with: (?target: String | Kobako::RPC::Handle, ?method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> Request
-
-      def ==: (untyped other) -> bool
-
-      def hash: () -> Integer
-    end
-
-    def self.encode_request: (Request request) -> String
-
-    def self.decode_request: (String bytes) -> Request
-
-    class Response
-      attr_reader status: Integer
-      attr_reader payload: untyped
-
-      def self.ok: (untyped value) -> Response
-
-      def self.error: (Kobako::RPC::Fault fault) -> Response
-
-      def initialize: (Integer status, untyped payload) -> void
-                    | (status: Integer, payload: untyped) -> void
-
-      def with: (?status: Integer, ?payload: untyped) -> Response
-
-      def ok?: () -> bool
-
-      def error?: () -> bool
-
-      def ==: (untyped other) -> bool
-
-      def hash: () -> Integer
-    end
-
-    def self.encode_response: (Response response) -> String
-
-    def self.decode_response: (String bytes) -> Response
-  end
-end

data/sig/kobako/rpc/fault.rbs

@@ -1,20 +0,0 @@
-module Kobako
-  module RPC
-    class Fault
-      VALID_TYPES: Array[String]
-
-      attr_reader type: String
-      attr_reader message: String
-      attr_reader details: untyped
-
-      def initialize: (String type, String message, untyped details) -> void
-                    | (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
-end

data/sig/kobako/rpc/handle.rbs

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

data/sig/kobako/rpc/namespace.rbs

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

data/sig/kobako/rpc/server.rbs

@@ -1,37 +0,0 @@
-module Kobako
-  module RPC
-    class Server
-      attr_reader handle_table: HandleTable
-
-      def initialize: (?handle_table: HandleTable) -> void
-
-      def define: (Symbol | String name) -> Kobako::RPC::Namespace
-
-      def lookup: (String target) -> untyped
-
-      def bound?: (String target) -> bool
-
-      def namespaces: () -> Array[Kobako::RPC::Namespace]
-
-      def size: () -> Integer
-
-      def empty?: () -> bool
-
-      def to_preamble: () -> Array[[String, Array[String]]]
-
-      def encoded_preamble: () -> String
-
-      def seal!: () -> self
-
-      def sealed?: () -> bool
-
-      def reset_handles!: () -> HandleTable
-
-      def dispatch: (String request_bytes) -> String
-
-      private
-
-      def parse_target: (String target) -> [Kobako::RPC::Namespace?, String?, String?]
-    end
-  end
-end

data/sig/kobako/wasm.rbs

@@ -1,39 +0,0 @@
-module Kobako
-  module Wasm
-    class Error < StandardError
-    end
-
-    class ModuleNotBuiltError < Error
-    end
-
-    def self.default_path: () -> String
-
-    class TimeoutError < Error
-    end
-
-    class MemoryLimitError < Error
-    end
-
-    class Instance
-      def self.from_path: (
-        String path,
-        (Float | Integer)? timeout_seconds,
-        Integer? memory_limit,
-        Integer? stdout_limit_bytes,
-        Integer? stderr_limit_bytes
-      ) -> Instance
-
-      def server=: (Kobako::RPC::Server server) -> void
-
-      def eval: (String preamble, String source, String snippets) -> void
-
-      def run: (String preamble, String snippets, String envelope) -> void
-
-      def stdout: () -> [String, bool]
-
-      def stderr: () -> [String, bool]
-
-      def outcome!: () -> String
-    end
-  end
-end