amqp 0.8.0.rc12 → 0.8.0.rc13

data/docs/RabbitMQVersions.textile

@@ -1,10 +1,23 @@
-h1. amqp gem and RabbitMQ versions compatibility
+# @title Ruby AMQP gem: RabbitMQ versions compatibility
+
+h1. Ruby amqp gem and RabbitMQ versions compatibility
+
+h2. About this guide
+
+This guide covers compatibility of the "Ruby amqp gem":http://github.com/ruby-amqp/amqp with various versions of "RabbitMQ":http://rabbitmq.com messaging broker.
+
+
+
+h2. Covered versions
+
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.6.0 and later.
+
+
 
 h2. Using recent versions on Debian and Ubuntu
 
 Ubuntu (even 10.10) and Debian both "ship with old RabbitMQ version":http://packages.ubuntu.com/maverick/rabbitmq-server,
-that only supports AMQP protocol 0.8. amqp gem 0.8.0 and later *will not work with RabbitMQ versions
-before 2.0.0*.
+that only supports AMQP protocol 0.8. Ruby amqp gem 0.8.0 and later *will not work with RabbitMQ versions before 2.0.0*.
 
 We strongly recommend that you use "RabbitMQ apt repository":http://www.rabbitmq.com/debian.html#apt that has recent versions of RabbitMQ.
 
@@ -29,3 +42,21 @@ what was unclear? what wasn't covered? maybe you don't like guide style or gramm
 key to making 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
+
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    /* * * CONFIGURATION VARIABLES * * */
+    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname
+
+    var disqus_developer = 0; // set to 1 on local machine for testing comments
+    var disqus_identifier = 'amqp_rabbitmq_versions';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/RabbitMQVersions.textile';
+
+    /* * * DON'T EDIT BELOW THIS LINE * * */
+    (function() {
+        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+    })();
+</script>

data/docs/Routing.textile

@@ -1,3 +1,6 @@
+# @title Ruby AMQP gem: Routing
+
+
 h1. TBD
 
 
@@ -8,7 +11,7 @@ TBD
 
 h2. Covered versions
 
-This guide covers amqp gem v0.8.0 and later.
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
 
 
 

data/docs/RunningTests.textile

@@ -0,0 +1,116 @@
+# @title Ruby AMQP gem: Running tests
+
+h1. Running amqp gem test suite
+
+
+h2. About this guide
+
+This guide is for people who want to contribute to amqp gem development. It has no relevant information for those
+who want to build applications using the library.
+
+
+h2. Covered versions
+
+Not applicable.
+
+
+
+
+h2. Canonical repository
+
+Since late 2010, the canonical amqp gem repository is at "github.com/ruby-amqp/amqp":https://github.com/ruby-amqp/amqp and *not tmm1/amqp*.
+
+
+
+h2. Initial setup
+
+amqp gem currently uses recent releases of RabbitMQ for automated tests. Broker installation is described in the {file:docs/GettingStarted.textile Getting started} guide
+and on "rabbitmq.com":http://www.rabbitmq.com/install.html. Once the broker is running, the only other step is to run
+
+<pre><code>
+./bin/set_test_suite_realms_up.sh
+</code></pre>
+
+that will set up vhosts and users we test authentication and authorization against. Please note that the script uses `rabbitmqctl` tool
+and in the server environment (for example, a virtual instance in the cloud) depending on your OS and/or distribution of choice, that tool
+may or may not be accessible to your OS user, so pay attention to that.
+
+
+
+h2. Dependencies
+
+Dependencies are managed by Bundler. So begin with
+
+<pre><code>
+gem install bundler --version "~> 1.0.13"
+</code></pre>
+
+and then, from the root of the repository run
+
+<pre><code>
+bundle install
+</code></pre>
+
+and you are good to go.
+
+
+
+
+h2. Running spec examples
+
+During development, it is sufficient to just use
+
+<pre><code>
+bundle exec rspec -c ./spec
+</code></pre>
+
+or replace ./spec with an individual file you want to run.
+
+
+
+
+h2. Continuous integration
+
+CI happens in two steps:
+
+ * Clean up *.rbc files produced by "Rubinius":http://rubini.us.
+ * Run the whole test suite
+
+For that, we use Rake:
+
+<pre><code>
+rake spec:ci
+</code></pre>
+
+Thanks to the excellent "Travis CI":http://travis-ci.org project, we run test suites across 5 Ruby implementations and 2 EventMachine versions, and can
+add more implementations/versions so easily it still seems unreal.
+
+
+
+
+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.
+
+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
+
+
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    /* * * CONFIGURATION VARIABLES * * */
+    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname
+
+    var disqus_developer = 0; // set to 1 on local machine for testing comments
+    var disqus_identifier = 'amqp_running_tests_textile';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/RunningTests.textile';
+
+    /* * * DON'T EDIT BELOW THIS LINE * * */
+    (function() {
+        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+    })();
+</script>

