bunny 0.2.0 → 0.3.0

data/lib/bunny/client.rb

@@ -1,4 +1,13 @@
-module API
+module Bunny
+	
+=begin rdoc
+
+=== DESCRIPTION:
+
+The Client class provides the major Bunny API methods.
+
+=end
+
   class Client
     CONNECT_TIMEOUT = 1.0
     RETRY_DELAY     = 10.0
@@ -6,6 +15,29 @@ module API
     attr_reader   :status, :host, :vhost, :port
     attr_accessor :channel, :logging, :exchanges, :queues, :ticket
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Sets up a Bunny::Client object ready for connection to a broker/server. _Client_._status_ is set to
+<tt>:not_connected</tt>.
+
+==== OPTIONS:
+
+* <tt>:host => '_hostname_' (default = 'localhost')</tt>
+* <tt>:port => _portno_ (default = 5672)</tt>
+* <tt>:vhost => '_vhostname_' (default = '/')</tt>
+* <tt>:user => '_username_' (default = 'guest')</tt>
+* <tt>:pass => '_password_' (default = 'guest')</tt>
+* <tt>:logging => true or false (_default_)</tt> - If set to _true_, session information is sent
+  to STDOUT.
+* <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
+  option, if set to _true_, tells the server that the client is insisting on a connection to the
+  specified server.
+
+=end
+
     def initialize(opts = {})
 			@host = opts[:host] || 'localhost'
 			@port = opts[:port] || Protocol::PORT
@@ -14,12 +46,97 @@ module API
       @vhost  = opts[:vhost] || '/'
 			@logging = opts[:logging] || false
       @insist = opts[:insist]
-      @status = NOT_CONNECTED
+      @status = :not_connected
     end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Declares an exchange to the broker/server. If the exchange does not exist, a new one is created
+using the arguments passed in. If the exchange already exists, a reference to it is created, provided
+that the arguments passed in do not conflict with the existing attributes of the exchange. If an error
+occurs a _Bunny_::_ProtocolError_ is raised.
+
+==== OPTIONS:
+
+* <tt>:type => one of :direct (_default_), :fanout, :topic, :headers</tt>
+* <tt>:passive => true or false</tt> - If set to _true_, the server will not create the exchange.
+  The client can use this to check whether an exchange exists without modifying the server state.
+* <tt>:durable => true or false (_default_)</tt> - If set to _true_ when creating a new exchange, the exchange
+  will be marked as durable. Durable exchanges remain active when a server restarts. Non-durable
+  exchanges (transient exchanges) are purged if/when a server restarts.
+* <tt>:auto_delete => true or false (_default_)</tt> - If set to _true_, the exchange is deleted
+  when all queues have finished using it.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== RETURNS:
+
+Exchange
+
+=end
+
+		def exchange(name, opts = {})
+			exchanges[name] ||= Bunny::Exchange.new(self, name, opts)
+		end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns hash of exchanges declared by Bunny.
+
+=end
+
 		def exchanges
 			@exchanges ||= {}
 		end
+
+=begin rdoc
+
+=== DESCRIPTION:
+
+Declares a queue to the broker/server. If the queue does not exist, a new one is created
+using the arguments passed in. If the queue already exists, a reference to it is created, provided
+that the arguments passed in do not conflict with the existing attributes of the queue. If an error
+occurs a _Bunny_::_ProtocolError_ is raised.
+
+==== OPTIONS:
+
+* <tt>:passive => true or false (_default_)</tt> - If set to _true_, the server will not create
+  the queue. The client can use this to check whether a queue exists without modifying the server
+  state.
+* <tt>:durable => true or false (_default_)</tt> - 	If set to _true_ when creating a new queue, the
+  queue will be marked as durable. Durable queues remain active when a server restarts. Non-durable
+  queues (transient queues) are purged if/when a server restarts. Note that durable queues do not
+  necessarily hold persistent messages, although it does not make sense to send persistent messages
+  to a transient queue.
+* <tt>:exclusive => true or false (_default_)</tt> - If set to _true_, requests an exclusive queue.
+  Exclusive queues may only be consumed from by the current connection. Setting the 'exclusive'
+  flag always implies 'auto-delete'.
+* <tt>:auto_delete => true or false (_default_)</tt> - 	If set to _true_, the queue is deleted
+  when all consumers have finished	using it. Last consumer can be cancelled either explicitly
+  or because its channel is closed. If there has never been a consumer on the queue, it is not
+  deleted.
+* <tt>:nowait => true or false (_default_)</tt> - Ignored by Bunny, always _false_.
+
+==== RETURNS:
+
+Queue
+
+=end
+		
+		def queue(name, opts = {})
+	    queues[name] ||= Bunny::Queue.new(self, name, opts)
+	  end
+	
+=begin rdoc
+
+=== DESCRIPTION:
+
+Returns hash of queues declared by Bunny.
+
+=end
 		
 		def queues
 			@queues ||= {}
@@ -49,24 +166,39 @@ module API
 
     def next_payload
       frame = next_frame
