bunny 0.9.0.pre10 → 0.9.0.pre11

data/bunny.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |s|
   s.name = "bunny"
   s.version = Bunny::VERSION.dup
   s.homepage = "http://github.com/ruby-amqp/bunny"
-  s.summary = "Easy to use synchronous Ruby client for RabbitMQ"
-  s.description = "Easy to use synchronous Ruby client for RabbitMQ"
+  s.summary = "Popular easy to use Ruby client for RabbitMQ"
+  s.description = "Popular easy to use Ruby client for RabbitMQ"
   s.license = "MIT"
 
   # Sorted alphabetically.
@@ -29,7 +29,7 @@ Gem::Specification.new do |s|
     map { |mail| Base64.decode64(mail) }
 
   # Dependencies
-  s.add_dependency "amq-protocol", ">= 1.4.0"
+  s.add_dependency "amq-protocol", ">= 1.6.0"
 
   # Files.
   s.has_rdoc = true

data/lib/bunny.rb

@@ -17,6 +17,8 @@ rescue LoadError => e
   # no-op
 end
 
+require "logger"
+
 # Core entities: connection, channel, exchange, queue, consumer
 require "bunny/session"
 require "bunny/channel"

data/lib/bunny/channel.rb

@@ -159,6 +159,7 @@ module Bunny
     # @param [Bunny::ConsumerWorkPool] work_pool Thread pool for delivery processing, by default of size 1
     def initialize(connection = nil, id = nil, work_pool = ConsumerWorkPool.new(1))
       @connection = connection
+      @logger     = connection.logger
       @id         = id || @connection.next_channel_id
       @status     = :opening
 
@@ -214,6 +215,7 @@ module Bunny
     def close
       @connection.close_channel(self)
       closed!
+      maybe_kill_consumer_work_pool!
     end
 
     # @return [Boolean] true if this channel is open, false otherwise
@@ -1281,7 +1283,7 @@ module Bunny
       raise_if_no_longer_open!
 
       if @next_publish_seq_no == 0
-        @confirms_continuations = ::Queue.new
+        @confirms_continuations = new_continuation
         @unconfirmed_set        = Set.new
         @nacked_set             = Set.new
         @next_publish_seq_no    = 1
@@ -1358,7 +1360,7 @@ module Bunny
     #
     # @api plugin
     def recover_from_network_failure
-      # puts "Recovering channel #{@id}"
+      @logger.debug "Recovering channel #{@id} after network failure"
       release_all_continuations
 
       recover_prefetch_setting
@@ -1392,7 +1394,7 @@ module Bunny
     # @api plugin
     def recover_queues
       @queues.values.dup.each do |q|
-        # puts "Recovering queue #{q.name}"
+        @logger.debug "Recovering queue #{q.name}"
         q.recover_from_network_failure
       end
     end
@@ -1436,7 +1438,7 @@ module Bunny
 
     # @private
     def handle_method(method)
-      # puts "Channel#handle_frame on channel #{@id}: #{method.inspect}"
+      @logger.debug "Channel#handle_frame on channel #{@id}: #{method.inspect}"
       case method
       when AMQ::Protocol::Queue::DeclareOk then
         @continuations.push(method)
@@ -1525,8 +1527,7 @@ module Bunny
           consumer.call(DeliveryInfo.new(basic_deliver), MessageProperties.new(properties), content)
         end
       else
-        # TODO: log it
-        puts "[warning] No consumer for tag #{basic_deliver.consumer_tag}"
+        @logger.warn "No consumer for tag #{basic_deliver.consumer_tag} on channel #{@id}!"
       end
     end
 
@@ -1537,7 +1538,7 @@ module Bunny
       if x
         x.handle_return(ReturnInfo.new(basic_return), MessageProperties.new(properties), content)
       else
-        # TODO: log a warning
+        @logger.warn "Exchange #{basic_return.exchange} is not in channel #{@id}'s cache! Dropping returned message!"
       end
     end
 
@@ -1574,12 +1575,13 @@ module Bunny
         t = Thread.current
         @threads_waiting_on_continuations << t
 
-        v = @continuations.pop
-        @threads_waiting_on_continuations.delete(t)
-
-        v
+        begin
+          @continuations.poll(@connection.continuation_timeout)
+        ensure
+          @threads_waiting_on_continuations.delete(t)
+        end
       else
