kobako 0.1.2 → 0.2.0

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

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

@@ -1,147 +0,0 @@
-# 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.rb

@@ -1,40 +0,0 @@
-# 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"