-      frame and frame.payload
+      frame.payload
     end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Closes the current communication channel and connection. If an error occurs a
+_Bunny_::_ProtocolError_ is raised. If successful, _Client_._status_ is set to <tt>:not_connected</tt>.
+
+==== RETURNS:
+
+<tt>:not_connected</tt> if successful.
+
+=end
+
     def close
       send_frame(
         Protocol::Channel::Close.new(:reply_code => 200, :reply_text => 'bye', :method_id => 0, :class_id => 0)
       )
-      raise API::ProtocolError, "Error closing channel #{channel}" unless next_method.is_a?(Protocol::Channel::CloseOk)
+      raise Bunny::ProtocolError, "Error closing channel #{channel}" unless next_method.is_a?(Protocol::Channel::CloseOk)
 
       self.channel = 0
       send_frame(
         Protocol::Connection::Close.new(:reply_code => 200, :reply_text => 'Goodbye', :class_id => 0, :method_id => 0)
       )
-      raise API::ProtocolError, "Error closing connection" unless next_method.is_a?(Protocol::Connection::CloseOk)
+      raise Bunny::ProtocolError, "Error closing connection" unless next_method.is_a?(Protocol::Connection::CloseOk)
 
       close_socket
     end
 
+		alias stop close
+
     def read(*args)
       send_command(:read, *args)
     end
@@ -75,11 +207,24 @@ module API
       send_command(:write, *args)
     end
 
+=begin rdoc
+
+=== DESCRIPTION:
+
+Opens a communication channel and starts a connection. If an error occurs, a
+_Bunny_::_ProtocolError_ is raised. If successful, _Client_._status_ is set to <tt>:connected</tt>.
+
+==== RETURNS:
+
+<tt>:connected</tt> if successful.
+
+=end
+		
 		def start_session
       @channel = 0
       write(Protocol::HEADER)
       write([1, 1, Protocol::VERSION_MAJOR, Protocol::VERSION_MINOR].pack('C4'))
-      raise API::ProtocolError, 'Connection initiation failed' unless next_method.is_a?(Protocol::Connection::Start)
+      raise Bunny::ProtocolError, 'Connection initiation failed' unless next_method.is_a?(Protocol::Connection::Start)
 
       send_frame(
         Protocol::Connection::StartOk.new(
@@ -91,7 +236,7 @@ module API
       )
 			
 			method = next_method
-			raise API::ProtocolError, "Connection failed - user: #{@user}, pass: #{@pass}" if method.nil?
+			raise Bunny::ProtocolError, "Connection failed - user: #{@user}, pass: #{@pass}" if method.nil?
 
       if method.is_a?(Protocol::Connection::Tune)
         send_frame(
@@ -102,23 +247,25 @@ module API
       send_frame(
         Protocol::Connection::Open.new(:virtual_host => @vhost, :capabilities => '', :insist => @insist)
       )
-      raise API::ProtocolError, 'Cannot open connection' unless next_method.is_a?(Protocol::Connection::OpenOk)
+      raise Bunny::ProtocolError, 'Cannot open connection' unless next_method.is_a?(Protocol::Connection::OpenOk)
 
       @channel = 1
       send_frame(Protocol::Channel::Open.new)
-      raise API::ProtocolError, "Cannot open channel #{channel}" unless next_method.is_a?(Protocol::Channel::OpenOk)
+      raise Bunny::ProtocolError, "Cannot open channel #{channel}" unless next_method.is_a?(Protocol::Channel::OpenOk)
 
       send_frame(
         Protocol::Access::Request.new(:realm => '/data', :read => true, :write => true, :active => true, :passive => true)
       )
       method = next_method
-      raise API::ProtocolError, 'Access denied' unless method.is_a?(Protocol::Access::RequestOk)
+      raise Bunny::ProtocolError, 'Access denied' unless method.is_a?(Protocol::Access::RequestOk)
       self.ticket = method.ticket
 
 			# return status
 			status
     end
 
+		alias start start_session
+
   private
 
     def buffer
@@ -129,7 +276,7 @@ module API
       begin
         socket.__send__(cmd, *args)
       rescue Errno::EPIPE, IOError => e
-        raise API::ServerDownError, e.message
+        raise Bunny::ServerDownError, e.message
       end
     end
 
@@ -145,9 +292,9 @@ module API
         if Socket.constants.include? 'TCP_NODELAY'
           @socket.setsockopt Socket::IPPROTO_TCP, Socket::TCP_NODELAY, 1
         end
-        @status   = CONNECTED
+        @status   = :connected
       rescue SocketError, SystemCallError, IOError, Timeout::Error => e
-        raise API::ServerDownError, e.message
+        raise Bunny::ServerDownError, e.message
       end
 
       @socket
@@ -157,7 +304,7 @@ module API
       # Close the socket. The server is not considered dead.
       @socket.close if @socket and not @socket.closed?
       @socket   = nil
-      @status   = NOT_CONNECTED
+      @status   = :not_connected
     end
 
     def log(*args)

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