puma 6.4.1 → 7.2.1

data/lib/puma/cluster.rb

@@ -22,7 +22,8 @@ module Puma
       @workers = []
       @next_check = Time.now
 
-      @phased_restart = false
+      @worker_max = [] # keeps track of 'max' stat values
+      @pending_phased_restart = false
     end
 
     # Returns the list of cluster worker handles.
@@ -44,10 +45,14 @@ module Puma
       end
     end
 
-    def start_phased_restart
-      @events.fire_on_restart!
+    def start_phased_restart(refork = false)
+      @events.fire_before_restart!
       @phase += 1
-      log "- Starting phased worker restart, phase: #{@phase}"
+      if refork
+        log "- Starting worker refork, phase: #{@phase}"
+      else
+        log "- Starting phased worker restart, phase: #{@phase}"
+      end
 
       # Be sure to change the directory again before loading
       # the app. This way we can pick up new code.
@@ -87,6 +92,10 @@ module Puma
 
       if @options[:fork_worker] && all_workers_in_phase?
         @fork_writer << "0\n"
+
+        if worker_at(0).phase > 0
+          @fork_writer << "-2\n"
+        end
       end
     end
 
@@ -162,7 +171,7 @@ module Puma
       (@workers.map(&:pid) - idle_timed_out_worker_pids).empty?
     end
 
-    def check_workers
+    def check_workers(refork = false)
       return if @next_check >= Time.now
 
       @next_check = Time.now + @options[:worker_check_interval]
@@ -177,10 +186,15 @@ module Puma
         # we need to phase any workers out (which will restart
         # in the right phase).
         #
-        w = @workers.find { |x| x.phase != @phase }
+        w = @workers.find { |x| x.phase < @phase }
 
         if w
-          log "- Stopping #{w.pid} for phased upgrade..."
+          if refork
+            log "- Stopping #{w.pid} for refork..."
+          else
+            log "- Stopping #{w.pid} for phased upgrade..."
+          end
+
           unless w.term?
             w.term
             log "- #{w.signal} sent to #{w.pid}..."
@@ -207,12 +221,11 @@ module Puma
         pipes[:wakeup] = @wakeup
       end
 
-      server = start_server if preload?
       new_worker = Worker.new index: index,
                               master: master,
                               launcher: @launcher,
                               pipes: pipes,
-                              server: server
+                              app: (app if preload?)
       new_worker.run
     end
 
@@ -224,7 +237,7 @@ module Puma
     def phased_restart(refork = false)
       return false if @options[:preload_app] && !refork
 
-      @phased_restart = true
+      @pending_phased_restart = refork ? :refork : true
       wakeup!
 
       true
@@ -254,11 +267,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,
@@ -269,7 +285,6 @@ module Puma
           last_status: w.last_status,
         }
       end
-
       {
         started_at: utc_iso8601(@started_at),
         workers: @workers.size,
@@ -338,7 +353,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
@@ -348,8 +363,6 @@ module Puma
     def run
       @status = :run
 
-      @idle_workers = {}
-
       output_header "cluster"
 
       # This is aligned with the output from Runner, see Runner#output_header
@@ -357,16 +370,12 @@ 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)
 
-        log "*     Restarts: (\u2714) hot (\u2716) phased"
+        log "*     Restarts: (\u2714) hot (\u2716) phased (#{@options[:fork_worker] ? "\u2714" : "\u2716"}) refork"
         log "* Preloading application"
         load_and_bind
 
@@ -384,7 +393,7 @@ module Puma
           end
         end
       else
-        log "*     Restarts: (\u2714) hot (\u2714) phased"
+        log "*     Restarts: (\u2714) hot (\u2714) phased (#{@options[:fork_worker] ? "\u2714" : "\u2716"}) refork"
 
         unless @config.app_configured?
           error "No application configured, nothing to run"
@@ -411,6 +420,7 @@ module Puma
 
       log "Use Ctrl-C to stop"
 
+      warn_ruby_mn_threads
       single_worker_warning
 
       redirect_io
@@ -440,30 +450,37 @@ module Puma
 
         while @status == :run
           begin
-            if all_workers_idle_timed_out?
+            if @options[:idle_timeout] && all_workers_idle_timed_out?
               log "- All workers reached idle timeout"
               break
             end
 
