kobako 0.1.0

data/lib/kobako/wire/envelope/payloads.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "../codec"
+
+module Kobako
+  module Wire
+    # Outcome-path envelopes (SPEC.md Outcome Envelope): Result and Panic
+    # value objects plus the tagged Outcome wrapper that frames them on
+    # the wire. The RPC-path counterparts (Request / Response) live in
+    # the parent +envelope.rb+ file.
+    module Envelope
+      # ============================================================
+      # Result (SPEC.md Outcome Envelope → Result)
+      # ============================================================
+      #
+      # Success Outcome payload. SPEC pins the Result envelope as a
+      # 1-element msgpack array carrying the value, keeping framing
+      # symmetric with the Panic envelope so the value position is never
+      # ambiguous.
+      Result = Data.define(:value)
+
+      def self.encode_result(value)
+        Codec::Encoder.encode([value])
+      end
+
+      def self.decode_result(bytes)
+        arr = Codec::Decoder.decode(bytes)
+        unless arr.is_a?(Array) && arr.length == 1
+          raise Codec::InvalidType, "Result envelope must be a 1-element array, got #{arr.inspect}"
+        end
+
+        Result.new(arr[0])
+      end
+
+      # ============================================================
+      # Panic (SPEC.md Outcome Envelope → Panic)
+      # ============================================================
+      #
+      # Failure Outcome payload. Encoded as a msgpack **map** keyed by
+      # name (forward-compatibility — unknown keys are silently ignored).
+      # Required: "origin" / "class" / "message". Optional: "backtrace"
+      # (array of str), "details" (any wire-legal value).
+      Panic = Data.define(:origin, :klass, :message, :backtrace, :details) do
+        def initialize(origin:, klass:, message:, backtrace: [], details: nil)
+          raise ArgumentError, "Panic origin must be String"  unless origin.is_a?(String)
+          raise ArgumentError, "Panic class must be String"   unless klass.is_a?(String)
+          raise ArgumentError, "Panic message must be String" unless message.is_a?(String)
+          unless backtrace.is_a?(Array) && backtrace.all?(String)
+            raise ArgumentError, "Panic backtrace must be Array of String"
+          end
+
+          super
+        end
+      end
+
+      Panic::ORIGIN_SANDBOX = "sandbox"
+      Panic::ORIGIN_SERVICE = "service"
+
+      def self.encode_panic(panic)
+        Codec::Encoder.encode(panic_map(panic))
+      end
+
+      # SPEC: Panic is a msgpack MAP keyed by name. Required keys always
+      # emitted; "backtrace" emitted only when non-empty (keep the wire
+      # compact); "details" only when non-nil. Ruby Hash preserves
+      # insertion order so the resulting msgpack map carries the keys in
+      # the order added below.
+      def self.panic_map(panic)
+        map = { "origin" => panic.origin, "class" => panic.klass, "message" => panic.message }
+        map["backtrace"] = panic.backtrace unless panic.backtrace.empty?
+        map["details"]   = panic.details   unless panic.details.nil?
+        map
+      end
+      private_class_method :panic_map
+
+      def self.decode_panic(bytes)
+        map = Codec::Decoder.decode(bytes)
+        raise Codec::InvalidType, "Panic envelope must be a map, got #{map.class}" unless map.is_a?(Hash)
+
+        Codec.translate_value_object_error do
+          Panic.new(
+            origin: map["origin"], klass: map["class"], message: map["message"],
+            backtrace: map["backtrace"] || [], details: map["details"]
+          )
+        end
+      end
+
+      # ============================================================
+      # Outcome (SPEC.md Outcome Envelope)
+      # ============================================================
+      #
+      # OUTCOME_BUFFER wrapper: one-byte tag (+0x01+ Result, +0x02+ Panic)
+      # followed by the msgpack payload of the corresponding envelope.
+      # Callers construct an +Outcome+ by wrapping the payload directly —
+      # +Outcome.new(Result.new(value))+ or +Outcome.new(panic)+ — so the
+      # contract reads symmetrically across both variants.
+      Outcome = Data.define(:payload) do
+        def initialize(payload:)
+          unless payload.is_a?(Result) || payload.is_a?(Panic)
+            raise ArgumentError, "Outcome payload must be Result or Panic, got #{payload.class}"
+          end
+
+          super
+        end
+
+        def result? = payload.is_a?(Result)
+        def panic?  = payload.is_a?(Panic)
+      end
+
+      def self.encode_outcome(outcome)
+        tag, body = encode_outcome_payload(outcome.payload)
+        out = String.new(encoding: Encoding::ASCII_8BIT)
+        out << [tag].pack("C")
+        out << body
+        out
+      end
+
+      def self.encode_outcome_payload(payload)
+        case payload
+        when Result then [OUTCOME_TAG_RESULT, encode_result(payload.value)]
+        when Panic  then [OUTCOME_TAG_PANIC, encode_panic(payload)]
+        end
+      end
+      private_class_method :encode_outcome_payload
+
+      def self.decode_outcome(bytes)
+        bytes = bytes.b
+        raise Codec::InvalidType, "Outcome bytes must not be empty" if bytes.empty?
+
+        tag = bytes.getbyte(0)
+        body = bytes.byteslice(1, bytes.bytesize - 1)
+        Outcome.new(decode_outcome_payload(tag, body))
+      end
+
+      def self.decode_outcome_payload(tag, body)
+        case tag
+        when OUTCOME_TAG_RESULT then decode_result(body)
+        when OUTCOME_TAG_PANIC  then decode_panic(body)
+        else raise Codec::InvalidType, format("unknown outcome tag 0x%<tag>02x", tag: tag)
+        end
+      end
+      private_class_method :decode_outcome_payload
+    end
+  end
+end

