puma 3.8.2 → 4.0.0

data/lib/puma/events.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/const'
 require "puma/null_io"
 require 'stringio'
@@ -91,8 +93,7 @@ module Puma
     # parsing exception.
     #
     def parse_error(server, env, error)
-      @stderr.puts "#{Time.now}: HTTP parse error, malformed request (#{env[HTTP_X_FORWARDED_FOR] || env[REMOTE_ADDR]}): #{error.inspect}"
-      @stderr.puts "#{Time.now}: ENV: #{env.inspect}\n---\n"
+      @stderr.puts "#{Time.now}: HTTP parse error, malformed request (#{env[HTTP_X_FORWARDED_FOR] || env[REMOTE_ADDR]}): #{error.inspect}\n---\n"
     end
 
     # An SSL error has occurred.

data/lib/puma/io_buffer.rb

@@ -1,7 +1,4 @@
-require 'puma/detect'
+# frozen_string_literal: true
 
-if Puma.jruby?
-  require 'puma/java_io_buffer'
-else
-  require 'puma/puma_http11'
-end
+require 'puma/detect'
+require 'puma/puma_http11'

data/lib/puma/jruby_restart.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'ffi'
 
 module Puma
@@ -80,4 +82,3 @@ module Puma
     end
   end
 end
-

data/lib/puma/launcher.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puma/events'
 require 'puma/detect'
 
@@ -40,7 +42,7 @@ module Puma
     #       [200, {}, ["hello world"]]
     #     end
     #   end
-    #   Puma::Launcher.new(conf, argv: Puma::Events.stdio).run
+    #   Puma::Launcher.new(conf, events: Puma::Events.stdio).run
     def initialize(conf, launcher_args={})
       @runner        = nil
       @events        = launcher_args[:events] || Events::DEFAULT
@@ -63,8 +65,8 @@ module Puma
 
       generate_restart_data
 
-      if clustered? && (Puma.jruby? || Puma.windows?)
-        unsupported 'worker mode not supported on JRuby or Windows'
+      if clustered? && !Process.respond_to?(:fork)
+        unsupported "worker mode not supported on #{RUBY_ENGINE} on this platform"
       end
 
       if @options[:daemon] && Puma.windows?
@@ -86,6 +88,7 @@ module Puma
       else
         @runner = Single.new(self, @events)
       end
+      Puma.stats_object = @runner
 
       @status = :run
     end
@@ -163,6 +166,17 @@ module Puma
 
     # Run the server. This blocks until the server is stopped
     def run
+      previous_env =
+        if defined?(Bundler)
+          env = Bundler::ORIGINAL_ENV.dup
+          # add -rbundler/setup so we load from Gemfile when restarting
+          bundle = "-rbundler/setup"
+          env["RUBYOPT"] = [env["RUBYOPT"], bundle].join(" ").lstrip unless env["RUBYOPT"].to_s.include?(bundle)
+          env
+        else
+          ENV.to_h
+        end
+
       @config.clamp
 
       @config.plugins.fire_starts self
@@ -178,6 +192,7 @@ module Puma
         graceful_stop
       when :restart
         log "* Restarting..."
+        ENV.replace(previous_env)
         @runner.before_restart
         restart!
       when :exit
@@ -199,6 +214,15 @@ module Puma
       end
     end
 
+    def close_binder_listeners
+      @binder.listeners.each do |l, io|
+        io.close
+        uri = URI.parse(l)
+        next unless uri.scheme == 'unix'
+        File.unlink("#{uri.host}#{uri.path}")
+      end
+    end
+
     private
 
     def reload_worker_directory
@@ -222,8 +246,8 @@ module Puma
       else
         redirects = {:close_others => true}
         @binder.listeners.each_with_index do |(l, io), i|
-        ENV["PUMA_INHERIT_#{i}"] = "#{io.to_i}:#{l}"
-        redirects[io.to_i] = io.to_i
+          ENV["PUMA_INHERIT_#{i}"] = "#{io.to_i}:#{l}"
+          redirects[io.to_i] = io.to_i
         end
 
         argv = restart_args
@@ -286,8 +310,8 @@ module Puma
     end
 
     def title
-      buffer = "puma #{Puma::Const::VERSION} (#{@options[:binds].join(',')})"
-      buffer << " [#{@options[:tag]}]" if @options[:tag] && !@options[:tag].empty?
+      buffer  = "puma #{Puma::Const::VERSION} (#{@options[:binds].join(',')})"
+      buffer += " [#{@options[:tag]}]" if @options[:tag] && !@options[:tag].empty?
       buffer
     end
 