-        connection.event_loop.run_once until @continuations.length > 0
+        connection.reader_loop.run_once until @continuations.length > 0
 
         @continuations.pop
       end
@@ -1591,10 +1593,11 @@ module Bunny
         t = Thread.current
         @threads_waiting_on_basic_get_continuations << t
 
-        v = @basic_get_continuations.pop
-        @threads_waiting_on_basic_get_continuations.delete(t)
-
-        v
+        begin
+          @basic_get_continuations.poll(@connection.continuation_timeout)
+        ensure
+          @threads_waiting_on_basic_get_continuations.delete(t)
+        end
       else
         connection.event_loop.run_once until @basic_get_continuations.length > 0
 
@@ -1608,10 +1611,11 @@ module Bunny
         t = Thread.current
         @threads_waiting_on_confirms_continuations << t
 
-        v = @confirms_continuations.pop
-        @threads_waiting_on_confirms_continuations.delete(t)
-
-        v
+        begin
+          @confirms_continuations.poll(@connection.continuation_timeout)
+        ensure
+          @threads_waiting_on_confirms_continuations.delete(t)
+        end
       else
         connection.event_loop.run_once until @confirms_continuations.length > 0
 
@@ -1622,25 +1626,17 @@ module Bunny
     # Releases all continuations. Used by automatic network recovery.
     # @private
     def release_all_continuations
-      if @confirms_continuations.num_waiting > 0
-        @threads_waiting_on_confirms_continuations.each do |t|
-          t.run
-        end
+      @threads_waiting_on_confirms_continuations.each do |t|
+        t.run
       end
-      if @continuations.num_waiting > 0
-        @threads_waiting_on_continuations.each do |t|
-          t.run
-        end
+      @threads_waiting_on_continuations.each do |t|
+        t.run
       end
-      if @basic_get_continuations.num_waiting > 0
-        @threads_waiting_on_basic_get_continuations.each do |t|
-          t.run
-        end
+      @threads_waiting_on_basic_get_continuations.each do |t|
+        t.run
       end
 
-      @continuations           = ::Queue.new
-      @confirms_continuations  = ::Queue.new
-      @basic_get_continuations = ::Queue.new
+      self.reset_continuations
     end
 
     # Starts consumer work pool. Lazily called by #basic_consume to avoid creating new threads

data/lib/bunny/concurrent/continuation_queue.rb

@@ -16,6 +16,16 @@ module Bunny
         @q.pop
       end
 
+      def poll(timeout_in_ms = nil)
+        if timeout_in_ms
+          Bunny::Timer.timeout(timeout_in_ms / 1000, Timeout::Error) do
+            @q.pop
+          end
+        else
+          @q.pop
+        end
+      end
+
       def clear
         @q.clear
       end

data/lib/bunny/concurrent/linked_continuation_queue.rb

@@ -25,7 +25,7 @@ module Bunny
 
       def push(el, timeout_in_ms = nil)
         if timeout_in_ms
-          @q.offer(el, timeout_in_ms, TimeUnit.MILLISECONDS)
+          @q.offer(el, timeout_in_ms, TimeUnit::MILLISECONDS)
         else
           @q.offer(el)
         end
@@ -38,7 +38,9 @@ module Bunny
 
       def poll(timeout_in_ms = nil)
         if timeout_in_ms
-          @q.poll(timeout_in_ms, TimeUnit.MILLISECONDS)
+          v = @q.poll(timeout_in_ms, TimeUnit::MILLISECONDS)
+          raise ::Timeout::Error.new("operation did not finish in #{timeout_in_ms} ms") if v.nil?
+          v
         else
           @q.poll
         end

data/lib/bunny/exceptions.rb

@@ -98,7 +98,7 @@ module Bunny
   # Raised by adapters when frame does not end with {final octet AMQ::Protocol::Frame::FINAL_OCTET}.
   # This suggest that there is a bug in adapter or AMQ broker implementation.
   #
-  # @see http://files.travis-ci.org/docs/amqp/0.9.1/AMQP091Specification.pdf AMQP 0.9.1 specification (Section 2.3)
+  # @see https://www.rabbitmq.com/resources/specs/amqp0-9-1.pdf AMQP 0.9.1 specification (Section 2.3)
   class NoFinalOctetError < InconsistentDataError
     def initialize
       super("Frame doesn't end with #{AMQ::Protocol::Frame::FINAL_OCTET} as it must, which means the size is miscalculated.")
