celldee-bunny 0.2.0 → 0.3.0

data/lib/bunny/exchange.rb

@@ -1,83 +1,158 @@
-module API
-	class Exchange
-	
-	  attr_reader :client, :type, :name, :opts, :key
+module Bunny
+  
+=begin rdoc
 
-	  def initialize(client, name, opts = {})
-			# check connection to server
-			raise API::ConnectionError, 'Not connected to server' if client.status == NOT_CONNECTED
-		
-	    @client, @name, @opts = client, name, opts
-	
-			# set up the exchange type catering for default names
-			if name.match(/^amq\./)
-				new_type = name.sub(/amq\./, '')
-				# handle 'amq.match' default
-				new_type = 'headers' if new_type == 'match'
-				@type = new_type.to_sym
-			else
-				@type = opts[:type] || :direct
-			end
-			
-	    @key = opts[:key]
-			@client.exchanges[@name] ||= self
-			
-			# ignore the :nowait option if passed, otherwise program will hang waiting for a
-			# response that will not be sent by the server
-			opts.delete(:nowait)
-			
-	    unless name == "amq.#{type}" or name == ''
-	      client.send_frame(
-	        Protocol::Exchange::Declare.new(
-	          { :exchange => name, :type => type, :nowait => false }.merge(opts)
-	        )
-	      )
-
-				raise API::ProtocolError,
-					"Error declaring exchange #{name}: type = #{type}" unless
-					client.next_method.is_a?(Protocol::Exchange::DeclareOk)
-	    end
-	  end
-
-	  def publish(data, opts = {})
-	    out = []
-
-	    out << Protocol::Basic::Publish.new(
-	      { :exchange => name, :routing_key => opts.delete(:key) || key }.merge(opts)
-	    )
-	    data = data.to_s
-	    out << Protocol::Header.new(
-	      Protocol::Basic,
-	      data.length, {
-	        :content_type  => 'application/octet-stream',
-	        :delivery_mode => (opts.delete(:persistent) ? 2 : 1),
-	        :priority      => 0 
-	      }.merge(opts)
-	    )
-	    out << Transport::Frame::Body.new(data)
-
-	    client.send_frame(*out)
-	  end
-
-	  def delete(opts = {})
-			# ignore the :nowait option if passed, otherwise program will hang waiting for a
-			# response that will not be sent by the server
-			opts.delete(:nowait)
-			
-	    client.send_frame(
-	      Protocol::Exchange::Delete.new({ :exchange => name, :nowait => false }.merge(opts))
-	    )
-
-			raise API::ProtocolError,
-				"Error deleting exchange #{name}" unless
-				client.next_method.is_a?(Protocol::Exchange::DeleteOk)
-
-			client.exchanges.delete(name)
-			
-			# return confirmation
-			EXCHANGE_DELETED
-	  end
-
-	end
+=== DESCRIPTION:
+
+*Exchanges* are the routing and distribution hub of AMQP. All messages that Bunny sends
+to an AMQP broker/server _have_ to pass through an exchange in order to be routed to a
+destination queue. The AMQP specification defines the types of exchange that you can create.
+
+At the time of writing there are four (4) types of exchange defined -
+
+* <tt>:direct</tt>
+* <tt>:fanout</tt>
+* <tt>:topic</tt>
+* <tt>:headers</tt>
+
+AMQP-compliant brokers/servers are required to provide default exchanges for the _direct_ and
+_fanout_ exchange types. All default exchanges are prefixed with <tt>'amq.'</tt>, for example -
+
+* <tt>amq.direct</tt>
+* <tt>amq.fanout</tt>
+* <tt>amq.topic</tt>
+* <tt>amq.match</tt> or <tt>amq.headers</tt>
+
+If you want more information about exchanges, please consult the documentation for your
+target broker/server or visit the {AMQP website}[http://www.amqp.org] to find the version of the
+specification that applies to your target broker/server.
+
+=end
+  
+  class Exchange
+
+    attr_reader :client, :type, :name, :opts, :key
+
+    def initialize(client, name, opts = {})
+      # check connection to server
+      raise Bunny::ConnectionError, 'Not connected to server' if client.status == :not_connected
+    
+      @client, @name, @opts = client, name, opts
+  
+      # set up the exchange type catering for default names
+      if name.match(/^amq\./)
+        new_type = name.sub(/amq\./, '')
+        # handle 'amq.match' default
+        new_type = 'headers' if new_type == 'match'
+        @type = new_type.to_sym
+      else
+        @type = opts[:type] || :direct
+      end
+      
+      @key = opts[:key]
+      @client.exchanges[@name] ||= self
+      
+      # ignore the :nowait option if passed, otherwise program will hang waiting for a
+      # response that will not be sent by the server
+      opts.delete(:nowait)
+      
+      unless name == "amq.#{type}" or name == ''
+        client.send_frame(
+          Protocol::Exchange::Declare.new(
+            { :exchange => name, :type => type, :nowait => false }.merge(opts)
+          )
+        )
+
+        raise Bunny::ProtocolError,
+          "Error declaring exchange #{name}: type = #{type}" unless
+          client.next_method.is_a?(Protocol::Exchange::DeclareOk)
+      end
+    end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Publishes a message to a specific exchange. The message will be routed to queues as defined
+by the exchange configuration and distributed to any active consumers when the transaction,
+if any, is committed.
+
+==== OPTIONS:
+
+* <tt>:key => 'routing_key'</tt> - Specifies the routing key for the message. The routing key is
+  used for routing messages depending on the exchange configuration.
+* <tt>:mandatory => true or false (_default_)</tt> - Tells the server how to react if the message
+  cannot be routed to a queue. If set to _true_, the server will return an unroutable message
+  with a Return method. If this flag is zero, the server silently drops the message.
+* <tt>:immediate => true or false (_default_)</tt> - Tells the server how to react if the message
+  cannot be routed to a queue consumer immediately. If set to _true_, the server will return an
+  undeliverable message with a Return method. If set to _false_, the server will queue the message,
+  but with no guarantee that it will ever be consumed.
+
+==== RETURNS:
+
+nil
+
+=end
+
+    def publish(data, opts = {})
+      out = []
+
+      out << Protocol::Basic::Publish.new(
+        { :exchange => name, :routing_key => opts.delete(:key) || key }.merge(opts)
+      )
+      data = data.to_s
+      out << Protocol::Header.new(
+        Protocol::Basic,
+        data.length, {
+          :content_type  => 'application/octet-stream',
+          :delivery_mode => (opts.delete(:persistent) ? 2 : 1),
+          :priority      => 0 
+        }.merge(opts)
+      )
+      out << Transport::Frame::Body.new(data)
+
+      client.send_frame(*out)
+    end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Requests that an exchange is deleted from broker/server. Removes reference from exchanges
+if successful. If an error occurs raises _Bunny_::_ProtocolError_.
 	
+==== Options:
+
+* <tt>:if_unused => true or false (_default_)</tt> - If set to _true_, 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.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== Returns:
+
+<tt>:delete_ok</tt> if successful
+=end
+
+    def delete(opts = {})
+      # ignore the :nowait option if passed, otherwise program will hang waiting for a
+      # response that will not be sent by the server
+      opts.delete(:nowait)
+      
+      client.send_frame(
+        Protocol::Exchange::Delete.new({ :exchange => name, :nowait => false }.merge(opts))
+      )
+
+      raise Bunny::ProtocolError,
+        "Error deleting exchange #{name}" unless
+        client.next_method.is_a?(Protocol::Exchange::DeleteOk)
+
+      client.exchanges.delete(name)
+      
+      # return confirmation
+      :delete_ok
+    end
+
+  end
+  
 end

data/lib/bunny/protocol/protocol.rb

@@ -0,0 +1,135 @@
+module Bunny
+	module Protocol
+	  #:stopdoc:
+	  class Class::Method
+	    def initialize *args
+	      opts = args.pop if args.last.is_a? Hash
+	      opts ||= {}
+      
+	      @debug = 1 # XXX hack, p(obj) == '' if no instance vars are set
+      
+	      if args.size == 1 and args.first.is_a? Transport::Buffer
+	        buf = args.shift
+	      else
+	        buf = nil
+	      end
+
+	      self.class.arguments.each do |type, name|
+	        val = buf ? buf.read(type) :
+	                    args.shift || opts[name] || opts[name.to_s]
+	        instance_variable_set("@#{name}", val)
+	      end
+	    end
+
+	    def arguments
+	      self.class.arguments.inject({}) do |hash, (type, name)|
+	        hash.update name => instance_variable_get("@#{name}")
+	      end
+	    end
+
+	    def to_binary
+	      buf = Transport::Buffer.new
+	      buf.write :short, self.class.parent.id
+	      buf.write :short, self.class.id
+
+	      bits = []
+
+	      self.class.arguments.each do |type, name|
+	        val = instance_variable_get("@#{name}")
+	        if type == :bit
+	          bits << (val || false)
+	        else
+	          unless bits.empty?
+	            buf.write :bit, bits
+	            bits = []
+	          end
+	          buf.write type, val
+	        end
+	      end
+
+	      buf.write :bit, bits unless bits.empty?
+	      buf.rewind
+
+	      buf
+	    end
+    
+	    def to_s
+	      to_binary.to_s
+	    end
+    
+	    def to_frame channel = 0
+	      Transport::Frame::Method.new(self, channel)
+	    end
+	  end
+
+	  class Header
+	    def initialize *args
+	      opts = args.pop if args.last.is_a? Hash
+	      opts ||= {}
+      
+	      first = args.shift
+      
+	      if first.is_a? ::Class and first.ancestors.include? Protocol::Class
+	        @klass = first
+	        @size = args.shift || 0
+	        @weight = args.shift || 0
+	        @properties = opts
+
+	      elsif first.is_a? Transport::Buffer or first.is_a? String
+	        buf = first
+	        buf = Transport::Buffer.new(buf) unless buf.is_a? Transport::Buffer
+        
+	        @klass = Protocol.classes[buf.read(:short)]
+	        @weight = buf.read(:short)
+	        @size = buf.read(:longlong)
+
+	        props = buf.read(:properties, *klass.properties.map{|type,_| type })
+	        @properties = Hash[*klass.properties.map{|_,name| name }.zip(props).reject{|k,v| v.nil? }.flatten]
+
+	      else
+	        raise ArgumentError, 'Invalid argument'
+	      end
+      
+	    end
+	    attr_accessor :klass, :size, :weight, :properties
+    
+	    def to_binary
+	      buf = Transport::Buffer.new
+	      buf.write :short, klass.id
+	      buf.write :short, weight # XXX rabbitmq only supports weight == 0
+	      buf.write :longlong, size
+	      buf.write :properties, (klass.properties.map do |type, name|
+	                               [ type, properties[name] || properties[name.to_s] ]
+	                             end)
+	      buf.rewind
+	      buf
+	    end
+    
+	    def to_s
+	      to_binary.to_s
+	    end
+
+	    def to_frame channel = 0
+	      Transport::Frame::Header.new(self, channel)
+	    end
+
+	    def == header
+	      [ :klass, :size, :weight, :properties ].inject(true) do |eql, field|
+	        eql and __send__(field) == header.__send__(field)
+	      end
+	    end
+
+	    def method_missing meth, *args, &blk
+	      @properties.has_key?(meth) || @klass.properties.find{|_,name| name == meth } ? @properties[meth] :
+	                                                                                     super
+	    end
+	  end
+
+	  def self.parse buf
+	    buf = Transport::Buffer.new(buf) unless buf.is_a? Transport::Buffer
+	    class_id, method_id = buf.read(:short, :short)
+	    classes[class_id].methods[method_id].new(buf)
+	  end
+
+	end
+end