amqp 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8f2f4d10362c5c533ba2d5b430626abb8e1eaa98
-  data.tar.gz: f80eecaca4102e7c3c0a2ff7522a2d090ddb23f4
+  metadata.gz: c7cd9670c82561f472831d5844d8aedf21704384
+  data.tar.gz: 72de0158e4620a8c11468fa6ae141770f5eb5c40
 SHA512:
-  metadata.gz: 0499db6a9bcf66885c76c95824a913571e2833e88fedf6d2b659ca01b3c21c52d30f3fb779eada43918bff9d5b0dbe705f29cc9ff11a32643cf6a592ccca996e
-  data.tar.gz: 58bc2ac9aa9412196ab37aaea1c3f968fdf76b8f5ff1bfa430ceec516cc04ed473b4e01dd8ef353184c055d05c5d37ebe80354f91f9d60d663895eec83a16b3f
+  metadata.gz: 0590210e5493862466fc7c5bfaae3322f4fcd4c738f57eba25e811d4d76205b51b6bf327c44941f59a6b93a24436d6961baaafefeaf64c88b378a7faa6a24dba
+  data.tar.gz: b579abed8e4432158e908dd6d4e992c17e815029b89b3ccb6b0a7b15483eb2bb21a7dc49df7fe389e4d9adc04660b19d0dd8ef620a15578d880b18181932cfa9

data/ChangeLog.md

@@ -1,4 +1,26 @@
-## Changes Between 1.2.0 and 1.2.1
+## Changes Between 1.2.x and 1.3.0
+
+### Exchange-to-Exchange Bindings Support
+
+amqp gem now supports [Exchange-to-Exchange Bindings](http://www.rabbitmq.com/e2e.html), a RabbitMQ
+extension.
+
+`AMQP::Exchange#bind` and `AMQP::Exchange#unbind` work very much like `AMQP::Queue#bind` and
+`AMQP::Queue#unbind`, with the argument exchange being the source one.
+
+Contributed by Stefan Kaes.
+
+### Internal Exchange Declaration
+
+amqp gem now supports declaration of internal exchanges
+(used via exchange-to-exchange bindings, cannot be published to
+by clients).
+
+To declare an exchange as internal, add `:internal => true` to
+declaration options.
+
+Contributed by Stefan Kaes.
+
 
 ### Initial Connection Failures Retries
 
@@ -7,7 +29,6 @@ means connection retries succeed.
 
 Contributed by Marius Hanne.
 
-
 ## Changes Between 1.1.0 and 1.2.0
 
 ### [Authentication Failure Notification](http://www.rabbitmq.com/auth-notification.html) Support
@@ -53,10 +74,6 @@ very short lived channels.
 `ConnectionClosedError` from `amq-client` is now defined again.
 
 
-### amq-protocol Update
-
-Minimum `amq-protocol` version is now `1.9.0`.
-
 ### Fixed Exceptions in AMQP::Exchange#handle_declare_ok
 
 `AMQP::Exchange#handle_declare_ok` no longer raises an exception

data/lib/amqp/channel.rb

@@ -172,7 +172,7 @@ module AMQP
 
     attr_reader :id
 
-    attr_reader :exchanges_awaiting_declare_ok, :exchanges_awaiting_delete_ok
+    attr_reader :exchanges_awaiting_declare_ok, :exchanges_awaiting_delete_ok, :exchanges_awaiting_bind_ok, :exchanges_awaiting_unbind_ok
     attr_reader :queues_awaiting_declare_ok, :queues_awaiting_delete_ok, :queues_awaiting_bind_ok, :queues_awaiting_unbind_ok, :queues_awaiting_purge_ok, :queues_awaiting_get_response
     attr_reader :consumers_awaiting_consume_ok, :consumers_awaiting_cancel_ok
 
@@ -1424,6 +1424,8 @@ module AMQP
 
       @queues_awaiting_declare_ok    = Array.new
       @exchanges_awaiting_declare_ok = Array.new
+      @exchanges_awaiting_bind_ok    = Array.new
+      @exchanges_awaiting_unbind_ok  = Array.new
 
       @queues_awaiting_delete_ok     = Array.new
 

data/lib/amqp/exchange.rb

@@ -365,9 +365,9 @@ module AMQP
                 end
               end
 
-              self.exchange_declare(passive = @opts[:passive], durable = @opts[:durable], auto_delete = @opts[:auto_delete], nowait = @opts[:nowait], @opts[:arguments], &shim)
+              self.exchange_declare(@opts[:passive], @opts[:durable], @opts[:auto_delete], @opts[:internal], @opts[:nowait], @opts[:arguments], &shim)
             else
-              self.exchange_declare(passive = @opts[:passive], durable = @opts[:durable], auto_delete = @opts[:auto_delete], nowait = @opts[:nowait], @opts[:arguments])
+              self.exchange_declare(@opts[:passive], @opts[:durable], @opts[:auto_delete], @opts[:internal], @opts[:nowait], @opts[:arguments])
             end
           end
         end
@@ -422,6 +422,10 @@ module AMQP
       @name && ((@name == AMQ::Protocol::EMPTY_STRING) || !!(@name =~ /^amq\.(direct|fanout|topic|headers|match)/i))
     end # predefined?
 
+    # @return [Boolean] true if this exchange is an internal exchange
+    def internal?
+      @opts[:internal]
+    end
 
     # 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
@@ -604,14 +608,15 @@ module AMQP
     # @group Declaration
 
     # @api public
-    def exchange_declare(passive = false, durable = false, auto_delete = false, nowait = false, arguments = nil, &block)
+    def exchange_declare(passive = false, durable = false, auto_delete = false, internal = false, nowait = false, arguments = nil, &block)
       # for re-declaration
       @passive     = passive
       @durable     = durable
       @auto_delete = auto_delete
       @arguments   = arguments
+      @internal    = internal
 
-      @connection.send_frame(AMQ::Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, passive, durable, auto_delete, false, nowait, arguments))
+      @connection.send_frame(AMQ::Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, passive, durable, auto_delete, internal, nowait, arguments))
 
       unless nowait
         self.define_callback(:declare, &block)
