puma 6.6.1 → 7.0.4

data/lib/puma/cli.rb

@@ -39,10 +39,8 @@ module Puma
       @control_url = nil
       @control_options = {}
 
-      setup_options env
-
       begin
-        @parser.parse! @argv
+        setup_options env
 
         if file = @argv.shift
           @conf.configure do |user_config, file_config|
@@ -93,7 +91,7 @@ module Puma
     #
 
     def setup_options(env = ENV)
-      @conf = Configuration.new({}, {events: @events}, env) do |user_config, file_config|
+      @conf = Configuration.new({}, { events: @events }, env) do |user_config, file_config|
         @parser = OptionParser.new do |o|
           o.on "-b", "--bind URI", "URI to bind to (tcp://, unix://, ssl://)" do |arg|
             user_config.bind arg
@@ -240,7 +238,7 @@ module Puma
             $stdout.puts o
             exit 0
           end
-        end
+        end.parse! @argv
       end
     end
   end

data/lib/puma/client.rb

@@ -1,13 +1,5 @@
 # frozen_string_literal: true
 
-class IO
-  # We need to use this for a jruby work around on both 1.8 and 1.9.
-  # So this either creates the constant (on 1.8), or harmlessly
-  # reopens it (on 1.9).
-  module WaitReadable
-  end
-end
-
 require_relative 'detect'
 require_relative 'io_buffer'
 require 'tempfile'
@@ -64,6 +56,11 @@ module Puma
 
     TE_ERR_MSG = 'Invalid Transfer-Encoding'
 
+    # See:
+    # https://httpwg.org/specs/rfc9110.html#rfc.section.5.6.1.1
+    # https://httpwg.org/specs/rfc9112.html#rfc.section.6.1
+    STRIP_OWS = /\A[ \t]+|[ \t]+\z/
+
     # The object used for a request with no body. All requests with
     # no body share this one object since it has no state.
     EmptyBody = NullIO.new
@@ -111,7 +108,8 @@ module Puma
     end
 
     attr_reader :env, :to_io, :body, :io, :timeout_at, :ready, :hijacked,
-                :tempfile, :io_buffer, :http_content_length_limit_exceeded
+                :tempfile, :io_buffer, :http_content_length_limit_exceeded,
+                :requests_served
 
     attr_writer :peerip, :http_content_length_limit
 
@@ -133,9 +131,9 @@ module Puma
       "#<Puma::Client:0x#{object_id.to_s(16)} @ready=#{@ready.inspect}>"
     end
 
-    # For the hijack protocol (allows us to just put the Client object
-    # into the env)
-    def call
+    # For the full hijack protocol, `env['rack.hijack']` is set to
+    # `client.method :full_hijack`
+    def full_hijack
       @hijacked = true
       env[HIJACK_IO] ||= @io
     end
@@ -150,11 +148,12 @@ module Puma
     end
 
     # Number of seconds until the timeout elapses.