data/lib/kobako/wire/envelope.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative "handle"
+require_relative "exception"
+require_relative "codec"
+
+module Kobako
+  module Wire
+    # Envelope-layer encoders/decoders for the kobako wire contract.
+    #
+    # SPEC.md → Wire Contract pins the logical shape of every host↔guest
+    # message and SPEC.md → Wire Codec → Envelope Frame Layout pins the
+    # binary framing. This module assembles the four envelope kinds
+    # (Request, Response, Result, Panic) and the outer Outcome wrapper on
+    # top of the lower-level {Codec::Encoder} / {Codec::Decoder} primitives.
+    #
+    # The contract collapses into two wire paths:
+    #
+    #   - **RPC path** (lives in this file): Request / Response — guest
+    #     calls a Service, host returns a value or an Exception.
+    #   - **Outcome path** (lives in +envelope/payloads.rb+): Result /
+    #     Panic wrapped in an Outcome envelope — the host reads this
+    #     after +__kobako_run+ to surface either the script's last
+    #     expression or a Sandbox/Service panic.
+    #
+    # The envelope objects are plain Value Objects; they own the field
+    # invariants (raising +ArgumentError+ on violation). The encode/decode
+    # helpers around them own the msgpack framing and translate value-
+    # object faults into the wire-layer +Codec::InvalidType+ taxonomy.
+    module Envelope
+      # ---------------- Outcome tag bytes (SPEC.md Outcome Envelope) -----
+
+      # First byte of the OUTCOME_BUFFER for a Result envelope.
+      OUTCOME_TAG_RESULT = 0x01
+      # First byte of the OUTCOME_BUFFER for a Panic envelope.
+      OUTCOME_TAG_PANIC  = 0x02
+
+      # ---------------- Response status bytes (SPEC.md Response Shape) ---
+
+      # Response variant marker for the success branch.
+      STATUS_OK    = 0
+      # Response variant marker for the error branch.
+      STATUS_ERROR = 1
+
+      # ============================================================
+      # Request (SPEC.md Wire Codec → Request)
+      # ============================================================
+      #
+      # 4-element msgpack array: [target, method, args, kwargs]. +target+
+      # is either a String ("Group::Member") or a {Handle}. SPEC pins
+      # +kwargs+ map keys to ext 0x00 Symbol (→ Wire Codec → Ext Types);
+      # enforced at construction so the Value Object is the single source
+      # of truth.
+      Request = Data.define(:target, :method_name, :args, :kwargs) do
+        def initialize(target:, method:, args: [], kwargs: {})
+          unless target.is_a?(String) || target.is_a?(Handle)
+            raise ArgumentError, "Request target must be String or Handle, got #{target.class}"
+          end
+          raise ArgumentError, "Request method must be String" unless method.is_a?(String)
+          raise ArgumentError, "Request args must be Array"    unless args.is_a?(Array)
+
+          validate_kwargs!(kwargs)
+          super(target: target, method_name: method, args: args, kwargs: kwargs)
+        end
+
+        private
+
+        def validate_kwargs!(kwargs)
+          raise ArgumentError, "Request kwargs must be Hash" unless kwargs.is_a?(Hash)
+
+          kwargs.each_key do |k|
+            raise ArgumentError, "Request kwargs keys must be Symbol, got #{k.class}" unless k.is_a?(Symbol)
+          end
+        end
+      end
+
+      # Encode a {Request} to bytes. The Value Object's own invariants
+      # are the contract; this method does not re-check the shape.
+      def self.encode_request(request)
+        Codec::Encoder.encode([request.target, request.method_name, request.args, request.kwargs])
+      end
+
+      def self.decode_request(bytes)
+        arr = Codec::Decoder.decode(bytes)
+        unless arr.is_a?(Array) && arr.length == 4
+          raise Codec::InvalidType, "Request must be a 4-element array, got #{arr.inspect}"
+        end
+
+        target, method_name, args, kwargs = arr
+        Codec.translate_value_object_error do
+          Request.new(target: target, method: method_name, args: args, kwargs: kwargs)
+        end
+      end
+
+      # ============================================================
+      # Response (SPEC.md Wire Codec → Response)
+      # ============================================================
+      #
+      # 2-element msgpack array: [status, value-or-error]. +status+ is 0
+      # (success) or 1 (error). For success the second element is the
+      # return value; for error it is an {Exception} (ext 0x02 envelope).
+      Response = Data.define(:status, :payload) do
+        def self.ok(value)
+          new(status: STATUS_OK, payload: value)
+        end
+
+        def self.err(exception)
+          unless exception.is_a?(Exception)
+            raise ArgumentError, "Response.err requires Kobako::Wire::Exception, got #{exception.class}"
+          end
+
+          new(status: STATUS_ERROR, payload: exception)
+        end
+
+        def initialize(status:, payload:)
+          unless [STATUS_OK, STATUS_ERROR].include?(status)
+            raise ArgumentError, "Response status must be 0 or 1, got #{status.inspect}"
+          end
+          if status == STATUS_ERROR && !payload.is_a?(Exception)
+            raise ArgumentError, "Response status=1 payload must be Kobako::Wire::Exception"
+          end
+
+          super
+        end
+
+        def ok?  = status == STATUS_OK
+        def err? = status == STATUS_ERROR
+      end
+
+      def self.encode_response(response)
+        Codec::Encoder.encode([response.status, response.payload])
+      end
+
+      def self.decode_response(bytes)
+        arr = Codec::Decoder.decode(bytes)
+        unless arr.is_a?(Array) && arr.length == 2
+          raise Codec::InvalidType, "Response must be a 2-element array, got #{arr.inspect}"
+        end
+
+        status, payload = arr
+        Codec.translate_value_object_error { Response.new(status: status, payload: payload) }
+      end
+    end
+  end
+end
+
+require_relative "envelope/payloads"