@@ -109,7 +109,7 @@ module Bunny
   # to the size specified in that frame's header.
   # This suggest that there is a bug in adapter or AMQ broker implementation.
   #
-  # @see http://files.travis-ci.org/docs/amqp/0.9.1/AMQP091Specification.pdf AMQP 0.9.1 specification (Section 2.3)
+  # @see https://www.rabbitmq.com/resources/specs/amqp0-9-1.pdf AMQP 0.9.1 specification (Section 2.3)
   class BadLengthError < InconsistentDataError
     def initialize(expected_length, actual_length)
       super("Frame payload should be #{expected_length} long, but it's #{actual_length} long.")
@@ -146,6 +146,9 @@ module Bunny
   class InvalidCommand < ConnectionLevelException
   end
 
+  class FrameError < ConnectionLevelException
+  end
+
   class UnexpectedFrame < ConnectionLevelException
   end
 

data/lib/bunny/heartbeat_sender.rb

@@ -9,8 +9,9 @@ module Bunny
     # API
     #
 
-    def initialize(transport)
+    def initialize(transport, logger)
       @transport = transport
+      @logger    = logger
       @mutex     = Mutex.new
 
       @last_activity_time = Time.now
@@ -46,10 +47,10 @@ module Bunny
           sleep @interval
         end
       rescue IOError => ioe
-        puts ioe.message
+        @logger.error "I/O error in the hearbeat sender: #{ioe.message}"
         stop
       rescue Exception => e
-        puts e.message
+        @logger.error "I/O error in the hearbeat sender: #{ioe.message}"
         stop
       end
     end
@@ -58,7 +59,8 @@ module Bunny
       now = Time.now
 
       if now > (@last_activity_time + @interval)
-        @transport.send_raw(AMQ::Protocol::HeartbeatFrame.encode)
+        @logger.debug "Sending a heartbeat, last activity time: #{@last_activity_time}, interval (s): #{@interval}"
+        @transport.write_without_timeout(AMQ::Protocol::HeartbeatFrame.encode)
       end
     end
   end

data/lib/bunny/queue.rb

@@ -326,12 +326,14 @@ module Bunny
         @channel.deregister_queue_named(old_name)
       end
 
+      # TODO: inject and use logger
       # puts "Recovering queue #{@name}"
       begin
         declare!
 
         @channel.register_queue(self)
       rescue Exception => e
+        # TODO: inject and use logger
         puts "Caught #{e.inspect} while redeclaring and registering #{@name}!"
       end
       recover_bindings
@@ -340,6 +342,7 @@ module Bunny
     # @private
     def recover_bindings
       @bindings.each do |b|
+        # TODO: inject and use logger
         # puts "Recovering binding #{b.inspect}"
         self.bind(b[:exchange], b)
       end

data/lib/bunny/{main_loop.rb → reader_loop.rb}

@@ -6,12 +6,13 @@ module Bunny
   # This loop uses a separate thread internally.
   #
   # This mimics the way RabbitMQ Java is designed quite closely.
-  class MainLoop
+  class ReaderLoop
 
     def initialize(transport, session, session_thread)
       @transport      = transport
       @session        = session
       @session_thread = session_thread
+      @logger         = @session.logger
     end
 
 
@@ -33,7 +34,6 @@ module Bunny
         rescue Errno::EBADF => ebadf
           # ignored, happens when we loop after the transport has already been closed
         rescue AMQ::Protocol::EmptyResponseError, IOError, SystemCallError => e
-          puts "Exception in the main loop:"
           log_exception(e)
 
           @network_is_down = true
@@ -44,7 +44,6 @@ module Bunny
             @session_thread.raise(Bunny::NetworkFailure.new("detected a network failure: #{e.message}", e))
           end
         rescue Exception => e
-          puts "Unepxected exception in the main loop:"
           log_exception(e)
 
           @network_is_down = true
@@ -55,8 +54,6 @@ module Bunny
 
     def run_once
       frame = @transport.read_next_frame
-      @session.signal_activity!
-
       return if frame.is_a?(AMQ::Protocol::HeartbeatFrame)
 
       if !frame.final? || frame.method_class.has_content?
@@ -88,10 +85,10 @@ module Bunny
     end
 
     def log_exception(e)
-      puts e.class.name
-      puts e.message
+      @logger.error "Exception in the reader loop: #{e.class.name}: #{e.message}"
+      @logger.error "Backtrace: "
       e.backtrace.each do |line|
