Skip to content
JSON-RPC over RabbitMQ
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


Build Status

An implementation of JSON-RPC over RabbitMQ through the Bunny library. Provides both a client and server.

A group of baby bunnies is called a fluffle.


Both the client and server implementations should be thread-safe, as their behavior is implemented on top of the excellent concurrent-ruby gem's data structures.

  • Client: Thread-safe client that can perform multiple requests concurrently
  • Server: Single or multi-threaded server (one request/response per thread)
  • Server: Easy-to-use built-in handlers and straightforward API for building custom handlers

Note: Fluffle uses JSON-RPC as a transfer format to structure requests and responses. However, due to some of the limitations imposed by AMQP, it cannot implement the complete set of behaviors in the JSON-RPC protocol. The most substantial of these limitations is that batch requests are not supported.


See the examples directory.

The server provides a few options for handling RPC requests:

  • Dispatcher: dispatcher.handle('upcase') { |str| str.upcase }
  • Delegator: delegate will receive the #upcase message with a single argument (the string)
  • Custom: any handler needs to implement the API described in Fluffle::Handlers::Base

Basic server and client

A server has two basic requirements: the URL of a RabbitMQ server to connect to and one or more queues to drain (with a handler for each queue).

Below is a basic server providing an upcase method to return the upper cased version of its argument:

require 'fluffle'

server = url: 'amqp://localhost'

server.drain do |dispatcher|
  dispatcher.handle('upcase') { |str| str.upcase }


This example relies on a couple features of Server#drain:

  1. By default it will drain the default queue.
  2. You can provide a block to the method to have it set up a Dispatcher handler and pass that in to the block.

And client to call that upcase method looks like:

client = url: 'amqp://localhost' 'upcase', ['Hello world!']

Response meta-data

The server adds an additional meta field to the response object with meta-data about how the request was handled. Currently the only entry in the meta object is the float handler_duration which is duration in seconds that was spent exclusively processing the handler.

// Example successful response with meta-data (6ms spent in handler)
  "jsonrpc": "2.0",
  "id": "123",
  "result": "baz",
  "meta": {"handler_duration": 0.006}

// Example error response with meta-data
  "jsonrpc": "2.0",
  "id": "123",
  "error": {"code": -32601, "message": "Method not found"},
  "meta": {"handler_duration": 0.007}


Released under the MIT license, see LICENSE for details.

You can’t perform that action at this time.