json_rpc_handler 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e714ed8007b1495db68aef79e5a649c63b8209e1b7600c405f8611ecadd16bd
-  data.tar.gz: 3b27a986d66f12f2919e8439b3e645e3c3b2e7136d5175e11f9c1e498f07b28c
+  metadata.gz: 4d06db2e48d586ba0b9ccd2597d73d2241aef95f5ff105b12e6888c5042e8d99
+  data.tar.gz: 4685164c85a5eeba765f212ad1318eb0de154409b3d79428ac68adbddc33b97d
 SHA512:
-  metadata.gz: d385890032cb7d7bb6791292aa42392dbad2d320904364c3651a55f0c6f99a396200d481c72d30d7b29786ac6f456a9d33a4a5dcd66bce0b4768b0171eba16b8
-  data.tar.gz: 25034b8fe5653f04e692fd555323e61ac44af0b7e90eab7c2ef6947288e89fb37ac874b177980d4c76ee143c64be08056f0317cdb94a128d7b3b96d2c5781a9f
+  metadata.gz: e306065b7487a8a77ac999a74966b625a48599ff4b3013bcee2a7e666d6841b0b80b198b18410ade448df63a9eb673c4d30d2401059a5189963b51ccc91fd8c1
+  data.tar.gz: c288e6f466591a896bf51b9fa4197b15153e6ccfc3327ae3af304f090eca4e0e91c88f8f21109a57efabde74ba8fc9bd84acb319e4c5ca6a566beeb345c52405

data/README.md

@@ -1,5 +1,8 @@
 # json_rpc_handler
 