-            if @phased_restart
-              start_phased_restart
-              @phased_restart = false
-              in_phased_restart = true
+            if @pending_phased_restart
+              start_phased_restart(@pending_phased_restart == :refork)
+
+              in_phased_restart = @pending_phased_restart
+              @pending_phased_restart = false
+
               workers_not_booted = @options[:workers]
+              # worker 0 is not restarted on refork
+              workers_not_booted -= 1 if in_phased_restart == :refork
             end
 
-            check_workers
+            check_workers(in_phased_restart == :refork)
 
             if read.wait_readable([0, @next_check - Time.now].max)
               req = read.read_nonblock(1)
+              next unless req
 
-              @next_check = Time.now if req == "!"
-              next if !req || req == "!"
+              if req == PIPE_WAKEUP
+                @next_check = Time.now
+                next
+              end
 
               result = read.gets
               pid = result.to_i
 
-              if req == "b" || req == "f"
+              if req == PIPE_BOOT || req == PIPE_FORK
                 pid, idx = result.split(':').map(&:to_i)
                 w = worker_at idx
                 w.pid = pid if w.pid.nil?
@@ -471,36 +488,36 @@ module Puma
 
               if w = @workers.find { |x| x.pid == pid }
                 case req
-                when "b"
+                when PIPE_BOOT
                   w.boot!
                   log "- Worker #{w.index} (PID: #{pid}) booted in #{w.uptime.round(2)}s, phase: #{w.phase}"
                   @next_check = Time.now
                   workers_not_booted -= 1
-                when "e"
+                when PIPE_EXTERNAL_TERM
                   # external term, see worker method, Signal.trap "SIGTERM"
                   w.term!
-                when "t"
+                when PIPE_TERM
                   w.term unless w.term?
-                when "p"
+                when PIPE_PING
                   status = result.sub(/^\d+/,'').chomp
                   w.ping!(status)
                   @events.fire(:ping!, w)
 
-                  if in_phased_restart && workers_not_booted.positive? && w0 = worker_at(0)
+                  if in_phased_restart && @options[:fork_worker] && workers_not_booted.positive? && w0 = worker_at(0)
                     w0.ping!(status)
                     @events.fire(:ping!, w0)
                   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
-                when "i"
-                  if @idle_workers[pid]
-                    @idle_workers.delete pid
+                when PIPE_IDLE
+                  if idle_workers[pid]
+                    idle_workers.delete pid
                   else
-                    @idle_workers[pid] = true
+                    idle_workers[pid] = true
                   end
                 end
               else
@@ -509,7 +526,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
@@ -560,9 +577,14 @@ module Puma
       @workers.reject! do |w|
         next false if w.pid.nil?
         begin
-          # When `fork_worker` is enabled, some worker may not be direct children, but grand children.
-          # Because of this they won't be reaped by `Process.wait2(-1)`, so we need to check them individually)
-          if reaped_children.delete(w.pid) || (@options[:fork_worker] && Process.wait(w.pid, Process::WNOHANG))
+          # We may need to check the PID individually because:
+          # 1. From Ruby versions 2.6 to 3.2, `Process.detach` can prevent or delay
+          #    `Process.wait2(-1)` from detecting a terminated process: https://bugs.ruby-lang.org/issues/19837.
+          # 2. When `fork_worker` is enabled, some worker may not be direct children,
+          #    but grand children.  Because of this they won't be reaped by `Process.wait2(-1)`.
+          if (status = reaped_children.delete(w.pid) || Process.wait2(w.pid, Process::WNOHANG)&.last)
+            w.process_status = status
+            @config.run_hooks(:after_worker_shutdown, w, @log_writer)
             true
           else
             w.term if w.term?
@@ -602,7 +624,11 @@ module Puma
     end
 
     def idle_timed_out_worker_pids
-      @idle_workers.keys
+      idle_workers.keys
+    end
+
+    def idle_workers
+      @idle_workers ||= {}
     end
   end
 end

data/lib/puma/cluster_accept_loop_delay.rb

@@ -0,0 +1,91 @@
+# 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"-ed
+  # - 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.
+  #
+  # ## Goal: 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 what the root cause is, 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), 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: 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 amount 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_delay
+
+    # Initialize happens once, `call` happens often. Perform global calculations here.
+    def initialize(
+      # Number of workers in the cluster
+      workers: ,
+      # Maximum delay in seconds i.e. 0.005 is 5 milliseconds
+      max_delay:
+    )
+      @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 ]