amqp 0.8.0.rc11 → 0.8.0.rc12

data/examples/guides/getting_started/03_babblr.rb

@@ -4,7 +4,7 @@
 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")
 

data/examples/guides/queues/05_binding_a_queue_using_exchange_instance.rb

@@ -5,7 +5,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")
 

data/examples/guides/queues/06_biding_a_queue_using_exchange_name_string.rb

@@ -5,7 +5,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"
 

data/examples/guides/queues/07_subscribing_to_receive_messages.rb

@@ -4,7 +4,7 @@
 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")
 

data/examples/guides/queues/08_poll_for_messages.rb

@@ -4,7 +4,7 @@
 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")
 

data/examples/guides/queues/09_unsubscribing_a_consumer.rb

@@ -4,7 +4,7 @@
 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")
 

data/examples/guides/queues/10_unbinding_from_exchange.rb

@@ -4,7 +4,7 @@
 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/guides/queues/11_purge_a_queue.rb

@@ -4,7 +4,7 @@
 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/guides/queues/12_deleting_a_queue.rb

@@ -4,7 +4,7 @@
 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/queues/declare_a_queue_without_assignment.rb

@@ -11,7 +11,7 @@ require 'amqp'
 
 puts "=> Queue#initialize example that uses a block"
 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/queues/declare_and_bind_a_server_named_queue.rb

@@ -11,7 +11,7 @@ require 'amqp'
 
 puts "=> Queue#initialize example that uses a block"
 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!" if channel.open?
 

data/lib/amqp/channel.rb

@@ -80,7 +80,7 @@ module AMQP
   # It is possible (and, indeed, recommended) to handle channel-level exceptions by defining an errback using #on_error:
   #
   # @example Queue declaration with incompatible attributes results in a channel-level exception
-  #   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!"
   #
@@ -926,6 +926,32 @@ module AMQP
     end
 
 
+    #
+    # Backwards compatibility with 0.6.x
+    #
+
+    # unique identifier
+    # @deprecated
+    def self.id
+      Thread.current[:mq_id] ||= "#{`hostname`.strip}-#{Process.pid}-#{Thread.current.object_id}"
+    end
+
+    # @private
+    # @deprecated
+    def self.default
+      # TODO: clear this when connection is closed
+      Thread.current[:mq] ||= AMQP::Channel.new
+    end
+
+    # Allows for calls to all MQ instance methods. This implicitly calls
+    # AMQP::Channel.new so that a new channel is allocated for subsequent operations.
+    # @deprecated
+    def self.method_missing(meth, *args, &blk)
+      self.default.__send__(meth, *args, &blk)
+    end
+
+
+
     protected
 
     # @private

data/lib/amqp/client.rb

@@ -21,6 +21,8 @@ module AMQP
     # @see AMQP.start
     # @see AMQP.connect
     # @api plugin
+    #
+    # @see http://bit.ly/ks8MXK Connecting to The Broker documentation guide
     def self.connect(connection_string_or_options = {}, options = {}, &block)
       opts = case connection_string_or_options
              when String then
@@ -40,21 +42,47 @@ module AMQP
 
     # Parses AMQP connection string and returns it's components as a hash.
     #
-    # @param [String] connection_string AMQP connection URI, à la JDBC connection string. For example: amqp://bus.megacorp.internal:5877/qa
+    # h2. vhost naming schemes
+    #
+    # 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 (/).
+    #
+    # This method will also unescape path part of the URI.
+    #
+    # @example How vhost is parsed
+    #
+    #   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
+    #
+    #
+    # @param [String] connection_string AMQP connection URI, à la JDBC connection string. For example: amqp://bus.megacorp.internal:5877.
     # @return [Hash] Connection parameters (:username, :password, :vhost, :host, :port, :ssl)
+    #
+    # @raise [ArgumentError] When connection URI schema is not amqp or amqps.
+    #
+    # @see http://bit.ly/ks8MXK Connecting to The Broker documentation guide
     # @api public
     def self.parse_connection_uri(connection_string)
       uri = URI.parse(connection_string)
