bunny 0.2.0 → 0.3.0

data/lib/bunny/queue.rb

@@ -1,12 +1,21 @@
-module API
+module Bunny
+	
+=begin rdoc
+
+=== DESCRIPTION:
+
+Queues store and forward messages. Queues can be configured in the server or created at runtime.
+Queues must be attached to at least one exchange in order to receive messages from publishers.
+
+=end
+
 	class Queue
-		
 	  attr_reader :name, :client
 	  attr_accessor :delivery_tag
 
 	  def initialize(client, name, opts = {})
 			# check connection to server
-			raise API::ConnectionError, 'Not connected to server' if client.status == NOT_CONNECTED
+			raise Bunny::ConnectionError, 'Not connected to server' if client.status == :not_connected
 			
 	    @client = client
 	    @opts   = opts
@@ -21,8 +30,25 @@ module API
 	      Protocol::Queue::Declare.new({ :queue => name, :nowait => false }.merge(opts))
 	    )
 	
-			raise API::ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Protocol::Queue::DeclareOk)
+			raise Bunny::ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Protocol::Queue::DeclareOk)
 	  end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Acknowledges one or more messages delivered via the _Deliver_ or _Get_-_Ok_ methods. The client can
+ask to confirm a single message or a set of messages up to and including a specific message.
+
+==== OPTIONS:
+
+* <tt>:delivery_tag</tt>
+* <tt>:multiple => true or false (_default_)</tt> - If set to _true_, the delivery tag is treated
+  as "up to and including", so that the client can acknowledge multiple messages with a single
+  method. If set to _false_, the delivery tag refers to a single message. If the multiple field
+  is _true_, and the delivery tag is zero, tells the server to acknowledge all outstanding messages.
+
+=end
 	
 		def ack
       client.send_frame(
@@ -33,6 +59,29 @@ module API
 			self.delivery_tag = nil
     end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Gets a message from a queue in a synchronous way. If error occurs, raises _Bunny_::_ProtocolError_.
+
+==== OPTIONS:
+
+* <tt>:header => true or false (_default_)</tt> - If set to _true_,
+  hash <tt>{:header, :delivery_details, :payload}</tt> is returned. 
+* <tt>:no_ack => true (_default_) or false</tt> - If set to _true_, the server does not expect an
+  acknowledgement message from the client. If set to _false_, the server expects an acknowledgement
+  message from the client and will re-queue the message if it does not receive one within a time specified
+  by the server.
+
+==== RETURNS:
+
+If <tt>:header => true</tt> returns hash <tt>{:header, :delivery_details, :payload}</tt>. <tt>:delivery_details</tt> is
+a hash <tt>{:delivery_tag, :redelivered, :exchange, :routing_key, :message_count}</tt>. If 
+<tt>:header => false</tt> only the message payload is returned.
+
+=end
+
 	  def pop(opts = {})
 			
 			# do we want the message header?
@@ -51,9 +100,9 @@ module API
 			method = client.next_method
 			
 			if method.is_a?(Protocol::Basic::GetEmpty) then
-				return QUEUE_EMPTY
+				return :queue_empty
 			elsif	!method.is_a?(Protocol::Basic::GetOk)
-				raise API::ProtocolError, "Error getting message from queue #{name}"
+				raise Bunny::ProtocolError, "Error getting message from queue #{name}"
 			end
 			
 			# get delivery tag to use for acknowledge
@@ -61,39 +110,107 @@ module API
 			
 	    header = client.next_payload
 	    msg    = client.next_payload
-	    raise API::MessageError, 'unexpected length' if msg.length < header.size
+	    raise Bunny::MessageError, 'unexpected length' if msg.length < header.size
 
-			hdr ? {:header => header, :payload => msg} : msg
+			# Return message with additional info if requested
+			hdr ? {:header => header, :payload => msg, :delivery_details => method.arguments} : msg
 			
 	  end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Publishes a message to the queue via the default nameless '' direct exchange.
+
+==== RETURNS:
+
+nil
+
+=end
+
 	  def publish(data, opts = {})
 	    exchange.publish(data, opts)
 	  end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns message count from Queue#status.
+
+=end
+
 	  def message_count
 	    s = status
 			s[:message_count]
 	  end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns consumer count from Queue#status.
+
+=end
+		
 	  def consumer_count
 	    s = status
 			s[:consumer_count]
 	  end
-  
-	  def status(opts = {})
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns hash {:message_count, :consumer_count}.
+
+=end
+ 
+	  def status
 	    client.send_frame(
-	      Protocol::Queue::Declare.new({ :queue => name, :passive => true }.merge(opts))
+	      Protocol::Queue::Declare.new({ :queue => name, :passive => true })
 	    )
 	    method = client.next_method
 	    {:message_count => method.message_count, :consumer_count => method.consumer_count}
 	  end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Asks the server to start a "consumer", which is a transient request for messages from a specific
+queue. Consumers last as long as the channel they were created on, or until the client cancels them
+with an _unsubscribe_. Every time a message reaches the queue it is passed to the _blk_ for
+processing. If error occurs, _Bunny_::_ProtocolError_ is raised.
+
+==== OPTIONS:
+* <tt>:header => true or false (_default_)</tt> - If set to _true_, hash is delivered for each message
+  <tt>{:header, :delivery_details, :payload}</tt>.
+* <tt>:consumer_tag => '_tag_'</tt> - Specifies the identifier for the consumer. The consumer tag is
+  local to a connection, so two clients can use the same consumer tags. If this field is empty the
+  queue name is used.
+* <tt>:no_ack=> true (_default_) or false</tt> - If set to _true_, the server does not expect an
+  acknowledgement message from the client. If set to _false_, the server expects an acknowledgement
+  message from the client and will re-queue the message if it does not receive one within a time specified
+  by the server.
+* <tt>:exclusive => true or false (_default_)</tt> - Request exclusive consumer access, meaning
+  only this consumer can access the queue.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== RETURNS:
+
+If <tt>:header => true</tt> returns hash <tt>{:header, :delivery_details, :payload}</tt> for each message.
+<tt>:delivery_details</tt> is a hash <tt>{:consumer_tag, :delivery_tag, :redelivered, :exchange, :routing_key}</tt>.
+If <tt>:header => false</tt> only message payload is returned.
+
+=end
 	
 		def subscribe(opts = {}, &blk)
 			consumer_tag = opts[:consumer_tag] || name
 			
-			# ignore the :nowait option if passed, otherwise program will not wait for a
-			# message to get to the server causing an error
+			# ignore the :nowait option if passed, otherwise program will hang waiting for a
+			# response from the server causing an error.
 			opts.delete(:nowait)
 			
 			# do we want the message header?
@@ -109,12 +226,13 @@ module API
 																	 		 :nowait => false }.merge(opts))
 			)
 			
