puma 7.0.4 → 7.2.0

data/lib/puma/cluster_accept_loop_delay.rb

@@ -20,48 +20,47 @@ module Puma
   # 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 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.
   #
-  # ## Distribute CPU resources across all workers
+  # ## 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 the root cause, but the observable outcome
+  # 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) then they will "race" to accept a request at roughly the same rate. However if one
+  # 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(s): Distribute requests across workers at start
+  # ## 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 amound proportional
-  # to the load the server is under. Capping the maximum delay to the scenario where all threads are busy
+  # 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_threads, :max_delay
+    attr_reader :max_delay
 
-    # Initialize happens once, `call` happens often. Push global calculations here
+    # 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 microseconds
-        max_delay: # In seconds i.e. 0.005 is 5 microseconds
-
-      )
+      # 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
 
@@ -76,12 +75,12 @@ module Puma
     # 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
+    # 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
+      # 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

data/lib/puma/configuration.rb

@@ -155,6 +155,7 @@ module Puma
       out_of_band: [],
       # Number of seconds for another request within a persistent session.
       persistent_timeout: 65, # PUMA_PERSISTENT_TIMEOUT
+      prune_bundler: false,
       queue_requests: true,
       rackup: 'config.ru'.freeze,
       raise_exception_on_sigterm: true,
@@ -196,7 +197,7 @@ module Puma
       @clamped = false
     end
 
-    attr_reader :plugins, :events, :hooks
+    attr_reader :plugins, :events, :hooks, :_options
 
     def options
       raise NotClampedError, "ensure clamp is called before accessing options" unless @clamped
@@ -237,18 +238,14 @@ module Puma
       min = env['PUMA_MIN_THREADS'] || env['MIN_THREADS']
       max = env['PUMA_MAX_THREADS'] || env['MAX_THREADS']
       persistent_timeout = env['PUMA_PERSISTENT_TIMEOUT']
-      workers = if env['WEB_CONCURRENCY'] == 'auto'
-        require_processor_counter
-        ::Concurrent.available_processor_count
-      else
-        env['WEB_CONCURRENCY']
-      end
+      workers_env = env['WEB_CONCURRENCY']
+      workers = workers_env && workers_env.strip != "" ? parse_workers(workers_env.strip) : nil
 
       {
         min_threads: min && min != "" && Integer(min),
         max_threads: max && max != "" && Integer(max),
         persistent_timeout: persistent_timeout && persistent_timeout != "" && Integer(persistent_timeout),
-        workers: workers && workers != "" && Integer(workers),
+        workers: workers,
         environment: env['APP_ENV'] || env['RACK_ENV'] || env['RAILS_ENV'],
       }
     end
@@ -379,12 +376,23 @@ module Puma
       require 'concurrent/utility/processor_counter'
     rescue LoadError
       warn <<~MESSAGE
-        WEB_CONCURRENCY=auto requires the "concurrent-ruby" gem to be installed.
+        WEB_CONCURRENCY=auto or workers(:auto) requires the "concurrent-ruby" gem to be installed.
         Please add "concurrent-ruby" to your Gemfile.
       MESSAGE
       raise
     end
 
+    def parse_workers(value)
+      if value == :auto || value == 'auto'
+        require_processor_counter
+        Integer(::Concurrent.available_processor_count)
+      else
+        Integer(value)
+      end
+    rescue ArgumentError, TypeError
+      raise ArgumentError, "workers must be an Integer or :auto"
+    end
+
     # Load and use the normal Rack builder if we can, otherwise
     # fallback to our minimal version.
     def rack_builder

data/lib/puma/const.rb

@@ -100,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "7.0.4"
-    CODE_NAME = "Romantic Warrior"
+    PUMA_VERSION = VERSION = "7.2.0"
+    CODE_NAME = "On The Corner"
 
     PUMA_SERVER_STRING = ["puma", PUMA_VERSION, CODE_NAME].join(" ").freeze
 

data/lib/puma/dsl.rb

@@ -216,6 +216,8 @@ module Puma
     #   activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
     # @example
     #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true, data_only: true}
     #
     def activate_control_app(url="auto", opts={})
       if url == "auto"
@@ -240,6 +242,7 @@ module Puma
 
       @options[:control_auth_token] = auth_token
       @options[:control_url_umask] = opts[:umask] if opts[:umask]
+      @options[:control_data_only] = opts[:data_only] if opts[:data_only]
     end
 
     # Load additional configuration from a file.
@@ -656,7 +659,8 @@ module Puma
       @options[:state] = path.to_s
     end
 
-    # Use +permission+ to restrict permissions for the state file.
+    # Use +permission+ to restrict permissions for the state file.  By convention,
+    # +permission+ is an octal number (e.g. `0640` or `0o640`).
     #
     # @example
     #   state_permission 0600
@@ -665,21 +669,27 @@ module Puma
       @options[:state_permission] = permission
     end
 
-    # How many worker processes to run.  Typically this is set to
-    # the number of available cores.
+    # How many worker processes to run. Typically this is set to the number of
+    # available cores.
     #
     # The default is the value of the environment variable +WEB_CONCURRENCY+ if
-    # set, otherwise 0.
+    # set, otherwise 0. Passing +:auto+ will set the value to
+    # +Concurrent.available_processor_count+ (requires the concurrent-ruby gem).
+    # On some platforms (e.g. under CPU quotas) this may be fractional, and Puma
+    # will round down. If it rounds down to 0, Puma will run in single mode and
+    # cluster-only hooks like +before_worker_boot+ will not execute.
+    # If you rely on cluster-only hooks, set an explicit worker count.
     #
-    # @note Cluster mode only.
+    # A value of 0 or nil means run in single mode.
     #
     # @example
     #   workers 2
+    #   workers :auto
     #
     # @see Puma::Cluster
     #
     def workers(count)
-      @options[:workers] = count.to_i
+      @options[:workers] = count.nil? ? 0 : @config.send(:parse_workers, count)
     end
 
     # Disable warning message when running in cluster mode with a single worker.
@@ -818,6 +828,20 @@ module Puma
 
     alias_method :after_worker_boot, :after_worker_fork
 
+    # Code to run in the master right after a worker has stopped. The worker's
+    # index and Process::Status are passed as arguments.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   after_worker_shutdown do |worker_handle|
+    #     puts 'Worker crashed' unless worker_handle.process_status.success?
+    #   end
+    #
+    def after_worker_shutdown(&block)
+      process_hook :after_worker_shutdown, nil, block, cluster_only: true
+    end
+
     # Code to run after puma is booted (works for both single and cluster modes).
     #
     # @example
@@ -980,6 +1004,7 @@ module Puma
     # The default is +true+ if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
+    # @note When using `fork_worker`, this only applies to worker 0.
     #
     # @example
     #   preload_app!
@@ -1207,13 +1232,19 @@ module Puma
     end
 
 
-    # Attempts to route traffic to less-busy workers by causing them to delay
-    # listening on the socket, allowing workers which are not processing any
+    # Maximum delay of worker accept loop.
+    #
+    # Attempts to route traffic to less-busy workers by causing a busy worker to delay
+    # listening on the socket, allowing workers which are not processing as many
     # requests to pick up new requests first.
     #
     # The default is 0.005 seconds.
     #
-    # Only works on MRI. For all other interpreters, this setting does nothing.
+    # To turn off this feature, set the value to 0.
+    #
+    # @note Cluster mode with >= 2 workers only.
+    #
+    # @note Interpreters with forking support only.
     #
     # @see Puma::Server#handle_servers
     # @see Puma::ThreadPool#wait_for_less_busy_worker
@@ -1357,7 +1388,7 @@ module Puma
     #
     # The default is +:auto+.
     #
-    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    # @see https://github.com/socketry/nio4r/blob/main/lib/nio/selector.rb
     #
     def io_selector_backend(backend)
       @options[:io_selector_backend] = backend.to_sym

data/lib/puma/launcher.rb

@@ -42,26 +42,40 @@ module Puma
     #   end
     #   Puma::Launcher.new(conf, log_writer: Puma::LogWriter.stdio).run
     def initialize(conf, launcher_args={})
-      @runner        = nil
-      @log_writer    = launcher_args[:log_writer] || LogWriter::DEFAULT
-      @events        = launcher_args[:events] || Events.new
-      @argv          = launcher_args[:argv] || []
-      @original_argv = @argv.dup
-      @config        = conf
-
-      env = launcher_args.delete(:env) || ENV
+      ## Minimal initialization before potential early restart (e.g. from bundle pruning)
 
+      @config = conf
+      # Advertise the CLI Configuration before config files are loaded
+      Puma.cli_config = @config if defined?(Puma.cli_config)
       @config.clamp
+
       @options = @config.options
 
+      @log_writer = launcher_args[:log_writer] || LogWriter::DEFAULT
+      @log_writer.formatter = LogWriter::PidFormatter.new if clustered?
+      @log_writer.formatter = @options[:log_formatter] if @options[:log_formatter]
+      @log_writer.custom_logger = @options[:custom_logger] if @options[:custom_logger]
       @options[:log_writer] = @log_writer
       @options[:logger] = @log_writer if clustered?
 
-      # Advertise the Configuration
-      Puma.cli_config = @config if defined?(Puma.cli_config)
+      @events = launcher_args[:events] || Events.new
+
+      @argv = launcher_args[:argv] || []
+      @original_argv = @argv.dup
+
+      ## End minimal initialization
+
+      generate_restart_data
+      Dir.chdir(@restart_dir)
+
+      prune_bundler!
+
+      env = launcher_args.delete(:env) || ENV
+
+      # Log after prune_bundler! to avoid duplicate logging if a restart occurs
       log_config if env['PUMA_LOG_CONFIG']
 
-      @binder        = Binder.new(@log_writer, @options)
+      @binder = Binder.new(@log_writer, @options)
       @binder.create_inherited_fds(env).each { |k| env.delete k }
       @binder.create_activated_fds(env).each { |k| env.delete k }
 
@@ -81,21 +95,10 @@ module Puma
         )
       end
 
-      @log_writer.formatter = LogWriter::PidFormatter.new if clustered?
-      @log_writer.formatter = @options[:log_formatter] if @options[:log_formatter]
-
-      @log_writer.custom_logger = @options[:custom_logger] if @options[:custom_logger]
-
-      generate_restart_data
-
       if clustered? && !Puma.forkable?
         unsupported "worker mode not supported on #{RUBY_ENGINE} on this platform"
       end
 
-      Dir.chdir(@restart_dir)
-
-      prune_bundler!
-
       @environment = @options[:environment] if @options[:environment]
       set_rack_environment
 
@@ -139,7 +142,10 @@ module Puma
     # Delete the configured pidfile
     def delete_pidfile
       path = @options[:pidfile]
-      File.unlink(path) if path && File.exist?(path)
+      begin
+        File.unlink(path) if path
+      rescue Errno::ENOENT
+      end
     end
 
     # Begin async shutdown of the server
@@ -381,9 +387,9 @@ module Puma
         # using it.
         @restart_dir = Dir.pwd
 
-        # Use the same trick as unicorn, namely favor PWD because
-        # it will contain an unresolved symlink, useful for when
-        # the pwd is /data/releases/current.
+      # Use the same trick as unicorn, namely favor PWD because
+      # it will contain an unresolved symlink, useful for when
+      # the pwd is /data/releases/current.
       elsif dir = ENV['PWD']
         s_env = File.stat(dir)
         s_pwd = File.stat(Dir.pwd)

data/lib/puma/reactor.rb

@@ -75,15 +75,12 @@ module Puma
     private
 
     def select_loop
-      close_selector = true
       begin
         until @input.closed? && @input.empty?
           # Wakeup any registered object that receives incoming data.
           # Block until the earliest timeout or Selector#wakeup is called.
           timeout = (earliest = @timeouts.first) && earliest.timeout
-          monitor_wake_up = false
           @selector.select(timeout) do |monitor|
-            monitor_wake_up = true
             wakeup!(monitor.value)
           end
 
@@ -103,18 +100,12 @@ module Puma
         STDERR.puts "Error in reactor loop escaped: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
 
-        # NoMethodError may be rarely raised when calling @selector.select, which
-        # is odd.  Regardless, it may continue for thousands of calls if retried.
-        # Also, when it raises, @selector.close also raises an error.
-        if !monitor_wake_up && NoMethodError === e
-          close_selector = false
-        else
-          retry
-        end
+        retry
       end