-      raise("Connection URI must use amqp or amqps schema (example: amqp://bus.megacorp.internal:5766/testbed)") unless %w{amqp amqps}.include?(uri.scheme)
+      raise ArgumentError.new("Connection URI must use amqp or amqps schema (example: amqp://bus.megacorp.internal:5766), learn more at http://bit.ly/ks8MXK") unless %w{amqp amqps}.include?(uri.scheme)
 
       opts = {}
 
-      opts[:user]  = URI.unescape(uri.user) if uri.user
-      opts[:pass]  = URI.unescape(uri.password) if uri.password
-      opts[:vhost] = URI.unescape(uri.path) if uri.path
-      opts[:host]  = uri.host if uri.host
-      opts[:port]  = uri.port || AMQP_PORTS[uri.scheme]
-      opts[:ssl]   = uri.scheme == AMQPS
+
+      opts[:scheme] = uri.scheme
+      opts[:user]   = URI.unescape(uri.user) if uri.user
+      opts[:pass]   = URI.unescape(uri.password) if uri.password
+      opts[:vhost]  = URI.unescape($1) if uri.path =~ %r{^/(.*)}
+      opts[:host]   = uri.host if uri.host
+      opts[:port]   = uri.port || AMQP_PORTS[uri.scheme]
+      opts[:ssl]    = uri.scheme == AMQPS
 
       opts
     end

data/lib/amqp/connection.rb

@@ -15,7 +15,7 @@ module AMQP
   # to AMQP broker using {AMQP.connect}. It is generally a good idea to
   # start EventMachine event loop in a separate thread and use {AMQP.connect}.
   # That said, for applications that do not publish or handle large volumes of
-  # data {AMQP.start} works very well and it's use is not discouraged.
+  # data {AMQP.start} works very well and its use is not discouraged.
   #
   # See {AMQP.connect} for information about arguments this method takes and
   # information about relevant topics such as authentication failure handling.
@@ -37,7 +37,9 @@ module AMQP
   # @api public
   def self.start(connection_options_or_string = {}, other_options = {}, &block)
     EM.run do
-      @connection ||= connect(connection_options_or_string, other_options, &block)
+      if !@connection || @connection.closed? || @connection.closing?
+        @connection   = connect(connection_options_or_string, other_options, &block)
+      end
       @channel      = Channel.new(@connection)
       @connection
     end
@@ -169,7 +171,7 @@ module AMQP
   #
   # @example Using AMQP.connect to connect to a public RabbitMQ instance with connection settings given as a URI
   #
-  #   AMQP.connect "amqp://guest:guest@dev.rabbitmq.com:5672/", :on_possible_authentication_failure => Proc.new { puts("Looks like authentication has failed") } do |connection|
+  #   AMQP.connect "amqp://guest:guest@dev.rabbitmq.com:5672", :on_possible_authentication_failure => Proc.new { puts("Looks like authentication has failed") } do |connection|
   #     AMQP::Channel.new(connection) do |channel|
   #       # ...
   #     end
@@ -191,6 +193,7 @@ module AMQP
   # @option connection_options_or_string [String]  :username ("guest") Username to use. Also can be specified as :user.
   # @option connection_options_or_string [String]  :password ("guest") Password to use. Also can be specified as :pass.
   # @option connection_options_or_string [Hash]  :ssl TLS (SSL) parameters to use.
+  # @option connection_options_or_string [#call]  :on_tcp_connection_failure A callable object that will be run if connection to server fails
   # @option connection_options_or_string [#call]  :on_possible_authentication_failure A callable object that will be run if authentication fails (see Authentication failure section)
   #
   #

data/lib/amqp/deprecated/mq.rb

@@ -17,26 +17,4 @@ class MQ
   # @note This class will be removed before 1.0 release.
   # @deprecated
   class Queue < ::AMQP::Queue; end
