puma 3.5.0 → 3.12.0

data/lib/puma/plugin.rb

@@ -28,6 +28,7 @@ module Puma
   class PluginRegistry
     def initialize
       @plugins = {}
+      @background = []
     end
 
     def register(name, cls)
@@ -53,6 +54,16 @@ module Puma
 
       raise UnknownPlugin, "file failed to register a plugin"
     end
+
+    def add_background(blk)
+      @background << blk
+    end
+
+    def fire_background
+      @background.each do |b|
+        Thread.new(&b)
+      end
+    end
   end
 
   Plugins = PluginRegistry.new
@@ -93,7 +104,7 @@ module Puma
     end
 
     def in_background(&blk)
-      Thread.new(&blk)
+      Plugins.add_background blk
     end
 
     def workers_supported?

data/lib/puma/plugin/tmp_restart.rb

@@ -8,7 +8,7 @@ Puma::Plugin.create do
 
     # If we can't write to the path, then just don't bother with this plugin
     begin
-      File.write path, ""
+      File.write(path, "") unless File.exist?(path)
       orig = File.stat(path).mtime
     rescue SystemCallError
       return
@@ -32,4 +32,3 @@ Puma::Plugin.create do
     end
   end
 end
-

data/lib/puma/rack/builder.rb

@@ -1,3 +1,6 @@
+module Puma
+end
+
 module Puma::Rack
   class Options
     def parse!(args)

data/lib/puma/rack/urlmap.rb

@@ -43,15 +43,17 @@ module Puma::Rack
     def call(env)
       path = env['PATH_INFO']
       script_name = env['SCRIPT_NAME']
-      hHost = env['HTTP_HOST']
-      sName = env['SERVER_NAME']
-      sPort = env['SERVER_PORT']
+      http_host = env['HTTP_HOST']
+      server_name = env['SERVER_NAME']
+      server_port = env['SERVER_PORT']
+
+      is_same_server = casecmp?(http_host, server_name) ||
+                    casecmp?(http_host, "#{server_name}:#{server_port}")
 
       @mapping.each do |host, location, match, app|
-        unless casecmp?(hHost, host) \
-            || casecmp?(sName, host) \
-            || (!host && (casecmp?(hHost, sName) ||
-                          casecmp?(hHost, sName+':'+sPort)))
+        unless casecmp?(http_host, host) \
+            || casecmp?(server_name, host) \
+            || (!host && is_same_server)
           next
         end
 
@@ -87,4 +89,3 @@ module Puma::Rack
     end
   end
 end
-

data/lib/puma/reactor.rb

@@ -2,15 +2,54 @@ require 'puma/util'
 require 'puma/minissl'
 
 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 request comes into a `Puma::Server` instance, it is then passed to a `Puma::Reactor` instance.
+  # The reactor stores the request in an array and calls `IO.select` on the array in a loop.
+  #
+  # When the request is written to by the client then the `IO.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`
+    # this 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
 
       @mutex = Mutex.new
+
+      # Read / Write pipes to wake up internal while loop
       @ready, @trigger = Puma::Util.pipe
       @input = []
       @sleep_for = DefaultSleepFor
@@ -21,6 +60,64 @@ module Puma
 
     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 `IO.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 `IO.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 `IO.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 fully 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 `IO.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 `IO.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 it's allowed time. If so,
+    # the client object is removed from the timeout aray, a 408 response is written.
+    # Then it's 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 `IO.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
 
@@ -28,6 +125,7 @@ module Puma
         begin
           ready = IO.select sockets, nil, nil, @sleep_for
         rescue IOError => e
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
           if sockets.any? { |socket| socket.closed? }
             STDERR.puts "Error in select: #{e.message} (#{e.class})"
             STDERR.puts e.backtrace
@@ -162,6 +260,16 @@ module Puma
       end
     end
 
+    # The `calculate_sleep` sets the value that the `IO.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
@@ -176,6 +284,31 @@ 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 `IO.select`. When a new connection is added to the
+    # reactor it cannot be added directly to the `sockets` aray, because
+    # the `IO.select` will not be watching for it yet.
+    #
+    # Instead what needs to happen is that `IO.select` needs to be woken up,
+    # the contents of `@input` added to the `sockets` array, and then
+    # another call to `IO.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 `IO.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
@@ -195,6 +328,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 +336,7 @@ module Puma
       begin
         @trigger << "!"
       rescue IOError
+        Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
       end
 
       @thread.join

data/lib/puma/runner.rb

@@ -1,4 +1,10 @@
+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
@@ -16,6 +22,10 @@ module Puma
       @options[:environment] == "development"
     end
 
+    def test?
+      @options[:environment] == "test"
+    end
+
     def log(str)
       @events.log str
     end
@@ -94,18 +104,30 @@ module Puma
       end
     end
 
+    def redirected_io?
+      @options[:redirect_stdout] || @options[:redirect_stderr]
+    end
+
     def redirect_io
       stdout = @options[:redirect_stdout]
       stderr = @options[:redirect_stderr]
       append = @options[:redirect_append]
 
       if stdout
