amqp 0.8.4 → 0.9.0.pre1

data/CHANGELOG

@@ -1,4 +1,4 @@
-= Version 0.8.2 (to be released)
+= Version 0.9.0 (not yet released)
 
 
 = Version 0.8.1
@@ -6,6 +6,7 @@
   * [BUG] AMQP::Queue#status can no longer result in queue instance @ivars being changed.
   * [API] AMQP::Channel#reuse allows channel instance to be reused with a different channel id, may be used to recover from channel-level exceptions.
 
+
 = Version 0.8.0
 
   * [API] AMQP::Session#on_skipped_heartbeats callback that can be used to handle skipped heartbeats (for cases when TCP network failure detection is not timely enough)

data/README.md

@@ -1,9 +1,9 @@
 # About Ruby amqp gem #
 
-Ruby amqp gem is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
+[Ruby amqp gem](http://rubyamqp.info) is a widely used, feature-rich, well-maintained asynchronous AMQP 0.9.1 client with batteries included.
 This library works with Ruby 1.8.7 (*except for p249*, see the FAQ), Ruby 1.9.2, Ruby 1.9.3, [JRuby](http://jruby.org), [Rubinius](http://rubini.us) as well as [REE](http://www.rubyenterpriseedition.com), and is licensed under the [Ruby License](http://www.ruby-lang.org/en/LICENSE.txt)
 
-0.8.0.RCs and later versions of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/hw2ELX)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
+0.8.0 and later versions of amqp gem implement [AMQP 0.9.1](http://bit.ly/amqp-model-explained) (see also [AMQP 0.9.1 spec document](http://bit.ly/amqp091spec)) and support [RabbitMQ extensions to AMQP 0.9.1](http://www.rabbitmq.com/extensions.html).
 
 [![Continuous Integration status](https://secure.travis-ci.org/ruby-amqp/amqp.png)](http://travis-ci.org/ruby-amqp/amqp)
 
@@ -123,7 +123,7 @@ to learn more about AMQP principles & concepts.
 
 We believe that in order to be a library our users **really** love, we need to care about documentation as much as (or more)
 code readability, API beauty and autotomated testing across 5 Ruby implementations on multiple operating systems. We do care
-about our [documentation](http://bitly.com/amqp-gem-docs): **if you don't find your answer in documentation, we consider it a high severity bug** that you
+about our [documentation](http://rubyamqp.info): **if you don't find your answer in documentation, we consider it a high severity bug** that you
 should [file to us](http://github.com/ruby-amqp/amqp/issues). Or just complain to [@rubyamqp](https://twitter.com/rubyamqp) on Twitter.
 
 
@@ -150,7 +150,7 @@ There is also a work-in-progress [Messaging Patterns and Use Cases With AMQP](ht
 
 ### Documentation guides ###
 
-[Documentation guides](http://bit.ly/amqp-gem-docs) describe the library itself as well as AMQP concepts, usage scenarios, topics like working with exchanges and queues,
+[Documentation guides](http://rubyamqp.info) (also [on rubydoc.info](http://bit.ly/amqp-gem-docs)) describe the library itself as well as AMQP concepts, usage scenarios, topics like working with exchanges and queues,
 error handing & recovery, broker-specific extensions, TLS support, troubleshooting and so on. Most of the documentation is in these guides.
 
 
@@ -172,6 +172,10 @@ Upgrading from amqp gem 0.6.x and 0.7.x to to 0.8.0.RCs is straightforward, plea
 The same guide explains amqp gem versions history and why you would want to upgrade.
 
 
+## Maintainer Information
+
+amqp gem is maintained by [Michael Klishin](https://github.com/michaelklishin).
+
 
 ## Community
 

data/docs/08Migration.textile

@@ -76,7 +76,13 @@ h2. Why developers should upgrade to 0.8.0
 
 h2. AMQP protocol version change
 
-amqp gem before 0.8.0.RCs series implemented (most of) AMQP 0.8 specification.
+amqp gem before 0.8.0 (0.6.x, 0.7.x) series implemented (most of) AMQP 0.8 specification. amqp gem 0.8.0 implements AMQP 0.9.1 and thus
+*requires RabbitMQ version 2.0 or later*. See {file:docs/RabbitMQVersions.textile RabbitMQ versions} for more information about
+RabbitMQ versions support and how obtain up-todate packages for your operating system.
+
+<span class="note">
+amqp gem 0.8.0 and later versions implement AMQP 0.9.1 and thus *requires RabbitMQ version 2.0 or later*
+</span>
 
 
 

data/docs/AMQP091ModelExplained.textile

@@ -262,7 +262,11 @@ To make it possible for a single broker to host multiple isolated "environments"
 of _virtual hosts_ (vhosts). They are similar to virtual hosts used by many popular Web servers and provide completely isolated environments
 in which AMQP entities live. AMQP clients specify what vhosts they want to use during AMQP connection negotiation.
 
-An AMQP 0.9.1 vhost name can be any non-blank string.
+An AMQP 0.9.1 vhost name can be any non-blank string. Some most common use cases for vhosts are
+
+ * To separate AMQP entities used by different groups of applications
+ * To separate multiple installations/environments (e.g. production, staging) of one or more applications
+ * To implement a multi-tenant environment
 
 
 h2. AMQP is Extensible

data/docs/DocumentationGuidesIndex.textile

@@ -20,7 +20,7 @@ but *most of the content is concentrated in just 3-4 guides* that are about 80%
 Here is a summary of guides and their content:
 
 <dl>
-  <dt>{file:docs/GettingStarted.textile Getting Started}</dt>
+  <dt>{file:docs/GettingStarted.textile Getting Started with Ruby amqp gem and RabbitMQ}</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.
@@ -73,6 +73,13 @@ Here is a summary of guides and their content:
   recovery is hard. How to survive typical problems. What other tools can help (e.g. HAProxy).
   </dd>
 
+  <dt>{file:docs/TestingWithEventedSpec.textile Unit and integration testing of AMQP applications}</dt>
+  <dd>
+  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":https://github.com/ruby-amqp/amqp/tree/master/spec.
+  </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
@@ -89,7 +96,7 @@ When more than one guide describes the same concept, we make sure to use cross-r
 
 h2. Full guide list
 
- * {file:docs/GettingStarted.textile Getting Started}
+ * {file:docs/GettingStarted.textile Getting Started with Ruby amqp gem and RabbitMQ}
  * {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}
@@ -99,6 +106,7 @@ h2. Full guide list
  * {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/TestingWithEventedSpec.textile Unit and integration testing of AMQP applications}
  * {file:docs/Troubleshooting.textile Troubleshooting and debugging AMQP applications}
  * {file:docs/Clustering.textile Clustering}
  * {file:docs/RabbitMQVersions.textile RabbitMQ versions}

data/docs/ErrorHandling.textile

@@ -502,6 +502,11 @@ Error handling can be easily integrated into object-oriented Ruby code (in fact,
 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.
 
+<span class="note">
+Because channel-level exceptions may be raised because of multiple unrelated reasons and often indicate misconfigurations, how they are handled is
+very specific to particular applications. A common strategy is to log an error and then open and use another channel.
+</span>
+
 
 h3. Common channel-level exceptions and what they mean
 

data/docs/Exchanges.textile

@@ -226,7 +226,7 @@ exchange = channel.direct("nodes.metadata")
 </code>
 </pre>
 
-Both methods asynchronously declare a queue. Because the declaration necessitates a network round trip, publishing
+Both methods asynchronously declare an exchange named "nodes.metadata". Because the declaration necessitates a network round trip, publishing
 operations on {AMQP::Exchange} instances are delayed until a broker reply (`exchange.declare-ok`) is received.
 
 Also, both methods let you pass a block to run a piece of code when the broker responds with `exchange.declare-ok`

data/docs/GettingStarted.textile

@@ -47,7 +47,7 @@ On Debian and Ubuntu, you can either "download the RabbitMQ .deb package":http:/
 For RPM-based distributions like RedHat or CentOS, the RabbitMQ team provides an "RPM package":http://www.rabbitmq.com/install.html#rpm.
 
 <span class="note">
-The RabbitMQ package that ships with recent Ubuntu 10.10 versions is outdated and *will not work with v0.8.0 and later of the amqp gem* (we need at least RabbitMQ v2.0 for use with this guide).
+The RabbitMQ package that ships with recent Ubuntu versions (for example, 10.10) is outdated and *will not work with v0.8.0 and later of the amqp gem* (we need at least RabbitMQ v2.0 for use with this guide).
 </span>
 
 
@@ -58,7 +58,7 @@ h3. Make sure that you have Ruby and "Rubygems":http://docs.rubygems.org/read/ch
 
 This guide assumes that you have installed one of the following supported Ruby implementations:
 
- * Ruby v1.8.7
+ * Ruby v1.8.7 [except for 1.8.7-p248 and -p249 that have "a bug that severely affects amqp gem":http://bit.ly/iONBmH]
  * Ruby v1.9.2
  * Ruby v1.9.3
  * JRuby (we recommend v1.6)
@@ -86,7 +86,7 @@ h3. You can also use Bundler to install the gem
 <code>
 source :rubygems
 
-gem "amqp", "~> 0.8.0" # optionally: :git => "git://github.com/ruby-amqp/amqp.git", :branch => "0.8.x-stable"
+gem "amqp", "~> 0.8.4" # optionally: :git => "git://github.com/ruby-amqp/amqp.git", :branch => "0.8.x-stable"
 </code>
 </pre>
 
@@ -101,7 +101,7 @@ irb -rubygems
 :001 > require "amqp"
 => true
 :002 > AMQP::VERSION
-=> "0.8.0"
+=> "0.8.4"
 </code>
 </pre>
 

data/docs/PatternsAndUseCases.textile

@@ -33,7 +33,8 @@ There are other, more specialized group of messaging patterns that are out of sc
 This guide demonstrates implementation of several common routing patterns plus explains how built-in AMQP 0.9.1 features
 can be used to implement message construction and message transformation patterns.
 
-TBD
+Note that guide is a work in progress. There are many messaging patterns and new variations are being discovered every year.
+This guide thus strives to be useful to the 80% of developers instead of being "complete".
 
 
 
@@ -86,63 +87,12 @@ h3. Code example
 
 h4. Client code
 
-<pre>
-<code>
-require "amqp"
-
-EventMachine.run do
-  connection = AMQP.connect
-  channel    = AMQP::Channel.new(connection)
-
-  replies_queue = channel.queue("", :exclusive => true, :auto_delete => true)
-  replies_queue.subscribe do |metadata, payload|
-    puts "[response] Response for #{metadata.correlation_id}: #{payload.inspect}"
-  end
-
-  # request time from a peer every 3 seconds
-  EventMachine.add_periodic_timer(3.0) do
-    puts "[request] Sending a request..."
-    channel.default_exchange.publish("get.time",
-                                     :routing_key => "amqpgem.examples.services.time",
-                                     :message_id  => Kernel.rand(10101010).to_s,
-                                     :reply_to    => replies_queue.name,
-                                     :immediate   => true)
-  end
-
-
-  Signal.trap("INT") { connection.close { EventMachine.stop } }
-end
-</code>
-</pre>
+<script src="https://gist.github.com/1207763.js"> </script>
 
 
 h4. Server code
 
-<pre>
-<code>
-require "amqp"
-
-EventMachine.run do
-  connection = AMQP.connect
-  channel    = AMQP::Channel.new(connection)
-
-  requests_queue = channel.queue("amqpgem.examples.services.time", :exclusive => true, :auto_delete => true)
-  requests_queue.subscribe(:ack => true) do |metadata, payload|
-    puts "[requests] Got a request #{metadata.message_id}. Sending a reply..."
-    channel.default_exchange.publish(Time.now.to_s,
-                                     :routing_key    => metadata.reply_to,
-                                     :correlation_id => metadata.message_id,
-                                     :immediate      => true,
-                                     :mandatory      => true)
-
-    metadata.ack
-  end
-
-
-  Signal.trap("INT") { connection.close { EventMachine.stop } }
-end
-</code>
-</pre>
+<script src="https://gist.github.com/1207764.js"> </script>
 
 In the examples above messages are published with the :immediate attribute set. This is not necessary in all
 cases: sometimes it is OK for requests to sit in the queue without active consumers. Replies, on the other hand,
@@ -153,8 +103,13 @@ server application will log returned messages. More on this in the {file:docs/Ex
 
 h3. Related patterns
 
- * Request/Reply
- * Event
+Request/Reply demonstrates two common techniques that are sometimes referred to as messaging patterns of its own:
+
+ * "Correlation Identifier":http://www.eaipatterns.com/CorrelationIdentifier.html (for identifying what request incoming response is for)
+ * "Return Address":http://www.eaipatterns.com/ReturnAddress.html (for identifying where replies should be sent)
+
+Other related patterns are
+
  * Scatter/Gather
  * Smart Proxy
 
@@ -187,86 +142,19 @@ h4. Request message attributes
 
 <dl>
   <dt>:type</dt>
-  <dd>Message type, as a string. For example: gems.install or commands.shutdown</dd>
+  <dd>Message type as a string. For example: gems.install or commands.shutdown</dd>
 </dl>
 
 h3. Code example
 
 h4. Producer (Sender)
 
-<pre>
-<code>
-require "rubygems"
-require "amqp"
-require "yaml"
-
-t = Thread.new { EventMachine.run }
-sleep(0.5)
-
-
-connection = AMQP.connect
-channel    = AMQP::Channel.new(connection, :auto_recovery => true)
-
-channel.prefetch(1)
-
-# Acknowledgements are good for letting the server know
-# that the task is finished. If the consumer doesn't send
-# the acknowledgement, then the task is considered to be unfinished
-# and will be requeued when consumer closes AMQP connection (because of a crash, for example).
-channel.queue("amqpgem.examples.patterns.command", :durable => true, :auto_delete => false).subscribe(:ack => true) do |metadata, payload|
-  case metadata.type
-  when "gems.install"
-    data = YAML.load(payload)
-    puts "[gems.install] Received a 'gems.install' request with #{data.inspect}"
-
-    # just to demonstrate a realistic example
-    shellout = "gem install #{data[:gem]} --version '#{data[:version]}'"
-    puts "[gems.install] Executing #{shellout}"; system(shellout)
-    puts "[gems.install] Done"
-    puts
-  else
-    puts "[commands] Unknown command: #{metadata.type}"
-  end
-
-  # message is processed, acknowledge it so that broker discards it
-  metadata.ack
-end
-
-puts "[boot] Ready. Will be publishing commands every 10 seconds."
-Signal.trap("INT") { connection.close { EventMachine.stop } }
-t.join
-</code>
-</pre>
+<script src="https://gist.github.com/1207758.js"> </script>
 
 
 h4. Consumer (Recipient)
 
-<pre>
-<code>
-require "amqp"
-require "yaml"
-
-t = Thread.new { EventMachine.run }
-sleep(0.5)
-
-connection = AMQP.connect
-channel    = AMQP::Channel.new(connection)
-
-# publish new commands every 3 seconds
-EventMachine.add_periodic_timer(10.0) do
-  puts "Publishing a command (gems.install)"
-  payload = { :gem => "rack", :version => "~> 1.3.0" }.to_yaml
-
-  channel.default_exchange.publish(payload,
-                                   :type        => "gems.install",
-                                   :routing_key => "amqpgem.examples.patterns.command")
-end
-
-puts "[boot] Ready"
-Signal.trap("INT") { connection.close { EventMachine.stop } }
-t.join
-</code>
-</pre>
+<script src="https://gist.github.com/1207761.js"> </script>
 
 
 h3. Related patterns
@@ -292,6 +180,12 @@ Some specific use cases of Event pattern are
  * Live sport score updates
  * Various "push notifications" for mobile applications
 
+The Event pattern is very similar to the Command pattern, however, there is typically certain differences between the two:
+
+ * Event listeners often do not respond back to event producers
+ * Event listeners are often concerned with data collection: they update counters, persist event information and so on
+ * There may be more than event listener in the system. Commands are often carried out by one particular application
+
 
 h3. AMQP-based implementation
 
@@ -300,12 +194,31 @@ then use server-named exclusive queues and all bind to that exchange. Event mess
 attribute to indicate event type and message body (plus, possibly, message headers) to pass event
 context information.
 
+h4. Request message attributes
+
+<dl>
+  <dt>:type</dt>
+  <dd>Message type as a string. For example: files.created, files.indexed or pages.viewed</dd>
+</dl>
+
+<span class="note">
+Due to misconfiguration or different upgrade time/policy, applications may receive events they do not know how to handle.
+It is important for developers to handle such cases, otherwise it is likely that consumers may crash.
+</span>
+
 More on fanout exchange type in the {file:docs/Exchanges.textile Working With Exchanges} guide.
 
 
 h3. Code example
 
-TBD
+h4. Producer (Sender)
+
+<script src="https://gist.github.com/1207750.js"> </script>
+
+
+h4. Consumer (Handler)
+
+<script src="https://gist.github.com/1207749.js"> </script>
 
 
 h3. Related patterns
@@ -315,19 +228,23 @@ h3. Related patterns
 
 
 
+
 h2. Document Message pattern
 
 h3. Description & Use cases
 
-TBD
+Document Message pattern is very similar to Command and Event patterns. The difference is in the intent: whereas a Command message tells
+the receiver to invoke certain behavior, a Document Message just passes data and lets the receiver decide what, if anything, to do with the data.
 
-h3. AMQP-based implementation
+Message payload is a single logical entity, for example, one (or a group of closely related) database rows or documents.
 
-TBD
+Use cases for the Document Message pattern often have something to do with processing of documents:
 
-h3. Code example
+ * Indexing
+ * Archiving
+ * Content extraction
+ * Transformation (translation, transcoding and so on) of document data
 
-TBD
 
 
 h2. Competing Consumers pattern

data/docs/Queues.textile

@@ -457,6 +457,8 @@ It can be right after receiving a message, or after persisting it to a data stor
 processing the message (for example, successfully fetching a Web page, processing and storing it into some persistent
 data store).
 
+!https://github.com/ruby-amqp/amqp/raw/master/docs/diagrams/006_amqp_091_message_acknowledgements.png!
+
 If a consumer dies without sending an acknowledgement, the AMQP broker will redeliver it to another consumer, or, if
 none are available at the time, the broker will wait until at least one consumer is registered for the same queue
 before attempting redelivery.

data/docs/RabbitMQVersions.textile

@@ -13,6 +13,17 @@ h2. Covered versions
 This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
+h2. RabbitMQ Version Requirement
+
+amqp gem before 0.8.0 (0.6.x, 0.7.x) series implemented (most of) AMQP 0.8 specification. amqp gem 0.8.0 implements AMQP 0.9.1 and thus
+*requires RabbitMQ version 2.0 or later*. See {file:docs/RabbitMQVersions.textile RabbitMQ versions} for more information about
+RabbitMQ versions support and how obtain up-todate packages for your operating system.
+
+<span class="note">
+amqp gem 0.8.0 and later versions implement AMQP 0.9.1 and thus *requires RabbitMQ version 2.0 or later*
+</span>
+
+
 
 h2. Using recent versions on Debian and Ubuntu
 
@@ -22,6 +33,9 @@ that only supports AMQP protocol 0.8. Ruby amqp gem 0.8.0 and later *will not wo
 We strongly recommend that you use "RabbitMQ apt repository":http://www.rabbitmq.com/debian.html#apt that has recent versions of RabbitMQ.
 
 
+
+h2. OpsCode Chef & Puppet
+
 h3. Chef cookbook for RabbitMQ
 
 There is a "Chef cookbook for RabbitMQ":https://github.com/opscode/cookbooks/tree/master/rabbitmq that installs recent versions from

data/docs/TestingWithEventedSpec.textile

@@ -1,34 +1,36 @@
-# @title Ruby AMQP gem: Testing with Evented spec
-
-h1. Testing you applications with evented-spec
+# @title Ruby AMQP gem: Testing AMQP applications
 
+h1. Testing AMQP applications
 
 h2. About this guide
 
-This guide covers writing tests with evented-spec for amqp-based applications.
+This guide covers unit testing of amqp-based applications, primarily using "evented-spec":http://github.com/ruby-amqp/evented-spec.
+
 
 
 h2. Covered versions
 
-This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
-Also covered is the "evented-spec gem":http://github.com/ruby-amqp/evented-spec v0.4.1 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later as well as
+"evented-spec gem":http://github.com/ruby-amqp/evented-spec v0.9.0 and later.
+
 
 h2. Rationale
 
-Asynchronous environments are somewhat more difficult to test.
-There are two different approaches to testing them:
+The AMQP protocol is inherently asynchronous. Testing of asynchronous code is often more difficult
+than synchronous code. There are two approaches to it:
 
 * Stubbing out a big chunk of the environment
 * Using the "real" environment
 
-First approach is risky because your application becomes divorced from reality and what *really* happens.
-Second approach is more "correct", but at the same time much more tedious, because there are a lot of things to wrap your head around: initial setup, error handling,
-in case of amqp, also connection starting.
+The former is risky because your application becomes divorced from actual behavior of other applications.
+The latter approach is more reliable but at the same time more tedious, because there is certain amount of incidental complexity
+that "real" environment carries.
 
-However, tediousness for most part can be easily fought with proper helpers and organization. evented-spec gem
-(based on arvicco's amqp-spec and tmmm1's em-spec) provides this kind of helpers for your asynchronous applications.
+However, a lot of this complexity can be eliminated with tools and libraries. The evented-spec gem is one of those tools. It grew
+out of necessity to test "amqp Ruby gem":http://github.com/ruby-amqp/amqp and has provent itself to be both very powerful and easy to
+use. This guide covers usage of that gem in context of applications that use amqp gem but can also be useful for testing EventMachine and
+Cool.io-based applications.
 
-This guide covers usage of that gem in context of amqp but there are all the parts for testing EM-based and Cool.io-based applications.
 
 h2. Using evented-spec
 
@@ -39,27 +41,49 @@ calls to your examples:
 
 <script src="https://gist.github.com/1027377.js"></script>
 
-h3. Implications of asynchronous environment (or why we need #done)
+
+
+h3. Testing in the Asynchronous Environment
 
 Since we are using callback mechanisms in order to provide asynchronicity, we have to deal with situation when we expect a response,
 and response never comes. Usual solution includes setting a timeout which makes the given tests fail if they aren't finished in a timely
 manner. When <code>#done</code> is called, your tests confirm successful ending of specs. Try removing <code>done</code> from the above
 example and see what happens. (spoiler: <code>EventedSpec::SpecHelper::SpecTimeoutExceededError: Example timed out</code>)
 
-h3. Changing default connection options and default timeout
 
-It is not uncommon to have custom options for your test environment. For example, setting up custom vhost and timeout:
+
+h3. The #done method
+
+The *#done* method call is a hint for evented-spec to consider the example finished. If this method is not called, example will be forcefully
+terminated after a certain period of time or "time out". This means there are two approaches to testing of asynchronous code:
+
+ * Have timeout value high enough for all operations to finish (for example, expected number of messages is received).
+ * Call #done when some condition holds true (for example, message with a specific property or payload is received).
+
+The latter approach is recommended because it makes tests less dependent on machine-specific throughput or timing: it is very
+common for continuous integration environments to use virtual machines that are significantly less powerful than machines developers
+use, so timeouts have to be carefully adjusted to work in both settings.
+
+
+
+h3. Default Connection Options and Timeout
+
+It is sometimes desirable to use custom connection settings for your test environment as well as the default timeout value used. evented-spec lets you do
+it:
 
 <script src="https://gist.github.com/1027410.js"> </script>
 
-Options are the same as used in <code>AMQP.connect</code>.
+Available options are passed to {AMQP.connect} so it is possible to specify host, port, vhost, username and password your test suite needs.
+
+
 
-h3. Callbacks
+h3. Lifecycle Callbacks
 
 evented-spec provides various callbacks similar to rspec's <code>before(:each)</code> / <code>after(:each)</code>. They are called <code>amqp_before</code> and
 <code>amqp_after</code> and happen right after connection is established or before connection is closed. It is a good place to put your channel initialization routines.
 
-h3. Example of a meaningful spec
+
+h3. Full Example
 
 Now that you're filled on theory part, it's time to do something with all this knowledge. Below goes a slightly modified version of one of the integration specs from AMQP
 suite. It sets up default topic exchange and publishes various messages about sports events:
@@ -69,7 +93,9 @@ suite. It sets up default topic exchange and publishes various messages about sp
 Couple of things to notice: <code>#done</code> is invoked using an optional callback and optional delay, also instance variables behavior in hooks is the same as in "normal" rspec
 hooks.
 
-h3. Using #delayed in your specs
+
+
+h3. Using #delayed
 
 AMQP gem uses "EventMachine":http://eventmachine.rubyforge.org/ under hood. If you don't know about eventmachine, you can read more about it on the official site.
 What's important for us is that you *cannot use <code>sleep</code> for delays*. Why? Because all the specs code is processed directly in the "reactor":http://en.wikipedia.org/wiki/Reactor_pattern thread, if you
@@ -83,16 +109,34 @@ In the following example, we declare two channels, then declare the same queue t
 
 If you draw a timeline, various events happen at 0.0s, then at 0.1s, then at 0.3s and eventually at 0.4s.
 
-h3. What happens under hood
 
-When you include <code>EventedSpec::AMQPSpec</code> module, <code>#it</code> calls are wrapped in <code>EM.start</code> + <code>AMQP.connect</code>
-calls, so you can start writing your examples as if you're connected. You still need to initialize your own channel though.
+h3. Design For Testability
+
+As *Integration With Objects* section of the {file:docs/GettingStarted.textile Getting Started with Ruby amqp gem and RabbitMQ} demonstrates, good object-oriented design
+often makes it possible to test AMQP consumers in isolation without connecting to the broker or even starting EventMachine even loop. All the "Design for testability"
+practices apply fully to AMQP application testing.
+
+
+
+h3. Real worldExamples
+
+Please refer to the "amqp gem test suite":https://github.com/ruby-amqp/amqp/tree/master/spec to see evented-spec in action.
+
+
+
+h3. How evented-spec Works
+
+When you include <code>EventedSpec::AMQPSpec</code> module, <code>#it</code> calls are wrapped in <code>EventMachine.start</code> + <code>AMQP.connect</code>
+calls, so you can start writing your examples as if you're connected. Please note that you still need to open your own channel(s).
+
 
 
 h2. What to read next
 
-There is a lot more to evented-spec than described in this guide. evented-spec has "rdocs":http://rdoc.info/github/ruby-amqp/evented-spec/master,
-which I strongly suggest to read in case you don't understand some parts of the gem.
+There is a lot more to evented-spec than described in this guide. "evented-spec documentation":http://rdoc.info/github/ruby-amqp/evented-spec/master
+covers that gem in more detail gem. For more code examples, see "amqp Ruby gem test suite":https://github.com/ruby-amqp/amqp/tree/master/spec.
+
+
 
 h2. Tell us what you think!
 

data/docs/VendorSpecificExtensions.textile

@@ -72,6 +72,10 @@ In some situations not a single message can be lost. The only reliable way of do
 Publisher confirms are similar to message acknowledgements documented in the {file:docs/Queues.textile Working With Queues} guide but involve publisher and AMQP broker
 instead of consumer and AMQP broker.
 
+!https://github.com/ruby-amqp/amqp/raw/master/docs/diagrams/006_amqp_091_message_acknowledgements.png!
+
+!https://github.com/ruby-amqp/amqp/raw/master/docs/diagrams/007_rabbitmq_publisher_confirms.png!
+
 
 h3. Public API
 

data/examples/error_handling/automatically_recovering_hello_world_consumer.rb

@@ -43,7 +43,7 @@ AMQP.start(:host => "localhost") do |connection, open_ok|
 
   Signal.trap "TERM", show_stopper
   Signal.trap "INT",  show_stopper
-  EM.add_timer(45, show_stopper)
+  EM.add_timer(ENV.fetch("TIMER", 45), show_stopper)
 
 
   puts "This example needs another script/app to publish messages to amq.fanout. See examples/error_handling/hello_world_producer.rb for example"

data/examples/error_handling/connection_loss_handler.rb

@@ -12,7 +12,7 @@ require 'amqp'
 puts "=> Connection loss is detected and handled"
 puts
 AMQP.start(:port     => 5672,
-           :vhost    => "/amq_client_testbed",
+           :vhost    => "amq_client_testbed",
            :user     => "amq_client_gem",
            :password => "amq_client_gem_password",
            :timeout        => 0.3,

data/examples/error_handling/hello_world_producer.rb

@@ -16,17 +16,29 @@ AMQP.start(:host => "localhost") do |connection, open_ok|
     raise connection_close.reply_text
   end
 
-  ch1 = AMQP::Channel.new(connection, 2)
+  connection.on_tcp_connection_loss do |conn, settings|
+    puts "[network failure] Trying to reconnect..."
+    conn.reconnect(false, 2)
+  end
+
+
+  ch1 = AMQP::Channel.new(connection, 2, :auto_recovery => true)
   ch1.on_error do |ch, channel_close|
     raise channel_close.reply_text
   end
 
 
   exchange = ch1.fanout("amq.fanout", :durable => true)
-  EventMachine.add_periodic_timer(0.5) do
-    puts "Publishing..."
+  EventMachine.add_periodic_timer(0.9) do
+    puts "Publishing via default exchange..."
+    # messages must be routable & there must be at least one consumer.
+    ch1.default_exchange.publish("Routed via default_exchange", :routing_key => "amqpgem.examples.autorecovery.queue")
+  end
+
+  EventMachine.add_periodic_timer(0.8) do
+    puts "Publishing via amq.fanout..."
     # messages must be routable & there must be at least one consumer.
-    exchange.publish("Hello", :immediate => true, :mandatory => true)
+    exchange.publish("Routed via amq.fanout", :immediate => true, :mandatory => true)
   end
 
 
@@ -36,7 +48,7 @@ AMQP.start(:host => "localhost") do |connection, open_ok|
 
   Signal.trap "TERM", show_stopper
   Signal.trap "INT",  show_stopper
-  EM.add_timer(15, show_stopper)
+  EM.add_timer(ENV.fetch("TIMER", 15), show_stopper)
 
   puts "This example a helper that publishes messages to amq.fanout. Use together with examples/error_handling/automatically_recovering_hello_world_consumer.rb."
   puts "This example terminates in 15 seconds and needs MANUAL RESTART when connection fails"

data/examples/error_handling/reopening_a_channel_after_channel_level_exception.rb

@@ -0,0 +1,67 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+
+puts "=> Queue redeclaration with different attributes results in a channel exception that is handled"
+puts
+EventMachine.run do
+  connection = AMQP.connect
+  AMQP::Channel.new(connection, :auto_recovery => true) do |channel, open_ok|
+    puts "Channel ##{channel.id} is now open!"
+
+    connection.on_error do |conn, connection_close|
+      puts <<-ERR
+      Handling a connection-level exception:
+
+      connection_close.reply_text: #{connection_close.reply_text}
+      ERR
+    end
+
+    channel.on_error do |ch, channel_close|
+      puts <<-ERR
+      Handling a channel-level exception.
+
+      AMQP class id : #{channel_close.class_id},
+      AMQP method id: #{channel_close.method_id},
+      Status code   : #{channel_close.reply_code}
+      Error message : #{channel_close.reply_text}
+      ERR
+
+      puts "Reusing channel #{ch.id}"
+      ch.reuse
+      puts "Channel id is now #{ch.id}"
+    end
+
+    EventMachine.add_timer(1.0) do
+      # these two definitions result in a race condition. For sake of this example,
+      # however, it does not matter. Whatever definition succeeds first, 2nd one will
+      # cause a channel-level exception (because attributes are not identical)
+      AMQP::Queue.new(channel, "amqpgem.examples.channel_exception", :auto_delete => true, :durable => false) do |queue|
+        puts "#{queue.name} is ready to go"
+      end
+
+      AMQP::Queue.new(channel, "amqpgem.examples.channel_exception", :auto_delete => true, :durable => true) do |queue|
+        puts "#{queue.name} is ready to go"
+      end
+    end
+  end
+
+
+  show_stopper = Proc.new do
+    $stdout.puts "Stopping..."
+
+    connection.close {
+      EM.stop { exit }
+    }
+  end
+
+  Signal.trap "INT", show_stopper
+  # EM.add_timer(2, show_stopper)
+end

data/examples/patterns/command/producer.rb

@@ -11,7 +11,7 @@ sleep(0.5)
 connection = AMQP.connect
 channel    = AMQP::Channel.new(connection)
 
-# publish new commands every 3 seconds
+# publish new commands every few seconds
 EventMachine.add_periodic_timer(10.0) do
   puts "Publishing a command (gems.install)"
   payload = { :gem => "rack", :version => "~> 1.3.0" }.to_yaml

data/examples/patterns/event/consumer.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift File.expand_path("../../../../lib", __FILE__)
+
+require "amqp"
+require "yaml"
+
+t = Thread.new { EventMachine.run }
+sleep(0.5)
+
+
+connection = AMQP.connect
+channel    = AMQP::Channel.new(connection, :auto_recovery => true)
+channel.on_error do |ch, channel_close|
+  raise "Channel-level exception: #{channel_close.reply_text}"
+end
+
+channel.prefetch(1)
+
+channel.queue("", :durable => false, :auto_delete => true).bind("amqpgem.patterns.events").subscribe do |metadata, payload|
+  begin
+    body = YAML.load(payload)
+
+    case metadata.type
+    when "widgets.created"   then
+      puts "A widget #{body[:id]} was created"
+    when "widgets.destroyed" then
+      puts "A widget #{body[:id]} was destroyed"
+    when "files.created"     then
+      puts "A new file (#{body[:filename]}, #{body[:sha1]}) was uploaded"
+    when "files.indexed"     then
+      puts "A new file (#{body[:filename]}, #{body[:sha1]}) was indexed"
+    else
+      puts "[warn] Do not know how to handle event of type #{metadata.type}"
+    end
+  rescue Exception => e
+    puts "[error] Could not handle event of type #{metadata.type}: #{e.inspect}"
+  end
+end
+
+puts "[boot] Ready"
+Signal.trap("INT") { connection.close { EventMachine.stop } }
+t.join

data/examples/patterns/event/producer.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift File.expand_path("../../../../lib", __FILE__)
+
+require "amqp"
+require "yaml"
+
+t = Thread.new { EventMachine.run }
+sleep(0.5)
+
+connection = AMQP.connect
+channel    = AMQP::Channel.new(connection)
+exchange   = channel.fanout("amqpgem.patterns.events", :durable => true, :auto_delete => false)
+
+
+EVENTS     = {
+  "pages.show" => {
+    :url      => "https://mysite.local/widgets/81772",
+    :referrer => "http://www.google.com/search?client=safari&rls=en&q=widgets&ie=UTF-8&oe=UTF-8"
+  },
+  "widgets.created" => {
+    :id       => 10,
+    :shape    => "round",
+    :owner_id => 1000
+  },
+  "widgets.destroyed" => {
+    :id        => 10,
+    :person_id => 1000
+  },
+  "files.created" => {
+    :sha1      => "1a62429f47bc8b405d17e84b648f2fbebc555ee5",
+    :filename  => "document.pdf"
+  },
+  "files.indexed" => {
+    :sha1      => "1a62429f47bc8b405d17e84b648f2fbebc555ee5",
+    :filename  => "document.pdf",
+    :runtime   => 1.7623,
+    :shared    => "shard02"
+  }
+}
+
+def generate_event
+  n       = (EVENTS.size * Kernel.rand).floor
+  type    = EVENTS.keys[n]
+  payload = EVENTS[type]
+
+  [type, payload]
+end
+
+# broadcast events
+EventMachine.add_periodic_timer(2.0) do
+  event_type, payload = generate_event
+
+  puts "Publishing a new event of type #{event_type}"
+  exchange.publish(payload.to_yaml, :type => event_type)
+end
+
+puts "[boot] Ready. Will be publishing events every few seconds."
+Signal.trap("INT") { connection.close { EventMachine.stop } }
+t.join

data/examples/queues/cancel_default_consumer.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+EventMachine.run do
+  connection = AMQP.connect(:host => '127.0.0.1')
+  puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+
+  channel  = AMQP::Channel.new(connection)
+  queue    = channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
+  exchange = channel.direct("amq.direct")
+
+  queue.bind(exchange, :routing_key => "amqpgem.key")
+
+  channel.on_error do |ch, channel_close|
+    puts channel_close.reply_text
+    connection.close { EventMachine.stop }
+  end
+
+  queue.subscribe do |metadata, payload|
+    puts "Received a message: #{payload}."
+  end
+
+  EventMachine.add_periodic_timer(1.0) do
+    exchange.publish("Hey, what a great view!", :routing_key => "amqpgem.key")
+  end
+
+  EventMachine.add_timer(3.0) do
+    queue.unsubscribe do
+      puts "Cancelled default consumer..."
+      connection.close { EventMachine.stop }
+    end
+  end
+end

data/lib/amqp/channel.rb

@@ -265,7 +265,7 @@ module AMQP
         @channel_is_open_deferrable.succeed
 
         # exchanges must be recovered first because queue recovery includes recovery of bindings. MK.
-        @exchanges.each { |name, e| e.auto_recover }
+        @exchanges.each { |name, e| puts("Recovering ex #{name}"); e.auto_recover }
         @queues.each    { |name, q| q.auto_recover }
       end
     end # auto_recover
@@ -423,7 +423,7 @@ module AMQP
     # @return [Exchange]
     # @api public
     def default_exchange
-      Exchange.default(self)
+      @default_exchange ||= Exchange.default(self)
     end
 
     # Defines, intializes and returns a fanout Exchange instance.

data/lib/amqp/exchange.rb

@@ -300,12 +300,12 @@ module AMQP
       @channel             = channel
       @type                = type
       @opts                = self.class.add_default_options(type, name, opts, block)
-      @default_routing_key = opts[:routing_key] || opts[:key]
+      @default_routing_key = opts[:routing_key] || opts[:key] || AMQ::Protocol::EMPTY_STRING
       @name                = name unless name.empty?
 
       @status                  = :unknown
       @default_publish_options = (opts.delete(:default_publish_options) || {
-                                    :routing_key  => AMQ::Protocol::EMPTY_STRING,
+                                    :routing_key  => @default_routing_key,
                                     :mandatory    => false,
                                     :immediate    => false
                                   }).freeze

data/lib/amqp/queue.rb

@@ -775,7 +775,7 @@ module AMQP
     # unsubscription request is acknowledged as complete by the server.
     #
     # @option opts [Boolean] :nowait (true)  If set, the server will not respond to the method. The client should
-    #                                        not wait for a reply method.  If the server could not complete the
+    #                                        not wait for a reply method, the callback (if passed) will be ignored. If the server could not complete the
     #                                        method it will raise a channel or connection exception.
     #
     # @yield [cancel_ok]

data/lib/amqp/version.rb

@@ -6,5 +6,5 @@ module AMQP
   #
   # @see AMQ::Protocol::VERSION
   # @return [String] AMQP gem version
-  VERSION = '0.8.4'
+  VERSION = '0.9.0.pre1'
 end

data/spec/integration/exchange_declaration_spec.rb

@@ -23,6 +23,75 @@ describe AMQP::Channel do
   # Examples
   #
 
+
+  describe "default exchange" do
+    subject do
+      @channel.default_exchange
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+  describe "exchange named amq.direct" do
+    subject do
+      @channel.direct("amq.direct")
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+  describe "exchange named amq.fanout" do
+    subject do
+      @channel.direct("amq.fanout")
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+  describe "exchange named amq.topic" do
+    subject do
+      @channel.direct("amq.topic")
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+  describe "exchange named amq.match" do
+    subject do
+      @channel.direct("amq.match")
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+  describe "exchange named amq.headers" do
+    subject do
+      @channel.direct("amq.headers")
+    end
+
+    it "is predefined" do
+      subject.should be_predefined
+      done
+    end
+  end
+
+
+
   describe "#direct" do
     context "when exchange name is specified" do
       it 'declares a new direct exchange with that name' do

data/spec/integration/regressions/concurrent_publishing_on_the_same_channel_spec.rb

@@ -61,7 +61,7 @@ if mri?
       queue    = @channel.queue("amqpgem.tests.concurrent_publishing", :auto_delete => true)
       exchange = @channel.default_exchange
       exchange.on_return do |method, header, body|
-        raise "Message was returned: #{method.reply_text}"
+        puts "Message was returned: #{method.reply_text}"
       end
 
       queue.subscribe do |metadata, payload|

metadata

@@ -1,13 +1,15 @@
 --- !ruby/object:Gem::Specification 
 name: amqp
 version: !ruby/object:Gem::Version 
-  hash: 55
-  prerelease: 
+  hash: 1923831867
+  prerelease: 6
   segments: 
   - 0
-  - 8
-  - 4
-  version: 0.8.4
+  - 9
+  - 0
+  - pre
+  - 1
+  version: 0.9.0.pre1
 platform: ruby
 authors: 
 - Aman Gupta
@@ -17,7 +19,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-04 00:00:00 Z
+date: 2012-01-01 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: eventmachine
@@ -131,6 +133,8 @@ files:
 - docs/diagrams/003_weathr_example_routing.png
 - docs/diagrams/004_fanout_exchange.png
 - docs/diagrams/005_direct_exchange.png
+- docs/diagrams/006_amqp_091_message_acknowledgements.png
+- docs/diagrams/007_rabbitmq_publisher_confirms.png
 - docs/diagrams/redhat/direct_exchange.png
 - docs/diagrams/redhat/fanout_exchange.png
 - docs/diagrams/redhat/topic_exchange.png
@@ -159,6 +163,7 @@ files:
 - examples/error_handling/manual_connection_and_channel_recovery.rb
 - examples/error_handling/queue_exclusivity_violation.rb
 - examples/error_handling/queue_name_violation.rb
+- examples/error_handling/reopening_a_channel_after_channel_level_exception.rb
 - examples/error_handling/tcp_connection_failure_handling_with_a_rescue_block.rb
 - examples/error_handling/tcp_connection_failure_with_a_callback.rb
 - examples/exchanges/autodeletion_of_exchanges.rb
@@ -210,6 +215,8 @@ files:
 - examples/legacy/stocks.rb
 - examples/patterns/command/consumer.rb
 - examples/patterns/command/producer.rb
+- examples/patterns/event/consumer.rb
+- examples/patterns/event/producer.rb
 - examples/patterns/request_reply/client.rb
 - examples/patterns/request_reply/server.rb
 - examples/publishing/publishing_a_one_off_message.rb
@@ -219,6 +226,7 @@ files:
 - examples/queues/accessing_message_metadata.rb
 - examples/queues/automatic_binding_for_default_direct_exchange.rb
 - examples/queues/basic_get.rb
+- examples/queues/cancel_default_consumer.rb
 - examples/queues/declare_a_queue_without_assignment.rb
 - examples/queues/declare_and_bind_a_server_named_queue.rb
 - examples/queues/queue_status.rb
@@ -348,12 +356,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version 
-      hash: 3
+      hash: 25
       segments: 
-      - 0
-      version: "0"
+      - 1
+      - 3
+      - 1
+      version: 1.3.1
 requirements: []
 
 rubyforge_project: amqp