puma 4.3.12 → 6.0.2

data/lib/puma/dsl.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'puma/const'
+require_relative 'const'
+require_relative 'util'
 
 module Puma
   # The methods that are available for use inside the configuration file.
@@ -14,24 +15,108 @@ module Puma
   #   end
   #   config.load
   #
-  #   puts config.options[:binds]
-  #   "tcp://127.0.0.1:3001"
+  #   puts config.options[:binds] # => "tcp://127.0.0.1:3001"
   #
   # Used to load file:
   #
   #   $ cat puma_config.rb
-  #     port 3002
+  #   port 3002
+  #
+  # Resulting configuration:
   #
   #   config = Configuration.new(config_file: "puma_config.rb")
   #   config.load
   #
-  #   puts config.options[:binds]
-  #   # => "tcp://127.0.0.1:3002"
+  #   puts config.options[:binds] # => "tcp://127.0.0.1:3002"
   #
   # You can also find many examples being used by the test suite in
   # +test/config+.
+  #
+  # Puma v6 adds the option to specify a key name (String or Symbol) to the
+  # hooks that run inside the forked workers.  All the hooks run inside the
+  # {Puma::Cluster::Worker#run} method.
+  #
+  # Previously, the worker index and the LogWriter instance were passed to the
+  # hook blocks/procs.  If a key name is specified, a hash is passed as the last
+  # parameter.  This allows storage of data, typically objects that are created
+  # before the worker that need to be passed to the hook when the worker is shutdown.
+  #
+  # 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              |
+  #
   class DSL
-    include ConfigDefault
+    ON_WORKER_KEY = [String, Symbol].freeze
+
+    # convenience method so logic can be used in CI
+    # @see ssl_bind
+    #
+    def self.ssl_bind_str(host, port, opts)
+      verify = opts.fetch(:verify_mode, 'none').to_s
+
+      tls_str =
+        if opts[:no_tlsv1_1]  then '&no_tlsv1_1=true'
+        elsif opts[:no_tlsv1] then '&no_tlsv1=true'
+        else ''
+        end
+
+      ca_additions = "&ca=#{Puma::Util.escape(opts[:ca])}" if ['peer', 'force_peer'].include?(verify)
+
+      backlog_str = opts[:backlog] ? "&backlog=#{Integer(opts[:backlog])}" : ''
+
+      if defined?(JRUBY_VERSION)
+        cipher_suites = opts[:ssl_cipher_list] ? "&ssl_cipher_list=#{opts[:ssl_cipher_list]}" : nil # old name
+        cipher_suites = "#{cipher_suites}&cipher_suites=#{opts[:cipher_suites]}" if opts[:cipher_suites]
+        protocols = opts[:protocols] ? "&protocols=#{opts[:protocols]}" : nil
+
+        keystore_additions = "keystore=#{opts[:keystore]}&keystore-pass=#{opts[:keystore_pass]}"
+        keystore_additions = "#{keystore_additions}&keystore-type=#{opts[:keystore_type]}" if opts[:keystore_type]
+        if opts[:truststore]
+          truststore_additions = "&truststore=#{opts[:truststore]}"
+          truststore_additions = "#{truststore_additions}&truststore-pass=#{opts[:truststore_pass]}" if opts[:truststore_pass]
+          truststore_additions = "#{truststore_additions}&truststore-type=#{opts[:truststore_type]}" if opts[:truststore_type]
+        end
+
+        "ssl://#{host}:#{port}?#{keystore_additions}#{truststore_additions}#{cipher_suites}#{protocols}" \
+          "&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
+        v_flags = (ary = opts[:verification_flags]) ? "&verification_flags=#{Array(ary).join ','}" : nil
+
+        cert_flags = (cert = opts[:cert]) ? "cert=#{Puma::Util.escape(cert)}" : nil
+        key_flags = (key = opts[:key]) ? "&key=#{Puma::Util.escape(key)}" : nil
+
+        reuse_flag =
+          if (reuse = opts[:reuse])
+            if reuse == true
+              '&reuse=dflt'
+            elsif reuse.is_a?(Hash) && (reuse.key?(:size) || reuse.key?(:timeout))
+              val = +''
+              if (size = reuse[:size]) && Integer === size
+                val << size.to_s
+              end
+              if (timeout = reuse[:timeout]) && Integer === timeout
+                val << ",#{timeout}"
+              end
+              if val.empty?
+                nil
+              else
+                "&reuse=#{val}"
+              end
+            else
+              nil
+            end
+          else
+            nil
+          end
+
+        "ssl://#{host}:#{port}?#{cert_flags}#{key_flags}#{ssl_cipher_filter}" \
+          "#{reuse_flag}&verify_mode=#{verify}#{tls_str}#{ca_additions}#{v_flags}#{backlog_str}"
+      end
+    end
 
     def initialize(options, config)
       @config  = config