data/lib/kobako/wire/exception.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Wire
+    # Wire-level value object for an ext-0x02 Exception envelope.
+    #
+    # SPEC pins the payload (Wire Codec → 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.
+    Exception = 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
+      # +Wire::Handle+.
+      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
+    end
+
+    Exception::VALID_TYPES = %w[runtime argument disconnected undefined].freeze
+  end
+end

data/lib/kobako/wire/handle.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Kobako
+  module Wire
+    # Wire-level value object for an ext-0x01 Capability Handle.
+    #
+    # SPEC pins the binary layout to fixext 4 with a 4-byte big-endian u32
+    # payload (Wire Codec → Ext Types → ext 0x01). ID 0 is reserved as the
+    # invalid sentinel; the maximum valid ID is 0x7fff_ffff (2^31 - 1).
+    #
+    # This is intentionally a thin value object built on +Data.define+ so
+    # equality, hash, and immutability are inherited. The runtime-facing
+    # +Kobako::Handle+ class lives at a higher layer and may add behaviour
+    # (HandleTable bookkeeping, reset semantics). The codec only needs to
+    # carry the opaque integer ID across the wire.
+    Handle = Data.define(:id) do
+      # +MIN_ID+ / +MAX_ID+ live on the Handle class (defined below this
+      # block), not in this block's binding — Data.define's block scope
+      # resolves bare constants against the enclosing +Wire+ module, so
+      # +MIN_ID+ would raise +NameError+. Use +self.class::CONST+ to
+      # reach the constants attached to the Handle class itself. Do not
+      # "simplify" this back to bare +MIN_ID+/+MAX_ID+.
+      def initialize(id:)
+        min = self.class::MIN_ID
+        max = self.class::MAX_ID
+        raise ArgumentError, "Handle id must be Integer" unless id.is_a?(Integer)
+        raise ArgumentError, "Handle id #{id} out of range [#{min}, #{max}]" unless id.between?(min, max)
+
+        super
+      end
+    end
+
+    Handle::MIN_ID = 1
+    Handle::MAX_ID = 0x7fff_ffff
+  end
+end

