bunny 0.4.3 → 0.4.4

data/lib/bunny/{client.rb → client091.rb}

@@ -12,8 +12,8 @@ The Client class provides the major Bunny API methods.
     CONNECT_TIMEOUT = 1.0
     RETRY_DELAY     = 10.0
 
-    attr_reader   :status, :host, :vhost, :port
-    attr_accessor :channel, :logging, :exchanges, :queues, :ticket
+    attr_reader   :status, :host, :vhost, :port, :logging, :spec
+    attr_accessor :channel, :logfile, :exchanges, :queues, :ticket
 
 =begin rdoc
 
@@ -29,24 +29,30 @@ Sets up a Bunny::Client object ready for connection to a broker/server. _Client_
 * <tt>:vhost => '_vhostname_' (default = '/')</tt>
 * <tt>:user => '_username_' (default = 'guest')</tt>
 * <tt>:pass => '_password_' (default = 'guest')</tt>
+* <tt>:logfile => '_logfilepath_' (default = nil)</tt>
 * <tt>:logging => true or false (_default_)</tt> - If set to _true_, session information is sent
-  to STDOUT.
+  to STDOUT if <tt>:logfile</tt> has not been specified. Otherwise, session information is written to
+  <tt>:logfile</tt>.
 * <tt>:insist => true or false (_default_)</tt> - In a configuration with multiple load-sharing
-  servers, the server may respond to a Connection.Open method with a Connection.Redirect. The insist
+  servers, the server may respond to a Connection::Open method with a Connection::Redirect. The insist
   option, if set to _true_, tells the server that the client is insisting on a connection to the
   specified server.
 
 =end
 
     def initialize(opts = {})
+			@spec = opts[:spec] || '0-8'
 			@host = opts[:host] || 'localhost'
 			@port = opts[:port] || Qrack::Protocol::PORT
       @user   = opts[:user]  || 'guest'
       @pass   = opts[:pass]  || 'guest'
       @vhost  = opts[:vhost] || '/'
+			@logfile = opts[:logfile] || nil
 			@logging = opts[:logging] || false
       @insist = opts[:insist]
       @status = :not_connected
+			@logger = nil
+			create_logger if @logging
     end
 
 =begin rdoc
@@ -156,7 +162,7 @@ Returns hash of queues declared by Bunny.
         data         = data.to_frame(channel) unless data.is_a?(Qrack::Transport::Frame)
         data.channel = channel
 
-        log :send, data
+        @logger.info("send") { data } if @logging
         write(data.to_s)
       end
       nil
@@ -164,7 +170,7 @@ Returns hash of queues declared by Bunny.
 
     def next_frame
       frame = Qrack::Transport::Frame.parse(buffer)
-      log :received, frame
+			@logger.info("received") { frame } if @logging
       frame
     end
 
@@ -235,7 +241,7 @@ _Bunny_::_ProtocolError_ is raised. If successful, _Client_._status_ is set to <
 				
         @channel = 0
         write(Qrack::Protocol::HEADER)
-        write([1, 1, Qrack::Protocol::VERSION_MAJOR, Qrack::Protocol::VERSION_MINOR].pack('C4'))
+        write([1, 1, Qrack::Protocol::VERSION_MINOR, Qrack::Protocol::VERSION_MAJOR].pack('C4'))
         raise Bunny::ProtocolError, 'Connection initiation failed' unless next_method.is_a?(Qrack::Protocol::Connection::Start)
 
         send_frame(
@@ -312,6 +318,11 @@ the message, potentially then delivering it to an alternative subscriber.
 	    )
 
 	  end
+	
+		def logging=(bool)
+			@logging = bool
+			create_logger if @logging
+		end
 
   private
 
@@ -358,11 +369,10 @@ the message, potentially then delivering it to an alternative subscriber.
       @status   = :not_connected
     end
 
-    def log(*args)
-      return unless logging
-      require 'pp'
-      pp args
-	    puts
+    def create_logger
+			@logfile ? @logger = Logger.new("#{logfile}") : @logger = Logger.new(STDOUT)
+			@logger.level = Logger::INFO
+			@logger.datetime_format = "%Y-%m-%d %H:%M:%S"
     end
 
   end

data/lib/bunny/exchange091.rb