@@ -304,16 +328,6 @@ module Puma
       @options[:prune_bundler] && clustered? && !@options[:preload_app]
     end
 
-    def close_binder_listeners
-      @binder.listeners.each do |l, io|
-        io.close
-        uri = URI.parse(l)
-        next unless uri.scheme == 'unix'
-        File.unlink("#{uri.host}#{uri.path}")
-      end
-    end
-
-
     def generate_restart_data
       if dir = @options[:directory]
         @restart_dir = dir
@@ -337,8 +351,6 @@ module Puma
 
       @restart_dir ||= Dir.pwd
 
-      require 'rubygems'
-
       # if $0 is a file in the current directory, then restart
       # it the same, otherwise add -S on there because it was
       # picked up in PATH.
@@ -349,9 +361,10 @@ module Puma
         arg0 = [Gem.ruby, "-S", $0]
       end
 
-      # Detect and reinject -Ilib from the command line
+      # Detect and reinject -Ilib from the command line, used for testing without bundler
+      # cruby has an expanded path, jruby has just "lib"
       lib = File.expand_path "lib"
-      arg0[1,0] = ["-I", lib] if $:[0] == lib
+      arg0[1,0] = ["-I", lib] if [lib, "lib"].include?($LOAD_PATH[0])
 
       if defined? Puma::WILD_ARGS
         @restart_argv = arg0 + Puma::WILD_ARGS + @original_argv
@@ -381,12 +394,28 @@ module Puma
 
       begin
         Signal.trap "SIGTERM" do
-          stop
+          graceful_stop
+
+          raise(SignalException, "SIGTERM") if @options[:raise_exception_on_sigterm]
         end
       rescue Exception
         log "*** SIGTERM not implemented, signal based gracefully stopping unavailable!"
       end
 
+      begin
+        Signal.trap "SIGINT" do
+          if Puma.jruby?
+            @status = :exit
+            graceful_stop
+            exit
+          end
+
+          stop
+        end
+      rescue Exception
+        log "*** SIGINT not implemented, signal based gracefully stopping unavailable!"
+      end
+
       begin
         Signal.trap "SIGHUP" do
           if @runner.redirected_io?
@@ -398,14 +427,6 @@ module Puma
       rescue Exception
         log "*** SIGHUP not implemented, signal based logs reopening unavailable!"
       end
-
-      if Puma.jruby?
-        Signal.trap("INT") do
-          @status = :exit
-          graceful_stop
-          exit
-        end
-      end
     end
   end
 end

data/lib/puma/minissl.rb

@@ -1,3 +1,10 @@
+# frozen_string_literal: true
+
+begin
+  require 'io/wait'
+rescue LoadError
+end
+
 module Puma
   module MiniSSL
     class Socket
@@ -11,6 +18,10 @@ module Puma
         @socket
       end
 
+      def closed?
+        @socket.closed?
+      end
+
       def readpartial(size)
         while true
           output = @engine.read
@@ -36,12 +47,29 @@ module Puma
         output
       end
 
-      def read_nonblock(size)
+      def read_nonblock(size, *_)
+        # *_ is to deal with keyword args that were added
+        # at some point (and being used in the wild)
         while true
           output = engine_read_all
           return output if output
 
-          data = @socket.read_nonblock(size)
+          begin
+            data = @socket.read_nonblock(size, exception: false)
+            if data == :wait_readable || data == :wait_writable
+              if @socket.to_io.respond_to?(data)
+                @socket.to_io.__send__(data)
+              elsif data == :wait_readable
+                IO.select([@socket.to_io])
+              else
+                IO.select(nil, [@socket.to_io])
+              end
+            elsif !data
+              return nil
+            else
+              break
+            end
+          end while true
 
           @engine.inject(data)
           output = engine_read_all
@@ -55,6 +83,8 @@ module Puma
       end
 
       def write(data)
+        return 0 if data.empty?
+
         need = data.bytesize
 
         while true
@@ -77,39 +107,46 @@ module Puma
       alias_method :syswrite, :write
       alias_method :<<, :write
 
+      # This is a temporary fix to deal with websockets code using
+      # write_nonblock. The problem with implementing it properly
+      # is that it means we'd have to have the ability to rewind
+      # an engine because after we write+extract, the socket
+      # write_nonblock call might raise an exception and later
+      # code would pass the same data in, but the engine would think
+      # it had already written the data in. So for the time being
+      # (and since write blocking is quite rare), go ahead and actually
+      # block in write_nonblock.
+      def write_nonblock(data, *_)
+        write data
+      end
+
       def flush
         @socket.flush
       end
 