@@ -65,7 +150,7 @@ module Puma
     end
 
     def default_host
-      @options[:default_host] || Configuration::DefaultTCPHost
+      @options[:default_host] || Configuration::DEFAULTS[:tcp_host]
     end
 
     def inject(&blk)
@@ -98,6 +183,9 @@ module Puma
     #       [body]
     #     ]
     #   end
+    #
+    # @see Puma::Configuration#app
+    #
     def app(obj=nil, &block)
       obj ||= block
 
@@ -153,28 +241,34 @@ module Puma
     end
 
     # Bind the server to +url+. "tcp://", "unix://" and "ssl://" are the only
-    # accepted protocols. Multiple urls can be bound to, calling `bind` does
+    # accepted protocols. Multiple urls can be bound to, calling +bind+ does
     # not overwrite previous bindings.
     #
     # The default is "tcp://0.0.0.0:9292".
     #
     # You can use query parameters within the url to specify options:
     #
-    #  - Set the socket backlog depth with +backlog+, default is 1024.
-    #  - Set up an SSL certificate with +key+ & +cert+.
-    #  - Set whether to optimize for low latency instead of throughput with
-    #    +low_latency+, default is to optimize for low latency. This is done
-    #    via +Socket::TCP_NODELAY+.
-    #  - Set socket permissions with +umask+.
+    # * Set the socket backlog depth with +backlog+, default is 1024.
+    # * Set up an SSL certificate with +key+ & +cert+.
+    # * Set up an SSL certificate for mTLS with +key+, +cert+, +ca+ and +verify_mode+.
+    # * Set whether to optimize for low latency instead of throughput with
+    #   +low_latency+, default is to not optimize for low latency. This is done
+    #   via +Socket::TCP_NODELAY+.
+    # * Set socket permissions with +umask+.
     #
     # @example Backlog depth
     #   bind 'unix:///var/run/puma.sock?backlog=512'
     # @example SSL cert
     #   bind 'ssl://127.0.0.1:9292?key=key.key&cert=cert.pem'
+    # @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'
     # @example Socket permissions
     #   bind 'unix:///var/run/puma.sock?umask=0111'
+    # @see Puma::Runner#load_and_bind
+    # @see Puma::Cluster#run
+    #
     def bind(url)
       @options[:binds] ||= []
       @options[:binds] << url
@@ -184,22 +278,49 @@ module Puma
       @options[:binds] = []
     end
 
+    # Bind to (systemd) activated sockets, regardless of configured binds.
+    #
+    # Systemd can present sockets as file descriptors that are already opened.
+    # By default Puma will use these but only if it was explicitly told to bind
+    # to the socket. If not, it will close the activated sockets. This means
+    # all configuration is duplicated.
+    #
+    # Binds can contain additional configuration, but only SSL config is really
+    # relevant since the unix and TCP socket options are ignored.
+    #
+    # This means there is a lot of duplicated configuration for no additional
+    # value in most setups. This method tells the launcher to bind to all
+    # activated sockets, regardless of existing bind.
+    #
+    # To clear configured binds, the value only can be passed. This will clear
+    # out any binds that may have been configured.
+    #
+    # @example Use any systemd activated sockets as well as configured binds
+    #   bind_to_activated_sockets
+    #
+    # @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.
     #
     # @example
     #   port 9292
     def port(port, host=nil)
       host ||= default_host
