puma 4.1.1 → 5.0.0

data/lib/puma/commonlogger.rb

@@ -3,7 +3,7 @@
 module Puma
   # Rack::CommonLogger forwards every request to the given +app+, and
   # logs a line in the
-  # {Apache common log format}[http://httpd.apache.org/docs/1.3/logs.html#common]
+  # {Apache common log format}[https://httpd.apache.org/docs/1.3/logs.html#common]
   # to the +logger+.
   #
   # If +logger+ is nil, CommonLogger will fall back +rack.errors+, which is
@@ -16,7 +16,7 @@ module Puma
   # (which is called without arguments in order to make the error appear for
   # sure)
   class CommonLogger
-    # Common Log Format: http://httpd.apache.org/docs/1.3/logs.html#common
+    # Common Log Format: https://httpd.apache.org/docs/1.3/logs.html#common
     #
     #   lilith.local - - [07/Aug/2006 23:58:02 -0400] "GET / HTTP/1.1" 500 -
     #

data/lib/puma/configuration.rb

@@ -54,9 +54,7 @@ module Puma
     attr_reader :user_options, :file_options, :default_options
 
     def [](key)
-      return user_options[key]    if user_options.key?(key)
-      return file_options[key]    if file_options.key?(key)
-      return default_options[key] if default_options.key?(key)
+      fetch(key)
     end
 
     def []=(key, value)
@@ -64,7 +62,11 @@ module Puma
     end
 
     def fetch(key, default_value = nil)
-      self[key] || default_value
+      return user_options[key]    if user_options.key?(key)
+      return file_options[key]    if file_options.key?(key)
+      return default_options[key] if default_options.key?(key)
+
+      default_value
     end
 
     def all_of(key)
@@ -106,7 +108,7 @@ module Puma
   #
   # It also handles loading plugins.
   #
-  # > Note: `:port` and `:host` are not valid keys. By they time they make it to the
+  # > Note: `:port` and `:host` are not valid keys. By the time they make it to the
   #   configuration options they are expected to be incorporated into a `:binds` key.
   #   Under the hood the DSL maps `port` and `host` calls to `:binds`
   #
@@ -137,6 +139,10 @@ module Puma
       @file_dsl    = DSL.new(@options.file_options, self)
       @default_dsl = DSL.new(@options.default_options, self)
 
+      if !@options[:prune_bundler]
+        default_options[:preload_app] = (@options[:workers] > 1) && Puma.forkable?
+      end
+
       if block
         configure(&block)
       end
@@ -167,22 +173,26 @@ module Puma
       self
     end
 
