lib/bunny/exceptions.rb in bunny-0.9.0.pre13 vs lib/bunny/exceptions.rb in bunny-0.9.0.rc1

@@ -1,18 +1,26 @@
 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
 
     def initialize(message, cause)
       super(message)
       @cause = cause
     end
   end
 
+  # Base class for all channel level exceptions
   class ChannelLevelException < Exception
     attr_reader :channel, :channel_close
 
     def initialize(message, ch, channel_close)
       super(message)
@@ -20,10 +28,11 @@
       @channel       = ch
       @channel_close = channel_close
     end
   end
 
+  # Base class for all connection level exceptions
   class ConnectionLevelException < Exception
     attr_reader :connection, :connection_close
 
     def initialize(message, connection, connection_close)
       super(message)
@@ -32,10 +41,12 @@
       @connection_close = connection_close
     end
   end
 
 
+  # Raised when TCP connection to RabbitMQ fails because of an unresolved
+  # hostname, connectivity problem, etc
   class TCPConnectionFailed < Exception
     attr_reader :hostname, :port
 
     def initialize(e, hostname, port)
       m = case e
@@ -46,20 +57,23 @@
           end
       super("Could not estabilish TCP connection to #{hostname}:#{port}: #{m}")
     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)
         super("Trying to send frame through a closed connection. Frame is #{frame.inspect}, method class is #{frame.method_class}")
       else
         super("Trying to send frame through a closed connection. Frame is #{frame.inspect}")
       end
     end
   end
 
+  # Raised when RabbitMQ closes TCP connection before finishing connection
+  # sequence properly. This typically indicates an authentication issue.
   class PossibleAuthenticationFailureError < Exception
 
     #
     # API
     #
@@ -74,22 +88,32 @@
     end # initialize(settings)
   end # PossibleAuthenticationFailureError
 
 
   # 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 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
+  # 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
 
 
   # Base exception class for data consistency and framing errors.
   class InconsistentDataError < Exception
@@ -114,54 +138,69 @@
     def initialize(expected_length, actual_length)
       super("Frame payload should be #{expected_length} long, but it's #{actual_length} long.")
     end
   end
 
-
+  # Raised when a closed channel is used
   class ChannelAlreadyClosed < Exception
     attr_reader :channel
 
     def initialize(message, ch)
       super(message)
 
       @channel = ch
     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
 
     def initialize(other)
       super(other.message)
       @other = other
     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
 
 end