jrpc 1.1.8 → 2.1.0

data/lib/jrpc/transport/tcp.rb

@@ -0,0 +1,292 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+module JRPC
+  module Transport
+    class Tcp < Base
+      # Pull error classes into this scope so `raise ConnectionError` resolves correctly.
+      # Without this, Ruby's constant lookup would find JRPC::ConnectionError (v1) instead.
+      ConnectionError = Base::ConnectionError
+      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
+        @read_buffer = ''.b
+      end
+
+      def connect
+        deadline = @connect_timeout ? monotonic_now + @connect_timeout : nil
+        attempts_remaining = @connect_retry_count + 1
+        begin
+          connect_once(deadline)
+        rescue ConnectionError, Timeout
+          attempts_remaining -= 1
+          raise if attempts_remaining <= 0
+          raise if deadline && remaining_time(deadline) <= 0 # total budget spent
+
+          sleep @connect_retry_interval
+          retry
+        end
+      end
+
+      def write_frame(bytes, timeout:)
+        raise ConnectionError, 'transport closed' if @socket.nil?
+
+        frame = "#{bytes.bytesize}:#{bytes},"
+        written = 0
+        deadline = timeout ? monotonic_now + timeout : nil
+
+        while written < frame.bytesize
+          remaining = remaining_time(deadline)
+          close_and_raise_timeout!('write') if remaining && remaining <= 0
+
+          writable = @socket.wait_writable(remaining)
+          close_and_raise_timeout!('write') unless writable
+
+          begin
+            n = @socket.write_nonblock(frame.byteslice(written..))
+            written += n
+          rescue IO::WaitWritable
+            # socket not ready yet; loop back to IO.select. Rescue the module (not the
+            # concrete IO::EAGAINWaitWritable) so IO::EWOULDBLOCKWaitWritable is also
+            # caught on platforms where EAGAIN != EWOULDBLOCK (macOS/BSD).
+          rescue Errno::EPIPE, Errno::ECONNRESET, IOError => e
+            close
+            raise ConnectionError, "write failed: #{e.class}: #{e.message}"
+          end
+        end
+      end
+
+      def read_frame(timeout:)
+        raise ConnectionError, 'transport closed' if @socket.nil?
+
+        deadline = timeout ? monotonic_now + timeout : nil
+
+        loop do
+          result = try_parse_frame
+          return result unless result == :wait
+
+          remaining = remaining_time(deadline)
+          close_and_raise_timeout!('read') if remaining && remaining <= 0
+
+          readable = @socket.wait_readable(remaining)
+          close_and_raise_timeout!('read') unless readable
+
+          fill_buffer
+        end
+      end
+
+      def try_read_frame
+        raise ConnectionError, 'transport closed' if @socket.nil?
+
+        # Parse first so already-buffered frames survive an EOF on the next read.
+        result = try_parse_frame
+        return result unless result == :wait
+
+        # fill_buffer swallows EAGAIN (no data yet); the re-parse then returns :wait.
+        fill_buffer
+        try_parse_frame
+      end
+
+      def close
+        begin
+          @socket&.close
+        rescue StandardError
+          nil
+        end
+        @socket = nil
+        @read_buffer = ''.b
+      end
+
+      def closed?
+        @socket.nil? || @socket.closed?
+      end
+
+      attr_reader :socket
+
+      private
+
+      # Attempt a single TCP connect.  All errors are normalised to ConnectionError or Timeout.
+      def connect_once(deadline)
+        # Close any existing socket first so connecting on an already-connected
+        # transport replaces it cleanly instead of orphaning the old file descriptor.
+        begin
+          @socket&.close
+        rescue StandardError
+          nil
+        end
+        @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)
+        end
+
+        @socket = sock
+        @read_buffer = ''.b
+      end
+
+      def fill_buffer
+        chunk = @socket.read_nonblock(65_536)
+        @read_buffer << chunk.b
+      rescue IO::WaitReadable
+        # no data right now; caller already confirmed readable via IO.select
+      rescue Errno::ECONNRESET, Errno::EPIPE, IOError => e
+        close
+        raise ConnectionError, "read failed: #{e.class}: #{e.message}"
+      end
+
+      def build_socket
+        host, port_str = @server.split(':', 2)
+        addr_info = ::Socket.getaddrinfo(host, nil, nil, ::Socket::SOCK_STREAM)
+        family = ::Socket.const_get(addr_info[0][0])
+        sockaddr = ::Socket.pack_sockaddr_in(port_str.to_i, addr_info[0][3])
+        sock = ::Socket.new(family, ::Socket::SOCK_STREAM, 0)
+        [sock, sockaddr]
+      rescue StandardError => e
+        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
+      rescue Errno::EISCONN
+        true # already connected
+      rescue IO::WaitWritable
+        writable = sock.wait_writable(connect_wait_timeout(deadline))
+        unless writable
+          begin
+            sock.close
+          rescue StandardError
+            nil
+          end
+          raise Timeout, "connect timed out to #{@server}"
+        end
+        false
+        # loop again → next connect_nonblock call will return EISCONN or error
+      rescue StandardError => e
+        begin
+          sock.close
+        rescue StandardError
+          nil
+        end
+        raise ConnectionError, "#{e.class}: #{e.message}"
+      end
+
+      # Wait passed to a single IO.select while connecting: the smaller of the per-attempt
+      # cap and the time left in the overall connect deadline. nil (block forever) only when
+      # neither bound is set.
+      def connect_wait_timeout(deadline)
+        bounds = [@connect_attempt_timeout, remaining_time(deadline)].compact
+        return nil if bounds.empty?
+
+        wait = bounds.min
+        wait.negative? ? 0 : wait
+      end
+
+      def try_parse_frame
+        return :wait if @read_buffer.empty?
+
+        colon_idx = @read_buffer.index(':'.b)
+
+        if colon_idx.nil?
+          unless @read_buffer.match?(/\A\d+\z/)
+            raise MalformedFrame, "non-digit in length prefix: #{@read_buffer.byteslice(0, 32).inspect}"
+          end
+
+          return :wait
+        end
+
+        raise MalformedFrame, 'empty length prefix' if colon_idx.zero?
+
+        length_str = @read_buffer.byteslice(0, colon_idx)
+        raise MalformedFrame, "non-digit in length prefix: #{length_str.inspect}" unless length_str.match?(/\A\d+\z/)
+        if length_str.bytesize > 1 && length_str.getbyte(0) == 48 # ord('0'): leading zero
+          raise MalformedFrame, "leading zero in length prefix: #{length_str.inspect}"
+        end
+
+        length = Integer(length_str, 10)
+        frame_end = colon_idx + 1 + length # index of the expected comma
+
+        return :wait if @read_buffer.bytesize <= frame_end
+
+        unless @read_buffer.getbyte(frame_end) == 44 # ord(',')
+          raise MalformedFrame, "missing comma terminator at position #{frame_end}"
+        end
+
+        data = @read_buffer.byteslice(colon_idx + 1, length).force_encoding(Encoding::UTF_8)
+        # The line-194 guard guarantees bytesize > frame_end, so this byteslice is never nil.
+        @read_buffer = @read_buffer.byteslice((frame_end + 1)..)
+        data
+      end
+
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def remaining_time(deadline)
+        return nil unless deadline
+
+        deadline - monotonic_now
+      end
+
+      def close_and_raise_timeout!(operation)
+        close
+        raise Timeout, "#{operation} timed out on #{@server}"
+      end
+    end
+  end
+end