-      def close
-        begin
-          # Try to setup (so that we can then close them) any
-          # partially initialized sockets.
-          while @engine.init?
-            # Don't let this socket hold this loop forever.
-            # If it can't send more packets within 1s, then
-            # give up.
-            return unless IO.select([@socket], nil, nil, 1)
-            begin
-              read_nonblock(1024)
-            rescue Errno::EAGAIN
-            end
-          end
-
-          done = @engine.shutdown
-
-          while true
-            enc = @engine.extract
-            @socket.write enc
-
-            notify = @socket.sysread(1024)
+      def read_and_drop(timeout = 1)
+        return :timeout unless IO.select([@socket], nil, nil, timeout)
+        return :eof unless read_nonblock(1024)
+        :drop
+      rescue Errno::EAGAIN
+        # do nothing
+        :eagain
+      end
 
-            @engine.inject notify
-            done = @engine.shutdown
+      def should_drop_bytes?
+        @engine.init? || !@engine.shutdown
+      end
 
-            break if done
+      def close
+        begin
+          # Read any drop any partially initialized sockets and any received bytes during shutdown.
+          # Don't let this socket hold this loop forever.
+          # If it can't send more packets within 1s, then give up.
+          while should_drop_bytes?
+            return if [:timeout, :eof].include?(read_and_drop(1))
           end
         rescue IOError, SystemCallError
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
           # nothing
         ensure
           @socket.close
@@ -140,11 +177,17 @@ module Puma
 
     class Context
       attr_accessor :verify_mode
+      attr_reader :no_tlsv1
+
+      def initialize
+        @no_tlsv1 = false
+      end
 
       if defined?(JRUBY_VERSION)
         # jruby-specific Context properties: java uses a keystore and password pair rather than a cert/key pair
         attr_reader :keystore
         attr_accessor :keystore_pass
+        attr_accessor :ssl_cipher_list
 
         def keystore=(keystore)
           raise ArgumentError, "No such keystore file '#{keystore}'" unless File.exist? keystore
@@ -160,6 +203,7 @@ module Puma
         attr_reader :key
         attr_reader :cert
         attr_reader :ca
+        attr_accessor :ssl_cipher_filter
 
         def key=(key)
           raise ArgumentError, "No such key file '#{key}'" unless File.exist? key
@@ -176,11 +220,18 @@ module Puma
           @ca = ca
         end
 
+
         def check
           raise "Key not configured" unless @key
           raise "Cert not configured" unless @cert
         end
       end
+
+      def no_tlsv1=(tlsv1)
+        raise ArgumentError, "Invalid value of no_tlsv1" unless ['true', 'false', true, false].include?(tlsv1)
+        @no_tlsv1 = tlsv1
+      end
+
     end
 
     VERIFY_NONE = 0
@@ -214,7 +265,7 @@ module Puma
       end
 
       def close
-        @socket.close
+        @socket.close unless @socket.closed?       # closed? call is for Windows
       end
     end
   end

data/lib/puma/null_io.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   # Provides an IO-like object that always appears to contain no data.
   # Used as the value for rack.input when the request has no body.

data/lib/puma/plugin.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Puma
   class UnknownPlugin < RuntimeError; end
 

data/lib/puma/plugin/tmp_restart.rb

@@ -32,4 +32,3 @@ Puma::Plugin.create do
     end
   end
 end
-

data/lib/puma/rack/builder.rb

@@ -110,7 +110,8 @@ module Puma::Rack
 
           has_options = false
           server.valid_options.each do |name, description|
-            next if name.to_s.match(/^(Host|Port)[^a-zA-Z]/) # ignore handler's host and port options, we do our own.
+            next if name.to_s =~ /^(Host|Port)[^a-zA-Z]/ # ignore handler's host and port options, we do our own.
+
             info << "  -O %-21s %s" % [name, description]
             has_options = true
           end

data/lib/puma/reactor.rb

@@ -1,57 +1,201 @@
+# frozen_string_literal: true
+
 require 'puma/util'
 require 'puma/minissl'
 
+require 'nio'
+
 module Puma
