puma 6.4.3 → 8.0.2

data/lib/puma/dsl.rb

@@ -13,7 +13,7 @@ module Puma
   #   config = Configuration.new({}) do |user_config|
   #     user_config.port 3001
   #   end
-  #   config.load
+  #   config.clamp
   #
   #   puts config.options[:binds] # => "tcp://127.0.0.1:3001"
   #
@@ -25,7 +25,7 @@ module Puma
   # Resulting configuration:
   #
   #   config = Configuration.new(config_file: "puma_config.rb")
-  #   config.load
+  #   config.clamp
   #
   #   puts config.options[:binds] # => "tcp://127.0.0.1:3002"
   #
@@ -43,15 +43,17 @@ module Puma
   #
   # The following hooks have been updated:
   #
-  #     | DSL Method         |  Options Key            | Fork Block Location |
-  #     | on_worker_boot     | :before_worker_boot     | inside, before      |
-  #     | on_worker_shutdown | :before_worker_shutdown | inside, after       |
-  #     | on_refork          | :before_refork          | inside              |
+  #     | DSL Method             |  Options Key            | Fork Block Location |
+  #     | before_worker_boot     | :before_worker_boot     | inside, before      |
+  #     | before_worker_shutdown | :before_worker_shutdown | inside, after       |
+  #     | before_refork          | :before_refork          | inside              |
+  #     | after_refork           | :after_refork           | inside              |
   #
   class DSL
     ON_WORKER_KEY = [String, Symbol].freeze
 
-    # convenience method so logic can be used in CI
+    # Convenience method so logic can be used in CI.
+    #
     # @see ssl_bind
     #
     def self.ssl_bind_str(host, port, opts)
@@ -85,6 +87,7 @@ module Puma
           "&verify_mode=#{verify}#{tls_str}#{ca_additions}#{backlog_str}"
       else
         ssl_cipher_filter = opts[:ssl_cipher_filter] ? "&ssl_cipher_filter=#{opts[:ssl_cipher_filter]}" : nil
+        ssl_ciphersuites = opts[:ssl_ciphersuites] ? "&ssl_ciphersuites=#{opts[:ssl_ciphersuites]}" : nil
         v_flags = (ary = opts[:verification_flags]) ? "&verification_flags=#{Array(ary).join ','}" : nil
 
         cert_flags = (cert = opts[:cert]) ? "cert=#{Puma::Util.escape(cert)}" : nil
@@ -115,7 +118,7 @@ module Puma
             nil
           end
 
-        "ssl://#{host}:#{port}?#{cert_flags}#{key_flags}#{password_flags}#{ssl_cipher_filter}" \
+        "ssl://#{host}:#{port}?#{cert_flags}#{key_flags}#{password_flags}#{ssl_cipher_filter}#{ssl_ciphersuites}" \
           "#{reuse_flag}&verify_mode=#{verify}#{tls_str}#{ca_additions}#{v_flags}#{backlog_str}#{low_latency_str}"
       end
     end
@@ -152,7 +155,7 @@ module Puma
     end
 
     def default_host
-      @options[:default_host] || Configuration::DEFAULTS[:tcp_host]
+      @options[:default_host] || Configuration.default_tcp_host
     end
 
     def inject(&blk)
@@ -163,7 +166,10 @@ module Puma
       @options[key.to_sym] || default
     end
 
-    # Load the named plugin for use by this configuration
+    # Load the named plugin for use by this configuration.
+    #
+    # @example
+    #   plugin :tmp_restart
     #
     def plugin(name)
       @plugins << @config.load_plugin(name)
@@ -210,6 +216,9 @@ 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"
         path = Configuration.temp_path
@@ -233,10 +242,15 @@ 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
-    # Files get loaded later via Configuration#load
+    # Load additional configuration from a file.
+    # Files get loaded later via Configuration#load.
+    #
+    # @example
+    #   load 'config/puma/production.rb'
+    #
     def load(file)
       @options[:config_files] ||= []
       @options[:config_files] << file
@@ -246,7 +260,8 @@ module Puma
     # accepted protocols. Multiple urls can be bound to, calling +bind+ does
     # not overwrite previous bindings.
     #
-    # The default is "tcp://0.0.0.0:9292".
+    # The default is "tcp://[::]:9292" when IPv6 interfaces are available,
+    # otherwise "tcp://0.0.0.0:9292".
     #
     # You can use query parameters within the url to specify options:
     #
@@ -265,9 +280,10 @@ module Puma
     # @example SSL cert for mutual TLS (mTLS)
     #   bind 'ssl://127.0.0.1:9292?key=key.key&cert=cert.pem&ca=ca.pem&verify_mode=force_peer'
     # @example Disable optimization for low latency