data/lib/jrpc/transport/test.rb

@@ -0,0 +1,333 @@
+# 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
+
+      def error_response(id, error)
+        code = error.respond_to?(:code) && error.code.is_a?(Integer) ? error.code : -32_000
+        JSON.generate(
+          { 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'id' => id,
+            'error' => { 'code' => code, 'message' => error.message } }
+        )
+      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/transport.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'jrpc/transport/base'
+require 'jrpc/transport/tcp'
+
+module JRPC
+  module Transport
+    def self.build(server, **)
+      JRPC::Transport::Tcp.new(server, **)
+    end
+  end
+end

data/lib/jrpc/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module JRPC
-  VERSION = '1.1.8'
+  VERSION = '2.1.0'
 end

data/lib/jrpc.rb

@@ -1,22 +1,20 @@
+# frozen_string_literal: true
+
 require 'socket'
 require 'json'
+require 'concurrent'
 require 'jrpc/version'
-require 'jrpc/error/error'
-require 'jrpc/utils'
-require 'jrpc/base_client'
-require 'jrpc/transport/socket_base'
-require 'jrpc/transport/socket_tcp'
-require 'jrpc/tcp_client'
-require 'jrpc/error/connection_error'
-require 'jrpc/error/client_error'
-require 'jrpc/error/server_error'
-require 'jrpc/error/internal_error'
-require 'jrpc/error/internal_server_error'
-require 'jrpc/error/invalid_params'
-require 'jrpc/error/invalid_request'
-require 'jrpc/error/method_not_found'
-require 'jrpc/error/parse_error'
-require 'jrpc/error/unknown_error'
+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'
+require 'jrpc/shared_client/registry'
+require 'jrpc/shared_client/outbound_queue'
+require 'jrpc/shared_client/transport_loop'
+require 'jrpc/shared_client'
 
 module JRPC
   JSON_RPC_VERSION = '2.0'