amqp 0.8.0.rc13 → 0.8.0.rc14

data/docs/ConnectionEncryptionWithTLS.textile

@@ -1,11 +1,13 @@
 # @title Ruby AMQP gem: Using TLS
 
-h1. TBD
+h1. Using TLS with Ruby amqp gem
 
 
 h2. About this guide
 
-TBD
+This guide covers connection to AMQP brokers using TLS (also known as SSL) and related issues. This guide
+does not explain basic TLS concepts. For that, refer to resources like "Introduction to SSL":https://developer.mozilla.org/en/Introduction_to_SSL
+or "Wikipedia page on TLS":http://en.wikipedia.org/wiki/Transport_Layer_Security.
 
 
 h2. Covered versions
@@ -13,16 +15,74 @@ h2. Covered versions
 This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
+h2. Broker version requirements
 
-h2. TBD
+h3. RabbitMQ
 
-TBD
+RabbitMQ supports TLS since version 1.7.0. Minimum requirements are
+
+ * Erlang R13B
+ * Erlang SSL application 3.10
+
+The recommended distribution is R14B (SSL 4.0.1) or later. This should be considered the minimum configuration for Java
+and Erlang clients due to an incorrect RC4 implementation in earlier versions of Erlang.
+
+Learn more at "rabbitmq.com TLS page":http://www.rabbitmq.com/ssl.html.
+
+
+
+h2. Pre-requisites
+
+AMQP brokers typically need to be configured to use TLS. Just like Web servers, TLS connections are usually accepted
+on a separate port (5671). "rabbitmq.com TLS page":http://www.rabbitmq.com/ssl.html describes how to configure RabbitMQ
+to use TLS, how to generate certificates for development and so on.
+
+
+
+h2. Connecting to AMQP broker using TLS
+
+To instruct Ruby amqp gem to use TLS for connection, pass :ssl option that specifies certificate chain file path
+as well as private key file path:
+
+<pre>
+<code>
+AMQP.start(:port     => 5671,
+           :ssl => {
+             :cert_chain_file  => certificate_chain_file_path,
+             :private_key_file => client_private_key_file_path
+           }) do |connection|
+  puts "Connected, authenticated. TLS seems to work."
+
+  connection.disconnect { puts "Now closing the connection…"; EventMachine.stop }
+end
+</code>
+</pre>
+
+Note that TLS connection may take a bit of time to establish (up to several seconds in some cases). To verify that
+broker connection actually uses TLS, refer to RabbitMQ log file:
+
+<pre>
+=INFO REPORT==== 28-Jun-2011::08:41:24 ===
+accepted TCP connection on 0.0.0.0:5671 from 127.0.0.1:53444
+
+=INFO REPORT==== 28-Jun-2011::08:41:24 ===
+starting TCP connection <0.9904.0> from 127.0.0.1:53444
+
+=INFO REPORT==== 28-Jun-2011::08:41:24 ===
+upgraded TCP connection <0.9904.0> to SSL
+</pre>
+
+
+
+h2. Example code
+
+TLS example (as well as sample certificates you can use to get started with) can be found in the "amqp gem git repository":https://github.com/ruby-amqp/amqp/tree/master/examples
 
 
 
 h2. Tell us what you think!
 
-Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.
 

data/docs/DocumentationGuidesIndex.textile

@@ -2,32 +2,112 @@
 
 h1. Ruby AMQP gem documentation guides
 
-h2. Guide list
+h2. Which versions of the amqp gem do the guides cover?
 