-        puts line
+        @logger.error "\t#{line}"
       end
     end
   end

data/lib/bunny/session.rb

@@ -4,7 +4,7 @@ require "thread"
 require "bunny/transport"
 require "bunny/channel_id_allocator"
 require "bunny/heartbeat_sender"
-require "bunny/main_loop"
+require "bunny/reader_loop"
 require "bunny/authentication/credentials_encoder"
 require "bunny/authentication/plain_mechanism_encoder"
 require "bunny/authentication/external_mechanism_encoder"
@@ -70,6 +70,10 @@ module Bunny
     # Authentication mechanism, e.g. "PLAIN" or "EXTERNAL"
     # @return [String]
     attr_reader :mechanism
+    # @return [Logger]
+    attr_reader :logger
+    # @return [Integer] Timeout for blocking protocol operations (queue.declare, queue.bind, etc), in milliseconds. Default is 4000.
+    attr_reader :continuation_timeout
 
 
     # @param [String, Hash] connection_string_or_opts Connection string or a hash of connection options
@@ -103,10 +107,11 @@ module Bunny
       @user            = self.username_from(opts)
       @pass            = self.password_from(opts)
       @vhost           = self.vhost_from(opts)
-      @logfile         = opts[:logfile]
-      @logging         = opts[:logging] || false
+      @logfile         = opts[:log_file] || opts[:logfile] || STDOUT
       @threaded        = opts.fetch(:threaded, true)
 
+      self.init_logger(opts[:log_level] || ENV["BUNNY_LOG_LEVEL"] || Logger::WARN)
+
       # should automatic recovery from network failures be used?
       @automatically_recover = if opts[:automatically_recover].nil? && opts[:automatic_recovery].nil?
                                  true
@@ -114,6 +119,8 @@ module Bunny
                                  opts[:automatically_recover] || opts[:automatic_recovery]
                                end
       @network_recovery_interval = opts.fetch(:network_recovery_interval, DEFAULT_NETWORK_RECOVERY_INTERVAL)
+      # in ms
+      @continuation_timeout      = opts.fetch(:continuation_timeout, 4000)
 
       @status             = :not_connected
 
@@ -128,7 +135,6 @@ module Bunny
       @locale              = @opts.fetch(:locale, DEFAULT_LOCALE)
       # mutex for the channel id => channel hash
       @channel_mutex       = Mutex.new
-      @network_mutex       = Mutex.new
       @channels            = Hash.new
 
       self.reset_continuations
@@ -180,8 +186,8 @@ module Bunny
         self.init_connection
         self.open_connection
 
-        @event_loop = nil
-        self.start_main_loop if @threaded
+        @reader_loop = nil
+        self.start_reader_loop if @threaded
 
         @default_channel = self.create_channel
       rescue Exception => e
@@ -201,11 +207,11 @@ module Bunny
     # opened (this operation is very fast and inexpensive).
     #
     # @return [Bunny::Channel] Newly opened channel
-    def create_channel(n = nil)
+    def create_channel(n = nil, consumer_pool_size = 1)
       if n && (ch = @channels[n])
         ch
       else
-        ch = Bunny::Channel.new(self, n)
+        ch = Bunny::Channel.new(self, n, ConsumerWorkPool.new(consumer_pool_size || 1))
         ch.open
         ch
       end
@@ -341,7 +347,7 @@ module Bunny
 
     # @private
     def handle_frame(ch_number, method)
-      # puts "Session#handle_frame on #{ch_number}: #{method.inspect}"
+      @logger.debug "Session#handle_frame on #{ch_number}: #{method.inspect}"
       case method
       when AMQ::Protocol::Channel::OpenOk then
         @continuations.push(method)
@@ -357,14 +363,14 @@ module Bunny
         begin
           @continuations.clear
 
-          event_loop.stop
-          @event_loop = nil
+          reader_loop.stop
+          @reader_loop = nil
 
           @transport.close
         rescue StandardError => e
-          puts e.class.name
-          puts e.message
-          puts e.backtrace
+          @logger.error e.class.name
+          @logger.error e.message
+          @logger.error e.backtrace
         ensure
           @continuations.push(:__unblock__)
         end
@@ -381,7 +387,7 @@ module Bunny
         if ch = @channels[ch_number]
           ch.handle_method(method)
         else