-    #   bind 'tcp://0.0.0.0:9292?low_latency=false'
+    #   bind 'tcp://[::]:9292?low_latency=false'
     # @example Socket permissions
     #   bind 'unix:///var/run/puma.sock?umask=0111'
+    #
     # @see Puma::Runner#load_and_bind
     # @see Puma::Cluster#run
     #
@@ -302,46 +318,81 @@ module Puma
     #
     # @example Only bind to systemd activated sockets, ignoring other binds
     #   bind_to_activated_sockets 'only'
+    #
     def bind_to_activated_sockets(bind=true)
       @options[:bind_to_activated_sockets] = bind
     end
 
-    # Define the TCP port to bind to. Use +bind+ for more advanced options.
+    # Define the TCP port to bind to. Use `bind` for more advanced options.
+    #
+    # The default is +9292+.
     #
     # @example
-    #   port 9292
+    #   port 3000
+    #
     def port(port, host=nil)
       host ||= default_host
       bind URI::Generic.build(scheme: 'tcp', host: host, port: Integer(port)).to_s
     end
 
     # Define how long the tcp socket stays open, if no data has been received.
+    #
+    # The default is 30 seconds.
+    #
+    # @example
+    #   first_data_timeout 40
+    #
     # @see Puma::Server.new
+    #
     def first_data_timeout(seconds)
       @options[:first_data_timeout] = Integer(seconds)
     end
 
     # Define how long persistent connections can be idle before Puma closes them.
+    #
+    # The default is 65 seconds.
+    #
+    # @example
+    #   persistent_timeout 30
+    #
     # @see Puma::Server.new
+    #
     def persistent_timeout(seconds)
       @options[:persistent_timeout] = Integer(seconds)
     end
 
     # If a new request is not received within this number of seconds, begin shutting down.
+    #
+    # The default is +nil+.
+    #
+    # @example
+    #   idle_timeout 60
+    #
     # @see Puma::Server.new
+    #
     def idle_timeout(seconds)
       @options[:idle_timeout] = Integer(seconds)
     end
 
-    # Work around leaky apps that leave garbage in Thread locals
-    # across requests.
-    def clean_thread_locals(which=true)
-      @options[:clean_thread_locals] = which
+    # Use a clean fiber per request which ensures a clean slate for fiber
+    # locals and fiber storage. Also provides a cleaner backtrace with less
+    # Puma internal stack frames.
+    #
+    # The default is +false+.
+    #
+    # @example
+    #   fiber_per_request
+    #
+    def fiber_per_request(which=true)
+      @options[:fiber_per_request] = which
     end
 
+    alias clean_thread_locals fiber_per_request
+
     # When shutting down, drain the accept socket of pending connections and
     # process them. This loops over the accept socket until there are no more
     # read events and then stops looking and waits for the requests to finish.
+    #
     # @see Puma::Server#graceful_shutdown
     #
     def drain_on_shutdown(which=true)
@@ -355,18 +406,22 @@ module Puma
     #
     # @example
     #   environment 'production'
+    #
     def environment(environment)
       @options[:environment] = environment
     end
 
-    # How long to wait for threads to stop when shutting them
-    # down. Defaults to :forever. Specifying :immediately will cause
-    # Puma to kill the threads immediately.  Otherwise the value
-    # is the number of seconds to wait.
+    # How long to wait for threads to stop when shutting them down.
+    # Specifying :immediately will cause Puma to kill the threads immediately.
+    # Otherwise the value is the number of seconds to wait.
     #
     # Puma always waits a few seconds after killing a thread for it to try
     # to finish up it's work, even in :immediately mode.
+    #
+    # The default is +:forever+.
+    #
     # @see Puma::Server#graceful_shutdown
+    #
     def force_shutdown_after(val=:forever)
       i = case val
           when :forever
@@ -386,20 +441,25 @@ module Puma
     # This can be called multiple times to add code each time.
     #
     # @example
-    #   on_restart do
+    #   before_restart do
     #     puts 'On restart...'
     #   end
-    def on_restart(&block)
-      @options[:on_restart] ||= []
-      @options[:on_restart] << block
+    #
+    def before_restart(&block)
+      Puma.deprecate_method_change :on_restart, __callee__, __method__
+
+      process_hook :before_restart, nil, block
     end
 
+    alias_method :on_restart, :before_restart
+
     # Command to use to restart Puma. This should be just how to
     # load Puma itself (ie. 'ruby -Ilib bin/puma'), not the arguments
     # to Puma, as those are the same as the original process.
     #
     # @example
     #   restart_command '/u/app/lolcat/bin/restart_puma'