- * {file:docs/GettingStarted.textile Getting started}
- * {file:docs/ConnectingToTheBroker.textile Connecting to the broker}
- * {file:docs/Queues.textile Working with queues}
- * {file:docs/Exchanges.textile Working with exchanges}
+These guides cover v0.8.0.RC13 and later of the "Ruby amqp gem":http://github.com/ruby-amqp/amqp.
+
+
+h2. 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:
+
+<dl>
+  <dt>{file:docs/GettingStarted.textile Getting Started}</dt>
+  <dd>
+  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.
+  </dd>
+
+
+  <dt>{file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}</dt>
+  <dd>
+  Explains 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.
+  </dd>
+
+  <dt>{file:docs/ConnectingToTheBroker.textile Connecting to the Broker}</dt>
+  <dd>
+  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.
+  </dd>
+
+  <dt>{file:docs/Queues.textile Working With Queues}</dt>
+  <dd>
+  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.
+  </dd>
+
+  <dt>{file:docs/Exchanges.textile Working With Exchanges}</dt>
+  <dd>
+  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.
+  How to delete an exchange.
+  </dd>
+
+  <dt>{file:docs/PatternsAndUseCases.textile Patterns and Use Cases}</dt>
+  <dd>Typical use cases, patterns and routing topologies.</dd>
+
+  <dt>{file:docs/Durability.textile Durability and Message Persistence}</dt>
+  <dd>Exchange durability. Queue durability. Message persistence. Performance implications.</dd>
+
+  <dt>{file:docs/ErrorHandling.textile Error Handling and Recovery}</dt>
+  <dd>
+  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).
+  </dd>
+
+  <dt>{file:docs/RabbitMQVersions.textile RabbitMQ versions}</dt>
+  <dd>
+  RabbitMQ versions that amqp gem supports. Popular Linux distributions and RabbitMQ versions they ship. How to obtain up-to-date official
+  packages of RabbitMQ.
+  </dd>
+
+  <dt>{file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}</dt>
+  <dd>All things related to TLS-encrypted connections.</dd>
+</dl>
+
+
+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.
+
+
+h2. Full guide list
+
+ * {file:docs/GettingStarted.textile Getting Started}
+ * {file:docs/AMQP091ModelExplained.textile AMQP 0.9.1 Model Explained}
+ * {file:docs/ConnectingToTheBroker.textile Connecting to the Broker}
+ * {file:docs/Queues.textile Working With Queues}
+ * {file:docs/Exchanges.textile Working With Exchanges}
  * {file:docs/Bindings.textile Bindings}
- * {file:docs/Routing.textile Routing}
- * {file:docs/Durability.textile Durability and message persistence}
- * {file:docs/ErrorHandling.textile Error handling}
+ * {file:docs/PatternsAndUseCases.textile Patterns and Use Cases}
+ * {file:docs/Durability.textile Durability and Message Persistence}
+ * {file:docs/ErrorHandling.textile Error Handling and Recovery}
  * {file:docs/08Migration.textile Upgrading from version 0.6.x/0.7.x to 0.8.x and above}
  * {file:docs/Troubleshooting.textile Troubleshooting and debugging AMQP applications}
  * {file:docs/Clustering.textile Clustering}
  * {file:docs/RabbitMQVersions.textile RabbitMQ versions}
  * {file:docs/ConnectionEncryptionWithTLS.textile Using TLS (SSL)}
- * {file:docs/VendorSpecificExtensions.textile Vendor-specific extensions to AMQP 0.9.1 spec}
+ * {file:docs/VendorSpecificExtensions.textile Vendor-specific Extensions to AMQP 0.9.1 spec}
  * {file:docs/RunningTests.textile Running amqp gem test suite}
 
 
 h2. Tell us what you think!
 
-Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
-what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
-key to making documentation better.
+Please take a moment to tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or the "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp.
+ 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 mailing list communication is not an option for you for some reason, you can "contact guides author directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation
+If, for some reason, you cannot use the communication channels mentioned above, you can "contact the author of the guides directly":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation
 
 
 <div id="disqus_thread"></div>

data/docs/Durability.textile

@@ -98,7 +98,7 @@ See {file:docs/Clustering.textile Clustering guide} for in-depth discussion of t
 
 h2. Tell us what you think!
 
-Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.
 

data/docs/ErrorHandling.textile

@@ -9,17 +9,23 @@ multiple kinds of failures: protocol exceptions, network failures, broker failur
 Correct error handling and recovery is not easy. This guide explains how amqp gem helps you in dealing with
 issues like
 
- * Broker connection failures
+ * Initial broker connection failures
  * Network connection interruption
- * TLS (SSL) related issues
  * AMQP connection-level exceptions
  * AMQP channel-level exceptions
  * Broker failure
