amqp 0.8.0.rc12 → 0.8.0.rc13

data/lib/amqp/client.rb

@@ -40,32 +40,42 @@ module AMQP
       end
     end
 
-    # Parses AMQP connection string and returns it's components as a hash.
+    # Parses AMQP connection URI and returns its components as a hash.
     #
     # 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 (/).
+    # It is convenient to be able to specify the AMQP connection
+    # parameters as a URI string, and various "amqp" URI schemes
+    # exist.  Unfortunately, there is no standard for these URIs, so
+    # while the schemes share the basic idea, they differ in some
+    # details.  This implementation aims to encourage URIs that work
+    # as widely as possible.
     #
-    # This method will also unescape path part of the URI.
+    # The URI scheme should be "amqp", or "amqps" if SSL is required.
+    #
+    # The host, port, username and password are represented in the
+    # authority component of the URI in the same way as in http URIs.
+    #
+    # The vhost is obtained from the first segment of the path, with the
+    # leading slash removed.  The path should contain only a single
+    # segment (i.e, the only slash in it should be the leading one).
+    # If the vhost is to include slashes or other reserved URI
+    # characters, these should be percent-escaped.
     #
     # @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
+    #   AMQP::Client.parse_connection_uri("amqp://dev.rabbitmq.com/foo/bar")    # => ArgumentError
     #
     #
     # @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.
+    # @raise [ArgumentError] When connection URI schema is not amqp or amqps, or the path contains multiple segments
     #
     # @see http://bit.ly/ks8MXK Connecting to The Broker documentation guide
     # @api public
@@ -75,14 +85,16 @@ module AMQP
 
       opts = {}
 
-
       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
+      if uri.path =~ %r{^/(.*)}
+        raise ArgumentError.new("#{uri} has multiple-segment path; please percent-encode any slashes in the vhost name (e.g. /production => %2Fproduction). Learn more at http://bit.ly/amqp-gem-and-connection-uris") if $1.index('/')
+        opts[:vhost] = URI.unescape($1)
+      end
 
       opts
     end

data/lib/amqp/exchange.rb

@@ -366,8 +366,10 @@ module AMQP
 
     # Publishes message to the exchange. The message will be routed to queues by the exchange
     # and distributed to any active consumers. Routing logic is determined by exchange type and
-    # configuration as well as  message attributes (like :routing_key).
+    # configuration as well as message attributes (like :routing_key or message headers).
     #
+    # Published data is opaque and not modified by Ruby amqp gem in any way. Serialization of data with JSON, Thrift, BSON
+    # or similar libraries before publishing is very common.
     #
     #
     # h2. Data serialization
@@ -375,14 +377,48 @@ module AMQP
     # Note that this method calls #to_s on payload argument value. You are encouraged to take care of
     # data serialization before publishing (using JSON, Thrift, Protocol Buffers or other serialization library).
     # Note that because AMQP is a binary protocol, text formats like JSON lose lose their strong point of being easy
-    # to inspect data as it travels across network.
+    # to inspect data as it travels across network. For the same reason BSON may be a good fit.
     #
     #
+    # h2. Publishing and message persistence
+    #
+    # In cases when you application cannot afford to lose a message, AMQP 0.9.1 has several features to offer:
+    #
+    # * Persistent messages
+    # * Messages acknowledgements
+    # * Transactions
+    # * (a RabbitMQ-specific extension) Publisher confirms
+    #
+    # This is a broad topic and we dedicate a separate guide, {file:docs/Durability.textile Durability and message persistence}, to it.
+    #
+    #
+    # h2. Publishing callback and guarantees it DOES NOT offer
+    #
+    # Exact moment when message is published is not determined and depends on many factors, including machine's networking stack configuration,
+    # so (optional) block this method takes is scheduled for next event loop tick, and data is staged for delivery for current event loop
+    # tick. For most applications, this is good enough. The only way to guarantee a message was delivered in a distributed system is to
+    # ask a peer to send you a message back. RabbitMQ
+    #
+    # @note Optional callback this method takes DOES NOT OFFER ANY GUARANTEES ABOUT DATA DELIVERY and must not be used as a "delivery callback".
+    #       The only way to guarantee delivery in distributed environment is to use an acknowledgement mechanism, such as AMQP transactions
+    #       or lightweight "publisher confirms" RabbitMQ extension supported by amqp gem. See {file:docs/Durability.textile Durability and message persistence}
+    #       and {file:docs/Exchanges.textile Working With Exchanges} guides for details.
+    #
     #
     # h2. Event loop blocking
     #
