json_rpc_handler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4e714ed8007b1495db68aef79e5a649c63b8209e1b7600c405f8611ecadd16bd
+  data.tar.gz: 3b27a986d66f12f2919e8439b3e645e3c3b2e7136d5175e11f9c1e498f07b28c
+SHA512:
+  metadata.gz: d385890032cb7d7bb6791292aa42392dbad2d320904364c3651a55f0c6f99a396200d481c72d30d7b29786ac6f456a9d33a4a5dcd66bce0b4768b0171eba16b8
+  data.tar.gz: 25034b8fe5653f04e692fd555323e61ac44af0b7e90eab7c2ef6947288e89fb37ac874b177980d4c76ee143c64be08056f0317cdb94a128d7b3b96d2c5781a9f

data/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025-present, Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,113 @@
+# json_rpc_handler
+
+A lightweight, fully spec-compliant [JSON-RPC 2.0][1] handler.
+
+It only deals with the parsing and handling of JSON-RPC requests, producing
+appropriate JSON-RPC responses.
+
+It does not deal with the transport layer (e.g. HTTP, WebSockets, etc.)
+
+[1]: https://www.jsonrpc.org/specification
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json_rpc_handler'
+```
+
+And then execute:
+
+```sh
+bundle
+```
+
+Or install it yourself as:
+
+```sh
+gem install json_rpc_handler
+```
+
+## Usage
+
+If you already have a request object parsed from JSON, you can use the `handle`
+method. Pass a block to the `handle` call to look up methods by name:
+
+```rb
+require 'json_rpc_handler'
+
+request = {
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'add',
+  params: {a: 1, b: 2},
+}
+
+result = JsonRpcHandler.handle(request) do |method_name|
+  case method_name
+  when 'add'
+    ->(params) { params[:a] + params[:b] }
+  end
+end
+
+puts result.to_json
+# {"jsonrpc":"2.0","id":1,"result":3}
+```
+
+Returning a `nil` from the method lookup block will result in a method not found
+error.
+
+If the request JSON is not already parsed, you can use the `handle_json` method:
+
+```rb
+request_json = '{"jsonrpc": "2.0","id":1,"method":"add","params":{"a":1,"b":2}}'
+
+result_json = JsonRpcHandler.handle_json(request_json) do |method_name|
+  case method_name
+  when 'add'
+    ->(params) { params[:a] + params[:b] }
+  end
+end
+
+puts result_json
+# {"jsonrpc":"2.0","id":1,"result":3}
+```
+
+A `nil` from `handle` or `handle_json` means "no content" - either the
+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).
+
+## Development
+
+After checking out the repo:
+
+1. Run `bundle` to install dependencies.
+2. Run `rake test` to run the tests, including code coverage.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/Shopify/json-rpc-handler. This project is intended to be a
+safe, welcoming space for collaboration, and contributors are expected to adhere
+to the [Contributor Covenant][2] code of conduct. Read more about contributing
+[here][3].
+
+[2]: https://contributor-covenant.org
+[3]: https://github.com/Shopify/json-rpc-handler/blob/main/CONTRIBUTING.md
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][4].
+
+[4]: https://opensource.org/licenses/MIT
+
+## Code of Conduct
+
+Everyone interacting in this repository is expected to follow the
+[Code of Conduct][5].
+
+[5]: https://github.com/Shopify/json-rpc-handler/blob/main/CODE_OF_CONDUCT.md

data/lib/json_rpc_handler/version.rb

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

data/lib/json_rpc_handler.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require 'json_rpc_handler/version'
+
+module JsonRpcHandler
+  class Version
+    V1_0 = '1.0'
+    V2_0 = '2.0'
+  end
+
+  class ErrorCode
+    InvalidRequest = -32600
+    MethodNotFound = -32601
+    InvalidParams = -32602
+    InternalError = -32603
+    ParseError = -32700
+  end
+
+  module_function
+
+  def handle(request, &method_finder)
+    if request.is_a? Array
+      return error_response id: :unknown_id, 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
+
+      # A single item is hoisted out of the array
+      return responses.first if responses.one?
+
+      # An empty array yields nil
+      responses if responses.any?
+    elsif request.is_a? Hash
+      # Handle single request
+      process_request request, &method_finder
+    else
+      error_response id: :unknown_id, error: {
+        code: ErrorCode::InvalidRequest,
+        message: 'Invalid Request',
+        data: 'Request must be an array or a hash',
+      }
+    end
+  end
+
+  def handle_json(request_json, &method_finder)
+    begin
+      request = JSON.parse request_json, symbolize_names: true
+      response = handle request, &method_finder
+    rescue JSON::ParserError
+      response =error_response id: :unknown_id, error: {
+        code: ErrorCode::ParseError,
+        message: 'Parse error',
+        data: 'Invalid JSON',
+      }
+    end
+
+    response.to_json if response
+  end
+
+  def process_request(request, &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_method_name?(request[:method]) then 'Method name must be a string and not start with "rpc."'
+    end
+
+    return error_response id: :unknown_id, error: {
+      code: ErrorCode::InvalidRequest,
+      message: 'Invalid Request',
+      data: error,
+    } if error
+
+    method_name = request[:method]
+    params = request[:params]
+
+    unless valid_params? params
+      return error_response id:, error: {
+        code: ErrorCode::InvalidParams,
+        message: 'Invalid params',
+        data: 'Method parameters must be an array or an object or null',
+      }
+    end
+
+    begin
+      method = method_finder.call method_name
+
+      if method.nil?
+        return error_response id:, error: {
+          code: ErrorCode::MethodNotFound,
+          message: 'Method not found',
+          data: method_name,
+        }
+      end
+
+      result = method.call params
+
+      success_response id:, result:
+    rescue StandardError => e
+      error_response id:, error: {
+        code: ErrorCode::InternalError,
+        message: 'Internal error',
+        data: e.message,
+      }
+    end
+  end
+
+  def valid_version?(version)
+    version == Version::V2_0
+  end
+
+  def valid_id?(id)
+    id.is_a?(String) || id.is_a?(Integer) || id.nil?
+  end
+
+  def valid_method_name?(method)
+    method.is_a?(String) && !method.start_with?('rpc.')
+  end
+
+  def valid_params?(params)
+    params.nil? || params.is_a?(Array) || params.is_a?(Hash)
+  end
+
+  def success_response(id:, result:)
+    {
+      jsonrpc: Version::V2_0,
+      id:,
+      result:,
+    } unless id.nil?
+  end
+
+  def error_response(id:, error:)
+    {
+      jsonrpc: Version::V2_0,
+      id: valid_id?(id) ? id : nil,
+      error: error.compact,
+    } unless id.nil?
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: json_rpc_handler
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ates Goral
+bindir: bin
+cert_chain: []
+date: 2025-03-12 00:00:00.000000000 Z
+dependencies: []
+email:
+- ates.goral@shopify.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE.md
+- README.md
+- lib/json_rpc_handler.rb
+- lib/json_rpc_handler/version.rb
+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
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.3.7
+requirements: []
+rubygems_version: 3.6.5
+specification_version: 4
+summary: A spec-compliant JSON-RPC 2.0 handler
+test_files: []