Ruby AMQP gem documentation guides

This Documentation Has Moved to rubyamqp.info

amqp gem documentation guides are now hosted on rubyamqp.info.

Which versions of the amqp gem do the guides cover?

These guides cover v0.8.0.RC14 and later of the Ruby amqp gem.

Documentation structure and how to read these guides

We recommend that you read the documentation guides in the order that they are listed. The Getting Started guide is written as a tutorial that describes several typical applications and their problem scope, then provides full code examples and finally breaks them down into smaller pieces that are explained in detail.

Once you are finished with the tutorial, reading the other guides in sequence will gradually explain all of the AMQP 0.9.1 features that are relevant to application developers, including application design concerns and common practices. At present, some guides are yet to be written but most of the content is concentrated in just 3-4 guides that are about 80% finished and provide plenty of examples.

Here is a summary of guides and their content:

Getting Started with Ruby amqp gem and RabbitMQ: Walks you through gem installation and 3 applications that demonstrate what AMQP has to offer. Explains how amqp gem should be integrated into rich object-oriented Ruby programs.
AMQP 0.9.1 Model Explained: A simple, 2 page long introduction to the AMQP 0.9.1 model, focusing on what purpose individual features have. Reading other documentation guides will be easier when you are armed with this knowledge: a lot of the AMQP & RabbitMQ power comes from the AMQP Model.
Connecting to the Broker: Connecting to AMQP broker. How to integrate with standalone applications as well as Ruby on Rails, Merb, Sinatra or Rack apps. What difference application server (Unicorn, Passenger, Thin, etc) makes. How to handle authentication failures and network connectivity issues. Closing AMQP connection gracefully.
Working With Queues: What AMQP queues are. How to declare AMQP queues. When and how to use server-named and explicitly named queues. How to subscribe for “push” message delivery. What message acknowledgements are. How to access AMQP message metadata. How to fetch (“pull”) messages from queues on demand. How to bind and unbind a queue to an exchange. How to delete a queue.
Working With Exchanges: What AMQP exchanges are. Concept of binding. How to declare AMQP exchanges. How different exchange types route messages and common use cases. How to publish messages, especially how to do it reliably. What AMQP transactions are. What Publisher Confirms are. When messages are returned. How to delete an exchange.
Bindings: What AMQP bindings are, in-depth. How to bind queues to exchanges. How to unbind queues from exchanges. What’s the life cycle of messages is. How unroutable messages are handled.
Patterns and Use Cases: Typical use cases, patterns and routing topologies.
Durability and Message Persistence: Exchange durability. Queue durability. Message persistence. Performance implications.
Error Handling and Recovery: Network failures. Connection-level exceptions. Channel-level exceptions. Why error handling is easy but recovery is hard. How to survive typical problems. What other tools can help (e.g. HAProxy).
Unit and integration testing of AMQP applications: Unit testing of asynchronous code: typical problems and ways to solve them. An oviewview of evented-spec, the gem that amqp gem itself uses for its test suite.
RabbitMQ versions: RabbitMQ versions that amqp gem supports. Popular Linux distributions and RabbitMQ versions they ship. How to obtain up-to-date official packages of RabbitMQ.
Using TLS (SSL): All things related to TLS-encrypted connections.

When more than one guide describes the same concept, we make sure to use cross-references, however, only one guide discusses the concept in detail.

Full guide list

License

This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images & stylesheets). The source is available on Github.

Authors

These guides were written by Michael Klishin and edited by Chris Duncan

Tell us what you think!

Please take a moment to tell us what you think about this guide on Twitter or the Ruby AMQP mailing list. Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.

If, for some reason, you cannot use the communication channels mentioned above, you can contact the author of the guides directly