jrpc 1.1.8 → 2.1.0

data/bin/jrpc

@@ -1,19 +1,19 @@
 #!/usr/bin/env ruby
-# coding: utf-8
+# frozen_string_literal: true
 
 require 'optparse'
 require 'jrpc'
 
 Options = Struct.new(
-    :host,
-    :port,
-    :type,
-    :method,
-    :params,
-    :id,
-    :debug,
-    :namespace,
-    :timeout
+  :host,
+  :port,
+  :type,
+  :rpc_method,
+  :params,
+  :debug,
+  :connect_timeout,
+  :read_timeout,
+  :write_timeout
 )
 
 class Parser
@@ -22,7 +22,9 @@ class Parser
     args.host = '127.0.0.1'
     args.port = 7080
     args.type = 'request'
-    args.timeout = 5
+    args.connect_timeout = 5
+    args.read_timeout = 5
+    args.write_timeout = 60
 
     opt_parser = OptionParser.new do |opts|
       opts.banner = 'Usage: jrpc [options] method [params, ...]'
@@ -39,20 +41,20 @@ class Parser
         args.type = 'request'
       end
 
-      opts.on('-n', '--notification', 'Sets type to is notification (default false)') do
+      opts.on('-n', '--notification', 'Sets type to notification (default false)') do
         args.type = 'notification'
       end
 
-      opts.on('--namespace=NAMESPACE', 'Sets method namespace') do |namespace|
-        args.namespace = namespace
+      opts.on('--connect-timeout=TIMEOUT', Float, 'connect timeout in seconds (default 5)') do |t|
+        args.connect_timeout = t
       end
 
-      opts.on('--id=ID', 'Request ID (will be generated randomly by default)') do |id|
-        args.id = id
+      opts.on('--read-timeout=TIMEOUT', Float, 'read timeout in seconds (default 5)') do |t|
+        args.read_timeout = t
       end
 
-      opts.on('--timeout=TIMEOUT', 'timeout for socket') do |timeout|
-        args.timeout = timeout
+      opts.on('--write-timeout=TIMEOUT', Float, 'write timeout in seconds (default 60)') do |t|
+        args.write_timeout = t
       end
 
       opts.on('-d', '--debug', 'Debug output') do
@@ -71,10 +73,9 @@ class Parser
     end
 
     opt_parser.parse!(argv)
-    args.method = argv.first
-    args.params = argv[1..-1]
-    # puts "PARSED:\n#{args.inspect}\n#{argv.inspect}"
-    return args
+    args.rpc_method = argv.first
+    args.params = argv[1..]
+    args
   end
 end
 
@@ -84,16 +85,26 @@ logger = Logger.new($stdout)
 logger.level = options.debug ? Logger::DEBUG : Logger::INFO
 addr = "#{options.host}:#{options.port}"
 logger.debug { "Connecting to #{addr} ..." }
-client = JRPC::TcpClient.new(addr, namespace: options.namespace, timeout: options.timeout, logger: logger)
 
-logger.debug { "Sending #{options.type} #{options.method} #{options.params} ..." }
-response = client.perform_request(options.method, params: options.params, type: options.type.to_sym)
+client = JRPC::SimpleClient.new(
+  addr,
+  connect_timeout: options.connect_timeout,
+  read_timeout: options.read_timeout,
+  write_timeout: options.write_timeout,
+  logger: logger
+)
+
+params = options.params.empty? ? nil : options.params
+
+logger.debug { "Sending #{options.type} #{options.rpc_method} #{params} ..." }
 
 if options.type == 'request'
+  response = client.request(options.rpc_method, params)
   logger.debug { "Request was sent. Response: #{response.inspect}" }
   puts JSON.pretty_generate(response)
 else
-  logger.debug 'Notification was sent.'
+  client.notification(options.rpc_method, params)
+  logger.debug { 'Notification was sent.' }
 end
 
 client.close

data/bin/jrpc-shell

@@ -1,5 +1,5 @@
 #!/usr/bin/env ruby
-# coding: utf-8
+# frozen_string_literal: true
 
 require 'readline'
 require 'singleton'
@@ -20,18 +20,19 @@ class Command
   end
 
   attr_accessor :logger, :client, :help_usage
-  instance.logger = Logger.new(STDOUT)
+
+  instance.logger = Logger.new($stdout)
   instance.logger.level = Logger::INFO
   instance.help_usage = [
-      'Usage:',
-      '  connect host port',
-      '  disconnect',
-      '  request method param1 param2',
-      '  request method {"param1": 1. "param2": 2}',
-      '  notification method param1 param2',
-      '  notification method {"param1": 1. "param2": 2}',
-      '  help',
-      '  version'
+    'Usage:',
+    '  connect host port',
+    '  disconnect',
+    '  request method param1 param2',
+    '  request method {"param1": 1, "param2": 2}',
+    '  notification method param1 param2',
+    '  notification method {"param1": 1, "param2": 2}',
+    '  help',
+    '  version'
   ].join("\n")
 
   def cmd_help