data/docs/Troubleshooting.textile

@@ -0,0 +1,131 @@
+# @title Ruby AMQP gem: Troubleshooting and debugging AMQP applications
+
+h1. Troubleshooting and debugging AMQP applications
+
+
+h2. About this guide
+
+This guide describes tools and strategies that help in troubleshooting and debugging applications that use AMQP in general and "Ruby AMQP gem":http://github.com/ruby-amqp/amqp
+in particular.
+
+
+h2. Covered versions
+
+This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.
+
+
+
+h2. First steps
+
+Whenever something doesn't work, check the following things before asking on the mailing list:
+
+ * AMQP broker log.
+ * List of users in a particular vhost you are trying to connect.
+ * Network connectivity. We know, it's obvious, yet even experienced developers and devops engineers struggle with network access misconfigurations every once in a while.
+ * If EventMachine is started in a separate thread, make sure that isn't dead. If it is, this usually means there was an exception that caused it to terminate,
+   or environment it is running in "mixes threads and fork(2) system call":http://bit.ly/fork-and-threads.
+
+
+
+h2. Inspecting AMQP broker log file
+
+In this section we will cover typical problems that can be tracked down by reading AMQP broker log. We will use RabbitMQ as an example, however, different AMQP brokers
+often log most of the same issues.
+
+RabbitMQ logs abrupt TCP connection failures, timeouts, protocol version mismatches and so on.
+If you are running RabbitMQ, log locations for various operating systems and distributions is documented in the "RabbitMQ installation guide":http://www.rabbitmq.com/install.html
+
+On Mac OS X, RabbitMQ installed via Homebrew logs to $HOMEBREW_HOME/var/log/rabbitmq/rabbit@$HOSTNAME.log. For example, if you have Homebrew installed at /usr/local and
+your hostname is giove, log will be at /usr/local/var/log/rabbitmq/rabbit@giove.log.
+
+Here is what authentication failure looks like in RabbitMQ log:
+
+<pre>
+=ERROR REPORT==== 17-May-2011::17:37:58 ===
+exception on TCP connection <0.4770.0> from 127.0.0.1:46551
+{channel0_error,starting,
+                {amqp_error,access_refused,
+                            "AMQPLAIN login refused: user 'pipeline_agent' - invalid credentials",
+                            'connection.start_ok'}}
+</pre>
+
+This means that connection attempt with username pipeline_agent failed because credentials were invalid. If you are seeing this message, make sure username,
+password *and vhost* are correct.
+
+
+The following entry:
+
+<pre>
+=ERROR REPORT==== 17-May-2011::17:26:28 ===
+exception on TCP connection <0.4201.62> from 10.8.0.30:57990
+{bad_header,<<65,77,81,80,0,0,9,1>>}
+</pre>
+
+Means that client supports AMQP 0.9.1 but broker doesn't (RabbitMQ versions pre-2.0 only support AMQP 0.8, for example). If you are using amqp gem 0.8 or later
+and seeing this entry in your broker log, you are connecting to AMQP broker that is too old to support this AMQP version. In case of RabbitMQ, make sure you run
+version 2.0 or later.
+
+TBD
+
+
+
+h2. Testing network connection with AMQP broker using Telnet
+
+One simple way to check network connection between a particular network node and a node running AMQP broker is to use `telnet`:
+
+<pre>
+telnet [host or ip] 5672
+</pre>
+
+then enter any random string of text and hit Enter. AMQP broker should immediately close down the connection. Here is an example
+session:
+
+<pre>
+telnet localhost 5672
+Connected to localhost.
+Escape character is '^]'.
+adjasd
+AMQP    Connection closed by foreign host.
+</pre>
+
+If instead Telnet exits after printing
+
+<pre>
+telnet: connect to address [host or ip]: Connection refused
+telnet: Unable to connect to remote host
+</pre>
+
+then connection from the machine you are running Telnet tests on and AMQP broker fails. This can be due to many different reasons, but
+it is a good idea to check these two things first:
+
+ * Firewall configuration for port 5672
+ * DNS setup (if hostname is used)
+
+
+
+
+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.
+
+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
+
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    /* * * CONFIGURATION VARIABLES * * */
+    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname
+
+    var disqus_developer = 0; // set to 1 on local machine for testing comments
+    var disqus_identifier = 'amqp_troubleshooting';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/Troubleshooting.textile';
+
+    /* * * DON'T EDIT BELOW THIS LINE * * */
+    (function() {
+        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+    })();
+</script>

data/docs/VendorSpecificExtensions.textile

@@ -1,3 +1,5 @@
+# @title Ruby AMQP gem: Using vendor-specific AMQP extensions
+
 h1. Vendor-specific AMQP extensions support in amqp gem
 
 h2. RabbitMQ extensions
