amqp 0.8.0.rc13 → 0.8.0.rc14

data/examples/routing/round_robin_with_direct_exchange.rb

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require "amqp"
+
+EventMachine.run do
+  AMQP.connect do |connection|
+    channel1  = AMQP::Channel.new(connection)
+    channel2  = AMQP::Channel.new(connection)
+    exchange = channel1.direct("amqpgem.examples.exchanges.direct", :auto_delete => true)
+
+    q1 = channel1.queue("amqpgem.examples.queues.shared", :auto_delete => true).bind(exchange, :routing_key => "shared.key")
+    q1.subscribe do |payload|
+      puts "Queue #{q1.name} on channel 1 received #{payload}"
+    end
+
+    # since the queue is shared, binding here is redundant but we will leave it in for completeness.
+    q2 = channel2.queue("amqpgem.examples.queues.shared", :auto_delete => true).bind(exchange, :routing_key => "shared.key")
+    q2.subscribe do |payload|
+      puts "Queue #{q2.name} on channel 2 received #{payload}"
+    end
+
+    # Publish some test data in a bit, after all queues are declared & bound
+    EventMachine.add_timer(1.2) do
+      5.times { |i| exchange.publish("Hello #{i}, direct exchanges world!", :routing_key => "shared.key") }
+    end
+
+
+    show_stopper = Proc.new { connection.close { EventMachine.stop } }
+
+    Signal.trap "TERM", show_stopper
+    EM.add_timer(3, show_stopper)
+  end
+end

data/examples/routing/round_robin_with_the_default_exchange.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require "amqp"
+
+EventMachine.run do
+  AMQP.connect do |connection|
+    channel1  = AMQP::Channel.new(connection)
+    channel2  = AMQP::Channel.new(connection)
+    exchange = channel1.default_exchange
+
+    q1 = channel1.queue("amqpgem.examples.queues.shared", :auto_delete => true)
+    q1.subscribe do |payload|
+      puts "Queue #{q1.name} on channel 1 received #{payload}"
+    end
+
+    q2 = channel2.queue("amqpgem.examples.queues.shared", :auto_delete => true)
+    q2.subscribe do |payload|
+      puts "Queue #{q2.name} on channel 2 received #{payload}"
+    end
+
+    # Publish some test data in a bit, after all queues are declared & bound
+    EventMachine.add_timer(1.2) do
+      5.times { |i| exchange.publish("Hello #{i}, direct exchanges world!", :routing_key => "amqpgem.examples.queues.shared") }
+    end
+
+
+    show_stopper = Proc.new { connection.close { EventMachine.stop } }
+
+    Signal.trap "TERM", show_stopper
+    EM.add_timer(3, show_stopper)
+  end
+end

data/examples/routing/unroutable_mandatory_message_is_returned.rb

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+require 'amqp'
+
+puts "=> Handling a returned unroutable message that was published as mandatory"
+puts
+
+AMQP.start(:host => '127.0.0.1') do |connection|
+  channel  = AMQP.channel
+  channel.on_error { |ch, channel_close| EventMachine.stop; raise "channel error: #{channel_close.reply_text}" }
+
+  # this exchange has no bindings, so messages published to it cannot be routed.
+  exchange = channel.fanout("amqpgem.examples.fanout", :auto_delete => true)
+  exchange.on_return do |basic_return, metadata, payload|
+    puts "#{payload} was returned! reply_code = #{basic_return.reply_code}, reply_text = #{basic_return.reply_text}"
+  end
+
+  EventMachine.add_timer(0.3) {
+    10.times do |i|
+      exchange.publish("Message ##{i}", :mandatory => true)
+    end
+  }
+
+  EventMachine.add_timer(2) {
+    connection.close { EventMachine.stop }
+  }
+end

data/examples/routing/weather_updates.rb

@@ -15,27 +15,28 @@ EventMachine.run do
 
     # Subscribers.
     channel.queue("", :exclusive => true) do |queue|
-      queue.bind(exchange, :routing_key => "americas.north.#").subscribe do |headers, payload|
-        puts "An update for North America: #{payload}, routing key is #{headers.routing_key}"
+      queue.bind(exchange, :routing_key => "americas.north.#").subscribe do |metadata, payload|
+        puts "An update for North America: #{payload}, routing key is #{metadata.routing_key}"
       end
     end
-    channel.queue("americas.south").bind(exchange, :routing_key => "americas.south.#").subscribe do |headers, payload|
-      puts "An update for South America: #{payload}, routing key is #{headers.routing_key}"
+    channel.queue("americas.south").bind(exchange, :routing_key => "americas.south.#").subscribe do |metadata, payload|
+      puts "An update for South America: #{payload}, routing key is #{metadata.routing_key}"
     end
