puma 6.6.0 → 8.0.2

data/lib/puma/dsl.rb

@@ -13,7 +13,7 @@ module Puma
   #   config = Configuration.new({}) do |user_config|
   #     user_config.port 3001
   #   end
-  #   config.load
+  #   config.clamp
   #
   #   puts config.options[:binds] # => "tcp://127.0.0.1:3001"
   #
@@ -25,7 +25,7 @@ module Puma
   # Resulting configuration:
   #
   #   config = Configuration.new(config_file: "puma_config.rb")
-  #   config.load
+  #   config.clamp
   #
   #   puts config.options[:binds] # => "tcp://127.0.0.1:3002"
   #
@@ -43,11 +43,11 @@ module Puma
   #
   # The following hooks have been updated:
   #
-  #     | DSL Method         |  Options Key            | Fork Block Location |
-  #     | on_worker_boot     | :before_worker_boot     | inside, before      |
-  #     | on_worker_shutdown | :before_worker_shutdown | inside, after       |
-  #     | on_refork          | :before_refork          | inside              |
-  #     | after_refork       | :after_refork           | inside              |
+  #     | DSL Method             |  Options Key            | Fork Block Location |
+  #     | before_worker_boot     | :before_worker_boot     | inside, before      |
+  #     | before_worker_shutdown | :before_worker_shutdown | inside, after       |
+  #     | before_refork          | :before_refork          | inside              |
+  #     | after_refork           | :after_refork           | inside              |
   #
   class DSL
     ON_WORKER_KEY = [String, Symbol].freeze
@@ -155,7 +155,7 @@ module Puma
     end
 
     def default_host
-      @options[:default_host] || Configuration::DEFAULTS[:tcp_host]
+      @options[:default_host] || Configuration.default_tcp_host
     end
 
     def inject(&blk)
@@ -216,6 +216,8 @@ module Puma
     #   activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
     # @example
     #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
+    # @example
+    #   activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true, data_only: true}
     #
     def activate_control_app(url="auto", opts={})
       if url == "auto"
@@ -240,6 +242,7 @@ module Puma
 
       @options[:control_auth_token] = auth_token
       @options[:control_url_umask] = opts[:umask] if opts[:umask]
+      @options[:control_data_only] = opts[:data_only] if opts[:data_only]
     end
 
     # Load additional configuration from a file.
@@ -257,7 +260,8 @@ module Puma
     # accepted protocols. Multiple urls can be bound to, calling +bind+ does
     # not overwrite previous bindings.
     #
-    # The default is "tcp://0.0.0.0:9292".
+    # The default is "tcp://[::]:9292" when IPv6 interfaces are available,
+    # otherwise "tcp://0.0.0.0:9292".
     #
     # You can use query parameters within the url to specify options:
     #
@@ -276,7 +280,7 @@ module Puma
     # @example SSL cert for mutual TLS (mTLS)
     #   bind 'ssl://127.0.0.1:9292?key=key.key&cert=cert.pem&ca=ca.pem&verify_mode=force_peer'
     # @example Disable optimization for low latency
-    #   bind 'tcp://0.0.0.0:9292?low_latency=false'
+    #   bind 'tcp://[::]:9292?low_latency=false'
     # @example Socket permissions
     #   bind 'unix:///var/run/puma.sock?umask=0111'
     #
@@ -346,7 +350,7 @@ module Puma
 
     # Define how long persistent connections can be idle before Puma closes them.
     #
-    # The default is 20 seconds.
+    # The default is 65 seconds.
     #
     # @example
     #   persistent_timeout 30
@@ -370,18 +374,21 @@ module Puma
       @options[:idle_timeout] = Integer(seconds)
     end
 
-    # Work around leaky apps that leave garbage in Thread locals
-    # across requests.
+    # Use a clean fiber per request which ensures a clean slate for fiber
+    # locals and fiber storage. Also provides a cleaner backtrace with less
+    # Puma internal stack frames.
     #
     # The default is +false+.
     #
     # @example
