puma 3.12.6 → 5.3.2

data/lib/puma/const.rb

@@ -100,8 +100,9 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "3.12.6".freeze
-    CODE_NAME = "Llamas in Pajamas".freeze
+    PUMA_VERSION = VERSION = "5.3.2".freeze
+    CODE_NAME = "Sweetnighter".freeze
+
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2
@@ -129,27 +130,24 @@ module Puma
     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
@@ -167,6 +165,9 @@ module Puma
     LINE_END = "\r\n".freeze
     REMOTE_ADDR = "REMOTE_ADDR".freeze
     HTTP_X_FORWARDED_FOR = "HTTP_X_FORWARDED_FOR".freeze
+    HTTP_X_FORWARDED_SSL = "HTTP_X_FORWARDED_SSL".freeze
+    HTTP_X_FORWARDED_SCHEME = "HTTP_X_FORWARDED_SCHEME".freeze
+    HTTP_X_FORWARDED_PROTO = "HTTP_X_FORWARDED_PROTO".freeze
 
     SERVER_NAME = "SERVER_NAME".freeze
     SERVER_PORT = "SERVER_PORT".freeze
@@ -175,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
@@ -228,12 +228,24 @@ module Puma
     COLON = ": ".freeze
 
     NEWLINE = "\n".freeze
-    HTTP_INJECTION_REGEX = /[\r\n]/.freeze
 
     HIJACK_P = "rack.hijack?".freeze
     HIJACK = "rack.hijack".freeze
     HIJACK_IO = "rack.hijack_io".freeze
 
     EARLY_HINTS = "rack.early_hints".freeze
