bunny

Bunny, a Ruby RabbitMQ Client

Bunny is a RabbitMQ client that focuses on ease of use. It is feature complete, supports all recent RabbitMQ features and does not have any heavyweight dependencies.

I Know What RabbitMQ and Bunny are, How Do I Get Started?

Right here!

What is Bunny Good For?

One can use Bunny to make Ruby applications interoperate with other applications (both built in Ruby and not). Complexity and size may vary from simple work queues to complex multi-stage data processing workflows that involve many applications built with all kinds of technologies.

Specific examples:

• Events collectors, metrics & analytics applications can aggregate events produced by various applications (Web and not) in the company network.

• A Web application may route messages to a Java app that works with SMS delivery gateways.

• MMO games can use flexible routing RabbitMQ provides to propagate event notifications to players and locations.

• Price updates from public markets or other sources can be distributed between interested parties, from trading systems to points of sale in a specific geographic region.

• Content aggregators may update full-text search and geospatial search indexes by delegating actual indexing work to other applications over RabbitMQ.

• Companies may provide streaming/push APIs to their customers, partners or just general public.

• Continuous integration systems can distribute builds between multiple machines with various hardware and software configurations using advanced routing features of RabbitMQ.

• An application that watches updates from a real-time stream (be it markets data or Twitter stream) can propagate updates to interested parties, including Web applications that display that information in the real time.

Ports to Other Languages

Bunny has inspired a number of other RabbitMQ (AMQP 0-9-1) client libraries that closely follow its feature set and API shape, form and ergonomics.

• Swift 6

Supported Ruby Versions

Modern Bunny versions support

• CRuby 3.2 through 4.0 (inclusive)
• TruffleRuby

For environments that use TLS, Bunny expects Ruby installations to use a recent enough OpenSSL version that includes support for TLS 1.3.

JRuby

Bunny no longer supports JRuby.

JRuby users should use March Hare, which has a similar API and is built on top of the RabbitMQ Java client specifically for JRuby.

Supported RabbitMQ Versions

Modern Bunny releases target currently community supported RabbitMQ release series.

The protocol implemented by Bunny was first introduced in RabbitMQ 2.0 and has evolved via extensions and with next to no breaking changes, so all key Bunny operations can be used with a wide range of RabbitMQ versions, accounting for the few potentially breaking changes they may introduce, e.g. the idempotency of queue.delete operations.

Change Log

Change log.

Installation & Bundler Dependency

Most Recent Release

Bundler Dependency

To use Bunny in a project managed with Bundler:

gem "bunny", ">= 3.0"

With Rubygems

To install Bunny with RubyGems:

gem install bunny

Quick Start

Below is a small snippet that demonstrates how to publish and synchronously consume ("pull API") messages with Bunny.

For a 15 minute tutorial using more practical examples, see Getting Started with RabbitMQ and Ruby using Bunny.

…

Documentation

Getting Started

For a 15 minute tutorial using more practical examples, see Getting Started with RabbitMQ and Ruby using Bunny.

Guides

Bunny documentation guides are under docs/guides in this repository:

• Queues and Consumers
• Exchanges and Publishers
• AMQP 0.9.1 Model Explained
• Connecting to RabbitMQ
• Error Handling and Recovery
• TLS/SSL Support
• Bindings
• Using RabbitMQ Extensions with Bunny
• Durability and Related Matters

Some highly relevant RabbitMQ documentation guides:

• Connections
• Channels
• Queues
• Quorum queues
• Streams (Bunny can perform basic operations on streams even though it does not implement the RabbitMQ Stream protocol)
• Publishers
• Consumers
• Data safety: publisher and consumer Confirmations
• Production Checklist

API Reference

Bunny API Reference.

Community and Getting Help

Mailing List

Please use GitHub Discussions for questions.

GitHub issues should be used for specific, well understood, actionable maintainers and contributors can work on.

We encourage you to keep an eye on RabbitMQ Discussions, join the RabbitMQ mailing list and the RabbitMQ Discord server.

Reporting Issues

If you find a bug you understand well, poor default, incorrect or unclear piece of documentation, or missing feature, please file an issue on GitHub.

Please use Bunny's mailing list for questions, investigations, and discussions. GitHub issues should be used for specific, well understood, actionable maintainers and contributors can work on.

When filing an issue, please specify which Bunny and RabbitMQ versions you are using, provide recent RabbitMQ log file contents, full exception stack traces, and steps to reproduce (or failing test cases).

Other Ruby RabbitMQ Clients

The other widely used Ruby RabbitMQ client is March Hare (JRuby-only). It's a mature library that requires RabbitMQ 3.3.x or later.

Contributing

See CONTRIBUTING.md for more information about running various test suites.

License

Released under the MIT license.