jrpc 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c257edbf0909e62cffe47dc7b8a79e928b4b4c24f7166bbbbec3b7141d01270f
-  data.tar.gz: 671298a50f68328de11586e0e80eeba0ae18814ce79827b57dcd54699605c20c
+  metadata.gz: 84a616f81dad776fc7efea4d4e8fd778a3e2d5b42568118f0206f44f9b4e1b10
+  data.tar.gz: b8e8a2d8468d5e713e9015faccea22370775b99e476f17b4962cc0ebdc504d35
 SHA512:
-  metadata.gz: 807cca67ef7ae784989daa7cf89797d9e255f77087822d1c1cae607839d02b2aed75916e5b1e75c47a11bfba5526eccd8df257fd1e36cf38029ba02e137ded28
-  data.tar.gz: c987f2beba104d457137aeaa74821db2fb6835dee9161c39c50f1e409f254efc924c8c23178cc43e07867e083d7c11ebfd1dbf8f3a70d617c652380267abc224
+  metadata.gz: a58ecaa54dcaafae9871d5c7264e03adc57946859b75b72112a79bc7595df81495e5a4910fe69da28b66bf1b82c0cdb3026a5ccc0ea4f6786e81c50fea030413
+  data.tar.gz: abc7911d9cc8ffac7481decc11e01fc7524b1ce800c65c5bf7652c3567adad66ceedae7c63353f6f160a123957528254434807e58911dbaa61c221e3ee30727f

data/CHANGELOG.md

@@ -1,6 +1,23 @@
 # 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**
 

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

@@ -3,7 +3,7 @@
 [![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 2.0 client for Ruby, over TCP, with netstring framing.
+A JSON-RPC v2 client for Ruby, over TCP, with netstring framing.
 
 JRPC ships two clients with sharp, separate responsibilities:
 
@@ -133,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
@@ -145,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

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/transport/test.rb

@@ -282,12 +282,14 @@ module JRPC
         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
-        JSON.generate(
-          { 'jsonrpc' => JRPC::JSON_RPC_VERSION, 'id' => id,
-            'error' => { 'code' => code, 'message' => error.message } }
-        )
+        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)

data/lib/jrpc/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jrpc
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Denis Talakevich