puma 3.12.1 → 4.1.0

data/lib/puma/cluster.rb

@@ -19,8 +19,6 @@ module Puma
   # via the `spawn_workers` method call. Each worker will have it's own
   # instance of a `Puma::Server`.
   class Cluster < Runner
-    WORKER_CHECK_INTERVAL = 5
-
     def initialize(cli, events)
       super cli, events
 
@@ -37,7 +35,35 @@ module Puma
       @workers.each { |x| x.term }
 
       begin
-        @workers.each { |w| Process.waitpid(w.pid) }
+        if RUBY_VERSION < '2.6'
+          @workers.each do |w|
+            begin
+              Process.waitpid(w.pid)
+            rescue Errno::ECHILD
+              # child is already terminated
+            end
+          end
+        else
+          # below code is for a bug in Ruby 2.6+, above waitpid call hangs
+          t_st = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          pids = @workers.map(&:pid)
+          loop do
+            pids.reject! do |w_pid|
+              begin
+                if Process.waitpid(w_pid, Process::WNOHANG)
+                  log "    worker status: #{$?}"
+                  true
+                end
+              rescue Errno::ECHILD
+                true # child is already terminated
+              end
+            end
+            break if pids.empty?
+            sleep 0.5
+          end
+          t_end = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          log format("    worker shutdown time: %6.2f", t_end - t_st)
+        end
       rescue Interrupt
         log "! Cancelled waiting for workers"
       end
@@ -69,12 +95,13 @@ module Puma
         @signal = "TERM"
         @options = options
         @first_term_sent = nil
+        @started_at = Time.now
         @last_checkin = Time.now
         @last_status = '{}'
         @dead = false
       end
 
-      attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status
+      attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status, :started_at
 
       def booted?
         @stage == :booted
@@ -183,7 +210,7 @@ module Puma
     def check_workers(force=false)
       return if !force && @next_check && @next_check >= Time.now
 
-      @next_check = Time.now + WORKER_CHECK_INTERVAL
+      @next_check = Time.now + Const::WORKER_CHECK_INTERVAL
 
       any = false
 
@@ -200,14 +227,11 @@ module Puma
       # during this loop by giving the kernel time to kill them.
       sleep 1 if any
 
-      while @workers.any?
-        pid = Process.waitpid(-1, Process::WNOHANG)
-        break unless pid
-
-        @workers.delete_if { |w| w.pid == pid }
+      pids = []
+      while pid = Process.waitpid(-1, Process::WNOHANG) do
+        pids << pid
       end
-
-      @workers.delete_if(&:dead?)
+      @workers.reject! { |w| w.dead? || pids.include?(w.pid) }
 
       cull_workers
       spawn_workers
@@ -290,7 +314,7 @@ module Puma
         base_payload = "p#{Process.pid}"
 
         while true
-          sleep WORKER_CHECK_INTERVAL
+          sleep Const::WORKER_CHECK_INTERVAL
           begin
             b = server.backlog || 0
             r = server.running || 0
@@ -355,8 +379,8 @@ module Puma
     def stats
       old_worker_count = @workers.count { |w| w.phase != @phase }
       booted_worker_count = @workers.count { |w| w.booted? }