+
+    # Minimum interval to checks worker health
+    WORKER_CHECK_INTERVAL = 5
+
+    # Illegal character in the key or value of response header
+    DQUOTE = "\"".freeze
+    HTTP_HEADER_DELIMITER = Regexp.escape("(),/:;<=>?@[]{}\\").freeze
+    ILLEGAL_HEADER_KEY_REGEX = /[\x00-\x20#{DQUOTE}#{HTTP_HEADER_DELIMITER}]/.freeze
+    # header values can contain HTAB?
+    ILLEGAL_HEADER_VALUE_REGEX = /[\x00-\x08\x0A-\x1F]/.freeze
+
+    # Banned keys of response header
+    BANNED_HEADER_KEY = /\A(rack\.|status\z)/.freeze
   end
 end

data/lib/puma/control_cli.rb

@@ -11,7 +11,32 @@ require 'socket'
 module Puma
   class ControlCLI
 
-    COMMANDS = %w{halt restart phased-restart start stats status stop reload-worker-directory gc gc-stats}
+    # values must be string or nil
+    # value of `nil` means command cannot be processed via signal
+    # @version 5.0.3
+    CMD_PATH_SIG_MAP = {
+      'gc'       => nil,
+      'gc-stats' => nil,
+      'halt'     => 'SIGQUIT',
+      'phased-restart' => 'SIGUSR1',
+      'refork'   => 'SIGURG',
+      'reload-worker-directory' => nil,
+      'restart'  => 'SIGUSR2',
+      'start'    => nil,
+      'stats'    => nil,
+      'status'   => '',
+      'stop'     => 'SIGTERM',
+      'thread-backtraces' => nil
+    }.freeze
+
+    # @deprecated 6.0.0
+    COMMANDS = CMD_PATH_SIG_MAP.keys.freeze
+
+    # commands that cannot be used in a request
+    NO_REQ_COMMANDS = %w{refork}.freeze
+
+    # @version 5.0.0
+    PRINTABLE_COMMANDS = %w{gc-stats stats thread-backtraces}.freeze
 
     def initialize(argv, stdout=STDOUT, stderr=STDERR)
       @state = nil
@@ -22,6 +47,7 @@ module Puma
       @control_auth_token = nil
       @config_file = nil
       @command = nil
+      @environment = ENV['RACK_ENV'] || ENV['RAILS_ENV']
 
       @argv = argv.dup
       @stdout = stdout
@@ -29,7 +55,7 @@ module Puma
       @cli_options = {}
 
       opts = OptionParser.new do |o|
-        o.banner = "Usage: pumactl (-p PID | -P pidfile | -S status_file | -C url -T token | -F config.rb) (#{COMMANDS.join("|")})"
+        o.banner = "Usage: pumactl (-p PID | -P pidfile | -S status_file | -C url -T token | -F config.rb) (#{CMD_PATH_SIG_MAP.keys.join("|")})"
 
         o.on "-S", "--state PATH", "Where the state file to use is" do |arg|
           @state = arg
@@ -59,13 +85,18 @@ 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
         end
 
         o.on_tail("-V", "--version", "Show version") do
-          puts Const::PUMA_VERSION
+          @stdout.puts Const::PUMA_VERSION
           exit
         end
       end
@@ -75,9 +106,22 @@ module Puma
 
       @command = argv.shift
 
+      # check presence of command
+      unless @command
+        raise "Available commands: #{CMD_PATH_SIG_MAP.keys.join(", ")}"
+      end
+
+      unless CMD_PATH_SIG_MAP.key? @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,19 +133,8 @@ 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
-      @stdout.puts e.backtrace
       exit 1
     end
 
@@ -123,7 +156,7 @@ module Puma
         @pid = sf.pid
       elsif @pidfile
         # get pid from pid_file
-        @pid = File.open(@pidfile).gets.to_i
+        @pid = File.read(@pidfile, mode: 'rb:UTF-8').to_i
       end
     end
 
@@ -131,17 +164,29 @@ module Puma
       uri = URI.parse @control_url
 
       # create server object by scheme
-      server = case uri.scheme
-                when "tcp"
-                  TCPSocket.new uri.host, uri.port
-                when "unix"
-                  UNIXSocket.new "#{uri.host}#{uri.path}"
-                else
-                  raise "Invalid scheme: #{uri.scheme}"
-                end
-
-      if @command == "status"
-        message "Puma is started"
+      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'
+          # check for abstract UNIXSocket
+          UNIXSocket.new(@control_url.start_with?('unix://@') ?
+            "\0#{uri.host}#{uri.path}" : "#{uri.host}#{uri.path}")
+        else
+          raise "Invalid scheme: #{uri.scheme}"
+        end
+
+      if @command == 'status'
+        message 'Puma is started'
+      elsif NO_REQ_COMMANDS.include? @command
+        raise "Invalid request command: #{@command}"
       else
         url = "/#{@command}"
 
@@ -149,10 +194,10 @@ module Puma
           url = url + "?token=#{@control_auth_token}"
         end
 
-        server << "GET #{url} HTTP/1.0\r\n\r\n"
+        server.syswrite "GET #{url} HTTP/1.0\r\n\r\n"
 
         unless data = server.read
-          raise "Server closed connection before responding"
+          raise 'Server closed connection before responding'
         end
 
         response = data.split("\r\n")
@@ -161,57 +206,55 @@ module Puma
           raise "Server sent empty response"
         end
 
-        (@http,@code,@message) = response.first.split(" ",3)
+        @http, @code, @message = response.first.split(' ',3)
 
-        if @code == "403"
-          raise "Unauthorized access to server (wrong auth token)"
-        elsif @code == "404"
+        if @code == '403'
+          raise 'Unauthorized access to server (wrong auth token)'
+        elsif @code == '404'
           raise "Command error: #{response.last}"
-        elsif @code != "200"
+        elsif @code != '200'
           raise "Bad response from server: #{@code}"
         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
       unless @pid
-        raise "Neither pid nor control url available"
+        raise 'Neither pid nor control url available'
       end
 
       begin
+        sig = CMD_PATH_SIG_MAP[@command]
 
-        case @command
-        when "restart"
-          Process.kill "SIGUSR2", @pid
-
-        when "halt"
-          Process.kill "QUIT", @pid
-
-        when "stop"
-          Process.kill "SIGTERM", @pid
-
-        when "stats"
-          puts "Stats not available via pid only"
-          return
-
-        when "reload-worker-directory"
-          puts "reload-worker-directory not available via pid only"
+        if sig.nil?
+          @stdout.puts "'#{@command}' not available via pid only"
+          @stdout.flush unless @stdout.sync
           return
-
-        when "phased-restart"
-          Process.kill "SIGUSR1", @pid
-
-        else
+        elsif sig.start_with? 'SIG'
+          Process.kill sig, @pid
+        elsif @command == 'status'
+          begin
+            Process.kill 0, @pid
+            @stdout.puts 'Puma is started'
+            @stdout.flush unless @stdout.sync
+          rescue Errno::ESRCH
+            raise 'Puma is not running'
+          end
           return
         end
-
       rescue SystemCallError
-        if @command == "restart"
+        if @command == 'restart'
           start
         else
           raise "No pid '#{@pid}' found"
@@ -222,23 +265,21 @@ module Puma
     end
 
     def run
-      return start if @command == "start"
-
+      return start if @command == 'start'
       prepare_configuration
 
-      if Puma.windows?
+      if Puma.windows? || @control_url
         send_request
       else
-        @control_url ? send_request : send_signal
+        send_signal
       end
 
     rescue => e
       message e.message
-      message e.backtrace
       exit 1
     end
 
-  private
+    private
     def start
       require 'puma/cli'
 
@@ -250,6 +291,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,15 +1,36 @@
 # frozen_string_literal: true
 
+# This file can be loaded independently of puma.rb, so it cannot have any code
+# that assumes puma.rb is loaded.
+
+
 module Puma
-  IS_JRUBY = defined?(JRUBY_VERSION)
+  # @version 5.2.1
+  HAS_FORK = ::Process.respond_to? :fork
+
+  IS_JRUBY = Object.const_defined? :JRUBY_VERSION
+
+  IS_WINDOWS = !!(RUBY_PLATFORM =~ /mswin|ming|cygwin/ ||
+    IS_JRUBY && RUBY_DESCRIPTION =~ /mswin/)
+
+  # @version 5.2.0
+  IS_MRI = (RUBY_ENGINE == 'ruby' || RUBY_ENGINE.nil?)
 
   def self.jruby?
     IS_JRUBY
   end
 
-  IS_WINDOWS = RUBY_PLATFORM =~ /mswin|ming|cygwin/
-
   def self.windows?
     IS_WINDOWS
   end
+
+  # @version 5.0.0
+  def self.mri?
+    IS_MRI
+  end
+
+  # @version 5.0.0
+  def self.forkable?
+    HAS_FORK
+  end
 end

data/lib/puma/dsl.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'puma/const'
+
 module Puma
-  # The methods that are available for use inside the config file.
+  # The methods that are available for use inside the configuration file.
   # These same methods are used in Puma cli and the rack handler
   # internally.
   #
@@ -12,24 +14,60 @@ 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+.
   #
-  # Detailed docs can be found in `examples/config.rb`
   class DSL
     include ConfigDefault
 
+    # 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=#{opts[:ca]}" if ['peer', 'force_peer'].include?(verify)
+
+      if defined?(JRUBY_VERSION)
+        ssl_cipher_list = opts[:ssl_cipher_list] ?
+          "&ssl_cipher_list=#{opts[:ssl_cipher_list]}" : nil
+
+        keystore_additions = "keystore=#{opts[:keystore]}&keystore-pass=#{opts[:keystore_pass]}"
+
+        "ssl://#{host}:#{port}?#{keystore_additions}#{ssl_cipher_list}" \
+          "&verify_mode=#{verify}#{tls_str}#{ca_additions}"
+      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
+
+        "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}" \
+          "#{ssl_cipher_filter}&verify_mode=#{verify}#{tls_str}#{ca_additions}#{v_flags}"
+      end
+    end
+
     def initialize(options, config)
       @config  = config
       @options = options
@@ -79,8 +117,24 @@ module Puma
       @plugins << @config.load_plugin(name)
     end
 
-    # Use +obj+ or +block+ as the Rack app. This allows a config file to
-    # be the app itself.
+    # Use an object or block as the rack application. This allows the
+    # configuration file to be the application itself.
+    #
+    # @example
+    #   app do |env|
+    #     body = 'Hello, World!'
+    #
+    #     [
+    #       200,
+    #       {
+    #         'Content-Type' => 'text/plain',
+    #         'Content-Length' => body.length.to_s
+    #       },
+    #       [body]
+    #     ]
+    #   end
+    #
+    # @see Puma::Configuration#app
     #
     def app(obj=nil, &block)
       obj ||= block
@@ -90,9 +144,20 @@ module Puma
       @options[:app] = obj
     end
 
-    # Start the Puma control rack app on +url+. This app can be communicated
-    # with to control the main server.
+    # Start the Puma control rack application on +url+. This application can
+    # be communicated with to control the main server. Additionally, you can
+    # provide an authentication token, so all requests to the control server
+    # will need to include that token as a query parameter. This allows for
+    # simple authentication.
+    #
+    # Check out {Puma::App::Status} to see what the app has available.
     #
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock'
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
     def activate_control_app(url="auto", opts={})
       if url == "auto"
         path = Configuration.temp_path
@@ -103,7 +168,12 @@ module Puma
       end
 
       if opts[:no_token]
-        auth_token = :none
+        # We need to use 'none' rather than :none because this value will be
+        # passed on to an instance of OptionParser, which doesn't support
+        # symbols as option values.
+        #
+        # See: https://github.com/puma/puma/issues/1193#issuecomment-305995488
+        auth_token = 'none'
       else
         auth_token = opts[:auth_token]
         auth_token ||= Configuration.random_token
@@ -120,22 +190,32 @@ module Puma
       @options[:config_files] << file
     end
 
-    # Adds a binding for the server to +url+. tcp://, unix://, and ssl:// are the only accepted
-    # protocols. Use query parameters within the url to specify options.
+    # Bind the server to +url+. "tcp://", "unix://" and "ssl://" are the only
+    # accepted protocols. Multiple urls can be bound to, calling `bind` does
+    # not overwrite previous bindings.
     #
-    # @note multiple urls can be bound to, calling `bind` does not overwrite previous bindings.
+    # The default is "tcp://0.0.0.0:9292".
     #
-    # @example Explicitly the socket backlog depth (default is 1024)
-    #   bind('unix:///var/run/puma.sock?backlog=2048')
+    # You can use query parameters within the url to specify options:
     #
-    # @example Set up ssl cert
-    #   bind('ssl://127.0.0.1:9292?key=key.key&cert=cert.pem')
+    # * 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 not optimize for low latency. This is done
+    #   via +Socket::TCP_NODELAY+.
+    # * Set socket permissions with +umask+.
     #
-    # @example Prefer low-latency over higher throughput (via `Socket::TCP_NODELAY`)
-    #   bind('tcp://0.0.0.0:9292?low_latency=true')
+    # @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 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
     #
-    # @example Set socket permissions
-    #   bind('unix:///var/run/puma.sock?umask=0111')
     def bind(url)
       @options[:binds] ||= []
       @options[:binds] << url
@@ -145,48 +225,75 @@ 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
-    #
+    # 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
 
     # Work around leaky apps that leave garbage in Thread locals
-    # across requests
-    #
+    # across requests.
     def clean_thread_locals(which=true)
       @options[:clean_thread_locals] = which
     end
 
-    # Daemonize the server into the background. Highly suggest that
-    # this be combined with +pidfile+ and +stdout_redirect+.
-    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.
+    # 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)
       @options[:drain_on_shutdown] = which
     end
 
-    # Set the environment in which the Rack's app will run.
+    # Set the environment in which the rack's app will run. The value must be
+    # a string.
+    #
+    # The default is "development".
+    #
+    # @example
+    #   environment 'production'
     def environment(environment)
       @options[:environment] = environment
     end
@@ -198,6 +305,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
@@ -205,37 +313,48 @@ module Puma
           when :immediately
             0
           else
-            Integer(val)
+            Float(val)
           end
 
       @options[:force_shutdown_after] = i
     end
 
     # Code to run before doing a restart. This code should
-    # close logfiles, database connections, etc.
+    # close log files, database connections, etc.
     #
     # This can be called multiple times to add code each time.
     #
+    # @example
+    #   on_restart do
+    #     puts 'On restart...'
+    #   end
     def on_restart(&block)
       @options[:on_restart] ||= []
       @options[:on_restart] << block
     end
 
-    # 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.
+    # 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
 
-    # Store the pid of the server in the file at +path+.
+    # Store the pid of the server in the file at "path".
+    #
+    # @example
+    #   pidfile '/u/apps/lolcat/tmp/pids/puma.pid'
     def pidfile(path)
       @options[:pidfile] = path.to_s
     end
 
-    # Disable request logging.
+    # Disable request logging, if this isn't used it'll be enabled by default.
     #
+    # @example
+    #   quiet
     def quiet(which=true)
       @options[:log_requests] = !which
     end
@@ -254,30 +373,47 @@ module Puma
 
     # Load +path+ as a rackup file.
     #
-    def rackup(path)
-      @options[:rackup] = path.to_s
-    end
-
-    # Run Puma in TCP mode
+    # The default is "config.ru".
     #
-    def tcp_mode!
-      @options[:mode] = :tcp
+    # @example
+    #   rackup '/u/apps/lolcat/config.ru'
+    def rackup(path)
+      @options[:rackup] ||= path.to_s
     end
 
     def early_hints(answer=true)
       @options[:early_hints] = answer
     end
 
-    # Redirect STDOUT and STDERR to files specified.
+    # Redirect +STDOUT+ and +STDERR+ to files specified. The +append+ parameter
+    # 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
       @options[:redirect_append] = append
     end
 
+    def log_formatter(&block)
+      @options[:log_formatter] = block
+    end
+
     # Configure +min+ to be the minimum number of threads to use to answer
     # requests and +max+ the maximum.
     #
+    # 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
+    # @example
+    #   threads 5, 5
     def threads(min, max)
       min = Integer(min)
       max = Integer(max)
@@ -293,81 +429,153 @@ 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 this method.
+    #
+    # @example
+    #   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'
+    #     verification_flags: flags,        # optional, not supported by JRuby
+    #   }
+    # @example For JRuby, two keys are required: keystore & keystore_pass.
+    #   ssl_bind '127.0.0.1', '9292', {
+    #     keystore: path_to_keystore,
+    #     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')
-
-      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}"
-      else
-        bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}&verify_mode=#{verify}"
-      end
+      bind self.class.ssl_bind_str(host, port, opts)
     end
 
     # Use +path+ as the file to store the server info state. This is