-      bind "tcp://#{host}:#{port}"
+      bind URI::Generic.build(scheme: 'tcp', host: host, port: Integer(port)).to_s
     end
 
-    # Define how long persistent connections can be idle before Puma closes
-    # them.
+    # Define how long persistent connections can be idle before Puma closes them.
+    # @see Puma::Server.new
     def persistent_timeout(seconds)
       @options[:persistent_timeout] = Integer(seconds)
     end
 
     # Define how long the tcp socket stays open, if no data has been received.
+    # @see Puma::Server.new
     def first_data_timeout(seconds)
       @options[:first_data_timeout] = Integer(seconds)
     end
@@ -210,24 +331,11 @@ module Puma
       @options[:clean_thread_locals] = which
     end
 
-    # Daemonize the server into the background. It's highly recommended to
-    # use this in combination with +pidfile+ and +stdout_redirect+.
-    #
-    # The default is "false".
-    #
-    # @example
-    #   daemonize
+    # 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
     #
-    # @example
-    #   daemonize false
-    def daemonize(which=true)
-      @options[:daemon] = which
-    end
-
-    # 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.
     def drain_on_shutdown(which=true)
       @options[:drain_on_shutdown] = which
     end
@@ -250,6 +358,7 @@ module Puma
     #
     # Puma always waits a few seconds after killing a thread for it to try
     # to finish up it's work, even in :immediately mode.
+    # @see Puma::Server#graceful_shutdown
     def force_shutdown_after(val=:forever)
       i = case val
           when :forever
@@ -257,7 +366,7 @@ module Puma
           when :immediately
             0
           else
-            Integer(val)
+            Float(val)
           end
 
       @options[:force_shutdown_after] = i
@@ -322,20 +431,21 @@ module Puma
     # @example
     #   rackup '/u/apps/lolcat/config.ru'
     def rackup(path)
-      @options[:rackup] = path.to_s
+      @options[:rackup] ||= path.to_s
     end
 
-    # Run Puma in TCP mode
-    #
-    def tcp_mode!
-      @options[:mode] = :tcp
+    # 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
 
     def early_hints(answer=true)
       @options[:early_hints] = answer
     end
 
-    # Redirect STDOUT and STDERR to files specified. The +append+ parameter
+    # Redirect +STDOUT+ and +STDERR+ to files specified. The +append+ parameter
     # specifies whether the output is appended, the default is +false+.
     #
     # @example
@@ -355,7 +465,10 @@ module Puma
     # Configure +min+ to be the minimum number of threads to use to answer
     # requests and +max+ the maximum.
     #
-    # The default is "0, 16".
+    # The default is the environment variables +PUMA_MIN_THREADS+ / +PUMA_MAX_THREADS+
+    # (or +MIN_THREADS+ / +MAX_THREADS+ if the +PUMA_+ variables aren't set).
+    #
+    # If these environment variables aren't set, the default is "0, 5" in MRI or "0, 16" for other interpreters.
     #
     # @example
     #   threads 0, 16
@@ -376,8 +489,19 @@ module Puma
       @options[:max_threads] = max
     end
 
-    # Instead of "bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'" you
-    # can also use the "ssl_bind" option.
+    # Instead of using +bind+ and manually constructing a URI like:
+    #
+    #    bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'
+    #
+    # you can use the this method.
+    #
+    # When binding on localhost you don't need to specify +cert+ and +key+,
+    # Puma will assume you are using the +localhost+ gem and try to load the
+    # appropriate files.
+    #
+    # When using the options hash parameter, the `reuse:` value is either
+    # `true`, which sets reuse 'on' with default values, or a hash, with `:size`
+    # and/or `:timeout` keys, each with integer values.
     #
     # @example
     #   ssl_bind '127.0.0.1', '9292', {
@@ -385,29 +509,30 @@ module Puma
     #     key: path_to_key,
     #     ssl_cipher_filter: cipher_filter, # optional
     #     verify_mode: verify_mode,         # default 'none'
