puma 3.11.4 → 4.2.0

data/lib/puma/reactor.rb

@@ -1,58 +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 appropriate 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
           Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
-          if sockets.any? { |socket| socket.closed? }
+          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
@@ -61,40 +204,47 @@ 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
               # will be flooding them with errors when persistent connections
               # are closed.
               rescue ConnectionError
-                c.write_500
+                c.write_error(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
 
@@ -102,19 +252,19 @@ module Puma
               rescue HttpParserError => e
                 @server.lowlevel_error(e, c.env)
 
-                c.write_400
+                c.write_error(400)
                 c.close
 
-                sockets.delete c
+                clear_monitor mon
 
                 @events.parse_error @server, c.env, e
               rescue StandardError => e
                 @server.lowlevel_error(e, c.env)
 
-                c.write_500
+                c.write_error(500)
                 c.close
 
-                sockets.delete c
+                clear_monitor mon
               end
             end
           end
@@ -124,11 +274,13 @@ module Puma
           @mutex.synchronize do
             now = Time.now
 
-            while @timeouts.first.timeout_at < now
-              c = @timeouts.shift
-              c.write_408 if c.in_data_phase
+            while @timeouts.first.value.timeout_at < now
+              mon = @timeouts.shift
+              c = mon.value
+              c.write_error(408) if c.in_data_phase
               c.close
-              sockets.delete c
+
+              clear_monitor mon
 
               break if @timeouts.empty?
             end
@@ -139,6 +291,11 @@ module Puma
       end
     end
 
+    def clear_monitor(mon)
+      @selector.deregister mon.value
+      @monitors.delete mon
+    end
+
     public
 
     def run
@@ -150,6 +307,7 @@ module Puma
 
     def run_in_thread
       @thread = Thread.new do
+        Puma.set_thread_name "reactor"
         begin
           run_internal
         rescue StandardError => e
@@ -163,11 +321,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
@@ -177,17 +345,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
 

data/lib/puma/runner.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 require 'puma/server'
 require 'puma/const'
 
 module Puma
+  # Generic class that is used by `Puma::Cluster` and `Puma::Single` to
+  # serve requests. This class spawns a new instance of `Puma::Server` via
+  # a call to `start_server`.
   class Runner
     def initialize(cli, events)
       @launcher = cli
@@ -9,6 +14,7 @@ module Puma
       @options = cli.options
       @app = nil
       @control = nil
+      @started_at = Time.now
     end
 
     def daemon?
@@ -19,6 +25,10 @@ module Puma
       @options[:environment] == "development"
     end
 
+    def test?
+      @options[:environment] == "test"
+    end
+
     def log(str)
       @events.log str
     end
@@ -43,12 +53,12 @@ module Puma
 
       uri = URI.parse str
 
-      app = Puma::App::Status.new @launcher
-
       if token = @options[:control_auth_token]
-        app.auth_token = token unless token.empty? or token == :none
+        token = nil if token.empty? || token == 'none'
       end
 
+      app = Puma::App::Status.new @launcher, token
+
       control = Puma::Server.new app, @launcher.events
       control.min_threads = 0
       control.max_threads = 1
@@ -165,7 +175,7 @@ module Puma
         server.early_hints = true
       end
 
-      unless development?
+      unless development? || test?
         server.leak_stack_on_error = false
       end
 

data/lib/puma/server.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 require 'stringio'
 
 require 'puma/thread_pool'
 require 'puma/const'
 require 'puma/events'
 require 'puma/null_io'
-require 'puma/compat'
 require 'puma/reactor'
 require 'puma/client'
 require 'puma/binder'
@@ -14,15 +15,20 @@ require 'puma/util'
 
 require 'puma/puma_http11'
 
-unless Puma.const_defined? "IOBuffer"
-  require 'puma/io_buffer'
-end
-
 require 'socket'
 
 module Puma
 
   # The HTTP Server itself. Serves out a single Rack app.
+  #
+  # This class is used by the `Puma::Single` and `Puma::Cluster` classes
+  # to generate one or more `Puma::Server` instances capable of handling requests.
+  # Each Puma process will contain one `Puma::Server` instance.
+  #
+  # The `Puma::Server` instance pulls requests from the socket, adds them to a
+  # `Puma::Reactor` where they get eventually passed to a `Puma::ThreadPool`.
+  #
+  # Each `Puma::Server` will have one reactor and one thread pool.
   class Server
 
     include Puma::Const
@@ -68,7 +74,6 @@ module Puma
       @first_data_timeout = options.fetch(:first_data_timeout, FIRST_DATA_TIMEOUT)
 
       @binder = Binder.new(events)
-      @own_binder = true
 
       @leak_stack_on_error = true
 
@@ -91,7 +96,6 @@ module Puma
 
     def inherit_binder(bind)
       @binder = bind
-      @own_binder = false
     end
 
     def tcp_mode!
@@ -159,6 +163,18 @@ module Puma
       @thread_pool and @thread_pool.spawned
     end
 
+
+    # This number represents the number of requests that
+    # the server is capable of taking right now.
+    #
+    # For example if the number is 5 then it means
+    # there are 5 threads sitting idle ready to take
+    # a request. If one request comes in, then the
+    # value would be 4 until it finishes processing.
+    def pool_capacity
+      @thread_pool and @thread_pool.pool_capacity
+    end
+
     # Lopez Mode == raw tcp apps
 
     def run_lopez_mode(background=true)
@@ -191,7 +207,10 @@ module Puma
       @events.fire :state, :running
 
       if background
-        @thread = Thread.new { handle_servers_lopez_mode }
+        @thread = Thread.new do
+          Puma.set_thread_name "server"
+          handle_servers_lopez_mode
+        end
         return @thread
       else
         handle_servers_lopez_mode
@@ -241,11 +260,17 @@ module Puma
         STDERR.puts "Exception handling servers: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
       ensure
-        @check.close
-        @notify.close
+        begin
+          @check.close
+        rescue
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        end
 
-        if @status != :restart and @own_binder
-          @binder.close
+        # Prevent can't modify frozen IOError (RuntimeError)
+        begin
+          @notify.close
+        rescue IOError
+          # no biggy
         end
       end
 
@@ -295,7 +320,7 @@ module Puma
 
           @events.ssl_error self, addr, cert, e
         rescue HttpParserError => e
-          client.write_400
+          client.write_error(400)
           client.close
 
           @events.parse_error self, client.env, e
@@ -329,7 +354,10 @@ module Puma
       @events.fire :state, :running
 
       if background
-        @thread = Thread.new { handle_servers }
+        @thread = Thread.new do
+          Puma.set_thread_name "server"
+          handle_servers
+        end
         return @thread
       else
         handle_servers
@@ -370,7 +398,10 @@ module Puma
                     end
 
                     pool << client
-                    pool.wait_until_not_full
+                    busy_threads = pool.wait_until_not_full
+                    if busy_threads == 0
+                      @options[:out_of_band].each(&:call) if @options[:out_of_band]
+                    end
                   end
                 rescue SystemCallError
                   # nothing
@@ -402,10 +433,6 @@ module Puma
       ensure
         @check.close
         @notify.close
-
-        if @status != :restart and @own_binder
-          @binder.close
-        end
       end
 
       @events.fire :state, :done
@@ -484,7 +511,7 @@ module Puma
       rescue HttpParserError => e
         lowlevel_error(e, client.env)
 
-        client.write_400
+        client.write_error(400)
 
         @events.parse_error self, client.env, e
 
@@ -492,7 +519,7 @@ module Puma
       rescue StandardError => e
         lowlevel_error(e, client.env)
 
-        client.write_500
+        client.write_error(500)
 
         @events.unknown_error self, e, "Read"
 
@@ -567,19 +594,26 @@ module Puma
     end
 
     def default_server_port(env)
-      return PORT_443 if env[HTTPS_KEY] == 'on' || env[HTTPS_KEY] == 'https'
-      env['HTTP_X_FORWARDED_PROTO'] == 'https' ? PORT_443 : PORT_80
+      if ['on', HTTPS].include?(env[HTTPS_KEY]) || env[HTTP_X_FORWARDED_PROTO].to_s[0...5] == HTTPS || env[HTTP_X_FORWARDED_SCHEME] == HTTPS || env[HTTP_X_FORWARDED_SSL] == "on"
+        PORT_443
+      else
+        PORT_80
+      end
     end
 
-    # Given the request +env+ from +client+ and a partial request body
-    # in +body+, finish reading the body if there is one and invoke
-    # the rack app. Then construct the response and write it back to
-    # +client+
+    # Takes the request +req+, invokes the Rack application to construct
+    # the response and writes it back to +req.io+.
+    #
+    # The second parameter +lines+ is a IO-like object unique to this thread.
+    # This is normally an instance of Puma::IOBuffer.
     #
-    # +cl+ is the previously fetched Content-Length header if there
-    # was one. This is an optimization to keep from having to look
-    # it up again.
+    # It'll return +false+ when the connection is closed, this doesn't mean
+    # that the response wasn't successful.
     #
+    # It'll return +:async+ if the connection remains open but will be handled
+    # elsewhere, i.e. the connection has been hijacked by the Rack application.
+    #
+    # Finally, it'll return +true+ on keep-alive connections.
     def handle_request(req, lines)
       env = req.env
       client = req.io
@@ -602,23 +636,27 @@ module Puma
       head = env[REQUEST_METHOD] == HEAD
 
       env[RACK_INPUT] = body
-      env[RACK_URL_SCHEME] =  env[HTTPS_KEY] ? HTTPS : HTTP
+      env[RACK_URL_SCHEME] = default_server_port(env) == PORT_443 ? HTTPS : HTTP
 
       if @early_hints
         env[EARLY_HINTS] = lambda { |headers|
-          fast_write client, "HTTP/1.1 103 Early Hints\r\n".freeze
+          begin
+            fast_write client, "HTTP/1.1 103 Early Hints\r\n".freeze
 
-          headers.each_pair do |k, vs|
-            if vs.respond_to?(:to_s) && !vs.to_s.empty?
-              vs.to_s.split(NEWLINE).each do |v|
-                fast_write client, "#{k}: #{v}\r\n"
+            headers.each_pair do |k, vs|
+              if vs.respond_to?(:to_s) && !vs.to_s.empty?
+                vs.to_s.split(NEWLINE).each do |v|
+                  fast_write client, "#{k}: #{v}\r\n"
+                end
+              else
+                fast_write client, "#{k}: #{vs}\r\n"
               end
-            else
-              fast_write client, "#{k}: #{vs}\r\n"
             end
-          end
 
-          fast_write client, "\r\n".freeze
+            fast_write client, "\r\n".freeze
+          rescue ConnectionError
+            # noop, if we lost the socket we just won't send the early hints
+          end
         }
       end
 
@@ -914,6 +952,10 @@ module Puma
         @events.debug "Drained #{count} additional connections."
       end
 
+      if @status != :restart
+        @binder.close
+      end
+
       if @thread_pool
         if timeout = @options[:force_shutdown_after]
           @thread_pool.shutdown timeout.to_i