+  # Internal Docs, Not a public interface.
+  #
+  # The Reactor object is responsible for ensuring that a request has been
+  # completely received before it starts to be processed. This may be known as read buffering.
+  # If read buffering is not done, and no other read buffering is performed (such as by an application server
+  # such as nginx) then the application would be subject to a slow client attack.
+  #
+  # Each Puma "worker" process has its own Reactor. For example if you start puma with `$ puma -w 5` then
+  # it will have 5 workers and each worker will have it's own reactor.
+  #
+  # For a graphical representation of how the reactor works see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline).
+  #
+  # ## Reactor Flow
+  #
+  # A connection comes into a `Puma::Server` instance, it is then passed to a `Puma::Reactor` instance,
+  # which stores it in an array and waits for any of the connections to be ready for reading.
+  #
+  # The waiting/wake up is performed with nio4r, which will use the apropriate backend (libev, Java NIO or
+  # just plain IO#select). The call to `NIO::Selector#select` will "wake up" and
+  # return the references to any objects that caused it to "wake". The reactor
+  # then loops through each of these request objects, and sees if they're complete. If they
+  # have a full header and body then the reactor passes the request to a thread pool.
+  # Once in a thread pool, a "worker thread" can run the the application's Ruby code against the request.
+  #
+  # If the request is not complete, then it stays in the array, and the next time any
+  # data is written to that socket reference, then the loop is woken up and it is checked for completeness again.
+  #
+  # A detailed example is given in the docs for `run_internal` which is where the bulk
+  # of this logic lives.
   class Reactor
     DefaultSleepFor = 5
 
+    # Creates an instance of Puma::Reactor
+    #
+    # The `server` argument is an instance of `Puma::Server`
+    # that is used to write a response for "low level errors"
+    # when there is an exception inside of the reactor.
+    #
+    # The `app_pool` is an instance of `Puma::ThreadPool`.
+    # Once a request is fully formed (header and body are received)
+    # it will be passed to the `app_pool`.
     def initialize(server, app_pool)
       @server = server
       @events = server.events
       @app_pool = app_pool
 
+      @selector = NIO::Selector.new
+
       @mutex = Mutex.new
+
+      # Read / Write pipes to wake up internal while loop
       @ready, @trigger = Puma::Util.pipe
       @input = []
       @sleep_for = DefaultSleepFor
       @timeouts = []
 
-      @sockets = [@ready]
+      mon = @selector.register(@ready, :r)
+      mon.value = @ready
+
+      @monitors = [mon]
     end
 
     private
 
+    # Until a request is added via the `add` method this method will internally
+    # loop, waiting on the `sockets` array objects. The only object in this
+    # array at first is the `@ready` IO object, which is the read end of a pipe
+    # connected to `@trigger` object. When `@trigger` is written to, then the loop
+    # will break on `NIO::Selector#select` and return an array.
+    #
+    # ## When a request is added:
+    #
+    # When the `add` method is called, an instance of `Puma::Client` is added to the `@input` array.
+    # Next the `@ready` pipe is "woken" by writing a string of `"*"` to `@trigger`.
+    #
+    # When that happens, the internal loop stops blocking at `NIO::Selector#select` and returns a reference
+    # to whatever "woke" it up. On the very first loop, the only thing in `sockets` is `@ready`.
+    # When `@trigger` is written-to, the loop "wakes" and the `ready`
+    # variable returns an array of arrays that looks like `[[#<IO:fd 10>], [], []]` where the
+    # first IO object is the `@ready` object. This first array `[#<IO:fd 10>]`
+    # is saved as a `reads` variable.
+    #
+    # The `reads` variable is iterated through. In the case that the object
+    # is the same as the `@ready` input pipe, then we know that there was a `trigger` event.
+    #
+    # If there was a trigger event, then one byte of `@ready` is read into memory. In the case of the first request,
+    # the reactor sees that it's a `"*"` value and the reactor adds the contents of `@input` into the `sockets` array.
+    # The while then loop continues to iterate again, but now the `sockets` array contains a `Puma::Client` instance in addition
+    # to the `@ready` IO object. For example: `[#<IO:fd 10>, #<Puma::Client:0x3fdc1103bee8 @ready=false>]`.
+    #
+    # Since the `Puma::Client` in this example has data that has not been read yet,
+    # the `NIO::Selector#select` is immediately able to "wake" and read from the `Puma::Client`. At this point the
+    # `ready` output looks like this: `[[#<Puma::Client:0x3fdc1103bee8 @ready=false>], [], []]`.
+    #
+    # Each element in the first entry is iterated over. The `Puma::Client` object is not
+    # the `@ready` pipe, so the reactor checks to see if it has the full header and body with
+    # the `Puma::Client#try_to_finish` method. If the full request has been sent,
+    # then the request is passed off to the `@app_pool` thread pool so that a "worker thread"
+    # can pick up the request and begin to execute application logic. This is done
+    # via `@app_pool << c`. The `Puma::Client` is then removed from the `sockets` array.
+    #
+    # If the request body is not present then nothing will happen, and the loop will iterate
+    # again. When the client sends more data to the socket the `Puma::Client` object will
+    # wake up the `NIO::Selector#select` and it can again be checked to see if it's ready to be
+    # passed to the thread pool.
+    #
+    # ## Time Out Case
+    #
+    # In addition to being woken via a write to one of the sockets the `NIO::Selector#select` will
+    # periodically "time out" of the sleep. One of the functions of this is to check for
+    # any requests that have "timed out". At the end of the loop it's checked to see if
+    # the first element in the `@timeout` array has exceed its allowed time. If so,
+    # the client object is removed from the timeout array, a 408 response is written.
+    # Then its connection is closed, and the object is removed from the `sockets` array
+    # that watches for new data.
+    #
+    # This behavior loops until all the objects that have timed out have been removed.
+    #
+    # Once all the timeouts have been processed, the next duration of the `NIO::Selector#select` sleep
+    # will be set to be equal to the amount of time it will take for the next timeout to occur.
+    # This calculation happens in `calculate_sleep`.
     def run_internal
