bunny 0.9.0.pre13 → 0.9.0.rc1

data/lib/bunny/framing.rb

@@ -1,10 +1,12 @@
 module Bunny
+  # @private
   module Framing
     ENCODINGS_SUPPORTED = defined? Encoding
     HEADER_SLICE = (0..6).freeze
     DATA_SLICE = (7..-1).freeze
     PAYLOAD_SLICE = (0..-2).freeze
 
+    # @private
     module String
       class Frame < AMQ::Protocol::Frame
         def self.decode(string)
@@ -30,6 +32,7 @@ module Bunny
     end # String
 
 
+    # @private
     module IO
       class Frame < AMQ::Protocol::Frame
         def self.decode(io)

data/lib/bunny/heartbeat_sender.rb

@@ -3,6 +3,9 @@ require "amq/protocol/client"
 require "amq/protocol/frame"
 
 module Bunny
+  # Periodically sends heartbeats, keeping track of the last publishing activity.
+  #
+  # @private
   class HeartbeatSender
 
     #
@@ -50,7 +53,7 @@ module Bunny
         @logger.error "I/O error in the hearbeat sender: #{ioe.message}"
         stop
       rescue Exception => e
-        @logger.error "I/O error in the hearbeat sender: #{ioe.message}"
+        @logger.error "Error in the hearbeat sender: #{e.message}"
         stop
       end
     end

data/lib/bunny/message_properties.rb

@@ -14,82 +14,104 @@ module Bunny
     # API
     #
 
+    # @private
     def initialize(properties)
       @properties = properties
     end
 
+    # Iterates over the message properties
+    # @see Enumerable#each
     def each(*args, &block)
       @properties.each(*args, &block)
     end
 
+    # Accesses message properties by key
+    # @see Hash#[]
     def [](k)
       @properties[k]
     end
 
+    # @return [Hash] Hash representation of this delivery info
     def to_hash
       @properties
     end
 
+    # @private
     def to_s
       to_hash.to_s
     end
 
+    # @private
     def inspect
       to_hash.inspect
     end
 
+    # @return [String] (Optional) content type of the message, as set by the publisher
     def content_type
       @properties[:content_type]
     end
 
+    # @return [String] (Optional) content encoding of the message, as set by the publisher
     def content_encoding
       @properties[:content_encoding]
     end
 
+    # @return [String] Message headers
     def headers
       @properties[:headers]
     end
 
+    # @return [Integer] Delivery mode (persistent or transient)
     def delivery_mode
       @properties[:delivery_mode]
     end
 
+    # @return [Integer] Message priority, as set by the publisher
     def priority
       @properties[:priority]
     end
 
+    # @return [String] What message this message is a reply to (or corresponds to), as set by the publisher
     def correlation_id
       @properties[:correlation_id]
     end
 
+    # @return [String] (Optional) How to reply to the publisher (usually a reply queue name)
     def reply_to
       @properties[:reply_to]
     end
 
+    # @return [String] Message expiration, as set by the publisher
     def expiration
       @properties[:expiration]
     end
 
+    # @return [String] Message ID, as set by the publisher
     def message_id
       @properties[:message_id]
     end
 
+    # @return [Time] Message timestamp, as set by the publisher
     def timestamp
       @properties[:timestamp]
     end
 
+    # @return [String] Message type, as set by the publisher
     def type
       @properties[:type]
     end
 
+    # @return [String] Publishing user, as set by the publisher
     def user_id
       @properties[:user_id]
     end
 
+    # @return [String] Publishing application, as set by the publisher
     def app_id
       @properties[:app_id]
     end
 
+    # @return [String] Cluster ID, as set by the publisher
     def cluster_id
       @properties[:cluster_id]
     end

data/lib/bunny/queue.rb

@@ -256,6 +256,55 @@ module Bunny
       end
     end
 
