jrpc 2.0.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9d76a4b0925e75829ba1a406594a0ef8f0c8045e38d6a06362c3eac2892affb
-  data.tar.gz: f6f28cf60f79bd9108f82299b8cac6ada99ae3a0a80bcc85baa3fa1b51c86560
+  metadata.gz: 84a616f81dad776fc7efea4d4e8fd778a3e2d5b42568118f0206f44f9b4e1b10
+  data.tar.gz: b8e8a2d8468d5e713e9015faccea22370775b99e476f17b4962cc0ebdc504d35
 SHA512:
-  metadata.gz: 365d4ab7d191d4853b48f9c05875afb11e4619bf4a8a733b66bf52f8dd79bcb702c4d91bdff561088bee4086dcda01af58c3ee4ce0e89d838c8490019c827aaa
-  data.tar.gz: cb74295dd00108aa5e2de6bf93584204e903a36aa523cb6ea44cc5f18bf787c3273969a8cb18d89efbed89db8757b65ad24a45ba5ba66cd49aa2518413f989b8
+  metadata.gz: a58ecaa54dcaafae9871d5c7264e03adc57946859b75b72112a79bc7595df81495e5a4910fe69da28b66bf1b82c0cdb3026a5ccc0ea4f6786e81c50fea030413
+  data.tar.gz: abc7911d9cc8ffac7481decc11e01fc7524b1ce800c65c5bf7652c3567adad66ceedae7c63353f6f160a123957528254434807e58911dbaa61c221e3ee30727f

data/CHANGELOG.md

@@ -1,6 +1,45 @@
 # Changelog
 