-    channel.queue("us.california").bind(exchange, :routing_key => "americas.north.us.ca.*").subscribe do |headers, payload|
-      puts "An update for US/California: #{payload}, routing key is #{headers.routing_key}"
+    channel.queue("us.california").bind(exchange, :routing_key => "americas.north.us.ca.*").subscribe do |metadata, payload|
+      puts "An update for US/California: #{payload}, routing key is #{metadata.routing_key}"
     end
-    channel.queue("us.tx.austin").bind(exchange, :routing_key => "#.tx.austin").subscribe do |headers, payload|
-      puts "An update for Austin, TX: #{payload}, routing key is #{headers.routing_key}"
+    channel.queue("us.tx.austin").bind(exchange, :routing_key => "#.tx.austin").subscribe do |metadata, payload|
+      puts "An update for Austin, TX: #{payload}, routing key is #{metadata.routing_key}"
     end
-    channel.queue("it.rome").bind(exchange, :routing_key => "europe.italy.rome").subscribe do |headers, payload|
-      puts "An update for Rome, Italy: #{payload}, routing key is #{headers.routing_key}"
+    channel.queue("it.rome").bind(exchange, :routing_key => "europe.italy.rome").subscribe do |metadata, payload|
+      puts "An update for Rome, Italy: #{payload}, routing key is #{metadata.routing_key}"
     end
-    channel.queue("asia.hk").bind(exchange, :routing_key => "asia.southeast.hk.#").subscribe do |headers, payload|
-      puts "An update for Hong Kong: #{payload}, routing key is #{headers.routing_key}"
+    channel.queue("asia.hk").bind(exchange, :routing_key => "asia.southeast.hk.#").subscribe do |metadata, payload|
+      puts "An update for Hong Kong: #{payload}, routing key is #{metadata.routing_key}"
     end
 
-    EM.add_timer(1) do
+    # publish a bunch of messages after 1 second, when all queues are declared and bound
+    EventMachine.add_timer(1) do
       exchange.publish("San Diego update", :routing_key => "americas.north.us.ca.sandiego").
         publish("Berkeley update",        :routing_key => "americas.north.us.ca.berkeley").
         publish("San Francisco update",    :routing_key => "americas.north.us.ca.sanfrancisco").
@@ -49,13 +50,7 @@ EventMachine.run do
     end
 
 
-    show_stopper = Proc.new {
-      connection.close do
-        EM.stop
-      end
-    }
-
-    Signal.trap "INT",  show_stopper
+    show_stopper = Proc.new { connection.close { EventMachine.stop } }
     Signal.trap "TERM", show_stopper
 
     EM.add_timer(3, show_stopper)

data/examples/tls/using_tls.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require "bundler"
+Bundler.setup
+
+$:.unshift(File.expand_path("../../../lib", __FILE__))
+
+examples_dir = File.join(File.dirname(File.expand_path(__FILE__)), "..")
+
+certificate_chain_file_path  = File.join(examples_dir, "tls_certificates", "client", "cert.pem")
+client_private_key_file_path = File.join(examples_dir, "tls_certificates", "client", "key.pem")
+
+
+require 'amqp'
+
+# This example assumes you have configured RabbitMQ to listen on port 5671
+# for TLS connections (using RabbitMQ configuration file), for example:
+#
+# [
+#   {rabbit, [
+#      {ssl_listeners, [5671]},
+#      {ssl_options, [{cacertfile, "/usr/local/etc/rabbitmq/tls/testca/cacert.pem"},
+#                     {certfile,   "/usr/local/etc/rabbitmq/tls/server/cert.pem"},
+#                     {keyfile,    "/usr/local/etc/rabbitmq/tls/server/key.pem"},
+#                     {verify,     verify_peer},
+#                     {fail_if_no_peer_cert, true}]}
+#    ]}
+# ].
+#
+# See TLS certificates under ./examples/tls_certificates
+
+AMQP.start(:port     => 5671,
+           :ssl => {
+             :cert_chain_file  => certificate_chain_file_path,
+             :private_key_file => client_private_key_file_path
+           }) do |connection|
+  puts "Connected, authenticated. TLS seems to work."
+
+  connection.disconnect { puts "Now closing the connection…"; EventMachine.stop }
+end

data/lib/amqp/bit_set.rb