+    # @param [Hash] opts Options
+    #
+    # @option opts [Boolean] :ack (false) Will the message be acknowledged manually?
+    # @option opts [Float] :timeout (1.0) Max amount of time, in seconds, to wait before raising an exception
+    #
+    # @return [Array] Triple of delivery info, message properties and message content.
+    #                 If the queue is empty, all three will be nils.
+    #
+    # @raises [Bunny::ClientException] When no message is available in the amount of time provided via the :timeout option
+    #
+    # @see http://rubybunny.info/articles/queues.html Queues and Consumers guide
+    # @see Bunny::Queue#subscribe
+    # @api public
+    #
+    # @example
+    #   conn = Bunny.new
+    #   conn.start
+    #
+    #   ch   = conn.create_channel
+    #   q = ch.queue("test1")
+    #   x = ch.default_exchange
+    #   x.publish("Hello, everybody!", :routing_key => 'test1')
+    #
+    #   delivery_info, properties, payload = q.pop_waiting(:timeout => 0.5)
+    #
+    #   puts "This is the message: " + payload + "\n\n"
+    #   conn.close
+    def pop_waiting(opts = {:ack => false, :timeout => 1.0}, &block)
+      delivery_info, properties, content = nil, nil, nil
+
+      Bunny::Timer.timeout(opts[:timeout], ClientTimeout) do
+        loop do
+          delivery_info, properties, content = @channel.basic_get(@name, opts)
+
+          if !content.nil?
+            break
+          end
+        end
+      end
+
+      if block
+        block.call(delivery_info, properties, content)
+      else
+        [delivery_info, properties, content]
+      end
+    end
+    alias get_waiting pop_waiting
+
+
     # Publishes a message to the queue via default exchange. Takes the same arguments
     # as {Bunny::Exchange#publish}
     #

data/lib/bunny/reader_loop.rb

@@ -6,6 +6,7 @@ module Bunny
   # This loop uses a separate thread internally.
   #
   # This mimics the way RabbitMQ Java is designed quite closely.
+  # @private
   class ReaderLoop
 
     def initialize(transport, session, session_thread)

data/lib/bunny/return_info.rb

@@ -24,38 +24,49 @@ module Bunny
       }
     end
 
+    # Iterates over the returned delivery properties
+    # @see Enumerable#each
     def each(*args, &block)
       @hash.each(*args, &block)
     end
 
+    # Accesses returned delivery properties by key
+    # @see Hash#[]
     def [](k)
       @hash[k]
     end
 
+    # @return [Hash] Hash representation of this returned delivery info
     def to_hash
       @hash
     end
 
+    # @private
     def to_s
       to_hash.to_s
     end
 
+    # @private
     def inspect
       to_hash.inspect
     end
 
+    # @return [Integer] Reply (status) code of the cause
     def reply_code
       @basic_return.reply_code
     end
 
+    # @return [Integer] Reply (status) text of the cause, explaining why the message was returned
     def reply_text
       @basic_return.reply_text
     end
 
+    # @return [String] Exchange the message was published to
     def exchange
       @basic_return.exchange
     end
 
+    # @return [String] Routing key the message has
     def routing_key
       @basic_return.routing_key
     end

data/lib/bunny/session.rb

@@ -54,8 +54,10 @@ module Bunny
       :information  => "http://rubybunny.info",
     }
 
+    # @private
     DEFAULT_LOCALE = "en_GB"
 
+    # Default reconnection interval for TCP connection failures
     DEFAULT_NETWORK_RECOVERY_INTERVAL = 5.0
 
 
@@ -63,6 +65,8 @@ module Bunny
     # API
     #
 
+    # @return [Bunny::Transport]
+    attr_reader :transport
     attr_reader :status, :host, :port, :heartbeat, :user, :pass, :vhost, :frame_max, :threaded
     attr_reader :server_capabilities, :server_properties, :server_authentication_mechanisms, :server_locales
     attr_reader :default_channel
@@ -138,6 +142,8 @@ module Bunny
       @channels            = Hash.new
 
       self.reset_continuations
+
+      self.initialize_transport
     end
 
     # @return [String] RabbitMQ hostname (or IP address) used
@@ -169,7 +175,20 @@ module Bunny
       @threaded
     end
 
-    # Starts connection process
+    def configure_socket(&block)
+      raise ArgumentError, "No block provided!" if block.nil?
+
+      if @transport
+        @transport.configure_socket(&block)
+      else
+        @socket_configurator = block
+      end
+    end
+
+    # Starts the connection process.
+    #
+    # @see http://rubybunny.info/articles/getting_started.html
+    # @see http://rubybunny.info/articles/connecting.html
     # @api public
     def start
       return self if connected?
@@ -183,6 +202,13 @@ module Bunny
         self.maybe_close_transport
         self.initialize_transport
 
+        @transport.initialize_socket
+        @transport.connect
+
+        if @socket_configurator
+          @transport.configure_socket(&@socket_configurator)
+        end
+
         self.init_connection
         self.open_connection
 
@@ -198,6 +224,9 @@ module Bunny
       self
     end
 
