protocol-jsonrpc 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0605256ce9da467440c5c83f3d871eef77a465a33553f9f3fbb7d5f4f4edbcd2
-  data.tar.gz: baa116715ac8ad29ad29f5cf188dcba524e6bcfbce4f88ecfd69288736bac692
+  metadata.gz: '0488651e9e3c97f90a8bfe83c904ade78a8e0532e524fc6b1e97fd7ec2334f0f'
+  data.tar.gz: 2d9c402bcd8786051868b545afdb858ca862fcd4e699e6910a720467b4d0ab3d
 SHA512:
-  metadata.gz: 8843f873055775f88cd4d5780d21ae605c3ebd688c94f700388be5edddbf3e795ceb15ba69557ddafe7a08224b7f95d52a3c1a68357fd1ea427af54a2cf64868
-  data.tar.gz: 7b8cd982a41aa44003629fdea9dc16d6ce447eb1cdaf3c25e26600e61dee5674490eed22f5b3183b71fcd48375270447ae4f8f29b21b8986889633840628bb3e
+  metadata.gz: 32a5eaf0c2424ce7a93250a7d164fb98a856eb918422481de1d7348906edbd9817cd87d32f55c1eeef3338c9ff7c531329cdd98bad5512254e4c121ae5442b0f
+  data.tar.gz: be8901fb47e177223a99175999b3e25798c0709505f558442020cca36d24da59e970114cefdbb907874005fac1c241360a78134e7bba2ca49869fbde3182cab2

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## [Unreleased]
 
+## [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
 
@@ -37,6 +54,7 @@ Here's a basic example showing how to create a JSON-RPC connection over a socket
 ```ruby
 require 'protocol/jsonrpc'
 require 'protocol/jsonrpc/connection'
+require 'protocol/jsonrpc/framer'
 require 'socket'
 
 # Create a socket pair for testing
@@ -47,12 +65,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 +87,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 +109,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 +146,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 +165,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 }
 )
 ```
 
@@ -173,7 +180,7 @@ Typically created by replying to a request:
 response = request.reply(19)
 
 # Or directly
-response = Protocol::Jsonrpc::ResponseMessage.new(
+response = Protocol::Jsonrpc::Response.new(
   result: 19,
   id: 1
 )
@@ -187,80 +194,105 @@ For error responses:
 # Create from an error object
 error = Protocol::Jsonrpc::InvalidParamsError.new("Invalid parameters")
 error_response = request.reply(error)
+```
 
-# Standard error types include:
-# - ParseError
-# - InvalidRequestError
-# - MethodNotFoundError
-# - InvalidParamsError
-# - InternalError
-# - ServerError
+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
 ```
 
 ## 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
+
+  # Flush any buffered data
+  def flush
+    # Implementation depends on your transport
   end
-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,22 @@ 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
+        Message.load(frame.unpack)
+      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",
@@ -44,17 +44,21 @@ 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
         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)
+          InternalError.new(error.message, data:, id:)
         else
           raise error
         end
@@ -64,13 +68,14 @@ module Protocol
 
       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,55 @@ 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))
+            ErrorResponse.new(id:, error: Error.from_message(**error), jsonrpc:)
           in { id:, result: }
-            ResponseMessage.new(id:, result:)
+            Response.new(id:, result:, jsonrpc:)
           in { id:, method: }
-            RequestMessage.new(id:, method:, params: parsed[:params])
+            Request.new(id:, method:, params: parsed[:params], jsonrpc:)
           in { method: }
-            NotificationMessage.new(method:, params: parsed[:params])
+            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_message.rb → notification.rb}

@@ -3,14 +3,12 @@
 # Released under the MIT License.
 # Copyright 2025 by Martin Emde
 
-require_relative "message"
-
 module Protocol
   module Jsonrpc
-    NotificationMessage = Data.define(:method, :params) do
+    Notification = Data.define(:method, :params, :jsonrpc) do
       include Message
 
-      def initialize(method:, params: nil)
+      def initialize(method:, params: nil, jsonrpc: JSONRPC_VERSION)
         super
 
         unless method.is_a?(String)
@@ -22,16 +20,22 @@ module Protocol
       end
 
       def to_h
-        h = super.merge(method:)
-        h[:params] = params if params
+        h = super
+        h.delete(:params) if params.nil?
         h
       end
 
+      # Compatibility with the Message interface, Notifications have no ID
       def id = nil
 
-      def reply = nil
+      # Compatibility with the Request
+      # Yields the notificatino for processing but ignores the result
+      def reply(*, &)
+        yield self if block_given?
+        nil # notification always returns nil
+      end
 
-      def response? = false
+      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.0"
   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"
+
+    autoload :Batch, "protocol/jsonrpc/batch"
+    autoload :Connection, "protocol/jsonrpc/connection"
+    autoload :Error, "protocol/jsonrpc/error"
+    autoload :ErrorResponse, "protocol/jsonrpc/error_response"
+    autoload :Frame, "protocol/jsonrpc/frame"
+    autoload :Framer, "protocol/jsonrpc/framer"
+    autoload :InvalidMessage, "protocol/jsonrpc/invalid_message"
+    autoload :Message, "protocol/jsonrpc/message"
+    autoload :Notification, "protocol/jsonrpc/notification"
+    autoload :Request, "protocol/jsonrpc/request"
+    autoload :Response, "protocol/jsonrpc/response"
+    autoload :VERSION, "protocol/jsonrpc/version"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: protocol-jsonrpc
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 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