puma 7.0.4 → 8.0.0

data/lib/puma/server.rb

@@ -11,7 +11,7 @@ require_relative 'reactor'
 require_relative 'client'
 require_relative 'binder'
 require_relative 'util'
-require_relative 'request'
+require_relative 'response'
 require_relative 'configuration'
 require_relative 'cluster_accept_loop_delay'
 
@@ -19,9 +19,6 @@ require 'socket'
 require 'io/wait' unless Puma::HAS_NATIVE_IO_WAIT
 
 module Puma
-  # Add `Thread#puma_server` and `Thread#puma_server=`
-  Thread.attr_accessor(:puma_server)
-
   # The HTTP Server itself. Serves out a single Rack app.
   #
   # This class is used by the `Puma::Single` and `Puma::Cluster` classes
@@ -34,15 +31,15 @@ module Puma
   # Each `Puma::Server` will have one reactor and one thread pool.
   class Server
     module FiberPerRequest
-      def handle_request(client, requests)
+      def handle_request(processor, client, requests)
         Fiber.new do
           super
         end.resume
       end
     end
 
-    include Puma::Const
-    include Request
+    include Const
+    include Response
 
     attr_reader :options
     attr_reader :thread
@@ -262,7 +259,9 @@ module Puma
 
       @status = :run
 