@@ -0,0 +1,80 @@
+# encoding: utf-8
+
+module AMQP
+  # Very minimalistic, pure Ruby implementation of bit set. Inspired by java.util.BitSet,
+  # although significantly smaller in scope.
+  class BitSet
+
+    #
+    # API
+    #
+
+    ADDRESS_BITS_PER_WORD = 6
+    BITS_PER_WORD         = (1 << ADDRESS_BITS_PER_WORD)
+    WORD_MASK             = 0xffffffffffffffff
+
+    # @param [Integer] Number of bits in the set
+    # @api public
+    def initialize(nbits)
+      @nbits = nbits
+
+      self.init_words(nbits)
+    end # initialize(nbits)
+
+    # Sets (flags) given bit. This method allows bits to be set more than once in a row, no exception will be raised.
+    #
+    # @param [Integer] A bit to set
+    # @api public
+    def set(i)
+      w = self.word_index(i)
+      @words[w] |= (1 << i)
+    end # set(i)
+
+    # Fetches flag value for given bit.
+    #
+    # @param [Integer] A bit to fetch
+    # @return [Boolean] true if given bit is set, false otherwise
+    # @api public
+    def get(i)
+      w = self.word_index(i)
+
+      (@words[w] & (1 << i)) != 0
+    end # get(i)
+    alias [] get
+
+    # Unsets (unflags) given bit. This method allows bits to be unset more than once in a row, no exception will be raised.
+    #
+    # @param [Integer] A bit to unset
+    # @api public
+    def unset(i)
+      w = self.word_index(i)
+      return if w.nil?
+
+      @words[w] &= ~(1 << i)
+    end # unset(i)
+
+    # Clears all bits in the set
+    # @api public
+    def clear
+      self.init_words(@nbits)
+    end # clear
+
+
+    #
+    # Implementation
+    #
+
+    protected
+
+    # @private
+    def init_words(nbits)
+      n      = word_index(nbits-1) + 1
+      @words = Array.new(n) { 1 }
+    end # init_words
+
+    # @private
+    def word_index(i)
+      i >> ADDRESS_BITS_PER_WORD
+    end # word_index(i)
+  end # BitSet
+end # AMQP

data/lib/amqp/broker.rb

@@ -0,0 +1,72 @@
+# encoding: utf-8
+
+module AMQP
+  # A utility class that makes inspection of broker capabilities easier.
+  class Broker
+
+    #
+    # API
+    #
+
+    RABBITMQ_PRODUCT = "RabbitMQ".freeze
+
+    # Broker information
+    # @return [Hash]
+    # @see Session#server_properties
+    attr_reader :properties
+
+    # @return [Hash] properties Broker information
+    # @see Session#server_properties
+    def initialize(properties)
+      @properties = properties
+    end # initialize(properties)
+
+    # @group Product information
+
+    # @return [Boolean] true if broker is RabbitMQ
+    def rabbitmq?
+      self.product == RABBITMQ_PRODUCT
+    end # rabbitmq?
+
+    # @return [String] Broker product information
+    def product
+      @product ||= @properties["product"]
+    end # product
+
+    # @return [String] Broker version
+    def version
+      @version ||= @properties["version"]
+    end # version
+
+    # @endgroup
+
+
+
+    # @group Product capabilities
+
+    # @return [Boolean]
+    def supports_publisher_confirmations?
+      @properties["capabilities"]["publisher_confirms"]
+    end # supports_publisher_confirmations?
+
+    # @return [Boolean]
+    def supports_basic_nack?
+      @properties["capabilities"]["basic.nack"]
+    end # supports_basic_nack?
+
+    # @return [Boolean]
+    def supports_consumer_cancel_notifications?
+      @properties["capabilities"]["consumer_cancel_notify"]
+    end # supports_consumer_cancel_notifications?
+
+    # @return [Boolean]
+    def supports_exchange_to_exchange_bindings?
+      @properties["capabilities"]["exchange_exchange_bindings"]
+    end # supports_exchange_to_exchange_bindings?
+
+
+    # @endgroup
+
+
+  end # Broker
+end # AMQP

data/lib/amqp/channel.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 
+require "amqp/int_allocator"
 require "amqp/exchange"
 require "amqp/queue"
 
@@ -156,9 +157,6 @@ module AMQP
     attr_reader :status
 
 
-    # @note We encourage you to not rely on default AMQP connection and pass connection parameter
-    #       explicitly.
-    #
     # @param [AMQP::Session] connection Connection to open this channel on. If not given, default AMQP
     #                                   connection (accessible via {AMQP.connection}) will be used.
     # @param [Integer]       id         Channel id. Must not be greater than max channel id client and broker
@@ -194,6 +192,7 @@ module AMQP
     #
     #
     # @option options [Boolean] :prefetch (nil)  Specifies number of messages to prefetch. Channel-specific. See {AMQP::Channel#prefetch}.
+    # @option options [Boolean] :auto_recovery (nil)  Turns on automatic network failure recovery mode for this channel.
     #
     # @yield [channel, open_ok] Yields open channel instance and AMQP method (channel.open-ok) instance. The latter is optional.
     # @yieldparam [Channel] channel Channel that is successfully open
@@ -205,14 +204,18 @@ module AMQP
     def initialize(connection = nil, id = self.class.next_channel_id, options = {}, &block)
       raise 'AMQP can only be used from within EM.run {}' unless EM.reactor_running?
 