-      worker_status = '[' + @workers.map { |w| %Q!{ "pid": #{w.pid}, "index": #{w.index}, "phase": #{w.phase}, "booted": #{w.booted?}, "last_checkin": "#{w.last_checkin.utc.iso8601}", "last_status": #{w.last_status} }!}.join(",") + ']'
-      %Q!{ "workers": #{@workers.size}, "phase": #{@phase}, "booted_workers": #{booted_worker_count}, "old_workers": #{old_worker_count}, "worker_status": #{worker_status} }!
+      worker_status = '[' + @workers.map { |w| %Q!{ "started_at": "#{w.started_at.utc.iso8601}", "pid": #{w.pid}, "index": #{w.index}, "phase": #{w.phase}, "booted": #{w.booted?}, "last_checkin": "#{w.last_checkin.utc.iso8601}", "last_status": #{w.last_status} }!}.join(",") + ']'
+      %Q!{ "started_at": "#{@started_at.utc.iso8601}", "workers": #{@workers.size}, "phase": #{@phase}, "booted_workers": #{booted_worker_count}, "old_workers": #{old_worker_count}, "worker_status": #{worker_status} }!
     end
 
     def preload?
@@ -390,10 +414,13 @@ module Puma
           log "Early termination of worker"
           exit! 0
         else
+          @launcher.close_binder_listeners
+
           stop_workers
           stop
 
-          raise SignalException, "SIGTERM"
+          raise(SignalException, "SIGTERM") if @options[:raise_exception_on_sigterm]
+          exit 0 # Clean exit, workers were stopped
         end
       end
     end
@@ -487,7 +514,7 @@ module Puma
 
             force_check = false
 
-            res = IO.select([read], nil, nil, WORKER_CHECK_INTERVAL)
+            res = IO.select([read], nil, nil, Const::WORKER_CHECK_INTERVAL)
 
             if res
               req = read.read_nonblock(1)

data/lib/puma/configuration.rb

@@ -20,7 +20,7 @@ module Puma
   # In this class any "user" specified options take precedence over any
   # "file" specified options, take precedence over any "default" options.
   #
-  # User input is prefered over "defaults":
+  # User input is preferred over "defaults":
   #   user_options    = { foo: "bar" }
   #   default_options = { foo: "zoo" }
   #   options = UserFileDefaultOptions.new(user_options, default_options)
@@ -32,7 +32,7 @@ module Puma
   #   puts options.all_of(:foo)
   #   # => ["bar", "zoo"]
   #
-  # A "file" option can be set. This config will be prefered over "default" options
+  # A "file" option can be set. This config will be preferred over "default" options
   # but will defer to any available "user" specified options.
   #
   #   user_options    = { foo: "bar" }
@@ -186,7 +186,8 @@ module Puma
         :rackup => DefaultRackup,
         :logger => STDOUT,
         :persistent_timeout => Const::PERSISTENT_TIMEOUT,
-        :first_data_timeout => Const::FIRST_DATA_TIMEOUT
+        :first_data_timeout => Const::FIRST_DATA_TIMEOUT,
+        :raise_exception_on_sigterm => true
       }
     end
 

data/lib/puma/const.rb

@@ -100,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "3.12.1".freeze
-    CODE_NAME = "Llamas in Pajamas".freeze
+    PUMA_VERSION = VERSION = "4.1.0".freeze
+    CODE_NAME = "Fourth and One".freeze
     PUMA_SERVER_STRING = ['puma', PUMA_VERSION, CODE_NAME].join(' ').freeze
 
     FAST_TRACK_KA_TIMEOUT = 0.2
@@ -160,6 +160,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
@@ -227,5 +230,9 @@ module Puma
     HIJACK_IO = "rack.hijack_io".freeze
 
     EARLY_HINTS = "rack.early_hints".freeze
+
+    # Mininum interval to checks worker health
+    WORKER_CHECK_INTERVAL = 5
+
   end
 end

data/lib/puma/control_cli.rb

@@ -101,7 +101,6 @@ module Puma
 
     rescue => e
       @stdout.puts e.message
-      @stdout.puts e.backtrace
       exit 1
     end
 
@@ -206,6 +205,16 @@ module Puma
         when "phased-restart"
           Process.kill "SIGUSR1", @pid
 
+        when "status"
+          begin
+            Process.kill 0, @pid
+            puts "Puma is started"
+          rescue Errno::ESRCH
+            raise "Puma is not running"
+          end
+
+          return
+
         else
           return
         end
@@ -234,7 +243,6 @@ module Puma
 
     rescue => e
       message e.message
-      message e.backtrace
       exit 1
     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.
   #
@@ -26,7 +28,8 @@ module Puma
   #   puts config.options[:binds]
   #   # => "tcp://127.0.0.1:3002"
   #
-  # Detailed docs can be found in `examples/config.rb`
+  # You can also find many examples being used by the test suite in
+  # +test/config+.
   class DSL
     include ConfigDefault
 
@@ -79,9 +82,22 @@ 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
     def app(obj=nil, &block)
       obj ||= block
 
@@ -90,9 +106,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 +130,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 +152,29 @@ 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 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 Set socket permissions
-    #   bind('unix:///var/run/puma.sock?umask=0111')
+    # @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'
     def bind(url)
       @options[:binds] ||= []
       @options[:binds] << url
@@ -147,33 +186,40 @@ module Puma
 
     # 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}"
     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.
     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.
     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+.
+    # 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
+    #
+    # @example
+    #   daemonize false
     def daemonize(which=true)
       @options[:daemon] = which
     end
@@ -186,7 +232,13 @@ module Puma
       @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
@@ -212,30 +264,41 @@ module Puma
     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,6 +317,10 @@ module Puma
 
     # Load +path+ as a rackup file.
     #
+    # The default is "config.ru".
+    #
+    # @example
+    #   rackup '/u/apps/lolcat/config.ru'
     def rackup(path)
       @options[:rackup] = path.to_s
     end
@@ -268,16 +335,32 @@ module Puma
       @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 "0, 16".
+    #
+    # @example
+    #   threads 0, 16
+    # @example
+    #   threads 5, 5
     def threads(min, max)
       min = Integer(min)
       max = Integer(max)
@@ -293,81 +376,135 @@ 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.
+    #
+    # @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'
+    #   }
+    # @example For JRuby additional 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
+    #   }
     def ssl_bind(host, port, opts)
       verify = opts.fetch(:verify_mode, 'none')
+      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}"
+        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
-        bind "ssl://#{host}:#{port}?cert=#{opts[:cert]}&key=#{opts[:key]}&verify_mode=#{verify}"
+        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
     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.
+    # How many worker processes to run.  Typically this is set to
+    # to the number of available cores.
     #
+    # The default is 0.
+    #
+    # @note Cluster mode only.
     def workers(count)
       @options[:workers] = count.to_i
     end
 
-    # *Cluster mode only* Code to run immediately before master process
+    # 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_fork do
+    #     puts 'Before worker fork...'
+    #   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,7 +512,26 @@ module Puma
 
     alias_method :after_worker_boot, :after_worker_fork
 
+    # 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
+
     # 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
@@ -386,22 +542,28 @@ module Puma
       directory dir
     end
 
-    # Run the app as a raw TCP app instead of an HTTP rack app
+    # Run the app as a raw TCP app instead of an HTTP rack app.
     def tcp_mode
       @options[:mode] = :tcp
     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. This is off by default.
     #
+    # @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 +573,82 @@ 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.
+    #
+    # @note This is incompatible with +preload_app!+.
     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
+    def raise_exception_on_sigterm(answer=true)
+      @options[:raise_exception_on_sigterm] = 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
     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
     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.
     def worker_shutdown_timeout(timeout)
       @options[:worker_shutdown_timeout] = Integer(timeout)
     end
@@ -459,7 +665,7 @@ 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.
     def queue_requests(answer=true)
       @options[:queue_requests] = answer
     end
@@ -488,7 +694,7 @@ module Puma
     #                          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
+    #                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