Skip to content

ruby-amqp/rabbitmq_http_api_client

Repository files navigation

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.

About

RabbitMQ HTTP API client for Ruby

Topics

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Contributors 25