+[![Gem (including prereleases)](https://img.shields.io/gem/v/json_rpc_handler?0.1.1)](https://rubygems.org/gems/json_rpc_handler)
+[![CI](https://github.com/Shopify/json-rpc-handler/actions/workflows/ci.yml/badge.svg)](https://github.com/Shopify/json-rpc-handler/actions/workflows/ci.yml)
+
 A lightweight, fully spec-compliant [JSON-RPC 2.0][1] handler.
 
 It only deals with the parsing and handling of JSON-RPC requests, producing
@@ -79,6 +82,106 @@ method returned `nil`, or all method calls of a batch request returned `nil`. It
 is up to the integration to apply the appropriate transport-layer semantics
 (e.g. returning a 204 No Content).
 
+### Error handling
+
+Unexpected exceptions from method lookup or a registered method return code
+`-32603` and message `Internal error`, with no `data` member.
+
+Pass `on_error:` to `handle` or `handle_json` to report these exceptions. The hook
+receives the exception and a context hash with `id` and `method` keys. It runs
+before the internal error response is built, once for each failing batch item,
+including notifications. The notification's `id` is `nil`.
+
+```ruby
+methods = { 'add' => ->(params) { params[:a] + params[:b] } }
+on_error = ->(exception, context) {
+  warn "#{context[:method]} #{context[:id].inspect}: #{exception.message}"
+}
+
+JsonRpcHandler.handle(request, on_error:) { |name| methods[name] }
+JsonRpcHandler.handle_json(request_json, on_error:) { |name| methods[name] }
+```
+
+The hook's return value is ignored. If it raises a `StandardError`, that error is
+ignored without calling the hook again. The original request still gets the
+internal error response, or no response for a notification.
+
+For an explicit error response, raise `JsonRpcHandler::Error`, a `StandardError`
+subclass. Its constructor takes required `code:` and `message:` keywords and an
+optional `data:` keyword:
+
+```ruby
+response = JsonRpcHandler.handle(request) do |name|
+  if name == 'add'
+    ->(_params) {
+      raise JsonRpcHandler::Error.new(
+        code: -32001,
+        message: 'Try later',
+        data: { retry: true },
+      )
+    }
+  end
+end
+
+puts response.to_json
+# {"jsonrpc":"2.0","id":1,"error":{"code":-32001,"message":"Try later","data":{"retry":true}}}
+```
+
+The supplied code, message, and data become the response's error fields. A `nil`
+`data` value is omitted; values such as `false` and `0` are kept. There is no
+fallback from `data` to the exception message. These explicit errors do not call
+`on_error:` and still produce no response for notifications. Other response
+errors, such as Method not found and Parse error, keep their existing fields and
+do not call the hook.
+
+### ID Validation
+
+By default, string request IDs are validated to contain only alphanumeric
+characters, dashes, and underscores.
+
+**Note:** The JSON-RPC 2.0 specification does not specify a default ID validation pattern, but this default validation
+is recommended to protect against XSS vulnerabilities when IDs are reflected in responses.
+
+```rb
+# Default behavior - accepts alphanumerics, dashes, underscores
+request = { jsonrpc: '2.0', id: 'request-123_abc', method: 'add', params: {a: 1, b: 2} }
+JsonRpcHandler.handle(request) { |method_name| ... }
+# => {"jsonrpc":"2.0","id":"request-123_abc","result":3}
+
+# Rejects potentially dangerous characters
+request = { jsonrpc: '2.0', id: '<script>alert("xss")</script>', method: 'add', params: {a: 1, b: 2} }
+JsonRpcHandler.handle(request) { |method_name| ... }
+# => {"jsonrpc":"2.0","id":null,"error":{"code":-32600,"message":"Invalid Request","data":"Request ID must match validation pattern, or be an integer or null"}}
+```
+
+You can customize the validation pattern by passing the `id_validation_pattern`
+parameter:
+
+```rb
+# Allow email-like IDs with a custom pattern
+custom_pattern = /\A[a-zA-Z0-9_.\-@]+\z/
+request = { jsonrpc: '2.0', id: 'user@example.com', method: 'add', params: {a: 1, b: 2} }
+
+JsonRpcHandler.handle(request, id_validation_pattern: custom_pattern) do |method_name|
+  # ...
+end
+
+# Also works with handle_json
+JsonRpcHandler.handle_json(request_json, id_validation_pattern: custom_pattern) do |method_name|
+  # ...
+end
+```
+
+To disable ID validation entirely (not recommended), pass
+`nil` as the pattern:
+
+```rb
+# Accepts any string
+JsonRpcHandler.handle(request, id_validation_pattern: nil) do |method_name|
+  # ...
+end
+```
+
 ## Development
 
 After checking out the repo:

data/lib/json_rpc_handler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonRpcHandler
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/json_rpc_handler.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'json_rpc_handler/version'
+require 'json'
 
 module JsonRpcHandler
   class Version
@@ -16,18 +17,31 @@ module JsonRpcHandler
     ParseError = -32700
   end
 
+  class Error < StandardError
+    attr_reader :code, :data
+
+    def initialize(code:, message:, data: nil)
+      super(message)
+      @code = code
+      @data = data
+    end
+  end
+
+  DEFAULT_ALLOWED_ID_CHARACTERS = /\A[a-zA-Z0-9_-]+\z/.freeze
+
   module_function
 
-  def handle(request, &method_finder)
+  def handle(request, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, on_error: nil, &method_finder)
+
     if request.is_a? Array
-      return error_response id: :unknown_id, error: {
+      return error_response id: :unknown_id, id_validation_pattern:, error: {
         code: ErrorCode::InvalidRequest,
         message: 'Invalid Request',
         data: 'Request is an empty array',
       } if request.empty?
 
       # Handle batch requests
-      responses = request.map { |req| process_request req, &method_finder }.compact
+      responses = request.map { |req| process_request req, id_validation_pattern:, on_error:, &method_finder }.compact
 
       # A single item is hoisted out of the array
       return responses.first if responses.one?
@@ -36,9 +50,9 @@ module JsonRpcHandler
       responses if responses.any?
     elsif request.is_a? Hash
       # Handle single request
-      process_request request, &method_finder
+      process_request request, id_validation_pattern:, on_error:, &method_finder
     else
-      error_response id: :unknown_id, error: {
+      error_response id: :unknown_id, id_validation_pattern:, error: {
         code: ErrorCode::InvalidRequest,
         message: 'Invalid Request',
         data: 'Request must be an array or a hash',
@@ -46,12 +60,12 @@ module JsonRpcHandler
     end
   end
 
-  def handle_json(request_json, &method_finder)
+  def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, on_error: nil, &method_finder)
     begin
       request = JSON.parse request_json, symbolize_names: true
-      response = handle request, &method_finder
+      response = handle request, id_validation_pattern:, on_error:, &method_finder
     rescue JSON::ParserError
-      response =error_response id: :unknown_id, error: {
+      response = error_response id: :unknown_id, id_validation_pattern:, error: {
         code: ErrorCode::ParseError,
         message: 'Parse error',
         data: 'Invalid JSON',
@@ -61,16 +75,16 @@ module JsonRpcHandler
     response.to_json if response
   end
 
-  def process_request(request, &method_finder)
+  def process_request(request, id_validation_pattern:, on_error: nil, &method_finder)
     id = request[:id]
 
     error = case
       when !valid_version?(request[:jsonrpc]) then 'JSON-RPC version must be 2.0'
-      when !valid_id?(request[:id]) then 'Request ID must be a string or an integer or null'
+      when !valid_id?(request[:id], id_validation_pattern) then 'Request ID must match validation pattern, or be an integer or null'
       when !valid_method_name?(request[:method]) then 'Method name must be a string and not start with "rpc."'
     end
 
-    return error_response id: :unknown_id, error: {
+    return error_response id: :unknown_id, id_validation_pattern:, error: {
       code: ErrorCode::InvalidRequest,
       message: 'Invalid Request',
       data: error,
@@ -80,7 +94,7 @@ module JsonRpcHandler
     params = request[:params]
 
     unless valid_params? params
-      return error_response id:, error: {
+      return error_response id:, id_validation_pattern:, error: {
         code: ErrorCode::InvalidParams,
         message: 'Invalid params',
         data: 'Method parameters must be an array or an object or null',
@@ -91,7 +105,7 @@ module JsonRpcHandler
       method = method_finder.call method_name
 
       if method.nil?
-        return error_response id:, error: {
+        return error_response id:, id_validation_pattern:, error: {
           code: ErrorCode::MethodNotFound,
           message: 'Method not found',
           data: method_name,
@@ -101,11 +115,22 @@ module JsonRpcHandler
       result = method.call params
 
       success_response id:, result:
+    rescue Error => e
+      error_response id:, id_validation_pattern:, error: {
+        code: e.code,
+        message: e.message,
+        data: e.data,
+      }
     rescue StandardError => e
-      error_response id:, error: {
+      begin
+        on_error&.call(e, { id:, method: method_name })
+      rescue StandardError
+        # Reporter errors must not change the response.
+      end
+
+      error_response id:, id_validation_pattern:, error: {
         code: ErrorCode::InternalError,
         message: 'Internal error',
-        data: e.message,
       }
     end
   end
@@ -114,8 +139,12 @@ module JsonRpcHandler
     version == Version::V2_0
   end
 
-  def valid_id?(id)
-    id.is_a?(String) || id.is_a?(Integer) || id.nil?
+
+  def valid_id?(id, pattern = nil)
+    return true if id.nil? || id.is_a?(Integer)
+    return false unless id.is_a?(String)
+
+    pattern ? id.match?(pattern) : true
   end
 
   def valid_method_name?(method)
@@ -134,10 +163,10 @@ module JsonRpcHandler
     } unless id.nil?
   end
 
-  def error_response(id:, error:)
+  def error_response(id:, id_validation_pattern:, error:)
     {
       jsonrpc: Version::V2_0,
-      id: valid_id?(id) ? id : nil,
+      id: valid_id?(id, id_validation_pattern) ? id : nil,
       error: error.compact,
     } unless id.nil?
   end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: json_rpc_handler
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ates Goral
 bindir: bin
 cert_chain: []
-date: 2025-03-12 00:00:00.000000000 Z
+date: 2026-11-10 00:00:00.000000000 Z
 dependencies: []
 email:
 - ates.goral@shopify.com
@@ -20,13 +20,13 @@ files:
 - README.md
 - lib/json_rpc_handler.rb
 - lib/json_rpc_handler/version.rb
-homepage: https://github.com/Shopify/json_rpc_handler
+homepage: https://github.com/Shopify/json-rpc-handler
 licenses:
 - MIT
 metadata:
-  bug_tracker_uri: https://github.com/Shopify/json_rpc_handler/issues
-  changelog_uri: https://github.com/Shopify/json_rpc_handler/blob/main/CHANGELOG.md
-  source_code_uri: https://github.com/Shopify/json_rpc_handler
+  bug_tracker_uri: https://github.com/Shopify/json-rpc-handler/issues
+  changelog_uri: https://github.com/Shopify/json-rpc-handler/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/Shopify/json-rpc-handler
   allowed_push_host: https://rubygems.org
   rubygems_mfa_required: 'true'
 rdoc_options: []
@@ -43,7 +43,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.7
 requirements: []
-rubygems_version: 3.6.5
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A spec-compliant JSON-RPC 2.0 handler
 test_files: []