Project

Motivations

streadway/amqp, the sanctioned RabbitMQ driver for Go, is an excellent library with a great API but limited scope. It offers a full implementation of the AMQP spec, but comes with very few additional quality-of-life features.

From it’s documentation:

Goals

    Provide a functional interface that closely represents the AMQP 0.9.1 model
    targeted to RabbitMQ as a server. This includes the minimum necessary to
    interact the semantics of the protocol.

Things not intended to be supported:

    Auto reconnect and re-synchronization of client and server topologies.

    Reconnection would require understanding the error paths when the topology
    cannot be declared on reconnect. This would require a new set of types and code
    paths that are best suited at the call-site of this package. AMQP has a dynamic
    topology that needs all peers to agree. If this doesn't happen, the behavior
    is undefined. Instead of producing a possible interface with undefined
    behavior, this package is designed to be simple for the caller to implement the
    necessary connection-time topology declaration so that reconnection is trivial
    and encapsulated in the caller's application code.

Without a supplied way to handle reconnections, bespoke solutions abound.

Most of these solutions are overly-fitted to a specific problem (consumer vs producer or involve domain-specific logic), are prone to data races (can you spot them in the first link?), are cumbersome to inject into a production code (do we abort the business logic on an error or try to recover in-place?), and have bugs (each solution has its own redial bugs rather than finding them in a single lib where fixes can benefit everyone and community code coverage is high).

Nome of this is meant to disparage the above solutions – they likely work great in the code they were created for – but they point to a need that is not being filled by the sanctioned driver. The nature of the default *Channel API encourages solutions that are ill-suited to stateless handlers OR require you to handle retries every place you must interact with the broker. Such implementation details can be annoying when writing higher-level business logic and can lead to either unnecessary error returns, bespoke solutions in every project, or messy calling code at sites which need to interact with an AMQP broker.

Roger, Rabbit is inspired by aio-pika’s robust connections and channels, which abstract away connection management with an identical API to their non-robust counterparts, allowing robust AMQP broker interactions with minimal fuss and very few limitations.

Note

Roger, Rabbit is not meant to supplant streadway/amqp (We build on top of it!), but an extension with quality-of-life features. Roger, Rabbit would no be possible without the amazing groundwork laid down by streadway/amqp.

Goals

The goals of the Roger, Rabbit package are as follows:

• Offer a Drop-in Replacement for streadway/amqp: APIs may be extended (adding fields to amqp.Config or additional methods to *amqp.Channel, for instance) but must not break existing code unless absolutely necessary.

• Add as few Additional Error Paths as Possible: Errors may be extended with additional information concerning disconnect scenarios, but new error type returns from *Connection or *amqp.Channel should be an absolute last resort.

• Be Highly Extensible: Roger, Rabbit seeks to offer a high degree of extensibility via features like middleware, in an effort to reduce the balkanization of amqp client solutions.

Current Limitations & Warnings

• Performance: Roger, Rabbit has not been extensively benchmarked against streadway/amqp. To see preliminary benchmarks, take a look at the next section.

• Transaction Support: Roger, Rabbit does not currently support amqp Transactions, as the author does not use them. Draft PR’s with possible implementations are welcome!

• Reliability: While the author uses this library in production, it is still early days, and more battle-testing will be needed before this library is promoted to version 1.0. PR’s are welcome for Bug Fixes, code coverage, or new features.

Benchmarks

Because of Roger, Rabbit’s middleware-driven design, some overhead is expected vs streadway proper. However, initial benchmarks are promising, and show only minimal impact. For most applications, the overhead cost is likely worth the cost for ease of development and flexibility.

Still, if absolute peak throughput is critical to an application, a less general and more tailored approach may be warranted.

Benchmarks can be found in ./amqp/benchmark_test.go.

Machine: Intel(R) Core(TM) i9-8950HK CPU @ 2.90GHz || Calculated by taking the fastest of four runs.

OPERATION	LIB	EXECUTIONS	NS/OP	COMPARISON
QueueInspect	sw	2,838	812,594	–
–	rr	2,470	813,269	+0.1%
Publish	sw	7,4559	28,882	–
–	rr	7,0665	30,031	+4.0%
Publish & Confirm	sw	3,4528	59,703	–
–	rr	3,5481	62,198	+4.2%
Consume (QoS 100)	sw	75,433	27,206	–
–	rr	73,957	29,846	+9.7%

Run with the following command:

go test -p 1 -count 4 -bench=Comparison -run=NoTests -benchtime=2s ./...