+    #
     def restart_command(cmd)
       @options[:restart_cmd] = cmd.to_s
     end
@@ -408,31 +468,49 @@ module Puma
     #
     # @example
     #   pidfile '/u/apps/lolcat/tmp/pids/puma.pid'
+    #
     def pidfile(path)
       @options[:pidfile] = path.to_s
     end
 
-    # Disable request logging, if this isn't used it'll be enabled by default.
+    # Disable request logging, the inverse of `log_requests`.
+    #
+    # The default is +true+.
     #
     # @example
     #   quiet
+    #
     def quiet(which=true)
       @options[:log_requests] = !which
     end
 
-    # Enable request logging
+    # Enable request logging, the inverse of `quiet`.
+    #
+    # The default is +false+.
+    #
+    # @example
+    #   log_requests
     #
     def log_requests(which=true)
       @options[:log_requests] = which
     end
 
     # Pass in a custom logging class instance
+    #
+    # @example
+    #   custom_logger Logger.new('t.log')
+    #
     def custom_logger(custom_logger)
       @options[:custom_logger] = custom_logger
     end
 
     # Show debugging info
     #
+    # The default is +false+.
+    #
+    # @example
+    #   debug
+    #
     def debug
       @options[:debug] = true
     end
@@ -443,6 +521,7 @@ module Puma
     #
     # @example
     #   rackup '/u/apps/lolcat/config.ru'
+    #
     def rackup(path)
       @options[:rackup] ||= path.to_s
     end
@@ -450,21 +529,32 @@ module Puma
     # Allows setting `env['rack.url_scheme']`.
     # Only necessary if X-Forwarded-Proto is not being set by your proxy
     # Normal values are 'http' or 'https'.
+    #
     def rack_url_scheme(scheme=nil)
       @options[:rack_url_scheme] = scheme
     end
 
+    # Enable HTTP 103 Early Hints responses.
+    #
+    # The default is +nil+.
+    #
+    # @example
+    #   early_hints
+    #
     def early_hints(answer=true)
       @options[:early_hints] = answer
     end
 
     # Redirect +STDOUT+ and +STDERR+ to files specified. The +append+ parameter
-    # specifies whether the output is appended, the default is +false+.
+    # specifies whether the output is appended.
+    #
+    # The default is +false+.
     #
     # @example
     #   stdout_redirect '/app/lolcat/log/stdout', '/app/lolcat/log/stderr'
     # @example
     #   stdout_redirect '/app/lolcat/log/stdout', '/app/lolcat/log/stderr', true
+    #
     def stdout_redirect(stdout=nil, stderr=nil, append=false)
       @options[:redirect_stdout] = stdout
       @options[:redirect_stderr] = stderr
@@ -475,8 +565,9 @@ module Puma
       @options[:log_formatter] = block
     end
 
-    # Configure +min+ to be the minimum number of threads to use to answer
-    # requests and +max+ the maximum.
+    # Configure the number of threads to use to answer requests.
+    #
+    # It can be a single fixed number, or a +min+ and a +max+.
     #
     # The default is the environment variables +PUMA_MIN_THREADS+ / +PUMA_MAX_THREADS+
     # (or +MIN_THREADS+ / +MAX_THREADS+ if the +PUMA_+ variables aren't set).
@@ -484,10 +575,13 @@ module Puma
     # If these environment variables aren't set, the default is "0, 5" in MRI or "0, 16" for other interpreters.
     #
     # @example
+    #   threads 5
+    # @example
     #   threads 0, 16
     # @example
     #   threads 5, 5
-    def threads(min, max)
+    #
+    def threads(min, max = min)
       min = Integer(min)
       max = Integer(max)
       if min > max
@@ -502,6 +596,29 @@ module Puma
       @options[:max_threads] = max
     end
 
+    # Configure the max number of IO threads.
+    #
+    # When request handlers know the current requests will no longer use a significant amount
+    # of CPU, they can mark the current request as IO bound using <tt>env["puma.mark_as_io_bound"]</tt>.
+    #
+    # Threads marked as IO bound are allowed to go over the max thread limit.
+    #
+    # @example
+    #   threads 5
+    #   max_io_threads 5
+    #
+    # The above example allows for 5 regular threads and 5 IO threads to process requests concurrently.
+    # Any IO thread over the limit is counted as a regular thread, hence the above configuration also
+    # allows for 3 regular threads and 7 IO threads for example.
+    def max_io_threads(max)
+      max = Integer(max)
+      if max < 0
+        raise "The maximum number of IO threads (#{max}) must be a positive number"
+      end
+
+      @options[:max_io_threads] = max
+    end
+
     # Instead of using +bind+ and manually constructing a URI like:
     #
     #    bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'
