celldee-bunny 0.2.0 → 0.3.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Chris Duncan
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README

@@ -0,0 +1,49 @@
+= Bunny: A synchronous Ruby AMQP client
+
+*GitHub* *repo*: http://github.com/celldee/bunny
+     
+=== DESCRIPTION:
+
+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 useful 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
+* Create and delete queues
+* Publish and consume messages
+
+Bunny is known to work with RabbitMQ version 1.5.4 and version 0-8 of the AMQP specification.
+
+=== INSTALL:
+
+*Rubyforge*: <tt>gem install bunny</tt>
+
+*GitHub*: <tt>gem install celldee-bunny</tt>
+
+=== QUICK START:
+
+   require 'bunny'
+
+   b = Bunny::Client.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('Hello everybody!')
+
+   # get message from the queue
+   msg = q.pop
+
+   puts 'This is the message: ' + msg + "\n\n"
+
+   # close the connection
+   b.stop
+
+=== OTHER:
+Please see the _examples_ directory for additional usage information.

data/Rakefile

@@ -1,6 +1,6 @@
 task :codegen do
-  sh 'ruby protocol/codegen.rb > lib/amqp/spec.rb'
-	sh 'ruby lib/amqp/spec.rb'
+  sh 'ruby ext/codegen.rb > lib/bunny/protocol/spec.rb'
+	sh 'ruby lib/bunny/protocol/spec.rb'
 end
 
 task :spec do
@@ -8,5 +8,4 @@ task :spec do
 	Spec::Rake::SpecTask.new do |t|
 		t.spec_opts = ['--color']
 	end
-end
-	
+end

data/bunny.gemspec