+    #     verification_flags: flags,        # optional, not supported by JRuby
+    #     reuse: true                       # optional
     #   }
-    # @example For JRuby additional keys are required: keystore & keystore_pass.
+    #
+    # @example Using self-signed certificate with the +localhost+ gem:
+    #   ssl_bind '127.0.0.1', '9292'
+    #
+    # @example Alternatively, you can provide +cert_pem+ and +key_pem+:
+    #   ssl_bind '127.0.0.1', '9292', {
+    #     cert_pem: File.read(path_to_cert),
+    #     key_pem: File.read(path_to_key),
+    #     reuse: {size: 2_000, timeout: 20} # optional
+    #   }
+    #
+    # @example For JRuby, two keys are required: +keystore+ & +keystore_pass+
     #   ssl_bind '127.0.0.1', '9292', {
-    #     cert: path_to_cert,
-    #     key: path_to_key,
-    #     ssl_cipher_filter: cipher_filter, # optional
-    #     verify_mode: verify_mode,         # default 'none'
     #     keystore: path_to_keystore,
-    #     keystore_pass: password
+    #     keystore_pass: password,
+    #     ssl_cipher_list: cipher_list,     # optional
+    #     verify_mode: verify_mode          # default 'none'
     #   }
-    def ssl_bind(host, port, opts)
-      verify = opts.fetch(:verify_mode, 'none').to_s
-      no_tlsv1 = opts.fetch(:no_tlsv1, 'false')
-      no_tlsv1_1 = opts.fetch(:no_tlsv1_1, 'false')
-      ca_additions = "&ca=#{opts[:ca]}" if ['peer', 'force_peer'].include?(verify)
-
-      if defined?(JRUBY_VERSION)
-        keystore_additions = "keystore=#{opts[:keystore]}&keystore-pass=#{opts[:keystore_pass]}"
-        bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}&#{keystore_additions}&verify_mode=#{verify}&no_tlsv1=#{no_tlsv1}&no_tlsv1_1=#{no_tlsv1_1}#{ca_additions}"
-      else
-        ssl_cipher_filter = "&ssl_cipher_filter=#{opts[:ssl_cipher_filter]}" if opts[:ssl_cipher_filter]
-        bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}#{ssl_cipher_filter}&verify_mode=#{verify}&no_tlsv1=#{no_tlsv1}&no_tlsv1_1=#{no_tlsv1_1}#{ca_additions}"
-      end
+    def ssl_bind(host, port, opts = {})
+      add_pem_values_to_options_store(opts)
+      bind self.class.ssl_bind_str(host, port, opts)
     end
 
     # Use +path+ as the file to store the server info state. This is
@@ -419,16 +544,46 @@ module Puma
       @options[:state] = path.to_s
     end
 
+    # Use +permission+ to restrict permissions for the state file.
+    #
+    # @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
-    # to the number of available cores.
+    # the number of available cores.
     #
-    # The default is 0.
+    # The default is the value of the environment variable +WEB_CONCURRENCY+ if
+    # set, otherwise 0.
     #
     # @note Cluster mode only.
+    # @see Puma::Cluster
     def workers(count)
       @options[:workers] = count.to_i
     end
 
+    # Disable warning message when running in cluster mode with a single worker.
+    #
+    # Cluster mode has some overhead of running an additional 'control' process
+    # in order to manage the cluster. If only running a single worker it is
+    # likely not worth paying that overhead vs running in single mode with
+    # additional threads instead.
+    #
+    # There are some scenarios where running cluster mode with a single worker
+    # may still be warranted and valid under certain deployment scenarios, see
+    # https://github.com/puma/puma/issues/2534
+    #
+    # Moving from workers = 1 to workers = 0 will save 10-30% of memory use.
+    #
+    # @note Cluster mode only.
+    def silence_single_worker_warning
+      @options[:silence_single_worker_warning] = true
+    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
@@ -455,12 +610,11 @@ module Puma
     #
     # @note Cluster mode only.
     # @example
