amqp 0.8.0.rc11 → 0.8.0.rc12

data/CHANGELOG

@@ -1,5 +1,6 @@
 = Version 0.8.0
 
+  * [API] Connection URI (string) format for vhosts no longer assumes that vhosts begin with a slash (/), learn more at http://bit.ly/mfzwcB
   * [FEATURE] Returned messages, including header & content via AMQP::Exchange#on_publish. Callback accepts 3 args: basic_return, header, body
   * [BUG] Ruby 1.8.7-p249 is not supported because of this (p249-specific) Ruby bug: http://bit.ly/iONBmH
   * [FEATURE] AMQP::Utilities::EventLoopHelper detects app server (if any) being used and starts EventMachine reactor in an optimal way.

data/Gemfile

@@ -19,7 +19,7 @@ custom_gem "amq-client",   :git => "git://github.com/ruby-amqp/amq-client.git",
 custom_gem "amq-protocol", :git => "git://github.com/ruby-amqp/amq-protocol.git", :branch => "master"
 
 group(:development) do
-  gem "yard"
+  gem "yard", ">= 0.7.0"
   # yard tags this buddy along
   gem "RedCloth"
 
@@ -29,6 +29,7 @@ group(:development) do
   # To test event loop helper and various Rack apps
   gem "thin"
   gem "unicorn", :platform => :ruby
+  gem "changelog"
 end
 
 group(:test) do

data/amqp.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
 
   # Dependencies
   s.add_dependency "eventmachine"
-  s.add_dependency "amq-client", ">= 0.7.0.alpha23"
+  s.add_dependency "amq-client", ">= 0.7.0.alpha25"
 
   begin
     require "changelog"

data/docs/ConnectingToTheBroker.textile

@@ -23,8 +23,86 @@ server and code required to establish connection to AMQP broker needs to be a li
 bit different.
 
 
+h2. Two ways to specify connection parameters
 
-h2. In standalone applications
+Connection parameters (host, port, username, vhost and so on) can be passed in two forms:
+
+ * As a hash
+ * As a connection URI string (à la JDBC)
+
+
+h3. Using a hash
+
+Hash options amqp gem will recognize are
+
+ * :host
+ * :port
+ * :username (aliased as :user)
+ * :password (aliased as :pass)
+ * :vhost
+ * :ssl
+ * :timeout
+ * :frame_max
+
+h4. Default parameters
+
+Default connection parameters are
+
+<pre>
+<code>
+{
+  :host      => "127.0.0.1",
+  :port      => 5672,
+  :user      => "guest",
+  :pass      => "guest",
+  :vhost     => "/",
+  :ssl       => false,
+  :frame_max => 131072
+}
+</code>
+</pre>
+
+
+h3. Using connection strings
+
+It is possible to use connection URIs (à la JDBC) with amqp and amqps schemas, for example:
+
+ * amqp://dev.rabbitmq.com
+ * amqp://dev.rabbitmq.com:5672
+ * amqp://guest:guest@dev.rabbitmq.com:5672
+ * amqp://hedgehog:t0ps3kr3t@hub.megacorp.internal/production
+ * amqps://hub.megacorp.internal//
+
+Two supported schemas are *amqp* and *amqps*. Default port for amqp is 5672. If port isn't given, and schema
+is amqps, amqp gem will assume it has to connect to 5671, default port for amqps.
+
+h4. Vhosts: naming schemas and parsing
+
+AMQP 0.9.1 spec does not define what vhost naming scheme should be. RabbitMQ and Apache Qpid use different schemes
+(Qpid said to have two) but the bottom line is: even though some brokers use / as the default vhost, it can be *any string*.
+Host (and optional port) part must be separated from vhost (path component) with a slash character (/).
+
+Here are some examples that demonstrate how {AMQP::Client.parse_connection_uri} parses out vhost from connection URI:
+
+<pre>
+<code>
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com")            # => vhost is nil, so default (/) will be used
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/")           # => vhost is an empty string
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com//")          # => vhost is /
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com//vault")     # => vhost is /vault
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/%2Fvault")   # => vhost is /vault
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/production") # => vhost is production
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/a.b.c")      # => vhost is a.b.c
+AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com///a/b/c/d")  # => vhost is //a/b/c/d
+</code>
+</pre>
+
+{AMQP::Client.parse_connection_uri} will also unescape path part of the URI.
+
+
+
+
+h2. Starting event loop & connecting in standalone applications
 
 h3. EventMachine event loop
 