@@ -527,6 +644,7 @@ module Puma
     #     cert: path_to_cert,
     #     key: path_to_key,
     #     ssl_cipher_filter: cipher_filter, # optional
+    #     ssl_ciphersuites: ciphersuites,   # optional
     #     verify_mode: verify_mode,         # default 'none'
     #     verification_flags: flags,        # optional, not supported by JRuby
     #     reuse: true                       # optional
@@ -549,6 +667,7 @@ module Puma
     #     ssl_cipher_list: cipher_list,     # optional
     #     verify_mode: verify_mode          # default 'none'
     #   }
+    #
     def ssl_bind(host, port, opts = {})
       add_pem_values_to_options_store(opts)
       bind self.class.ssl_bind_str(host, port, opts)
@@ -559,30 +678,42 @@ module Puma
     #
     # @example
     #   state_path '/u/apps/lolcat/tmp/pids/puma.state'
+    #
     def state_path(path)
       @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
-    # @version 5.0.0
     #
     def state_permission(permission)
       @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.
+    #
+    # A value of 0 or nil means run in single mode.
+    #
+    # @example
+    #   workers 2
+    #   workers :auto
     #
-    # @note Cluster mode only.
     # @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.
@@ -598,16 +729,66 @@ module Puma
     #
     # Moving from workers = 1 to workers = 0 will save 10-30% of memory use.
     #
+    # The default is +false+.
+    #
     # @note Cluster mode only.
+    #
+    # @example
+    #  silence_single_worker_warning
+    #
     def silence_single_worker_warning
       @options[:silence_single_worker_warning] = true
     end
 
     # Disable warning message when running single mode with callback hook defined.
+    #
+    # The default is +false+.
+    #
+    # @example
+    #   silence_fork_callback_warning
+    #
     def silence_fork_callback_warning
       @options[:silence_fork_callback_warning] = true
     end
 
+    # Code to run only in single mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Single mode only.
+    #
+    # @example
+    #   single do
+    #     silence_fork_callback_warning
+    #   end
+    #
+    def single(&block)
+      raise ArgumentError, "A block must be provided to `single`" unless block
+
+      @options[:single] ||= []
+      @options[:single] << block
+    end
+
+    # Code to run only in cluster mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   cluster do
+    #     prune_bundler
+    #   end
+    #
+    def cluster(&block)
+      raise ArgumentError, "A block must be provided to `cluster`" unless block
+
+      @options[:cluster] ||= []
+      @options[:cluster] << block
+    end
+
     # Code to run immediately before master process
     # forks workers (once on boot). These hooks can block if necessary
     # to wait for background operations unknown to Puma to finish before
@@ -618,15 +799,14 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @note Cluster mode only.
+    #
     # @example
     #   before_fork do
     #     puts "Starting workers..."
     #   end
+    #
     def before_fork(&block)
-      warn_if_in_single_mode('before_fork')
-
-      @options[:before_fork] ||= []
-      @options[:before_fork] << block
+      process_hook :before_fork, nil, block, cluster_only: true
     end
 
     # Code to run in a worker when it boots to setup
@@ -635,77 +815,123 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @note Cluster mode only.
+    #
     # @example
-    #   on_worker_boot do
+    #   before_worker_boot do
     #     puts 'Before worker boot...'
     #   end
-    def on_worker_boot(key = nil, &block)
-      warn_if_in_single_mode('on_worker_boot')
+    #
+    def before_worker_boot(key = nil, &block)
+      Puma.deprecate_method_change :on_worker_boot, __callee__, __method__
 
-      process_hook :before_worker_boot, key, block, 'on_worker_boot'
+      process_hook :before_worker_boot, key, block, cluster_only: true
     end
 
+    alias_method :on_worker_boot, :before_worker_boot
+
     # Code to run immediately before a worker shuts
-    # down (after it has finished processing HTTP requests). These hooks
+    # down (after it has finished processing HTTP requests). The worker's
+    # index is passed as an argument. These hooks
     # can block if necessary to wait for background operations unknown
     # to Puma to finish before the process terminates.
     #
     # This can be called multiple times to add several hooks.
     #
     # @note Cluster mode only.
+    #
     # @example
-    #   on_worker_shutdown do
+    #   before_worker_shutdown do
     #     puts 'On worker shutdown...'
     #   end
