RabbitMQ HTTP API Client for Ruby

This gem is a RabbitMQ HTTP API client for Ruby. It supports

• Getting cluster overview information
• Getting cluster nodes status (# file descriptors used, RAM consumption and so on)
• Getting information about exchanges, queues, bindings
• Closing client connections
• Getting information about vhosts, users, permissions
• Getting information about enabled plugins, protocols, their ports, etc
• Managing vhosts, users, permissions

and will support more HTTP API features in the future

• Publishing messages via HTTP
• Operations on components/extensions
• Operations on federation policies

Supported Ruby Versions

• CRuby 2.7 through 3.x
• JRuby 9K

Supported RabbitMQ Versions

This library targets RabbitMQ release series covered by community support.

All versions require RabbitMQ Management UI plugin to be installed and enabled.

Installation

Add this line to your application's Gemfile to use the latest version of this library:

# Depends on Faraday 2.x
gem 'rabbitmq_http_api_client', '>= 3.0.0'

If you absolutely must use Faraday 1.x, use the 2.x series:

# Depends on Faraday 1.x.
# Consider using 3.0.0 and later versions.
gem 'rabbitmq_http_api_client', '>= 2.2.0'

And then execute:

bundle install

Or install it manually with:

gem install rabbitmq_http_api_client

Usage

To require the client:

require "rabbitmq/http/client"

Specifying Endpoint and Credentials

Use RabbitMQ::HTTP::Client#connect to specify RabbitMQ HTTP API endpoint (e.g. http://127.0.0.1:15672) and credentials:

require "rabbitmq/http/client"

endpoint = "http://127.0.0.1:15672"
client = RabbitMQ::HTTP::Client.new(endpoint, username: "guest", password: "guest")

Alternatively, credentials can be specified in the endpoint URI:

require "rabbitmq/http/client"

client = RabbitMQ::HTTP::Client.new("http://guest:guest@127.0.0.1:15672")

Client API Design Overview

All client methods return arrays or hash-like structures that can be used like JSON, via Hash#[] or regular method access:

r = client.overview

puts r[:rabbitmq_version]
puts r.erlang_version

Accessing Management API with HTTPS

All additional options other than :username and :password are passed to Faraday::Connection. So, it is possible to use HTTPS like so:

c = RabbitMQ::HTTP::Client.new("https://127.0.0.1:15672/", username: "guest", password: "guest", ssl: {
  client_cer: ...,
  client_key: ...,
  ca_file:    ...,
  ca_path:    ...,
  cert_store: ...
})

Or, if you have good reasons to do so, disable peer verification:

c = RabbitMQ::HTTP::Client.new("https://127.0.0.1:15672/", username: "guest", password: "guest", ssl: {
  verify: false
})

Node and Cluster Status

# Get cluster information overview
h     = client.overview

# List cluster nodes with detailed status info for each one of them
nodes = client.list_nodes
n     = nodes.first
puts n.mem_used
puts n.run_queue

# Get detailed status of a node
n     = client.node_info("rabbit@localhost")
puts n.disk_free
puts n.proc_used
puts n.fd_total

# Get Management Plugin extension list
xs    = client.list_extensions

# List all the entities (vhosts, queues, exchanges, bindings, users, etc)
defs  = client.list_definitions

Operations on Connections

# List all connections to a node
conns = client.list_connections
conn  = conns.first
puts conn.name
puts conn.client_properties.product

# Get a connection information by name
conns = client.list_connections
conn  = client.connection_info(conns.first.name)
puts conn.name
puts conn.client_properties.product

# Forcefully close a connection
conns = client.list_connections
client.close_connection(conns.first.name)

Operations on Channels

# List all channels
channs = client.list_channels
ch     = channs.first
puts ch.number
puts ch.prefetch_count
puts ch.name


# Get a channel information by name
conns = client.list_channels
conn  = client.channel_info(conns.first.name)
puts conn.name

Operations on Exchanges

# List all exchanges in the cluster
xs = client.list_exchanges
x  = xs.first

puts x.type
puts x.name
puts x.vhost
puts x.durable
puts x.auto_delete

# List all exchanges in a vhost
xs = client.list_exchanges("myapp.production")
x  = xs.first

puts x.type
puts x.name
puts x.vhost

# Get information about an exchange in a vhost
x  = client.exchange_info("/", "log.events")

puts x.type
puts x.name
puts x.vhost

# List all exchanges in a vhost for which an exchange is the source
client.list_bindings_by_source("/", "log.events")

# List all exchanges in a vhost for which an exchange is the destination
client.list_bindings_by_destination("/", "command.handlers.email")

Operations on Queues

# List all queues in a node
qs = client.list_queues
q  = qs.first

puts q.name
puts q.auto_delete
puts q.durable
puts q.backing_queue_status
puts q.active_consumers


# Get information about a queue
client.queue_info("/", "collector1.megacorp.local")

# Declare a queue
client.declare_queue("/", "collector1.megacorp.local", :durable => false, :auto_delete => true)

# Delete a queue
client.delete_queue("/", "collector1.megacorp.local")

# List bindings for a queue
bs = client.list_queue_bindings("/", "collector1.megacorp.local")

# Purge a queue
client.purge_queue("/", "collector1.megacorp.local")

# Fetch messages from a queue
ms = client.get_messages("/", "collector1.megacorp.local", :count => 10, :requeue => false, :encoding => "auto")
m  = ms.first

puts m.properties.content_type
puts m.payload
puts m.payload_encoding

Operations on Bindings

# List all bindings
bs = client.list_bindings
b  = bs.first

puts b.destination
puts b.destination_type
puts b.source
puts b.routing_key
puts b.vhost

# List all bindings in a vhost
bs = client.list_bindings("/")

# List all bindings between an exchange and a queue
bs = client.list_bindings_between_queue_and_exchange("/", "collector1.megacorp.local", "log.events")

Operations on Vhosts

# List all vhosts
vs = client.list_vhosts
v  = vs.first

puts v.name
puts v.tracing

# Get information about a vhost
v  = client.vhost_info("/")

puts v.name
puts v.tracing

# Create a vhost
client.create_vhost("myapp.staging")

# Delete a vhost
client.delete_vhost("myapp.staging")

Managing Users

# List all users
us = client.list_users
u  = us.first

puts u.name
puts u.password_hash
puts u.tags

# Get information about a user
u  = client.user_info("guest")

puts u.name
puts u.password_hash
puts u.tags

# Update information about a user
client.update_user("myapp", :tags => "services,policymaker,management", :password => "t0ps3krEt")

# Delete a user
client.delete_user("myapp")

Managing Permissions

# List all permissions
ps = client.list_permissions

puts p.user
puts p.read
puts p.write
puts p.configure
puts p.vhost

# List all permissions in a vhost
ps = client.list_permissions("/")

puts p.user
puts p.read
puts p.write
puts p.configure
puts p.vhost

# List permissions of a user
ps = client.user_permissions("guest")

# List permissions of a user in a vhost
ps = client.list_permissions_of("/", "guest")

# Update permissions of a user in a vhost
ps = client.update_permissions_of("/", "guest", :write => ".*", :read => ".*", :configure => ".*")

# Clear permissions of a user in a vhost
ps = client.clear_permissions_of("/", "guest")

Running Tests

Before running the test suites, run a script that will set up the local node:

export RUBY_RABBITMQ_HTTP_API_CLIENT_RABBITMQCTL="/path/to/sbin/rabbitmqctl"
export RUBY_RABBITMQ_HTTP_API_CLIENT_RABBITMQ_PLUGINS="/path/to/sbin/rabbitmq-plugins"

./bin/ci/before_build.sh

To run all specs:

bundle install
bundle exec rspec -cfd spec

The test suite assumes that RabbitMQ is running locally with stock settings and rabbitmq-management plugin enabled.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new pull request

License & Copyright

Double-licensed under the MIT and the Mozilla Public License 2.0 (same as RabbitMQ).

(c) Michael S. Klishin, 2012-2024.