-    #   clean_thread_locals
+    #   fiber_per_request
     #
-    def clean_thread_locals(which=true)
-      @options[:clean_thread_locals] = which
+    def fiber_per_request(which=true)
+      @options[:fiber_per_request] = which
     end
 
+    alias clean_thread_locals fiber_per_request
+
     # When shutting down, drain the accept socket of pending connections and
     # process them. This loops over the accept socket until there are no more
     # read events and then stops looking and waits for the requests to finish.
@@ -434,14 +441,18 @@ module Puma
     # This can be called multiple times to add code each time.
     #
     # @example
-    #   on_restart do
+    #   before_restart do
     #     puts 'On restart...'
     #   end
     #
-    def on_restart(&block)
-      process_hook :on_restart, nil, block, 'on_restart'
+    def before_restart(&block)
+      Puma.deprecate_method_change :on_restart, __callee__, __method__
+
+      process_hook :before_restart, nil, block
     end
 
+    alias_method :on_restart, :before_restart
+
     # Command to use to restart Puma. This should be just how to
     # load Puma itself (ie. 'ruby -Ilib bin/puma'), not the arguments
     # to Puma, as those are the same as the original process.
@@ -585,6 +596,29 @@ module Puma
       @options[:max_threads] = max
     end
 
+    # Configure the max number of IO threads.
+    #
+    # When request handlers know the current requests will no longer use a significant amount
+    # of CPU, they can mark the current request as IO bound using <tt>env["puma.mark_as_io_bound"]</tt>.
+    #
+    # Threads marked as IO bound are allowed to go over the max thread limit.
+    #
+    # @example
+    #   threads 5
+    #   max_io_threads 5
+    #
+    # The above example allows for 5 regular threads and 5 IO threads to process requests concurrently.
+    # Any IO thread over the limit is counted as a regular thread, hence the above configuration also
+    # allows for 3 regular threads and 7 IO threads for example.
+    def max_io_threads(max)
+      max = Integer(max)
+      if max < 0
+        raise "The maximum number of IO threads (#{max}) must be a positive number"
+      end
+
+      @options[:max_io_threads] = max
+    end
+
     # Instead of using +bind+ and manually constructing a URI like:
     #
     #    bind 'ssl://127.0.0.1:9292?key=key_path&cert=cert_path'
@@ -649,32 +683,37 @@ module Puma
       @options[:state] = path.to_s
     end
 
-    # Use +permission+ to restrict permissions for the state file.
+    # Use +permission+ to restrict permissions for the state file.  By convention,
+    # +permission+ is an octal number (e.g. `0640` or `0o640`).
     #
     # @example
     #   state_permission 0600
     #
-    # @version 5.0.0
-    #
     def state_permission(permission)
       @options[:state_permission] = permission
     end
 
-    # How many worker processes to run.  Typically this is set to
-    # the number of available cores.
+    # How many worker processes to run. Typically this is set to the number of
+    # available cores.
     #
     # The default is the value of the environment variable +WEB_CONCURRENCY+ if
-    # set, otherwise 0.
+    # set, otherwise 0. Passing +:auto+ will set the value to
+    # +Concurrent.available_processor_count+ (requires the concurrent-ruby gem).
+    # On some platforms (e.g. under CPU quotas) this may be fractional, and Puma
+    # will round down. If it rounds down to 0, Puma will run in single mode and
+    # cluster-only hooks like +before_worker_boot+ will not execute.
+    # If you rely on cluster-only hooks, set an explicit worker count.
     #
-    # @note Cluster mode only.
+    # A value of 0 or nil means run in single mode.
     #
     # @example
     #   workers 2
+    #   workers :auto
     #
     # @see Puma::Cluster
     #
     def workers(count)
-      @options[:workers] = count.to_i
+      @options[:workers] = count.nil? ? 0 : @config.send(:parse_workers, count)
     end
 
     # Disable warning message when running in cluster mode with a single worker.
@@ -712,6 +751,44 @@ module Puma
       @options[:silence_fork_callback_warning] = true
     end
 