@@ -625,7 +630,7 @@ module AMQP
     # @api public
     def redeclare(&block)
       nowait = block.nil?
-      @connection.send_frame(AMQ::Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, @passive, @durable, @auto_delete, false, nowait, @arguments))
+      @connection.send_frame(AMQ::Protocol::Exchange::Declare.encode(@channel.id, @name, @type.to_s, @passive, @durable, @auto_delete, @internal, nowait, @arguments))
 
       unless nowait
         self.define_callback(:declare, &block)
@@ -653,6 +658,111 @@ module AMQP
     end # delete(if_unused = false, nowait = false)
 
 
+    # @group Exchange to Exchange Bindings
+
+    # This method binds a source exchange to a destination exchange. Messages
+    # sent to the source exchange are forwarded to the destination exchange, provided
+    # the message routing key matches the routing key specified when binding the
+    # exchanges.
+    #
+    # A valid exchange name (or reference) must be passed as the first
+    # parameter.
+    # @example Binding two source exchanges to a destination exchange
+    #
+    #  ch          = AMQP::Channel.new(connection)
+    #  source1     = ch.fanout('backlog-events-datacenter-1')
+    #  source2     = ch.fanout('backlog-events-datacenter-2')
+    #  destination = ch.fanout('baklog-events')
+    #  destination.bind(source1).bind(source2)
+    #
+    #
+    # @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.
+    #                                      Not all exchanges use a routing key! Refer to the specific
+    #                                      exchange documentation.
+    #
+    # @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.
+    # @return [Exchange] Self
+    #
+    #
+    # @yield [] Since exchange.bind-ok carries no attributes, no parameters are yielded to the block.
+    #
+
+    # @api public
+    def bind(source, opts = {}, &block)
+      source = source.name if source.respond_to?(:name)
+      routing_key = opts[:key] || opts[:routing_key] || AMQ::Protocol::EMPTY_STRING
+      arguments = opts[:arguments] || {}
+      nowait = opts[:nowait] || block.nil?
+      @channel.once_open do
+        @connection.send_frame(AMQ::Protocol::Exchange::Bind.encode(@channel.id, @name, source, routing_key, nowait, arguments))
+        unless nowait
+          self.define_callback(:bind, &block)
+          @channel.exchanges_awaiting_bind_ok.push(self)
+        end
+      end
+      self
+    end
+
+    # This method unbinds a source exchange from a previously bound destination exchange.
+    #
+    # A valid exchange name (or reference) must be passed as the first
+    # parameter.
+    # @example Binding and unbinding two exchanges
+    #
+    #  ch          = AMQP::Channel.new(connection)
+    #  source      = ch.fanout('backlog-events')
+    #  destination = ch.fanout('backlog-events-copy')
+    #  destination.bind(source)
+    #  ...
+    #  destination.unbind(source)
+    #
+    #
+    # @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.
+    #                                      Not all exchanges use a routing key! Refer to the specific
+    #                                      exchange documentation.
+    #
+    # @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.
+    # @return [Exchange] Self
+    #
+    #
+    # @yield [] Since exchange.unbind-ok carries no attributes, no parameters are yielded to the block.
+    #
+
+    # @api public
+    def unbind(source, opts = {}, &block)
+      source = source.name if source.respond_to?(:name)
+      routing_key = opts[:key] || opts[:routing_key] || AMQ::Protocol::EMPTY_STRING
+      arguments = opts[:arguments] || {}
+      nowait = opts[:nowait] || block.nil?
+      @channel.once_open do
+        @connection.send_frame(AMQ::Protocol::Exchange::Unbind.encode(@channel.id, @name, source, routing_key, nowait, arguments))
+        unless nowait
+          self.define_callback(:unbind, &block)
+          @channel.exchanges_awaiting_unbind_ok.push(self)
+        end
+      end
+      self
+    end
+
+    # @endgroup
 
     # @group Publishing Messages
 