@@ -44,9 +45,15 @@ class Command
 
   def cmd_connect(host, port)
     client&.close
-    self.client = JRPC::TcpClient.new("#{host}:#{port}", namespace: '', timeout: 5, logger: logger)
+    self.client = JRPC::SimpleClient.new(
+      "#{host}:#{port}",
+      connect_timeout: 5,
+      read_timeout: 5,
+      write_timeout: 60,
+      logger: logger
+    )
     'Connected.'
-  rescue JRPC::Error => e
+  rescue JRPC::Errors::Error => e
     "ERROR: JRPC #{e.message}\n#{help_usage}"
   end
 
@@ -61,37 +68,40 @@ class Command
   def cmd_request(method, *params)
     return "ERROR: Not connected\n#{help_usage}" if client.nil?
 
-    params = JSON.parse(params.first) if params.size == 1 && params[0] == '{'
+    params = JSON.parse(params.first) if params.size == 1 && params[0].start_with?('{')
+    params = nil if params.empty?
 
-    response = client.perform_request(method, params: params)
+    response = client.request(method, params)
     JSON.pretty_generate(response)
-  rescue JRPC::Error => e
+  rescue JRPC::Errors::Error => e
     "ERROR: JRPC #{e.message}\n#{help_usage}"
   end
 
   def cmd_notification(method, *params)
     return "ERROR: Not connected\n#{help_usage}" if client.nil?
 
-    params = JSON.parse(params.first) if params.size == 1 && params[0] == '{'
+    params = JSON.parse(params.first) if params.size == 1 && params[0].start_with?('{')
+    params = nil if params.empty?
 
-    response = client.perform_request(method, params: params, type: :notification)
-    JSON.pretty_generate(response)
-  rescue JRPC::Error => e
+    client.notification(method, params)
+    'Notification sent.'
+  rescue JRPC::Errors::Error => e
     "ERROR: JRPC #{e.message}\n#{help_usage}"
   end
 end
 
+EXIT_COMMANDS = %w[exit close quit].freeze
+
 puts 'Welcome to JRPC shell'
-while input = Readline.readline('> ', true)
-  if %w[exit close quit].include?(input)
+while (input = Readline.readline('> ', true))
+  if EXIT_COMMANDS.include?(input)
     break
   elsif input == 'hist'
     puts Readline::HISTORY.to_a
   elsif input == ''
-    # Remove blank lines from history
     Readline::HISTORY.pop
   else
-    command, *args = input.split(' ')
+    command, *args = input.split
     puts Command.call(command, args)
   end
 end

data/jrpc.gemspec

@@ -1,5 +1,6 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'jrpc/version'
 
@@ -16,14 +17,11 @@ Gem::Specification.new do |spec|
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 3.3'
 
-  spec.add_dependency 'netstring', '~> 0'
-  spec.add_dependency 'oj', '~> 3.0'
+  spec.add_dependency 'concurrent-ruby', '~> 1.2'
+  spec.add_dependency 'logger'
 
   spec.executables << 'jrpc'
   spec.executables << 'jrpc-shell'
-
-  spec.add_development_dependency 'bundler'
-  spec.add_development_dependency 'rake', '~> 13.0'
-  spec.add_development_dependency 'rspec', '~> 3.0'
 end

data/lib/jrpc/errors.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module JRPC
+  module Errors
+    class Error < RuntimeError; end
+
+    class ClientError < Error; end
+
+    class ConnectionError < Error
+    end
+
+    class Timeout < Error; end
+
+    class ServerError < Error
+      attr_reader :code
+
+      def initialize(message, code: nil)
+        @code = code
+        super(message)
+      end
+    end
+
+    class MalformedResponseError < ServerError
+      def initialize(message)
+        super(message, code: nil)
+      end
+    end
+
+    class ParseError < ServerError
+      def initialize(message)
+        super(message, code: -32_700)
+      end
+    end
+
+    class InvalidRequest < ServerError
+      def initialize(message)
+        super(message, code: -32_600)
+      end
+    end
+
+    class MethodNotFound < ServerError
+      def initialize(message)
+        super(message, code: -32_601)
+      end
+    end
+
+    class InvalidParams < ServerError
+      def initialize(message)
+        super(message, code: -32_602)
+      end
+    end
+
+    class InternalError < ServerError
+      def initialize(message)
+        super(message, code: -32_603)
+      end
+    end
+
+    class InternalServerError < ServerError
+    end
+
+    class UnknownError < ServerError
+    end
+  end
+end

