bunny 0.1.0 → 0.1.1

data/README.markdown

@@ -4,30 +4,23 @@ Google Group: [bunny-amqp](http://groups.google.com/group/bunny-amqp)
 
 Mailing List: [bunny-amqp-devel](http://rubyforge.org/mailman/listinfo/bunny-amqp-devel)
 
-Rubyforge: [bunny-amqp](http://bunny-amqp.rubyforge.org)
+Rubyforge: [bunny-amqp](http://rubyforge.org/projects/bunny-amqp)
 
 ## Announcements
 
-**IMPORTANT**
+Bunny v0.1.1 has been released. It contains the following changes -
 
-The Exchange#initialize method arguments have changed as of version 0.0.7
-
-You now create an exchange like this -
-
-    b = Bunny.new
-    exch = b.exchange('my_exchange', :type => :fanout)
-
-If you do not specify a :type option then a default of :direct is used.
-
-The old way was -
-
-    b = Bunny.new
-    exch = b.exchange(:fanout, 'my_exchange')
+*  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
 
 ## About
 
 *Bunny* is an [AMQP](http://www.amqp.org) (Advanced Message Queuing Protocol) client, written in Ruby, that is intended to allow you to interact with AMQP-compliant message brokers/servers such as [RabbitMQ](http://www.rabbitmq.com) in a synchronous fashion.
 
+It is based on a great deal of fabulous code from [amqp](http://github.com/tmm1/amqp) by Aman Gupta and [Carrot](http://github.com/famoseagle/carrot) by Amos Elliston.
+
 You can use *Bunny* to -
 
 * Create and delete exchanges
@@ -43,12 +36,7 @@ You can use *Bunny* to -
     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 a queue
     q = b.queue('test1')
@@ -110,12 +98,15 @@ Queue#message_count
 ### Return queue consumer count
 Queue#consumer_count
 
-### Return queue status (array of message count and consumer_count)
+### Return queue status (hash {:message count, :consumer_count})
 Queue#status
 
 ### Delete a queue from the target server
 Queue#delete({_options_})
 
+### Acknowledge receipt of a message
+Queue#ack
+
 ## Acknowledgements
 
 This project has borrowed heavily from the following two projects and owes their respective creators and collaborators a whole lot of gratitude:

data/examples/fanout.rb

@@ -0,0 +1,44 @@
+# fanout.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(: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
+
+# declare queues
+q1 = b.queue('test_fan1')
+q2 = b.queue('test_fan2')
+
+# create a fanout exchange
+exch = b.exchange('test_fan', :type => :fanout)
+
+# bind the queues to the exchange
+q1.bind(exch)
+q2.bind(exch)
+
+# publish a message to the exchange
+exch.publish('This message will be fanned out')
+
+# get message from the queues
+msg = q1.pop
+puts 'This is the message from q1: ' + msg + "\n\n"
+msg = q2.pop
+puts 'This is the message from q2: ' + msg + "\n\n"
+
+# close the client connection
+b.stop

data/examples/simple.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 a queue
 q = b.queue('test1')

data/examples/simple_ack.rb

@@ -0,0 +1,33 @@
+# simple_ack.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(:logging => true)
+
+# start a communication session with the amqp server
+b.start
+
+# declare a queue
+q = b.queue('test1')
+
+# publish a message to the queue
+q.publish('Testing acknowledgements')
+
+# get message from the queue
+msg = q.pop(:ack => true)
+
+# acknowledge receipt of message
+q.ack
+
+puts 'This is the message: ' + msg + "\n\n"
+
+# close the client connection
+b.stop

data/examples/simple_consumer.rb

@@ -0,0 +1,36 @@
+# consumer.rb
+
+# N.B. To be used in conjunction with publisher.rb - RUN THIS BEFORE 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'.
+
+# 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(: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')
+
+# subscribe to queue
+msg = q.subscribe(:consumer_tag => 'testtag1')
+
+# output received message
+puts msg
+
+# close the connection
+b.stop

data/examples/simple_publisher.rb

@@ -0,0 +1,33 @@
+# simple_publisher.rb
+
+# N.B. To be used in conjunction with simple_consumer.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(: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')
+
+# message should now be picked up by the consumer so we can stop
+b.stop

data/lib/amqp.rb

@@ -3,10 +3,14 @@ module AMQP
     require "amqp/#{file}"
   end
 
-	# constants
+	# return messages
 	CONNECTED = 'CONNECTED'
 	NOT_CONNECTED = 'NOT CONNECTED'
 	QUEUE_EMPTY = 'QUEUE EMPTY'
+	QUEUE_DELETED = 'QUEUE DELETED'
+	EXCHANGE_DELETED = 'EXCHANGE DELETED'
+	BIND_SUCCEEDED = 'BIND SUCCEEDED'
+	UNBIND_SUCCEEDED = 'UNBIND SUCCEEDED'
 
 	# specific error definitions
 	class ProtocolError < StandardError; end

data/lib/bunny/exchange.rb

@@ -65,6 +65,9 @@ class Bunny
 				client.next_method.is_a?(Protocol::Exchange::DeleteOk)
 
 			client.exchanges.delete(name)
+			
+			# return confirmation
+			EXCHANGE_DELETED
 	  end
 
 	end

data/lib/bunny/queue.rb

@@ -24,15 +24,28 @@ class Bunny
 	
 			raise ProtocolError, "Error declaring queue #{name}" unless client.next_method.is_a?(Protocol::Queue::DeclareOk)
 	  end
+	
+		def ack
+      client.send_frame(
+        Protocol::Basic::Ack.new(:delivery_tag => delivery_tag)
+      )
+
+			# reset delivery tag
+			self.delivery_tag = nil
+    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(
 	      Protocol::Basic::Get.new({ :queue => name,
 																	 :consumer_tag => name,
-																	 :no_ack => !opts.delete(:ack),
+																	 :no_ack => !ack,
 																	 :nowait => true }.merge(opts))
 	    )
 	
@@ -44,6 +57,9 @@ class Bunny
 				raise 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 MessageError, 'unexpected length' if msg.length < header.size
@@ -57,20 +73,58 @@ class Bunny
 	  end
 
 	  def message_count
-	    status.first
+	    s = status
+			s[:message_count]
 	  end
 
 	  def consumer_count
-	    status.last
+	    s = status
+			s[:consumer_count]
 	  end
   
-	  def status(opts = {}, &blk)
+	  def status(opts = {})
 	    client.send_frame(
 	      Protocol::Queue::Declare.new({ :queue => name, :passive => true }.merge(opts))
 	    )
 	    method = client.next_method
-	    [method.message_count, method.consumer_count]
+	    {:message_count => method.message_count, :consumer_count => method.consumer_count}
 	  end
+	
+		def subscribe(opts = {})
+			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
+			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(
+				Protocol::Basic::Consume.new({ :queue => name,
+																	 		 :consumer_tag => consumer_tag,
+																	 		 :no_ack => !ack,
+																	 		 :nowait => false }.merge(opts))
+			)
+			
+			raise ProtocolError,
+				"Error subscribing to queue #{name}" unless
+				client.next_method.is_a?(Protocol::Basic::ConsumeOk)
+			
+			method = client.next_method
+			
+			# get delivery tag to use for acknowledge
+			self.delivery_tag = method.delivery_tag if ack
+			
+			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 bind(exchange, opts = {})
 	    exchange           = exchange.respond_to?(:name) ? exchange.name : exchange
@@ -90,6 +144,9 @@ class Bunny
 			raise ProtocolError,
 				"Error binding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::BindOk)
+				
+			# return message
+			BIND_SUCCEEDED
 	  end
 
 	  def unbind(exchange, opts = {})
@@ -107,6 +164,9 @@ class Bunny
 			raise ProtocolError,
 				"Error unbinding queue #{name}" unless
 				client.next_method.is_a?(Protocol::Queue::UnbindOk)
+				
+			# return message
+			UNBIND_SUCCEEDED
 	  end
 
 	  def delete(opts = {})
@@ -123,6 +183,9 @@ class Bunny
 				client.next_method.is_a?(Protocol::Queue::DeleteOk)
 	
 			client.queues.delete(name)
+			
+			# return confirmation
+			QUEUE_DELETED
 	  end
 
 	private

data/spec/exchange_spec.rb

@@ -62,7 +62,8 @@ describe Bunny::Exchange do
 	
 	it "should be able to be deleted" do
 		exch = @b.exchange('direct_exchange')
-		exch.delete
+		res = exch.delete
+		res.should == 'EXCHANGE DELETED'
 		@b.exchanges.has_key?('direct_exchange').should be false
 	end
 	

data/spec/queue_spec.rb

@@ -22,25 +22,25 @@ describe Bunny::Queue do
 	it "should ignore the :nowait option when binding to an exchange" do
 		exch = @b.exchange('direct_exch')
 		q = @b.queue('test0')
-		q.bind(exch, :nowait => true)
+		q.bind(exch, :nowait => true).should == 'BIND SUCCEEDED'
 	end
 	
 	it "should be able to bind to an exchange" do
 		exch = @b.exchange('direct_exch')
 		q = @b.queue('test1')
-		q.bind(exch)
+		q.bind(exch).should == 'BIND SUCCEEDED'
 	end
 	
 	it "should ignore the :nowait option when unbinding from an exchange" do
 		exch = @b.exchange('direct_exch')
 		q = @b.queue('test0')
-		q.unbind(exch, :nowait => true)
+		q.unbind(exch, :nowait => true).should == 'UNBIND SUCCEEDED'
 	end
 	
 	it "should be able to unbind from an exchange" do
 		exch = @b.exchange('direct_exch')
 		q = @b.queue('test1')
-		q.unbind(exch)
+		q.unbind(exch).should == 'UNBIND SUCCEEDED'
 	end
 
 	it "should be able to publish a message" do
@@ -76,7 +76,8 @@ describe Bunny::Queue do
 
 	it "should be able to be deleted" do
 		q = @b.queue('test1')
-		q.delete
+		res = q.delete
+		res.should == 'QUEUE DELETED'
 		@b.queues.has_key?('test1').should be false
 	end
 	

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bunny
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - Chris Duncan
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-04-25 00:00:00 +01:00
+date: 2009-04-27 00:00:00 +01:00
 default_executable: 
 dependencies: []
 
@@ -36,6 +36,10 @@ files:
 - lib/amqp/spec.rb
 - lib/bunny.rb
 - examples/simple.rb
+- examples/fanout.rb
+- examples/simple_consumer.rb
+- examples/simple_publisher.rb
+- examples/simple_ack.rb
 - spec/bunny_spec.rb
 - spec/exchange_spec.rb
 - spec/queue_spec.rb