@@ -0,0 +1,37 @@
+Gem::Specification.new do |s|
+  s.name = %q{bunny}
+  s.version = "0.3.0"
+  s.authors = ["Chris Duncan"]
+  s.date = %q{2009-05-10}
+  s.description = %q{Another synchronous Ruby AMQP client}
+  s.email = %q{celldee@gmail.com}
+  s.rubyforge_project = %q{bunny-amqp}
+  s.has_rdoc = true
+ 	s.extra_rdoc_files = [ "README" ]
+  s.rdoc_options = [ "--main", "README" ]
+  s.homepage = %q{http://github.com/celldee/bunny}
+  s.summary = %q{A synchronous Ruby AMQP client that enables interaction with AMQP-compliant brokers/servers.}
+  s.files = ["LICENSE",
+ "README",
+ "Rakefile",
+ "bunny.gemspec",
+ "examples/simple.rb",
+ "examples/simple_ack.rb",
+ "examples/simple_consumer.rb",
+ "examples/simple_fanout.rb",
+ "examples/simple_publisher.rb",
+ "examples/simple_topic.rb",
+ "ext/amqp-0.8.json",
+ "ext/codegen.rb",
+ "lib/bunny.rb",
+ "lib/bunny/client.rb",
+ "lib/bunny/exchange.rb",
+ "lib/bunny/protocol/protocol.rb",
+ "lib/bunny/protocol/spec.rb",
+ "lib/bunny/queue.rb",
+ "lib/bunny/transport/buffer.rb",
+ "lib/bunny/transport/frame.rb",
+ "spec/bunny_spec.rb",
+ "spec/exchange_spec.rb",
+ "spec/queue_spec.rb"]
+end

data/examples/simple.rb

@@ -10,7 +10,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new(:logging => true)
+b = Bunny::Client.new(:logging => true)
 
 # start a communication session with the amqp server
 b.start

data/examples/simple_ack.rb

@@ -10,7 +10,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new(:logging => true)
+b = Bunny::Client.new(:logging => true)
 
 # start a communication session with the amqp server
 b.start

data/examples/simple_consumer.rb

@@ -27,7 +27,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new(:logging => true)
+b = Bunny::Client.new(:logging => true)
 
 # start a communication session with the amqp server
 b.start

data/examples/simple_fanout.rb

@@ -10,7 +10,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new(:logging => true)
+b = Bunny::Client.new(:logging => true)
 
 # start a communication session with the amqp server
 b.start

data/examples/simple_publisher.rb

@@ -12,7 +12,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new(:logging => true)
+b = Bunny::Client.new(:logging => true)
 
 # start a communication session with the amqp server
 b.start

data/examples/simple_topic.rb

@@ -10,7 +10,7 @@ $:.unshift File.dirname(__FILE__) + '/../lib'
 
 require 'bunny'
 
-b = Bunny.new
+b = Bunny::Client.new
 
 # start a communication session with the amqp server
 b.start
@@ -50,9 +50,9 @@ 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
+until msg == :queue_empty do
 	msg = allsport.pop
-	puts 'This is a message from the allsport q: ' + msg + "\n\n" unless msg == 'QUEUE EMPTY'
+	puts 'This is a message from the allsport q: ' + msg + "\n\n" unless msg == :queue_empty
 end
 
 # close the client connection

data/ext/codegen.rb

@@ -0,0 +1,177 @@
+require 'rubygems'
+require 'json'
+
+name = 'amqp-0.8.json'
+path = File.dirname(__FILE__)+'/'+name
+s = JSON.parse(File.read(path))
+
+# require 'pp'
+# pp(s)
+# exit
+
+require 'erb'
+
+puts ERB.new(%q[
+  #:stopdoc:
+  # this file was autogenerated on <%= Time.now.to_s %>
+  # using <%= name.ljust(16) %> (mtime: <%= File.mtime(path) %>)
+  #
+  # DO NOT EDIT! (edit ext/codegen.rb instead, and run `rake codegen`)
+
+  module Bunny
+    module Transport
+      class Frame
+        def self.types
+          @types ||= {}
+        end
+
+        def self.Frame id
+          (@_base_frames ||= {})[id] ||= Class.new(Frame) do
+            class_eval %[
+              def self.inherited klass
+                klass.const_set(:ID, #{id})
+                Frame.types[#{id}] = klass
+              end
+            ]
+          end
+        end
+
+        <%- s['constants'].select{|c| (1..8).include? c['value'] }.each do |c| -%>
+        class <%= c['name'].gsub(/^FRAME-/,'').split('-').map{|w| w.downcase.capitalize}.join.ljust(9) -%> < Frame( <%= c['value'] -%> ); end
+        <%- end -%>
+
+        FOOTER = <%= frame_end = s['constants'].find{|c| c['name'] == 'FRAME-END' }['value'] %>
+      end
+    end
+  end
+  
+  module Bunny
+    module Protocol
+      HEADER        = <%= s['name'].dump %>.freeze
+      VERSION_MAJOR = <%= s['major-version'] %>
+      VERSION_MINOR = <%= s['minor-version'] %>
+      PORT          = <%= s['port'] %>
+
+      RESPONSES = {
+        <%- s['constants'].select{|c| c['value'] != frame_end and (200..500).include? c['value'] }.each do |c| -%>
+        <%= c['value'] %> => :<%= c['name'].tr('-', '_').gsub(/^FRAME_/,'').upcase -%>,
+        <%- end -%>
+      }
+
+      FIELDS = [
+        <%- s['domains'].select{|d| d.first == d.last }.each do |d| -%>
+        :<%= d.first -%>,
+        <%- end -%>
+      ]
+
+      class Class
+        class << self
+          FIELDS.each do |f|
+            class_eval %[
+              def #{f} name
+                properties << [ :#{f}, name ] unless properties.include?([:#{f}, name])
+                attr_accessor name
+              end
+            ]
+          end
+        
+          def properties() @properties ||= [] end
+
+          def id()   self::ID end
+          def name() self::NAME end
+        end
+
+        class Method
+          class << self
+            FIELDS.each do |f|
+              class_eval %[
+                def #{f} name
+                  arguments << [ :#{f}, name ] unless arguments.include?([:#{f}, name])
+                  attr_accessor name
+                end
+              ]
+            end
+          
+            def arguments() @arguments ||= [] end
+
+            def parent() Protocol.const_get(self.to_s[/Protocol::(.+?)::/,1]) end
+            def id()     self::ID end
+            def name()   self::NAME end
+          end
+
+          def == b
+            self.class.arguments.inject(true) do |eql, (type, name)|
+              eql and __send__("#{name}") == b.__send__("#{name}")
+            end
+          end
+        end
+    
+        def self.methods() @methods ||= {} end
+    
+        def self.Method(id, name)
+          @_base_methods ||= {}
+          @_base_methods[id] ||= ::Class.new(Method) do
+            class_eval %[
+              def self.inherited klass
+                klass.const_set(:ID, #{id})
+                klass.const_set(:NAME, :#{name.to_s})
+                klass.parent.methods[#{id}] = klass
+                klass.parent.methods[klass::NAME] = klass
+              end
+            ]
+          end
+        end
+      end
+
+      def self.classes() @classes ||= {} end
+
+      def self.Class(id, name)
+        @_base_classes ||= {}
+        @_base_classes[id] ||= ::Class.new(Class) do
+          class_eval %[
+            def self.inherited klass
+              klass.const_set(:ID, #{id})
+              klass.const_set(:NAME, :#{name.to_s})
+              Protocol.classes[#{id}] = klass
+              Protocol.classes[klass::NAME] = klass
+            end
+          ]
+        end
+      end
+    end
+  end
+  
+  module Bunny
+    module Protocol
+      <%- s['classes'].each do |c| -%>
+      class <%= c['name'].capitalize.ljust(12) %> < Class( <%= c['id'].to_s.rjust(3) %>, :<%= c['name'].ljust(12) %> ); end
+      <%- end -%>
+
+      <%- s['classes'].each do |c| -%>
+      class <%= c['name'].capitalize %>
+        <%- c['properties'].each do |p| -%>
+        <%= p['type'].ljust(10) %> :<%= p['name'].tr('-','_') %>
+        <%- end if c['properties'] -%>
+
+        <%- c['methods'].each do |m| -%>
+        class <%= m['name'].capitalize.gsub(/-(.)/){ "#{$1.upcase}"}.ljust(12) %> < Method( <%= m['id'].to_s.rjust(3) %>, :<%= m['name'].tr('- ','_').ljust(14) %> ); end
+        <%- end -%>
+
+        <%- c['methods'].each do |m| -%>
+        class <%= m['name'].capitalize.gsub(/-(.)/){ "#{$1.upcase}"} %>
+          <%- m['arguments'].each do |a| -%>
+          <%- if a['domain'] -%>
+          <%= s['domains'].find{|k,v| k == a['domain']}.last.ljust(10) %> :<%= a['name'].tr('- ','_') %>
+          <%- else -%>
+          <%= a['type'].ljust(10) %> :<%= a['name'].tr('- ','_') %>
+          <%- end -%>
+          <%- end if m['arguments'] -%>
+        end
+
+        <%- end -%>
+      end
+
+      <%- end -%>
+    end
+  end
+].gsub!(/^  /,''), nil, '>-%').result(binding)

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)