+    # Code to run only in single mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Single mode only.
+    #
+    # @example
+    #   single do
+    #     silence_fork_callback_warning
+    #   end
+    #
+    def single(&block)
+      raise ArgumentError, "A block must be provided to `single`" unless block
+
+      @options[:single] ||= []
+      @options[:single] << block
+    end
+
+    # Code to run only in cluster mode.
+    # Runs after all config files are loaded.
+    #
+    # This can be called multiple times.
+    #
+    # @note Cluster mode only.
+    #
+    # @example
+    #   cluster do
+    #     prune_bundler
+    #   end
+    #
+    def cluster(&block)
+      raise ArgumentError, "A block must be provided to `cluster`" unless block
+
+      @options[:cluster] ||= []
+      @options[:cluster] << block
+    end
+
     # Code to run immediately before master process
     # forks workers (once on boot). These hooks can block if necessary
     # to wait for background operations unknown to Puma to finish before
@@ -729,9 +806,7 @@ module Puma
     #   end
     #
     def before_fork(&block)
-      warn_if_in_single_mode('before_fork')
-
-      process_hook :before_fork, nil, block, 'before_fork'
+      process_hook :before_fork, nil, block, cluster_only: true
     end
 
     # Code to run in a worker when it boots to setup
@@ -742,16 +817,18 @@ module Puma
     # @note Cluster mode only.
     #
     # @example
-    #   on_worker_boot do
+    #   before_worker_boot do
     #     puts 'Before worker boot...'
     #   end
     #
-    def on_worker_boot(key = nil, &block)
-      warn_if_in_single_mode('on_worker_boot')
+    def before_worker_boot(key = nil, &block)
+      Puma.deprecate_method_change :on_worker_boot, __callee__, __method__
 
-      process_hook :before_worker_boot, key, block, 'on_worker_boot'
+      process_hook :before_worker_boot, key, block, cluster_only: true
     end
 
+    alias_method :on_worker_boot, :before_worker_boot
+
     # Code to run immediately before a worker shuts
     # down (after it has finished processing HTTP requests). The worker's
     # index is passed as an argument. These hooks
@@ -763,16 +840,18 @@ module Puma
     # @note Cluster mode only.
     #
     # @example
-    #   on_worker_shutdown do
+    #   before_worker_shutdown do
     #     puts 'On worker shutdown...'
     #   end
     #
-    def on_worker_shutdown(key = nil, &block)
-      warn_if_in_single_mode('on_worker_shutdown')
+    def before_worker_shutdown(key = nil, &block)
+      Puma.deprecate_method_change :on_worker_shutdown, __callee__, __method__
 
-      process_hook :before_worker_shutdown, key, block, 'on_worker_shutdown'
+      process_hook :before_worker_shutdown, key, block, cluster_only: true
     end
 
+    alias_method :on_worker_shutdown, :before_worker_shutdown
+
     # Code to run in the master right before a worker is started. The worker's
     # index is passed as an argument.
     #
@@ -781,16 +860,18 @@ module Puma
     # @note Cluster mode only.
     #
     # @example
-    #   on_worker_fork do
+    #   before_worker_fork do
     #     puts 'Before worker fork...'
     #   end
     #
-    def on_worker_fork(&block)
-      warn_if_in_single_mode('on_worker_fork')
+    def before_worker_fork(&block)
+      Puma.deprecate_method_change :on_worker_fork, __callee__, __method__
 
-      process_hook :before_worker_fork, nil, block, 'on_worker_fork'
+      process_hook :before_worker_fork, nil, block, cluster_only: true
     end
 
+    alias_method :on_worker_fork, :before_worker_fork
+
     # Code to run in the master after a worker has been started. The worker's
     # index is passed as an argument.
     #
@@ -804,34 +885,53 @@ module Puma
     #   end
     #
     def after_worker_fork(&block)