-    # used by pumactl to query and control the server.
+    # used by +pumactl+ to query and control the server.
     #
+    # @example
+    #   state_path '/u/apps/lolcat/tmp/pids/puma.state'
     def state_path(path)
       @options[:state] = path.to_s
     end
 
-    # *Cluster mode only* How many worker processes to run.
+    # 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
+    # the number of available cores.
     #
+    # 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
 
-    # *Cluster mode only* Code to run immediately before master process
+    # 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
+    # to wait for background operations unknown to Puma to finish before
     # the process terminates.
-    # This can be used to close any connections to remote servers (database, redis, ...)
-    # that were opened when preloading the code
+    # This can be used to close any connections to remote servers (database,
+    # Redis, ...) that were opened when preloading the code.
     #
-    # This can be called multiple times to add hooks.
+    # 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)
       @options[:before_fork] ||= []
       @options[:before_fork] << block
     end
 
-    # *Cluster mode only* Code to run in a worker when it boots to setup
+    # Code to run in a worker when it boots to setup
     # the process before booting the app.
     #
-    # This can be called multiple times to add hooks.
+    # This can be called multiple times to add several hooks.
     #
+    # @note Cluster mode only.
+    # @example
+    #   on_worker_boot do
+    #     puts 'Before worker boot...'
+    #   end
     def on_worker_boot(&block)
       @options[:before_worker_boot] ||= []
       @options[:before_worker_boot] << block
     end
 