-    # To minimize blocking of EventMachine event loop, this method performs network I/O on the next event loop tick. This means
-    # that shutting down the event loop immediately after {Exchange#publish} returns will result in message never being sent.
+    # When intermixing publishing of many messages with other workload that may take some time, even loop blocking may affect the performance.
+    # There are several ways to avoid it:
+    #
+    # * Run EventMachine in a separate thread.
+    # * Use EventMachine.next_tick.
+    # * Use EventMachine.defer to offload operation to EventMachine thread pool.
+    #
+    # TBD: this subject is worth a separate guide
+    #
+    #
+    # h2. Sending one-off messages
+    #
     # If you need to send a one-off message and then stop the event loop, pass a block to {Exchange#publish} that will be executed
     # after message is pushed down the network stack, and use {AMQP::Session#disconnect} to properly tear down AMQP connection
     # (see example under Examples section below).
@@ -393,18 +429,6 @@ module AMQP
     #   end
     #
     #
-    # h2. Publishing and persistence
-    #
-    # In cases when you application cannot afford to lose a message, AMQP 0.9.1 has several features to offer:
-    #
-    # * Persistent messages
-    # * Messages acknowledgements
-    # * Transactions
-    # * (a RabbitMQ-specific extension) Publisher confirms
-    #
-    # This is a broad topic and we dedicate a separate guide, {file:docs/Durability.textile Durability and message persistence}, to it.
-    #
-    #
     #
     # @param  [#to_s] payload  Message payload (content). Note that this method calls #to_s on payload argument value.
     #                          You are encouraged to take care of data serialization before publishing (using JSON, Thrift,
@@ -446,48 +470,41 @@ module AMQP
     #
     # @return [Exchange] self
     #
-    # @note Please make sure you read {file:docs/Durability.textile Durability guide} that covers exchanges durability vs. messages
+    # @note Please make sure you read {file:docs/Durability.textile Durability an message persistence} guide that covers exchanges durability vs. messages
     #       persistence.
     # @api public
     def publish(payload, options = {}, &block)
-      EM.next_tick do
-        opts    = @default_publish_options.merge(options)
+      opts    = @default_publish_options.merge(options)
 
-        @channel.once_open do
-          super(payload.to_s, opts[:key] || opts[:routing_key] || @default_routing_key, @default_headers.merge(options), opts[:mandatory], opts[:immediate])
+      @channel.once_open do
+        super(payload.to_s, opts[:key] || opts[:routing_key] || @default_routing_key, @default_headers.merge(options), opts[:mandatory], opts[:immediate])
 
-          # don't pass block to AMQ::Client::Exchange#publish because it will be executed
-          # immediately and we want to do it later. See ruby-amqp/amqp/#67 MK.
-          block.call if block
-        end
+        # don't pass block to AMQ::Client::Exchange#publish because it will be executed
+        # immediately and we want to do it later. See ruby-amqp/amqp/#67 MK.
+        EventMachine.next_tick(&block) if block
       end
 
       self
     end
 
 
-    # This method deletes an exchange.  When an exchange is deleted all queue
-    # bindings on the exchange are cancelled.
+    # This method deletes an exchange. When an exchange is deleted all queue bindings on the exchange are deleted, too.
+    # Further attempts to publish messages to a deleted exchange will result in a channel-level exception.
     #
-    # Further attempts to publish messages to a deleted exchange will raise
-    # an AMQP::Channel::Error due to a channel close exception.
+    # @example Deleting an exchange
     #
-    #  exchange = AMQP::Channel.direct('name', :routing_key => 'foo.bar')
+    #  exchange = AMQP::Channel.direct("search.indexing")
     #  exchange.delete
     #
-    # == Options
-    # * :nowait => true | false (default 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
-    # method it will raise a channel or connection exception.
-    #
-    #  exchange.delete(:nowait => false)
+    # @option opts [Boolean] :nowait (false) 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
+    #                                        method it will raise a channel or connection exception.
     #
-    # * :if_unused => true | false (default false)
-    # If set, the server will only delete the exchange if it has no queue
-    # bindings. If the exchange has queue bindings the server does not
-    # delete it but raises a channel exception instead (AMQP::Error).
+    # @option opts [Boolean] :if_unused (false) If set, the server will only delete the exchange if it has no queue
+    #                                           bindings. If the exchange has queue bindings the server does not
+    #                                           delete it but raises a channel exception instead.
     #
+    # @return [NilClass] nil
     # @api public
     def delete(opts = {}, &block)
       @channel.once_open do

data/lib/amqp/queue.rb

@@ -170,11 +170,16 @@ module AMQP
     #
     # @api public
     def initialize(channel, name = AMQ::Protocol::EMPTY_STRING, opts = {}, &block)