-      warn_if_in_single_mode('after_worker_fork')
-
-      process_hook :after_worker_fork, nil, block, 'after_worker_fork'
+      process_hook :after_worker_fork, nil, block, cluster_only: true
     end
 
     alias_method :after_worker_boot, :after_worker_fork
 
-    # Code to run after puma is booted (works for both: single and clustered)
+    # Code to run in the master right after a worker has stopped. The worker's
+    # index and Process::Status are passed as arguments.
+    #
+    # @note Cluster mode only.
     #
     # @example
-    #   on_booted do
+    #   after_worker_shutdown do |worker_handle|
+    #     puts 'Worker crashed' unless worker_handle.process_status.success?
+    #   end
+    #
+    def after_worker_shutdown(&block)
+      process_hook :after_worker_shutdown, nil, block, cluster_only: true
+    end
+
+    # Code to run after puma is booted (works for both single and cluster modes).
+    #
+    # @example
+    #   after_booted do
     #     puts 'After booting...'
     #   end
     #
-    def on_booted(&block)
-      @config.options[:events].on_booted(&block)
+    def after_booted(&block)
+      Puma.deprecate_method_change :on_booted, __callee__, __method__
+
+      @config.events.after_booted(&block)
     end
 
+    alias_method :on_booted, :after_booted
+
     # Code to run after puma is stopped (works for both: single and clustered)
     #
     # @example
-    #   on_stopped do
+    #   after_stopped do
     #     puts 'After stopping...'
     #   end
     #
-    def on_stopped(&block)
-      @config.options[:events].on_stopped(&block)
+    def after_stopped(&block)
+      Puma.deprecate_method_change :on_stopped, __callee__, __method__
+
+      @config.events.after_stopped(&block)
     end
+    alias_method :on_stopped, :after_stopped
 
     # When `fork_worker` is enabled, code to run in Worker 0
     # before all other workers are re-forked from this process,
@@ -847,25 +947,27 @@ module Puma
     # @note Cluster mode with `fork_worker` enabled only.
     #
     # @example
-    #   on_refork do
+    #   before_refork do
     #     3.times {GC.start}
     #   end
     #
     # @version 5.0.0
     #
-    def on_refork(key = nil, &block)
-      warn_if_in_single_mode('on_refork')
+    def before_refork(key = nil, &block)
+      Puma.deprecate_method_change :on_refork, __callee__, __method__
 
-      process_hook :before_refork, key, block, 'on_refork'
+      process_hook :before_refork, key, block, cluster_only: true
     end
 
+    alias_method :on_refork, :before_refork
+
     # When `fork_worker` is enabled, code to run in Worker 0
     # after all other workers are re-forked from this process,
     # after the server has temporarily stopped serving requests
     # (once per complete refork cycle).
     #
     # This can be used to re-open any connections to remote servers
-    # (database, Redis, ...) that were closed via on_refork.
+    # (database, Redis, ...) that were closed via before_refork.
     #
     # This can be called multiple times to add several hooks.
     #
@@ -877,7 +979,7 @@ module Puma
     #   end
     #
     def after_refork(key = nil, &block)
-      process_hook :after_refork, key, block, 'after_refork'
+      process_hook :after_refork, key, block
     end
 
     # Provide a block to be executed just before a thread is added to the thread
@@ -893,14 +995,18 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @example
-    #   on_thread_start do
+    #   before_thread_start do
     #     puts 'On thread start...'
     #   end
     #
-    def on_thread_start(&block)
-      process_hook :before_thread_start, nil, block, 'on_thread_start'
+    def before_thread_start(&block)
+      Puma.deprecate_method_change :on_thread_start, __callee__, __method__
+
+      process_hook :before_thread_start, nil, block
     end
 
+    alias_method :on_thread_start, :before_thread_start
+
     # Provide a block to be executed after a thread is trimmed from the thread
     # pool. Be careful: while this block executes, Puma's main loop is
     # blocked, so no new requests will be picked up.
@@ -917,14 +1023,18 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     # @example
-    #   on_thread_exit do
+    #   before_thread_exit do
     #     puts 'On thread exit...'
     #   end
     #
