A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates easily with all Rack-based applications (Rails, Sinatra, Hanami, etc).

• Key features
• Installation
• Quickstart
• Examples
• Documentation
• Development
  • Type checking
• Contributing
• License
• Code of Conduct

• Spec-compliant: Fully implements the JSON-RPC 2.0 specification
• Rack middleware integration: Seamlessly integrates with Rack applications (Rails, Sinatra, Hanami, etc)
• Support for all request types: Handles single requests, notifications, and batch requests
• Rails routing DSL: Elegant routing DSL for Rails applications with support for namespaces and batch handling
• Error handling: Comprehensive error handling with standard JSON-RPC error responses
• Request validation: Define request parameter specifications and validations
• Helpers: Convenient helper methods to simplify request and response processing
• Optimized JSON handling: Uses MultiJSON to automatically select the fastest available JSON library

The gem integrates seamlessly into your Rack-based application:

block-beta columns 4 App["Your app"]:4 Rails:1 Sinatra:1 RackApp["Other Rack-compatible framework"]:2 Middleware["JSON-RPC Middleware"]:4 Rack["Rack"]:4 HTTP["HTTP"]:4 classDef middlewareStyle fill:#ff6b6b,stroke:#d63031,stroke-width:2px,color:#fff class Middleware middlewareStyle 

Install the gem and add to the application's Gemfile by executing:

$ bundle add jsonrpc-middleware 

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install jsonrpc-middleware 

Create a file called config.ru and run bundle exec rackup:

# frozen_string_literal: true require 'bundler/inline' gemfile do source 'https://rubygems.org' gem 'jsonrpc-middleware', require: 'jsonrpc' gem 'puma' gem 'rack' gem 'rackup' end JSONRPC.configure do procedure(:add, allow_positional_arguments: true) do params do required(:addends).filled(:array) required(:addends).value(:array).each(type?: Numeric) end rule(:addends) do key.failure('must contain at least one addend') if value.empty? end end end class App include JSONRPC::Helpers def call(env) @env = env if jsonrpc_request? sum = add(jsonrpc_request.params) jsonrpc_response(sum) elsif jsonrpc_notification? add(jsonrpc_notification.params) jsonrpc_notification_response else results = add_in_batches(jsonrpc_batch) jsonrpc_batch_response(results) end end private def add(params) addends = params.is_a?(Array) ? params : params['addends'] # Handle positional and named arguments addends.sum end def add_in_batches(batch) batch.process_each { |request_or_notification| add(request_or_notification.params) } end end use JSONRPC::Middleware run App.new

This will give you a fully-featured JSON-RPC server, capable of:

• Handling JSON-RPC requests, notifications and batches
• Validating the allowed JSON-RPC methods (e.g. allow only add)
• Validating the JSON-RPC method parameters (e.g. allow only non-empty arrays of numbers)
• Accept positional and named parameters (params: [5, 5], params: { addends: [5, 5] })
• Respond successfully or erroneously, according to the specification

For more advanced setups, or other frameworks such as Rails or Sinatra, check the examples.

• YARD documentation

Examples for the most common Rack-based applications, including Rails and Sinatra can be found here

After checking out the repo, run bin/setup to install dependencies.

To install this gem onto your local machine, run bundle exec rake install.

You can also run bin/console for an interactive prompt that will allow you to experiment.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

The health and maintainability of the codebase is ensured through a set of Rake tasks to test, lint and audit the gem for security vulnerabilities and documentation:

rake build # Build jsonrpc-middleware.gem into the pkg directory rake build:checksum # Generate SHA512 checksum of jsonrpc-middleware.gem into the checksums directory rake bundle:audit:check # Checks the Gemfile.lock for insecure dependencies rake bundle:audit:update # Updates the bundler-audit vulnerability database rake clean # Remove any temporary products rake clobber # Remove any generated files rake coverage # Run spec with coverage rake examples:bundle_install # Run bundle install on all example folders (useful after updating the gem version) rake install # Build and install jsonrpc-middleware.gem into system gems rake install:local # Build and install jsonrpc-middleware.gem into system gems without network access rake qa # Test, lint and perform security and documentation audits rake release[remote] # Create tag v0.1.0 and build and push jsonrpc-middleware-0.1.0.gem to rubygems.org rake rubocop # Run RuboCop rake rubocop:autocorrect # Autocorrect RuboCop offenses (only when it's safe) rake rubocop:autocorrect_all # Autocorrect RuboCop offenses (safe and unsafe) rake spec # Run RSpec code examples rake verify_measurements # Verify that yardstick coverage is at least 100% rake yard # Generate YARD Documentation rake yard:format # Format YARD documentation rake yard:junk # Check the junk in your YARD Documentation rake yardstick_measure # Measure docs in lib/**/*.rb with yardstick 

This gem leverages RBS, a language to describe the structure of Ruby programs. It is used to provide type checking and autocompletion in your editor. Run bundle exec typeprof FILENAME to generate an RBS definition for the given Ruby file. And validate all definitions using Steep with the command bundle exec steep check.

If you find any issues or bugs, please report them here, I will be happy to have a look at them and fix them as soon as possible.

Bug reports and pull requests are welcome on GitHub at https://github.com/wilsonsilva/jsonrpc-middleware. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the JSONRPC::Middleware Ruby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.