+    # @!attribute [r] timeout
     def timeout
       [@timeout_at - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
     end
 
-    def reset(fast_check=true)
+    def reset
       @parser.reset
       @io_buffer.reset
       @read_header = true
@@ -166,7 +165,10 @@ module Puma
       @peerip = nil if @remote_addr_header
       @in_last_chunk = false
       @http_content_length_limit_exceeded = false
+    end
 
+    # only used with back-to-back requests contained in the buffer
+    def process_back_to_back_requests
       if @buffer
         return false unless try_to_parse_proxy_protocol
 
@@ -178,25 +180,20 @@ module Puma
           raise HttpParserError,
             "HEADER is longer than allowed, aborting client early."
         end
-
-        return false
-      else
-        begin
-          if fast_check && @to_io.wait_readable(FAST_TRACK_KA_TIMEOUT)
-            return try_to_finish
-          end
-        rescue IOError
-          # swallow it
-        end
       end
     end
 
+    # if a client sends back-to-back requests, the buffer may contain one or more
+    # of them.
+    def has_back_to_back_requests?
+      !(@buffer.nil? || @buffer.empty?)
+    end
+
     def close
       tempfile_close
       begin
         @io.close
       rescue IOError, Errno::EBADF
-        Puma::Util.purge_interrupt_queue
       end
     end
 
@@ -291,8 +288,10 @@ module Puma
 
     def eagerly_finish
       return true if @ready
-      return false unless @to_io.wait_readable(0)
-      try_to_finish
+      while @to_io.wait_readable(0) # rubocop: disable Style/WhileUntilModifier
+        return true if try_to_finish
+      end
+      false
     end
 
     def finish(timeout)
@@ -412,17 +411,18 @@ module Puma
       if te
         te_lwr = te.downcase
         if te.include? ','
-          te_ary = te_lwr.split ','
+          te_ary = te_lwr.split(',').each { |te| te.gsub!(STRIP_OWS, "") }
           te_count = te_ary.count CHUNKED
           te_valid = te_ary[0..-2].all? { |e| ALLOWED_TRANSFER_ENCODING.include? e }
-          if te_ary.last == CHUNKED && te_count == 1 && te_valid
-            @env.delete TRANSFER_ENCODING2
-            return setup_chunked_body body
-          elsif te_count >= 1
+          if te_count > 1
             raise HttpParserError   , "#{TE_ERR_MSG}, multiple chunked: '#{te}'"
+          elsif te_ary.last != CHUNKED
+            raise HttpParserError   , "#{TE_ERR_MSG}, last value must be chunked: '#{te}'"
           elsif !te_valid
             raise HttpParserError501, "#{TE_ERR_MSG}, unknown value: '#{te}'"
           end
+          @env.delete TRANSFER_ENCODING2
+          return setup_chunked_body body
         elsif te_lwr == CHUNKED
           @env.delete TRANSFER_ENCODING2
           return setup_chunked_body body

data/lib/puma/cluster/worker.rb

@@ -110,7 +110,6 @@ module Puma
         begin
           @worker_write << "#{PIPE_BOOT}#{Process.pid}:#{index}\n"
         rescue SystemCallError, IOError
-          Puma::Util.purge_interrupt_queue
           STDERR.puts "Master seems to have exited, exiting."
           return
         end
@@ -128,16 +127,16 @@ module Puma
 
             while true
               begin
-                b = server.backlog || 0
-                r = server.running || 0
-                t = server.pool_capacity || 0
-                m = server.max_threads || 0
-                rc = server.requests_count || 0
-                bt = server.busy_threads || 0
-                payload = %Q!#{base_payload}{ "backlog":#{b}, "running":#{r}, "pool_capacity":#{t}, "max_threads":#{m}, "requests_count":#{rc}, "busy_threads":#{bt} }\n!
-                io << payload
+                payload = base_payload.dup
+
+                hsh = server.stats
+                hsh.each do |k, v|
+                  payload << %Q! "#{k}":#{v || 0},!
+                end
+                # sub call properly adds 'closing' string
+                io << payload.sub(/,\z/, " }\n")
+                server.reset_max
               rescue IOError
-                Puma::Util.purge_interrupt_queue
                 break
               end
               sleep @options[:worker_check_interval]

data/lib/puma/cluster/worker_handle.rb

@@ -4,13 +4,15 @@ module Puma
   class Cluster < Runner
     #—————————————————————— DO NOT USE — this class is for internal use only ———
 
-
     # This class represents a worker process from the perspective of the puma
     # master process. It contains information about the process and its health
     # and it exposes methods to control the process via IPC. It does not
     # include the actual logic executed by the worker process itself. For that,
     # see Puma::Cluster::Worker.
     class WorkerHandle # :nodoc:
+      # array of stat 'max' keys
+      WORKER_MAX_KEYS = [:backlog_max, :reactor_max]
+
       def initialize(idx, pid, phase, options)
         @index = idx
         @pid = pid
@@ -23,6 +25,7 @@ module Puma
         @last_checkin = Time.now
         @last_status = {}
         @term = false
+        @worker_max = Array.new WORKER_MAX_KEYS.length, 0
       end
 
       attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status, :started_at
@@ -51,12 +54,40 @@ module Puma
         @term
       end
 
-      STATUS_PATTERN = /{ "backlog":(?<backlog>\d*), "running":(?<running>\d*), "pool_capacity":(?<pool_capacity>\d*), "max_threads":(?<max_threads>\d*), "requests_count":(?<requests_count>\d*), "busy_threads":(?<busy_threads>\d*) }/
-      private_constant :STATUS_PATTERN
-
       def ping!(status)
+        hsh = {}
+        k, v = nil, nil
+        status.tr('}{"', '').strip.split(", ") do |kv|
+          cntr = 0
+          kv.split(':') do |t|
+            if cntr == 0
+              k = t
+              cntr = 1
+            else
+              v = t
+            end
+          end
+          hsh[k.to_sym] = v.to_i
+        end
+
+        # check stat max values, we can't signal workers to reset the max values,
+        # so we do so here
+        WORKER_MAX_KEYS.each_with_index do |key, idx|
+          next unless hsh[key]
+
+          if hsh[key] < @worker_max[idx]
+            hsh[key] = @worker_max[idx]
+          else
+            @worker_max[idx] = hsh[key]
+          end
+        end
         @last_checkin = Time.now
-        @last_status = status.match(STATUS_PATTERN).named_captures.map { |c_name, c| [c_name.to_sym, c.to_i] }.to_h
+        @last_status = hsh
+      end
+
+      # Resets max values to zero.  Called whenever `Cluster#stats` is called
+      def reset_max
+        WORKER_MAX_KEYS.length.times { |idx| @worker_max[idx] = 0 }
       end
 
       # @see Puma::Cluster#check_workers

data/lib/puma/cluster.rb

@@ -22,6 +22,7 @@ module Puma
       @workers = []
       @next_check = Time.now
 
+      @worker_max = [] # keeps track of 'max' stat values
       @phased_restart = false
     end
 
@@ -45,8 +46,7 @@ module Puma
     end
 
     def start_phased_restart(refork = false)
-      @events.fire_on_restart!
-
+      @events.fire_before_restart!
       @phase += 1
       if refork
         log "- Starting worker refork, phase: #{@phase}"
@@ -268,11 +268,14 @@ module Puma
     end
 
     # Inside of a child process, this will return all zeroes, as @workers is only populated in
-    # the master process.
+    # the master process.  Calling this also resets stat 'max' values to zero.
     # @!attribute [r] stats
+    # @return [Hash]
+
     def stats
       old_worker_count = @workers.count { |w| w.phase != @phase }
       worker_status = @workers.map do |w|
+        w.reset_max
         {
           started_at: utc_iso8601(w.started_at),
           pid: w.pid,
@@ -283,7 +286,6 @@ module Puma
           last_status: w.last_status,
         }
       end
-
       {
         started_at: utc_iso8601(@started_at),
         workers: @workers.size,
@@ -352,7 +354,7 @@ module Puma
 
           stop_workers
           stop
-          @events.fire_on_stopped!
+          @events.fire_after_stopped!
           raise(SignalException, "SIGTERM") if @options[:raise_exception_on_sigterm]
           exit 0 # Clean exit, workers were stopped
         end
@@ -369,12 +371,8 @@ module Puma
 
       if preload?
         # Threads explicitly marked as fork safe will be ignored. Used in Rails,
-        # but may be used by anyone. Note that we need to explicit
-        # Process::Waiter check here because there's a bug in Ruby 2.6 and below
-        # where calling thread_variable_get on a Process::Waiter will segfault.
-        # We can drop that clause once those versions of Ruby are no longer
-        # supported.
-        fork_safe = ->(t) { !t.is_a?(Process::Waiter) && t.thread_variable_get(:fork_safe) }
+        # but may be used by anyone.
+        fork_safe = ->(t) { t.thread_variable_get(:fork_safe) }
 
         before = Thread.list.reject(&fork_safe)
 
@@ -423,6 +421,7 @@ module Puma
 
       log "Use Ctrl-C to stop"
 
+      warn_ruby_mn_threads
       single_worker_warning
 
       redirect_io
@@ -511,7 +510,7 @@ module Puma
                   end
 
                   if !booted && @workers.none? {|worker| worker.last_status.empty?}
-                    @events.fire_on_booted!
+                    @events.fire_after_booted!
                     debug_loaded_extensions("Loaded Extensions - master:") if @log_writer.debug?
                     booted = true
                   end
@@ -528,7 +527,7 @@ module Puma
             end
 
             if in_phased_restart && workers_not_booted.zero?
-              @events.fire_on_booted!
+              @events.fire_after_booted!
               debug_loaded_extensions("Loaded Extensions - master:") if @log_writer.debug?
               in_phased_restart = false
             end

data/lib/puma/cluster_accept_loop_delay.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Puma
+  # Calculate a delay value for sleeping when running in clustered mode
+  #
+  # The main reason this is a class is so it can be unit tested independently.
+  # This makes modification easier in the future if we can encode properties of the
+  # delay into a test instead of relying on end-to-end testing only.
+  #
+  # This is an imprecise mechanism to address specific goals:
+  #
+  # - Evenly distribute requests across all workers at start
+  # - Evenly distribute CPU resources across all workers
+  #
+  # ## Goal: Distribute requests across workers at start
+  #
+  # There was a perf bug in Puma where one worker would wake up slightly before the rest and accept
+  # all the requests on the socket even though it didn't have enough resources to process all of them.
+  # This was originally fixed by never calling accept when a worker had more requests than threads
+  # already https://github.com/puma/puma/pull/3678/files/2736ebddb3fc8528e5150b5913fba251c37a8bf7#diff-a95f46e7ce116caddc9b9a9aa81004246d5210d5da5f4df90a818c780630166bL251-L291
+  #
+  # With the introduction of true keepalive support, there are two ways a request can come in:
+  # - A new request from a new client comes into the socket and it must be "accept"-d
+  # - A keepalive request is served and the connection is retained. Another request is then accepted
+  #
+  # Ideally the server handles requests in the order they come in, and ideally it doesn't accept more requests than it can handle.
+  # These goals are contradictory, because when the server is at maximum capacity due to keepalive connections, it could mean we
+  # block all new requests, even if those came in before the new request on the older keepalive connection.
+  #
+  # ## Distribute CPU resources across all workers
+  #
+  # - This issue was opened https://github.com/puma/puma/issues/2078
+  #
+  # There are several entangled issues and it's not exactly clear the root cause, but the observable outcome
+  # was that performance was better with a small sleep, and that eventually became the default.
+  #
+  # An attempt to describe why this works is here: https://github.com/puma/puma/issues/2078#issuecomment-3287032470.
+  #
+  # Summarizing: The delay is for tuning the rate at which "accept" is called on the socket.
+  # Puma works by calling "accept" nonblock on the socket in a loop. When there are multiple workers,
+  # (processes) then they will "race" to accept a request at roughly the same rate. However if one
+  # worker has all threads busy processing requests, then accepting a new request might "steal" it from
+  # a less busy worker. If a worker has no work to do, it should loop as fast as possible.
+  #
+  # ## Solution(s): Distribute requests across workers at start
+  #
+  # For now, both goals are framed as "load balancing" across workers (processes) and achieved through
+  # the same mechanism of sleeping longer to delay busier workers. Rather than the prior Puma 6.x
+  # and earlier behavior of using a binary on/off sleep value, we increase it an amound proportional
+  # to the load the server is under. Capping the maximum delay to the scenario where all threads are busy
+  # and the todo list has reached a multiplier of the maximum number of threads.
+  #
+  # Private: API may change unexpectedly
+  class ClusterAcceptLoopDelay
+    attr_reader :max_threads, :max_delay
+
+    # Initialize happens once, `call` happens often. Push global calculations here
+    def initialize(
+        # Number of workers in the cluster
+        workers: ,
+        # Maximum delay in seconds i.e. 0.005 is 5 microseconds
+        max_delay: # In seconds i.e. 0.005 is 5 microseconds
+
+      )
+      @on = max_delay > 0 && workers >= 2
+      @max_delay = max_delay.to_f
+
+      # Reach maximum delay when `max_threads * overload_multiplier` is reached in the system
+      @overload_multiplier = 25.0
+    end
+
+    def on?
+      @on
+    end
+
+    # We want the extreme values of this delay to be known (minimum and maximum) as well as
+    # a predictable curve between the two. i.e. no step functions or hard cliffs.
+    #
+    # Return value is always numeric. Returns 0 if there should be no delay
+    def calculate(
+      # Number of threads working right now, plus number of requests in the todo list
+      busy_threads_plus_todo:,
+      # Maximum number of threads in the pool, note that the busy threads (alone) may go over this value at times
+      # if the pool needs to be reaped. The busy thread plus todo count may go over this value by a large amount
+      max_threads:
+    )
+      max_value = @overload_multiplier * max_threads
+      # Approaches max delay when `busy_threads_plus_todo` approaches `max_value`
+      return max_delay * busy_threads_plus_todo.clamp(0, max_value) / max_value
+    end
+  end
+end

data/lib/puma/commonlogger.rb

@@ -29,13 +29,13 @@ module Puma
 
     CONTENT_LENGTH       = 'Content-Length' # should be lower case from app,
                                             # Util::HeaderHash allows mixed
-    HTTP_VERSION         = Const::HTTP_VERSION
     HTTP_X_FORWARDED_FOR = Const::HTTP_X_FORWARDED_FOR
     PATH_INFO            = Const::PATH_INFO
     QUERY_STRING         = Const::QUERY_STRING
     REMOTE_ADDR          = Const::REMOTE_ADDR
     REMOTE_USER          = 'REMOTE_USER'
     REQUEST_METHOD       = Const::REQUEST_METHOD
+    SERVER_PROTOCOL      = Const::SERVER_PROTOCOL
 
     def initialize(app, logger=nil)
       @app = app
@@ -70,7 +70,7 @@ module Puma
         env[REQUEST_METHOD],
         env[PATH_INFO],
         env[QUERY_STRING].empty? ? "" : "?#{env[QUERY_STRING]}",
-        env[HTTP_VERSION],
+        env[SERVER_PROTOCOL],
         now - began_at ]
 
       write(msg)
@@ -87,7 +87,7 @@ module Puma
         env[REQUEST_METHOD],
         env[PATH_INFO],
         env[QUERY_STRING].empty? ? "" : "?#{env[QUERY_STRING]}",
-        env[HTTP_VERSION],
+        env[SERVER_PROTOCOL],
         status.to_s[0..3],
         length,
         now - began_at ]