-    #   on_worker_fork do
-    #     puts 'Before worker fork...'
+    #   on_worker_boot do
+    #     puts 'Before worker boot...'
     #   end
-    def on_worker_boot(&block)
-      @options[:before_worker_boot] ||= []
-      @options[:before_worker_boot] << block
+    def on_worker_boot(key = nil, &block)
+      process_hook :before_worker_boot, key, block, 'on_worker_boot'
     end
 
     # Code to run immediately before a worker shuts
@@ -475,9 +629,8 @@ module Puma
     #   on_worker_shutdown do
     #     puts 'On worker shutdown...'
     #   end
-    def on_worker_shutdown(&block)
-      @options[:before_worker_shutdown] ||= []
-      @options[:before_worker_shutdown] << block
+    def on_worker_shutdown(key = nil, &block)
+      process_hook :before_worker_shutdown, key, block, 'on_worker_shutdown'
     end
 
     # Code to run in the master right before a worker is started. The worker's
@@ -491,8 +644,7 @@ module Puma
     #     puts 'Before worker fork...'
     #   end
     def on_worker_fork(&block)
-      @options[:before_worker_fork] ||= []
-      @options[:before_worker_fork] << block
+      process_hook :before_worker_fork, nil, block, 'on_worker_fork'
     end
 
     # Code to run in the master after a worker has been started. The worker's
@@ -506,12 +658,33 @@ module Puma
     #     puts 'After worker fork...'
     #   end
     def after_worker_fork(&block)
-      @options[:after_worker_fork] ||= []
-      @options[:after_worker_fork] = block
+      process_hook :after_worker_fork, nil, block, 'after_worker_fork'
     end
 
     alias_method :after_worker_boot, :after_worker_fork
 
+    # When `fork_worker` is enabled, code to run in Worker 0
+    # before 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 trigger extra garbage-collection to maximize
+    # copy-on-write efficiency, or close any connections to remote servers
+    # (database, Redis, ...) that were opened while the server was running.
+    #
+    # This can be called multiple times to add several hooks.
+    #
+    # @note Cluster mode with `fork_worker` enabled only.
+    # @example
+    #   on_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'
+    end
+
     # 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.
@@ -522,8 +695,7 @@ module Puma
     #
     # This can be called multiple times to add several hooks.
     def out_of_band(&block)
-      @options[:out_of_band] ||= []
-      @options[:out_of_band] << block
+      process_hook :out_of_band, nil, block, 'out_of_band'
     end
 
     # The directory to operate out of.
@@ -536,19 +708,8 @@ module Puma
       @options[:directory] = dir.to_s
     end
 
-    # DEPRECATED: The directory to operate out of.
-    def worker_directory(dir)
-      $stderr.puts "worker_directory is deprecated. Please use `directory`"
-      directory dir
-    end
-
-    # Run the app as a raw TCP app instead of an HTTP rack app.
-    def tcp_mode
-      @options[:mode] = :tcp
-    end
-
     # Preload the application before starting the workers; this conflicts with
-    # phased restart feature. This is off by default.
+    # phased restart feature. On by default if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
     # @example
@@ -583,7 +744,7 @@ module Puma
     # new Bundler context and thus can float around as the release
     # dictates.
     #
-    # See also: extra_runtime_dependencies
+    # @see extra_runtime_dependencies
     #
     # @note This is incompatible with +preload_app!+.
     # @note This is only supported for RubyGems 2.2+
@@ -600,6 +761,9 @@ module Puma
     #
     # @example
     #   raise_exception_on_sigterm false
+    # @see Puma::Launcher#setup_signals
+    # @see Puma::Cluster#setup_signals
+    #
     def raise_exception_on_sigterm(answer=true)
       @options[:raise_exception_on_sigterm] = answer
     end
@@ -615,6 +779,8 @@ 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 = [])
       @options[:extra_runtime_dependencies] = Array(answer)
     end
@@ -632,6 +798,19 @@ module Puma
       @options[:tag] = string.to_s
     end
 