+
       # Wakeup all remaining objects on shutdown.
       @timeouts.each(&@block)
-      @selector.close if close_selector
+      @selector.close
     end
 
     # Start monitoring the object.

data/lib/puma/request.rb

@@ -36,17 +36,19 @@ module Puma
     # Takes the request contained in +client+, invokes the Rack application to construct
     # the response and writes it back to +client.io+.
     #
-    # It'll return +false+ when the connection is closed, this doesn't mean
+    # It'll return +:close+ when the connection is closed, this doesn't mean
     # that the response wasn't successful.
     #
+    # It'll return +:keep_alive+ if the connection is a pipeline or keep-alive connection.
+    # Which may contain additional requests.
+    #
     # 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.
     # @param client [Puma::Client]
     # @param requests [Integer]
-    # @return [Boolean,:async]
-    #
+    # @return [:close, :keep_alive, :async]
     def handle_request(client, requests)
       env = client.env
       io_buffer = client.io_buffer
@@ -54,7 +56,7 @@ module Puma
       app_body = nil
       error = nil
 
-      return false if closed_socket?(socket)
+      return :close if closed_socket?(socket)
 
       if client.http_content_length_limit_exceeded
         return prepare_response(413, {}, ["Payload Too Large"], requests, client)
@@ -167,13 +169,13 @@ module Puma
     #   a call to `Server#lowlevel_error`
     # @param requests [Integer] number of inline requests handled
     # @param client [Puma::Client]
-    # @return [Boolean,:async] keep-alive status or `:async`
+    # @return [:close, :keep_alive, :async]
     def prepare_response(status, headers, res_body, requests, client)
       env = client.env
       socket = client.io
       io_buffer = client.io_buffer
 
-      return false if closed_socket?(socket)
+      return :close if closed_socket?(socket)
 
       # Close the connection after a reasonable number of inline requests
       force_keep_alive = @enable_keep_alives && client.requests_served < @max_keep_alive
@@ -244,7 +246,7 @@ module Puma
           io_buffer << LINE_END
           fast_write_str socket, io_buffer.read_and_reset
           socket.flush
-          return keep_alive
+          return keep_alive ? :keep_alive : :close
         end
       else
         if content_length
@@ -270,7 +272,7 @@ module Puma
       fast_write_response socket, body, io_buffer, chunked, content_length.to_i
       body.close if close_body
       # if we're shutting down, close keep_alive connections
-      !shutting_down? && keep_alive
+      !shutting_down? && keep_alive ? :keep_alive : :close
     end
 
     HTTP_ON_VALUES = { "on" => true, HTTPS => true }

data/lib/puma/runner.rb

@@ -70,7 +70,7 @@ module Puma
         token = nil if token.empty? || token == 'none'
       end
 
-      app = Puma::App::Status.new @launcher, token
+      app = Puma::App::Status.new @launcher, token: token, data_only: @options[:control_data_only]
 
       # A Reactor is not created and nio4r is not loaded when 'queue_requests: false'
       # Use `nil` for events, no hooks in control server

data/lib/puma/server.rb

@@ -19,9 +19,6 @@ require 'socket'
 require 'io/wait' unless Puma::HAS_NATIVE_IO_WAIT
 
 module Puma
-  # Add `Thread#puma_server` and `Thread#puma_server=`
-  Thread.attr_accessor(:puma_server)
-
   # The HTTP Server itself. Serves out a single Rack app.
   #
   # This class is used by the `Puma::Single` and `Puma::Cluster` classes
@@ -262,7 +259,7 @@ module Puma
 
       @status = :run
 