-          # TODO: log a warning
+          @logger.warn "Channel #{ch_number} is not open on this connection!"
         end
       end
     end
@@ -415,7 +421,7 @@ module Bunny
       if !recovering_from_network_failure?
         @recovering_from_network_failure = true
         if recoverable_network_failure?(exception)
-          # puts "Recovering from a network failure..."
+          @logger.warn "Recovering from a network failure..."
           @channels.each do |n, ch|
             ch.maybe_kill_consumer_work_pool!
           end
@@ -443,7 +449,7 @@ module Bunny
     def recover_from_network_failure
       begin
         sleep @network_recovery_interval
-        # puts "About to start recovery..."
+        @logger.debug "About to start connection recovery..."
         start
 
         if open?
@@ -452,7 +458,7 @@ module Bunny
           recover_channels
         end
       rescue TCPConnectionFailed, AMQ::Protocol::EmptyResponseError => e
-        # puts "TCP connection failed, reconnecting in 5 seconds"
+        @logger.warn "TCP connection failed, reconnecting in 5 seconds"
         sleep @network_recovery_interval
         retry if recoverable_network_failure?(e)
       end
@@ -470,11 +476,6 @@ module Bunny
       end
     end
 
-    # @private
-    def send_raw(data)
-      @transport.write(data)
-    end
-
     # @private
     def instantiate_connection_level_exception(frame)
       case frame
@@ -482,6 +483,8 @@ module Bunny
         klass = case frame.reply_code
                 when 320 then
                   ConnectionForced
+                when 501 then
+                  FrameError
                 when 503 then
                   InvalidCommand
                 when 504 then
@@ -560,18 +563,18 @@ module Bunny
     end
 
     # @private
-    def start_main_loop
-      event_loop.start
+    def start_reader_loop
+      reader_loop.start
     end
 
     # @private
-    def event_loop
-      @event_loop ||= MainLoop.new(@transport, self, Thread.current)
+    def reader_loop
+      @reader_loop ||= ReaderLoop.new(@transport, self, Thread.current)
     end
 
     # @private
-    def maybe_shutdown_main_loop
-      @event_loop.stop if @event_loop
+    def maybe_shutdown_reader_loop
+      @reader_loop.stop if @reader_loop
     end
 
     # @private
@@ -585,11 +588,12 @@ module Bunny
     #
     # @raise [ConnectionClosedError]
     # @private
-    def send_frame(frame)
+    def send_frame(frame, signal_activity = true)
       if closed?
         raise ConnectionClosedError.new(frame)
       else
-        @network_mutex.synchronize { @transport.write(frame.encode) }
+        @transport.write(frame.encode)
+        signal_activity! if signal_activity
       end
     end
 
@@ -599,11 +603,12 @@ module Bunny
     #
     # @raise [ConnectionClosedError]
     # @private
-    def send_frame_without_timeout(frame)
+    def send_frame_without_timeout(frame, signal_activity = true)
       if closed?
         raise ConnectionClosedError.new(frame)
       else
-        @network_mutex.synchronize { @transport.write_without_timeout(frame.encode) }
+        @transport.write_without_timeout(frame.encode)
+        signal_activity! if signal_activity
       end
     end
 
@@ -618,8 +623,8 @@ module Bunny
       # If we synchronize on the channel, however, this is both thread safe and pretty fine-grained
       # locking. Note that "single frame" methods do not need this kind of synchronization. MK.
       channel.synchronize do
-        frames.each { |frame| self.send_frame(frame) }
-        @transport.flush
+        frames.each { |frame| self.send_frame(frame, false) }
+        signal_activity!
       end
     end # send_frameset(frames)
 
@@ -635,10 +640,17 @@ module Bunny
       # If we synchronize on the channel, however, this is both thread safe and pretty fine-grained
       # locking. Note that "single frame" methods do not need this kind of synchronization. MK.
       channel.synchronize do
-        frames.each { |frame| self.send_frame_without_timeout(frame) }
+        frames.each { |frame| self.send_frame_without_timeout(frame, false) }
+        signal_activity!
       end
     end # send_frameset_without_timeout(frames)
 
+    # @return [String]
+    # @api public
+    def to_s
+      "Bunny::Session #{@user}@#{@host}:#{@port}, vhost=#{@vhost}"
+    end
+
     protected
 
     # @api private