+    # Socket operation timeout used by this connection
+    # @return [Integer]
+    # @private
     def read_write_timeout
       @transport.read_write_timeout
     end
@@ -397,6 +426,7 @@ module Bunny
       raise @last_connection_error if @last_connection_error
     end
 
+    # @private
     def handle_frameset(ch_number, frames)
       method = frames.first
 
@@ -486,11 +516,15 @@ module Bunny
                 when 501 then
                   FrameError
                 when 503 then
-                  InvalidCommand
+                  CommandInvalid
                 when 504 then
                   ChannelError
                 when 505 then
                   UnexpectedFrame
+                when 506 then
+                  ResourceError
+                when 541 then
+                  InternalError
                 else
                   raise "Unknown reply code: #{frame.reply_code}, text: #{frame.reply_text}"
                 end
@@ -615,7 +649,7 @@ module Bunny
     # Sends multiple frames, one by one. For thread safety this method takes a channel
     # object and synchronizes on it.
     #
-    # @api private
+    # @private
     def send_frameset(frames, channel)
       # some developers end up sharing channels between threads and when multiple
       # threads publish on the same channel aggressively, at some point frames will be
@@ -632,7 +666,7 @@ module Bunny
     # object and synchronizes on it. Uses transport implementation that does not perform
     # timeout control.
     #
-    # @api private
+    # @private
     def send_frameset_without_timeout(frames, channel)
       # some developers end up sharing channels between threads and when multiple
       # threads publish on the same channel aggressively, at some point frames will be
@@ -653,7 +687,7 @@ module Bunny
 
     protected
 
-    # @api private
+    # @private
     def init_connection
       self.send_preamble
 
@@ -668,7 +702,7 @@ module Bunny
       @status = :connected
     end
 
-    # @api private
+    # @private
     def open_connection
       @transport.send_frame(AMQ::Protocol::Connection::StartOk.encode(@client_properties, @mechanism, self.encode_credentials(username, password), @locale))
       @logger.debug "Sent connection.start-ok"
@@ -732,7 +766,7 @@ module Bunny
       0 == val || val.nil?
     end
 
-    # @api private
+    # @private
     def negotiate_value(client_value, server_value)
       return server_value if client_value == :server
 
@@ -743,59 +777,59 @@ module Bunny
       end
     end
 
-    # @api private
+    # @private
     def initialize_heartbeat_sender
       @logger.debug "Initializing heartbeat sender..."
       @heartbeat_sender = HeartbeatSender.new(@transport, @logger)
       @heartbeat_sender.start(@heartbeat)
     end
 
-    # @api private
+    # @private
     def maybe_shutdown_heartbeat_sender
       @heartbeat_sender.stop if @heartbeat_sender
     end
 
-    # @api private
+    # @private
     def initialize_transport
       @transport = Transport.new(self, @host, @port, @opts.merge(:session_thread => Thread.current))
     end
 
-    # @api private
+    # @private
     def maybe_close_transport
       @transport.close if @transport
     end
 
     # Sends AMQ protocol header (also known as preamble).
-    # @api private
+    # @private
     def send_preamble
       @transport.write(AMQ::Protocol::PREAMBLE)
       @logger.debug "Sent protocol preamble"
     end
 
 
-    # @api private
+    # @private
     def encode_credentials(username, password)
       @credentials_encoder.encode_credentials(username, password)
     end # encode_credentials(username, password)
 
-    # @api private
+    # @private
     def credentials_encoder_for(mechanism)
       Authentication::CredentialsEncoder.for_session(self)
     end
 
     if defined?(JRUBY_VERSION)
-      # @api private
+      # @private
       def reset_continuations
         @continuations = Concurrent::LinkedContinuationQueue.new
       end
     else
-      # @api private
+      # @private
       def reset_continuations
         @continuations = Concurrent::ContinuationQueue.new
       end
     end
 
-    # @api private
+    # @private
     def wait_on_continuations
       unless @threaded
         reader_loop.run_once until @continuations.length > 0
@@ -804,7 +838,7 @@ module Bunny
       @continuations.poll(@continuation_timeout)
     end
 
-    # @api private
+    # @private
     def init_logger(level)
       @logger          = ::Logger.new(@logfile)
       @logger.level    = normalize_log_level(level)
@@ -813,7 +847,7 @@ module Bunny
       @logger
     end
 
-    # @api private
+    # @private
     def normalize_log_level(level)
       case level
       when :debug, Logger::DEBUG, "debug" then Logger::DEBUG