-      sockets = @sockets
+      monitors = @monitors
+      selector = @selector
 
       while true
         begin
-          ready = IO.select sockets, nil, nil, @sleep_for
+          ready = selector.select @sleep_for
         rescue IOError => e
-          if sockets.any? { |socket| socket.closed? }
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+          if monitors.any? { |mon| mon.value.closed? }
             STDERR.puts "Error in select: #{e.message} (#{e.class})"
             STDERR.puts e.backtrace
-            sockets = sockets.reject { |socket| socket.closed? }
+
+            monitors.reject! do |mon|
+              if mon.value.closed?
+                selector.deregister mon.value
+                true
+              end
+            end
+
             retry
           else
             raise
           end
         end
 
-        if ready and reads = ready[0]
-          reads.each do |c|
-            if c == @ready
+        if ready
+          ready.each do |mon|
+            if mon.value == @ready
               @mutex.synchronize do
                 case @ready.read(1)
                 when "*"
-                  sockets += @input
+                  @input.each do |c|
+                    mon = nil
+                    begin
+                      begin
+                        mon = selector.register(c, :r)
+                      rescue ArgumentError
+                        # There is a bug where we seem to be registering an already registered
+                        # client. This code deals with this situation but I wish we didn't have to.
+                        monitors.delete_if { |submon| submon.value.to_io == c.to_io }
+                        selector.deregister(c)
+                        mon = selector.register(c, :r)
+                      end
+                    rescue IOError
+                      # Means that the io is closed, so we should ignore this request
+                      # entirely
+                    else
+                      mon.value = c
+                      @timeouts << mon if c.timeout_at
+                      monitors << mon
+                    end
+                  end
                   @input.clear
+
+                  @timeouts.sort! { |a,b| a.value.timeout_at <=> b.value.timeout_at }
+                  calculate_sleep
                 when "c"
-                  sockets.delete_if do |s|
-                    if s == @ready
+                  monitors.reject! do |submon|
+                    if submon.value == @ready
                       false
                     else
-                      s.close
+                      submon.value.close
+                      begin
+                        selector.deregister submon.value
+                      rescue IOError
+                        # nio4r on jruby seems to throw an IOError here if the IO is closed, so
+                        # we need to swallow it.
+                      end
                       true
                     end
                   end
@@ -60,19 +204,21 @@ module Puma
                 end
               end
             else
+              c = mon.value
+
               # We have to be sure to remove it from the timeout
               # list or we'll accidentally close the socket when
               # it's in use!
               if c.timeout_at
                 @mutex.synchronize do
-                  @timeouts.delete c
+                  @timeouts.delete mon
                 end
               end
 
               begin
                 if c.try_to_finish
                   @app_pool << c
-                  sockets.delete c
+                  clear_monitor mon
                 end
 
               # Don't report these to the lowlevel_error handler, otherwise
@@ -82,18 +228,23 @@ module Puma
                 c.write_500
                 c.close
 