-      @thread_pool = ThreadPool.new(thread_name, options) { |client| process_client client }
+      @thread_pool = ThreadPool.new(thread_name, options, server: self) { |client| process_client client }
 
       if @queue_requests
         @reactor = Reactor.new(@io_selector_backend) { |c|
@@ -302,7 +299,7 @@ module Puma
     # 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.
     #
-    # For a graphical representation of how the request buffer works see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline).
+    # For a graphical representation of how the request buffer works see [architecture.md](https://github.com/puma/puma/blob/main/docs/architecture.md).
     #
     # The method 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,
@@ -481,9 +478,6 @@ module Puma
     #
     # Return true if one or more requests were processed.
     def process_client(client)
-      # Advertise this server into the thread
-      Thread.current.puma_server = self
-
       close_socket = true
 
       requests = 0
@@ -502,31 +496,41 @@ module Puma
           client.finish(@first_data_timeout)
         end
 
-        @requests_count += 1
-        case handle_request(client, requests + 1)
-        when false
-        when :async
-          close_socket = false
-        when true
-          requests += 1
+        can_loop = true
+        while can_loop
+          can_loop = false
+          @requests_count += 1
+          case handle_request(client, requests + 1)
+          when :close
+          when :async
+            close_socket = false
+          when :keep_alive
+            requests += 1
 
-          client.reset
+            client.reset
 
-          # This indicates data exists in the client read buffer and there may be
-          # additional requests on it, so process them
-          next_request_ready = if client.has_back_to_back_requests?
-            with_force_shutdown(client) { client.process_back_to_back_requests }
-          else
-            with_force_shutdown(client) { client.eagerly_finish }
-          end
+            # This indicates data exists in the client read buffer and there may be
+            # additional requests on it, so process them
+            next_request_ready = if client.has_back_to_back_requests?
+              with_force_shutdown(client) { client.process_back_to_back_requests }
+            else
+              with_force_shutdown(client) { client.eagerly_finish }
+            end
 
-          if next_request_ready
-            @thread_pool << client
-            close_socket = false
-          elsif @queue_requests
-            client.set_timeout @persistent_timeout
-            if @reactor.add client
-              close_socket = false
+            if next_request_ready
+              # When Puma has spare threads, allow this one to be monopolized
+              # Perf optimization for https://github.com/puma/puma/issues/3788
+              if @thread_pool.waiting > 0
+                can_loop = true
+              else
+                @thread_pool << client
+                close_socket = false
+              end
+            elsif @queue_requests
+              client.set_timeout @persistent_timeout
+              if @reactor.add client
+                close_socket = false
+              end
             end
           end
         end
@@ -706,7 +710,7 @@ module Puma
 
     def reset_max
       @reactor.reactor_max = 0 if @reactor
-      @thread_pool.reset_max
+      @thread_pool&.reset_max
     end
 
     # below are 'delegations' to binder

data/lib/puma/single.rb

@@ -49,8 +49,8 @@ module Puma
 
       start_control
 
-      @server = server = start_server
-      server_thread = server.run
+      @server = start_server
+      server_thread = @server.run
 
       log "Use Ctrl-C to stop"
 

data/lib/puma/state_file.rb

@@ -32,10 +32,11 @@ module Puma
             "#{k}: \"#{v}\"\n" : "#{k}: #{v}\n")
         end
       end
+
       if permission
-        File.write path, contents, mode: 'wb:UTF-8'
-      else
         File.write path, contents, mode: 'wb:UTF-8', perm: permission
+      else
+        File.write path, contents, mode: 'wb:UTF-8'
       end
     end
 

data/lib/puma/thread_pool.rb

@@ -5,6 +5,10 @@ require 'thread'
 require_relative 'io_buffer'
 
 module Puma
+
+  # Add `Thread#puma_server` and `Thread#puma_server=`
+  Thread.attr_accessor(:puma_server)
+
   # Internal Docs for A simple thread pool management object.
   #
   # Each Puma "worker" has a thread pool to process requests.
@@ -33,7 +37,9 @@ module Puma
     # The block passed is the work that will be performed in each
     # thread.
     #
-    def initialize(name, options = {}, &block)
+    def initialize(name, options = {}, server: nil, &block)
+      @server = server
+
       @not_empty = ConditionVariable.new
       @not_full = ConditionVariable.new
       @mutex = Mutex.new
@@ -134,6 +140,9 @@ module Puma
       trigger_before_thread_start_hooks
       th = Thread.new(@spawned) do |spawned|
         Puma.set_thread_name '%s tp %03i' % [@name, spawned]
+        # Advertise server into the thread
+        Thread.current.puma_server = @server
+
         todo  = @todo
         block = @block
         mutex = @mutex