jrpc 1.1.7 → 2.0.0

data/lib/jrpc/shared_client/transport_loop.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module JRPC
+  class SharedClient
+    class TransportLoop
+      SELECT_FLOOR = 60.0
+
+      def initialize(
+        transport:, registry:, outbound_queue:, wake_pipe_reader:,
+        write_timeout:, reap_timeout:, logger:,
+        shutdown_check:,
+        clock: nil
+      )
+        @transport = transport
+        @registry = registry
+        @outbound_queue = outbound_queue
+        @wake_pipe_reader = wake_pipe_reader
+        @write_timeout = write_timeout
+        @reap_timeout = reap_timeout
+        @logger = logger
+        @shutdown_check = shutdown_check
+        @clock = clock || method(:default_clock)
+        @last_rx_at = nil
+      end
+
+      # Runs the transport loop. Calls on_crash.(err) on unexpected exception, then returns.
+      def run(&)
+        main_loop
+      rescue StandardError => e
+        log_error("transport thread crashed: #{e.class}: #{e.message}\n#{e.backtrace.join("\n")}")
+        err = Errors::ConnectionError.new("transport thread crashed: #{e.class}: #{e.message}")
+        yield(err)
+      end
+
+      private
+
+      def clock_now
+        @clock.call
+      end
+
+      def default_clock
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      def shutting_down?
+        @shutdown_check.call
+      end
+
+      def main_loop
+        loop do
+          break if shutting_down? && @outbound_queue.empty? && @registry.empty?
+
+          ensure_connected
+
+          ios_read = [@wake_pipe_reader]
+          ios_read << @transport.socket unless @transport.closed?
+          ios_write = []
+          ios_write << @transport.socket if !@transport.closed? && !@outbound_queue.empty?
+
+          timeout = compute_select_timeout
+          readable, writable, = IO.select(ios_read, ios_write, [], timeout)
+
+          drain_wake_pipe if readable&.include?(@wake_pipe_reader)
+          flush_one_outbound if writable&.include?(@transport.socket)
+          consume_inbound if readable&.include?(@transport.socket)
+
+          expire_due_tickets
+          sweep_dead_threads
+          reap_if_idle
+        end
+      end
+
+      def ensure_connected
+        return unless @transport.closed?
+        return if @outbound_queue.empty? && @registry.empty?
+
+        begin
+          @transport.connect
+          @last_rx_at = clock_now
+        rescue Transport::Base::ConnectionError, Transport::Base::Timeout => e
+          drain_connection_error("connect failed: #{e.message}")
+        end
+      end
+
+      def compute_select_timeout
+        now = clock_now
+        candidates = [SELECT_FLOOR]
+
+        registry_min = nil
+        @registry.each_ticket { |t| registry_min = [registry_min || t.expires_at, t.expires_at].min if t.expires_at }
+        queue_min = @outbound_queue.earliest_deadline
+
+        [registry_min, queue_min].each do |deadline|
+          candidates << [deadline - now, 0].max if deadline
+        end
+
+        if @reap_timeout && !@transport.closed? && @outbound_queue.empty? && @registry.empty? && @last_rx_at
+          reap_remaining = (@last_rx_at + @reap_timeout) - now
+          candidates << [reap_remaining, 0].max
+        end
+
+        candidates.min
+      end
+
+      def drain_wake_pipe
+        loop do
+          @wake_pipe_reader.read_nonblock(1024)
+        end
+      rescue IO::WaitReadable
+        # drained
+      end
+
+      def flush_one_outbound
+        ticket = @outbound_queue.pop_nonblock
+        return unless ticket
+
+        return if ticket.cancelled?
+
+        now = clock_now
+        if ticket.expired?(now)
+          @registry.delete(ticket) if ticket.id
+          if ticket.thread.nil?
+            log_error('fire_and_forget notification expired before send')
+          elsif ticket.alive?
+            ticket.reject(Errors::Timeout.new('ttl expired before send'))
+          else
+            log_error("ticket expired before send; owner gone: #{ticket.id.inspect}")
+          end
+          return
+        end
+
+        begin
+          @transport.write_frame(ticket.payload, timeout: @write_timeout)
+        rescue Transport::Base::Timeout => e
+          err = Errors::Timeout.new("write timeout: #{e.message}")
+          signal_or_log(ticket, err)
+          drain_connection_error('write timeout; partial frame may have been sent')
+          return
+        rescue Transport::Base::ConnectionError, Transport::Base::Error => e
+          err = Errors::ConnectionError.new(e.message)
+          signal_or_log(ticket, err)
+          drain_connection_error(e.message)
+          return
+        end
+
+        # Fire-and-forget notification: nothing more to do.
+        return if ticket.thread.nil?
+
+        # Blocking notification (no id): the caller only waits for the send.
+        # Request (has id): leave it registered; the response will resolve it.
+        ticket.fulfill(nil) if ticket.id.nil?
+      end
+
+      def read_next_frame
+        @transport.try_read_frame
+      rescue Transport::Base::MalformedFrame => e
+        log_error("framing error: #{e.message}")
+        drain_connection_error('framing corruption; stream resynchronized')
+        nil
+      rescue Transport::Base::ConnectionError, Transport::Base::Error => e
+        drain_connection_error(e.message)
+        nil
+      end
+
+      def consume_inbound
+        loop do
+          frame = read_next_frame
+          return unless frame
+
+          break if frame == :wait
+
+          @last_rx_at = clock_now
+
+          begin
+            parsed = Message.parse(frame)
+          rescue Errors::MalformedResponseError => e
+            log_error("JSON parse error on inbound frame: #{e.message}")
+            drain_connection_error('framing corruption; stream resynchronized')
+            return
+          end
+
+          id = parsed['id']
+          if id.nil?
+            log_error('server-initiated message received (no id), dropping')
+            next
+          end
+
+          ticket = @registry.fetch_and_delete(id)
+          if ticket.nil?
+            log_error("orphan response: id=#{id.inspect}")
+            next
+          end
+
+          if ticket.cancelled? || !ticket.alive?
+            log_error("orphan response: ticket #{id.inspect} cancelled or owner dead")
+            next
+          end
+
+          begin
+            Message.validate_response!(parsed, id)
+          rescue Errors::MalformedResponseError => e
+            ticket.reject(e)
+            next
+          end
+
+          if parsed.key?('error')
+            ticket.reject(Message.error_to_exception(parsed['error']))
+          else
+            ticket.fulfill(parsed['result'])
+          end
+        end
+      end
+
+      def expire_due_tickets
+        now = clock_now
+        expired_ids = []
+        @registry.each_ticket { |t| expired_ids << t.id if t.expired?(now) }
+        expired_ids.each do |id|
+          ticket = @registry.fetch_and_delete(id)
+          next unless ticket
+
+          if ticket.alive?
+            ticket.reject(Errors::Timeout.new('ttl expired'))
+          else
+            log_error("expired ticket #{id.inspect} owner thread dead; dropping")
+          end
+        end
+
+        @outbound_queue.each_snapshot do |ticket|
+          next unless ticket.expired?(now)
+
+          @outbound_queue.delete(ticket)
+          if ticket.thread.nil?
+            log_error('fire_and_forget notification expired in queue')
+          elsif ticket.alive?
+            ticket.reject(Errors::Timeout.new('ttl expired'))
+          else
+            log_error("expired queued ticket #{ticket.id.inspect} owner thread dead; dropping")
+          end
+        end
+      end
+
+      def sweep_dead_threads
+        dead = []
+        @registry.each_ticket { |t| dead << t unless t.alive? }
+        dead.each do |ticket|
+          @registry.delete(ticket)
+          log_error("owner thread dead; dropping in-flight ticket #{ticket.id.inspect}")
+        end
+      end
+
+      def reap_if_idle
+        return unless @reap_timeout
+        return if @transport.closed?
+        return unless @outbound_queue.empty? && @registry.empty?
+        return unless @last_rx_at && (clock_now - @last_rx_at) >= @reap_timeout
+
+        @transport.close
+        @last_rx_at = nil
+      end
+
+      def drain_connection_error(message)
+        begin
+          @transport.close
+        rescue StandardError
+          nil
+        end
+        err = Errors::ConnectionError.new(message)
+        @registry.drain_all_with(err)
+        @outbound_queue.each_snapshot do |ticket|
+          @outbound_queue.delete(ticket)
+          signal_or_log(ticket, err)
+        end
+        @last_rx_at = nil
+      end
+
+      def signal_or_log(ticket, err)
+        if ticket.thread
+          ticket.reject(err)
+        else
+          log_error("fire_and_forget send failed: #{err.message}")
+        end
+      end
+
+      def log_error(msg)
+        @logger&.error("[JRPC::SharedClient] #{msg}")
+      end
+    end
+  end
+end