-      @thread_pool = ThreadPool.new(thread_name, options) { |client| process_client client }
+      @thread_pool = ThreadPool.new(thread_name, options, server: self) do |processor, client|
+        process_client(processor, client)
+      end
 
       if @queue_requests
         @reactor = Reactor.new(@io_selector_backend) { |c|
@@ -302,12 +301,12 @@ module Puma
     # If read buffering is not done, and no other read buffering is performed (such as by an application server
     # such as nginx) then the application would be subject to a slow client attack.
     #
-    # For a graphical representation of how the request buffer works see [architecture.md](https://github.com/puma/puma/blob/master/docs/architecture.md#connection-pipeline).
+    # For a graphical representation of how the request buffer works see [architecture.md](https://github.com/puma/puma/blob/main/docs/architecture.md).
     #
     # The method checks to see if it has the full header and body with
     # the `Puma::Client#try_to_finish` method. If the full request has been sent,
     # then the request is passed to the ThreadPool (`@thread_pool << client`)
-    # so that a "worker thread" can pick up the request and begin to execute application logic.
+    # so that a "processor thread" can pick up the request and begin to execute application logic.
     # The Client is then removed from the reactor (return `true`).
     #
     # If a client object times out, a 408 response is written, its connection is closed,
@@ -404,6 +403,7 @@ module Puma
                   next
                 end
                 drain += 1 if shutting_down?
+
                 client = new_client(io, sock)
                 client.send(addr_send_name, addr_value) if addr_value
                 pool << client
@@ -447,7 +447,9 @@ module Puma
     def new_client(io, sock)
       client = Client.new(io, @binder.env(sock))
       client.listener = sock
+      client.env_set_http_version = @env_set_http_version
       client.http_content_length_limit = @http_content_length_limit
+      client.supported_http_methods = @supported_http_methods
       client
     end
 
@@ -473,17 +475,14 @@ module Puma
     # Given a connection on +client+, handle the incoming requests,
     # or queue the connection in the Reactor if no request is available.
     #
-    # This method is called from a ThreadPool worker thread.
+    # This method is called from a ThreadPool processor thread.
     #
     # This method supports HTTP Keep-Alive so it may, depending on if the client
     # indicates that it supports keep alive, wait for another request before
     # returning.
     #
     # Return true if one or more requests were processed.
-    def process_client(client)
-      # Advertise this server into the thread
-      Thread.current.puma_server = self
-
+    def process_client(processor, client)
       close_socket = true
 
       requests = 0
@@ -502,31 +501,41 @@ module Puma
           client.finish(@first_data_timeout)
         end
 
-        @requests_count += 1
-        case handle_request(client, requests + 1)
-        when false
-        when :async
-          close_socket = false
-        when true
-          requests += 1
+        can_loop = true
+        while can_loop
+          can_loop = false
+          @requests_count += 1
+          case handle_request(processor, client, requests + 1)
+          when :close
+          when :async
+            close_socket = false
+          when :keep_alive
+            requests += 1
 
-          client.reset
+            client.reset
 
-          # This indicates data exists in the client read buffer and there may be
-          # additional requests on it, so process them
-          next_request_ready = if client.has_back_to_back_requests?
-            with_force_shutdown(client) { client.process_back_to_back_requests }
-          else
-            with_force_shutdown(client) { client.eagerly_finish }
-          end
+            # This indicates data exists in the client read buffer and there may be
+            # additional requests on it, so process them
+            next_request_ready = if client.has_back_to_back_requests?
+              with_force_shutdown(client) { client.process_back_to_back_requests }
+            else
+              with_force_shutdown(client) { client.eagerly_finish }
+            end
 
-          if next_request_ready
-            @thread_pool << client
-            close_socket = false
-          elsif @queue_requests
-            client.set_timeout @persistent_timeout
-            if @reactor.add client
-              close_socket = false
+            if next_request_ready
+              # When Puma has spare threads, allow this one to be monopolized
+              # Perf optimization for https://github.com/puma/puma/issues/3788
+              if @thread_pool.waiting > 0
+                can_loop = true
+              else
+                @thread_pool << client
+                close_socket = false
+              end
+            elsif @queue_requests
+              client.set_timeout @persistent_timeout
+              if @reactor.add client
+                close_socket = false
+              end
             end
           end
         end
@@ -573,7 +582,7 @@ module Puma
         lowlevel_error(e, client.env)
         @log_writer.ssl_error e, client.io
       when HttpParserError
-        response_to_error(client, requests, e, 400)
+        response_to_error(client, requests, e, client.error_status_code || 400)
         @log_writer.parse_error e, client
       when HttpParserError501
         response_to_error(client, requests, e, 501)
@@ -606,7 +615,15 @@ module Puma
     end
 
     def response_to_error(client, requests, err, status_code)
-      status, headers, res_body = lowlevel_error(err, client.env, status_code)
+      # @todo remove sometime later
+      if status_code == 413
+        status = 413
+        res_body = ["Payload Too Large"]
+        headers = {}
+        headers[CONTENT_LENGTH2] = 17
+      else
+        status, headers, res_body = lowlevel_error(err, client.env, status_code)
+      end
       prepare_response(status, headers, res_body, requests, client)
     end
     private :response_to_error
@@ -614,32 +631,11 @@ module Puma
     # Wait for all outstanding requests to finish.
     #
     def graceful_shutdown
-      if options[:shutdown_debug]
-        threads = Thread.list
-        total = threads.size
-
-        pid = Process.pid
-
-        $stdout.syswrite "#{pid}: === Begin thread backtrace dump ===\n"
-
-        threads.each_with_index do |t,i|
-          $stdout.syswrite "#{pid}: Thread #{i+1}/#{total}: #{t.inspect}\n"
-          $stdout.syswrite "#{pid}: #{t.backtrace.join("\n#{pid}: ")}\n\n"
-        end
-        $stdout.syswrite "#{pid}: === End thread backtrace dump ===\n"
-      end
-
       if @status != :restart
         @binder.close
       end
 
-      if @thread_pool
-        if timeout = options[:force_shutdown_after]
-          @thread_pool.shutdown timeout.to_f
-        else
-          @thread_pool.shutdown
-        end
-      end
+      @thread_pool.shutdown(options[:force_shutdown_after])
     end
 
     def notify_safely(message)
@@ -656,7 +652,7 @@ module Puma
     end
     private :notify_safely
 
-    # Stops the acceptor thread and then causes the worker threads to finish
+    # Stops the acceptor thread and then causes the processor threads to finish
     # off the request queue before finally exiting.
 
     def stop(sync=false)
@@ -706,7 +702,7 @@ module Puma
 
     def reset_max
       @reactor.reactor_max = 0 if @reactor
-      @thread_pool.reset_max
+      @thread_pool&.reset_max
     end
 
     # below are 'delegations' to binder
@@ -726,6 +722,49 @@ module Puma
       @binder.add_unix_listener path, umask, mode, backlog
     end
 
+    # Updates the minimum and maximum number of threads in the thread pool.
+    #
+    # This method allows dynamic adjustment of the thread pool size while the server
+    # is running. It validates the provided values and updates both the thread pool
+    # and the server's thread configuration.
+    #
+    # @param min [Integer] The minimum number of threads to maintain in the pool.
+    #   Defaults to the current minimum if not specified. Must be greater than 0
+    #   and less than or equal to max.
+    # @param max [Integer] The maximum number of threads allowed in the pool.
+    #   Defaults to the current maximum if not specified. Must be greater than or
+    #   equal to min.
+    #
+    # @return [void]
+    #
+    # @note If validation fails, a warning message is logged and no changes are made.
+    #
+    # @example Update both min and max threads
+    #   server.update_thread_pool_min_max(min: 2, max: 8)
+    #
+    # @example Update only the minimum threads
+    #   server.update_thread_pool_min_max(min: 4)
+    #
+    # @example Update only the maximum threads
+    #   server.update_thread_pool_min_max(max: 16)
+    #
+    def update_thread_pool_min_max(min: @min_threads, max: @max_threads)
+      if min > max
+        @log_writer.log "`min' value cannot be greater than `max' value."
+        return
+      end
+
+      if min < 0
+        @log_writer.log "`min' value cannot be less than 0"
+        return
+      end
+
+      @thread_pool&.with_mutex do
+        @thread_pool.min, @thread_pool.max = min, max
+        @min_threads, @max_threads = min, max
+      end
+    end
+
     # @!attribute [r] connected_ports
     def connected_ports
       @binder.connected_ports

data/lib/puma/server_plugin_control.rb

@@ -0,0 +1,32 @@
+module Puma
+  # ServerPluginControl provides a control interface for server plugins to
+  # interact with and manage server settings dynamically.
+  #
+  # This class acts as a facade between plugins and the Puma server,
+  # allowing plugins to safely modify server configuration and thread pool
+  # settings without direct access to the server's internal state.
+  #
+  class ServerPluginControl
+    def initialize(server)
+      @server = server
+    end
+
+    # Returns the maximum number of threads in the thread pool.
+    def max_threads
+      @server.max_threads
+    end
+
+    # Returns the minimum number of threads in the thread pool.
+    def min_threads
+      @server.min_threads
+    end
+
+    # Updates the minimum and maximum number of threads in the thread pool.
+    #
+    # @see Puma::Server#update_thread_pool_min_max
+    #
+    def update_thread_pool_min_max(min: max_threads, max: min_threads)
+      @server.update_thread_pool_min_max(min: min, max: max)
+    end
+  end
+end

data/lib/puma/single.rb

@@ -49,8 +49,8 @@ module Puma
 
       start_control
 
-      @server = server = start_server
-      server_thread = server.run
+      @server = start_server
+      server_thread = @server.run
 
       log "Use Ctrl-C to stop"
 

data/lib/puma/state_file.rb

@@ -32,10 +32,11 @@ module Puma
             "#{k}: \"#{v}\"\n" : "#{k}: #{v}\n")
         end
       end
+
       if permission
-        File.write path, contents, mode: 'wb:UTF-8'
-      else
         File.write path, contents, mode: 'wb:UTF-8', perm: permission
+      else
+        File.write path, contents, mode: 'wb:UTF-8'
       end
     end
 

data/lib/puma/thread_pool.rb

@@ -3,8 +3,13 @@
 require 'thread'
 
 require_relative 'io_buffer'
+require_relative 'server_plugin_control'
 
 module Puma
+
+  # Add `Thread#puma_server` and `Thread#puma_server=`
+  Thread.attr_accessor(:puma_server)
+
   # Internal Docs for A simple thread pool management object.
   #
   # Each Puma "worker" has a thread pool to process requests.
@@ -20,6 +25,51 @@ module Puma
     class ForceShutdown < RuntimeError
     end
 
+    class ProcessorThread
+      attr_accessor :thread
+      attr_writer :marked_as_io_thread
+
+      def initialize(pool)
+        @pool = pool
+        @thread = nil
+        @marked_as_io_thread = false
+      end
+
+      def mark_as_io_thread!
+        unless @marked_as_io_thread
+          @marked_as_io_thread = true
+
+          # Immediately signal the pool that it can spawn a new thread
+          # if there's some work in the queue.
+          @pool.spawn_thread_if_needed
+        end
+      end
+
+      def marked_as_io_thread?
+        @marked_as_io_thread
+      end
+
+      def alive?
+        @thread&.alive?
+      end
+
+      def join(...)
+        @thread.join(...)
+      end
+
+      def kill(...)
+        @thread.kill(...)
+      end
+
+      def [](key)
+        @thread[key]
+      end
+
+      def raise(...)
+        @thread.raise(...)
+      end
+    end
+
     # How long, after raising the ForceShutdown of a thread during
     # forced shutdown mode, to wait for the thread to try and finish
     # up its work before leaving the thread to die on the vine.
@@ -33,7 +83,9 @@ module Puma
     # The block passed is the work that will be performed in each
     # thread.
     #
-    def initialize(name, options = {}, &block)
+    def initialize(name, options = {}, server: nil, &block)
+      @server = server
+
       @not_empty = ConditionVariable.new
       @not_full = ConditionVariable.new
       @mutex = Mutex.new
@@ -46,10 +98,13 @@ module Puma
       @name = name
       @min = Integer(options[:min_threads])
       @max = Integer(options[:max_threads])
+      @max_io_threads = Integer(options[:max_io_threads] || 0)
+
       # Not an 'exposed' option, options[:pool_shutdown_grace_time] is used in CI
       # to shorten @shutdown_grace_time from SHUTDOWN_GRACE_TIME. Parallel CI
       # makes stubbing constants difficult.
       @shutdown_grace_time = Float(options[:pool_shutdown_grace_time] || SHUTDOWN_GRACE_TIME)
+      @shutdown_debug = options[:shutdown_debug]
       @block = block
       @out_of_band = options[:out_of_band]
       @out_of_band_running = false
@@ -64,7 +119,7 @@ module Puma
       @trim_requested = 0
       @out_of_band_pending = false
 
-      @workers = []
+      @processors = []
 
       @auto_trim = nil
       @reaper = nil
@@ -81,6 +136,7 @@ module Puma
     end
 
     attr_reader :spawned, :trim_requested, :waiting
+    attr_accessor :min, :max
 
     # generate stats hash so as not to perform multiple locks
     # @return [Hash] hash containing stat info from ThreadPool
@@ -90,8 +146,9 @@ module Puma
         @backlog_max = 0
         { backlog: @todo.size,
           running: @spawned,
-          pool_capacity: @waiting + (@max - @spawned),
+          pool_capacity: pool_capacity,
           busy_threads: @spawned - @waiting + @todo.size,
+          io_threads: @processors.count(&:marked_as_io_thread?),
           backlog_max: temp
         }
       end
@@ -115,7 +172,7 @@ module Puma
 
     # @!attribute [r] pool_capacity
     def pool_capacity
-      waiting + (@max - spawned)
+      (waiting + (@max - spawned)).clamp(0, Float::INFINITY)
     end
 
     # @!attribute [r] busy_threads
@@ -132,8 +189,12 @@ module Puma
       @spawned += 1
 
       trigger_before_thread_start_hooks
-      th = Thread.new(@spawned) do |spawned|
+      processor = ProcessorThread.new(self)
+      processor.thread = Thread.new(processor, @spawned) do |processor, spawned|
         Puma.set_thread_name '%s tp %03i' % [@name, spawned]
+        # Advertise server into the thread
+        Thread.current.puma_server = @server
+
         todo  = @todo
         block = @block
         mutex = @mutex
@@ -144,11 +205,23 @@ module Puma
           work = nil
 
           mutex.synchronize do
+            if processor.marked_as_io_thread?
+              if @processors.count { |t| !t.marked_as_io_thread? } < @max
+                # We're not at max processor threads, so the io thread can rejoin the normal population.
+                processor.marked_as_io_thread = false
+              else
+                # We're already at max threads, so we exit the extra io thread.
+                @processors.delete(processor)
+                trigger_before_thread_exit_hooks
+                Thread.exit
+              end
+            end
+
             while todo.empty?
               if @trim_requested > 0
                 @trim_requested -= 1
                 @spawned -= 1
-                @workers.delete th
+                @processors.delete(processor)
                 not_full.signal
                 trigger_before_thread_exit_hooks
                 Thread.exit
@@ -170,16 +243,16 @@ module Puma
           end
 
           begin
-            @out_of_band_pending = true if block.call(work)
+            @out_of_band_pending = true if block.call(processor, work)
           rescue Exception => e
             STDERR.puts "Error reached top of thread-pool: #{e.message} (#{e.class})"
           end
         end
       end
 
-      @workers << th
+      @processors << processor
 
-      th
+      processor
     end
 
     private :spawn_thread
@@ -189,7 +262,7 @@ module Puma
 
       @before_thread_start.each do |b|
         begin
-          b[:block].call
+          b[:block].call(ServerPluginControl.new(@server))
         rescue Exception => e
           STDERR.puts "WARNING before_thread_start hook failed with exception (#{e.class}) #{e.message}"
         end
@@ -248,6 +321,16 @@ module Puma
         @mutex.synchronize(&block)
     end
 
+    # :nodoc:
+    #
+    # Must be called with @mutex held!
+    #
+    def can_spawn_processor?
+      io_processors_count = @processors.count(&:marked_as_io_thread?)
+      extra_io_processors_count = io_processors_count > @max_io_threads ? io_processors_count - @max_io_threads : 0
+      (@spawned - io_processors_count) < (@max - extra_io_processors_count)
+    end
+
     # Add +work+ to the todo list for a Thread to pickup and process.
     def <<(work)
       with_mutex do
@@ -259,12 +342,21 @@ module Puma
         t = @todo.size
         @backlog_max = t if t > @backlog_max
 
-        if @waiting < @todo.size and @spawned < @max
+        if @waiting < @todo.size and can_spawn_processor?
           spawn_thread
         end
 
         @not_empty.signal
       end
+      self
+    end
+
+    def spawn_thread_if_needed # :nodoc:
+      with_mutex do
+        if @waiting < @todo.size and can_spawn_processor?
+          spawn_thread
+        end
+      end
     end
 
     # If there are any free threads in the pool, tell one to go ahead
@@ -285,16 +377,12 @@ module Puma
     # spawned counter so that new healthy threads could be created again.
     def reap
       with_mutex do
-        dead_workers = @workers.reject(&:alive?)
+        @processors, dead_processors = @processors.partition(&:alive?)
 
-        dead_workers.each do |worker|
-          worker.kill
+        dead_processors.each do |processor|
+          processor.kill
           @spawned -= 1
         end
-
-        @workers.delete_if do |w|
-          dead_workers.include?(w)
-        end
       end
     end
 
@@ -353,7 +441,7 @@ module Puma
     # Next, wait an extra +@shutdown_grace_time+ seconds then force-kill remaining
     # threads. Finally, wait 1 second for remaining threads to exit.
     #
-    def shutdown(timeout=-1)
+    def shutdown(timeout)
       threads = with_mutex do
         @shutdown = true
         @trim_requested = @spawned
@@ -362,8 +450,12 @@ module Puma
 
         @auto_trim&.stop
         @reaper&.stop
-        # dup workers so that we join them all safely
-        @workers.dup
+        # dup processors so that we join them all safely
+        @processors.dup
+      end
+
+      if @shutdown_debug == true
+        shutdown_debug("Shutdown initiated")
       end
 
       if timeout == -1
@@ -373,13 +465,16 @@ module Puma
         join = ->(inner_timeout) do
           start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           threads.reject! do |t|
-            elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-            t.join inner_timeout - elapsed
+            remaining = inner_timeout - (Process.clock_gettime(Process::CLOCK_MONOTONIC) - start)
+            remaining > 0 && t.join(remaining)
           end
         end
 
         # Wait +timeout+ seconds for threads to finish.
         join.call(timeout)
+        if @shutdown_debug == :on_force && !threads.empty?
+          shutdown_debug("Shutdown timeout exceeded")
+        end
 
         # If threads are still running, raise ForceShutdown and wait to finish.
         @shutdown_mutex.synchronize do
@@ -389,6 +484,9 @@ module Puma
           end
         end
         join.call(@shutdown_grace_time)
+        if @shutdown_debug == :on_force && !threads.empty?
+          shutdown_debug("Shutdown grace timeout exceeded")
+        end
 
         # If threads are _still_ running, forcefully kill them and wait to finish.
         threads.each(&:kill)
@@ -396,7 +494,24 @@ module Puma
       end
 
       @spawned = 0
-      @workers = []
+      @processors = []
+    end
+
+    private
+
+    def shutdown_debug(message)
+      pid = Process.pid
+      threads = Thread.list
+
+      $stdout.syswrite "#{pid}: #{message}\n"
+      $stdout.syswrite "#{pid}: === Begin thread backtrace dump ===\n"
+
+      threads.each_with_index do |thread, index|
+        $stdout.syswrite "#{pid}: Thread #{index + 1}/#{threads.size}: #{thread.inspect}\n"
+        $stdout.syswrite "#{pid}: #{(thread.backtrace || []).join("\n#{pid}: ")}\n\n"
+      end
+
+      $stdout.syswrite "#{pid}: === End thread backtrace dump ===\n"
     end
   end
 end

data/lib/rack/handler/puma.rb

@@ -109,7 +109,7 @@ module Puma
         end
 
         if port
-          host ||= ::Puma::Configuration::DEFAULTS[:tcp_host]
+          host ||= ::Puma::Configuration.default_tcp_host
           config.port port, host
         end
       end