-    # *Cluster mode only* Code to run immediately before a worker shuts
+    # Code to run immediately before a worker shuts
     # down (after it has finished processing HTTP requests). These hooks
     # can block if necessary to wait for background operations unknown
-    # to puma to finish before the process terminates.
+    # to Puma to finish before the process terminates.
     #
-    # This can be called multiple times to add hooks.
+    # This can be called multiple times to add several hooks.
     #
+    # @note Cluster mode only.
+    # @example
+    #   on_worker_shutdown do
+    #     puts 'On worker shutdown...'
+    #   end
     def on_worker_shutdown(&block)
       @options[:before_worker_shutdown] ||= []
       @options[:before_worker_shutdown] << block
     end
 
-    # *Cluster mode only* Code to run in the master when it is
-    # about to create the worker by forking itself.
+    # 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 hooks.
+    # This can be called multiple times to add several hooks.
     #
+    # @note Cluster mode only.
+    # @example
+    #   on_worker_fork do
+    #     puts 'Before worker fork...'
+    #   end
     def on_worker_fork(&block)
       @options[:before_worker_fork] ||= []
       @options[:before_worker_fork] << block
     end
 
-    # *Cluster mode only* Code to run in the master after it starts
-    # a worker.
+    # Code to run in the master after a worker has been started. The worker's
+    # index is passed as an argument.
     #