@@ -48,7 +126,7 @@ Standalone applications often can afford starting event loop on the main thread.
 recommended way.
 
 
-h3. AMQP.connect with a block
+h3. Using AMQP.connect with a block
 
 Once event loop is running, {AMQP.connect} method will attempt to connect to the broker. It can be used in two ways. Here is the
 first one:
@@ -70,7 +148,7 @@ end
 authentication succeeded, broker and client finished negotiating connection parameters like max frame size).
 
 
-h3. AMQP.connect without a callback
+h3. Using AMQP.connect without a callback
 
 Alternative way of connecting is this:
 
@@ -93,7 +171,8 @@ arise from attempts to use a connection object that is not fully opened yet. For
 with the block version, as we will see in the following sections.
 
 
-h3. AMQP.start
+
+h3. Using AMQP.start
 
 EventMachine.run and {AMQP.connect} with a block is such a common combination that amqp gem provides a shortcut:
 
@@ -101,7 +180,7 @@ EventMachine.run and {AMQP.connect} with a block is such a common combination th
 <code>
 require "amqp"
 
-AMQP.start("amqp://dev.rabbitmq.com:5672/") do |client|
+AMQP.start("amqp://dev.rabbitmq.com:5672") do |client|
   # connection is open and ready to be used
 end
 </code>
@@ -275,7 +354,7 @@ it means that authentication has failed.
 
 
 
-h2. In Web applications (Ruby on Rails, Sinatra, Merb, Rack)
+h2. Starting event loop & connecting in Web applications (Ruby on Rails, Sinatra, Merb, Rack)
 
 Web applications are different from standalone applications in that main thread is occupied by Web/application server like Unicorn
 or Thin, so you need to start EventMachine reactor before you attempt to use {AMQP.connect}.
@@ -346,6 +425,57 @@ Thin and Goliath are not pre-forking servers so there is no need to re-establish
 
 
 
+
+h2. If it just doesn't work: troubleshooting
+
+If you read this guide yet your issue is still unresolved, 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.
+
+
+h3. 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.
+
+
+
 h2. What to read next
 
  * {file:docs/Queues.textile Queues}

data/docs/GettingStarted.textile

@@ -265,7 +265,7 @@ account on Blabbr to get updates about what is up in the world of basketball. He
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://dev.rabbitmq.com:5672/") do |connection|
+AMQP.start("amqp://dev.rabbitmq.com:5672") do |connection|
   channel  = AMQP::Channel.new(connection)
   exchange = channel.fanout("nba.scores")
 
@@ -568,7 +568,7 @@ This tutorial ends here. Congratulations! You have learned quite a bit about bot
 
 h2. What to read next
 
-Documentation is organized as a {file:docs/DocumentationGuidesIndex.textile Routing guide number of guides}, covering all kinds of
+Documentation is organized as a {file:docs/DocumentationGuidesIndex.textile Number of guides}, covering all kinds of
 topics from {file:docs/Routing.textile routing} to {file:docs/ErrorHandling.textile error handling} to
 {file:docs/VendorSpecificExchanges.textile Broker-specific AMQP 0.9.1 extensions}.
 

data/docs/Queues.textile

@@ -59,7 +59,7 @@ Here is an example:
 <pre>
 <code>
 # Declaring a server-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     AMQP::Queue.new(channel, "", :auto_delete => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go. AMQP method: #{declare_ok.inspect}"
@@ -78,7 +78,7 @@ If you want to declare a queue with a particular name, for example, "images.resi
 <pre>
 <code>
 # Declaring a server-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     AMQP::Queue.new(channel, "images.resize", :auto_delete => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go."
@@ -153,7 +153,7 @@ require "rubygems"
 require "amqp"
 
 # Declaring a client-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     AMQP::Queue.new(channel, "images.resize", :durable => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go."
@@ -178,7 +178,7 @@ require "rubygems"
 require "amqp"
 
 # Declaring a client-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     channel.queue("images.resize", :durable => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go."