-
-
-  #
-  # Backwards compatibility with 0.6.x
-  #
-
-  # unique identifier
-  def MQ.id
-    Thread.current[:mq_id] ||= "#{`hostname`.strip}-#{Process.pid}-#{Thread.current.object_id}"
-  end
-
-  # @private
-  def MQ.default
-    # TODO: clear this when connection is closed
-    Thread.current[:mq] ||= MQ.new
-  end
-
-  # Allows for calls to all MQ instance methods. This implicitly calls
-  # MQ.new so that a new channel is allocated for subsequent operations.
-  def MQ.method_missing(meth, *args, &blk)
-    MQ.default.__send__(meth, *args, &blk)
-  end
 end

data/lib/amqp/queue.rb

@@ -219,27 +219,33 @@ module AMQP
     end # server_named?
 
 
-    # This method binds a queue to an exchange.  Until a queue is
-    # bound it will not receive any messages.  In a classic messaging
+    # This method binds a queue to an exchange. Until a queue is
+    # bound it will not receive any messages. In a classic messaging
     # model, store-and-forward queues are bound to a dest exchange
     # and subscription queues are bound to a dest_wild exchange.
     #
     # A valid exchange name (or reference) must be passed as the first
     # parameter.
-    # @example Both of these are valid
-    #  exch = AMQP::Channel.direct('foo exchange')
-    #  queue = AMQP::Channel.queue('bar queue')
-    #  queue.bind('foo.exchange') # OR
-    #  queue.bind(exch)
+    # @example Binding a queue to exchange using AMQP::Exchange instance
     #
-    # It is not valid to call #bind without the +exchange+ parameter.
+    #  ch       = AMQP::Channel.new(connection)
+    #  exchange = ch.direct('backlog.events')
+    #  queue    = ch.queue('', :exclusive => true)
+    #  queue.bind(exchange)
     #
-    # It is unnecessary to call #bind when the exchange name and queue
-    # name match exactly (for :direct and :fanout exchanges only).
-    # There is an implicit bind which will deliver the messages from
-    # the exchange to the queue.
     #
-    # @param [Exchange] Exchange to bind to.
+    # @example Binding a queue to exchange using exchange name
+    #
+    #  ch       = AMQP::Channel.new(connection)
+    #  queue    = ch.queue('', :exclusive => true)
+    #  queue.bind('backlog.events')
+    #
+    #
+    # Note that if your producer application knows consumer queue name and wants to deliver
+    # a message there, direct exchange may be sufficient (in other words, if your code declares an exchange with
+    # the same name as a queue and binds it to that queue, consider using the default exchange and routing key on publishing).
+    #
+    # @param [Exchange] Exchange to bind to. May also be a string or any object that responds to #name.
     #
     # @option opts [String] :routing_key   Specifies the routing key for the binding. The routing key is
     #                                      used for routing messages depending on the exchange configuration.

data/lib/amqp/version.rb

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

data/spec/integration/authentication_spec.rb

@@ -10,6 +10,8 @@ describe "Authentication attempt" do
   include EventedSpec::EMSpec
   include EventedSpec::SpecHelper
 
+  default_timeout 1.0
+
 
   describe "with default connection parameters" do
 
@@ -45,12 +47,12 @@ describe "Authentication attempt" do
 
     # assuming there is an account amqp_gem with password of "amqp_gem_password" that has
     # access to /amqp_gem_testbed
-    context "when amqp_gem/amqp_gem_testbed has access to /amqp_gem_testbed" do
+    context "when amqp_gem/amqp_gem_testbed has access to amqp_gem_testbed" do
       context "and provided credentials are correct" do
         it "succeeds" do
-          connection = AMQP.connect :username => "amqp_gem", :password => "amqp_gem_password", :vhost => "/amqp_gem_testbed"
+          connection = AMQP.connect(AMQP_OPTS.merge(:username => "amqp_gem", :password => "amqp_gem_password", :vhost => "/amqp_gem_testbed"))
 