-    def on_thread_exit(&block)
-      process_hook :before_thread_exit, nil, block, 'on_thread_exit'
+    def before_thread_exit(&block)
+      Puma.deprecate_method_change :on_thread_exit, __callee__, __method__
+
+      process_hook :before_thread_exit, nil, block
     end
 
+    alias_method :on_thread_exit, :before_thread_exit
+
     # Code to run out-of-band when the worker is idle.
     # These hooks run immediately after a request has finished
     # processing and there are no busy threads on the worker.
@@ -936,7 +1046,7 @@ module Puma
     # This can be called multiple times to add several hooks.
     #
     def out_of_band(&block)
-      process_hook :out_of_band, nil, block, 'out_of_band'
+      process_hook :out_of_band, nil, block
     end
 
     # The directory to operate out of.
@@ -950,12 +1060,13 @@ module Puma
       @options[:directory] = dir.to_s
     end
 
-    # Preload the application before starting the workers; this conflicts with
-    # phased restart feature.
+    # Preload the application before forking the workers; this conflicts with
+    # the phased restart feature.
     #
     # The default is +true+ if your app uses more than 1 worker.
     #
     # @note Cluster mode only.
+    # @note When using `fork_worker`, this only applies to worker 0.
     #
     # @example
     #   preload_app!
@@ -991,6 +1102,7 @@ module Puma
     # new Bundler context and thus can float around as the release
     # dictates.
     #
+    # @note Cluster mode only.
     # @note This is incompatible with +preload_app!+.
     # @note This is only supported for RubyGems 2.2+
     #
@@ -1096,7 +1208,7 @@ module Puma
 
     # Change the default worker timeout for booting.
     #
-    # The default is the value of `worker_timeout`.
+    # The default is 60 seconds.
     #
     # @note Cluster mode only.
     #
@@ -1111,7 +1223,7 @@ module Puma
 
     # Set the timeout for worker shutdown.
     #
-    # The default is 60 seconds.
+    # The default is 30 seconds.
     #
     # @note Cluster mode only.
     #
@@ -1143,10 +1255,10 @@ module Puma
     # @see Puma::Cluster#cull_workers
     #
     def worker_culling_strategy(strategy)
-      stategy = strategy.to_sym
+      strategy = strategy.to_sym
 
       if ![:youngest, :oldest].include?(strategy)
-        raise "Invalid value for worker_culling_strategy - #{stategy}"
+        raise "Invalid value for worker_culling_strategy - #{strategy}"
       end
 
       @options[:worker_culling_strategy] = strategy
@@ -1178,24 +1290,31 @@ module Puma
     # threads will be written to $stdout. This can help figure
     # out why shutdown is hanging.
     #
-    def shutdown_debug(val=true)
-      @options[:shutdown_debug] = val
+    # If `on_force` is true, the backtraces will be written only
+    # when the shutdown is forced i.e. not graceful.
+    #
+    # @see force_shutdown_after
+    def shutdown_debug(val = true, on_force: false)
+      @options[:shutdown_debug] = val && on_force ? :on_force : val
     end
 
-
-    # Attempts to route traffic to less-busy workers by causing them to delay
-    # listening on the socket, allowing workers which are not processing any
+    # Maximum delay of worker accept loop.
+    #
+    # Attempts to route traffic to less-busy workers by causing a busy worker to delay
+    # listening on the socket, allowing workers which are not processing as many
     # requests to pick up new requests first.
     #
     # The default is 0.005 seconds.
     #
-    # Only works on MRI. For all other interpreters, this setting does nothing.
+    # To turn off this feature, set the value to 0.
+    #
+    # @note Cluster mode with >= 2 workers only.
+    #
+    # @note Interpreters with forking support only.
     #
     # @see Puma::Server#handle_servers
     # @see Puma::ThreadPool#wait_for_less_busy_worker
     #
-    # @version 5.0.0
-    #
     def wait_for_less_busy_worker(val=0.005)
       @options[:wait_for_less_busy_worker] = val.to_f
     end