+        unless Dir.exist?(File.dirname(stdout))
+          raise "Cannot redirect STDOUT to #{stdout}"
+        end
+
         STDOUT.reopen stdout, (append ? "a" : "w")
         STDOUT.sync = true
         STDOUT.puts "=== puma startup: #{Time.now} ==="
       end
 
       if stderr
+        unless Dir.exist?(File.dirname(stderr))
+          raise "Cannot redirect STDERR to #{stderr}"
+        end
+
         STDERR.reopen stderr, (append ? "a" : "w")
         STDERR.sync = true
         STDERR.puts "=== puma startup: #{Time.now} ==="
@@ -146,7 +168,11 @@ module Puma
         server.tcp_mode!
       end
 
-      unless development?
+      if @options[:early_hints]
+        server.early_hints = true
+      end
+
+      unless development? || test?
         server.leak_stack_on_error = false
       end
 

data/lib/puma/server.rb

@@ -23,6 +23,15 @@ 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` instacne.
+  #
+  # 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
@@ -57,19 +66,19 @@ module Puma
 
       @min_threads = 0
       @max_threads = 16
-      @auto_trim_time = 1
+      @auto_trim_time = 30
       @reaping_time = 1
 
       @thread = nil
       @thread_pool = nil
+      @early_hints = nil
 
-      @persistent_timeout = options[:persistent_timeout]
+      @persistent_timeout = options.fetch(:persistent_timeout, PERSISTENT_TIMEOUT)
+      @first_data_timeout = options.fetch(:first_data_timeout, FIRST_DATA_TIMEOUT)
 
       @binder = Binder.new(events)
       @own_binder = true
 
-      @first_data_timeout = FIRST_DATA_TIMEOUT
-
       @leak_stack_on_error = true
 
       @options = options
@@ -78,9 +87,11 @@ module Puma
       ENV['RACK_ENV'] ||= "development"
 
       @mode = :http
+
+      @precheck_closing = true
     end
 
-    attr_accessor :binder, :leak_stack_on_error
+    attr_accessor :binder, :leak_stack_on_error, :early_hints
 
     forward :add_tcp_listener,  :@binder
     forward :add_ssl_listener,  :@binder
@@ -100,6 +111,8 @@ module Puma
     # packetizes our stream. This improves both latency and throughput.
     #
     if RUBY_PLATFORM =~ /linux/
+      UNPACK_TCP_STATE_FROM_TCP_INFO = "C".freeze
+
       # 6 == Socket::IPPROTO_TCP
       # 3 == TCP_CORK
       # 1/0 == turn on/off
@@ -107,6 +120,7 @@ module Puma
         begin
           socket.setsockopt(6, 3, 1) if socket.kind_of? TCPSocket
         rescue IOError, SystemCallError
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
         end
       end
 
@@ -114,6 +128,24 @@ module Puma
         begin
           socket.setsockopt(6, 3, 0) if socket.kind_of? TCPSocket
         rescue IOError, SystemCallError
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        end
+      end
+
+      def closed_socket?(socket)
+        return false unless socket.kind_of? TCPSocket
+        return false unless @precheck_closing
+
+        begin
+          tcp_info = socket.getsockopt(Socket::SOL_TCP, Socket::TCP_INFO)
+        rescue IOError, SystemCallError
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+          @precheck_closing = false
+          false
+        else
+          state = tcp_info.unpack(UNPACK_TCP_STATE_FROM_TCP_INFO)[0]
+          # TIME_WAIT: 6, CLOSE: 7, CLOSE_WAIT: 8, LAST_ACK: 9, CLOSING: 11
+          (state >= 6 && state <= 9) || state == 11
         end
       end
     else
@@ -122,6 +154,10 @@ module Puma
 
       def uncork_socket(socket)
       end
+
+      def closed_socket?(socket)
+        false
+      end
     end
 
     def backlog
@@ -132,6 +168,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)
@@ -193,7 +241,11 @@ module Puma
                   # nothing
                 rescue Errno::ECONNABORTED
                   # client closed the socket even before accept
-                  io.close rescue nil
+                  begin
+                    io.close
+                  rescue
+                    Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+                  end
                 end
               end
             end
@@ -210,7 +262,12 @@ module Puma
         STDERR.puts "Exception handling servers: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
       ensure
-        @check.close
+        begin
+          @check.close
+        rescue
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        end
+
         @notify.close
 
         if @status != :restart and @own_binder
@@ -242,6 +299,10 @@ module Puma
       @thread_pool = ThreadPool.new(@min_threads,
                                     @max_threads,
                                     IOBuffer) do |client, buffer|
+
+        # Advertise this server into the thread
+        Thread.current[ThreadLocalKey] = self
+
         process_now = false
 
         begin
@@ -264,7 +325,7 @@ module Puma
           client.close
 
           @events.parse_error self, client.env, e
-        rescue ConnectionError
+        rescue ConnectionError, EOFError
           client.close
         else
           if process_now
@@ -335,13 +396,17 @@ module Puma
                     end
 
                     pool << client
-                    pool.wait_until_not_full unless queue_requests
+                    pool.wait_until_not_full
                   end
                 rescue SystemCallError
                   # nothing
                 rescue Errno::ECONNABORTED
                   # client closed the socket even before accept
-                  io.close rescue nil
+                  begin
+                    io.close
+                  rescue
+                    Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+                  end
                 end
               end
             end
@@ -354,7 +419,7 @@ module Puma
 
         graceful_shutdown if @status == :stop || @status == :restart
         if queue_requests
-          @reactor.clear! if @status == :restart
+          @reactor.clear!
           @reactor.shutdown
         end
       rescue Exception => e
@@ -399,6 +464,7 @@ module Puma
     #
     def process_client(client, buffer)
       begin
+
         clean_thread_locals = @options[:clean_thread_locals]
         close_socket = true
 
@@ -462,6 +528,7 @@ module Puma
         begin
           client.close if close_socket
         rescue IOError, SystemCallError
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
           # Already closed
         rescue StandardError => e
           @events.unknown_error self, e, "Client"
@@ -493,7 +560,9 @@ module Puma
 
         raise "No REQUEST PATH" unless env[REQUEST_PATH]
 
-        env[QUERY_STRING] = uri.query
+        # A nil env value will cause a LintError (and fatal errors elsewhere),
+        # so only set the env value if there actually is a value.
+        env[QUERY_STRING] = uri.query if uri.query
       end
 
       env[PATH_INFO] = env[REQUEST_PATH]
@@ -541,6 +610,8 @@ module Puma
       env = req.env
       client = req.io
 
+      return false if closed_socket?(client)
+
       normalize_env env, req
 
       env[PUMA_SOCKET] = client
@@ -559,6 +630,24 @@ module Puma
       env[RACK_INPUT] = body
       env[RACK_URL_SCHEME] =  env[HTTPS_KEY] ? HTTPS : HTTP
 
+      if @early_hints
+        env[EARLY_HINTS] = lambda { |headers|
+          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"
+              end
+            else
+              fast_write client, "#{k}: #{vs}\r\n"
+            end
+          end
+
+          fast_write client, "\r\n".freeze
+        }
+      end
+
       # A rack extension. If the app writes #call'ables to this
       # array, we will invoke them when the request is done.
       #
@@ -587,7 +676,7 @@ module Puma
           headers = {}
           res_body = ["Request was internally terminated early\n"]
 
-        rescue StandardError => e
+        rescue Exception => e
           @events.unknown_error self, e, "Rack app", env
 
           status, headers, res_body = lowlevel_error(e, env)
@@ -656,7 +745,7 @@ module Puma
             next
           end
 
-          if vs.respond_to?(:to_s)
+          if vs.respond_to?(:to_s) && !vs.to_s.empty?
             vs.to_s.split(NEWLINE).each do |v|
               lines.append k, colon, v, line_ending
             end
@@ -700,8 +789,8 @@ module Puma
 
         begin
           res_body.each do |part|
+            next if part.bytesize.zero?
             if chunked
-              next if part.bytesize.zero?
               fast_write client, part.bytesize.to_s(16)
               fast_write client, line_ending
               fast_write client, part
@@ -860,35 +949,38 @@ module Puma
       end
     end
 
-    # Stops the acceptor thread and then causes the worker threads to finish
-    # off the request queue before finally exiting.
-    #
-    def stop(sync=false)
+    def notify_safely(message)
       begin
-        @notify << STOP_COMMAND
+        @notify << message
       rescue IOError
-        # The server, in another thread, is shutting down
+         # The server, in another thread, is shutting down
+        Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+      rescue RuntimeError => e
+        # Temporary workaround for https://bugs.ruby-lang.org/issues/13239
+        if e.message.include?('IOError')
+          Thread.current.purge_interrupt_queue if Thread.current.respond_to? :purge_interrupt_queue
+        else
+          raise e
+        end
       end
+    end
+    private :notify_safely
 
+    # Stops the acceptor thread and then causes the worker threads to finish
+    # off the request queue before finally exiting.
+
+    def stop(sync=false)
+      notify_safely(STOP_COMMAND)
       @thread.join if @thread && sync
     end
 
     def halt(sync=false)
-      begin
-        @notify << HALT_COMMAND
-      rescue IOError
-        # The server, in another thread, is shutting down
-      end
-
+      notify_safely(HALT_COMMAND)
       @thread.join if @thread && sync
     end
 
     def begin_restart
-      begin
-        @notify << RESTART_COMMAND
-      rescue IOError
-        # The server, in another thread, is shutting down
-      end
+      notify_safely(RESTART_COMMAND)
     end
 
     def fast_write(io, str)
@@ -911,5 +1003,15 @@ module Puma
       end
     end
     private :fast_write
+
+    ThreadLocalKey = :puma_server
+
+    def self.current
+      Thread.current[ThreadLocalKey]
+    end
+
+    def shutting_down?
+      @status == :stop || @status == :restart
+    end
   end
 end