-			raise API::ProtocolError,
+			raise Bunny::ProtocolError,
 				"Error subscribing to queue #{name}" unless
 				client.next_method.is_a?(Protocol::Basic::ConsumeOk)
 			
 			while true
 				method = client.next_method
+
 				break if method.is_a?(Protocol::Basic::CancelOk)
 			
 				# get delivery tag to use for acknowledge
@@ -122,19 +240,56 @@ module API
 			
 				header = client.next_payload
 		    msg    = client.next_payload
-		    raise API::MessageError, 'unexpected length' if msg.length < header.size
+		    raise Bunny::MessageError, 'unexpected length' if msg.length < header.size
 				
-				# pass the message to the block for processing
-				blk.call(hdr ? {:header => header, :payload => msg} : msg)
+				# pass the message and related info, if requested, to the block for processing
+				blk.call(hdr ? {:header => header, :payload => msg, :delivery_details => method.arguments} : msg)
 			end
 			
 		end
 		
+=begin rdoc
+
+=== DESCRIPTION:
+
+Cancels a consumer. This does not affect already delivered messages, but it does mean
+the server will not send any more messages for that consumer.
+
+==== OPTIONS:
+
+* <tt>:consumer_tag => '_tag_'</tt> - Specifies the identifier for the consumer.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+=end
+		
 		def unsubscribe(opts = {})
 			consumer_tag = opts[:consumer_tag] || name
+			
+			# ignore the :nowait option if passed, otherwise program will hang waiting for a
+			# response from the server causing an error
+			opts.delete(:nowait)
+			
       client.send_frame( Protocol::Basic::Cancel.new({ :consumer_tag => consumer_tag }.merge(opts)))
+			
     end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Binds a queue to an exchange. Until a queue is bound it will not receive any messages. Queues are
+bound to the direct exchange '' by default. If error occurs, a _Bunny_::_ProtocolError_ is raised.
+
+* <tt>:key => 'routing key'* <tt>:key => 'routing_key'</tt> - Specifies the routing key for
+  the binding. The routing key is used for routing messages depending on the exchange configuration.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== RETURNS:
+
+<tt>:bind_ok</tt> if successful.
+
+=end
+
 	  def bind(exchange, opts = {})
 	    exchange           = exchange.respond_to?(:name) ? exchange.name : exchange
 	
@@ -150,16 +305,38 @@ module API
 		 																:nowait => false }.merge(opts))
 	    )
 	