data/lib/jrpc/shared_client.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module JRPC
+  class SharedClient
+    attr_reader :server
+
+    def initialize(server, **options)
+      @server = server
+      @write_timeout = options.fetch(:write_timeout, 5)
+      @default_ttl = options.fetch(:default_ttl, 30)
+      @reap_timeout = options.fetch(:reap_timeout, nil)
+      @max_queue_size = options.fetch(:max_queue_size, 10_000)
+      @logger = options.fetch(:logger, nil)
+      # Single monotonic clock source shared with the transport loop. The
+      # :clock option is an internal test seam (deterministic TTL specs);
+      # callers should not need it.
+      @clock = options.fetch(:clock, nil) || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+
+      if @write_timeout && @default_ttl && @write_timeout >= @default_ttl
+        raise ArgumentError, "write_timeout (#{@write_timeout}) must be < default_ttl (#{@default_ttl})"
+      end
+
+      @transport = options.fetch(:transport) do
+        Transport.build(server, **options)
+      end
+
+      @id_gen = options.fetch(:id_gen) do
+        IdGenerator.new(prefix: options.fetch(:id_prefix, nil), thread_safe: true)
+      end
+
+      @registry = SharedClient::Registry.new
+      @outbound_queue = SharedClient::OutboundQueue.new(capacity: @max_queue_size)
+      @wake_pipe_reader, @wake_pipe_writer = IO.pipe
+
+      @lifecycle_mutex = Mutex.new
+      # :running -> :closing -> :closed   (user-initiated close)
+      # :running -> :dead                 (transport thread crashed)
+      @status = :running
+
+      shutdown_check = -> { @lifecycle_mutex.synchronize { @status == :closing } }
+
+      @transport_loop = SharedClient::TransportLoop.new(
+        transport: @transport,
+        registry: @registry,
+        outbound_queue: @outbound_queue,
+        wake_pipe_reader: @wake_pipe_reader,
+        write_timeout: @write_timeout,
+        reap_timeout: @reap_timeout,
+        logger: @logger,
+        shutdown_check: shutdown_check,
+        clock: @clock
+      )
+
+      @transport_thread = Thread.new do
+        @transport_loop.run do |err|
+          @lifecycle_mutex.synchronize { @status = :dead }
+          drain_all(err)
+        end
+      end
+      @transport_thread.abort_on_exception = false
+    end
+
+    def request(method, params = nil, ttl: @default_ttl)
+      id = @id_gen.next
+      ticket = Ticket.new(
+        id: id,
+        payload: Message.dump(Message.build_request(method, params, id)),
+        thread: Thread.current,
+        expires_at: ttl ? clock_now + ttl : nil
+      )
+
+      enqueue!(ticket)
+      await(ticket, ttl)
+    end
+
+    def notification(method, params = nil, ttl: @default_ttl, fire_and_forget: false)
+      ticket = Ticket.new(
+        id: nil,
+        payload: Message.dump(Message.build_notification(method, params)),
+        thread: fire_and_forget ? nil : Thread.current,
+        expires_at: ttl ? clock_now + ttl : nil
+      )
+
+      enqueue!(ticket)
+      return nil if fire_and_forget
+
+      await(ticket, ttl)
+      nil
+    end
+
+    def close(timeout: 5)
+      @lifecycle_mutex.synchronize do
+        return true if @status == :closed
+
+        @status = :closing
+      end
+
+      wake_transport
+
+      joined = @transport_thread.join(timeout)
+
+      unless joined
+        begin
+          @transport.close
+        rescue StandardError
+          nil
+        end
+        @transport_thread.join(1.0)
+        @transport_thread.kill if @transport_thread.alive?
+        @transport_thread.join
+        # Forced kill: the loop never reached its graceful drain, so fail
+        # whatever was still in flight. (A graceful exit drained itself; a
+        # crash drained via on_crash. reject is idempotent in every case.)
+        drain_all(Errors::ConnectionError.new('client force-closed'))
+      end
+
+      # Safe now that the transport thread is guaranteed dead.
+      begin
+        @wake_pipe_writer.close
+      rescue StandardError
+        nil
+      end
+      begin
+        @wake_pipe_reader.close
+      rescue StandardError
+        nil
+      end
+
+      @lifecycle_mutex.synchronize { @status = :closed }
+      !joined.nil?
+    end
+
+    def closed?
+      @lifecycle_mutex.synchronize { @status == :closed }
+    end
+
+    WAIT_GRACE = 1.0 # caller-side backstop beyond the loop-enforced ttl
+
+    private
+
+    def clock_now
+      @clock.call
+    end
+
+    def enqueue!(ticket)
+      @lifecycle_mutex.synchronize do
+        case @status
+        when :closing, :closed
+          raise Errors::ClientError, 'client closed'
+        when :dead
+          raise Errors::ClientError, 'client unusable: transport thread exited'
+        end
+        @outbound_queue.push_nonblock(ticket)
+        @registry.register(ticket) if ticket.id
+      end
+      wake_transport
+    end
+
+    # Caller side. Blocks thread- and fiber-cooperatively until the loop
+    # resolves the ticket, with a real-time backstop in case the loop dies.
+    def await(ticket, ttl)
+      ticket.wait(ttl ? ttl + WAIT_GRACE : nil)
+
+      if ticket.fulfilled?
+        ticket.result
+      elsif ticket.rejected?
+        raise ticket.error
+      else
+        raise Errors::Timeout, "request timed out after #{ttl}s"
+      end
+    ensure
+      unless ticket.resolved?
+        ticket.cancel
+        @registry.delete(ticket)
+        @outbound_queue.delete(ticket)
+      end
+    end
+
+    def drain_all(err)
+      @registry.drain_all_with(err)
+      @outbound_queue.close_and_drain.each do |ticket|
+        next if ticket.thread.nil?
+
+        ticket.reject(err)
+      end
+    end
+
+    def wake_transport
+      @wake_pipe_writer.write_nonblock('.')
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/jrpc/simple_client.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module JRPC
+  # NOT thread-safe: a SimpleClient instance must not be shared across threads or
+  # fibers. It owns a single transport/socket plus an unsynchronized id counter, so
+  # 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
+    attr_reader :server
+
+    def initialize(server, **options)
+      @closed = false
+      @server = server
+      @read_timeout = options.fetch(:read_timeout, 60)
+      @write_timeout = options.fetch(:write_timeout, 60)
+      @autoclose = options.fetch(:autoclose, false)
+      @logger = options[:logger]
+      @transport = options.fetch(:transport) do
+        Transport.build(server, **options)
+      end
+      @id_gen = options.fetch(:id_gen) do
+        IdGenerator.new(prefix: options[:id_prefix], thread_safe: false)
+      end
+    end
+
+    def request(method, params = nil, read_timeout: @read_timeout, write_timeout: @write_timeout)
+      raise Errors::ClientError, 'client closed' if @closed
+
+      id = @id_gen.next
+      json = Message.dump(Message.build_request(method, params, id))
+
+      with_transport_error_handling do
+        connect_if_needed!
+        @transport.write_frame(json, timeout: write_timeout)
+        raw = @transport.read_frame(timeout: read_timeout)
+        response = Message.parse(raw)
+        Message.validate_response!(response, id)
+        raise Message.error_to_exception(response['error']) if response.key?('error')
+
+        response['result']
+      end
+    end
+
+    def notification(method, params = nil, write_timeout: @write_timeout)
+      raise Errors::ClientError, 'client closed' if @closed
+
+      json = Message.dump(Message.build_notification(method, params))
+
+      with_transport_error_handling do
+        connect_if_needed!
+        @transport.write_frame(json, timeout: write_timeout)
+        nil
+      end
+    end
+
+    def close
+      return true if @closed
+
+      @transport.close
+      @closed = true
+      true
+    end
+
+    def closed?
+      @closed
+    end
+
+    private
+
+    def connect_if_needed!
+      @transport.connect if @transport.closed?
+    end
+
+    # Translate transport-level errors into the client's public Errors:: hierarchy and
+    # apply the autoclose policy. Shared by request and notification so the mapping and
+    # the close-after-each-call rule live in exactly one place.
+    def with_transport_error_handling
+      yield
+    rescue Transport::Base::Timeout => e
+      raise Errors::Timeout, e.message
+    rescue Transport::Base::ConnectionError => e
+      raise Errors::ConnectionError, e.message
+    rescue Transport::Base::MalformedFrame => e
+      raise Errors::MalformedResponseError, e.message
+    ensure
+      @transport.close if @autoclose
+    end
+  end
+end

