protocol-jsonrpc 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0605256ce9da467440c5c83f3d871eef77a465a33553f9f3fbb7d5f4f4edbcd2
-  data.tar.gz: baa116715ac8ad29ad29f5cf188dcba524e6bcfbce4f88ecfd69288736bac692
+  metadata.gz: b54b4f7232fe6c0daa9a4e589f4db5edd2aba983cbcfc7a4ab880cfaaa2c2ffa
+  data.tar.gz: f8df39a2b673213f62e9681e1500d7f7b487aa4c77d925253e3dc019c6c0f8d1
 SHA512:
-  metadata.gz: 8843f873055775f88cd4d5780d21ae605c3ebd688c94f700388be5edddbf3e795ceb15ba69557ddafe7a08224b7f95d52a3c1a68357fd1ea427af54a2cf64868
-  data.tar.gz: 7b8cd982a41aa44003629fdea9dc16d6ce447eb1cdaf3c25e26600e61dee5674490eed22f5b3183b71fcd48375270447ae4f8f29b21b8986889633840628bb3e
+  metadata.gz: ee456605301d8af0745a57b453583ba115f711f63a93b24463ad86fafaa32e862832d81359654eb48ded753ba6aa1568e251855ec115858984bed24b6dc4277a
+  data.tar.gz: 6683a84ec2f1bdc098dfb09caf187cf34763896067f10711b232f54971b8566a3ffedf13224e3a2b9fbb726d799d4e249b9b761f03b92e938d168402d7fecc5f

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.2.1] - 2025-06-01
+
+- If a reply block for a Notification raises, suppress the error as defined in the spec
+
+## [0.2.0] - 2025-06-01
+
+**Breaking changes**: As I work towarsd a 1.0.0 release, I've changed the interface to ensure a uniform interface for [JSON-RPC 2.0 batch processing](https://www.jsonrpc.org/specification#batch). I believe we have a much more robust implementation now, so I will try to stay more consistent, but please be cautious upgrading until 1.0.0 is released and we finalize the interface.
+
+- Adds full support for batch processing with uniform reply block interface.
+- Better error handling, though this is my biggest area of improvement.
+- InvalidMessage is now returned when a message is invalid, allowing the receiver to inspect and handle the message, but still benefiting from automatic replies.
+
 ## [0.1.0] - 2025-04-20
 
 - Initial release

data/README.md

@@ -23,10 +23,27 @@ gem install protocol-jsonrpc
 
 Protocol::Jsonrpc has several core concepts:
 
-- A `Protocol::Jsonrpc::Message` is the base class which represents JSON-RPC message structures
-- A `Protocol::Jsonrpc::Framer` wraps an underlying stream (like a socket) for reading and writing JSON-RPC messages
-- A `Protocol::Jsonrpc::Connection` wraps a framer and provides higher-level methods for communication
-- Various message types including `RequestMessage`, `ResponseMessage`, `NotificationMessage`, and `ErrorMessage`
+### `Protocol::Jsonrpc::Message`
+
+This is the type which represents JSON-RPC message structures.
+
+Each of the 4 JSONRPC message types has their own class which include the `Message` module.
+
+- `Protocol::Jsonrpc::ErrorResponse`
+- `Protocol::Jsonrpc::Notification`
+- `Protocol::Jsonrpc::Request`
+- `Protocol::Jsonrpc::Response`
+
+### `Protocol::Jsonrpc::Framer`
+
+This provides one implementation for an object that splits JSONRPC messages off of some sort of socket or communication layer.
+
+The provided implementation wraps an underlying bi-directional stream (like a unixsocket) for reading and writing JSON-RPC messages.
+
+### `Protocol::Jsonrpc::Connection`
+
+This wraps a framer and provides higher-level methods for communication.
+
 
 ## Basic Usage
 