+    # @version 5.0.0
+    def default_max_threads
+      Puma.mri? ? 5 : 16
+    end
+
     def puma_default_options
       {
-        :min_threads => 0,
-        :max_threads => 16,
+        :min_threads => Integer(ENV['PUMA_MIN_THREADS'] || ENV['MIN_THREADS'] || 0),
+        :max_threads => Integer(ENV['PUMA_MAX_THREADS'] || ENV['MAX_THREADS'] || default_max_threads),
         :log_requests => false,
         :debug => false,
         :binds => ["tcp://#{DefaultTCPHost}:#{DefaultTCPPort}"],
-        :workers => 0,
-        :daemon => false,
+        :workers => Integer(ENV['WEB_CONCURRENCY'] || 0),
         :mode => :http,
         :worker_timeout => DefaultWorkerTimeout,
         :worker_boot_timeout => DefaultWorkerTimeout,
         :worker_shutdown_timeout => DefaultWorkerShutdownTimeout,
         :remote_address => :socket,
         :tag => method(:infer_tag),
-        :environment => -> { ENV['RACK_ENV'] || "development" },
+        :environment => -> { ENV['RACK_ENV'] || ENV['RAILS_ENV'] || "development" },
         :rackup => DefaultRackup,
         :logger => STDOUT,
         :persistent_timeout => Const::PERSISTENT_TIMEOUT,
@@ -245,14 +255,6 @@ module Puma
     def app
       found = options[:app] || load_rackup
 
-      if @options[:mode] == :tcp
-        require 'puma/tcp_logger'
-
-        logger = @options[:logger]
-        quiet = !@options[:log_requests]
-        return TCPLogger.new(logger, found, quiet)
-      end
-
       if @options[:log_requests]
         require 'puma/commonlogger'
         logger = @options[:logger]
@@ -275,8 +277,15 @@ module Puma
       @plugins.create name
     end
 
-    def run_hooks(key, arg)
-      @options.all_of(key).each { |b| b.call arg }
+    def run_hooks(key, arg, events)
+      @options.all_of(key).each do |b|
+        begin
+          b.call arg
+        rescue => e
+          events.log "WARNING hook #{key} failed with exception (#{e.class}) #{e.message}"
+          events.debug e.backtrace.join("\n")
+        end
+      end
     end
 
     def self.temp_path
@@ -332,29 +341,9 @@ module Puma
     end
 
     def self.random_token
-      begin
-        require 'openssl'
-      rescue LoadError
-      end
-
-      count = 16
-
-      bytes = nil
-
-      if defined? OpenSSL::Random
-        bytes = OpenSSL::Random.random_bytes(count)
-      elsif File.exist?("/dev/urandom")
-        File.open('/dev/urandom') { |f| bytes = f.read(count) }
-      end
-
-      if bytes
-        token = "".dup
-        bytes.each_byte { |b| token << b.to_s(16) }
-      else
-        token = (0..count).to_a.map { rand(255).to_s(16) }.join
-      end
+      require 'securerandom' unless defined?(SecureRandom)
 
-      return token
+      SecureRandom.hex(16)
     end
   end
 end

data/lib/puma/const.rb

@@ -100,8 +100,9 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "4.1.1".freeze
-    CODE_NAME = "Fourth and One".freeze
+    PUMA_VERSION = VERSION = "5.0.0".freeze
+    CODE_NAME = "Spoony Bard".freeze
+
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2
@@ -118,31 +119,35 @@ module Puma
     # sending data back
     WRITE_TIMEOUT = 10
 
+    # How many requests to attempt inline before sending a client back to
+    # the reactor to be subject to normal ordering. The idea here is that
+    # we amortize the cost of going back to the reactor for a well behaved
+    # but very "greedy" client across 10 requests. This prevents a not
+    # well behaved client from monopolizing the thread forever.
+    MAX_FAST_INLINE = 10
+
     # The original URI requested by the client.
     REQUEST_URI= 'REQUEST_URI'.freeze
     REQUEST_PATH = 'REQUEST_PATH'.freeze
     QUERY_STRING = 'QUERY_STRING'.freeze
+    CONTENT_LENGTH = "CONTENT_LENGTH".freeze
 
     PATH_INFO = 'PATH_INFO'.freeze
 
     PUMA_TMP_BASE = "puma".freeze
 
-    # Indicate that we couldn't parse the request
-    ERROR_400_RESPONSE = "HTTP/1.1 400 Bad Request\r\n\r\n".freeze
-
-    # The standard empty 404 response for bad requests.  Use Error4040Handler for custom stuff.
-    ERROR_404_RESPONSE = "HTTP/1.1 404 Not Found\r\nConnection: close\r\nServer: Puma #{PUMA_VERSION}\r\n\r\nNOT FOUND".freeze
-
-    # The standard empty 408 response for requests that timed out.
-    ERROR_408_RESPONSE = "HTTP/1.1 408 Request Timeout\r\nConnection: close\r\nServer: Puma #{PUMA_VERSION}\r\n\r\n".freeze
-
-    CONTENT_LENGTH = "CONTENT_LENGTH".freeze
-
-    # Indicate that there was an internal error, obviously.
-    ERROR_500_RESPONSE = "HTTP/1.1 500 Internal Server Error\r\n\r\n".freeze
-
-    # A common header for indicating the server is too busy.  Not used yet.
-    ERROR_503_RESPONSE = "HTTP/1.1 503 Service Unavailable\r\n\r\nBUSY".freeze
+    ERROR_RESPONSE = {
+      # Indicate that we couldn't parse the request
+      400 => "HTTP/1.1 400 Bad Request\r\n\r\n".freeze,
+      # The standard empty 404 response for bad requests.  Use Error4040Handler for custom stuff.
+      404 => "HTTP/1.1 404 Not Found\r\nConnection: close\r\nServer: Puma #{PUMA_VERSION}\r\n\r\nNOT FOUND".freeze,
+      # The standard empty 408 response for requests that timed out.
+      408 => "HTTP/1.1 408 Request Timeout\r\nConnection: close\r\nServer: Puma #{PUMA_VERSION}\r\n\r\n".freeze,
+      # Indicate that there was an internal error, obviously.
+      500 => "HTTP/1.1 500 Internal Server Error\r\n\r\n".freeze,
+      # A common header for indicating the server is too busy.  Not used yet.
+      503 => "HTTP/1.1 503 Service Unavailable\r\n\r\nBUSY".freeze
+    }
 
     # The basic max request size we'll try to read.
     CHUNK_SIZE = 16 * 1024
@@ -171,7 +176,6 @@ module Puma
     PORT_443 = "443".freeze
     LOCALHOST = "localhost".freeze
     LOCALHOST_IP = "127.0.0.1".freeze
-    LOCALHOST_ADDR = "127.0.0.1:0".freeze
 
     SERVER_PROTOCOL = "SERVER_PROTOCOL".freeze
     HTTP_11 = "HTTP/1.1".freeze
@@ -224,6 +228,7 @@ module Puma
     COLON = ": ".freeze
 
     NEWLINE = "\n".freeze
+    HTTP_INJECTION_REGEX = /[\r\n]/.freeze
 
     HIJACK_P = "rack.hijack?".freeze
     HIJACK = "rack.hijack".freeze

data/lib/puma/control_cli.rb

@@ -11,7 +11,10 @@ require 'socket'
 module Puma
   class ControlCLI
 
-    COMMANDS = %w{halt restart phased-restart start stats status stop reload-worker-directory gc gc-stats}
+    COMMANDS = %w{halt restart phased-restart start stats status stop reload-worker-directory gc gc-stats thread-backtraces refork}
+
+    # @version 5.0.0
+    PRINTABLE_COMMANDS = %w{gc-stats stats thread-backtraces}
 
     def initialize(argv, stdout=STDOUT, stderr=STDERR)
       @state = nil
@@ -22,6 +25,7 @@ module Puma
       @control_auth_token = nil
       @config_file = nil
       @command = nil
+      @environment = ENV['RACK_ENV'] || ENV['RAILS_ENV']
 
       @argv = argv.dup
       @stdout = stdout
@@ -59,6 +63,11 @@ module Puma
           @config_file = arg
         end
 
+        o.on "-e", "--environment ENVIRONMENT",
+          "The environment to run the Rack app on (default development)" do |arg|
+          @environment = arg
+        end
+
         o.on_tail("-H", "--help", "Show this message") do
           @stdout.puts o
           exit
@@ -75,9 +84,22 @@ module Puma
 
       @command = argv.shift
 
+      # check presence of command
+      unless @command
+        raise "Available commands: #{COMMANDS.join(", ")}"
+      end
+
+      unless COMMANDS.include? @command
+        raise "Invalid command: #{@command}"
+      end
+
       unless @config_file == '-'
-        if @config_file.nil? and File.exist?('config/puma.rb')
-          @config_file = 'config/puma.rb'
+        environment = @environment || 'development'
+
+        if @config_file.nil?
+          @config_file = %W(config/puma/#{environment}.rb config/puma.rb).find do |f|
+            File.exist?(f)
+          end
         end
 
         if @config_file
@@ -89,16 +111,6 @@ module Puma
           @pidfile            ||= config.options[:pidfile]
         end
       end
-
-      # check present of command
-      unless @command
-        raise "Available commands: #{COMMANDS.join(", ")}"
-      end
-
-      unless COMMANDS.include? @command
-        raise "Invalid command: #{@command}"
-      end
-
     rescue => e
       @stdout.puts e.message
       exit 1
@@ -122,7 +134,7 @@ module Puma
         @pid = sf.pid
       elsif @pidfile
         # get pid from pid_file
-        @pid = File.open(@pidfile).gets.to_i
+        File.open(@pidfile) { |f| @pid = f.read.to_i }
       end
     end
 
@@ -131,6 +143,13 @@ module Puma
 
       # create server object by scheme
       server = case uri.scheme
+                when "ssl"
+                  require 'openssl'
+                  OpenSSL::SSL::SSLSocket.new(
+                    TCPSocket.new(uri.host, uri.port),
+                    OpenSSL::SSL::SSLContext.new)
+                    .tap { |ssl| ssl.sync_close = true }  # default is false
+                    .tap(&:connect)
                 when "tcp"
                   TCPSocket.new uri.host, uri.port
                 when "unix"
@@ -171,10 +190,16 @@ module Puma
         end
 
         message "Command #{@command} sent success"
-        message response.last if @command == "stats" || @command == "gc-stats"
+        message response.last if PRINTABLE_COMMANDS.include?(@command)
       end
     ensure
-      server.close if server && !server.closed?
+      if server
+        if uri.scheme == "ssl"
+          server.sysclose
+        else
+          server.close unless server.closed?
+        end
+      end
     end
 
     def send_signal
@@ -215,6 +240,9 @@ module Puma
 
           return
 
+        when "refork"
+          Process.kill "SIGURG", @pid
+
         else
           return
         end
@@ -246,7 +274,7 @@ module Puma
       exit 1
     end
 
-  private
+    private
     def start
       require 'puma/cli'
 
@@ -258,6 +286,7 @@ module Puma
       run_args += ["--control-url", @control_url] if @control_url
       run_args += ["--control-token", @control_auth_token] if @control_auth_token
       run_args += ["-C", @config_file] if @config_file
+      run_args += ["-e", @environment] if @environment
 
       events = Puma::Events.new @stdout, @stderr
 

data/lib/puma/detect.rb

@@ -1,6 +1,13 @@
 # frozen_string_literal: true
 
 module Puma
+  # at present, MiniSSL::Engine is only defined in extension code, not in minissl.rb
+  HAS_SSL = const_defined?(:MiniSSL, false) && MiniSSL.const_defined?(:Engine, false)
+
+  def self.ssl?
+    HAS_SSL
+  end
+
   IS_JRUBY = defined?(JRUBY_VERSION)
 
   def self.jruby?
@@ -12,4 +19,14 @@ module Puma
   def self.windows?
     IS_WINDOWS
   end
+
+  # @version 5.0.0
+  def self.mri?
+    RUBY_ENGINE == 'ruby' || RUBY_ENGINE.nil?
+  end
+
+  # @version 5.0.0
+  def self.forkable?
+    ::Process.respond_to?(:fork)
+  end
 end

data/lib/puma/dsl.rb

@@ -14,22 +14,23 @@ 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+.
+  #
   class DSL
     include ConfigDefault
 
@@ -98,6 +99,9 @@ module Puma
     #       [body]
     #     ]
     #   end
+    #
+    # @see Puma::Configuration#app
+    #
     def app(obj=nil, &block)
       obj ||= block
 
@@ -160,12 +164,12 @@ module Puma
     #
     # 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 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+.
     #
     # @example Backlog depth
     #   bind 'unix:///var/run/puma.sock?backlog=512'
@@ -175,6 +179,9 @@ module Puma
     #   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
@@ -193,13 +200,14 @@ module Puma
       bind "tcp://#{host}:#{port}"
     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 +218,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+.
+    # 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
     #
-    # The default is "false".
-    #
-    # @example
-    #   daemonize
-    #
-    # @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 +245,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 +253,7 @@ module Puma
           when :immediately
             0
           else
-            Integer(val)
+            Float(val)
           end
 
       @options[:force_shutdown_after] = i
@@ -322,20 +318,14 @@ module Puma
     # @example
     #   rackup '/u/apps/lolcat/config.ru'
     def rackup(path)
-      @options[:rackup] = path.to_s
-    end
-
-    # Run Puma in TCP mode
-    #
-    def tcp_mode!
-      @options[:mode] = :tcp
+      @options[:rackup] ||= path.to_s
     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
@@ -376,8 +366,8 @@ 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 `bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'` you
+    # can also use the this method.
     #
     # @example
     #   ssl_bind '127.0.0.1', '9292', {
@@ -396,7 +386,7 @@ module Puma
     #     keystore_pass: password
     #   }
     def ssl_bind(host, port, opts)
-      verify = opts.fetch(:verify_mode, 'none')
+      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)
@@ -419,12 +409,23 @@ 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.
     #
     # @note Cluster mode only.
+    # @see Puma::Cluster
     def workers(count)
       @options[:workers] = count.to_i
     end
@@ -455,8 +456,8 @@ 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] ||= []
@@ -512,6 +513,29 @@ module Puma
 
     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(&block)