data/lib/jrpc/id_generator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module JRPC
+  class IdGenerator
+    def initialize(prefix: nil, thread_safe: false)
+      @prefix = prefix || SecureRandom.hex(8)
+      @n = 0
+      @mutex = thread_safe ? Mutex.new : nil
+    end
+
+    def next
+      n = if @mutex
+            @mutex.synchronize { @n += 1 }
+          else
+            @n += 1
+          end
+      "#{@prefix}-#{n}"
+    end
+  end
+end

data/lib/jrpc/message.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module JRPC
+  module Message
+    def self.build_request(method, params, id)
+      validate_params!(method, params)
+      envelope = { 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'method' => method.to_s, 'id' => id }
+      envelope['params'] = params unless params.nil?
+      envelope
+    end
+
+    def self.build_notification(method, params)
+      validate_params!(method, params)
+      envelope = { 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'method' => method.to_s }
+      envelope['params'] = params unless params.nil?
+      envelope
+    end
+
+    def self.dump(envelope)
+      JSON.generate(envelope)
+    end
+
+    def self.parse(json_string)
+      JSON.parse(json_string)
+    rescue JSON::ParserError => e
+      raise Errors::MalformedResponseError, "JSON parse error: #{e.message}"
+    end
+
+    def self.validate_response!(hash, expected_id)
+      raise Errors::MalformedResponseError, 'response must be a Hash' unless hash.is_a?(Hash)
+      raise Errors::MalformedResponseError, "jsonrpc must be #{JRPC::JSON_RPC_VERSION.inspect}" unless hash['jsonrpc'] == JRPC::JSON_RPC_VERSION
+      unless hash['id'] == expected_id
+        raise Errors::MalformedResponseError, "id mismatch: expected #{expected_id.inspect}, got #{hash['id'].inspect}"
+      end
+
+      has_result = hash.key?('result')
+      has_error = hash.key?('error')
+      unless has_result ^ has_error
+        raise Errors::MalformedResponseError, "response must have exactly one of 'result' or 'error'"
+      end
+
+      if has_error
+        err = hash['error']
+        raise Errors::MalformedResponseError, 'error must be a Hash' unless err.is_a?(Hash)
+        raise Errors::MalformedResponseError, 'error.code must be an Integer' unless err['code'].is_a?(Integer)
+        raise Errors::MalformedResponseError, 'error.message must be a String' unless err['message'].is_a?(String)
+      end
+    end
+
+    def self.error_to_exception(error_hash)
+      code = error_hash['code']
+      message = error_hash['message']
+      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)
+      end
+    end
+
+    def self.validate_params!(method, params)
+      unless method.is_a?(String) || method.is_a?(Symbol)
+        raise Errors::ClientError, 'method must be a String or Symbol'
+      end
+      raise Errors::ClientError, 'method must not be empty' if method.to_s.empty?
+      unless params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+        raise Errors::ClientError, 'params must be nil, Array, or Hash'
+      end
+    end
+
+    private_class_method :validate_params!
+  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/outbound_queue.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module JRPC
+  class SharedClient
+    class OutboundQueue
+      def initialize(capacity: nil)
+        @mutex = Mutex.new
+        @arr = []
+        @capacity = capacity
+        @closed = false
+      end
+
+      # Raises ClientError("queue full") or ClientError("queue closed") on failure.
+      def push_nonblock(ticket)
+        @mutex.synchronize do
+          raise Errors::ClientError, 'queue closed' if @closed
+          raise Errors::ClientError, 'queue full' if @capacity && @arr.size >= @capacity
+
+          @arr << ticket
+        end
+      end
+
+      # Returns next Ticket or nil if empty.
+      def pop_nonblock
+        @mutex.synchronize { @arr.shift }
+      end
+
+      # Yields each ticket from a snapshot; does not hold the mutex during the block.
+      def each_snapshot(&)
+        snapshot = @mutex.synchronize { @arr.dup }
+        snapshot.each(&)
+      end
+
+      # Removes by object identity. Returns true if removed, false if not found.
+      def delete(ticket)
+        @mutex.synchronize do
+          idx = @arr.index { |t| t.equal?(ticket) }
+          return false unless idx
+
+          @arr.delete_at(idx)
+          true
+        end
+      end
+
+      # Returns the earliest expires_at across all queued tickets, or nil.
+      def earliest_deadline
+        @mutex.synchronize do
+          deadlines = @arr.filter_map(&:expires_at)
+          deadlines.min
+        end
+      end
+
+      def empty?
+        @mutex.synchronize { @arr.empty? }
+      end
+
+      def size
+        @mutex.synchronize { @arr.size }
+      end
+
+      # Sets closed = true, returns and clears all remaining tickets.
+      # Idempotent: returns [] on second call.
+      def close_and_drain
+        @mutex.synchronize do
+          @closed = true
+          @arr.slice!(0..)
+        end
+      end
+    end
+  end
+end

