bunny 0.9.0.pre13 → 0.9.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b138bcc7caf170e8104ab84dcf9dc4ae89387efa
-  data.tar.gz: e379d87d1c0fa62e5c84908f530d8160328873cf
+  metadata.gz: a3593389008586553f21244193e35c325767ee25
+  data.tar.gz: e16cdce6c2dea0e4a01d5847494286e2b64a17ca
 SHA512:
-  metadata.gz: f850913f5f76996a6f333ff5bc2a945506c99b1463999b2f912a1602d7f96ff293285d26beb48ddf99cba314f69c6910d38e23858408c11d39a18dc821583dff
-  data.tar.gz: a12db3df3ad28867e4af5268e5a8f623884649cddc2259ceef6fadbd716099fc7928712857ababe86ad4e336406ea0d3672f8b8d0dd2dab4547475feccf5a41b
+  metadata.gz: 292dc01ab77ceb89f4c6dcd8e3a81f91e90167de8df9461a5da6a1466cb9f705c7f18e22ad3286774c5f18e66a21175c73588cfc609321a87f386e91613e08b7
+  data.tar.gz: efd54687b032919ed942a985d4a7f9c703110bd35faab173eb97de8c8a02e24de8edd1da0a9b00bb96e1a572afe905142ab637b24f94ab8e1834ea11a7803597

data/ChangeLog.md

@@ -1,3 +1,26 @@
+## Changes between Bunny 0.9.0.pre13 and 0.9.0.pre14
+
+### Bunny::Queue#pop_waiting
+
+`Bunny::Queue#pop_waiting` is a new function that mimics `Bunny::Queue#pop`
+but will wait until a message is available. It uses a `:timeout` option and will
+raise an exception if the timeout is hit:
+
+``` ruby
+# given 1 message in the queue,
+# works exactly as Bunny::Queue#get
+q.pop_waiting
+
+# given no messages in the queue, will wait for up to 0.5 seconds
+# for a message to become available. Raises an exception if the timeout
+# is hit
+q.pop_waiting(:timeout => 0.5)
+```
+
+This method only makes sense for collecting Request/Reply ("RPC") replies.
+
+
+
 ## Changes between Bunny 0.9.0.pre12 and 0.9.0.pre13
 
 ### Channels Without Consumers Now Tear Down Consumer Pools

data/README.md

@@ -33,12 +33,12 @@ To install Bunny 0.9.x with RubyGems:
 gem install bunny --pre
 ```
 
-the most recent 0.9.x version is `0.9.0.pre11`.
+the most recent 0.9.x version is `0.9.0.pre13`.
 
 To use Bunny 0.9.x in a project managed with Bundler:
 
 ``` ruby