@@ -35,9 +52,8 @@ Protocol::Jsonrpc has several core concepts:
 Here's a basic example showing how to create a JSON-RPC connection over a socket pair:
 
 ```ruby
-require 'protocol/jsonrpc'
-require 'protocol/jsonrpc/connection'
-require 'socket'
+require "protocol/jsonrpc"
+require "socket"
 
 # Create a socket pair for testing
 client_socket, server_socket = UNIXSocket.pair
@@ -47,12 +63,12 @@ client = Protocol::Jsonrpc::Connection.new(Protocol::Jsonrpc::Framer.new(client_
 server = Protocol::Jsonrpc::Connection.new(Protocol::Jsonrpc::Framer.new(server_socket))
 
 # Client sends a request
-subtract = Protocol::Jsonrpc::RequestMessage.new(method: "subtract", params: [42, 23])
+subtract = Protocol::Jsonrpc::Request.new(method: "subtract", params: [42, 23])
 client.write(subtract)
 
 # Server reads the request
 message = server.read
-# => <#Protocol::Jsonrpc::RequestMessage id:"...", method: "subtract", params: [42, 23]>
+# => <#Protocol::Jsonrpc::Request id:"...", method: "subtract", params: [42, 23]>
 
 # Server processes the request (calculating the result)
 result = message.params.inject(:-) if message.method == "subtract"
@@ -69,13 +85,14 @@ client.close
 server.close
 ```
 
-### Realistic Server Implementation
+### Server Implementation
 
-For a more realistic server implementation:
+Here's a server implementation showing how to handle different message types:
 
 ```ruby
 require 'protocol/jsonrpc'
 require 'protocol/jsonrpc/connection'
+require 'protocol/jsonrpc/framer'
 require 'socket'
 
 server = TCPServer.new('localhost', 4567)
@@ -90,39 +107,27 @@ handlers = {
   "divide" => ->(params) { params.reduce(:/) }
 }
 
-# Track pending requests awaiting responses
-pending_requests = {}
+def handle_request(method, params)
+  puts "Received request: #{method}"
+  if handlers.key?(method)
+    handlers[method].call(params)
+  else
+    raise Protocol::Jsonrpc::MethodNotFoundError.new
+  end
+end
 
 # Main server loop
 begin
   while (message = connection.read)
-    case message
-    when Protocol::Jsonrpc::RequestMessage
-      puts "Received request: #{message.method}"
-
-      if handlers.key?(message.method)
-        result = handlers[message.method].call(message.params)
-        connection.write(message.reply(result))
-      else
-        error = Protocol::Jsonrpc::MethodNotFoundError.new
-        connection.write(message.reply(error))
+    response = message.reply do |message|
+      if message.request?
+        handle_request(message.method, message.params)
+      elsif message.notification?
+        puts "Notification: #{message.method}"
+        # Handle notification (no response needed)
       end
-
-    when Protocol::Jsonrpc::NotificationMessage
-      puts "Notification: #{message.method}"
-      # Handle notification (no response needed)
-
-    when Protocol::Jsonrpc::ResponseMessage
-      puts "Response: #{message.result}"
-      # Process response for an earlier request
-      request = pending_requests.delete(message.id)
-      request.call(message) if request
-
-    when Protocol::Jsonrpc::ErrorMessage
-      puts "Error: #{message.error.message}"
-      request = pending_requests.delete(message.id)
-      request.call(message) if request
     end
+    connection.write(response)
   end
 rescue Errno::EPIPE, IOError => e
   puts "Connection closed: #{e.message}"
@@ -139,14 +144,14 @@ end
 
 ```ruby
 # Create a request with positional parameters