data/lib/jrpc/transport/base.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module JRPC
+  module Transport
+    class Base
+      class Error < StandardError; end
+
+      class ConnectionError < Error; end
+
+      class Timeout < Error; end
+
+      class MalformedFrame < Error; end
+
+      def initialize(server, **options)
+        @server = server
+        # connect_timeout: total wall-clock budget for the whole connect (across retries).
+        # connect_attempt_timeout: cap on a single connect attempt; nil means a single
+        # attempt is bounded only by whatever is left of connect_timeout.
+        @connect_timeout = options.fetch(:connect_timeout, 60)
+        @connect_attempt_timeout = options.fetch(:connect_attempt_timeout, nil)
+        @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)
+      end
+
+      # Abstract interface. Subclasses must implement every method below; the bodies
+      # only exist to fail loudly if one is forgotten, so they carry no logic worth
+      # covering and are excluded from coverage via :nocov:.
+      # :nocov:
+      def connect
+        raise NotImplementedError
+      end
+
+      def write_frame(bytes, timeout:)
+        raise NotImplementedError
+      end
+
+      def read_frame(timeout:)
+        raise NotImplementedError
+      end
+
+      def try_read_frame
+        raise NotImplementedError
+      end
+
+      def close
+        raise NotImplementedError
+      end
+
+      def closed?
+        raise NotImplementedError
+      end
+
+      def socket
+        raise NotImplementedError
+      end
+      # :nocov:
+    end
+  end
+end