@@ -750,10 +860,17 @@ module AMQP
       self.exec_callback_once_yielding_self(:declare, method)
     end
 
+    def handle_bind_ok(method)
+      self.exec_callback_once(:bind, method)
+    end
+
+    def handle_unbind_ok(method)
+      self.exec_callback_once(:unbind, method)
+    end
+
     def handle_delete_ok(method)
       self.exec_callback_once(:delete, method)
-    end # handle_delete_ok(method)
-
+    end
 
 
     self.handle(AMQ::Protocol::Exchange::DeclareOk) do |connection, frame|
@@ -764,6 +881,21 @@ module AMQP
       exchange.handle_declare_ok(method)
     end # handle
 
+    self.handle(AMQ::Protocol::Exchange::BindOk) do |connection, frame|
+      method   = frame.decode_payload
+      channel  = connection.channels[frame.channel]
+      exchange = channel.exchanges_awaiting_bind_ok.shift
+
+      exchange.handle_bind_ok(method)
+    end # handle
+
+    self.handle(AMQ::Protocol::Exchange::UnbindOk) do |connection, frame|
+      method   = frame.decode_payload
+      channel  = connection.channels[frame.channel]
+      exchange = channel.exchanges_awaiting_unbind_ok.shift
+
+      exchange.handle_unbind_ok(method)
+    end # handle
 
     self.handle(AMQ::Protocol::Exchange::DeleteOk) do |connection, frame|
       channel  = connection.channels[frame.channel]
@@ -789,7 +921,7 @@ module AMQP
 
     # @private
     def self.add_default_options(type, name, opts, block)
-      { :exchange => name, :type => type, :nowait => block.nil? }.merge(opts)
+      { :exchange => name, :type => type, :nowait => block.nil?, :internal => false }.merge(opts)
     end
   end # Exchange
 end # AMQP

data/lib/amqp/version.rb

@@ -6,5 +6,5 @@ module AMQP
   #
   # @see AMQ::Protocol::VERSION
   # @return [String] AMQP gem version
-  VERSION = '1.2.1'
+  VERSION = '1.3.0'
 end

data/spec/integration/exchange_declaration_spec.rb

@@ -472,6 +472,28 @@ describe AMQP::Channel do
       end # it
     end # context
 
+    context "when exchange is declared with or without :internal parameter" do
+      it "should create a public exchange by default" do
+        exchange = @channel.topic("a new public topic exchange")
+
+        exchange.should_not be_internal
+        done
+      end # it
+
+      it "should create a public exchange when :internal is false" do
+        exchange = @channel.topic("a new-public topic exchange", :internal => false)
+
+        exchange.should_not be_internal
+        done
+      end # it
+
+      it "should create an internal exchange when :internal is true" do
+        exchange = @channel.topic("a new internal topic exchange", :internal => true)
+
+        exchange.should be_internal
+        done
+      end # it
+    end # context
 
     context "when exchange is re-declared with parameters different from the original declaration" do
       amqp_after do

data/spec/integration/exchange_to_exchange_binding_spec.rb