data/lib/jrpc/shared_client/registry.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module JRPC
+  class SharedClient
+    class Registry
+      def initialize
+        @mutex = Mutex.new
+        @tickets = {}
+      end
+
+      def register(ticket)
+        @mutex.synchronize { @tickets[ticket.id] = ticket }
+      end
+
+      def fetch_and_delete(id)
+        @mutex.synchronize { @tickets.delete(id) }
+      end
+
+      def delete(ticket)
+        @mutex.synchronize { @tickets.delete(ticket.id) }
+      end
+
+      # Yields each ticket while holding the registry mutex. Block must be quick — no I/O.
+      def each_ticket(&blk)
+        @mutex.synchronize { @tickets.each_value(&blk) }
+      end
+
+      # Signals every ticket with error and clears the registry atomically.
+      # Idempotent: tickets already in :done/:cancelled are skipped.
+      TERMINAL_STATES = %i[done cancelled].freeze
+
+      def drain_all_with(error)
+        tickets = @mutex.synchronize { @tickets.values.tap { @tickets.clear } }
+        tickets.each do |ticket|
+          next if TERMINAL_STATES.include?(ticket.state)
+
+          ticket.signal_error(error)
+        end
+      end
+
+      def empty?
+        @mutex.synchronize { @tickets.empty? }
+      end
+    end
+  end
+end

data/lib/jrpc/shared_client/ticket.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module JRPC
+  class SharedClient
+    # One in-flight request or notification together with its result future.
+    #
+    # The result is backed by a write-once Concurrent::Promises.resolvable_future.
+    # That single primitive replaces the old hand-rolled Mutex+ConditionVariable
+    # state machine and gives us three things for free:
+    #
+    #   * idempotent resolution  - fulfill/reject never raise on a second call,
+    #     so the transport loop and the close path can both resolve a ticket
+    #     without racing (fixes the old :cancelled -> :done overwrite).
+    #   * a caller-side timeout   - #wait takes a timeout, so a caller is no
+    #     longer at the mercy of the loop thread to be woken (fixes the
+    #     "loop dies, callers hang forever" hole).
+    #   * fiber cooperation       - the future's wait bottoms out in a
+    #     scheduler-aware ConditionVariable, so blocking a fiber under Falcon /
+    #     rage-rb yields to the reactor instead of stalling the thread.
+    #
+    # `cancelled` is a separate monotonic flag (the caller gave up); it is
+    # deliberately NOT part of the future, so cancellation can never race or
+    # overwrite a real result.
+    class Ticket
+      attr_reader :id, :payload, :thread, :expires_at
+
+      def initialize(id:, payload:, thread:, expires_at: nil)
+        @id = id
+        @payload = payload
+        @thread = thread
+        @expires_at = expires_at
+        @future = Concurrent::Promises.resolvable_future
+        @cancelled = Concurrent::AtomicBoolean.new(false)
+      end
+
+      # --- caller side -------------------------------------------------------
+
+      # Block until resolved or `timeout` seconds elapse (nil waits forever).
+      # Cooperates with the fiber scheduler. Returns self; inspect afterwards.
+      def wait(timeout = nil)
+        @future.wait(timeout)
+        self
+      end
+
+      def resolved? = @future.resolved?
+      def fulfilled? = @future.fulfilled?
+      def rejected? = @future.rejected?
+      def result = @future.fulfilled? ? @future.value : nil
+      def error = @future.rejected? ? @future.reason : nil
+
+      def cancel = @cancelled.make_true
+      def cancelled? = @cancelled.true?
+
+      # --- worker (transport loop / close) side ------------------------------
+      # All idempotent: the first resolution wins, later ones are no-ops.
+
+      def fulfill(value) = @future.fulfill(value, false)
+      def reject(err) = @future.reject(err, false)
+
+      # Resolution aliases used by Registry/OutboundQueue and the transport loop.
+      def signal_done(result:) = fulfill(result)
+      def signal_error(err) = reject(err)
+      # blocking notification: caller waits only for the send
+      def signal_sent = fulfill(nil)
+
+      # Coarse state view kept for Registry, which skips already-settled tickets.
+      def state
+        return :cancelled if cancelled?
+        return :done if resolved?
+
+        :pending
+      end
+
+      # --- misc --------------------------------------------------------------
+
+      # fire_and_forget tickets (thread: nil) are never "alive".
+      def alive? = @thread.nil? ? false : @thread.alive?
+
+      def expired?(now) = @expires_at ? now >= @expires_at : false
+    end
+  end
+end