bunny 0.1.1 → 0.2.0

data/README.markdown

@@ -1,19 +1,20 @@
 # Bunny: A synchronous Ruby AMQP client
 
-Google Group: [bunny-amqp](http://groups.google.com/group/bunny-amqp)
+Google Group: [http://groups.google.com/group/bunny-amqp](http://groups.google.com/group/bunny-amqp)
 
-Mailing List: [bunny-amqp-devel](http://rubyforge.org/mailman/listinfo/bunny-amqp-devel)
+Mailing List: [http://rubyforge.org/mailman/listinfo/bunny-amqp-devel](http://rubyforge.org/mailman/listinfo/bunny-amqp-devel)
 
-Rubyforge: [bunny-amqp](http://rubyforge.org/projects/bunny-amqp)
+Rubyforge: [http://rubyforge.org/projects/bunny-amqp](http://rubyforge.org/projects/bunny-amqp)
+
+Twitter: [http://twitter.com/bunny_amqp](https://twitter.com/bunny_amqp)
 
 ## Announcements
 
-Bunny v0.1.1 has been released. It contains the following changes -
+Bunny v0.2.0 is now available. The highlights are -
 
-*  Queue#delete method returns ‘QUEUE DELETED’, Exchange#delete method returns ‘EXCHANGE DELETED’, Queue#bind returns ‘BIND SUCCEEDED’, Queue#unbind returns ‘UNBIND SUCCEEDED’
-* Queue#subscribe method available (see example bunny/examples/simple_consumer.rb)
-* Queue#status now returns a hash {:message_count, :consumer_count}
-* Queue#ack works after a Queue#subscribe or Queue#pop if :ack => true was specified
+* Code has been re-organised enabling Bunny to play nicely with [amqp](http://github.com/tmm1/amqp) (thanks [Dan](http://github.com/danielsdeleo))
+* When instantiating a default exchange (one beginning with ‘amq.’) the type will be inferred from the name.
+* Fixed Queue#subscribe and included Queue#unsubscribe method. See examples/simple_consumer.rb for details
 
 ## About
 
@@ -92,6 +93,12 @@ Queue#publish(_**data**_, {_options_})
 ### Pop a message off of a queue
 Queue#pop({_options_})
 
+### Subscribe to a queue
+Queue#subscribe({_options_}, &blk)
+
+### Unsubscribe from a queue
+Queue#unsubscribe({_options_})
+
 ### Return queue message count
 Queue#message_count
 

data/examples/simple_consumer.rb

@@ -1,6 +1,6 @@
 # consumer.rb
 
-# N.B. To be used in conjunction with publisher.rb - RUN THIS BEFORE simple_publisher.rb
+# N.B. To be used in conjunction with simple_publisher.rb
 
 # Assumes that target message broker/server has a user called 'guest' with a password 'guest'
 # and that it is running on 'localhost'.
@@ -8,6 +8,21 @@
 # If this is not the case, please change the 'Bunny.new' call below to include
 # the relevant arguments e.g. b = Bunny.new(:user => 'john', :pass => 'doe', :host => 'foobar')
 
+# How this example works
+#=======================
+#
+# Open up two console windows start this program in one of them by typing -
+#
+# ruby simple_consumer.rb
+#
+# Then switch to the other console window and type -
+#
+# ruby simple_publisher.rb
+#
+# A message will be printed out by the simple_consumer and it will wait for the next message
+#
+# Run simple_publisher 3 more times. After the last run simple_consumer will stop.
+
 $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
@@ -26,11 +41,15 @@ exch = b.exchange('sorting_room')
 # bind queue to exchange
 q.bind(exch, :key => 'fred')
 
-# subscribe to queue
-msg = q.subscribe(:consumer_tag => 'testtag1')
+# initialize counter
+i = 1
 
-# output received message
-puts msg
+# subscribe to queue
+q.subscribe(:consumer_tag => 'testtag1') do |msg|
+	puts i.to_s + ': ' + msg
+	i+=1
+	q.unsubscribe(:consumer_tag => 'testtag1') if i == 5
+end
 
 # close the connection
 b.stop

data/examples/{fanout.rb → simple_fanout.rb}

@@ -13,12 +13,7 @@ require 'bunny'
 b = Bunny.new(:logging => true)
 
 # start a communication session with the amqp server
-begin
-  b.start
-rescue Exception => e
-  puts 'ERROR - Could not start a session: ' + e
-  exit
-end
+b.start
 
 # declare queues
 q1 = b.queue('test_fan1')

data/examples/simple_publisher.rb

@@ -1,6 +1,6 @@
 # simple_publisher.rb
 
-# N.B. To be used in conjunction with simple_consumer.rb
+# N.B. To be used in conjunction with simple_consumer.rb. See simple_consumer.rb for explanation.
 
 # Assumes that target message broker/server has a user called 'guest' with a password 'guest'
 # and that it is running on 'localhost'.
@@ -17,15 +17,9 @@ b = Bunny.new(:logging => true)
 # start a communication session with the amqp server
 b.start
 
-# create/get queue
-q = b.queue('po_box')
-
 # create/get exchange
 exch = b.exchange('sorting_room')
 
-# bind queue to exchange
-q.bind(exch, :key => 'fred')
-
 # publish message to exchange
 exch.publish('This is a message from the publisher', :key => 'fred')
 

data/examples/simple_topic.rb

@@ -0,0 +1,59 @@
+# simple_topic.rb
+
+# Assumes that target message broker/server has a user called 'guest' with a password 'guest'
+# and that it is running on 'localhost'.
+
+# If this is not the case, please change the 'Bunny.new' call below to include
+# the relevant arguments e.g. b = Bunny.new(:user => 'john', :pass => 'doe', :host => 'foobar')
+
+$:.unshift File.dirname(__FILE__) + '/../lib'
+
+require 'bunny'
+
+b = Bunny.new
+
+# start a communication session with the amqp server
+b.start
+
+# declare queues
+soccer = b.queue('topic_soccer')
+cricket = b.queue('topic_cricket')
+rugby = b.queue('topic_rugby')
+allsport = b.queue('topic_allsport')
+
+# create a topic exchange
+sports_results = b.exchange('sports_results', :type => :topic)
+
+# bind the queues to the exchange
+soccer.bind(sports_results, :key => 'soccer.*')
+cricket.bind(sports_results, :key => 'cricket.*')
+rugby.bind(sports_results, :key => 'rugby.*')
+allsport.bind(sports_results, :key => '*.result')
+
+# publish messages to the exchange
+sports_results.publish('Manchester United 1 : Hull City 4', :key => 'soccer.result')
+sports_results.publish('England beat Australia by 5 wickets in first test', :key => 'cricket.result')
+sports_results.publish('British Lions 15 : South Africa 12', :key => 'rugby.result')
+
+# get message from the queues
+
+# soccer queue got the soccer message
+msg = soccer.pop
+puts 'This is a message from the soccer q: ' + msg + "\n\n"
+
+# cricket queue got the cricket message
+msg = cricket.pop
+puts 'This is a message from the cricket q: ' + msg + "\n\n"
+
+# rugby queue got the rugby message
+msg = rugby.pop
+puts 'This is a message from the rugby q: ' + msg + "\n\n"
+
+# allsport queue got all of the messages
+until msg == 'QUEUE EMPTY' do
+	msg = allsport.pop
+	puts 'This is a message from the allsport q: ' + msg + "\n\n" unless msg == 'QUEUE EMPTY'
+end
+
+# close the client connection
+b.stop

data/lib/{amqp.rb → api_messages.rb}

@@ -1,8 +1,4 @@
-module AMQP
-	%w[ spec buffer protocol frame client ].each do |file|
-    require "amqp/#{file}"
-  end
-
+module API
 	# return messages
 	CONNECTED = 'CONNECTED'
 	NOT_CONNECTED = 'NOT CONNECTED'

data/lib/bunny.rb

@@ -1,19 +1,32 @@
 $:.unshift File.expand_path(File.dirname(__FILE__))
 
-%w[socket thread timeout amqp].each do |file|
+# Ruby standard libraries
+%w[socket thread timeout].each do |file|
 	require file
 end
 
-%w[ exchange queue header ].each do |file|
-  require "bunny/#{file}"
+# AMQP protocol and transport
+%w[spec protocol buffer frame].each do |file|
+	require 'engineroom/' + file
 end
 
+# Bunny API 
+%w[client exchange header queue].each do |file|
+	require 'bunny/' + file
+end
+
+# Error and return message definitions
+require 'api_messages'
+
 class Bunny
-	
+	include Protocol
+	include Transport
+	include API
+
 	attr_reader :client
 
 	def initialize(opts = {})
-		@client = AMQP::Client.new(opts)
+		@client = API::Client.new(opts)
   end
 
 	def logging=(bool)
@@ -33,11 +46,11 @@ class Bunny
 	end
 	
 	def exchange(name, opts = {})
-		client.exchanges[name] ||= Exchange.new(client, name, opts)
+		client.exchanges[name] ||= API::Exchange.new(client, name, opts)
 	end
   
   def queue(name, opts = {})
-    client.queues[name] ||= Queue.new(client, name, opts)
+    client.queues[name] ||= API::Queue.new(client, name, opts)
   end
 
   def stop
@@ -63,5 +76,5 @@ class Bunny
 	def port
 		client.port
 	end
-
+	
 end

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

@@ -1,4 +1,4 @@
-module AMQP
+module API
   class Client
     CONNECT_TIMEOUT = 1.0
     RETRY_DELAY     = 10.0
@@ -8,7 +8,7 @@ module AMQP
 
     def initialize(opts = {})
 			@host = opts[:host] || 'localhost'
-			@port = opts[:port] || AMQP::PORT
+			@port = opts[:port] || Protocol::PORT
       @user   = opts[:user]  || 'guest'
       @pass   = opts[:pass]  || 'guest'
       @vhost  = opts[:vhost] || '/'
@@ -28,7 +28,7 @@ module AMQP
     def send_frame(*args)
       args.each do |data|
         data.ticket  = ticket if ticket and data.respond_to?(:ticket=)
-        data         = data.to_frame(channel) unless data.is_a?(Frame)
+        data         = data.to_frame(channel) unless data.is_a?(Transport::Frame)
         data.channel = channel
 
         log :send, data
@@ -38,7 +38,7 @@ module AMQP
     end
 
     def next_frame
-      frame = Frame.parse(buffer)
+      frame = Transport::Frame.parse(buffer)
       log :received, frame
       frame
     end
@@ -56,13 +56,13 @@ module AMQP
       send_frame(
         Protocol::Channel::Close.new(:reply_code => 200, :reply_text => 'bye', :method_id => 0, :class_id => 0)
       )
-      raise ProtocolError, "Error closing channel #{channel}" unless next_method.is_a?(Protocol::Channel::CloseOk)
+      raise API::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 ProtocolError, "Error closing connection" unless next_method.is_a?(Protocol::Connection::CloseOk)
+      raise API::ProtocolError, "Error closing connection" unless next_method.is_a?(Protocol::Connection::CloseOk)
 
       close_socket
     end
@@ -77,9 +77,9 @@ module AMQP
 
 		def start_session
       @channel = 0
-      write(HEADER)
-      write([1, 1, VERSION_MAJOR, VERSION_MINOR].pack('C4'))
-      raise ProtocolError, 'Connection initiation failed' unless next_method.is_a?(Protocol::Connection::Start)
+      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)
 
       send_frame(
         Protocol::Connection::StartOk.new(
@@ -91,7 +91,7 @@ module AMQP
       )
 			
 			method = next_method
-			raise ProtocolError, "Connection failed - user: #{@user}, pass: #{@pass}" if method.nil?
+			raise API::ProtocolError, "Connection failed - user: #{@user}, pass: #{@pass}" if method.nil?
 
       if method.is_a?(Protocol::Connection::Tune)
         send_frame(
@@ -102,17 +102,17 @@ module AMQP
       send_frame(
         Protocol::Connection::Open.new(:virtual_host => @vhost, :capabilities => '', :insist => @insist)
       )
-      raise ProtocolError, 'Cannot open connection' unless next_method.is_a?(Protocol::Connection::OpenOk)
+      raise API::ProtocolError, 'Cannot open connection' unless next_method.is_a?(Protocol::Connection::OpenOk)
 
       @channel = 1
       send_frame(Protocol::Channel::Open.new)
-      raise ProtocolError, "Cannot open channel #{channel}" unless next_method.is_a?(Protocol::Channel::OpenOk)
+      raise API::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 ProtocolError, 'Access denied' unless method.is_a?(Protocol::Access::RequestOk)
+      raise API::ProtocolError, 'Access denied' unless method.is_a?(Protocol::Access::RequestOk)
       self.ticket = method.ticket
 
 			# return status
@@ -122,14 +122,14 @@ module AMQP
   private
 
     def buffer
-      @buffer ||= Buffer.new(self)
+      @buffer ||= Transport::Buffer.new(self)
     end
 
     def send_command(cmd, *args)
       begin
         socket.__send__(cmd, *args)
       rescue Errno::EPIPE, IOError => e
-        raise ServerDownError, e.message
+        raise API::ServerDownError, e.message
       end
     end
 
@@ -147,7 +147,7 @@ module AMQP
         end
         @status   = CONNECTED
       rescue SocketError, SystemCallError, IOError, Timeout::Error => e
-        raise ServerDownError, e.message
+        raise API::ServerDownError, e.message
       end
 
       @socket

data/lib/bunny/exchange.rb

@@ -1,16 +1,24 @@
-class Bunny
+module API
 	class Exchange
 	
-		include AMQP
-	
 	  attr_reader :client, :type, :name, :opts, :key
 
 	  def initialize(client, name, opts = {})
 			# check connection to server
-			raise ConnectionError, 'Not connected to server' if client.status == NOT_CONNECTED
+			raise API::ConnectionError, 'Not connected to server' if client.status == NOT_CONNECTED
 		
 	    @client, @name, @opts = client, name, opts
-			@type = opts[:type] || :direct
+	
+			# 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
 			
@@ -25,7 +33,7 @@ class Bunny
 	        )
 	      )
 
-				raise ProtocolError,
+				raise API::ProtocolError,
 					"Error declaring exchange #{name}: type = #{type}" unless
 					client.next_method.is_a?(Protocol::Exchange::DeclareOk)
 	    end
@@ -46,7 +54,7 @@ class Bunny
 	        :priority      => 0 
 	      }.merge(opts)
 	    )
-	    out << Frame::Body.new(data)
+	    out << Transport::Frame::Body.new(data)
 
 	    client.send_frame(*out)
 	  end
@@ -60,7 +68,7 @@ class Bunny
 	      Protocol::Exchange::Delete.new({ :exchange => name, :nowait => false }.merge(opts))
 	    )
 
-			raise ProtocolError,
+			raise API::ProtocolError,
 				"Error deleting exchange #{name}" unless
 				client.next_method.is_a?(Protocol::Exchange::DeleteOk)
 

data/lib/bunny/header.rb

@@ -1,8 +1,6 @@
-class Bunny
+module API
 	class Header
 	
-		include AMQP
-	
 		attr_reader :client
 	
 	  def initialize(client, header_obj)

data/lib/bunny/queue.rb

@@ -1,18 +1,17 @@
-class Bunny
+module API
 	class Queue
 		
-		include AMQP
-		
 	  attr_reader :name, :client
 	  attr_accessor :delivery_tag
 
 	  def initialize(client, name, opts = {})
 			# check connection to server
-			raise ConnectionError, 'Not connected to server' if client.status == NOT_CONNECTED
+			raise API::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
@@ -22,7 +21,7 @@ class Bunny
 	      Protocol::Queue::Declare.new({ :queue => name, :nowait => false }.merge(opts))
 	    )
 	
-			raise ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Protocol::Queue::DeclareOk)
+			raise API::ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Protocol::Queue::DeclareOk)
 	  end
 	
 		def ack
@@ -54,7 +53,7 @@ class Bunny
 			if method.is_a?(Protocol::Basic::GetEmpty) then
 				return QUEUE_EMPTY
 			elsif	!method.is_a?(Protocol::Basic::GetOk)
-				raise ProtocolError, "Error getting message from queue #{name}"
+				raise API::ProtocolError, "Error getting message from queue #{name}"
 			end
 			
 			# get delivery tag to use for acknowledge
@@ -62,7 +61,7 @@ class Bunny
 			
 	    header = client.next_payload
 	    msg    = client.next_payload
-	    raise MessageError, 'unexpected length' if msg.length < header.size
+	    raise API::MessageError, 'unexpected length' if msg.length < header.size
 
 			hdr ? {:header => header, :payload => msg} : msg
 			
@@ -90,7 +89,7 @@ class Bunny
 	    {:message_count => method.message_count, :consumer_count => method.consumer_count}
 	  end
 	
-		def subscribe(opts = {})
+		def subscribe(opts = {}, &blk)
 			consumer_tag = opts[:consumer_tag] || name
 			
 			# ignore the :nowait option if passed, otherwise program will not wait for a
@@ -110,21 +109,31 @@ class Bunny
 																	 		 :nowait => false }.merge(opts))
 			)
 			