-    # This can be called multiple times to add hooks.
+    # 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)
       @options[:after_worker_fork] ||= []
       @options[:after_worker_fork] = block
@@ -375,33 +583,70 @@ module Puma
 
     alias_method :after_worker_boot, :after_worker_fork
 
-    # The directory to operate out of.
-    def directory(dir)
-      @options[:directory] = dir.to_s
+    # 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
 
-    # DEPRECATED: The directory to operate out of.
-    def worker_directory(dir)
-      $stderr.puts "worker_directory is deprecated. Please use `directory`"
-      directory dir
+    # 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.
+    # The worker doesn't accept new requests until this code finishes.
+    #
+    # This hook is useful for running out-of-band garbage collection
+    # or scheduling asynchronous tasks to execute after a response.
+    #
+    # This can be called multiple times to add several hooks.
+    def out_of_band(&block)
+      @options[:out_of_band] ||= []
+      @options[:out_of_band] << block
     end
 
-    # Run the app as a raw TCP app instead of an HTTP rack app
-    def tcp_mode
-      @options[:mode] = :tcp
+    # The directory to operate out of.
+    #
+    # The default is the current directory.
+    #
+    # @example
+    #   directory '/u/apps/lolcat'
+    def directory(dir)
+      @options[:directory] = dir.to_s
     end
 