@@ -1269,24 +1388,31 @@ module Puma
     # A refork will automatically trigger once after the specified number of requests
     # (default 1000), or pass 0 to disable auto refork.
     #
+    # @note This is experimental.
     # @note Cluster mode only.
     #
-    # @version 5.0.0
-    #
     def fork_worker(after_requests=1000)
       @options[:fork_worker] = Integer(after_requests)
     end
 
-    # The number of requests to attempt inline before sending a client back to
-    # the reactor to be subject to normal ordering.
+    # @deprecated Use {#max_keep_alive} instead.
+    #
+    def max_fast_inline(num_of_requests)
+      Puma.deprecate_method_change :max_fast_inline, __method__, :max_keep_alive
+      @options[:max_keep_alive] ||= Float(num_of_requests) unless num_of_requests.nil?
+    end
+
+    # The number of requests a keep-alive client can submit before being closed.
+    # Note that some applications (server to server) may benefit from a very high
+    # number or Float::INFINITY.
     #
-    # The default is 10.
+    # The default is 999.
     #
     # @example
-    #   max_fast_inline 20
+    #   max_keep_alive 20
     #
-    def max_fast_inline(num_of_requests)
-      @options[:max_fast_inline] = Float(num_of_requests)
+    def max_keep_alive(num_of_requests)
+      @options[:max_keep_alive] = Float(num_of_requests) unless num_of_requests.nil?
     end
 
     # When `true`, keep-alive connections are maintained on inbound requests.
@@ -1328,7 +1454,7 @@ module Puma
     #
     # The default is +:auto+.
     #
-    # @see https://github.com/socketry/nio4r/blob/master/lib/nio/selector.rb
+    # @see https://github.com/socketry/nio4r/blob/main/lib/nio/selector.rb
     #
     def io_selector_backend(backend)
       @options[:io_selector_backend] = backend.to_sym
@@ -1416,30 +1542,21 @@ module Puma
       end
     end
 
-    def process_hook(options_key, key, block, meth)
+    def process_hook(options_key, key, block, cluster_only: false)
+      raise ArgumentError, "expected #{options_key} to be given a block" unless block
+
+      @config.hooks[options_key] = true
+
       @options[options_key] ||= []
-      if ON_WORKER_KEY.include? key.class
-        @options[options_key] << [block, key.to_sym]
+      hook_options = { block: block, cluster_only: cluster_only }
+      hook_options[:id] = if ON_WORKER_KEY.include?(key.class)
+        key.to_sym
       elsif key.nil?
-        @options[options_key] << block
+        nil
       else
-        raise "'#{meth}' key must be String or Symbol"
-      end
-    end
-
-    def warn_if_in_single_mode(hook_name)
-      return if @options[:silence_fork_callback_warning]
-      # user_options (CLI) have precedence over config file
-      workers_val = @config.options.user_options[:workers] || @options[:workers] ||
-        @config.puma_default_options[:workers] || 0
-      if workers_val == 0
-        log_string =
-          "Warning: You specified code to run in a `#{hook_name}` block, " \
-          "but Puma is not configured to run in cluster mode (worker count > 0), " \
-          "so your `#{hook_name}` block will not run."
-
-        LogWriter.stdio.log(log_string)
+        raise "'#{options_key}' key must be String or Symbol"
       end
+      @options[options_key] << hook_options
     end
   end
 end

data/lib/puma/error_logger.rb

@@ -78,10 +78,12 @@ module Puma
     def request_title(req)
       env = req.env
 
+      query_string = env[QUERY_STRING]
+
       REQUEST_FORMAT % [
         env[REQUEST_METHOD],
         env[REQUEST_PATH] || env[PATH_INFO],
-        env[QUERY_STRING] || "",
+        query_string.nil? || query_string.empty? ? "" : "?#{query_string}",
         env[HTTP_X_FORWARDED_FOR] || env[REMOTE_ADDR] || "-"
       ]
     end