data/lib/kobako/wire.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Host-side namespace for the kobako wire contract (SPEC.md → Wire
+# Contract). The wire is split into two layers, mirrored on the Rust
+# side by the +codec+ / +envelope+ modules in the +kobako-wasm+ crate:
+#
+#   - {Codec} — byte-level MessagePack codec (SPEC.md → Wire Codec):
+#     {Codec::Encoder}, {Codec::Decoder}, {Codec::Factory}, plus the
+#     {Codec::Error} taxonomy. This is the layer that emits and
+#     consumes raw bytes; ext types 0x01 (Capability Handle) and
+#     0x02 (Exception envelope) are registered exactly once on the
+#     Factory, where the numeric codes live as module-private constants
+#     alongside the Rust-side +codec::EXT_HANDLE+ / +codec::EXT_ERRENV+.
+#
+#   - {Envelope} — logical message framing (SPEC.md → Wire Contract):
+#     {Envelope::Request} / {Envelope::Response} / {Envelope::Result}
+#     / {Envelope::Panic} / {Envelope::Outcome} value objects and
+#     their encode/decode helpers, built on top of {Codec}.
+#
+# {Handle} and {Exception} are value objects that travel through both
+# layers; they live directly under +Wire+ so neither layer "owns" them.
+#
+# The namespace is intentionally self-contained — it does not depend
+# on the native extension or on +lib/kobako.rb+ — so it can be required
+# directly from tests that run on a clean checkout (no compiled artifacts).
+module Kobako
+  # See the file-level documentation above for the layer split. The
+  # module body is intentionally empty: the byte-level codec lives in
+  # {Wire::Codec}, the logical framing in {Wire::Envelope}, and the
+  # shared value objects ({Wire::Handle} / {Wire::Exception}) load
+  # themselves into this namespace via the +require_relative+ calls
+  # below.
+  module Wire
+  end
+end
+
+require_relative "wire/handle"
+require_relative "wire/exception"
+require_relative "wire/codec"
+require_relative "wire/envelope"

data/lib/kobako.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "kobako/version"
+require "kobako/kobako"
+require_relative "kobako/errors"
+require_relative "kobako/wasm"
+require_relative "kobako/sandbox"

data/sig/kobako.rbs

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

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: kobako
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Aotokitsuruya
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: msgpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rb_sys
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.91
+description: kobako provides an in-process Wasm sandbox (wasmtime + mruby) with a
+  MessagePack-based host/guest RPC, allowing Ruby applications to execute untrusted
+  mruby scripts under capability-based Service injection.
+email:
+- contact@aotoki.me
+executables: []
+extensions:
+- ext/kobako/extconf.rb
+extra_rdoc_files: []
+files:
+- Cargo.lock
+- Cargo.toml
+- LICENSE
+- README.md
+- data/kobako.wasm
+- ext/kobako/Cargo.toml
+- ext/kobako/extconf.rb
+- ext/kobako/src/lib.rs
+- ext/kobako/src/wasm.rs
+- ext/kobako/src/wasm/cache.rs
+- ext/kobako/src/wasm/dispatch.rs
+- ext/kobako/src/wasm/host_state.rs
+- ext/kobako/src/wasm/instance.rs
+- lib/kobako.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/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
+homepage: https://github.com/elct9620/kobako
+licenses:
+- Apache-2.0
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/elct9620/kobako
+  source_code_uri: https://github.com/elct9620/kobako
+  changelog_uri: https://github.com/elct9620/kobako/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/elct9620/kobako/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.11
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Embeddable Wasm sandbox for running untrusted mruby code from Ruby applications.
+test_files: []