fotonauts-bunny 0.4.0

data/lib/bunny/exchange.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::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(
+        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/queue.rb

@@ -0,0 +1,410 @@
+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
+	    @name   = name
+			@delivery_tag = nil
+	
+			# 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))
+	    )
+	
+			raise Bunny::ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Qrack::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(
+        Qrack::Protocol::Basic::Ack.new(:delivery_tag => delivery_tag)
+      )
+
+			# 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
+
+	private
+	  def exchange
+	    @exchange ||= Bunny::Exchange.new(client, '', {:type => :direct, :key => name})
+	  end
+
+	  def bindings
+	    @bindings ||= {}
+	  end
+	end
+	
+end

data/lib/bunny.rb

@@ -0,0 +1,37 @@
+$:.unshift File.expand_path(File.dirname(__FILE__))
+
+# Ruby standard libraries
+%w[socket thread timeout].each do |file|
+	require file
+end
+
+require 'qrack/qrack'
+
+require 'bunny/client'
+require 'bunny/exchange'
+require 'bunny/queue'
+
+module Bunny
+	
+	include Qrack
+
+	class ProtocolError < StandardError; end
+	class ServerDownError < StandardError; end
+	class ConnectionError < StandardError; end
+	class MessageError < StandardError; end
+	
+	VERSION = '0.4.0'
+	
+	# Returns the Bunny version number
+
+	def self.version
+		VERSION
+	end
+	
+	# Instantiates new Bunny::Client
+	
+	def self.new(opts = {})
+		Bunny::Client.new(opts)
+	end
+
+end

data/lib/qrack/client.rb

@@ -0,0 +1,5 @@
+module Qrack
+	# Client ancestor class
+	class Client
+	end
+end