@@ -0,0 +1,158 @@
+module Bunny
+  
+=begin rdoc
+
+=== 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(
+          Qrack::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?(Qrack::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 << Qrack::Protocol::Basic::Publish.new(
+        { :exchange => name, :routing_key => opts.delete(:key) || key }.merge(opts)
+      )
+      data = data.to_s
+      out << Qrack::Protocol::Header.new(
+        Qrack::Protocol::Basic,
+        data.length, {
+          :content_type  => 'application/octet-stream',
+          :delivery_mode => (opts.delete(:persistent) ? 2 : 1),
+          :priority      => 0 
+        }.merge(opts)
+      )
+      out << Qrack::Transport::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(
+        Qrack::Protocol::Exchange::Delete.new({ :exchange => name, :nowait => false }.merge(opts))
+      )
+
+      raise Bunny::ProtocolError,
+        "Error deleting exchange #{name}" unless
+        client.next_method.is_a?(Qrack::Protocol::Exchange::DeleteOk)
+
+      client.exchanges.delete(name)
+      
+      # return confirmation
+      :delete_ok
+    end
+
+  end
+  
+end

data/lib/bunny/queue091.rb

@@ -0,0 +1,458 @@
+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 Bunny::ConnectionError, 'Not connected to server' if client.status == :not_connected
+			
+	    @client = client
+	    @opts   = opts
+      @delivery_tag = nil
+
+      # Queues without a given name are named by the server and are generally
+      # bound to the process that created them.
+      if !name
+        opts = {
+          :passive => false,
+          :durable => false,
+          :exclusive => true,
+          :auto_delete => true
+        }.merge(opts)
+      end
+	
+			# 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(
+	      Qrack::Protocol::Queue::Declare.new({ :queue => name || '', :nowait => false }.merge(opts))
+	    )
+	
+      method = client.next_method
+			raise Bunny::ProtocolError, "Error declaring queue #{name}" unless method.is_a?(Qrack::Protocol::Queue::DeclareOk)
+
+      @name = method.queue
+	  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(opts={})
+			# If delivery tag is nil then set it to 1 to prevent errors
+			self.delivery_tag = 1 if self.delivery_tag.nil?
+			
+      client.send_frame(
+        Qrack::Protocol::Basic::Ack.new({:delivery_tag => delivery_tag, :multiple => false}.merge(opts))
+      )
+
+			# reset delivery tag
+			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?
+			hdr = opts.delete(:header)
+			
+			# do we want to have to provide an acknowledgement?
+			ack = opts.delete(:ack)
+			
+	    client.send_frame(
+	      Qrack::Protocol::Basic::Get.new({ :queue => name,
+																	 :consumer_tag => name,
+																	 :no_ack => !ack,
+																	 :nowait => true }.merge(opts))
+	    )
+	
+			method = client.next_method
+			
+			if method.is_a?(Qrack::Protocol::Basic::GetEmpty) then
+				return :queue_empty
+			elsif	!method.is_a?(Qrack::Protocol::Basic::GetOk)
+				raise Bunny::ProtocolError, "Error getting message from queue #{name}"
+			end
+			
+			# get delivery tag to use for acknowledge
+			self.delivery_tag = method.delivery_tag if ack
+			
+	    header = client.next_payload
+	    msg    = client.next_payload
+	    raise Bunny::MessageError, 'unexpected length' if msg.length < header.size
+
+			# 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
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns hash {:message_count, :consumer_count}.
+
+=end
+ 
+	  def status
+	    client.send_frame(
+	      Qrack::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 hang waiting for a
+			# response from the server causing an error.
+			opts.delete(:nowait)
+			
+			# do we want the message header?
+			hdr = opts.delete(:header)
+			
+			# do we want to have to provide an acknowledgement?
+			ack = opts.delete(:ack)
+			
+			client.send_frame(
+				Qrack::Protocol::Basic::Consume.new({ :queue => name,
+																	 		 :consumer_tag => consumer_tag,
+																	 		 :no_ack => !ack,
+																	 		 :nowait => false }.merge(opts))
+			)
+			
+			raise Bunny::ProtocolError,
+				"Error subscribing to queue #{name}" unless
+				client.next_method.is_a?(Qrack::Protocol::Basic::ConsumeOk)
+			
+			while true
+				method = client.next_method
+
+				break if method.is_a?(Qrack::Protocol::Basic::CancelOk)
+			
+				# get delivery tag to use for acknowledge
+				self.delivery_tag = method.delivery_tag if ack
+			
+				header = client.next_payload
+		    msg    = client.next_payload
+		    raise Bunny::MessageError, 'unexpected length' if msg.length < header.size
+				
+				# 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( Qrack::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
+	
+			# 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[exchange] = opts
+	    client.send_frame(
+	      Qrack::Protocol::Queue::Bind.new({ :queue => name,
+		 																:exchange => exchange,
+		 																:routing_key => opts.delete(:key),
+		 																:nowait => false }.merge(opts))
+	    )
+	
+			raise Bunny::ProtocolError,
+				"Error binding queue #{name}" unless
+				client.next_method.is_a?(Qrack::Protocol::Queue::BindOk)
+				
+			# return message
+			: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(
+	      Qrack::Protocol::Queue::Unbind.new({ :queue => name,
+		 																	:exchange => exchange,
+		 																	:routing_key => opts.delete(:key),
+		 																	:nowait => false }.merge(opts)
+	      )
+	    )
+	
+			raise Bunny::ProtocolError,
+				"Error unbinding queue #{name}" unless
+				client.next_method.is_a?(Qrack::Protocol::Queue::UnbindOk)
+				
+			# return message
+			: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
+			# response that will not be sent by the server
+			opts.delete(:nowait)
+			
+	    client.send_frame(
+	      Qrack::Protocol::Queue::Delete.new({ :queue => name, :nowait => false }.merge(opts))
+	    )
+	
+			raise Bunny::ProtocolError,
+				"Error deleting queue #{name}" unless
+				client.next_method.is_a?(Qrack::Protocol::Queue::DeleteOk)
+	
+			client.queues.delete(name)
+			
+			# return confirmation
+			:delete_ok
+	  end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Removes all messages from a queue.  It does not cancel consumers.  Purged messages are deleted
+without any formal "undo" mechanism. If an error occurs raises _Bunny_::_ProtocolError_.
+
+==== Options:
+
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== Returns:
+
+<tt>:purge_ok</tt> if successful
+=end
+	
+	def purge(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(
+      Qrack::Protocol::Queue::Purge.new({ :queue => name, :nowait => false }.merge(opts))
+    )
+
+		raise Bunny::ProtocolError, "Error purging queue #{name}" unless client.next_method.is_a?(Qrack::Protocol::Queue::PurgeOk)
+		
+		# return confirmation
+		:purge_ok
+		
+  end
+
+	private
+	  def exchange
+	    @exchange ||= Bunny::Exchange.new(client, '', {:type => :direct, :key => name})
+	  end
+
+	  def bindings
+	    @bindings ||= {}
+	  end
+	end
+	
+end