+    # Change the default interval for checking workers.
+    #
+    # The default value is 5 seconds.
+    #
+    # @note Cluster mode only.
+    # @example
+    #   worker_check_interval 5
+    # @see Puma::Cluster#check_workers
+    #
+    def worker_check_interval(interval)
+      @options[:worker_check_interval] = Integer(interval)
+    end
+
     # Verifies that all workers have checked in to the master process within
     # the given timeout. If not the worker process will be restarted. This is
     # not a request timeout, it is to protect against a hung or dead process.
@@ -642,9 +821,11 @@ module Puma
     # @note Cluster mode only.
     # @example
     #   worker_timeout 60
+    # @see Puma::Cluster::Worker#ping_timeout
+    #
     def worker_timeout(timeout)
       timeout = Integer(timeout)
-      min = Const::WORKER_CHECK_INTERVAL
+      min = @options.fetch(:worker_check_interval, Configuration::DEFAULTS[:worker_check_interval])
 
       if timeout <= min
         raise "The minimum worker_timeout must be greater than the worker reporting interval (#{min})"
@@ -658,19 +839,48 @@ module Puma
     # If unspecified, this defaults to the value of worker_timeout.
     #
     # @note Cluster mode only.
-    # @example:
+    #
+    # @example
     #   worker_boot_timeout 60
+    # @see Puma::Cluster::Worker#ping_timeout
+    #
     def worker_boot_timeout(timeout)
       @options[:worker_boot_timeout] = Integer(timeout)
     end
 
-    # Set the timeout for worker shutdown
+    # Set the timeout for worker shutdown.
     #
     # @note Cluster mode only.
+    # @see Puma::Cluster::Worker#term
+    #
     def worker_shutdown_timeout(timeout)
       @options[:worker_shutdown_timeout] = Integer(timeout)
     end
 
+    # Set the strategy for worker culling.
+    #
+    # There are two possible values:
+    #
+    # 1. **:youngest** - the youngest workers (i.e. the workers that were
+    #    the most recently started) will be culled.
+    # 2. **:oldest** - the oldest workers (i.e. the workers that were started
+    #    the longest time ago) will be culled.
+    #
+    # @note Cluster mode only.
+    # @example
+    #   worker_culling_strategy :oldest
+    # @see Puma::Cluster#cull_workers
+    #
+    def worker_culling_strategy(strategy)
+      stategy = strategy.to_sym
+
+      if ![:youngest, :oldest].include?(strategy)
+        raise "Invalid value for worker_culling_strategy - #{stategy}"
+      end
+
+      @options[:worker_culling_strategy] = strategy
+    end
+
     # When set to true (the default), workers accept all requests
     # and queue them before passing them to the handlers.
     # When set to false, each worker process accepts exactly as
@@ -684,6 +894,7 @@ 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.
+    # @see Puma::Server
     def queue_requests(answer=true)
       @options[:queue_requests] = answer
     end
@@ -691,29 +902,50 @@ module Puma
     # When a shutdown is requested, the backtraces of all the
     # threads will be written to $stdout. This can help figure
     # out why shutdown is hanging.
+    #
     def shutdown_debug(val=true)
       @options[:shutdown_debug] = 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
+    # requests to pick up new requests first.
+    #
+    # Only works on MRI. For all other interpreters, this setting does nothing.
+    # @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
+    end
+
     # Control how the remote address of the connection is set. This
     # is configurable because to calculate the true socket peer address
     # a kernel syscall is required which for very fast rack handlers
     # slows down the handling significantly.
     #
