puma 6.6.0 → 7.0.3

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
@@ -370,18 +370,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 +437,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.
@@ -654,8 +661,6 @@ module Puma
     # @example
     #   state_permission 0600
     #
-    # @version 5.0.0
-    #
     def state_permission(permission)
       @options[:state_permission] = permission
     end
@@ -729,9 +734,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 +745,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 +768,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 +788,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 +813,39 @@ 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 after puma is booted (works for both single and cluster modes).
     #
     # @example
-    #   on_booted do
+    #   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 +861,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 +893,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 +909,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 +937,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 +960,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,8 +974,8 @@ 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.
     #
@@ -1111,7 +1135,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 +1167,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
@@ -1194,8 +1218,6 @@ module Puma
     # @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 +1291,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.
     #
-    # The default is 10.
+    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 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.
@@ -1416,30 +1445,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

data/lib/puma/events.rb

@@ -3,7 +3,7 @@
 module Puma
 
   # This is an event sink used by `Puma::Server` to handle
-  # lifecycle events such as :on_booted, :on_restart, and :on_stopped.
+  # lifecycle events such as :after_booted, :before_restart, and :after_stopped.
   # Using `Puma::DSL` it is possible to register callback hooks
   # for each event type.
   class Events
@@ -30,28 +30,43 @@ module Puma
       h
     end
 
+    def after_booted(&block)
+      register(:after_booted, &block)
+    end
+
+    def before_restart(&block)
+      register(:before_restart, &block)
+    end
+
+    def after_stopped(&block)
+      register(:after_stopped, &block)
+    end
+
     def on_booted(&block)
-      register(:on_booted, &block)
+      Puma.deprecate_method_change :on_booted, __callee__, :after_booted
+      after_booted(&block)
     end
 
     def on_restart(&block)
-      register(:on_restart, &block)
+      Puma.deprecate_method_change :on_restart, __callee__, :before_restart
+      before_restart(&block)
     end
 
     def on_stopped(&block)
-      register(:on_stopped, &block)
+      Puma.deprecate_method_change :on_stopped, __callee__, :after_stopped
+      after_stopped(&block)
     end
 
-    def fire_on_booted!
-      fire(:on_booted)
+    def fire_after_booted!
+      fire(:after_booted)
     end
 
-    def fire_on_restart!
-      fire(:on_restart)
+    def fire_before_restart!
+      fire(:before_restart)
     end
 
-    def fire_on_stopped!
-      fire(:on_stopped)
+    def fire_after_stopped!
+      fire(:after_stopped)
     end
   end
 end

data/lib/puma/io_buffer.rb

@@ -34,13 +34,17 @@ module Puma
 
     alias_method :clear, :reset
 
-    # before Ruby 2.5, `write` would only take one argument
-    if RUBY_VERSION >= '2.5' && RUBY_ENGINE != 'truffleruby'
-      alias_method :append, :write
-    else
+    # Create an `IoBuffer#append` method that accepts multiple strings and writes them
+    if RUBY_ENGINE == 'truffleruby'
+      # truffleruby (24.2.1, like ruby 3.3.7)
+      #   StringIO.new.write("a", "b") # => `write': wrong number of arguments (given 2, expected 1) (ArgumentError)
       def append(*strs)
         strs.each { |str| write str }
       end
+    else
+      # Ruby 3+
+      #   StringIO.new.write("a", "b") # => 2
+      alias_method :append, :write
     end
   end
 end

data/lib/puma/launcher/bundle_pruner.rb

@@ -37,7 +37,7 @@ module Puma
           ENV['PUMA_BUNDLER_PRUNED'] = '1'
           ENV["BUNDLE_APP_CONFIG"] = bundle_app_config
           args = [Gem.ruby, puma_wild_path, '-I', dirs.join(':')] + @original_argv
-          # Ruby 2.0+ defaults to true which breaks socket activation
+          # Defaults to true which breaks socket activation
           args += [{:close_others => false}]
           Kernel.exec(*args)
         end

data/lib/puma/launcher.rb

@@ -22,12 +22,15 @@ module Puma
     #
     # +conf+ A Puma::Configuration object indicating how to run the server.
     #
-    # +launcher_args+ A Hash that currently has one required key `:events`,
-    # this is expected to hold an object similar to an `Puma::LogWriter.stdio`,
-    # this object will be responsible for broadcasting Puma's internal state
-    # to a logging destination. An optional key `:argv` can be supplied,
-    # this should be an array of strings, these arguments are re-used when
-    # restarting the puma server.
+    # +launcher_args+ A Hash that has a few optional keys.
+    # - +:log_writer+:: Expected to hold an object similar to `Puma::LogWriter.stdio`.
+    #   This object will be responsible for broadcasting Puma's internal state
+    #   to a logging destination.
+    # - +:events+:: Expected to hold an object similar to `Puma::Events`.
+    # - +:argv+:: Expected to be an array of strings.
+    # - +:env+:: Expected to hold a hash of environment variables.
+    #
+    # These arguments are re-used when restarting the puma server.
     #
     # Examples:
     #