@@ -659,6 +671,7 @@ module Bunny
     # @api 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"
 
       frame = begin
                 @transport.read_next_frame
@@ -669,6 +682,7 @@ module Bunny
               end
       if frame.nil?
         @state = :closed
+        @logger.error "RabbitMQ closed TCP connection before AMQP 0.9.1 connection was finalized. Most likely this means authentication failure."
         raise Bunny::PossibleAuthenticationFailureError.new(self.user, self.vhost, self.password.size)
       end
 
@@ -682,11 +696,15 @@ module Bunny
                               else
                                 negotiate_value(@client_heartbeat, connection_tune.heartbeat)
                               end
+      @logger.debug "Heartbeat interval negotiation: client = #{@client_heartbeat}, server = #{connection_tune.heartbeat}, result = #{@heartbeat}"
+      @logger.info "Heartbeat interval used (in seconds): #{@heartbeat}"
 
       @channel_id_allocator = ChannelIdAllocator.new(@channel_max)
 
       @transport.send_frame(AMQ::Protocol::Connection::TuneOk.encode(@channel_max, @frame_max, @heartbeat))
+      @logger.debug "Sent connection.tune-ok with heartbeat interval = #{@heartbeat}, frame_max = #{@frame_max}, channel_max = #{@channel_max}"
       @transport.send_frame(AMQ::Protocol::Connection::Open.encode(self.vhost))
+      @logger.debug "Sent connection.open with vhost = #{self.vhost}"
 
       frame2 = begin
                  @transport.read_next_frame
@@ -697,6 +715,7 @@ module Bunny
                end
       if frame2.nil?
         @state = :closed
+        @logger.warn "RabbitMQ closed TCP connection before AMQP 0.9.1 connection was finalized. Most likely this means authentication failure."
         raise Bunny::PossibleAuthenticationFailureError.new(self.user, self.vhost, self.password.size)
       end
       connection_open_ok = frame2.decode_payload
@@ -726,8 +745,8 @@ module Bunny
 
     # @api private
     def initialize_heartbeat_sender
-      # puts "Initializing heartbeat sender..."
-      @heartbeat_sender = HeartbeatSender.new(@transport)
+      @logger.debug "Initializing heartbeat sender..."
+      @heartbeat_sender = HeartbeatSender.new(@transport, @logger)
       @heartbeat_sender.start(@heartbeat)
     end
 
@@ -749,7 +768,8 @@ module Bunny
     # Sends AMQ protocol header (also known as preamble).
     # @api private
     def send_preamble
-      @transport.send_raw(AMQ::Protocol::PREAMBLE)
+      @transport.write(AMQ::Protocol::PREAMBLE)
+      @logger.debug "Sent protocol preamble"
     end
 
 
@@ -763,22 +783,47 @@ module Bunny
       Authentication::CredentialsEncoder.for_session(self)
     end
 
-    # @api private
-    def reset_continuations
-      @continuations = if defined?(JRUBY_VERSION)
-                         Concurrent::LinkedContinuationQueue.new
-                       else
-                         Concurrent::ContinuationQueue.new
-                       end
+    if defined?(JRUBY_VERSION)
+      # @api private
+      def reset_continuations
+        @continuations = Concurrent::LinkedContinuationQueue.new
+      end
+    else
+      # @api private
+      def reset_continuations
+        @continuations = Concurrent::ContinuationQueue.new
+      end
     end
 
     # @api private
     def wait_on_continuations
       unless @threaded
-        event_loop.run_once until @continuations.length > 0
+        reader_loop.run_once until @continuations.length > 0
       end
 
-      @continuations.pop
+      @continuations.poll(@continuation_timeout)
+    end
+
+    # @api private
+    def init_logger(level)
+      @logger          = ::Logger.new(@logfile)
+      @logger.level    = normalize_log_level(level)
+      @logger.progname = self.to_s
+
+      @logger
+    end
+
+    # @api private
+    def normalize_log_level(level)
+      case level
+      when :debug, Logger::DEBUG, "debug" then Logger::DEBUG
+      when :info,  Logger::INFO,  "info"  then Logger::INFO
+      when :warn,  Logger::WARN,  "warn"  then Logger::WARN
+      when :error, Logger::ERROR, "error" then Logger::ERROR
+      when :fatal, Logger::FATAL, "fatal" then Logger::FATAL
+      else
+        Logger::WARN
+      end
     end
   end # Session