+      raise ArgumentError.new("queue name must not be nil; if you want broker to generate queue name for you, pass an empty string") if name.nil?
+
       @channel  = channel
       name      = AMQ::Protocol::EMPTY_STRING if name.nil?
       @name     = name unless name.empty?
       @server_named = name.empty?
       @opts         = self.class.add_default_options(name, opts, block)
+
+      raise ArgumentError.new("server-named queues (name = '') declaration with :nowait => true makes no sense. If you are not sure what that means, simply drop :nowait => true from opts.") if @server_named && @opts[:nowait]
+
       @bindings     = Hash.new
 
       # a deferrable that we use to delay operations until this queue is actually declared.
@@ -254,6 +259,10 @@ module AMQP
     #                                      name is empty, the routing key will be the current queue for the
     #                                      channel, which is the last declared queue.
     #
+    # @option opts [Hash] :arguments (nil)  A hash of optional arguments with the declaration. Headers exchange type uses these metadata
+    #                                       attributes for routing matching.
+    #                                       In addition, brokers may implement AMQP extensions using x-prefixed declaration arguments.
+    #
     # @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
     #                                       method it will raise a channel or connection exception.
@@ -472,7 +481,7 @@ module AMQP
     #
     # @example Use of callback with a single argument
     #
-    #  EM.run do
+    #  EventMachine.run do
     #    exchange = AMQP::Channel.direct("foo queue")
     #    EM.add_periodic_timer(1) do
     #      exchange.publish("random number #{rand(1000)}")
@@ -488,19 +497,55 @@ module AMQP
     #
     # @example Use of callback with two arguments
     #
-    #  EM.run do
-    #    exchange = AMQP::Channel.direct("foo queue")
-    #    EM.add_periodic_timer(1) do
-    #      exchange.publish("random number #{rand(1000)}")
+    #  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)
+    #
+    #    channel.on_error do |ch, channel_close|
+    #      puts channel_close.reply_text
+    #      connection.close { EventMachine.stop }
     #    end
     #
-    #    # note that #bind is never called; it is implicit because
-    #    # the exchange and queue names match
-    #    queue = AMQP::Channel.queue('foo queue')
-    #    queue.subscribe do |header, body|
-    #      p header
-    #      puts "received payload [#{body}]"
+    #    queue.subscribe do |metadata, payload|
+    #      puts "metadata.routing_key : #{metadata.routing_key}"
+    #      puts "metadata.content_type: #{metadata.content_type}"
+    #      puts "metadata.priority    : #{metadata.priority}"
+    #      puts "metadata.headers     : #{metadata.headers.inspect}"
+    #      puts "metadata.timestamp   : #{metadata.timestamp.inspect}"
+    #      puts "metadata.type        : #{metadata.type}"
+    #      puts "metadata.delivery_tag: #{metadata.delivery_tag}"
+    #      puts "metadata.redelivered : #{metadata.redelivered}"
+    #
+    #      puts "metadata.app_id      : #{metadata.app_id}"
+    #      puts "metadata.exchange    : #{metadata.exchange}"
+    #      puts
+    #      puts "Received a message: #{payload}. Disconnecting..."
+    #
+    #      connection.close {
+    #        EventMachine.stop { exit }
+    #      }
     #    end
+    #
+    #    exchange.publish("Hello, world!",
+    #                     :app_id      => "amqpgem.example",
+    #                     :priority    => 8,
+    #                     :type        => "kinda.checkin",
+    #                     # headers table keys can be anything
+    #                     :headers     => {
+    #                       :coordinates => {
+    #                         :latitude  => 59.35,
+    #                         :longitude => 18.066667
+    #                       },
+    #                       :participants => 11,
+    #                       :venue        => "Stockholm"
+    #                     },
+    #                     :timestamp   => Time.now.to_i)
     #  end
     #
     #
@@ -516,10 +561,15 @@ module AMQP
     #                                        method it will raise a channel or connection exception.
     #
     # @option opts [#call] :confirm (nil)   If set, this proc will be called when the server confirms subscription
-    #                                       to the queue with a ConsumeOk message. Setting this option will
+    #                                       to the queue with a basic.consume-ok message. Setting this option will
     #                                       automatically set :nowait => false. This is required for the server
     #                                       to send a confirmation.
     #
+    # @option opts [Boolean] :exclusive (false) Request exclusive consumer access, meaning only this consumer can access the queue.
+    #                                           This is useful when you want a long-lived shared queue to be temporarily accessible by just
+    #                                           one application (or thread, or process). If application exclusive consumer is part of crashes
+    #                                           or loses network connection to the broker, channel is closed and exclusive consumer is thus cancelled.
+    #
     #
     # @yield [headers, payload] When block only takes one argument, yields payload to it. In case of two arguments, yields headers and payload.
     # @yieldparam [AMQP::Header] headers Headers (metadata) associated with this message (for example, routing key).