-			raise ProtocolError,
+			raise API::ProtocolError,
 				"Error subscribing to queue #{name}" unless
 				client.next_method.is_a?(Protocol::Basic::ConsumeOk)
 			
-			method = client.next_method
+			while true
+				method = client.next_method
+				break if method.is_a?(Protocol::Basic::CancelOk)
 			
-			# get delivery tag to use for acknowledge
-			self.delivery_tag = method.delivery_tag if ack
+				# get delivery tag to use for acknowledge
+				self.delivery_tag = method.delivery_tag if ack
+			
+				header = client.next_payload
+		    msg    = client.next_payload
+		    raise API::MessageError, 'unexpected length' if msg.length < header.size
+				
+				# pass the message to the block for processing
+				blk.call(hdr ? {:header => header, :payload => msg} : msg)
+			end
 			
-			header = client.next_payload
-	    msg    = client.next_payload
-	    raise MessageError, 'unexpected length' if msg.length < header.size
-
-			hdr ? {:header => header, :payload => msg} : msg
 		end
+		
+		def unsubscribe(opts = {})
+			consumer_tag = opts[:consumer_tag] || name
+      client.send_frame( Protocol::Basic::Cancel.new({ :consumer_tag => consumer_tag }.merge(opts)))
+    end
 
 	  def bind(exchange, opts = {})
 	    exchange           = exchange.respond_to?(:name) ? exchange.name : exchange
@@ -141,7 +150,7 @@ class Bunny
 		 																:nowait => false }.merge(opts))
 	    )
 	
-			raise ProtocolError,
+			raise API::ProtocolError,
 				"Error binding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::BindOk)
 				
@@ -161,7 +170,7 @@ class Bunny
 	      )
 	    )
 	
-			raise ProtocolError,
+			raise API::ProtocolError,
 				"Error unbinding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::UnbindOk)
 				
@@ -178,7 +187,7 @@ class Bunny
 	      Protocol::Queue::Delete.new({ :queue => name, :nowait => false }.merge(opts))
 	    )
 	
-			raise ProtocolError,
+			raise API::ProtocolError,
 				"Error deleting queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::DeleteOk)