@@ -40,3 +42,21 @@ what was unclear? what wasn't covered? maybe you don't like guide style or gramm
 key to making 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
+
+
+<div id="disqus_thread"></div>
+<script type="text/javascript">
+    /* * * CONFIGURATION VARIABLES * * */
+    var disqus_shortname = 'rubyamqpdocs'; // required: replace example with your forum shortname
+
+    var disqus_developer = 0; // set to 1 on local machine for testing comments
+    var disqus_identifier = 'amqp_vendor_specific_extensions';
+    var disqus_url = 'http://rdoc.info/github/ruby-amqp/amqp/master/file/docs/VendorSpecificExtensions.textile';
+
+    /* * * DON'T EDIT BELOW THIS LINE * * */
+    (function() {
+        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
+        dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
+        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
+    })();
+</script>

data/examples/channels/qos_aka_prefetch.rb

@@ -13,8 +13,8 @@ puts "=> Channel#prefetch"
 puts
 AMQP.start(:host => 'localhost') do |connection|
   ch = AMQP::Channel.new
-  ch.on_error do |ex|
-    raise "Oops! there has been a channel-level exception"
+  ch.on_error do |ch, channel_close|
+    raise "Oops! a channel-level exception: #{channel_close.inspect}"
   end
   ch.prefetch(1, false) do |_|
     puts "qos callback has fired"
@@ -29,6 +29,6 @@ AMQP.start(:host => 'localhost') do |connection|
     }
   end
 
-  Signal.trap "INT", show_stopper
+  Signal.trap "INT", &show_stopper
   EM.add_timer(1, show_stopper)
 end

data/examples/channels/qos_aka_prefetch_without_callback.rb

@@ -13,8 +13,8 @@ puts "=> Channel#prefetch"
 puts
 AMQP.start(:host => 'localhost') do |connection|
   ch = AMQP::Channel.new
-  ch.on_error do |ex|
-    raise "Oops! there has been a channel-level exception"
+  ch.on_error do |ch, channel_close|
+    raise "Oops! a channel-level exception: #{channel_close.inspect}"
   end
   ch.prefetch(1, false)
 

data/examples/error_handling/channel_level_exception.rb

@@ -16,7 +16,7 @@ AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
     puts "Channel ##{channel.id} is now open!"
 
     channel.on_error do |ch, close|
-      puts "Handling channel-level exception"
+      puts "Handling a channel-level exception: #{close.reply_text}"
     end
 
     EventMachine.add_timer(0.4) do

data/examples/error_handling/channel_level_exception_with_multiple_channels_involved.rb

@@ -23,6 +23,7 @@ AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
     puts "Channel ##{ch.id} is now open!"
   end
   ch2.on_error do |ch, close|
+    puts "close: #{close.inspect}"
     puts "Handling channel-level exception on channel with id of #{ch.id} (ch2)"
   end
 

data/examples/error_handling/connection_level_exception.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+EventMachine.run do
+  AMQP.connect(:host => '127.0.0.1', :port => 5672) do |connection|
+    puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+
+
+    connection.on_error do |conn, connection_close|
+      puts "Handling a connection-level exception: #{connection_close.reply_text}"
+
+      EventMachine.stop
+    end
+
+    # send_frame is NOT part of the public API, but it is public for entities like AMQ::Client::Channel
+    # and we use it here to trigger a connection-level exception. MK.
+    connection.send_frame(AMQ::Protocol::Connection::TuneOk.encode(1000, 1024 * 128 * 1024, 10))
+  end
+end

data/examples/error_handling/global_channel_level_exception_handler.rb

@@ -32,12 +32,12 @@ AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     puts "Channel ##{channel.id} is now open!"
 
-    channel.on_error do |ch, close|
+    channel.on_error do |ch, channel_close|
       puts "Handling channel-level exception at instance level"
     end
 
-    AMQP::Channel.on_error do |message|
-      puts "Handling channel-level exception at GLOBAL level. Jeez. Message is #{message}"
+    AMQP::Channel.on_error do |ch, channel_close|
+      puts "Handling channel-level exception at GLOBAL level. Jeez. Message is #{channel_close.reply_text}"
     end
 
     EventMachine.add_timer(0.4) do

data/examples/exchanges/autodeletion_of_exchanges.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+
+puts "=> Exchange#initialize example that uses :auto_delete => true"
+puts
+AMQP.start(:host => 'localhost', :port => 5673) do |connection|
+  AMQP::Channel.new do |channel, open_ok|
+    puts "Channel ##{channel.id} is now open!"
+
+    AMQP::Exchange.new(channel, :direct, "amqpgem.examples.xchange2", :auto_delete => false) do |exchange|
+      puts "#{exchange.name} is ready to go"
+    end
+
+    AMQP::Exchange.new(channel, :direct, "amqpgem.examples.xchange3", :auto_delete => true) do |exchange|
+      puts "#{exchange.name} is ready to go"
+    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