kobako 0.1.2 → 0.2.0

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?.parse_panic: (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
+  end
+end

data/sig/kobako/rpc/dispatcher.rbs

@@ -0,0 +1,33 @@
+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

@@ -0,0 +1,51 @@
+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

@@ -0,0 +1,20 @@
+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

@@ -0,0 +1,19 @@
+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/handle_table.rbs

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

data/sig/kobako/rpc/namespace.rbs

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,37 @@
+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/rpc.rbs

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

data/sig/kobako/sandbox.rbs

@@ -0,0 +1,53 @@
+module Kobako
+  class Sandbox
+    DEFAULT_OUTPUT_LIMIT: Integer
+
+    DEFAULT_TIMEOUT_SECONDS: Float
+
+    DEFAULT_MEMORY_LIMIT: Integer
+
+    attr_reader wasm_path: String
+    attr_reader instance: Kobako::Wasm::Instance
+    attr_reader stdout_limit: Integer
+    attr_reader stderr_limit: Integer
+    attr_reader timeout: Float?
+    attr_reader memory_limit: Integer?
+    attr_reader services: Kobako::RPC::Server
+
+    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
+
+    def define: (Symbol | String name) -> Kobako::RPC::Namespace
+
+    def run: (String source) -> untyped
+
+    private
+
+    def clear_captures!: () -> void
+
+    def normalize_timeout: ((Float | Integer)? timeout) -> Float?
+
+    def normalize_memory_limit: (Integer? memory_limit) -> Integer?
+
+    def reset_run_state!: () -> void
+
+    def read_captures!: () -> void
+
+    def run_guest: (String preamble, String source) -> void
+
+    def take_result!: () -> untyped
+  end
+end

data/sig/kobako/wasm.rbs

@@ -0,0 +1,37 @@
+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 run: (String preamble, String source) -> void
+
+      def stdout: () -> [String, bool]
+
+      def stderr: () -> [String, bool]
+
+      def outcome!: () -> String
+    end
+  end
+end

data/sig/kobako.rbs

@@ -1,4 +1,3 @@
 module Kobako
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kobako
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Aotokitsuruya
@@ -61,27 +61,47 @@ files:
 - ext/kobako/src/wasm/host_state.rs
 - ext/kobako/src/wasm/instance.rs
 - lib/kobako.rb
+- lib/kobako/capture.rb
+- lib/kobako/codec.rb
+- lib/kobako/codec/decoder.rb
+- lib/kobako/codec/encoder.rb
+- lib/kobako/codec/error.rb
+- lib/kobako/codec/factory.rb
+- lib/kobako/codec/utils.rb
 - lib/kobako/errors.rb
-- lib/kobako/registry.rb
-- lib/kobako/registry/dispatcher.rb
-- lib/kobako/registry/handle_table.rb
-- lib/kobako/registry/service_group.rb
+- lib/kobako/outcome.rb
+- lib/kobako/outcome/panic.rb
+- lib/kobako/rpc.rb
+- lib/kobako/rpc/dispatcher.rb
+- lib/kobako/rpc/envelope.rb
+- lib/kobako/rpc/fault.rb
+- lib/kobako/rpc/handle.rb
+- lib/kobako/rpc/handle_table.rb
+- lib/kobako/rpc/namespace.rb
+- lib/kobako/rpc/server.rb
 - lib/kobako/sandbox.rb
-- lib/kobako/sandbox/outcome_decoder.rb
-- lib/kobako/sandbox/output_buffer.rb
 - lib/kobako/version.rb
 - lib/kobako/wasm.rb
-- lib/kobako/wire.rb
-- lib/kobako/wire/codec.rb
-- lib/kobako/wire/codec/decoder.rb
-- lib/kobako/wire/codec/encoder.rb
-- lib/kobako/wire/codec/error.rb
-- lib/kobako/wire/codec/factory.rb
-- lib/kobako/wire/envelope.rb
-- lib/kobako/wire/envelope/payloads.rb
-- lib/kobako/wire/exception.rb
-- lib/kobako/wire/handle.rb
 - sig/kobako.rbs
+- sig/kobako/capture.rbs
+- sig/kobako/codec/decoder.rbs
+- sig/kobako/codec/encoder.rbs
+- sig/kobako/codec/error.rbs
+- sig/kobako/codec/factory.rbs
+- sig/kobako/codec/utils.rbs
+- sig/kobako/errors.rbs
+- sig/kobako/outcome.rbs
+- sig/kobako/outcome/panic.rbs
+- sig/kobako/rpc.rbs
+- sig/kobako/rpc/dispatcher.rbs
+- sig/kobako/rpc/envelope.rbs
+- sig/kobako/rpc/fault.rbs
+- sig/kobako/rpc/handle.rbs
+- sig/kobako/rpc/handle_table.rbs
+- sig/kobako/rpc/namespace.rbs
+- sig/kobako/rpc/server.rbs
+- sig/kobako/sandbox.rbs
+- sig/kobako/wasm.rbs
 homepage: https://github.com/elct9620/kobako
 licenses:
 - Apache-2.0

data/lib/kobako/registry/dispatcher.rb

@@ -1,168 +0,0 @@
-# frozen_string_literal: true
-
-module Kobako
-  class Registry
-    # Pure-function dispatcher for guest-initiated RPC calls. Decodes a
-    # msgpack-encoded Request envelope, resolves the target object through the
-    # Registry (path lookup or HandleTable lookup), invokes the method, and
-    # returns a msgpack-encoded Response envelope.
-    #
-    # The module is stateless — all mutable state is threaded through the
-    # +registry+ argument so Dispatcher has no instance variables and no side
-    # effects beyond mutating the HandleTable via +alloc+ when a non-wire-
-    # representable return value must be wrapped ({SPEC.md B-14}[link:../../../SPEC.md]).
-    #
-    # Entry point:
-    #
-    #   Kobako::Registry::Dispatcher.dispatch(request_bytes, registry)
-    #   # => msgpack-encoded Response bytes (never raises)
-    module Dispatcher
-      module_function
-
-      # Internal sentinel raised when target resolution fails. Mapped to
-      # Response.err with type="undefined". Contained at the wire boundary —
-      # not part of the public Kobako error taxonomy
-      # ({SPEC.md E-xx}[link:../../../SPEC.md]).
-      class UndefinedTargetError < StandardError; end
-
-      # Internal sentinel raised when a Handle target resolves to the
-      # +:disconnected+ sentinel in the HandleTable (ABA protection,
-      # {SPEC.md E-14}[link:../../../SPEC.md]). Mapped to Response.err with
-      # type="disconnected". Contained at the wire boundary.
-      class DisconnectedTargetError < StandardError; end
-
-      # Dispatch a single RPC request and return the encoded response bytes.
-      # Called by +Kobako::Registry#dispatch+ which is invoked from the Rust
-      # ext inside +__kobako_rpc_call+. +request_bytes+ is the msgpack-encoded
-      # Request envelope. +registry+ is the live registry for this run, used
-      # to resolve path-based targets via +#lookup+ and to access the
-      # +#handle_table+ for Handle-based targets and return-value wrapping.
-      # Always returns a binary String — never raises. Any failure during
-      # decode, lookup, or method invocation is reified as a Response.err
-      # envelope so the guest sees the failure as a normal RPC error rather
-      # than a wasm trap
-      # ({SPEC.md B-12}[link:../../../SPEC.md]).
-      def dispatch(request_bytes, registry)
-        value = perform_dispatch(request_bytes, registry)
-        encode_ok_or_wrap(value, registry)
-      rescue StandardError => e
-        encode_dispatch_error(e)
-      end
-
-      # Map an error raised during dispatch to a Response.err envelope.
-      # +error+ is the +StandardError+ caught at the dispatch boundary. Returns
-      # a msgpack-encoded Response envelope (binary). Four error buckets
-      # ({SPEC.md B-12}[link:../../../SPEC.md]): +Wire::Codec::Error+ →
-      # type="runtime" (wire decode failed); +DisconnectedTargetError+ →
-      # type="disconnected" (E-14); +UndefinedTargetError+ → type="undefined"
-      # (E-13); +ArgumentError+ → type="argument" (B-12 arity mismatch);
-      # everything else → type="runtime".
-      def encode_dispatch_error(error)
-        case error
-        when Kobako::Wire::Codec::Error then encode_err("runtime", "wire decode failed: #{error.message}")
-        when DisconnectedTargetError then encode_err("disconnected", error.message)
-        when UndefinedTargetError    then encode_err("undefined", error.message)
-        when ArgumentError           then encode_err("argument", error.message)
-        else                              encode_err("runtime", "#{error.class}: #{error.message}")
-        end
-      end
-
-      def perform_dispatch(request_bytes, registry)
-        request = Kobako::Wire::Envelope.decode_request(request_bytes)
-        handle_table = registry.handle_table
-        target_object = resolve_target(request.target, registry, handle_table)
-        args = request.args.map { |v| resolve_arg(v, handle_table) }
-        kwargs = request.kwargs.transform_values { |v| resolve_arg(v, handle_table) }
-        invoke(target_object, request.method_name, args, kwargs)
-      end
-
-      # Dispatch +method+ on +target+. +kwargs+ is already Symbol-keyed
-      # (the +Envelope::Request+ invariant pins it). The empty-kwargs
-      # branch omits the +**+ splat so Ruby 3.x's strict kwargs
-      # separation does not reject calls to no-kwarg methods when the
-      # wire carries the uniform empty-map shape.
-      def invoke(target, method, args, kwargs)
-        if kwargs.empty?
-          target.public_send(method.to_sym, *args)
-        else
-          target.public_send(method.to_sym, *args, **kwargs)
-        end
-      end
-
-      # {SPEC.md B-16}[link:../../../SPEC.md] — A Wire::Handle arriving as a positional or keyword
-      # argument identifies a host-side object previously allocated by a prior
-      # RPC's Handle wrap (B-14). Resolve it back to the Ruby object before
-      # the dispatch reaches +public_send+. A Handle whose entry is the
-      # +:disconnected+ sentinel (E-14) raises DisconnectedTargetError so
-      # the dispatcher emits a Response.err with type="disconnected".
-      def resolve_arg(value, handle_table)
-        case value
-        when Kobako::Wire::Handle
-          fetch_live_object(value.id, handle_table)
-        else
-          value
-        end
-      end
-
-      # Resolve a Request target to the Ruby object the Registry (or
-      # HandleTable) holds. String targets go through the Registry;
-      # Handle targets (ext 0x01) go through the HandleTable.
-      #
-      # Target type is already validated by +Wire::Envelope.decode_request+
-      # before this method is reached, so no else-branch is needed here —
-      # the wire layer is the system boundary that enforces the invariant.
-      def resolve_target(target, registry, handle_table)
-        case target
-        when String
-          resolve_path(target, registry)
-        when Kobako::Wire::Handle
-          resolve_handle(target, handle_table)
-        end
-      end
-
-      def resolve_path(path, registry)
-        registry.lookup(path)
-      rescue KeyError => e
-        raise UndefinedTargetError, e.message
-      end
-
-      def resolve_handle(handle, handle_table)
-        fetch_live_object(handle.id, handle_table)
-      end
-
-      # Resolve +id+ through the HandleTable, distinguishing the
-      # +:disconnected+ sentinel (E-14) from an unknown id (E-13).
-      def fetch_live_object(id, handle_table)
-        object = handle_table.fetch(id)
-        raise DisconnectedTargetError, "Handle id #{id} is disconnected" if object == :disconnected
-
-        object
-      rescue Kobako::HandleTableError => e
-        raise UndefinedTargetError, e.message
-      end
-
-      # Encode +value+ as a +Response.ok+ envelope. When the value is not
-      # wire-representable per {SPEC.md B-13}[link:../../../SPEC.md]'s type
-      # mapping, the +UnsupportedType+ rescue routes it through the
-      # HandleTable and re-encodes with the Capability Handle in place
-      # ({SPEC.md B-14}[link:../../../SPEC.md]). The happy path encodes
-      # exactly once.
-      def encode_ok_or_wrap(value, registry)
-        encode_ok(value)
-      rescue Kobako::Wire::Codec::UnsupportedType
-        encode_ok(Kobako::Wire::Handle.new(registry.handle_table.alloc(value)))
-      end
-
-      def encode_ok(value)
-        response = Kobako::Wire::Envelope::Response.ok(value)
-        Kobako::Wire::Envelope.encode_response(response)
-      end
-
-      def encode_err(type, message)
-        exception = Kobako::Wire::Exception.new(type: type, message: message)
-        response = Kobako::Wire::Envelope::Response.err(exception)
-        Kobako::Wire::Envelope.encode_response(response)
-      end
-    end
-  end
-end