-			raise API::ProtocolError,
+			raise Bunny::ProtocolError,
 				"Error binding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::BindOk)
 				
 			# return message
-			BIND_SUCCEEDED
+			:bind_ok
 	  end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Removes a queue binding from an exchange. If error occurs, a _Bunny_::_ProtocolError_ is raised.
+
+==== OPTIONS:
+* <tt>:key => 'routing key'* <tt>:key => 'routing_key'</tt> - Specifies the routing key for
+  the binding.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== RETURNS:
+
+<tt>:unbind_ok</tt> if successful.
+
+=end
+
 	  def unbind(exchange, opts = {})
 	    exchange = exchange.respond_to?(:name) ? exchange.name : exchange
+	
+			# 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)
+			
 	    bindings.delete(exchange)
 
 	    client.send_frame(
@@ -170,13 +347,36 @@ module API
 	      )
 	    )
 	
-			raise API::ProtocolError,
+			raise Bunny::ProtocolError,
 				"Error unbinding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::UnbindOk)
 				
 			# return message
-			UNBIND_SUCCEEDED
+			:unbind_ok
 	  end
+	
+=begin rdoc
+
+=== DESCRIPTION:
+
+Requests that a queue is deleted from broker/server. When a queue is deleted any pending messages
+are sent to a dead-letter queue if this is defined in the server configuration. Removes reference
+from queues 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 queue if it has no consumers. If the queue has consumers the server does not
+  delete it but raises a channel exception instead.
+* <tt>:if_empty => true or false (_default_)</tt> - If set to _true_, the server will only
+  delete the queue if it has no messages. If the queue is not empty the server raises a channel
+  exception.
+* <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
@@ -187,14 +387,14 @@ module API
 	      Protocol::Queue::Delete.new({ :queue => name, :nowait => false }.merge(opts))
 	    )
 	
-			raise API::ProtocolError,
+			raise Bunny::ProtocolError,
 				"Error deleting queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::DeleteOk)
 	
 			client.queues.delete(name)
 			
 			# return confirmation
-			QUEUE_DELETED
+			:delete_ok
 	  end
 
 	private

data/lib/bunny/transport/buffer.rb