-request = Protocol::Jsonrpc::RequestMessage.new(
+request = Protocol::Jsonrpc::Request.new(
   method: "subtract",
   params: [42, 23],
   id: 1  # Optional, auto-generated if not provided
 )
 
 # Create a request with named parameters
-request = Protocol::Jsonrpc::RequestMessage.new(
+request = Protocol::Jsonrpc::Request.new(
   method: "subtract",
   params: { minuend: 42, subtrahend: 23 },
   id: 2
@@ -158,9 +163,9 @@ request = Protocol::Jsonrpc::RequestMessage.new(
 Notifications are similar to requests but don't expect a response:
 
 ```ruby
-notification = Protocol::Jsonrpc::NotificationMessage.new(
+notification = Protocol::Jsonrpc::Notification.new(
   method: "update",
-  params: [1, 2, 3, 4, 5]
+  params: { a: 1 }
 )
 ```
 
@@ -172,8 +177,15 @@ Typically created by replying to a request:
 # From a request object
 response = request.reply(19)
 
+response = request.reply do |message|
+  message.params.sum if message.request? && message.method == "add"
+  if message.method == "fail"
+    raise "Oops, we failed" # gets turned into a error response
+  end
+end
+
 # Or directly
-response = Protocol::Jsonrpc::ResponseMessage.new(
+response = Protocol::Jsonrpc::Response.new(
   result: 19,
   id: 1
 )
@@ -188,79 +200,117 @@ For error responses:
 error = Protocol::Jsonrpc::InvalidParamsError.new("Invalid parameters")
 error_response = request.reply(error)
 
-# Standard error types include:
-# - ParseError
-# - InvalidRequestError
-# - MethodNotFoundError
-# - InvalidParamsError
-# - InternalError
-# - ServerError
+# Create from a reply that raises
+response = request.reply do |message|
+  raise "Oops" # Returns an InternalError response
+end
+```
+
+Error types represent the standard JSON-RPC error codes:
+
+```ruby
+Protocol::Jsonrpc::ParseError
+Protocol::Jsonrpc::InvalidRequestError
+Protocol::Jsonrpc::MethodNotFoundError
+Protocol::Jsonrpc::InvalidParamsError
+Protocol::Jsonrpc::InternalError
+```
+
+Most of the errors happen automatically, but some must be triggered manually.
+
+```ruby
+response = request.reply do |message|
+  raise Protocol::Jsonrpc::MethodNotFoundError, "We don't support any methods"
+end
 ```
 
 ## Batch Processing
 
-JSON-RPC supports batch requests and responses:
+JSON-RPC supports batch requests and responses. The library returns a `Protocol::Jsonrpc::Batch` that acts like an array and provides a `reply` method for processing:
 
 ```ruby
+# Send a batch request (client side)
 batch = [
-  Protocol::Jsonrpc::RequestMessage.new(method: "sum", params: [1, 2, 4]),
-  Protocol::Jsonrpc::NotificationMessage.new(method: "notify_hello", params: [7]),
-  Protocol::Jsonrpc::RequestMessage.new(method: "subtract", params: [42, 23])
+  Protocol::Jsonrpc::Request.new(method: "sum", params: [1, 2, 4]),
+  Protocol::Jsonrpc::Notification.new(method: "notify_hello", params: [7]),
+  Protocol::Jsonrpc::Request.new(method: "subtract", params: [42, 23])
 ]
 
-# Send batch request
 client.write(batch)
 
 # Process batch on server
-messages = server.read
-
-batch_response = messages.filter_map do |msg|
-  case msg
-  when Protocol::Jsonrpc::RequestMessage
-    # Only add responses for requests, not notifications
-    if msg.method == "sum"
-      msg.reply(msg.params.sum)
-    elsif msg.method == "subtract"
-      msg.reply(msg.params.reduce(:-))
+batch = server.read
+
+# Process each message in the batch using reply
+batch_response = batch.reply do |message|
+  case message
+  when Protocol::Jsonrpc::Request
+    # Handle request and return result
+    if message.method == "sum"
+      message.params.sum
+    elsif message.method == "subtract"
+      message.params.reduce(:-)
     else
-      msg.reply(Protocol::Jsonrpc::MethodNotFoundError.new)
+      # raising during a reply block will automatically respond with an error
+      raise Protocol::Jsonrpc::MethodNotFoundError.new
     end
-  when Protocol::Jsonrpc::NotificationMessage
-    handle_notification(msg)
-    nil
+  when Protocol::Jsonrpc::Notification
+    # Handle notification (return value is ignored)
+    handle_notification(message)
   end
 end
 
-# Send batch response if not empty
-server.write(batch_response) unless batch_response.empty?
+# Send batch response (automatically includes responses for requests, not notifications)
+server.write(batch_response)
 ```
 
+Batch processing supports;
+
+1. Consistent interface (`reply`) for both single and batch requests
+2. Automatic error handling and response collection
+3. Filters out nil responses (from notifications) automatically
+4. Maintains protocol compliance by only responding to requests and handling malformed batches
+
 ## Custom Framers
 
 The supplied Framer is designed for a bidirectional socket.
-You can also supply your own framer:
+You can also supply your own framer by implementing the following interface:
 
 ```ruby
 class MyFramer
-  def flush; end
-  def close; end
-
-  # Return an object that response to unpack
+  # Return a Frame object that contains the raw JSON
   def read_frame
+    # Read JSON data from your source (e.g., HTTP body, WebSocket, etc.)
+    raw_json = get_json_line_from_somewhere
+
+    # Return a Frame object
+    Protocol::Jsonrpc::Frame.new(raw_json: raw_json)
   end
 
-  # Accepts a
+  # Write a Frame object
   def write_frame(frame)
+    # frame.raw_json contains the JSON string to send
+    send_json_somewhere(frame.raw_json)
   end
-end
 
+  # Flush any buffered data
+  def flush
+    # Implementation depends on your transport
+  end
+
+  # Close the connection
+  def close
+    # Clean up resources
+  end
+end
 
 client = Protocol::Jsonrpc::Connection.new(MyFramer.new)
-client.read # calls read_frame, calling unpack on the returned object
 
-message = Protocol::Jsonrpc::NotificationMessage.new(method: "hello", params: ["world"])
-client.write(message) # calls write_frame with any message responding to `as_json`
+# Read messages (calls framer.read_frame and unpacks the JSON)
+message = client.read
 
+# Write messages (packs to JSON and calls framer.write_frame)
+client.write(Protocol::Jsonrpc::Notification.new(method: "hello", params: ["world"]))
 ```
 
 ## Development

data/lib/protocol/jsonrpc/batch.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright 2025 by Martin Emde
+
+module Protocol
+  module Jsonrpc
+    Batch = Data.define(:messages) do
+      def self.load(data)
+        return InvalidMessage.new(data: data.inspect) if data.empty?
+
+        messages = data.map { |message| Message.load(message) }
+        new(messages)
+      end
+
+      def to_a = messages
+      alias_method :to_ary, :to_a
+
+      def as_json = to_a.map(&:as_json)
+
+      def to_json(...) = JSON.generate(to_a.map(&:as_json), ...)
+      alias_method :to_s, :to_json
+
+      def reply(&block)
+        to_a.filter_map do |message|
+          message.reply(&block)
+        end
+      end
+
+      private
+
+      def method_missing(method, *args, **kwargs, &block)
+        if messages.respond_to?(method)
+          messages.send(method, *args, **kwargs, &block)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        messages.respond_to?(method, include_private) || super
+      end
+    end
+  end
+end

data/lib/protocol/jsonrpc/connection.rb

@@ -3,8 +3,6 @@
 # Released under the MIT License.
 # Copyright 2025 by Martin Emde
 
-require_relative "message"
-
 module Protocol
   module Jsonrpc
     class Connection
@@ -22,24 +20,24 @@ module Protocol
         @framer.close
       end
 
-      # Read a message from the framer
-      # @yield [Protocol::Jsonrpc::Message] The read message
-      # @return [Protocol::Jsonrpc::Message] The read message
+      # Read the next message or batch of messages from the framer
+      # @yield [Protocol::Jsonrpc::Message] Each message is yielded to the block
+      # @return [Protocol::Jsonrpc::Message, Protocol::Jsonrpc::Batch] The message or batch of messages
       def read(&block)
         flush
         frame = read_frame
         message = Message.load(frame.unpack)
         yield message if block_given?
         message
+      rescue => e
+        InvalidMessage.new(error: e)
       end
 
       # Write a message to the framer
-      # @param message [Protocol::Jsonrpc::Message, Array<Protocol::Jsonrpc::Message>] The message(s) to write
+      # @param message [Protocol::Jsonrpc::Message, Array<Protocol::Jsonrpc::Message>, Batch] The message(s) to write
       # @return [Boolean] True if successful
       def write(message)
-        frame = Frame.pack(message)
-        write_frame(frame)
-        true
+        write_frame Frame.pack(message)
       end
 
       # Low level read a frame from the framer

data/lib/protocol/jsonrpc/error.rb

@@ -15,7 +15,7 @@ module Protocol
       INVALID_PARAMS = -32_602
       INTERNAL_ERROR = -32_603
 
-      MESSAGES = Hash.new("Error").merge(
+      ERROR_MESSAGES = Hash.new("Error").merge(
         PARSE_ERROR => "Parse error",
         INVALID_REQUEST => "Invalid Request",
         METHOD_NOT_FOUND => "Method not found",
@@ -24,8 +24,10 @@ module Protocol
       ).freeze
 
       # Factory method to create the appropriate error type
+      # @param code [Integer] The JSON-RPC error code
+      # @param message [String] The error message
+      # @param data [#as_json, #to_json] Serializable data to return to the client
       # @param id [String, Integer] The request ID
-      # @param error [Hash] The error data from the JSON-RPC response
       # @return [Error] The appropriate error instance
       def self.from_message(code:, message:, data: nil, id: nil)
         case code
@@ -44,33 +46,43 @@ module Protocol
         end
       end
 
-      def self.wrap(error)
+      def self.wrap(error, data: nil, id: nil)
         case error
+        in nil
+          InvalidRequestError.new(data:, id:)
+        in String
+          InternalError.new(error, data:, id:)
         in Hash
           error = error.transform_keys(&:to_sym)
-          from_message(**error)
+          from_message(id: id, data: data, **error)
         in Jsonrpc::Error
+          error.data ||= data if data
+          error.id ||= id if id
           error
         in JSON::ParserError
-          ParseError.new(error.message, data: error)
+          ParseError.new("Parse error: #{error.message}", data:, id:)
         in StandardError
-          InternalError.new(error.message, data: error)
-        else
+          InternalError.new(error.message, data:, id:)
+        in Exception
           raise error
+        else
+          raise ArgumentError, "Unknown error type: #{error.class}"
         end
       end
 
-      attr_reader :data, :code, :id
+      attr_accessor :data, :id
+      attr_reader :code
 
       def initialize(message = nil, data: nil, id: nil)
         message = nil if message&.empty?
-        super([MESSAGES[code], message].compact.uniq.join(": "))
+        message ||= ERROR_MESSAGES[code]
+        super(message)
         @data = data
         @id = id
       end
 
       def reply(id: @id)
-        ErrorMessage.new(id:, error: self)
+        ErrorResponse.new(id:, error: self)
       end
 
       def to_h

data/lib/protocol/jsonrpc/{error_message.rb → error_response.rb}

@@ -3,14 +3,12 @@
 # Released under the MIT License.
 # Copyright 2025 by Martin Emde
 
-require_relative "message"
-
 module Protocol
   module Jsonrpc
-    ErrorMessage = Data.define(:id, :error) do
+    ErrorResponse = Data.define(:id, :error, :jsonrpc) do
       include Message
 
-      def initialize(id:, error:)
+      def initialize(id:, error:, jsonrpc: JSONRPC_VERSION)
         unless id.nil? || id.is_a?(String) || id.is_a?(Numeric)
           raise InvalidRequestError.new("ID must be nil, string or number", id: id)
         end
@@ -20,7 +18,9 @@ module Protocol
         super
       end
 
-      def to_h = super.merge(id:, error: error.to_h)
+      def to_h = super.merge(error: error.to_h)
+
+      def error? = true
 
       def response? = true
     end

data/lib/protocol/jsonrpc/frame.rb

@@ -4,44 +4,60 @@
 # Copyright 2025 by Martin Emde
 
 require "json"
-require_relative "error"
 
 module Protocol
   module Jsonrpc
     # Frame represents the raw JSON data structure of a JSON-RPC message
     # before it's validated and converted into a proper Message object.
-    # This handles the parsing of JSON and initial structure validation.
-    Frame = Data.define(:json) do
-      # Read a frame from the stream
-      # @param stream [IO] The stream to read from
-      # @return [Frame, nil] The parsed frame or nil if the stream is empty
-      def self.read(stream)
-        json = stream.gets
-        return nil if json.nil?
-        new(json:)
+    # Handles translation between JSON strings and Ruby Hashes and
+    # reading and writing to a stream.
+    Frame = Data.define(:raw_json) do
+      class << self
+        # Read a frame from the stream
+        # @param stream [IO] An objects that responds to `gets` and returns a String
+        # @return [Frame, nil] The parsed frame or nil if the stream is empty
+        def read(stream)
+          raw_json = stream.gets
+          return nil if raw_json.nil?
+          new(raw_json: raw_json.strip)
+        end
+
+        # Pack a message into a frame
+        # @param message [Message, Array<Message>] The message to pack
+        # @return [Frame] an instance that can be written to a stream
+        # @raise [ArgumentError] if the message is not a Message or Array of Messages
+        def pack(message)
+          if message.is_a?(Array)
+            new(raw_json: message.map { |msg| as_json(msg) }.to_json)
+          else
+            new(raw_json: as_json(message).to_json)
+          end
+        end
+
+        private def as_json(message)
+          return message if message.is_a?(Hash)
+          return message.as_json if message.respond_to?(:as_json)
+          raise ArgumentError, "Invalid message type: #{message.class}. Must be a Hash or respond to :as_json."
+        end
       end
 
-      # Unpack the json into a JSON object
+      # Unpack the raw_json into a Hash representing the JSON object
+      # Symbolizes the keys of the Hash.
       # @return [Hash] The parsed JSON object
+      # @raise [ParseError] if the JSON is invalid
       def unpack
-        JSON.parse(json, symbolize_names: true)
-      rescue JSON::ParserError => e
-        raise ParseError.new("Failed to parse message: #{e.message}", data: json)
+        JSON.parse(raw_json, symbolize_names: true)
       end
 
-      def self.pack(message)
-        case message
-        when Array
-          new(json: message.map { |msg| msg.is_a?(Message) ? msg.as_json : msg }.to_json)
-        when Hash, Message
-          new(json: message.to_json)
-        else
-          raise ArgumentError, "Invalid message type: #{message.class}"
-        end
-      end
+      def to_json(...) = raw_json
+
+      def to_s = raw_json
 
+      # Write the frame to a stream
+      # @param stream [IO] The stream to write to
+      # @return [void]
       def write(stream)
-        stream.write("#{json}\n")
+        stream.write("#{raw_json}\n")
       end
     end
   end

data/lib/protocol/jsonrpc/invalid_message.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright 2025 by Martin Emde
+
+module Protocol
+  module Jsonrpc
+    # When the message received is not valid JSON or not a valid JSON-RPC message,
+    # this class is returned in place of a normal Message.
+    # The error that would have been raised is returned as the error.
+    # This simplifies batch processing because invalid messages in the batch
+    # can be processed as part of the batch rather than raising and interrupting
+    # the batch processing.
+    InvalidMessage = Data.define(:error, :id) do
+      include Message
+
+      def initialize(error: nil, data: nil, id: nil)
+        error = Error.wrap(error, data:, id:)
+        super(error:, id: error.id)
+      end
+
+      def invalid? = true
+
+      def as_json = raise "InvalidMessage cannot be serialized"
+
+      def reply(...) = ErrorResponse.new(id:, error:)
+
+      def to_json(...) = raise "InvalidMessage cannot be serialized"
+
+      def to_s = raise "InvalidMessage cannot be serialized"
+    end
+  end
+end

data/lib/protocol/jsonrpc/message.rb

@@ -6,18 +6,15 @@
 require "json"
 require "securerandom"
 require "timeout"
-require_relative "error"
 
 module Protocol
   module Jsonrpc
-    # JsonrpcMessage provides stateless operations for creating and validating JSON-RPC messages.
+    # Protocol::Jsonrpc::Message provides operations for creating and validating JSON-RPC messages.
     # This class handles the pure functional aspects of JSON-RPC like:
     # - Creating properly formatted request/notification messages
     # - Validating incoming messages
     # - Parsing responses and errors
     module Message
-      JSONRPC_VERSION = "2.0"
-
       class << self
         # Validate, and return the JSON-RPC message or batch
         # @param data [Hash, Array] The parsed message
@@ -29,76 +26,56 @@ module Protocol
           when Hash
             from_hash(data)
           when Array
-            from_array(data)
+            Batch.load(data)
           else
-            raise InvalidRequestError.new("Invalid request object", data: data.inspect)
-          end
-        end
-
-        # This is wrong. It seems like we need something more like
-        # an enumerator where we can run the full parse, handle, response
-        # cycle for each item in the array, aggregating the results and
-        # errors and then returning the array.
-        #
-        # The problem is that the errors should get raised and then
-        # handled which turns them into ErrorMessages and then the errors
-        # get returned to the client.
-        #
-        # Ideally this array handling would be invisible to the connection
-        # which would just handle one at a time with the array wrapper
-        # being applied by a single place that handles the batching.
-        def from_array(array)
-          raise InvalidRequestError.new("Empty batch", data: array.inspect) if array.empty?
-
-          array.map do |msg|
-            from_hash(msg)
-          rescue => e
-            Error.wrap(e)
+            InvalidMessage.new(data: data.inspect)
           end
         end
 
         # @param parsed [Hash] The parsed message
         # @return [Message] The parsed message
         def from_hash(parsed)
-          raise InvalidRequestError.new("Request is not an object", data: parsed) unless parsed.is_a?(Hash)
-          raise InvalidRequestError.new("Unexpected JSON-RPC version", data: parsed) unless parsed[:jsonrpc] == JSONRPC_VERSION
+          return InvalidMessage.new(data: parsed.inspect) unless parsed.is_a?(Hash)
+
+          jsonrpc = parsed[:jsonrpc]
 
           case parsed
-          in { id:, error: }
-            ErrorMessage.new(id:, error: Error.from_message(**error))
-          in { id:, result: }
-            ResponseMessage.new(id:, result:)
-          in { id:, method: }
-            RequestMessage.new(id:, method:, params: parsed[:params])
-          in { method: }
-            NotificationMessage.new(method:, params: parsed[:params])
+          in {id:, error:}
+            ErrorResponse.new(id:, error: Error.from_message(**error), jsonrpc:)
+          in {id:, result:}
+            Response.new(id:, result:, jsonrpc:)
+          in {id:, method:}
+            Request.new(id:, method:, params: parsed[:params], jsonrpc:)
+          in {method:}
+            Notification.new(method:, params: parsed[:params], jsonrpc:)
           else
-            raise ParseError.new("Unknown message: #{parsed.inspect}", data: parsed)
+            InvalidMessage.new(data: parsed.inspect)
           end
+        rescue => error
+          InvalidMessage.new(error:, data: parsed.inspect)
         end
       end
 
-      def to_h = {jsonrpc: JSONRPC_VERSION}
-
-      def to_hash = to_h
-
       def as_json = to_h
 
       def to_json(...) = JSON.generate(as_json, ...)
 
       def to_s = to_json
 
+      # Is this a request? (Request)
+      def request? = false
+
+      # Is this a notification? (Notification)
+      def notification? = false
+
+      # Is this a response to a request? (Error or Response)
       def response? = false
 
-      def match?(message) = false
+      # Is this an error response? (ErrorResponse)
+      def error? = false
 
-      def reply(result_or_error)
-        if result_or_error.is_a?(StandardError)
-          ErrorMessage.new(id:, error: result_or_error)
-        else
-          ResponseMessage.new(id:, result: result_or_error)
-        end
-      end
+      # Is this an invalid message? (InvalidMessage)
+      def invalid? = false
     end
   end
 end

data/lib/protocol/jsonrpc/notification.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright 2025 by Martin Emde
+
+module Protocol
+  module Jsonrpc
+    Notification = Data.define(:method, :params, :jsonrpc) do
+      include Message
+
+      def initialize(method:, params: nil, jsonrpc: JSONRPC_VERSION)
+        super
+
+        unless method.is_a?(String)
+          raise InvalidRequestError.new("Method must be a string", data: method.inspect)
+        end
+        unless params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+          raise InvalidRequestError.new("Params must be an array or object", data: params.inspect)
+        end
+      end
+
+      def to_h
+        h = super
+        h.delete(:params) if params.nil?
+        h
+      end
+
+      # Compatibility with the Message interface, Notifications have no ID
+      def id = nil
+
+      # Compatibility with the Request
+      # Yields the notification for processing but ignores the result
+      def reply(*, &)
+        yield self if block_given?
+        nil
+      rescue
+        nil # JSON-RPC 2.0 spec says notifications should never return, even on error.
+      end
+
+      def notification? = true
+    end
+  end
+end

data/lib/protocol/jsonrpc/{request_message.rb → request.rb}

@@ -4,14 +4,13 @@
 # Copyright 2025 by Martin Emde
 
 require "securerandom"
-require_relative "message"
 
 module Protocol
   module Jsonrpc
-    RequestMessage = Data.define(:method, :params, :id) do
+    Request = Data.define(:method, :params, :id, :jsonrpc) do
       include Message
 
-      def initialize(method:, params: nil, id: SecureRandom.uuid)
+      def initialize(method:, params: nil, id: SecureRandom.uuid, jsonrpc: JSONRPC_VERSION)
         unless method.is_a?(String)
           raise InvalidRequestError.new("Method must be a string", data: method.inspect)
         end
@@ -26,12 +25,32 @@ module Protocol
       end
 
       def to_h
-        h = super.merge(id:, method:)
-        h[:params] = params if params
+        h = super
+        h.delete(:params) if params.nil?
         h
       end
 
-      def response? = false
+      def request? = true
+
+      def reply(*args, &)
+        if args.empty? && block_given?
+          begin
+            result_or_error = yield self
+          rescue => error
+            return ErrorResponse.new(id:, error:)
+          end
+        elsif args.length == 1
+          result_or_error = args.first
+        else
+          raise ArgumentError, "wrong number of arguments (given #{args.length}, expected 0 or 1)"
+        end
+
+        if result_or_error.is_a?(StandardError)
+          ErrorResponse.new(id:, error: result_or_error)
+        else
+          Response.new(id:, result: result_or_error)
+        end
+      end
     end
   end
 end

data/lib/protocol/jsonrpc/{response_message.rb → response.rb}

@@ -3,23 +3,19 @@
 # Released under the MIT License.
 # Copyright 2025 by Martin Emde
 
-require_relative "message"
-
 module Protocol
   module Jsonrpc
-    ResponseMessage = Data.define(:id, :result) do
+    Response = Data.define(:id, :result, :jsonrpc) do
       include Message
 
-      def initialize(id:, result:)
+      def initialize(id:, result:, jsonrpc: JSONRPC_VERSION)
         unless id.nil? || id.is_a?(String) || id.is_a?(Numeric)
-          raise InvalidRequestError.new("ID must be nil, string or number", id:)
+          raise InvalidRequestError.new("ID must be nil, string, or number", id:)
         end
 
         super
       end
 
-      def to_h = super.merge(id:, result:)
-
       def response? = true
     end
   end

data/lib/protocol/jsonrpc/version.rb

@@ -5,6 +5,6 @@
 
 module Protocol
   module Jsonrpc
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/protocol/jsonrpc.rb

@@ -3,16 +3,21 @@
 # Released under the MIT License.
 # Copyright 2025 by Martin Emde
 
-require_relative "jsonrpc/version"
-require_relative "jsonrpc/error"
-require_relative "jsonrpc/message"
-require_relative "jsonrpc/connection"
-require_relative "jsonrpc/error_message"
-require_relative "jsonrpc/notification_message"
-require_relative "jsonrpc/request_message"
-require_relative "jsonrpc/response_message"
-
 module Protocol
   module Jsonrpc
+    JSONRPC_VERSION = "2.0"
   end
 end
+
+require_relative "jsonrpc/version"
+require_relative "jsonrpc/error"
+require_relative "jsonrpc/message"
+require_relative "jsonrpc/error_response"
+require_relative "jsonrpc/invalid_message"
+require_relative "jsonrpc/notification"
+require_relative "jsonrpc/request"
+require_relative "jsonrpc/response"
+require_relative "jsonrpc/frame"
+require_relative "jsonrpc/framer"
+require_relative "jsonrpc/connection"
+require_relative "jsonrpc/batch"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-jsonrpc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Martin Emde
@@ -34,15 +34,17 @@ files:
 - LICENSE.txt
 - README.md
 - lib/protocol/jsonrpc.rb
+- lib/protocol/jsonrpc/batch.rb
 - lib/protocol/jsonrpc/connection.rb
 - lib/protocol/jsonrpc/error.rb
-- lib/protocol/jsonrpc/error_message.rb
+- lib/protocol/jsonrpc/error_response.rb
 - lib/protocol/jsonrpc/frame.rb
 - lib/protocol/jsonrpc/framer.rb
+- lib/protocol/jsonrpc/invalid_message.rb
 - lib/protocol/jsonrpc/message.rb
-- lib/protocol/jsonrpc/notification_message.rb
-- lib/protocol/jsonrpc/request_message.rb
-- lib/protocol/jsonrpc/response_message.rb
+- lib/protocol/jsonrpc/notification.rb
+- lib/protocol/jsonrpc/request.rb
+- lib/protocol/jsonrpc/response.rb
 - lib/protocol/jsonrpc/version.rb
 - sig/protocol/jsonrpc.rbs
 homepage: https://github.com/martinemde/protocol-jsonrpc

data/lib/protocol/jsonrpc/notification_message.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-# Released under the MIT License.
-# Copyright 2025 by Martin Emde
-
-require_relative "message"
-
-module Protocol
-  module Jsonrpc
-    NotificationMessage = Data.define(:method, :params) do
-      include Message
-
-      def initialize(method:, params: nil)
-        super
-
-        unless method.is_a?(String)
-          raise InvalidRequestError.new("Method must be a string", data: method.inspect)
-        end
-        unless params.nil? || params.is_a?(Array) || params.is_a?(Hash)
-          raise InvalidRequestError.new("Params must be an array or object", data: params.inspect)
-        end
-      end
-
-      def to_h
-        h = super.merge(method:)
-        h[:params] = params if params
-        h
-      end
-
-      def id = nil
-
-      def reply = nil
-
-      def response? = false
-    end
-  end
-end