-### Unreleased
+### 2.2.0
+
+**New**
+
+* `JRPC::Errors::ServerError#data` — the JSON-RPC `error.data` member is now carried
+  onto the raised exception instead of being dropped. `Message.error_to_exception`
+  reads `error['data']` and passes it to every `ServerError` subclass built from a peer
+  error object, verbatim and untyped (String, Hash, Array, … — whatever the peer sent),
+  `nil` when omitted. It is the only machine-readable detail an error object carries
+  beyond `code`, and servers use it to say *which* param was invalid or *which* id
+  conflicted. `MalformedResponseError` is raised locally rather than mapped from a peer
+  error object, so its `data` is always `nil`.
+  `JRPC::Transport::Test` emits a `data` member when a handler raises an error that
+  carries one, so the round trip is testable. Backwards compatible: on those classes
+  `data:` is a keyword with a `nil` default, and the wire frame is unchanged when there
+  is no data — the member is omitted, never emitted as `null`.
+
+### 2.1.0
+
+**New**
+
+* Debug-level wire-payload logging. When a `logger:` is configured, both
+  `SimpleClient` and `SharedClient` emit every request/response payload (the raw
+  JSON frame, exactly as written/read) at `DEBUG`, tagged `[JRPC::SimpleClient]`
+  / `[JRPC::SharedClient]` with `>>` (sent) / `<<` (received) markers. No logger,
+  no logging.
+* `JRPC::Transport::Test` — an in-process transport double for testing code that
+  uses JRPC, without a real server. Not required by default: `require
+  'jrpc/transport/test'`, then inject via `transport:` on either client. Stub
+  methods with `on('method') { |params| ... }` (return value becomes the result;
+  raise a `JRPC::Errors::ServerError` for an error response, or a transport error
+  to simulate a socket failure); records `requests`/`notifications`/`sent` for
+  assertions. A raw escape hatch (`push_response`/`push_raise`, `strict: false`)
+  covers malformed-response, id-mismatch, and orphan-frame cases. Works with both
+  `SimpleClient` and `SharedClient`. (Closes #10.)
+* Optional TCP MD5 Signature (RFC2385) support. Pass `tcp_md5_pass:` to
+  `SimpleClient`/`SharedClient` (or the transport directly) to authenticate the
+  connection with a per-peer MD5 key. Linux-only (`TCP_MD5SIG`); the key is
+  installed on the socket before connect, and a connect on a kernel/platform
+  without `TCP_MD5SIG` raises `ConnectionError`.
 
 ### 2.0.0
 

data/Gemfile

@@ -5,16 +5,15 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in jrpc.gemspec
 gemspec
 
-gem 'bundler'
 gem 'rake', '~> 13.0'
 gem 'rspec', '~> 3.0'
 
 # Provides a real Fiber.scheduler for the fiber-caller specs (SharedClient §9.8).
 gem 'async', '~> 2.0'
 
-gem 'rubocop', '~> 1.21'
-gem 'rubocop-performance'
-gem 'rubocop-rspec'
+gem 'rubocop', '~> 1.90.0'
+gem 'rubocop-performance', '~> 1.27.0'
+gem 'rubocop-rspec', '~> 3.10.2'
 gem 'rubocop-rake', '~> 0.7.1'
 
 gem 'simplecov', '~> 0.22', require: false

data/README.md

@@ -1,6 +1,9 @@
 # JRPC
 
-A JSON-RPC 2.0 client for Ruby, over TCP, with netstring framing.
+[![Gem Version](https://badge.fury.io/rb/jrpc.svg)](https://rubygems.org/gems/jrpc)
+[![CI](https://github.com/didww/jrpc/actions/workflows/ci.yml/badge.svg)](https://github.com/didww/jrpc/actions/workflows/ci.yml)
+
+A JSON-RPC v2 client for Ruby, over TCP, with netstring framing.
 
 JRPC ships two clients with sharp, separate responsibilities:
 
@@ -37,7 +40,8 @@ client = JRPC::SimpleClient.new(
   connect_retry_count: 0,     # retries after the first failed connect
   autoclose:           false, # close the socket after every call
   id_prefix:           nil,   # random per instance if nil
-  logger:              nil
+  tcp_md5_pass:        nil,   # RFC2385 TCP MD5 Signature key (Linux-only); nil disables
+  logger:              nil    # when set, logs every wire payload at DEBUG; nil disables
 )
 
 result = client.request(:sum, [1, 2])
@@ -72,7 +76,8 @@ client = JRPC::SharedClient.new(
   default_ttl:            30,     # per-message lifetime, seconds
   max_queue_size:         10_000, # bounded; pass nil for unbounded (opt-in OOM risk)
   id_prefix:              nil,
-  logger:                 nil
+  tcp_md5_pass:           nil,    # RFC2385 TCP MD5 Signature key (Linux-only); nil disables
+  logger:                 nil     # when set, logs every wire payload at DEBUG; nil disables
 )
 
 result = client.request(:sum, [1, 2])
@@ -128,6 +133,7 @@ Errors::Error (RuntimeError)
 ├── Errors::Timeout              # message TTL elapsed, or SimpleClient read/write/connect timeout
 └── Errors::ServerError          # peer returned an error, or the response was unusable
        attr_reader :code         # nil for malformed responses
+       attr_reader :data         # the error object's `data` member, nil when absent
        ├── Errors::ParseError              # -32700
        ├── Errors::InvalidRequest          # -32600
        ├── Errors::MethodNotFound          # -32601
@@ -140,11 +146,17 @@ Errors::Error (RuntimeError)
 
 `MalformedResponseError` is a `ServerError`, not a `ClientError`: a malformed response is the peer's fault.
 
+`#data` carries the error object's optional `data` member through untouched — a String,
+Hash, Array or number, whatever the peer sent, and `nil` when it sent none. It is where a
+server says *which* param was invalid or *which* id conflicted, so log it alongside the
+code. `MalformedResponseError` is raised locally rather than built from a peer error
+object, so its `data` is always `nil`.
+
 ```ruby
 begin
   client.request(:do_thing, [1, 2])
 rescue JRPC::Errors::ServerError => e
-  warn "rpc error #{e.code}: #{e.message}"
+  warn "rpc error #{e.code}: #{e.message} #{e.data.inspect}"
 rescue JRPC::Errors::Timeout
   warn "timed out"
 rescue JRPC::Errors::ConnectionError => e
@@ -161,6 +173,78 @@ require 'oj'
 Oj.mimic_JSON
 ```
 
+## TCP MD5 Signature (RFC2385)
+
+Both clients accept `tcp_md5_pass:` to enable per-connection authentication via the
+[TCP MD5 Signature option](https://www.rfc-editor.org/rfc/rfc2385). The kernel signs and
+verifies every TCP segment with `MD5(key + segment + addresses/ports)`; a peer with a
+mismatched or absent key has its segments silently dropped, so the handshake never
+completes.
+
+```ruby
+client = JRPC::SimpleClient.new("10.0.0.2:1234", tcp_md5_pass: "shared-secret")
+```
+
+- **Linux-only.** It relies on the `TCP_MD5SIG` socket option (and a kernel built with
+  `CONFIG_TCP_MD5SIG`). When `tcp_md5_pass` is set on a platform/kernel without it, the
+  first connect raises `ConnectionError` — the option never silently no-ops.
+- **The server must be configured with the same key for this client's address.** JRPC
+  only sets the client side; the peer (e.g. a router/BGP-style endpoint, or another
+  socket with a matching `TCP_MD5SIG`) must agree on the key.
+- **Key length is capped at 80 bytes** (`TCP_MD5SIG_MAXKEYLEN`); a longer key raises
+  `ConnectionError`.
+- The key is installed on the socket **before** connect, so it also protects the
+  handshake itself. It survives reconnects (reaping, connection drops) transparently.
+
+## Testing
+
+`JRPC::Transport::Test` is an in-process transport double for testing code that
+talks to a JSON-RPC server, without standing up a real one. It is **not** loaded
+by default — require it explicitly from your test setup:
+
+```ruby
+require 'jrpc/transport/test'
+
+transport = JRPC::Transport::Test.new
+transport.on('sum') { |params| params['a'] + params['b'] }
+
+client = JRPC::SimpleClient.new('test', transport: transport)
+client.request('sum', { 'a' => 1, 'b' => 2 }) # => 3
+
+transport.last_request # => { "jsonrpc" => "2.0", "method" => "sum", "params" => {...}, "id" => "..." }
+```
+
+Inject it through the `transport:` option of either `SimpleClient` or `SharedClient`.
+
+**Handlers** are the high-level API. A handler's return value is encoded as a result
+response echoing the request id. Raise to produce other outcomes:
+
+```ruby
+# JSON-RPC error response (mapped back to the matching JRPC::Errors class on the caller):
+transport.on('lookup') { raise JRPC::Errors::MethodNotFound, 'no such method' }
+
+# Simulated socket-level failure, raised when the client reads the response:
+transport.on('flaky') { raise JRPC::Transport::Base::ConnectionError, 'peer reset' }
+```
+
+In **strict mode (the default)** a request for a method with no handler raises
+`JRPC::Transport::Test::UnexpectedRequest` at write time, so a missing stub fails
+loudly instead of hanging. Pass `strict: false` to drive reads entirely with the
+raw escape hatch:
+
+```ruby
+transport = JRPC::Transport::Test.new(strict: false)
+# Feed literal response frames — for malformed responses, id mismatches, orphans:
+transport.push_response({ 'jsonrpc' => '2.0', 'id' => 'abc', 'result' => 42 })
+transport.push_raise(JRPC::Transport::Base::MalformedFrame.new('garbage'))
+```
+
+Other helpers: `fail_connect(error)` arms `connect` to raise; `requests`,
+`notifications`, and `sent` expose recordings for assertions; `reset` clears
+recordings and queued frames (keeping handlers). The transport opens a Unix
+socketpair so `SharedClient`'s `IO.select` loop works — call `shutdown` (e.g. in an
+`after` hook) for deterministic FD cleanup, or let the GC finalizer reclaim it.
+
 ## CLI tools
 
 Two executables ship with the gem:

data/lib/jrpc/errors.rb

@@ -11,15 +11,22 @@ module JRPC
 
     class Timeout < Error; end
 
+    # A JSON-RPC error object the peer sent back, carrying its `code` and its optional
+    # `data` member verbatim. Per the spec `data` is "a primitive or structured value"
+    # defined by the server, so it arrives as whatever JSON.parse produced — String,
+    # Hash, Array, Numeric — or nil when the peer omitted it.
     class ServerError < Error
-      attr_reader :code
+      attr_reader :code, :data
 
-      def initialize(message, code: nil)
+      def initialize(message, code: nil, data: nil)
         @code = code
+        @data = data
         super(message)
       end
     end
 
+    # Raised locally when a frame is unparseable or violates the envelope rules, so it
+    # never corresponds to a peer error object: no code, no data.
     class MalformedResponseError < ServerError
       def initialize(message)
         super(message, code: nil)
@@ -27,32 +34,32 @@ module JRPC
     end
 
     class ParseError < ServerError
-      def initialize(message)
-        super(message, code: -32_700)
+      def initialize(message, data: nil)
+        super(message, code: -32_700, data: data)
       end
     end
 
     class InvalidRequest < ServerError
-      def initialize(message)
-        super(message, code: -32_600)
+      def initialize(message, data: nil)
+        super(message, code: -32_600, data: data)
       end
     end
 
     class MethodNotFound < ServerError
-      def initialize(message)
-        super(message, code: -32_601)
+      def initialize(message, data: nil)
+        super(message, code: -32_601, data: data)
       end
     end
 
     class InvalidParams < ServerError
-      def initialize(message)
-        super(message, code: -32_602)
+      def initialize(message, data: nil)
+        super(message, code: -32_602, data: data)
       end
     end
 
     class InternalError < ServerError
-      def initialize(message)
-        super(message, code: -32_603)
+      def initialize(message, data: nil)
+        super(message, code: -32_603, data: data)
       end
     end
 

data/lib/jrpc/message.rb

@@ -49,17 +49,21 @@ module JRPC
       end
     end
 
+    # `error.data` is optional per the spec and is passed through untouched: servers use
+    # it to say *which* param was invalid, *which* id conflicted, and so on — the only
+    # machine-readable detail an error object carries beyond the code.
     def self.error_to_exception(error_hash)
       code = error_hash['code']
       message = error_hash['message']
+      data = error_hash['data']
       case code
-      when -32_700 then Errors::ParseError.new(message)
-      when -32_600 then Errors::InvalidRequest.new(message)
-      when -32_601 then Errors::MethodNotFound.new(message)
-      when -32_602 then Errors::InvalidParams.new(message)
-      when -32_603 then Errors::InternalError.new(message)
-      when -32_099..-32_000 then Errors::InternalServerError.new(message, code: code)
-      else Errors::UnknownError.new(message, code: code)
+      when -32_700 then Errors::ParseError.new(message, data: data)
+      when -32_600 then Errors::InvalidRequest.new(message, data: data)
+      when -32_601 then Errors::MethodNotFound.new(message, data: data)
+      when -32_602 then Errors::InvalidParams.new(message, data: data)
+      when -32_603 then Errors::InternalError.new(message, data: data)
+      when -32_099..-32_000 then Errors::InternalServerError.new(message, code: code, data: data)
+      else Errors::UnknownError.new(message, code: code, data: data)
       end
     end
 

data/lib/jrpc/payload_logging.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module JRPC
+  # Debug-level wire-payload logging shared by the clients. When a `logger` is
+  # configured, every request/response payload (the raw JSON netstring body,
+  # exactly as written/read) is emitted at DEBUG. Without a logger it is a no-op.
+  module PayloadLogging
+    SEND_MARK = '>>'
+    RECV_MARK = '<<'
+
+    def log_sent(payload)
+      @logger&.debug("[#{log_tag}] #{SEND_MARK} #{payload}")
+    end
+
+    def log_received(payload)
+      @logger&.debug("[#{log_tag}] #{RECV_MARK} #{payload}")
+    end
+  end
+end

data/lib/jrpc/shared_client/transport_loop.rb

@@ -3,6 +3,8 @@
 module JRPC
   class SharedClient
     class TransportLoop
+      include PayloadLogging
+
       SELECT_FLOOR = 60.0
 
       def initialize(
@@ -130,6 +132,7 @@ module JRPC
         end
 
         begin
+          log_sent(ticket.payload)
           @transport.write_frame(ticket.payload, timeout: @write_timeout)
         rescue Transport::Base::Timeout => e
           err = Errors::Timeout.new("write timeout: #{e.message}")
@@ -170,6 +173,7 @@ module JRPC
           break if frame == :wait
 
           @last_rx_at = clock_now
+          log_received(frame)
 
           begin
             parsed = Message.parse(frame)
@@ -283,7 +287,11 @@ module JRPC
       end
 
       def log_error(msg)
-        @logger&.error("[JRPC::SharedClient] #{msg}")
+        @logger&.error("[#{log_tag}] #{msg}")
+      end
+
+      def log_tag
+        'JRPC::SharedClient'
       end
     end
   end

data/lib/jrpc/simple_client.rb

@@ -6,6 +6,8 @@ module JRPC
   # concurrent calls would interleave socket reads/writes and corrupt the framing
   # buffer. Use one instance per thread/fiber (or a pool of instances).
   class SimpleClient
+    include PayloadLogging
+
     attr_reader :server
 
     def initialize(server, **options)
@@ -31,8 +33,10 @@ module JRPC
 
       with_transport_error_handling do
         connect_if_needed!
+        log_sent(json)
         @transport.write_frame(json, timeout: write_timeout)
         raw = @transport.read_frame(timeout: read_timeout)
+        log_received(raw)
         response = Message.parse(raw)
         Message.validate_response!(response, id)
         raise Message.error_to_exception(response['error']) if response.key?('error')
@@ -48,6 +52,7 @@ module JRPC
 
       with_transport_error_handling do
         connect_if_needed!
+        log_sent(json)
         @transport.write_frame(json, timeout: write_timeout)
         nil
       end
@@ -67,6 +72,10 @@ module JRPC
 
     private
 
+    def log_tag
+      'JRPC::SimpleClient'
+    end
+
     def connect_if_needed!
       @transport.connect if @transport.closed?
     end

data/lib/jrpc/transport/base.rb

@@ -21,6 +21,9 @@ module JRPC
         @connect_retry_count = options.fetch(:connect_retry_count, 0)
         @connect_retry_interval = options.fetch(:connect_retry_interval, 0.5)
         @write_timeout = options.fetch(:write_timeout, nil)
+        # Optional RFC2385 TCP MD5 Signature key. nil disables it. When set, the
+        # transport installs it on the socket before connect (Linux-only). See Tcp.
+        @tcp_md5_pass = options.fetch(:tcp_md5_pass, nil)
       end
 
       # Abstract interface. Subclasses must implement every method below; the bodies

data/lib/jrpc/transport/tcp.rb

@@ -11,6 +11,13 @@ module JRPC
       Timeout = Base::Timeout
       MalformedFrame = Base::MalformedFrame
 
+      # RFC2385 TCP MD5 Signature. TCP_MD5SIG is a Linux socket option (IPPROTO_TCP
+      # level); it is absent on platforms that don't support it, in which case the
+      # transport raises ConnectionError when a key is requested. The kernel caps the
+      # key at 80 bytes (TCP_MD5SIG_MAXKEYLEN, not exported as a Ruby constant).
+      TCP_MD5SIG = defined?(::Socket::TCP_MD5SIG) ? ::Socket::TCP_MD5SIG : nil
+      TCP_MD5SIG_MAXKEYLEN = 80
+
       def initialize(server, **options)
         super
         @socket = nil
@@ -121,6 +128,7 @@ module JRPC
         @socket = nil
 
         sock, sockaddr = build_socket
+        apply_tcp_md5sig!(sock, sockaddr) if @tcp_md5_pass
 
         loop do
           break if try_connect_nonblock(sock, sockaddr, deadline)
@@ -151,6 +159,47 @@ module JRPC
         raise ConnectionError, "#{e.class}: #{e.message}"
       end
 
+      # Install the RFC2385 TCP MD5 Signature key on the socket *before* connect, keyed
+      # to the peer at +peer_sockaddr+. The kernel then signs and verifies every segment
+      # of the connection; a peer with a mismatched (or absent) key has its segments
+      # silently dropped, so the handshake never completes. Linux-only. Any failure
+      # — unsupported platform, oversized key, or a setsockopt error — closes the
+      # just-built socket (no fd leak) and raises ConnectionError, since a security
+      # option that silently fails to apply is worse than a refused connection.
+      def apply_tcp_md5sig!(sock, peer_sockaddr)
+        raise ConnectionError, 'tcp_md5_pass set but TCP_MD5SIG is unsupported on this platform' if TCP_MD5SIG.nil?
+
+        key = @tcp_md5_pass.b
+        if key.bytesize > TCP_MD5SIG_MAXKEYLEN
+          raise ConnectionError, "tcp_md5_pass is #{key.bytesize} bytes; max is #{TCP_MD5SIG_MAXKEYLEN}"
+        end
+
+        # struct tcp_md5sig: sockaddr_storage(128) + flags(u8) + prefixlen(u8) +
+        # keylen(u16) + ifindex(u32) + key[80]. Basic per-peer mode leaves
+        # flags/prefixlen/ifindex zero; keylen/ifindex are native byte order.
+        addr = peer_sockaddr.b.ljust(128, "\x00".b)
+        meta = [0, 0, key.bytesize, 0].pack('CCSL')
+        keybuf = key.ljust(TCP_MD5SIG_MAXKEYLEN, "\x00".b)
+        sock.setsockopt(::Socket::IPPROTO_TCP, TCP_MD5SIG, addr + meta + keybuf)
+      rescue ConnectionError
+        close_socket(sock)
+        raise
+      rescue SystemCallError => e
+        close_socket(sock)
+        raise ConnectionError, "failed to set TCP MD5 signature (RFC2385): #{e.class}: #{e.message}"
+      rescue StandardError => e
+        # Any other failure (e.g. a non-String tcp_md5_pass that doesn't respond
+        # to #b) still closes the socket and normalises to ConnectionError.
+        close_socket(sock)
+        raise ConnectionError, "invalid tcp_md5_pass: #{e.class}: #{e.message}"
+      end
+
+      def close_socket(sock)
+        sock&.close
+      rescue StandardError
+        nil
+      end
+
       def try_connect_nonblock(sock, sockaddr, deadline)
         sock.connect_nonblock(sockaddr)
         true # connected

data/lib/jrpc/transport/test.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+# An in-process transport double for testing code that uses JRPC, without a real
+# TCP server. NOT required by default — require it explicitly from your test setup:
+#
+#   require 'jrpc/transport/test'
+#
+# Then inject it via the `transport:` option of either client:
+#
+#   transport = JRPC::Transport::Test.new
+#   transport.on('sum') { |params| params['a'] + params['b'] }
+#   client = JRPC::SimpleClient.new('test', transport: transport)
+#   client.request('sum', { 'a' => 1, 'b' => 2 }) # => 3
+#   transport.last_request # => { 'jsonrpc' => '2.0', 'method' => 'sum', ... }
+#
+# Two scripting mechanisms, both feeding a single FIFO inbound queue:
+#
+#   * Handlers (`on`): the primary, high-level API. When the client writes a
+#     request, the matching handler runs and its return value is encoded as a
+#     JSON-RPC result response echoing the request id. A handler may instead raise:
+#       - a JRPC::Errors::ServerError (or subclass) -> encoded as an error response
+#         (its #code, or -32000 if nil/absent);
+#       - a transport error (ConnectionError / Timeout / MalformedFrame) -> raised
+#         when the client reads the response, simulating a socket-level failure.
+#   * Raw frames (`push_response` / `push_raise`): the low-level escape hatch for
+#     testing malformed responses, id mismatches, and orphan/unsolicited frames,
+#     where you control the literal bytes the client reads.
+#
+# In `strict` mode (the default) a request whose method has no handler raises
+# UnexpectedRequest at write time, so a missing stub fails loudly instead of
+# hanging. Set `strict: false` to drive reads purely via push_response/push_raise.
+require 'jrpc'
+require 'socket'
+require 'monitor'
+require 'json'
+
+module JRPC
+  module Transport
+    class Test < Base
+      # Resolve `raise ConnectionError`-style names to the transport hierarchy the
+      # clients rescue, mirroring Tcp (otherwise constant lookup finds JRPC::* v1).
+      ConnectionError = Base::ConnectionError
+      Timeout = Base::Timeout
+      MalformedFrame = Base::MalformedFrame
+
+      # Raised at write time when a request arrives for a method with no registered
+      # handler and strict mode is on. A test-harness assertion, not a transport
+      # condition, so it is deliberately outside the Base::Error hierarchy: it
+      # propagates raw to your test (via SimpleClient) instead of being swallowed
+      # and remapped to a generic ConnectionError.
+      class UnexpectedRequest < StandardError; end
+
+      # GC backstop: release the socketpair FDs if a transport is dropped without an
+      # explicit #shutdown. Returns a proc that captures only the two IOs, never self.
+      def self.finalizer(io, signal)
+        proc do
+          [io, signal].each do |sock|
+            sock.close
+          rescue StandardError
+            nil
+          end
+        end
+      end
+
+      def initialize(server = 'test', **options)
+        super
+        @strict = options.fetch(:strict, true)
+        @mon = Monitor.new
+        @handlers = {}
+        @inbound = []       # FIFO of [:frame, String] | [:raise, Exception]
+        @sent = []          # raw payload strings exactly as the client wrote them
+        @requests = []      # parsed request envelopes (Hash) in write order
+        @notifications = [] # parsed notification envelopes (Hash) in write order
+        @open = false
+        @io = nil
+        @signal = nil
+        @fail_connect = nil
+      end
+
+      # --- Scripting API (called from your test thread) ---------------------------
+
+      # Register a handler for +method+. The block receives the request params
+      # (Array, Hash, or nil) and its return value becomes the JSON-RPC result.
+      def on(method, &block)
+        raise ArgumentError, 'on requires a block' unless block
+
+        @mon.synchronize { @handlers[method.to_s] = block }
+        self
+      end
+
+      # Enqueue a literal inbound frame. Accepts a JSON String (used verbatim, so it
+      # may be intentionally malformed) or a Hash (serialized with JSON.generate).
+      def push_response(frame)
+        payload = frame.is_a?(String) ? frame : JSON.generate(frame)
+        enqueue([:frame, payload])
+        self
+      end
+
+      # Enqueue an error to be raised on the client's next read, simulating a
+      # socket-level failure mid-stream. Pass a transport error for realistic
+      # behavior (e.g. JRPC::Transport::Base::ConnectionError.new('reset')).
+      def push_raise(error)
+        enqueue([:raise, error])
+        self
+      end
+
+      # Arm #connect to raise +error+ on every attempt until cleared by #reset.
+      # Defaults to a ConnectionError so SharedClient's loop treats it as a normal
+      # connect failure (drained), rather than a crash.
+      def fail_connect(error = ConnectionError.new('connect failed'))
+        @mon.synchronize { @fail_connect = error }
+        self
+      end
+
+      # Clear recordings, the inbound queue, and any armed connect failure. Keeps
+      # registered handlers so a transport can be reused across examples.
+      def reset
+        @mon.synchronize do
+          @inbound.clear
+          @sent.clear
+          @requests.clear
+          @notifications.clear
+          @fail_connect = nil
+          drain_signal
+        end
+        self
+      end
+
+      def sent          = @mon.synchronize { @sent.dup }
+      def requests      = @mon.synchronize { @requests.dup }
+      def notifications = @mon.synchronize { @notifications.dup }
+      def last_request  = @mon.synchronize { @requests.last }
+
+      # Close the socketpair FDs. Idempotent. Call from an after-hook for
+      # deterministic FD cleanup; otherwise the GC finalizer reclaims them.
+      def shutdown
+        @mon.synchronize do
+          @open = false
+          [@io, @signal].each do |sock|
+            sock&.close
+          rescue StandardError
+            nil
+          end
+          @io = nil
+          @signal = nil
+        end
+      end
+
+      # --- Transport interface (called from the client / SharedClient loop) -------
+
+      def connect
+        @mon.synchronize do
+          raise @fail_connect if @fail_connect
+
+          open_socketpair if @io.nil?
+          @open = true
+        end
+      end
+
+      # closed? tracks the logical open flag, not the FD: #close keeps the socketpair
+      # alive (so a concurrent IO.select in SharedClient's loop is never yanked) and
+      # only flips the flag, mirroring the proven spec helper.
+      def closed?
+        @mon.synchronize { !@open }
+      end
+
+      def socket
+        @mon.synchronize { @open ? @io : nil }
+      end
+
+      def write_frame(bytes, **)
+        @mon.synchronize do
+          raise ConnectionError, 'transport closed' if closed_unlocked?
+
+          @sent << bytes
+          envelope = JSON.parse(bytes)
+          if envelope.key?('id')
+            handle_request(envelope)
+          else
+            handle_notification(envelope)
+          end
+        end
+      end
+
+      def read_frame(**)
+        @mon.synchronize do
+          raise ConnectionError, 'transport closed' if closed_unlocked?
+
+          entry = pop_inbound
+          raise Timeout, 'read_frame: no scripted response available' if entry.nil?
+
+          deliver(entry)
+        end
+      end
+
+      def try_read_frame
+        @mon.synchronize do
+          raise ConnectionError, 'transport closed' if closed_unlocked?
+
+          entry = pop_inbound
+          if entry.nil?
+            drain_signal
+            return :wait
+          end
+
+          deliver(entry)
+        end
+      end
+
+      def close
+        @mon.synchronize do
+          @open = false
+          @inbound.clear
+          # Wake a loop blocked in IO.select so it re-checks closed? promptly.
+          signal_readable
+          true
+        end
+      end
+
+      private
+
+      def closed_unlocked?
+        !@open
+      end
+
+      def open_socketpair
+        # A bidirectional UNIX socketpair: @io (returned by #socket) stays writable
+        # while its send buffer has room, and becomes readable when we write a wake
+        # byte to @signal. SharedClient's loop selects on it for both directions;
+        # IO.pipe would not work (its read end is never writable, so the loop would
+        # never flush). Linux/macOS only.
+        @io, @signal = ::Socket.socketpair(:UNIX, :STREAM, 0)
+        # Drop any prior finalizer (from an earlier connect/shutdown cycle) before
+        # registering the new one, so they don't accumulate on a reused instance.
+        ObjectSpace.undefine_finalizer(self)
+        ObjectSpace.define_finalizer(self, self.class.finalizer(@io, @signal))
+      end
+
+      def handle_request(envelope)
+        @requests << envelope
+        method = envelope['method']
+        handler = @handlers[method]
+        if handler
+          run_request_handler(envelope['id'], envelope['params'], handler)
+        elsif @strict
+          raise UnexpectedRequest,
+                "JRPC::Transport::Test: no handler for request #{method.inspect}; " \
+                "register one with `transport.on(#{method.inspect}) { ... }`, " \
+                'queue a frame with push_response, or set strict: false'
+        end
+        # non-strict + no handler: reads are driven entirely by push_response/push_raise.
+      end
+
+      def run_request_handler(id, params, handler)
+        result = handler.call(params)
+        enqueue([:frame, result_response(id, result)])
+      rescue Errors::ServerError => e
+        enqueue([:frame, error_response(id, e)])
+      rescue Base::Error => e
+        # Transport-level failure (ConnectionError/Timeout/MalformedFrame): surface it
+        # when the client reads the response, simulating a mid-stream socket error.
+        enqueue([:raise, e])
+      end
+
+      def handle_notification(envelope)
+        @notifications << envelope
+        handler = @handlers[envelope['method']]
+        return unless handler
+
+        begin
+          handler.call(envelope['params'])
+        rescue Base::Error
+          # Simulate a send-time socket failure; surfaces through write_frame.
+          raise
+        rescue Errors::ServerError
+          # Notifications have no response channel, so a server error is meaningless.
+          nil
+        end
+      end
+
+      def result_response(id, result)
+        JSON.generate({ 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'id' => id, 'result' => result })
+      end
+
+      # `data` is emitted only when the raised error carries one, so a handler that
+      # ignores it produces the same frame as before.
+      def error_response(id, error)
+        code = error.respond_to?(:code) && error.code.is_a?(Integer) ? error.code : -32_000
+        data = error.respond_to?(:data) ? error.data : nil
+        err = { 'code' => code, 'message' => error.message }
+        err['data'] = data unless data.nil?
+        JSON.generate({ 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'id' => id, 'error' => err })
+      end
+
+      def enqueue(entry)
+        @mon.synchronize do
+          @inbound << entry
+          signal_readable
+        end
+      end
+
+      def pop_inbound
+        @inbound.shift
+      end
+
+      def deliver(entry)
+        type, value = entry
+        case type
+        when :raise then raise value
+        when :frame then value
+        end
+      end
+
+      # Make @io readable so a loop blocked in IO.select wakes. Best-effort: a full
+      # buffer just means the socket is already readable, so swallow any error.
+      def signal_readable
+        return if @signal.nil?
+
+        @signal.write_nonblock('.')
+      rescue StandardError
+        nil
+      end
+
+      # Drain accumulated wake bytes so @io stops selecting readable once the inbound
+      # queue is empty, preventing the loop from spinning.
+      def drain_signal
+        return if @io.nil?
+
+        loop { @io.read_nonblock(4096) }
+      rescue IO::WaitReadable, IOError
+        nil
+      end
+    end
+  end
+end

data/lib/jrpc/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JRPC
-  VERSION = '2.0.0'
+  VERSION = '2.2.0'
 end

data/lib/jrpc.rb

@@ -7,6 +7,7 @@ require 'jrpc/version'
 require 'jrpc/errors'
 require 'jrpc/id_generator'
 require 'jrpc/message'
+require 'jrpc/payload_logging'
 require 'jrpc/transport'
 require 'jrpc/simple_client'
 require 'jrpc/shared_client/ticket'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jrpc
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Denis Talakevich
@@ -64,6 +64,7 @@ files:
 - lib/jrpc/errors.rb
 - lib/jrpc/id_generator.rb
 - lib/jrpc/message.rb
+- lib/jrpc/payload_logging.rb
 - lib/jrpc/shared_client.rb
 - lib/jrpc/shared_client/outbound_queue.rb
 - lib/jrpc/shared_client/registry.rb
@@ -73,6 +74,7 @@ files:
 - lib/jrpc/transport.rb
 - lib/jrpc/transport/base.rb
 - lib/jrpc/transport/tcp.rb
+- lib/jrpc/transport/test.rb
 - lib/jrpc/version.rb
 homepage: https://github.com/didww/jrpc
 licenses: