puma 7.0.4 → 8.0.2

data/lib/puma/dsl.rb

@@ -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
@@ -592,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'
@@ -656,7 +683,8 @@ 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
@@ -665,21 +693,27 @@ module Puma
       @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.
@@ -717,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
@@ -818,6 +890,20 @@ module Puma
 
     alias_method :after_worker_boot, :after_worker_fork
 
+    # 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
+    #   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
@@ -980,6 +1066,7 @@ module Puma
     # 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!
@@ -1015,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+
     #
@@ -1120,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.
     #
@@ -1202,18 +1290,27 @@ 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
@@ -1357,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

data/lib/puma/launcher/bundle_pruner.rb

@@ -28,14 +28,12 @@ module Puma
 
         log '* Pruning Bundler environment'
         home = ENV['GEM_HOME']
-        bundle_gemfile = Bundler.original_env['BUNDLE_GEMFILE']
-        bundle_app_config = Bundler.original_env['BUNDLE_APP_CONFIG']
+        original_bundle_env = Bundler.original_env.select { |k, v| k.start_with?('BUNDLE_') && v }
 
         with_unbundled_env do
           ENV['GEM_HOME'] = home
-          ENV['BUNDLE_GEMFILE'] = bundle_gemfile
           ENV['PUMA_BUNDLER_PRUNED'] = '1'
-          ENV["BUNDLE_APP_CONFIG"] = bundle_app_config
+          original_bundle_env.each { |k, v| ENV[k] = v }
           args = [Gem.ruby, puma_wild_path, '-I', dirs.join(':')] + @original_argv
           # Defaults to true which breaks socket activation
           args += [{:close_others => false}]

data/lib/puma/launcher.rb

@@ -42,26 +42,40 @@ module Puma
     #   end
     #   Puma::Launcher.new(conf, log_writer: Puma::LogWriter.stdio).run
     def initialize(conf, launcher_args={})
-      @runner        = nil
-      @log_writer    = launcher_args[:log_writer] || LogWriter::DEFAULT
-      @events        = launcher_args[:events] || Events.new
-      @argv          = launcher_args[:argv] || []
-      @original_argv = @argv.dup
-      @config        = conf
-
-      env = launcher_args.delete(:env) || ENV
+      ## Minimal initialization before potential early restart (e.g. from bundle pruning)
 
+      @config = conf
+      # Advertise the CLI Configuration before config files are loaded
+      Puma.cli_config = @config if defined?(Puma.cli_config)
       @config.clamp
+
       @options = @config.options
 
+      @log_writer = launcher_args[:log_writer] || LogWriter::DEFAULT
+      @log_writer.formatter = LogWriter::PidFormatter.new if clustered?
+      @log_writer.formatter = @options[:log_formatter] if @options[:log_formatter]
+      @log_writer.custom_logger = @options[:custom_logger] if @options[:custom_logger]
       @options[:log_writer] = @log_writer
       @options[:logger] = @log_writer if clustered?
 
-      # Advertise the Configuration
-      Puma.cli_config = @config if defined?(Puma.cli_config)
+      @events = launcher_args[:events] || Events.new
+
+      @argv = launcher_args[:argv] || []
+      @original_argv = @argv.dup
+
+      ## End minimal initialization
+
+      generate_restart_data
+      Dir.chdir(@restart_dir)
+
+      prune_bundler!
+
+      env = launcher_args.delete(:env) || ENV
+
+      # Log after prune_bundler! to avoid duplicate logging if a restart occurs
       log_config if env['PUMA_LOG_CONFIG']
 
-      @binder        = Binder.new(@log_writer, @options)
+      @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 }
 
@@ -81,21 +95,10 @@ module Puma
         )
       end
 
-      @log_writer.formatter = LogWriter::PidFormatter.new if clustered?
-      @log_writer.formatter = @options[:log_formatter] if @options[:log_formatter]
-
-      @log_writer.custom_logger = @options[:custom_logger] if @options[:custom_logger]
-
-      generate_restart_data
-
       if clustered? && !Puma.forkable?
         unsupported "worker mode not supported on #{RUBY_ENGINE} on this platform"
       end
 
-      Dir.chdir(@restart_dir)
-
-      prune_bundler!
-
       @environment = @options[:environment] if @options[:environment]
       set_rack_environment
 
@@ -139,7 +142,10 @@ module Puma
     # Delete the configured pidfile
     def delete_pidfile
       path = @options[:pidfile]
-      File.unlink(path) if path && File.exist?(path)
+      begin
+        File.unlink(path) if path
+      rescue Errno::ENOENT
+      end
     end
 
     # Begin async shutdown of the server
@@ -381,9 +387,9 @@ module Puma
         # using it.
         @restart_dir = Dir.pwd
 
-        # Use the same trick as unicorn, namely favor PWD because
-        # it will contain an unresolved symlink, useful for when
-        # the pwd is /data/releases/current.
+      # Use the same trick as unicorn, namely favor PWD because
+      # it will contain an unresolved symlink, useful for when
+      # the pwd is /data/releases/current.
       elsif dir = ENV['PWD']
         s_env = File.stat(dir)
         s_pwd = File.stat(Dir.pwd)
@@ -470,8 +476,8 @@ module Puma
       end
 
       begin
-        unless Puma.jruby? # INFO in use by JVM already
-          Signal.trap "SIGINFO" do
+        if Puma.backtrace_signal
+          Signal.trap Puma.backtrace_signal do
             thread_status do |name, backtrace|
               @log_writer.log(name)
               @log_writer.log(backtrace.map { |bt| "  #{bt}" })
@@ -479,8 +485,7 @@ module Puma
           end
         end
       rescue Exception
-        # Not going to log this one, as SIGINFO is *BSD only and would be pretty annoying
-        # to see this constantly on Linux.
+        log "*** SIGINFO/SIGPWR not implemented, signal based backtrace unavailable!"
       end
     end
 

data/lib/puma/log_writer.rb

@@ -90,8 +90,14 @@ module Puma
       @debug
     end
 
-    def debug(str)
-      log("% #{str}") if @debug
+    def debug(str=nil, &block)
+      if @debug
+        if block_given?
+          log("% #{yield}")
+        else
+          log("% #{str}")
+        end
+      end
     end
 
     # Write +str+ to +@stderr+

data/lib/puma/reactor.rb

@@ -75,15 +75,12 @@ module Puma
     private
 
     def select_loop
-      close_selector = true
       begin
         until @input.closed? && @input.empty?
           # Wakeup any registered object that receives incoming data.
           # Block until the earliest timeout or Selector#wakeup is called.
           timeout = (earliest = @timeouts.first) && earliest.timeout
-          monitor_wake_up = false
           @selector.select(timeout) do |monitor|
-            monitor_wake_up = true
             wakeup!(monitor.value)
           end
 
@@ -103,18 +100,12 @@ module Puma
         STDERR.puts "Error in reactor loop escaped: #{e.message} (#{e.class})"
         STDERR.puts e.backtrace
 
-        # NoMethodError may be rarely raised when calling @selector.select, which
-        # is odd.  Regardless, it may continue for thousands of calls if retried.
-        # Also, when it raises, @selector.close also raises an error.
-        if !monitor_wake_up && NoMethodError === e
-          close_selector = false
-        else
-          retry
-        end
+        retry
       end
+
       # Wakeup all remaining objects on shutdown.
       @timeouts.each(&@block)
-      @selector.close if close_selector
+      @selector.close
     end
 
     # Start monitoring the object.