-                sockets.delete c
+                clear_monitor mon
 
               # SSL handshake failure
               rescue MiniSSL::SSLError => e
                 @server.lowlevel_error(e, c.env)
 
                 ssl_socket = c.io
-                addr = ssl_socket.peeraddr.last
+                begin
+                  addr = ssl_socket.peeraddr.last
+                rescue IOError
+                  addr = "<unknown>"
+                end
+
                 cert = ssl_socket.peercert
 
                 c.close
-                sockets.delete c
+                clear_monitor mon
 
                 @events.ssl_error @server, addr, cert, e
 
@@ -104,7 +255,7 @@ module Puma
                 c.write_400
                 c.close
 
-                sockets.delete c
+                clear_monitor mon
 
                 @events.parse_error @server, c.env, e
               rescue StandardError => e
@@ -113,7 +264,7 @@ module Puma
                 c.write_500
                 c.close
 
-                sockets.delete c
+                clear_monitor mon
               end
             end
           end
@@ -123,11 +274,13 @@ module Puma
           @mutex.synchronize do
             now = Time.now
 
-            while @timeouts.first.timeout_at < now
-              c = @timeouts.shift
+            while @timeouts.first.value.timeout_at < now
+              mon = @timeouts.shift
+              c = mon.value
               c.write_408 if c.in_data_phase
               c.close
-              sockets.delete c
+
+              clear_monitor mon
 
               break if @timeouts.empty?
             end
@@ -138,6 +291,11 @@ module Puma
       end
     end
 
+    def clear_monitor(mon)
+      @selector.deregister mon.value
+      @monitors.delete mon
+    end
+
     public
 
     def run
@@ -162,11 +320,21 @@ module Puma
       end
     end
 
+    # The `calculate_sleep` sets the value that the `NIO::Selector#select` will
+    # sleep for in the main reactor loop when no sockets are being written to.
+    #
+    # The values kept in `@timeouts` are sorted so that the first timeout
+    # comes first in the array. When there are no timeouts the default timeout is used.
+    #
+    # Otherwise a sleep value is set that is the same as the amount of time it
+    # would take for the first element to time out.
+    #
+    # If that value is in the past, then a sleep value of zero is used.
     def calculate_sleep
       if @timeouts.empty?
         @sleep_for = DefaultSleepFor
       else
-        diff = @timeouts.first.timeout_at.to_f - Time.now.to_f
+        diff = @timeouts.first.value.timeout_at.to_f - Time.now.to_f
 
         if diff < 0.0
           @sleep_for = 0
@@ -176,17 +344,35 @@ module Puma
       end
     end
 
+    # This method adds a connection to the reactor
+    #
+    # Typically called by `Puma::Server` the value passed in
+    # is usually a `Puma::Client` object that responds like an IO
+    # object.
+    #
+    # The main body of the reactor loop is in `run_internal` and it
+    # will sleep on `NIO::Selector#select`. When a new connection is added to the
+    # reactor it cannot be added directly to the `sockets` array, because
+    # the `NIO::Selector#select` will not be watching for it yet.
+    #
+    # Instead what needs to happen is that `NIO::Selector#select` needs to be woken up,
+    # the contents of `@input` added to the `sockets` array, and then
+    # another call to `NIO::Selector#select` needs to happen. Since the `Puma::Client`
+    # object can be read immediately, it does not block, but instead returns
+    # right away.
+    #
+    # This behavior is accomplished by writing to `@trigger` which wakes up
+    # the `NIO::Selector#select` and then there is logic to detect the value of `*`,
+    # pull the contents from `@input` and add them to the sockets array.
+    #
+    # If the object passed in has a timeout value in `timeout_at` then
+    # it is added to a `@timeouts` array. This array is then re-arranged
+    # so that the first element to timeout will be at the front of the
+    # array. Then a value to sleep for is derived in the call to `calculate_sleep`
     def add(c)
       @mutex.synchronize do
         @input << c
         @trigger << "*"
-
-        if c.timeout_at
-          @timeouts << c
-          @timeouts.sort! { |a,b| a.timeout_at <=> b.timeout_at }
-
-          calculate_sleep
-        end
       end
     end
 
@@ -195,6 +381,7 @@ module Puma
       begin
         @trigger << "c"
       rescue IOError
+        Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
       end
     end
 
@@ -202,6 +389,7 @@ module Puma
       begin
         @trigger << "!"
       rescue IOError
+        Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
       end
 
       @thread.join