-    def on_worker_shutdown(key = nil, &block)
-      warn_if_in_single_mode('on_worker_shutdown')
+    #
+    def before_worker_shutdown(key = nil, &block)
+      Puma.deprecate_method_change :on_worker_shutdown, __callee__, __method__
 
-      process_hook :before_worker_shutdown, key, block, 'on_worker_shutdown'
+      process_hook :before_worker_shutdown, key, block, cluster_only: true
     end
 
+    alias_method :on_worker_shutdown, :before_worker_shutdown
+
     # Code to run in the master right before a worker is started. The worker's
     # index is passed as an argument.
     #
     # This can be called multiple times to add several hooks.
     #
     # @note Cluster mode only.
+    #
     # @example
-    #   on_worker_fork do
+    #   before_worker_fork do
     #     puts 'Before worker fork...'
     #   end
-    def on_worker_fork(&block)
-      warn_if_in_single_mode('on_worker_fork')
+    #
+    def before_worker_fork(&block)
+      Puma.deprecate_method_change :on_worker_fork, __callee__, __method__
 
-      process_hook :before_worker_fork, nil, block, 'on_worker_fork'
+      process_hook :before_worker_fork, nil, block, cluster_only: true
     end
 
+    alias_method :on_worker_fork, :before_worker_fork
+
     # Code to run in the master after a worker has been started. The worker's
     # index is passed as an argument.
     #
     # This is called everytime a worker is to be started.
     #
     # @note Cluster mode only.
+    #
     # @example
     #   after_worker_fork do
     #     puts 'After worker fork...'
     #   end
+    #
     def after_worker_fork(&block)
-      warn_if_in_single_mode('after_worker_fork')
-
-      process_hook :after_worker_fork, nil, block, 'after_worker_fork'
+      process_hook :after_worker_fork, nil, block, cluster_only: true
     end
 
     alias_method :after_worker_boot, :after_worker_fork
 
-    # Code to run after puma is booted (works for both: single and clustered)
+    # 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
-    #   on_booted do
+    #   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
+    #   after_booted do
     #     puts 'After booting...'
     #   end
-    def on_booted(&block)
-      @config.options[:events].on_booted(&block)
+    #
+    def after_booted(&block)
+      Puma.deprecate_method_change :on_booted, __callee__, __method__
+
+      @config.events.after_booted(&block)
+    end
+
+    alias_method :on_booted, :after_booted
+
+    # Code to run after puma is stopped (works for both: single and clustered)
+    #
+    # @example
+    #   after_stopped do
+    #     puts 'After stopping...'
+    #   end
+    #
+    def after_stopped(&block)
+      Puma.deprecate_method_change :on_stopped, __callee__, __method__
+
+      @config.events.after_stopped(&block)
     end
+    alias_method :on_stopped, :after_stopped
 
     # When `fork_worker` is enabled, code to run in Worker 0
     # before all other workers are re-forked from this process,
@@ -719,14 +945,41 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @note Cluster mode with `fork_worker` enabled only.
+    #
     # @example
-    #   on_refork do
+    #   before_refork do
     #     3.times {GC.start}
     #   end
+    #
     # @version 5.0.0
     #
-    def on_refork(key = nil, &block)
-      process_hook :before_refork, key, block, 'on_refork'
+    def before_refork(key = nil, &block)
+      Puma.deprecate_method_change :on_refork, __callee__, __method__
+
+      process_hook :before_refork, key, block, cluster_only: true
+    end
+
+    alias_method :on_refork, :before_refork
+
+    # When `fork_worker` is enabled, code to run in Worker 0
+    # after all other workers are re-forked from this process,
+    # after the server has temporarily stopped serving requests
+    # (once per complete refork cycle).
+    #
+    # This can be used to re-open any connections to remote servers
+    # (database, Redis, ...) that were closed via before_refork.
+    #
+    # This can be called multiple times to add several hooks.
+    #
+    # @note Cluster mode with `fork_worker` enabled only.
+    #
+    # @example
+    #   after_refork do
+    #     puts 'After refork...'
+    #   end
+    #
+    def after_refork(key = nil, &block)
+      process_hook :after_refork, key, block
     end
 
     # Provide a block to be executed just before a thread is added to the thread
@@ -742,14 +995,18 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @example
-    #   on_thread_start do
+    #   before_thread_start do
     #     puts 'On thread start...'
     #   end
-    def on_thread_start(&block)
-      @options[:before_thread_start] ||= []
-      @options[:before_thread_start] << block
+    #
+    def before_thread_start(&block)
+      Puma.deprecate_method_change :on_thread_start, __callee__, __method__
+
+      process_hook :before_thread_start, nil, block
     end
 