-          done(0.5) {
+          done(0.4) {
             connection.should be_connected
             connection.close
           }
@@ -99,10 +101,10 @@ describe "Authentication attempt" do
 
     # assuming there is an account amqp_gem with password of "amqp_gem_password" that has
     # access to /amqp_gem_testbed
-    context "when amqp_gem/amqp_gem_testbed has access to /amqp_gem_testbed" do
+    context "when amqp_gem/amqp_gem_testbed has access to amqp_gem_testbed" do
       context "and provided credentials are correct" do
         it "succeeds" do
-          connection = AMQP.connect "amqp://amqp_gem:amqp_gem_password@localhost/amqp_gem_testbed"
+          connection = AMQP.connect "amqp://amqp_gem:amqp_gem_password@localhost/%2Famqp_gem_testbed"
 
           done(0.3) {
             connection.should be_connected

data/spec/spec_helper.rb

@@ -93,6 +93,7 @@ else
   AMQP_OPTS = {:host => 'localhost', :port => 5672}
 end
 
+puts "AMQP_OPTS = #{AMQP_OPTS.inspect}"
 
 #
 # Ruby version-specific

data/spec/unit/amqp/client_spec.rb

@@ -0,0 +1,149 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe AMQP::Client do
+
+  #
+  # Examples
+  #
+
+
+  describe ".parse_connection_uri(connection_string)" do
+    context "when schema is not one of [amqp, amqps]" do
+      it "raises ArgumentError" do
+        expect {
+          described_class.parse_connection_uri("http://dev.rabbitmq.com")
+        }.to raise_error(ArgumentError, /amqp or amqps schema/)
+      end
+    end
+
+
+    it "handles amqp:// URIs w/o path part" do
+      val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com")
+
+      val[:vhost].should be_nil # in this case, default / will be used
+      val[:host].should == "dev.rabbitmq.com"
+      val[:port].should == 5672
+      val[:scheme].should == "amqp"
+      val[:ssl].should be_false
+    end
+
+    it "handles amqps:// URIs w/o path part" do
+      val = described_class.parse_connection_uri("amqps://dev.rabbitmq.com")
+
+      val[:vhost].should be_nil
+      val[:host].should == "dev.rabbitmq.com"
+      val[:port].should == 5671
+      val[:scheme].should == "amqps"
+      val[:ssl].should be_true
+    end
+
+
+    context "when URI ends in a slash" do
+      it "parses vhost as an empty string" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com/")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == ""
+      end
+    end
+
+
+    context "when URI ends in two consecutive slashes (//)" do
+      it "parses vhost as /" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com//")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "/"
+      end
+    end
+
+
+    context "when URI ends in //vault" do
+      it "parses vhost as /vault" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com//vault")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "/vault"
+      end
+    end
+
+
+
+    context "when URI ends in /%2Fvault" do
+      it "parses vhost as /vault" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com/%2Fvault")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "/vault"
+      end
+    end
+
+
+    context "when URI is amqp://dev.rabbitmq.com/i.am.a.vhost.without.slashes" do
+      it "parses vhost as i.am.a.vhost.without.slashes" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com/i.am.a.vhost.without.slashes")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "i.am.a.vhost.without.slashes"
+      end
+    end
+
+
+    context "when URI is amqp://dev.rabbitmq.com/production" do
+      it "parses vhost as production" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com/production")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "production"
+      end
+    end
+
+
+    context "when URI is amqp://dev.rabbitmq.com///a/b/c/d" do
+      it "parses vhost as ///a/b/c/d" do
+        val = described_class.parse_connection_uri("amqp://dev.rabbitmq.com///a/b/c/d")
+
+        val[:host].should == "dev.rabbitmq.com"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:vhost].should == "//a/b/c/d"
+      end
+    end
+
+
+    context "when URI has username:password, for instance, amqp://hedgehog:t0ps3kr3t@hub.megacorp.internal" do
+      it "parses them out" do
+        val = described_class.parse_connection_uri("amqp://hedgehog:t0ps3kr3t@hub.megacorp.internal")
+
+        val[:host].should == "hub.megacorp.internal"
+        val[:port].should == 5672
+        val[:scheme].should == "amqp"
+        val[:ssl].should be_false
+        val[:user].should == "hedgehog"
+        val[:pass].should == "t0ps3kr3t"
+        val[:vhost].should be_nil # in this case, default / will be used
+      end
+    end
+  end
+end