https://github.com/wilsonsilva/jsonrpc-middleware
Ruby implementation of the JSON-RPC 2.0 protocol for Rack-based applications.
https://github.com/wilsonsilva/jsonrpc-middleware
json-rpc json-rpc2 jsonrpc jsonrpc2 middleware rack rails ruby ruby-gem ruby-on-rails
Last synced: 4 months ago
JSON representation
Ruby implementation of the JSON-RPC 2.0 protocol for Rack-based applications.
- Host: GitHub
- URL: https://github.com/wilsonsilva/jsonrpc-middleware
- Owner: wilsonsilva
- License: mit
- Created: 2025-05-22T21:28:59.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-17T05:37:42.000Z (10 months ago)
- Last Synced: 2025-10-07T21:55:38.570Z (9 months ago)
- Topics: json-rpc, json-rpc2, jsonrpc, jsonrpc2, middleware, rack, rails, ruby, ruby-gem, ruby-on-rails
- Language: Ruby
- Homepage: https://jsonrpc-middleware.com
- Size: 249 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
[](https://badge.fury.io/rb/jsonrpc-middleware)
[](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
[](https://qlty.sh/gh/wilsonsilva/projects/jsonrpc-middleware)
A Rack middleware implementing the JSON-RPC 2.0 protocol that integrates easily with all Rack-based applications (Rails, Sinatra, Hanami, etc).
## Table of contents
- [Key features](#-key-features)
- [Installation](#-installation)
- [Quickstart](#-quickstart)
- [Examples](#-examples)
- [Documentation](#-documentation)
- [Development](#-development)
* [Type checking](#-type-checking)
- [Contributing](#-contributing)
- [License](#-license)
- [Code of Conduct](#-code-of-conduct)
## 🔑 Key features
- **Spec-compliant**: Fully implements the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/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
## 🏗️ Architecture
The gem integrates seamlessly into your Rack-based application:
```mermaid
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
```
## 📦 Installation
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
## ⚡️ Quickstart
Create a file called `config.ru` and run `bundle exec rackup`:
```ruby
# 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](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md).
## 📚 Documentation
- [YARD documentation](https://rubydoc.info/gems/jsonrpc-middleware)
## 📜 Examples
Examples for the most common Rack-based applications, including Rails and Sinatra can be found [here](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/examples/README.md)
## 🔨 Development
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](https://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
```
### 🧪 Type checking
This gem leverages [RBS](https://github.com/ruby/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](https://github.com/soutaro/steep)
with the command `bundle exec steep check`.
## 🐞 Issues & Bugs
If you find any issues or bugs, please report them [here](https://github.com/wilsonsilva/jsonrpc-middleware/issues), I will be happy
to have a look at them and fix them as soon as possible.
## 🤝 Contributing
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](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/CODE_OF_CONDUCT.md).
## 📜 License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## 👔 Code of Conduct
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](https://github.com/wilsonsilva/jsonrpc-middleware/blob/main/CODE_OF_CONDUCT.md).