-    # *Cluster mode only* Preload the application before starting
-    # the workers and setting up the listen ports. This conflicts
-    # with using the phased restart feature, you can't use both.
+    # Preload the application before starting the workers; this conflicts with
+    # phased restart feature. On by default if your app uses more than 1 worker.
     #
+    # @note Cluster mode only.
+    # @example
+    #   preload_app!
     def preload_app!(answer=true)
       @options[:preload_app] = answer
     end
 
-    # Use +obj+ or +block+ as the low level error handler. This allows a config file to
-    # change the default error on the server.
+    # Use +obj+ or +block+ as the low level error handler. This allows the
+    # configuration file to change the default error on the server.
     #
+    # @example
+    #   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
@@ -411,38 +656,112 @@ module Puma
     # This option is used to allow your app and its gems to be
     # properly reloaded when not using preload.
     #
-    # When set, if puma detects that it's been invoked in the
+    # When set, if Puma detects that it's been invoked in the
     # context of Bundler, it will cleanup the environment and
     # re-run itself outside the Bundler environment, but directly
     # using the files that Bundler has setup.
     #
-    # This means that puma is now decoupled from your Bundler
+    # This means that Puma is now decoupled from your Bundler
     # context and when each worker loads, it will be loading a
     # 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
 
-    # Additional text to display in process listing
+    # By default, Puma will raise 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.
+    #
+    # @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
+    # to add a tag, use an empty string.
+    #
+    # @example
+    #   tag 'app name'
+    # @example
+    #   tag ''
     def tag(string)
       @options[:tag] = string.to_s
     end
 
-    # *Cluster mode only* Set the timeout for workers in seconds
-    # When set the master process will terminate any workers
-    # that have not checked in within the given +timeout+.
-    # This mitigates hung processes. Default value is 60 seconds.
+    # 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.
+    # Setting this value will not protect against slow requests.
+    #
+    # The minimum value is 6 seconds, the default value is 60 seconds.
+    #
+    # @note Cluster mode only.
+    # @example
+    #   worker_timeout 60
+    # @see Puma::Cluster::Worker#ping_timeout
+    #
     def worker_timeout(timeout)
-      @options[:worker_timeout] = Integer(timeout)
+      timeout = Integer(timeout)
+      min = Const::WORKER_CHECK_INTERVAL
+
+      if timeout <= min
+        raise "The minimum worker_timeout must be greater than the worker reporting interval (#{min})"
+      end
+
+      @options[:worker_timeout] = timeout
     end
 
-    # *Cluster mode only* Set the timeout for workers to boot
+    # Change the default worker timeout for booting.
+    #
+    # If unspecified, this defaults to the value of worker_timeout.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   worker_boot_timeout 60
+    # @see Puma::Cluster::Worker#ping_timeout
+    #
     def worker_boot_timeout(timeout)
       @options[:worker_boot_timeout] = Integer(timeout)
     end
 
-    # *Cluster mode only* 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
@@ -459,7 +778,8 @@ module Puma
     # Note that setting this to false disables HTTP keepalive and
     # 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.
+    # slow clients and queue requests before they reach Puma.
+    # @see Puma::Server
     def queue_requests(answer=true)
       @options[:queue_requests] = answer
     end
@@ -467,10 +787,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
@@ -478,18 +813,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
@@ -512,5 +847,68 @@ 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
+
+    # 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
   end
 end