+    alias_method :on_thread_start, :before_thread_start
+
     # Provide a block to be executed after a thread is trimmed from the thread
     # pool. Be careful: while this block executes, Puma's main loop is
     # blocked, so no new requests will be picked up.
@@ -766,14 +1023,18 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @example
-    #   on_thread_exit do
+    #   before_thread_exit do
     #     puts 'On thread exit...'
     #   end
-    def on_thread_exit(&block)
-      @options[:before_thread_exit] ||= []
-      @options[:before_thread_exit] << block
+    #
+    def before_thread_exit(&block)
+      Puma.deprecate_method_change :on_thread_exit, __callee__, __method__
+
+      process_hook :before_thread_exit, nil, block
     end
 
+    alias_method :on_thread_exit, :before_thread_exit
+
     # Code to run out-of-band when the worker is idle.
     # These hooks run immediately after a request has finished
     # processing and there are no busy threads on the worker.
@@ -783,8 +1044,9 @@ module Puma
     # or scheduling asynchronous tasks to execute after a response.
     #
     # This can be called multiple times to add several hooks.
+    #
     def out_of_band(&block)
-      process_hook :out_of_band, nil, block, 'out_of_band'
+      process_hook :out_of_band, nil, block
     end
 
     # The directory to operate out of.
@@ -793,16 +1055,22 @@ module Puma
     #
     # @example
     #   directory '/u/apps/lolcat'
+    #
     def directory(dir)
       @options[:directory] = dir.to_s
     end
 
-    # Preload the application before starting the workers; this conflicts with
-    # phased restart feature. On by default if your app uses more than 1 worker.
+    # Preload the application before forking the workers; this conflicts with
+    # the phased restart feature.
+    #
+    # 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!
+    #
     def preload_app!(answer=true)
       @options[:preload_app] = answer
     end
@@ -814,6 +1082,7 @@ module Puma
     #   lowlevel_error_handler do |err|
     #     [200, {}, ["error page"]]
     #   end
+    #
     def lowlevel_error_handler(obj=nil, &block)
       obj ||= block
       raise "Provide either a #call'able or a block" unless obj
@@ -833,23 +1102,27 @@ module Puma
     # new Bundler context and thus can float around as the release
     # dictates.
     #
-    # @see extra_runtime_dependencies
-    #
+    # @note Cluster mode only.
     # @note This is incompatible with +preload_app!+.
     # @note This is only supported for RubyGems 2.2+
+    #
+    # @see extra_runtime_dependencies
+    #
     def prune_bundler(answer=true)
       @options[:prune_bundler] = answer
     end
 
-    # By default, Puma will raise SignalException when SIGTERM is received. In
-    # environments where SIGTERM is something expected, you can suppress these
-    # with this option.
+    # Raises a SignalException when SIGTERM is received. In environments where
+    # SIGTERM is something expected, you can suppress these with this option.
     #
     # This can be useful for example in Kubernetes, where rolling restart is
-    # guaranteed usually on infrastructure level.
+    # guaranteed usually on the infrastructure level.
+    #
+    # The default is +true+.
     #
     # @example
     #   raise_exception_on_sigterm false
+    #
     # @see Puma::Launcher#setup_signals
     # @see Puma::Cluster#setup_signals
     #
@@ -868,6 +1141,7 @@ module Puma
     #   extra_runtime_dependencies ['gem_name_1', 'gem_name_2']
     # @example
     #   extra_runtime_dependencies ['puma_worker_killer', 'puma-heroku']
+    #
     # @see Puma::Launcher#extra_runtime_deps_directories
     #
     def extra_runtime_dependencies(answer = [])
@@ -879,21 +1153,26 @@ module Puma
     # If you do not specify a tag, Puma will infer it. If you do not want Puma
     # to add a tag, use an empty string.
     #
+    # The default is the current file or directory base name.
+    #
     # @example
     #   tag 'app name'
     # @example
     #   tag ''
+    #
     def tag(string)
       @options[:tag] = string.to_s
     end
 
     # Change the default interval for checking workers.
     #
-    # The default value is 5 seconds.
+    # The default is 5 seconds.
     #
     # @note Cluster mode only.
+    #
     # @example
-    #   worker_check_interval 5
+    #   worker_check_interval 10
+    #
     # @see Puma::Cluster#check_workers
     #
     def worker_check_interval(interval)
@@ -906,11 +1185,14 @@ module Puma
     # Setting this value will not protect against slow requests.
     #
     # This value must be greater than worker_check_interval.
-    # The default value is 60 seconds.
+    #
+    # The default is 60 seconds.
     #
     # @note Cluster mode only.
+    #
     # @example
     #   worker_timeout 60
+    #
     # @see Puma::Cluster::Worker#ping_timeout
     #
     def worker_timeout(timeout)
@@ -926,12 +1208,13 @@ module Puma
 
     # Change the default worker timeout for booting.
     #
-    # If unspecified, this defaults to the value of worker_timeout.
+    # The default is 60 seconds.
     #
     # @note Cluster mode only.
     #
     # @example
     #   worker_boot_timeout 60
+    #
     # @see Puma::Cluster::Worker#ping_timeout
     #
     def worker_boot_timeout(timeout)
@@ -940,7 +1223,13 @@ module Puma
 
     # Set the timeout for worker shutdown.
     #
+    # The default is 30 seconds.
+    #
     # @note Cluster mode only.
+    #
+    # @example
+    #   worker_shutdown_timeout 90
+    #
     # @see Puma::Cluster::Worker#term
     #
     def worker_shutdown_timeout(timeout)
@@ -956,22 +1245,26 @@ module Puma
     # 2. **:oldest** - the oldest workers (i.e. the workers that were started
     #    the longest time ago) will be culled.
     #
+    # The default is +:youngest+.
+    #
     # @note Cluster mode only.
+    #
     # @example
     #   worker_culling_strategy :oldest
+    #
     # @see Puma::Cluster#cull_workers
     #
     def worker_culling_strategy(strategy)
-      stategy = strategy.to_sym
+      strategy = strategy.to_sym
 
       if ![:youngest, :oldest].include?(strategy)
-        raise "Invalid value for worker_culling_strategy - #{stategy}"
+        raise "Invalid value for worker_culling_strategy - #{strategy}"
       end
 
       @options[:worker_culling_strategy] = strategy
     end
 
-    # When set to true (the default), workers accept all requests
+    # When set to true, workers accept all requests
     # and queue them before passing them to the handlers.
     # When set to false, each worker process accepts exactly as
     # many requests as it is configured to simultaneously handle.
@@ -984,7 +1277,11 @@ module Puma
     # slow clients will occupy a handler thread while the request
     # is being sent. A reverse proxy, such as nginx, can handle
     # slow clients and queue requests before they reach Puma.
+    #
+    # The default is +true+.
+    #
     # @see Puma::Server
+    #
     def queue_requests(answer=true)
       @options[:queue_requests] = answer
     end
@@ -993,19 +1290,30 @@ module Puma
     # threads will be written to $stdout. This can help figure
     # out why shutdown is hanging.
     #
-    def shutdown_debug(val=true)
-      @options[:shutdown_debug] = val
+    # If `on_force` is true, the backtraces will be written only
+    # when the shutdown is forced i.e. not graceful.
+    #
+    # @see force_shutdown_after
+    def shutdown_debug(val = true, on_force: false)
+      @options[:shutdown_debug] = val && on_force ? :on_force : val
     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.
     #
-    # Only works on MRI. For all other interpreters, this setting does nothing.
+    # The default is 0.005 seconds.
+    #
+    # 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
-    # @version 5.0.0
     #
     def wait_for_less_busy_worker(val=0.005)
       @options[:wait_for_less_busy_worker] = val.to_f
@@ -1018,7 +1326,7 @@ module Puma
     #
     # There are 5 possible values:
     #
-    # 1. **:socket** (the default) - read the peername from the socket using the
+    # 1. **:socket** - read the peername from the socket using the
     #    syscall. This is the normal behavior. If this fails for any reason (e.g.,
     #    if the peer disconnects between the connection being accepted and the getpeername
     #    system call), Puma will return "0.0.0.0"
@@ -1036,6 +1344,11 @@ module Puma
     #    you wish. Because Puma never uses this field anyway, it's format is
     #    entirely in your hands.
     #
+    # The default is +:socket+.
+    #
+    # @example
+    #   set_remote_address :localhost
+    #
     def set_remote_address(val=:socket)
       case val
       when :socket
@@ -1075,18 +1388,57 @@ module Puma
     # A refork will automatically trigger once after the specified number of requests
     # (default 1000), or pass 0 to disable auto refork.
     #
+    # @note This is experimental.
     # @note Cluster mode only.
-    # @version 5.0.0
     #
     def fork_worker(after_requests=1000)
       @options[:fork_worker] = Integer(after_requests)
     end
 
-    # The number of requests to attempt inline before sending a client back to
-    # the reactor to be subject to normal ordering.
+    # @deprecated Use {#max_keep_alive} instead.
     #
     def max_fast_inline(num_of_requests)