@@ -48,18 +51,21 @@ module Puma
 
       env = launcher_args.delete(:env) || ENV
 
-      @config.options[:log_writer] = @log_writer
+      @config.clamp
+      @options = @config.options
+
+      @options[:log_writer] = @log_writer
+      @options[:logger] = @log_writer if clustered?
 
       # Advertise the Configuration
       Puma.cli_config = @config if defined?(Puma.cli_config)
+      log_config if env['PUMA_LOG_CONFIG']
 
-      @config.load
-
-      @binder        = Binder.new(@log_writer, conf)
-      @binder.create_inherited_fds(ENV).each { |k| ENV.delete k }
-      @binder.create_activated_fds(ENV).each { |k| ENV.delete k }
+      @binder        = Binder.new(@log_writer, @options)
+      @binder.create_inherited_fds(env).each { |k| env.delete k }
+      @binder.create_activated_fds(env).each { |k| env.delete k }
 
-      @environment = conf.environment
+      @environment = @config.environment
 
       # Load the systemd integration if we detect systemd's NOTIFY_SOCKET.
       # Skip this on JRuby though, because it is incompatible with the systemd
@@ -68,20 +74,17 @@ module Puma
         @config.plugins.create('systemd')
       end
 
-      if @config.options[:bind_to_activated_sockets]
-        @config.options[:binds] = @binder.synthesize_binds_from_activated_fs(
-          @config.options[:binds],
-          @config.options[:bind_to_activated_sockets] == 'only'
+      if @options[:bind_to_activated_sockets]
+        @options[:binds] = @binder.synthesize_binds_from_activated_fs(
+          @options[:binds],
+          @options[:bind_to_activated_sockets] == 'only'
         )
       end
 
-      @options = @config.options
-      @config.clamp
-
       @log_writer.formatter = LogWriter::PidFormatter.new if clustered?
-      @log_writer.formatter = options[:log_formatter] if @options[:log_formatter]
+      @log_writer.formatter = @options[:log_formatter] if @options[:log_formatter]
 
-      @log_writer.custom_logger = options[:custom_logger] if @options[:custom_logger]
+      @log_writer.custom_logger = @options[:custom_logger] if @options[:custom_logger]
 
       generate_restart_data
 
@@ -97,8 +100,6 @@ module Puma
       set_rack_environment
 
       if clustered?
-        @options[:logger] = @log_writer
-
         @runner = Cluster.new(self)
       else
         @runner = Single.new(self)
@@ -106,8 +107,6 @@ module Puma
       Puma.stats_object = @runner
 
       @status = :run
-
-      log_config if env['PUMA_LOG_CONFIG']
     end
 
     attr_reader :binder, :log_writer, :events, :config, :options, :restart_dir
@@ -277,7 +276,7 @@ module Puma
     end
 
     def do_graceful_stop
-      @events.fire_on_stopped!
+      @events.fire_after_stopped!
       @runner.stop_blocked
     end
 
@@ -289,8 +288,8 @@ module Puma
     end
 
     def restart!
-      @events.fire_on_restart!
-      @config.run_hooks :on_restart, self, @log_writer
+      @events.fire_before_restart!
+      @config.run_hooks :before_restart, self, @log_writer
 
       if Puma.jruby?
         close_binder_listeners

data/lib/puma/minissl.rb

@@ -172,7 +172,6 @@ module Puma
             end
           end
         rescue IOError, SystemCallError
-          Puma::Util.purge_interrupt_queue
           # nothing
         ensure
           @socket.close

data/lib/puma/plugin/systemd.rb

@@ -14,9 +14,9 @@ Puma::Plugin.create do
     launcher.log_writer.log "* Enabling systemd notification integration"
 
     # hook_events
-    launcher.events.on_booted { Puma::SdNotify.ready }
-    launcher.events.on_stopped { Puma::SdNotify.stopping }
-    launcher.events.on_restart { Puma::SdNotify.reloading }
+    launcher.events.after_booted { Puma::SdNotify.ready }
+    launcher.events.after_stopped { Puma::SdNotify.stopping }
+    launcher.events.before_restart { Puma::SdNotify.reloading }
 
     # start watchdog
     if Puma::SdNotify.watchdog?