@@ -207,7 +207,7 @@ require "rubygems"
 require "amqp"
 
 # Declaring a server-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     AMQP::Queue.new(channel, "", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go."
@@ -232,7 +232,7 @@ require "rubygems"
 require "amqp"
 
 # Declaring a server-named queue using AMQP::Queue constructor
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     channel.queue("", :auto_delete => true, :exclusive => true) do |queue, declare_ok|
       puts "#{queue.name} is ready to go."
@@ -262,7 +262,7 @@ require "rubygems"
 require "amqp"
 
 # Binding a queue to an exchange
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange = channel.fanout("amq.fanout")
 
@@ -289,7 +289,7 @@ require "rubygems"
 require "amqp"
 
 # Binding a queue to an exchange
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange_name = "amq.fanout"
 
@@ -322,7 +322,7 @@ Then when a message arrives, message header and body (aka payload) are passed to
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange = channel.fanout("amq.fanout")
 
@@ -368,7 +368,7 @@ AMQP 0.9.1 also provides a way for applications to fetch (pull) messages from th
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange = channel.fanout("amq.fanout")
 
@@ -409,7 +409,7 @@ Sometimes it is necessary to unsubscribe from messages without deleting a queue.
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   AMQP::Channel.new do |channel, open_ok|
     exchange = channel.fanout("amq.fanout")
 
@@ -449,7 +449,7 @@ To unbind queue from exchange, use {AMQP::Queue#unbind}:
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   puts "Connected"
   AMQP::Channel.new(connection) do |channel, open_ok|
     puts "Opened a channel"
@@ -493,7 +493,7 @@ It is possible to purge (remove all messages from) a queue using {AMQP::Queue#pu
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   puts "Connected"
   AMQP::Channel.new(connection) do |channel, open_ok|
     puts "Opened a channel"
@@ -533,7 +533,7 @@ To delete a queue, use {AMQP::Queue#delete}:
 require "rubygems"
 require "amqp"
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   puts "Connected"
   AMQP::Channel.new(connection) do |channel, open_ok|
     puts "Opened a channel"

data/examples/channels/open_channel_with_one_arity_callback.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+
+puts "=> Channel#initialize example that uses a block"
+puts
+AMQP.start(:host => 'localhost') do |connection|
+  AMQP::Channel.new do |channel|
+    puts "Channel ##{channel.id} is now open!"
+  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/deprecated/default_thread_local_channel_instance.rb

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+# CODE BELOW IS USING DEPRECATED METHODS. PLEASE CONSIDER NOT USING THEM IF YOU CAN.
+#
+# The reason why these methods work at all is to make 0.6.x => 0.8.x migration easier so
+# people won't be stuck with AMQP (the protocol) 0.8 forever and can benefit from more
+# advanced AMQP 0.9.1 features.
+#
+
+EventMachine.run do
+  connection = AMQP.connect(:host => '127.0.0.1')
+  puts "Connected to AMQP broker. Running #{AMQP::VERSION} version of the gem..."
+
+  queue    = AMQP::Channel.queue("amqpgem.examples.hello_world", :auto_delete => true)
+  exchange = MQ.direct("")
+
+  queue.subscribe do |payload|
+    puts "Received a message: #{payload}. Disconnecting..."
+
+    connection.close {
+      EM.stop { exit }
+    }
+  end
+
+  exchange.publish "Hello, world!", :routing_key => queue.name
+end

data/examples/error_handling/channel_level_exception.rb

@@ -11,7 +11,7 @@ require 'amqp'
 
 puts "=> Queue redeclaration with different attributes results in a channel exception that is handled"
 puts
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+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!"
 

data/examples/error_handling/channel_level_exception_with_multiple_channels_involved.rb

@@ -11,7 +11,7 @@ require 'amqp'
 
 puts "=> Queue redeclaration with different attributes results in a channel exception that is handled"
 puts
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672") do |connection, open_ok|
   ch1 = AMQP::Channel.new(connection) do |ch, open_ok|
     puts "Channel ##{ch.id} is now open!"
   end

data/examples/error_handling/global_channel_level_exception_handler.rb

@@ -28,7 +28,7 @@ MSG
 puts
 puts
 
-AMQP.start("amqp://guest:guest@dev.rabbitmq.com:5672/") do |connection, open_ok|
+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!"