+ * TLS (SSL) related issues
+
+as well as
+
+ * How to recover after a network failure
+ * What is automatic recovery mode, when you should and should not use it
+
 
 
 h2. Covered versions
 
-This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0.RC14 and later.
 
 
 h2. Code examples
@@ -28,7 +34,7 @@ There are several {https://github.com/ruby-amqp/amqp/tree/master/examples/error_
 free to contribute new examples.
 
 
-h3. Broker connection failures
+h3. Initial broker connection failures
 
 When applications connect to the broker, they need to handle connection failures. Networks are not 100% reliable, even with modern system configuration tools
 like Chef or Puppet misconfigurations happen and broker might be down, too. Error detection should happen as early as possible. There are two ways of detecting
@@ -36,24 +42,6 @@ TCP connection failure, the first one is to catch an exception:
 
 <pre>
 <code>
-#!/usr/bin/env ruby
-# encoding: utf-8
-
-require "rubygems"
-require "amqp"
-
-
-puts "=> TCP connection failure handling with a rescue statement"
-puts
-
-connection_settings = {
-  :port     => 9689,
-  :vhost    => "/amq_client_testbed",
-  :user     => "amq_client_gem",
-  :password => "amq_client_gem_password",
-  :timeout        => 0.3
-}
-
 begin
   AMQP.start(connection_settings) do |connection, open_ok|
     raise "This should not be reachable"
@@ -64,6 +52,9 @@ end
 </code>
 </pre>
 
+Full example:
+<script src="https://gist.github.com/1016238.js"> </script>
+
 {AMQP.connect} (and {AMQP.start}) will raise {AMQP::TCPConnectionFailed} if connection fails. Code that catches it can write to log
 about the issue or use retry to execute begin block one more time. Because initial connection failures are due to misconfiguration or network outage, reconnection
 to the same endpoint (hostname, port, vhost combination) will result in the same issue over and over. TBD: failover, connection to the cluster.
@@ -72,16 +63,7 @@ Alternative way of handling connection failure is with an errback (a callback fo
 
 <pre>
 <code>
-#!/usr/bin/env ruby
-# encoding: utf-8
-
-require "rubygems"
-require "amqp"
-
-puts "=> TCP connection failure handling with a callback"
-puts
-
-handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
+handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EventMachine.stop }
 connection_settings = {
   :port     => 9689,
   :vhost    => "/amq_client_testbed",
@@ -90,14 +72,12 @@ connection_settings = {
   :timeout        => 0.3,
   :on_tcp_connection_failure => handler
 }
-
-
-AMQP.start(connection_settings) do |connection, open_ok|
-  raise "This should not be reachable"
-end
 </code>
 </pre>
 
+Full example:
+<script src="https://gist.github.com/1016235.js"> </script>
+
 :on_tcp_connection_failure option accepts any object that responds to #call.
 
 If you connect to the broker from a code in a class (as opposed to top-level scope in a script), Object#method can be used to pass object method as a handler
@@ -111,126 +91,510 @@ h3. Authentication failures
 Another reason why connection may fail is authentication failure. Handling authentication failure is very similar to handling initial TCP
 connection failure:
 
+<script src="https://gist.github.com/1016233.js"> </script>
+
+
+h4. Default handler
+
+default handler raises {AMQP::PossibleAuthenticationFailureError}:
+
+<script src="https://gist.github.com/1016234.js"> </script>
+
+In case you wonder why callback name has "possible" in it: {http://bit.ly/mTr1YN AMQP 0.9.1 spec} requires broker implementations to
+simply close TCP connection without sending any more data when an exception (such as authentication failure) occurs before AMQP connection
+is open. In practice, however, when broker closes TCP connection between successful TCP connection and before AMQP connection is open,
+it means that authentication has failed.
+
+
+
+h2. Handling network connection interruptions
+
+Network connectivity issues are sad fact of life in modern software systems. Event small products and projects these days consist of multiple
+applications, often running on more than one machine. Ruby amqp gem detects TCP connection failures and lets you handle them by
+defining a callback using {AMQP::Session#on_tcp_connection_loss}. That callback will be run when TCP connection fails, and will be passed
+two parameters: connection object and settings of the last successful connection.
+
 <pre>
 <code>
-#!/usr/bin/env ruby
-# encoding: utf-8
+connection.on_tcp_connection_loss do |connection, settings|
+  # reconnect in 10 seconds, without enforcement
+  connection.reconnect(false, 10)
+end
+</code>
+</pre>
 
-require "rubygems"
-require "amqp"
+Sometimes it is necessary for other entities in an application to react to network failures. amqp gem 0.8.0 and later provides a number event
+handlers to make this task easier for developers. This set of features is know as the "shutdown protocol" (the word "protocol" here means
+"API interface" or "behavior", not network protocol).
 
-puts "=> Authentication failure handling with a callback"
-puts
+{AMQP::Session}, {AMQP::Channel}, {AMQP::Exchange}, {AMQP::Queue} and {AMQP::Consumer all implement shutdown protocol and thus error
+handling API is consistent for all classes, with {AMQP::Session} and #{AMQP::Channel} having a few methods other entities do not have.
 
-handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
-connection_settings = {
-  :port     => 5672,
-  :vhost    => "/amq_client_testbed",
-  :user     => "amq_client_gem",
-  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
-  :timeout        => 0.3,
-  :on_tcp_connection_failure => handler,
-  :on_possible_authentication_failure => Proc.new { |settings|
-                                            puts "Authentication failed, as expected, settings are: #{settings.inspect}"
+The Shutdown protocol revolves around two events:
 
-                                            EM.stop
-                                          }
-}
+ * Network connection fails
+ * Broker closes AMQP connection (or channel)
+
+In this section, we concentrate only on the former. When network connection fails, the underlying networking library detects it and
+runs a piece of code on {AMQP::Session} to handle it. That, in turn, propagates this event to channels, channels propagate it to
+exchanges and queues, queues propagate it to their consumers (if any). Each of these entities in the object graph can react
+to network interruption by executing application-defined callbacks.
+
+h3. Shutdown Protocol methods on AMQP::Session
 
-AMQP.start(connection_settings) do |connection, open_ok|
-  raise "This should not be reachable"
+ * {AMQP::Session#on_tcp_connection_loss}
+ * {AMQP::Session#on_connection_interruption}
+
+The difference between these methods is that {AMQP::Session#on_tcp_connection_loss} is used to define a callback that will
+be executed *once* when TCP connection fails. It is possible that reconnection attempts will not succeed immediately, so
+there will be subsequent failures. To react to those, {AMQP::Session#on_connection_interruption} method is used.
+
+First argument that both of these methods yield to the handler your application defines is the connection itself. This is
+done to make sure you can register Ruby objects as handlers, and they do not have to keep any state around (for example,
+connection instances):
+
+<pre>
+<code>
+connection.on_connection_interruption do |conn|
+  puts "Connection detected connection interruption"
 end
+
+# or
+
+class ConnectionInterruptionHandler
+
+  #
+  # API
+  #
+
+  def handle(connection)
+    # handling logic
+  end
+
+end
+
+handler = ConnectionInterruptionHandler.new
+connection.on_connection_interruption(&handler.method(:handle))
 </code>
 </pre>
 
-default handler raises {AMQP::PossibleAuthenticationFailureError}:
+Note that {AMQP::Session#on_connection_interruption} callback is called *before* this event is propagated to channels, queues and so on.
+
+Different applications handle connection failures differently. It is very common to use {AMQP::Session#reconnect} method
+to schedule a reconnection to the same host, or use {AMQP::Session#reconnect_to} to connect to a different one.
+
+For some applications it is OK to simply exit and wait to be restarted at a later point in time, for example, by a process
+monitoring system like Nagios or Monit.
+
+
+h3. Shutdown Protocol methods on AMQP::Channel
+
+{AMQP::Channel} provides only one method: {AMQP::Channel#on_connection_interruption}, that registers a callback similar to
+the one seen in the previous section:
 
 <pre>
 <code>
-#!/usr/bin/env ruby
-# encoding: utf-8
+channel.on_connection_interruption do |ch|
+  puts "Channel #{ch.id} detected connection interruption"
+end
+</code>
+</pre>
 
-require "rubygems"
-require "amqp"
+Note that {AMQP::Channel#on_connection_interruption} callback is called *after* this event is propagated to exchanges, queues and so on.
+Right after that channel state is reset, except for error handling/recovery-related callbacks.
 
-puts "=> Authentication failure handling with a rescue block"
-puts
+<span class="note">
+Many applications do not need per-channel network failure handling.
+</span>
 
-handler             = Proc.new { |settings| puts "Failed to connect, as expected"; EM.stop }
-connection_settings = {
-  :port     => 5672,
-  :vhost    => "/amq_client_testbed",
-  :user     => "amq_client_gem",
-  :password => "amq_client_gem_password_that_is_incorrect #{Time.now.to_i}",
-  :timeout        => 0.3,
-  :on_tcp_connection_failure => handler
-}
 
+h3. Shutdown Protocol methods on AMQP::Exchange
 
-begin
-  AMQP.start(connection_settings) do |connection, open_ok|
-    raise "This should not be reachable"
-  end
-rescue AMQP::PossibleAuthenticationFailureError => afe
-  puts "Authentication failed, as expected, caught #{afe.inspect}"
-  EventMachine.stop if EventMachine.reactor_running?
+{AMQP::Exchange} provides only one method: {AMQP::Exchange#on_connection_interruption}, that registers a callback similar to
+the one seen in the previous section:
+
+<pre>
+<code>
+exchange.on_connection_interruption do |ex|
+  puts "Exchange #{ex.name} detected connection interruption"
 end
 </code>
 </pre>
 
-In case you wonder why callback name has "possible" in it: {http://bit.ly/mTr1YN AMQP 0.9.1 spec} requires broker implementations to
-simply close TCP connection without sending any more data when an exception (such as authentication failure) occurs before AMQP connection
-is open. In practice, however, when broker closes TCP connection between successful TCP connection and before AMQP connection is open,
-it means that authentication has failed.
+<span class="note">
+Many applications do not need per-exchange network failure handling.
+</span>
 
 
+h3. Shutdown Protocol methods on AMQP::Queue
 
-h2. Network connection interruption
+{AMQP::Queue} provides only one method: {AMQP::Queue#on_connection_interruption}, that registers a callback similar to
+the one seen in the previous section:
 
-TBD
+<pre>
+<code>
+queue.on_connection_interruption do |q|
+  puts "Queue #{q.name} detected connection interruption"
+end
+</code>
+</pre>
 
+Note that {AMQP::Queue#on_connection_interruption} callback is called *after* this event is propagated to consumers.
 
+<span class="note">
+Many applications do not need per-queue network failure handling.
+</span>
 
-h2. TLS (SSL) related issues
 
-TBD
+h3. Shutdown Protocol methods on AMQP::Consumer
+
+{AMQP::Consumer} provides only one method: {AMQP::Consumer#on_connection_interruption}, that registers a callback similar to
+the one seen in the previous section:
+
+<pre>
+<code>
+consumer.on_connection_interruption do |c|
+  puts "Consumer with consumer tag #{c.consumer_tag} detected connection interruption"
+end
+</code>
+</pre>
+
+<span class="note">
+Many applications do not need per-consumer network failure handling.
+</span>
+
+
+
+h2. Recovering from network connection failures
+
+Detecting network connections is nearly useless if AMQP-based application cannot recover from them. Recovery is the hard part
+in "error handling and recovery". Fortunately, recovery process for many applications follows one simple scheme that amqp
+gem can perform automatically for you.
+
+h3. Manual recovery
+
+Similarly to the Shutdown Protocol, amqp gem entities implement Recovery Protocol. Recovery Protocol consists of 3 methods
+connections, channels, queues, consumers and exchanges implement:
+
+ * {AMQP::Session#before_recovery}
+ * {AMQP::Session#auto_recover}
+ * {AMQP::Session#after_recovery}
+
+{AMQP::Session#before_recovery} lets application developers register a callback that will be executed *after TCP connection is
+re-established but before AMQP connection is reopened*. {AMQP::Session#after_recovery} is similar except that the callback is run
+*after AMQP connection is reopened*.
+
+{AMQP::Channel}, {AMQP::Queue}, {AMQP::Consumer} and {AMQP::Exchange} methods behavior is identical.
+
+
+h3. Automatic recovery
+
+Many applications use the same recovery strategy, that consists of the following steps:
+
+ * Re-open channels
+ * For each channel, re-declare exchanges
+ * For each channel, re-declare queues
+ * For each queue, recover all bindings
+ * For each queue, recover all consumers
+
+amqp gem provides a feature known as "automatic recovery" that is *opt-in* (not opt-out, not used by default) and lets application
+developers get aforementioned recovery strategy by setting one additional attribute on {AMQP::Channel} instance:
+
+<pre>
+<code>
+ch = AMQP::Channel.new(connection)
+ch.auto_recovery = true
+</code>
+</pre>
+
+
+A more verbose way to do the same thing:
+<pre>
+<code>
+ch = AMQP::Channel.new(connection, AMQP::Channel.next_channel_id, :auto_recovery => true)
+</code>
+</pre>
+
+Note that if you do not want to pass any options, 2nd argument can be left out as well,
+then it will default to {AMQP::Channel.next_channel_id}.
+
+
+To find out whether channel uses automatic recovery mode, use {AMQP::Channel#auto_recovering?}.
+
+Auto recovery mode can be turned on and off any number of times during channel life cycle, although very small percentage of
+applications really does this. Typically you decide what channels should be using automatic recovery at application design
+stage.
+
+Full example (run it, then shut down AMQP broker running on localhost, then bring it back up and use management tools such as `rabbitmqctl`
+to see that queues & bindings & consumer have all recovered):
+<script src="https://gist.github.com/1048076.js"> </script>
+
+Server-named queues, when recovered automatically, will get *new server-generated names* to guarantee there are no name collisions.
+
+<span note="class">
+When in doubt, try using automatic recovery first. If it is not sufficient for you application, switch to manual
+recovery using events and callbacks introduced in the "Manual recovery" section.
+</span>
+
+
+h2. Detecting broker failures
+
+AMQP applications see broker failure as TCP connection loss. There is no reliable way to know whether there is a network split
+or network peer is down.
+
 
 
 
 h2. AMQP connection-level exceptions
 
+h3. Handling connection-level exceptions
+
+Connection-level exceptions are rare and may indicate a serious issue with client library or in-flight data corruption. They mandate
+that connection cannot be used any more and must be closed. In any case, your application should be prepared to handle this kind of errors.
+To define a handler, use {AMQP::Session#on_error} method that takes a callback and yields two arguments to it when connection-level exception happens:
+
+<pre>
+<code>
+connection.on_error do |conn, connection_close|
+  puts "Handling a connection-level exception."
+  puts
+  puts "AMQP class id : #{connection_close.class_id}"
+  puts "AMQP method id: #{connection_close.method_id}"
+  puts "Status code   : #{connection_close.reply_code}"
+  puts "Error message : #{connection_close.reply_text}"
+end
+</code>
+</pre>
+
+Status codes are similar to those of HTTP. For the full list of error codes and their meaning, consult {http://www.rabbitmq.com/amqp-0-9-1-reference.html#constants AMQP 0.9.1 constants reference}.
+
+<span class="note">
+Only one connection-level exception handler can be defined per connection instance (the one added last replaces previously added ones).
+</span>
+
+Full example:
+<script src="https://gist.github.com/1015966.js"> </script>
+
+
+
+h2. Handling graceful broker shutdown
+
+When AMQP broker is shut down, it properly closes connection first. To do so, it uses *connection.close* AMQP method. AMQP clients then
+need to check if the reply code is equal to 320 (CONNECTION_FORCED) to distinguish graceful shutdown. With RabbitMQ, when broker
+is stopped using
+
+<pre>rabbitmqctl stop</pre>
+
+reply_text will be set to
+
+<pre>CONNECTION_FORCED - broker forced connection closure with reason 'shutdown'</pre>
+
+Each application choose how to handle graceful broker shutdowns individually, so *amqp gem's automatic reconnection does not cover graceful broker shutdowns*.
+Applications that want to reconnect when broker is stopped can use {AMQP::Session#periodically_reconnect} like so:
+
+<pre>
+<code>
+connection.on_error do |conn, connection_close|
+  puts "[connection.close] Reply code = #{connection_close.reply_code}, reply text = #{connection_close.reply_text}"
+  if connection_close.reply_code == 320
+    puts "[connection.close] Setting up a periodic reconnection timer..."
+    # every 30 seconds
+    conn.periodically_reconnect(30)
+  end
+end
+</code>
+</pre>
+
+Once AMQP connection is re-opened, channels in automatic recovery mode will recover just like they do after network outages.
+
+
+h2. Integrating channel-level exceptions handling with object-oriented Ruby code
+
+Error handling can be easily integrated into object-oriented Ruby code (in fact, this is highly encouraged).
+A common technique is to combine {http://rubydoc.info/stdlib/core/1.8.7/Object:method Object#method} and {http://rubydoc.info/stdlib/core/1.8.7/Method:to_proc Method#to_proc}
+and use object methods as error handlers:
+
+<pre>
+<code>
+class ConnectionManager
+
+  #
+  # API
+  #
+
+  def connect(*args, &block)
+    @connection = AMQP.connect(*args, &block)
+
+    # combines Object#method and Method#to_proc to use object
+    # method as a callback
+    @connection.on_error(&method(:on_error))
+  end # connect(*args, &block)
+
+
+  def on_error(connection, connection_close)
+    puts "Handling a connection-level exception."
+    puts
+    puts "AMQP class id : #{connection_close.class_id}"
+    puts "AMQP method id: #{connection_close.method_id}"
+    puts "Status code   : #{connection_close.reply_code}"
+    puts "Error message : #{connection_close.reply_text}"
+  end # on_error(connection, connection_close)
+end
+</code>
+</pre>
+
+Full example that uses objects:
+<script src="https://gist.github.com/1016049.js"> </script>
+
 TBD
 
 
 
+
 h2. AMQP channel-level exceptions
 
-TBD
+h3. Hanling channel-level exceptions
 
+Channel-level exceptions are more common than connection-level ones. They are handled in a similar manner, by defining a callback
+with {AMQP::Channel#on_error} method that takes a callback and yields two arguments to it when channel-level exception happens:
 
+<pre>
+<code>
+channel.on_error do |ch, channel_close|
+  puts "Handling a channel-level exception."
+  puts
+  puts "AMQP class id : #{channel_close.class_id}"
+  puts "AMQP method id: #{channel_close.method_id}"
+  puts "Status code   : #{channel_close.reply_code}"
+  puts "Error message : #{channel_close.reply_text}"
+end
+</code>
+</pre>
 
-h2. Broker failure
+Status codes are similar to those of HTTP. For the full list of error codes and their meaning, consult {http://www.rabbitmq.com/amqp-0-9-1-reference.html#constants AMQP 0.9.1 constants reference}.
 
-TBD
+<span class="note">
+Only one channel-level exception handler can be defined per channel instance (the one added last replaces previously added ones).
+</span>
+
+Full example:
+<script src="https://gist.github.com/1016042.js"> </script>
 
 
+h3. Integrating channel-level exceptions handling with object-oriented Ruby code
 
+Error handling can be easily integrated into object-oriented Ruby code (in fact, this is highly encouraged).
+A common technique is to combine {http://rubydoc.info/stdlib/core/1.8.7/Object:method Object#method} and {http://rubydoc.info/stdlib/core/1.8.7/Method:to_proc Method#to_proc}
+and use object methods as error handlers. For example of this, see section on connection-level exceptions above.
 
-h2. Recovery
+
+h3. Common channel-level exceptions and what they mean
+
+A few channel-level exceptions are common and deserve more attention.
+
+h4. 406 Precondition Failed
+
+<dl>
+  <dt>Description</dt>
+  <dd>The client requested a method that was not allowed because some precondition failed.</dd>
+
+  <dt>What might cause it</dt>
+  <dd>
+    <ul>
+      <li>
+        AMQP entity (a queue or exchange) was re-declared with attributes different from original declaration. Maybe two applications or pieces of code
+        declare the same entity with different attributes. Note that different AMQP client libraries historically use slightly different defaults for
+        entities and this may cause attribute mismatches.
+      </li>
+    <li>{AMQP::Channel#tx_commit} or {AMQP::Channel#tx_rollback} might be run on a channel that wasn't previously made transactional with {AMQP::Channel#tx_select}</li>
+    </ul>
+  </dd>
+
+  <dt>Example RabbitMQ error message</dt>
+  <dd>
+    <ul>
+      <li>PRECONDITION_FAILED - parameters for queue 'amqpgem.examples.channel_exception' in vhost '/' not equivalent</li>
+      <li>PRECONDITION_FAILED - channel is not transactional</li>
+    </ul>
+  </dd>
+</dl>
+
+h4. 405 Resource Locked
+
+<dl>
+  <dt>Description</dt>
+  <dd>The client attempted to work with a server entity to which it has no access because another client is working with it.</dd>
+
+  <dt>What might cause it</dt>
+  <dd>
+    <ul>
+      <li>Multiple applications (or different pieces of code/threads/processes/routines within a single application) might try to declare queues with the same name as exclusive.</li>
+    <li>Multiple consumer across multiple or single app might be registered as exclusive for the same queue.</li>
+    </ul>
+  </dd>
+
+  <dt>Example RabbitMQ error message</dt>
+  <dd>RESOURCE_LOCKED - cannot obtain exclusive access to locked queue 'amqpgem.examples.queue' in vhost '/'</dd>
+</dl>
+
+
+h4. 403 Access Refused
+
+<dl>
+  <dt>Description</dt>
+  <dd>The client attempted to work with a server entity to which it has no access due to security settings. </dd>
+
+  <dt>What might cause it</dt>
+  <dd>Application tries to access a queue or exchange it has no permissions for (or right kind of permissions, for example, write permissions)</dd>
+
+  <dt>Example RabbitMQ error message</dt>
+  <dd>ACCESS_REFUSED - access to queue 'amqpgem.examples.channel_exception' in vhost 'amqp_gem_testbed' refused for user 'amqp_gem_reader'</dd>
+</dl>
+
+
+
+
+h2. TLS (SSL) related issues
 
 TBD
 
 
 
+
+
 h2. Conclusion
 
+Distributed applications introduce a whole new class of failres developers need to be aware of. Many of them come from
+unreliability of the network. The famous "Fallacies of Distributed Computing":http://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing list
+common assumptions software engineers must not make:
+
+ * The network is reliable.
+ * Latency is zero.
+ * Bandwidth is infinite.
+ * The network is secure.
+ * Topology doesn't change.
+ * There is one administrator.
+ * Transport cost is zero.
+ * The network is homogeneous.
+
+Unfortunately, applications that use Ruby and AMQP are not immune to these problems and developers need to always keep that
+in mind. This list is just as relevant in 2011 as it was in the 90s.
+
+Ruby amqp gem 0.8.x and later lets applications to define handlers that handle connection-level exceptions, channel-level
+exceptions and TCP connection failures. Handling AMQP exceptions and network connection failures is relatively easy.
+Re-declaring AMQP instances application works with is where the most of complexity comes from. By using Ruby objects as
+error handlers, declaration of AMQP entities can be done in one place, making it much easier to understand and maintain.
+
+amqp gem error handling and interruption is not a copy of RabbitMQ Java client's "Shutdown Protocol":http://www.rabbitmq.com/api-guide.html#shutdown,
+but they turn out to be similar with respect to network failures and connection-level exceptions.
+
 TBD
 
 
 
 h2. Tell us what you think!
 
-Please take a moment and tell us what you think about this guide on "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
+Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
 what was unclear? what wasn't covered? maybe you don't like guide style or grammar and spelling are incorrect? Readers feedback is
 key to making documentation better.