@@ -527,6 +577,9 @@ module AMQP
     #
     # @return [Queue] Self
     # @api public
+    #
+    # @see file:docs/Queues.textile Documentation guide on queues
+    # @see #unsubscribe
     def subscribe(opts = {}, &block)
       raise Error, 'already subscribed to the queue' if @consumer_tag
 
@@ -662,7 +715,7 @@ module AMQP
 
     # @private
     def self.add_default_options(name, opts, block)
-      { :queue => name, :nowait => block.nil? }.merge(opts)
+      { :queue => name, :nowait => (block.nil? && !name.empty?) }.merge(opts)
     end
 
     private

data/lib/amqp/version.rb

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

data/spec/integration/authentication_spec.rb

@@ -46,11 +46,11 @@ describe "Authentication attempt" do
     #
 
     # assuming there is an account amqp_gem with password of "amqp_gem_password" that has
-    # access to /amqp_gem_testbed
+    # access to amqp_gem_testbed
     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_OPTS.merge(: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.4) {
             connection.should be_connected
@@ -70,7 +70,7 @@ describe "Authentication attempt" do
             callback_has_fired = true
             done
           }
-          connection = AMQP.connect(:username => "amqp_gem", :password => Time.now.to_i.to_s, :vhost => "/amqp_gem_testbed", :on_possible_authentication_failure => handler)
+          connection = AMQP.connect(:username => "amqp_gem", :password => Time.now.to_i.to_s, :vhost => "amqp_gem_testbed", :on_possible_authentication_failure => handler)
         end # it
       end
 
@@ -100,11 +100,11 @@ describe "Authentication attempt" do
     #
 
     # assuming there is an account amqp_gem with password of "amqp_gem_password" that has
-    # access to /amqp_gem_testbed
+    # access to amqp_gem_testbed
     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/%2Famqp_gem_testbed"
+          connection = AMQP.connect "amqp://amqp_gem:amqp_gem_password@localhost/amqp_gem_testbed"
 
           done(0.3) {
             connection.should be_connected

data/spec/integration/basic_get_spec.rb

@@ -87,7 +87,7 @@ describe AMQP::Queue, "#pop" do
         # Queue.Get doesn't qualify for subscription, hence, manual deletion is required
         @queue.delete
       }
-      done(1.5) {
+      done(2.5) {
         number_of_received_messages.should == expected_number_of_messages
       }
     end # it

data/spec/integration/channel_close_spec.rb

@@ -6,10 +6,17 @@ describe AMQP::Channel, "#close(&callback)" do
   include EventedSpec::AMQPSpec
 
   it "takes a callback which will run when we get back Channel.Close-Ok" do
-    channel = AMQP::Channel.new do |*args|
-      channel.close do |channel, method|
-        done
+    @events = []
+
+    AMQP::Channel.new do |ch|
+      @events << :open_ok
+      ch.close do |channel, close_ok|
+        @events << :close_ok
       end
     end
+
+    done(0.3) {
+      @events.should == [:open_ok, :close_ok]
+    }
   end
 end

data/spec/integration/queue_declaration_spec.rb

@@ -43,12 +43,33 @@ describe AMQP do
     end # context
 
     context "when queue name is passed on as an empty string" do
-      it "uses server-assigned queue name" do
-        @channel.queue("") do |queue, *args|
-          queue.name.should_not be_empty
-          queue.delete
-          done(0.3)
+      context "and :nowait isn't used" do
+        it "uses server-assigned queue name" do
+          @channel.queue("") do |queue, *args|
+            queue.name.should_not be_empty
+            queue.delete
+            done(0.3)
+          end
+        end
+      end
+
+
+      context "and :nowait is used" do
+        it "raises ArgumentError" do
+          expect { AMQP::Queue.new(@channel, "", :nowait => true) }.to raise_error(ArgumentError, /makes no sense/)
+          expect { @channel.queue("", :nowait => true) }.to raise_error(ArgumentError, /makes no sense/)
+
+          done
         end
+      end # context
+    end
+
+    context "when queue name is nil" do
+      it "raises ArgumentError" do
+        expect { AMQP::Queue.new(@channel, nil) }.to raise_error(ArgumentError, /queue name must not be nil/)
+        expect { @channel.queue(nil) }.to raise_error(ArgumentError, /queue name must not be nil/)
+
+        done
       end
     end # context