@@ -0,0 +1,266 @@
+module Bunny
+	module Transport #:nodoc: all
+	  class Buffer
+    
+	    def initialize data = ''
+	      @data = data
+	      @pos = 0
+	    end
+
+	    attr_reader :pos
+    
+	    def data
+	      @data.clone
+	    end
+	    alias :contents :data
+	    alias :to_s :data
+
+	    def << data
+	      @data << data.to_s
+	      self
+	    end
+    
+	    def length
+	      @data.length
+	    end
+    
+	    def empty?
+	      pos == length
+	    end
+    
+	    def rewind
+	      @pos = 0
+	    end
+    
+	    def read_properties *types
+	      types.shift if types.first == :properties
+      
+	      i = 0
+	      values = []
+
+	      while props = read(:short)
+	        (0..14).each do |n|
+	          # no more property types
+	          break unless types[i]
+          
+	          # if flag is set
+	          if props & (1<<(15-n)) != 0
+	            if types[i] == :bit
+	              # bit values exist in flags only
+	              values << true
+	            else
+	              # save type name for later reading
+	              values << types[i]
+	            end
+	          else
+	            # property not set or is false bit
+	            values << (types[i] == :bit ? false : nil)
+	          end
+
+	          i+=1
+	        end
+
+	        # bit(0) == 0 means no more property flags
+	        break unless props & 1 == 1
+	      end
+
+	      values.map do |value|
+	        value.is_a?(Symbol) ? read(value) : value
+	      end
+	    end
+
+	    def read *types
+	      if types.first == :properties
+	        return read_properties(*types)
+	      end
+
+	      values = types.map do |type|
+	        case type
+	        when :octet
+	          _read(1, 'C')
+	        when :short
+	          _read(2, 'n')
+	        when :long
+	          _read(4, 'N')
+	        when :longlong
+	          upper, lower = _read(8, 'NN')
+	          upper << 32 | lower
+	        when :shortstr
+	          _read read(:octet)
+	        when :longstr
+	          _read read(:long)
+	        when :timestamp
+	          Time.at read(:longlong)
+	        when :table
+	          t = Hash.new
+
+	          table = Buffer.new(read(:longstr))
+	          until table.empty?
+	            key, type = table.read(:shortstr, :octet)
+	            key = key.intern
+	            t[key] ||= case type
+	                       when 83 # 'S'
+	                         table.read(:longstr)
+	                       when 73 # 'I'
+	                         table.read(:long)
+	                       when 68 # 'D'
+	                         exp = table.read(:octet)
+	                         num = table.read(:long)
+	                         num / 10.0**exp
+	                       when 84 # 'T'
+	                         table.read(:timestamp)
+	                       when 70 # 'F'
+	                         table.read(:table)
+	                       end
+	          end
+
+	          t
+	        when :bit
+	          if (@bits ||= []).empty?
+	            val = read(:octet)
+	            @bits = (0..7).map{|i| (val & 1<<i) != 0 }
+	          end
+
+	          @bits.shift
+	        else
+	          raise Bunny::InvalidTypeError, "Cannot read data of type #{type}"
+	        end
+	      end
+      
+	      types.size == 1 ? values.first : values
+	    end
+    
+	    def write type, data
+	      case type
+	      when :octet
+	        _write(data, 'C')
+	      when :short
+	        _write(data, 'n')
+	      when :long
+	        _write(data, 'N')
+	      when :longlong
+	        lower =  data & 0xffffffff
+	        upper = (data & ~0xffffffff) >> 32
+	        _write([upper, lower], 'NN')
+	      when :shortstr
+	        data = (data || '').to_s
+	        _write([data.length, data], 'Ca*')
+	      when :longstr
+	        if data.is_a? Hash
+	          write(:table, data)
+	        else
+	          data = (data || '').to_s
+	          _write([data.length, data], 'Na*')
+	        end
+	      when :timestamp
+	        write(:longlong, data.to_i)
+	      when :table
+	        data ||= {}
+	        write :longstr, (data.inject(Buffer.new) do |table, (key, value)|
+	                          table.write(:shortstr, key.to_s)
+
+	                          case value
+	                          when String
+	                            table.write(:octet, 83) # 'S'
+	                            table.write(:longstr, value.to_s)
+	                          when Fixnum
+	                            table.write(:octet, 73) # 'I'
+	                            table.write(:long, value)
+	                          when Float
+	                            table.write(:octet, 68) # 'D'
+	                            # XXX there's gotta be a better way to do this..
+	                            exp = value.to_s.split('.').last.length
+	                            num = value * 10**exp
+	                            table.write(:octet, exp)
+	                            table.write(:long, num)
+	                          when Time
+	                            table.write(:octet, 84) # 'T'
+	                            table.write(:timestamp, value)
+	                          when Hash
+	                            table.write(:octet, 70) # 'F'
+	                            table.write(:table, value)
+	                          end
+
+	                          table
+	                        end)
+	      when :bit
+	        [*data].to_enum(:each_slice, 8).each{|bits|
+	          write(:octet, bits.enum_with_index.inject(0){ |byte, (bit, i)|
+	            byte |= 1<<i if bit
+	            byte
+	           })
+	         }
+	      when :properties
+	        values = []
+	        data.enum_with_index.inject(0) do |short, ((type, value), i)|
+	          n = i % 15
+	          last = i+1 == data.size
+
+	          if (n == 0 and i != 0) or last
+	            if data.size > i+1
+	              short |= 1<<0
+	            elsif last and value
+	              values << [type,value]
+	              short |= 1<<(15-n)
+	            end
+
+	            write(:short, short)
+	            short = 0
+	          end
+
+	          if value and !last
+	            values << [type,value] 
+	            short |= 1<<(15-n)
+	          end
+
+	          short
+	        end
+        
+	        values.each do |type, value|
+	          write(type, value) unless type == :bit
+	        end
+	      else
+	        raise Bunny::InvalidTypeError, "Cannot write data of type #{type}"
+	      end
+      
+	      self
+	    end
+
+	    def extract
+	      begin
+	        cur_data, cur_pos = @data.clone, @pos
+	        yield self
+	      rescue Bunny::BufferOverflowError
+	        @data, @pos = cur_data, cur_pos
+	        nil
+	      end
+	    end
+
+	    def _read(size, pack = nil)
+	      if @data.is_a?(Bunny::Client)
+	        raw = @data.read(size)
+	        return raw if raw.nil? or pack.nil? 
+	        return raw.unpack(pack).first
+	      end
+
+	      if @pos + size > length
+	        raise Bunny::BufferOverflowError
+	      else
+	        data = @data[@pos,size]
+	        @data[@pos,size] = ''
+	        if pack
+	          data = data.unpack(pack)
+	          data = data.pop if data.size == 1
+	        end
+	        data
+	      end
+	    end
+    
+	    def _write data, pack = nil
+	      data = [*data].pack(pack) if pack
+	      @data[@pos,0] = data
+	      @pos += data.length
+	    end
+	  end
+	end
+end