-    # There are 4 possible values:
-    #
-    # * :socket (the default) - read the peername from the socket using the
-    #           syscall. This is the normal behavior.
-    # * :localhost - set the remote address to "127.0.0.1"
-    # * header: http_header - set the remote address to the value of the
-    #                          provided http header. For instance:
-    #                          `set_remote_address header: "X-Real-IP"`.
-    #                          Only the first word (as separated by spaces or comma)
-    #                          is used, allowing headers such as X-Forwarded-For
-    #                          to be used as well.
-    # * Any string - this allows you to hardcode remote address to any value
-    #                you wish. Because Puma never uses this field anyway, it's
-    #                format is entirely in your hands.
+    # There are 5 possible values:
+    #
+    # 1. **:socket** (the default) - 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"
+    # 2. **:localhost** - set the remote address to "127.0.0.1"
+    # 3. **header: <http_header>**- set the remote address to the value of the
+    #    provided http header. For instance:
+    #    `set_remote_address header: "X-Real-IP"`.
+    #    Only the first word (as separated by spaces or comma) is used, allowing
+    #    headers such as X-Forwarded-For to be used as well. If this header is absent,
+    #    Puma will fall back to the behavior of :socket
+    # 4. **proxy_protocol: :v1**- set the remote address to the value read from the
+    #    HAproxy PROXY protocol, version 1. If the request does not have the PROXY
+    #    protocol attached to it, will fall back to :socket
+    # 5. **\<Any string\>** - this allows you to hardcode remote address to any value
+    #    you wish. Because Puma never uses this field anyway, it's format is
+    #    entirely in your hands.
+    #
     def set_remote_address(val=:socket)
       case val
       when :socket
@@ -728,6 +960,13 @@ module Puma
         if hdr = val[:header]
           @options[:remote_address] = :header
           @options[:remote_address_header] = "HTTP_" + hdr.upcase.tr("-", "_")
+        elsif protocol_version = val[:proxy_protocol]
+          @options[:remote_address] = :proxy_protocol
+          protocol_version = protocol_version.downcase.to_sym
+          unless [:v1].include?(protocol_version)
+            raise "Invalid value for proxy_protocol - #{protocol_version.inspect}"
+          end
+          @options[:remote_address_proxy_protocol] = protocol_version
         else
           raise "Invalid value for set_remote_address - #{val.inspect}"
         end
@@ -736,5 +975,82 @@ module Puma
       end
     end
 
+    # When enabled, workers will be forked from worker 0 instead of from the master process.
+    # This option is similar to `preload_app` because the app is preloaded before forking,
+    # but it is compatible with phased restart.
+    #
+    # This option also enables the `refork` command (SIGURG), which optimizes copy-on-write performance
+    # in a running app.
+    #
+    # A refork will automatically trigger once after the specified number of requests
+    # (default 1000), or pass 0 to disable auto refork.
+    #
+    # @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.
+    #
+    def max_fast_inline(num_of_requests)
+      @options[:max_fast_inline] = Float(num_of_requests)
+    end
+
+    # Specify the backend for the IO selector.
+    #
+    # Provided values will be passed directly to +NIO::Selector.new+, with the
+    # exception of +:auto+ which will let nio4r choose the backend.
+    #
+    # Check the documentation of +NIO::Selector.backends+ for the list of valid
+    # options. Note that the available options on your system will depend on the
+    # operating system. If you want to use the pure Ruby backend (not
+    # recommended due to its comparatively low performance), set environment
+    # variable +NIO4R_PURE+ to +true+.
+    #
+    # The default is +:auto+.
+    #
+    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    #
+    def io_selector_backend(backend)
+      @options[:io_selector_backend] = backend.to_sym
+    end
+
+    def mutate_stdout_and_stderr_to_sync_on_write(enabled=true)
+      @options[:mutate_stdout_and_stderr_to_sync_on_write] = enabled
+    end
+
+    private
+
+    # 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)
+
+      @options[:store] ||= []
+
+      # Store cert_pem and key_pem to options[:store] if present
+      [:cert, :key].each do |v|
+        opt_key = :"#{v}_pem"
+        if opts[opt_key]
+          index = @options[:store].length
+          @options[:store] << opts[opt_key]
+          opts[v] = "store:#{index}"
+        end
+      end
+    end
+
+    def process_hook(options_key, key, block, meth)
+      @options[options_key] ||= []
+      if ON_WORKER_KEY.include? key.class
+        @options[options_key] << [block, key.to_sym]
+      elsif key.nil?
+        @options[options_key] << block
+      else
+        raise "'#{method}' key must be String or Symbol"
+      end
+    end
   end
 end