-      @options[:max_fast_inline] = Float(num_of_requests)
+      Puma.deprecate_method_change :max_fast_inline, __method__, :max_keep_alive
+      @options[:max_keep_alive] ||= Float(num_of_requests) unless num_of_requests.nil?
+    end
+
+    # The number of requests a keep-alive client can submit before being closed.
+    # Note that some applications (server to server) may benefit from a very high
+    # number or Float::INFINITY.
+    #
+    # The default is 999.
+    #
+    # @example
+    #   max_keep_alive 20
+    #
+    def max_keep_alive(num_of_requests)
+      @options[:max_keep_alive] = Float(num_of_requests) unless num_of_requests.nil?
+    end
+
+    # When `true`, keep-alive connections are maintained on inbound requests.
+    # Enabling this setting reduces the number of TCP operations, reducing response
+    # times for connections that can send multiple requests in a single connection.
+    #
+    # When Puma receives more incoming connections than available Puma threads,
+    # enabling the keep-alive behavior may result in processing requests out-of-order,
+    # increasing overall response time variance. Increased response time variance
+    # means that the overall average of response times might not change, but more
+    # outliers will exist. Those long-tail outliers may significantly affect response
+    # times for some processed requests.
+    #
+    # When `false`, Puma closes the connection after each request, requiring the
+    # client to open a new request. Disabling this setting guarantees that requests
+    # will be processed in the order they are fully received, decreasing response
+    # variance and eliminating long-tail outliers caused by keep-alive behavior.
+    # The trade-off is that the number of TCP operations required will increase.
+    #
+    # The default is +true+.
+    #
+    # @example
+    #   enable_keep_alives false
+    #
+    def enable_keep_alives(enabled=true)
+      @options[:enable_keep_alives] = enabled
     end
 
     # Specify the backend for the IO selector.
@@ -1102,12 +1454,20 @@ 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
     end
 
+    # Ensures +STDOUT+ and +STDERR+ is immediately flushed to the underlying
+    # operating system and is not buffered internally
+    #
+    # The default is +true+.
+    #
+    # @example
+    #   mutate_stdout_and_stderr_to_sync_on_write false
+    #
     def mutate_stdout_and_stderr_to_sync_on_write(enabled=true)
       @options[:mutate_stdout_and_stderr_to_sync_on_write] = enabled
     end
@@ -1119,8 +1479,12 @@ module Puma
     #
     # When no Content-Length http header is present, it is compared against the
     # size of the body of the request.
-     #
-    # The default value for http_content_length_limit is nil.
+    #
+    # The default is +nil+.
+    #
+    # @example
+    #   http_content_length_limit 2_000_000_000
+    #
     def http_content_length_limit(limit)
       @options[:http_content_length_limit] = limit
     end
@@ -1161,6 +1525,7 @@ module Puma
 
     # To avoid adding cert_pem and key_pem as URI params, we store them on the
     # options[:store] from where Puma binder knows how to find and extract them.
+    #
     def add_pem_values_to_options_store(opts)
       return if defined?(JRUBY_VERSION)
 
@@ -1177,30 +1542,21 @@ module Puma
       end
     end
 
-    def process_hook(options_key, key, block, meth)
+    def process_hook(options_key, key, block, cluster_only: false)
+      raise ArgumentError, "expected #{options_key} to be given a block" unless block
+
+      @config.hooks[options_key] = true
+
       @options[options_key] ||= []
-      if ON_WORKER_KEY.include? key.class
-        @options[options_key] << [block, key.to_sym]
+      hook_options = { block: block, cluster_only: cluster_only }
+      hook_options[:id] = if ON_WORKER_KEY.include?(key.class)
+        key.to_sym
       elsif key.nil?
-        @options[options_key] << block
+        nil
       else
-        raise "'#{meth}' key must be String or Symbol"
-      end
-    end
-
-    def warn_if_in_single_mode(hook_name)
-      return if @options[:silence_fork_callback_warning]
-      # user_options (CLI) have precedence over config file
-      workers_val = @config.options.user_options[:workers] || @options[:workers] ||
-        @config.puma_default_options[:workers] || 0
-      if workers_val == 0
-        log_string =
-          "Warning: You specified code to run in a `#{hook_name}` block, " \
-          "but Puma is not configured to run in cluster mode (worker count > 0 ), " \
-          "so your `#{hook_name}` block did not run"
-
-        LogWriter.stdio.log(log_string)
+        raise "'#{options_key}' key must be String or Symbol"
       end
+      @options[options_key] << hook_options
     end
   end
 end