@@ -0,0 +1,124 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe AMQP::Channel do
+
+  #
+  # Environment
+  #
+
+  include EventedSpec::AMQPSpec
+
+  default_options AMQP_OPTS
+  default_timeout 2
+
+
+  amqp_before do
+    @channel = AMQP::Channel.new
+  end
+
+  #
+  # Examples
+  #
+
+  describe "exchange to exchange bindings" do
+    context "basic properties" do
+      it "bind returns self" do
+        source1 = @channel.fanout("fanout-exchange-source-1")
+        source2 = @channel.fanout("fanout-exchange-source-2")
+        destination = @channel.fanout("fanout-exchange-destination-multi")
+        destination.bind(source1).bind(source2).should == destination
+        done
+      end
+
+      it "bind can work with strings for source exchange parameter" do
+        @channel.fanout("fanout-exchange-source-3")
+        destination = @channel.fanout("fanout-exchange-destination-multi-2")
+        destination.bind('fanout-exchange-source-3').should == destination
+        done
+      end
+    end
+
+    context "fanout exchanges" do
+      it "are bindable and forward messages" do
+        source = @channel.fanout("fanout-exchange-source")
+        destination = @channel.fanout("fanout-exchange-destination")
+        messages = []
+        destination.bind(source) do
+          queue = @channel.queue("fanout-forwarding", :auto_delete => true)
+          queue.subscribe do |metadata, payload|
+            messages << payload
+          end
+          queue.bind(destination) do
+            source.publish("x")
+          end
+        end
+        done(0.1) { messages.should == ["x"] }
+      end
+
+      it "can be unbound" do
+        source = @channel.fanout("fanout-exchange-source-2")
+        destination = @channel.fanout("fanout-exchange-destination-2")
+        destination.bind(source) do
+          destination.unbind(source) do
+            done
+          end
+        end
+      end
+
+      it "can be unbound without callbacks" do
+        source = @channel.fanout("fanout-exchange-source-2")
+        destination = @channel.fanout("fanout-exchange-destination-2")
+        destination.bind(source)
+        destination.unbind(source)
+        done
+      end
+
+      it "using :nowait => true should not call a passed in block" do
+        source = @channel.fanout("fanout-exchange-source-no-wait")
+        destination = @channel.fanout("fanout-exchange-destination-no-wait")
+        callback_called = false
+        destination.bind(source, :nowait => true) do
+          callback_called = true
+        end
+        done(0.1) { callback_called.should be_false}
+      end
+
+    end #context
+
+    context "topic exchanges" do
+      it "using routing key '#'" do
+        source = @channel.topic("topic-exchange-source")
+        destination = @channel.topic("topic-exchange-destination")
+        messages = []
+        destination.bind(source) do
+          queue = @channel.queue("ex-to-ex-default-key", :auto_delete => true)
+          queue.subscribe do |metadata, payload|
+            messages << payload
+          end
+          queue.bind(destination, :routing_key => "#") do
+            source.publish("a", :routing_key => "lalalala")
+          end
+        end
+        done(0.1) { messages.should == ["a"] }
+      end
+
+      it "using routing key 'foo'" do
+        source = @channel.topic("topic-exchange-source-foo")
+        destination = @channel.topic("topic-exchange-destination-foo")
+        messages = []
+        destination.bind(source, :routing_key => 'foo') do
+          queue = @channel.queue("foo-foo", :auto_delete => true)
+          queue.subscribe do |metadata, payload|
+            messages << payload
+          end
+          queue.bind(destination, :routing_key => "foo") do
+            source.publish("b", :routing_key => "foo")
+          end
+        end
+        done(0.1) { messages.should == ["b"]}
+      end
+    end #context
+  end # describe
+end # describe AMQP

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: amqp
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Aman Gupta
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-23 00:00:00.000000000 Z
+date: 2014-02-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
@@ -272,6 +272,7 @@ files:
 - spec/integration/declare_one_hundred_server_named_queues_spec.rb
 - spec/integration/direct_exchange_routing_spec.rb
 - spec/integration/exchange_declaration_spec.rb
+- spec/integration/exchange_to_exchange_binding_spec.rb
 - spec/integration/extensions/rabbitmq/publisher_confirmations_spec.rb
 - spec/integration/fanout_exchange_routing_spec.rb
 - spec/integration/headers_exchange_routing_spec.rb