-gem "bunny", ">= 0.9.0.pre11" # optionally: , :git => "git://github.com/ruby-amqp/bunny.git", :branch => "master"
+gem "bunny", ">= 0.9.0.pre13" # optionally: , :git => "git://github.com/ruby-amqp/bunny.git", :branch => "master"
 ```
 
 

data/lib/bunny.rb

@@ -26,7 +26,10 @@ require "bunny/exchange"
 require "bunny/queue"
 require "bunny/consumer"
 
+# Bunny is a RabbitMQ client that focuses on ease of use.
+# @see http://rubybunny.info
 module Bunny
+  # AMQP protocol version Bunny implements
   PROTOCOL_VERSION = AMQ::Protocol::PROTOCOL_VERSION
 
   # unifies Ruby standard library's Timeout (which is not accurate on
@@ -47,15 +50,24 @@ module Bunny
   # API
   #
 
+  # @return [String] Bunny version
   def self.version
     VERSION
   end
 
+  # @return [String] AMQP protocol version Bunny implements
   def self.protocol_version
     AMQ::Protocol::PROTOCOL_VERSION
   end
 
-
+  # Instantiates a new connection. The actual connection network
+  # connection is started with {Bunny::Session#start}
+  #
+  # @return [Bunny::Session]
+  # @see Bunny::Session#start
+  # @see http://rubybunny.info/articles/getting_started.html
+  # @see http://rubybunny.info/articles/connecting.html
+  # @api public
   def self.new(connection_string_or_opts = {}, opts = {}, &block)
     if connection_string_or_opts.respond_to?(:keys) && opts.empty?
       opts = connection_string_or_opts
@@ -71,7 +83,7 @@ module Bunny
   def self.run(connection_string_or_opts = {}, opts = {}, &block)
     raise ArgumentError, 'Bunny#run requires a block' unless block
 
-    client = Client.new(connection_string_or_opts, opts)
+    client = Session.new(connection_string_or_opts, opts)
 
     begin
       client.start
@@ -80,6 +92,7 @@ module Bunny
       client.stop
     end
 
+    # backwards compatibility
     :run_ok
   end
 end

data/lib/bunny/authentication/credentials_encoder.rb

@@ -1,27 +1,45 @@
 module Bunny
+  # Contains credentials encoding implementations for various
+  # authentication strategies.
   module Authentication
+    # Base credentials encoder. Subclasses implement credentials encoding for
+    # a particular authentication mechanism (PLAIN, EXTERNAL, etc).
+    #
+    # @api plugin
     class CredentialsEncoder
 
       #
       # API
       #
 
+      # Session that uses this encoder
+      # @return [Bunny::Session]
       attr_reader :session
 
+      # Instantiates a new encoder for the authentication mechanism
+      # used by the provided session.
+      #
+      # @return [Bunny::CredentialsEncoder]
       def self.for_session(session)
         registry[session.mechanism].new(session)
       end
 
+      # @private
       def self.registry
         @@registry ||= Hash.new { raise NotImplementedError }
       end
 
+      # Registers an encoder for authentication mechanism
+      # @api plugin
       def self.auth_mechanism(*mechanisms)
         mechanisms.each do |m|
           registry[m] = self
         end
       end
 
+      # Encodes provided credentials according to the specific authentication
+      # mechanism
+      # @return [String] Encoded credentials
       def encode_credentials(username, challenge)
         raise NotImplementedError.new("Subclasses must override this method")
       end

data/lib/bunny/authentication/external_mechanism_encoder.rb

@@ -2,6 +2,7 @@ require "bunny/authentication/credentials_encoder"
 
 module Bunny
   module Authentication
+    # Encodes credentials using the EXTERNAL mechanism
     class ExternalMechanismEncoder < CredentialsEncoder
 
       auth_mechanism "EXTERNAL", "external"

data/lib/bunny/authentication/plain_mechanism_encoder.rb

@@ -2,10 +2,12 @@ require "bunny/authentication/credentials_encoder"
 
 module Bunny
   module Authentication
+    # Encodes credentials using the PLAIN mechanism
     class PlainMechanismEncoder < CredentialsEncoder
 
       auth_mechanism "PLAIN", "plain"
 
+      # Encodes provided credentials as described in RFC 2595
       # @api public
       # @see http://tools.ietf.org/rfc/rfc2595.txt RFC 2595
       def encode_credentials(username, password)

data/lib/bunny/channel.rb

@@ -127,16 +127,20 @@ module Bunny
   #
   # @see http://www.rabbitmq.com/tutorials/amqp-concepts.html AMQP 0.9.1 Model Concepts Guide
   # @see http://rubybunny.info/articles/getting_started.html Getting Started with RabbitMQ Using Bunny
+  # @see http://rubybunny.info/articles/queues.html Queues and Consumers
+  # @see http://rubybunny.info/articles/exchanges.html Exchanges and Publishing
   # @see http://rubybunny.info/articles/error_handling.html Error Handling and Recovery Guide
   class Channel
 
     #
     # API
     #
+
     # @return [Integer] Channel id
     attr_accessor :id
     # @return [Bunny::Session] AMQP connection this channel was opened on
     attr_reader :connection
+    # @return [Symbol] Channel status (:opening, :open, :closed)
     attr_reader :status
     # @return [Bunny::ConsumerWorkPool] Thread pool delivered messages are dispatched to.
     attr_reader :work_pool
@@ -188,6 +192,7 @@ module Bunny
       @next_publish_seq_no = 0
     end
 
+    # @private
     def read_write_timeout
       @connection.read_write_timeout
     end
@@ -1443,6 +1448,7 @@ module Bunny
     # @endgroup
 
 
+    # @return [String] Brief human-readable representation of the channel
     def to_s
       "#<#{self.class.name}:#{object_id} @id=#{self.number} @connection=#{@connection.to_s}>"
     end
@@ -1777,7 +1783,7 @@ module Bunny
       raise ChannelAlreadyClosed.new("cannot use a channel that was already closed! Channel id: #{@id}", self) if closed?
     end
 
-    # @api private
+    # @private
     def reset_continuations
       @continuations           = new_continuation
       @confirms_continuations  = new_continuation
@@ -1786,12 +1792,12 @@ module Bunny
 
 
     if defined?(JRUBY_VERSION)
-      # @api private
+      # @private
       def new_continuation
         Concurrent::LinkedContinuationQueue.new
       end
     else
-      # @api private
+      # @private
       def new_continuation
         Concurrent::ContinuationQueue.new
       end

data/lib/bunny/channel_id_allocator.rb

@@ -2,6 +2,13 @@ require "thread"
 require "amq/int_allocator"
 
 module Bunny
+  # Bitset-based channel id allocator. When channels are closed,
+  # ids are released back to the pool.
+  #
+  # Every connection has its own allocator.
+  #
+  # Allocating and releasing ids is synchronized and can be performed
+  # from multiple threads.
   class ChannelIdAllocator
 
     #
@@ -64,6 +71,7 @@ module Bunny
       end
     end
 
+    # @private
     def synchronize(&block)
       @mutex.synchronize(&block)
     end

data/lib/bunny/concurrent/condition.rb

@@ -1,12 +1,14 @@
 require "thread"
 
 module Bunny
+  # @private
   module Concurrent
     # Akin to java.util.concurrent.Condition and intrinsic object monitors (Object#wait, Object#notify, Object#notifyAll) in Java:
     # threads can wait (block until notified) on a condition other threads notify them about.
     # Unlike the j.u.c. version, this one has a single waiting set.
     #
     # Conditions can optionally be annotated with a description string for ease of debugging.
+    # @private
     class Condition
       attr_reader :waiting_threads, :description
 

data/lib/bunny/concurrent/continuation_queue.rb

@@ -2,6 +2,9 @@ require "thread"
 
 module Bunny
   module Concurrent
+    # Continuation queue implementation for MRI and Rubinius
+    #
+    # @private
     class ContinuationQueue
       def initialize(*args, &block)
         @q = ::Queue.new(*args)

data/lib/bunny/concurrent/linked_continuation_queue.rb

@@ -9,6 +9,8 @@ java_import java.util.concurrent.TimeUnit
 
 module Bunny
   module Concurrent
+    # Continuation queue implementation for JRuby.
+    #
     # On JRuby, we'd rather use reliable and heavily battle tested j.u.c.
     # primitives with well described semantics than informally specified, clumsy
     # and limited Ruby standard library parts.
@@ -18,6 +20,7 @@ module Bunny
     #
     # Compared to the Ruby standard library Queue, there is one limitation: you cannot
     # push a nil on the queue, it will fail with a null pointer exception.
+    # @private
     class LinkedContinuationQueue
       def initialize(*args, &block)
         @q = LinkedBlockingQueue.new

data/lib/bunny/consumer.rb

@@ -79,10 +79,12 @@ module Bunny
       @channel.basic_cancel(@consumer_tag)
     end
 
+    # @return [String] More detailed human-readable string representation of this consumer
     def inspect
       "#<#{self.class.name}:#{object_id} @channel_id=#{@channel.number} @queue=#{self.queue_name}> @consumer_tag=#{@consumer_tag} @exclusive=#{@exclusive} @no_ack=#{@no_ack}>"
     end
 
+    # @return [String] Brief human-readable string representation of this consumer
     def to_s
       "#<#{self.class.name}:#{object_id} @channel_id=#{@channel.number} @queue=#{self.queue_name}> @consumer_tag=#{@consumer_tag}>"
     end

data/lib/bunny/consumer_tag_generator.rb

@@ -1,4 +1,5 @@
 module Bunny
+  # Used to generate consumer tags in the client
   class ConsumerTagGenerator
 
     #

data/lib/bunny/consumer_work_pool.rb

@@ -3,6 +3,8 @@ require "thread"
 module Bunny
   # Thread pool that dispatches consumer deliveries. Not supposed to be shared between channels
   # or threads.
+  #
+  # @private
   class ConsumerWorkPool
 
     #

data/lib/bunny/delivery_info.rb

@@ -1,5 +1,5 @@
 module Bunny
-  # Wraps AMQ::Protocol::Basic::Deliver to
+  # Wraps {AMQ::Protocol::Basic::Deliver} to
   # provide access to the delivery properties as immutable hash as
   # well as methods.
   class DeliveryInfo
@@ -14,8 +14,12 @@ module Bunny
     # API
     #
 
-    attr_reader :consumer, :channel
+    # @return [Bunny::Consumer] Consumer this delivery is for
+    attr_reader :consumer
+    # @return [Bunny::Channel] Channel this delivery is on
+    attr_reader :channel
 
+    # @private
     def initialize(basic_deliver, consumer, channel)
       @basic_deliver = basic_deliver
       @hash          = {
@@ -31,43 +35,55 @@ module Bunny
       @channel       = channel
     end
 
+    # Iterates over the delivery properties
+    # @see Enumerable#each
     def each(*args, &block)
       @hash.each(*args, &block)
     end
 
+    # Accesses delivery properties by key
+    # @see Hash#[]
     def [](k)
       @hash[k]
     end
 
+    # @return [Hash] Hash representation of this delivery info
     def to_hash
       @hash
     end
 
+    # @private
     def to_s
       to_hash.to_s
     end
 
+    # @private
     def inspect
       to_hash.inspect
     end
 
+    # @return [String] Consumer tag this delivery is for
     def consumer_tag
       @basic_deliver.consumer_tag
     end
 
+    # @return [String] Delivery identifier that is used to acknowledge, reject and nack deliveries
     def delivery_tag
       @basic_deliver.delivery_tag
     end
 
+    # @return [Boolean] true if this delivery is a redelivery (the message was requeued at least once)
     def redelivered
       @basic_deliver.redelivered
     end
     alias redelivered? redelivered
 
+    # @return [String] Name of the exchange this message was published to
     def exchange
       @basic_deliver.exchange
     end
 
+    # @return [String] Routing key this message was published with
     def routing_key
       @basic_deliver.routing_key
     end

data/lib/bunny/exceptions.rb

@@ -1,7 +1,14 @@
 module Bunny
+  # Base class for all Bunny exceptions
+  # @api public
   class Exception < ::StandardError
   end
 
+  # Indicates a network failure. If automatic network
+  # recovery mode is enabled, these will be typically handled
+  # by the client itself.
+  #
+  # @api public
   class NetworkFailure < Exception
     attr_reader :cause
 
@@ -11,6 +18,7 @@ module Bunny
     end
   end
 
+  # Base class for all channel level exceptions
   class ChannelLevelException < Exception
     attr_reader :channel, :channel_close
 
@@ -22,6 +30,7 @@ module Bunny
     end
   end
 
+  # Base class for all connection level exceptions
   class ConnectionLevelException < Exception
     attr_reader :connection, :connection_close
 
@@ -34,6 +43,8 @@ module Bunny
   end
 
 
+  # Raised when TCP connection to RabbitMQ fails because of an unresolved
+  # hostname, connectivity problem, etc
   class TCPConnectionFailed < Exception
     attr_reader :hostname, :port
 
@@ -48,6 +59,7 @@ module Bunny
     end
   end
 
+  # Raised when a frame is sent over an already closed connection
   class ConnectionClosedError < Exception
     def initialize(frame)
       if frame.respond_to?(:method_class)
@@ -58,6 +70,8 @@ module Bunny
     end
   end
 
+  # Raised when RabbitMQ closes TCP connection before finishing connection
+  # sequence properly. This typically indicates an authentication issue.
   class PossibleAuthenticationFailureError < Exception
 
     #
@@ -76,18 +90,28 @@ module Bunny
 
 
   # backwards compatibility
+  # @private
   ConnectionError = TCPConnectionFailed
+  # @private
   ServerDownError = TCPConnectionFailed
 
-  class ForcedChannelCloseError < Exception; end
-  class ForcedConnectionCloseError < Exception; end
-  class MessageError < Exception; end
-  class ProtocolError < Exception; end
-
-  # raised when read or write I/O operations time out (but only if
+  # Raised when a channel is closed forcefully using rabbitmqctl
+  # or the management UI plugin
+  class ForcedChannelCloseError < ChannelLevelException; end
+  # Raised when a connection is closed forcefully using rabbitmqctl
+  # or the management UI plugin
+  class ForcedConnectionCloseError < ConnectionLevelException; end
+  # @private
+  class MessageError  < ConnectionLevelException; end
+  # @private
+  class ProtocolError < ConnectionLevelException; end
+  # Raised when RabbitMQ reports and internal error
+  class InternalError < ConnectionLevelException; end
+
+  # Raised when read or write I/O operations time out (but only if
   # a connection is configured to use them)
   class ClientTimeout     < Timeout::Error; end
-  # raised on initial connection timeout
+  # Raised on initial TCP connection timeout
   class ConnectionTimeout < Timeout::Error; end
 
 
@@ -116,7 +140,7 @@ module Bunny
     end
   end
 
-
+  # Raised when a closed channel is used
   class ChannelAlreadyClosed < Exception
     attr_reader :channel
 
@@ -127,31 +151,43 @@ module Bunny
     end
   end
 
+  # Raised when RabbitMQ responds with 406 PRECONDITION_FAILED
   class PreconditionFailed < ChannelLevelException
   end
 
+  # Raised when RabbitMQ responds with 404 NOT_FOUND
   class NotFound < ChannelLevelException
   end
 
+  # Raised when RabbitMQ responds with 405 RESOUCE_LOCKED
   class ResourceLocked < ChannelLevelException
   end
 
+  # Raised when RabbitMQ responds with 403 ACCESS_REFUSED
   class AccessRefused < ChannelLevelException
   end
 
-
+  # Raised when RabbitMQ responds with 504 CHANNEL_ERROR
   class ChannelError < ConnectionLevelException
   end
 
-  class InvalidCommand < ConnectionLevelException
+  # Raised when RabbitMQ responds with 503 COMMAND_INVALID
+  class CommandInvalid < ConnectionLevelException
   end
 
+  # Raised when RabbitMQ responds with 501 FRAME_ERROR
   class FrameError < ConnectionLevelException
   end
 
+  # Raised when RabbitMQ responds with 505 UNEXPECTED_FRAME
   class UnexpectedFrame < ConnectionLevelException
   end
 
+  # Raised when RabbitMQ responds with 506 RESOURCE_ERROR
+  class ResourceError < ConnectionLevelException
+  end
+
+  # @private
   class NetworkErrorWrapper < Exception
     attr_reader :other
 
@@ -161,6 +197,9 @@ module Bunny
     end
   end
 
+  # Raised when RabbitMQ responds with 302 CONNECTION_FORCED
+  # (which means the connection was closed using rabbitmqctl or
+  # RabbitMQ management UI)
   class ConnectionForced < ConnectionLevelException
   end