-      @options    = options
       @connection = connection || AMQP.connection || AMQP.start
+      # this means 2nd argument is options
+      if id.kind_of?(Hash)
+        options = options.merge(id)
+        id      = self.class.next_channel_id
+      end
 
-      super(@connection, id)
+      super(@connection, id, options)
 
       @rpcs                       = Hash.new
       # we need this deferrable to mimic what AMQP gem 0.7 does to enable
-      # the following (HIGHLY discouraged) style of programming some people use in their
+      # the following (pseudo-synchronous) style of programming some people use in their
       # existing codebases:
       #
       # connection = AMQP.connect
@@ -242,6 +245,32 @@ module AMQP
       end # @connection.on_open
     end
 
+    # @return [Boolean] true if this channel is in automatic recovery mode
+    # @see #auto_recovering?
+    attr_accessor :auto_recovery
+
+    # @return [Boolean] true if this channel uses automatic recovery mode
+    def auto_recovering?
+      @auto_recovery
+    end # auto_recovering?
+
+    # Called by associated connection object when AMQP connection has been re-established
+    # (for example, after a network failure).
+    #
+    # @api plugin
+    def auto_recover
+      return unless auto_recovering?
+
+      self.open do
+        @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 }
+        @queues.each    { |name, q| q.auto_recover }
+      end
+    end # auto_recover
+
+
 
 
     # @group Declaring exchanges
@@ -753,6 +782,8 @@ module AMQP
     # @return [Queue]
     # @api public
     def queue(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?
+
       if name && !name.empty? && (queue = find_queue(name))
         extended_opts = Queue.add_default_options(name, opts, block)
 
@@ -791,6 +822,13 @@ module AMQP
       register_queue(queue)
     end
 
+    # @return [Array<AMQP::Queue>] Queues cache for this channel
+    # @api plugin
+    # @private
+    def queues
+      @queues
+    end # queues
+
     # @endgroup
 
 
@@ -872,7 +910,10 @@ module AMQP
     #
     # @api public
     def close(reply_code = 200, reply_text = DEFAULT_REPLY_TEXT, class_id = 0, method_id = 0, &block)
-      super(reply_code, reply_text, class_id, method_id, &block)
+      r = super(reply_code, reply_text, class_id, method_id, &block)
+      self.class.release_channel_id(@id)
+
+      r
     end
 
     # @endgroup
@@ -1090,8 +1131,10 @@ module AMQP
     #
     # @api plugin
     # @private
-    def handle_connection_interruption(exception = nil)
-      super(exception)
+    def handle_connection_interruption(reason = nil)
+      super(reason)
+
+      self.class.release_channel_id(@id) unless auto_recovering?
       @channel_is_open_deferrable = AMQ::Client::EventMachineClient::Deferrable.new
     end
 
@@ -1102,18 +1145,55 @@ module AMQP
       @channel_id_mutex ||= Mutex.new
     end
 
-    # Returns incrementing channel id. This method is thread safe.
+    # Returns next available channel id. This method is thread safe.
+    #
     # @return [Fixnum]
     # @api public
+    # @see Channel.release_channel_id
+    # @see Channel.reset_channel_id_allocator
     def self.next_channel_id
       channel_id_mutex.synchronize do
-        @last_channel_id ||= 0
-        @last_channel_id += 1
+        self.initialize_channel_id_allocator
 
-        @last_channel_id
+        @int_allocator.allocate
       end
     end
 
+    # Releases previously allocated channel id. This method is thread safe.
+    #
+    # @param [Fixnum] Channel id to release
+    # @api public
+    # @see Channel.next_channel_id
+    # @see Channel.reset_channel_id_allocator
+    def self.release_channel_id(i)
+      channel_id_mutex.synchronize do
+        self.initialize_channel_id_allocator
+
+        @int_allocator.release(i)
+      end
+    end # self.release_channel_id(i)
+
+    # Resets channel allocator. This method is thread safe.
+    # @api public
+    # @see Channel.next_channel_id
+    # @see Channel.release_channel_id
+    def self.reset_channel_id_allocator
+      channel_id_mutex.synchronize do
+        initialize_channel_id_allocator
+
+        @int_allocator.reset
+      end
+    end # self.reset_channel_id_allocator
+
+
+    # @private
+    def self.initialize_channel_id_allocator
+      # TODO: ideally, this should be in agreement with agreed max number of channels of the connection,
+      #       but it is possible that value either not yet available. MK.
+      max_channel     =  (1 << 16) - 1
+      @int_allocator ||= IntAllocator.new(1, max_channel)
+    end # self.initialize_channel_id_allocator
+
     # @private
     # @api plugin
     def register_rpc(rpc)