+      @options[:before_refork] ||= []
+      @options[:before_refork] << block
+    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.
@@ -536,17 +560,6 @@ 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.
     #
@@ -583,7 +596,10 @@ module Puma
     # new Bundler context and thus can float around as the release
     # dictates.
     #
+    # @see extra_runtime_dependencies
+    #
     # @note This is incompatible with +preload_app!+.
+    # @note This is only supported for RubyGems 2.2+
     def prune_bundler(answer=true)
       @options[:prune_bundler] = answer
     end
@@ -597,10 +613,30 @@ 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
 
+    # When using prune_bundler, if extra runtime dependencies need to be loaded to
+    # initialize your app, then this setting can be used. This includes any Puma plugins.
+    #
+    # Before bundler is pruned, the gem names supplied will be looked up in the bundler
+    # context and then loaded again after bundler is pruned.
+    # Only applies if prune_bundler is used.
+    #
+    # @example
+    #   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
+
     # Additional text to display in process listing.
     #
     # If you do not specify a tag, Puma will infer it. If you do not want Puma
@@ -624,6 +660,8 @@ 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
@@ -640,15 +678,20 @@ 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
@@ -666,6 +709,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
@@ -673,10 +717,25 @@ 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
@@ -684,18 +743,18 @@ module Puma
     #
     # 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.
+    # 1. **:socket** (the default) - read the peername from the socket using the
+    #    syscall. This is the normal behavior.
+    # 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.
+    # 4. **\<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
@@ -718,5 +777,38 @@ 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
+
+    # When enabled, Puma will GC 4 times before forking workers.
+    # If available (Ruby 2.7+), we will also call GC.compact.
+    # Not recommended for non-MRI Rubies.
+    #
+    # Based on the work of Koichi Sasada and Aaron Patterson, this option may
+    # decrease memory utilization of preload-enabled cluster-mode Pumas. It will
+    # also increase time to boot and fork. See your logs for details on how much
+    # time this adds to your boot process. For most apps, it will be less than one
+    # second.
+    #
+    # @see Puma::Cluster#nakayoshi_gc
+    # @version 5.0.0
+    #
+    def nakayoshi_fork(enabled=true)
+      @options[:nakayoshi_fork] = enabled
+    end
   end
 end