kobako 0.4.0 → 0.5.0

data/lib/kobako/rpc/fault.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  module RPC
-    # Wire-level value object for an ext-0x02 Exception envelope.
-    #
-    # SPEC pins the payload
-    # ({docs/wire-codec.md}[link:../../../docs/wire-codec.md] § Ext Types
-    # → ext 0x02) to a msgpack map with exactly three keys:
-    #   * "type"    — one of "runtime", "argument", "disconnected", "undefined"
-    #   * "message" — human-readable string
-    #   * "details" — any wire-legal value, or nil when absent
-    #
-    # This object holds the *encoded* form. Reifying the corresponding Ruby
-    # exception class (RuntimeError, ArgumentError, Kobako::ServiceError, ...)
-    # is the responsibility of the dispatch layer, not the codec.
-    #
-    # Built on +Data.define+ so equality, hash, and immutability are
-    # inherited from the value-object machinery; only the field invariants
-    # ride on top.
-    Fault = Data.define(:type, :message, :details) do
-      # +VALID_TYPES+ is attached to the Exception class below this block.
-      # Reach it through +self.class::VALID_TYPES+ — Data.define's block
-      # scope resolves bare constants against the enclosing +Wire+ module,
-      # so a bare +VALID_TYPES+ would raise +NameError+. Same pattern as
-      # +Kobako::Handle+.
-      # steep:ignore:start
-      def initialize(type:, message:, details: nil)
-        valid_types = self.class::VALID_TYPES
-        raise ArgumentError, "type must be String"    unless type.is_a?(String)
-        raise ArgumentError, "message must be String" unless message.is_a?(String)
-        raise ArgumentError, "type=#{type.inspect} not one of #{valid_types.inspect}" unless valid_types.include?(type)
-
-        super
-      end
-      # steep:ignore:end
-    end
-
-    Fault::VALID_TYPES = %w[runtime argument disconnected undefined].freeze
-  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,146 +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::HandleTable+ (lib/kobako/handle_table.rb) and is owned by
-    # the Sandbox — the Server only holds an injected reference so RPC
-    # dispatch resolves against the same table the wire layer allocates
-    # into (docs/behavior.md B-19). 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 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
-
-      # 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.
-      # Forwards both the Server (for namespace lookup) and the injected
-      # +HandleTable+ (for Handle resolution / return-value wrapping) to
-      # +Dispatcher.dispatch+. The Server holds the HandleTable as an
-      # injected reference, not an owned resource — the Sandbox owns it
-      # (B-19) — so the table is not exposed via accessors.
-      def dispatch(request_bytes)
-        Dispatcher.dispatch(request_bytes, self, @handle_table)
-      end
-
-      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/handle_table.rbs

@@ -1,23 +0,0 @@
-module Kobako
-  class HandleTable
-    def initialize: (?next_id: Integer) -> void
-
-    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
-  end
-end

data/sig/kobako/invocation.rbs

@@ -1,25 +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: (Kobako::HandleTable handle_table) -> 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

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, Kobako::HandleTable handle_table) -> 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, Kobako::HandleTable handle_table) -> untyped
-
-      def self?.resolve_target: (String | Kobako::Handle target, Server server, Kobako::HandleTable handle_table) -> untyped
-
-      def self?.resolve_path: (String path, Server server) -> untyped
-
-      def self?.resolve_handle: (Kobako::Handle handle, Kobako::HandleTable handle_table) -> untyped
-
-      def self?.require_live_object!: (Integer id, Kobako::HandleTable handle_table) -> untyped
-
-      def self?.encode_ok: (untyped value, Kobako::HandleTable handle_table) -> String
-
-      def self?.wrap_as_handle: (untyped value, Kobako::HandleTable handle_table) -> Kobako::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::Handle
-      attr_reader method_name: String
-      attr_reader args: Array[untyped]
-      attr_reader kwargs: Hash[Symbol, untyped]
-
-      def initialize: (target: String | Kobako::Handle, method: String, ?args: Array[untyped], ?kwargs: Hash[Symbol, untyped]) -> void
-
-      def with: (?target: String | Kobako::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/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,31 +0,0 @@
-module Kobako
-  module RPC
-    class Server
-      def initialize: (?handle_table: Kobako::HandleTable) -> void
-
-      def define: (Symbol | String name) -> Kobako::RPC::Namespace
-
-      def lookup: (String target) -> untyped
-
-      def bound?: (String target) -> bool
-
-      def size: () -> Integer
-
-      def empty?: () -> bool
-
-      def to_preamble: () -> Array[[String, Array[String]]]
-
-      def encoded_preamble: () -> String
-
-      def seal!: () -> self
-
-      def sealed?: () -> bool
-
-      def dispatch: (String request_bytes) -> String
-
-      private
-
-      def parse_target: (String target) -> [Kobako::RPC::Namespace?, String?, String?]
-    end
-  end
-end

data/sig/kobako/rpc/wire_error.rbs

@@ -1,6 +0,0 @@
-module Kobako
-  module RPC
-    class WireError < Kobako::SandboxError
-    end
-  end
-end

data/sig/kobako/wasm.rbs

@@ -1,41 +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
-
-      def usage: () -> [Float, Integer]
-    end
-  end
-end