puma 6.4.3 → 8.0.2

data/lib/puma/server.rb

@@ -11,13 +11,14 @@ 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'
 
 require 'socket'
 require 'io/wait' unless Puma::HAS_NATIVE_IO_WAIT
 
 module Puma
-
   # The HTTP Server itself. Serves out a single Rack app.
   #
   # This class is used by the `Puma::Single` and `Puma::Cluster` classes
@@ -29,9 +30,18 @@ module Puma
   #
   # Each `Puma::Server` will have one reactor and one thread pool.
   class Server
-    include Puma::Const
-    include Request
+    module FiberPerRequest
+      def handle_request(processor, client, requests)
+        Fiber.new do
+          super
+        end.resume
+      end
+    end
+
+    include Const
+    include Response
 
+    attr_reader :options
     attr_reader :thread
     attr_reader :log_writer
     attr_reader :events
@@ -46,8 +56,6 @@ module Puma
     attr_accessor :app
     attr_accessor :binder
 
-    THREAD_LOCAL_KEY = :puma_server
-
     # Create a server for the rack app +app+.
     #
     # +log_writer+ is a Puma::LogWriter object used to log info and error messages.
@@ -74,6 +82,9 @@ module Puma
 
       @thread = nil
       @thread_pool = nil
+      @reactor = nil
+
+      @env_set_http_version = nil
 
       @options = if options.is_a?(UserFileDefaultOptions)
         options
@@ -91,9 +102,19 @@ module Puma
       @min_threads               = @options[:min_threads]
       @max_threads               = @options[:max_threads]
       @queue_requests            = @options[:queue_requests]
-      @max_fast_inline           = @options[:max_fast_inline]
+      @max_keep_alive            = @options[:max_keep_alive]
+      @enable_keep_alives        = @options[:enable_keep_alives]
+      @enable_keep_alives      &&= @queue_requests
       @io_selector_backend       = @options[:io_selector_backend]
       @http_content_length_limit = @options[:http_content_length_limit]
+      @cluster_accept_loop_delay = ClusterAcceptLoopDelay.new(
+        workers: @options[:workers],
+        max_delay: @options[:wait_for_less_busy_worker] || 0 # Real default is in Configuration::DEFAULTS, this is for unit testing
+      )
+
+      if @options[:fiber_per_request]
+        singleton_class.prepend(FiberPerRequest)
+      end
 
       # make this a hash, since we prefer `key?` over `include?`
       @supported_http_methods =
@@ -110,7 +131,7 @@ module Puma
       temp = !!(@options[:environment] =~ /\A(development|test)\z/)
       @leak_stack_on_error = @options[:environment] ? temp : true
 
-      @binder = Binder.new(log_writer)
+      @binder = Binder.new(log_writer, @options)
 
       ENV['RACK_ENV'] ||= "development"
 
@@ -130,7 +151,7 @@ module Puma
     class << self
       # @!attribute [r] current
       def current
-        Thread.current[THREAD_LOCAL_KEY]
+        Thread.current.puma_server
       end
 
       # :nodoc:
@@ -161,7 +182,6 @@ module Puma
         begin
           skt.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_CORK, 1) if skt.kind_of? TCPSocket
         rescue IOError, SystemCallError
-          Puma::Util.purge_interrupt_queue
         end
       end
 
@@ -170,7 +190,6 @@ module Puma
         begin
           skt.setsockopt(Socket::IPPROTO_TCP, Socket::TCP_CORK, 0) if skt.kind_of? TCPSocket
         rescue IOError, SystemCallError
-          Puma::Util.purge_interrupt_queue
         end
       end
     else
@@ -191,7 +210,6 @@ module Puma
         begin
           tcp_info = skt.getsockopt(Socket::IPPROTO_TCP, Socket::TCP_INFO)
         rescue IOError, SystemCallError
-          Puma::Util.purge_interrupt_queue
           @precheck_closing = false
           false
         else
@@ -216,7 +234,6 @@ module Puma
       @thread_pool&.spawned
     end
 
-
     # This number represents the number of requests that
     # the server is capable of taking right now.
     #
@@ -242,16 +259,21 @@ 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| reactor_wakeup c }
+        @reactor = Reactor.new(@io_selector_backend) { |c|
+          # Inversion of control, the reactor is calling a method on the server when it
+          # is done buffering a request or receives a new request from a keepalive connection.
+          self.reactor_wakeup(c)
+        }
         @reactor.run
       end
 
-
-      @thread_pool.auto_reap! if @options[:reaping_time]
-      @thread_pool.auto_trim! if @options[:auto_trim_time]
+      @thread_pool.auto_reap! if options[:reaping_time]
+      @thread_pool.auto_trim! if @min_threads != @max_threads && options[:auto_trim_time]
 
       @check, @notify = Puma::Util.pipe unless @notify
 
@@ -271,17 +293,20 @@ module Puma
     # This method is called from the Reactor thread when a queued Client receives data,
     # times out, or when the Reactor is shutting down.
     #
+    # While the code lives in the Server, the logic is executed on the reactor thread, independently
+    # from the server.
+    #
     # It is responsible for ensuring that a request has been completely received
     # before it starts to be processed by the ThreadPool. This may be known as read buffering.
     # 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,
@@ -305,25 +330,28 @@ module Puma
       end
     rescue StandardError => e
       client_error(e, client)
-      client.close
+      close_client_safely(client)
       true
     end
 
     def handle_servers
+      @env_set_http_version = Object.const_defined?(:Rack) && ::Rack.respond_to?(:release) &&
+        Gem::Version.new(::Rack.release) < Gem::Version.new('3.1.0')
+
       begin
         check = @check
         sockets = [check] + @binder.ios
         pool = @thread_pool
         queue_requests = @queue_requests
-        drain = @options[:drain_on_shutdown] ? 0 : nil
+        drain = options[:drain_on_shutdown] ? 0 : nil
 
-        addr_send_name, addr_value = case @options[:remote_address]
+        addr_send_name, addr_value = case options[:remote_address]
         when :value
-          [:peerip=, @options[:remote_address_value]]
+          [:peerip=, options[:remote_address_value]]
         when :header
-          [:remote_addr_header=, @options[:remote_address_header]]
+          [:remote_addr_header=, options[:remote_address_header]]
         when :proxy_protocol
-          [:expect_proxy_proto=, @options[:remote_address_proxy_protocol]]
+          [:expect_proxy_proto=, options[:remote_address_proxy_protocol]]
         else
           [nil, nil]
         end
@@ -336,7 +364,7 @@ module Puma
                 @idle_timeout_reached = true
 
                 if @clustered
-                  @worker_write << "i#{Process.pid}\n" rescue nil
+                  @worker_write << "#{PipeRequest::PIPE_IDLE}#{Process.pid}\n" rescue nil
                   next
                 else
                   @log_writer.log "- Idle timeout reached"
@@ -349,15 +377,25 @@ module Puma
 
             if @idle_timeout_reached && @clustered
               @idle_timeout_reached = false
-              @worker_write << "i#{Process.pid}\n" rescue nil
+              @worker_write << "#{PipeRequest::PIPE_IDLE}#{Process.pid}\n" rescue nil
             end
 
             ios.first.each do |sock|
               if sock == check
                 break if handle_check
               else
-                pool.wait_until_not_full
-                pool.wait_for_less_busy_worker(@options[:wait_for_less_busy_worker])
+                # if ThreadPool out_of_band code is running, we don't want to add
+                # clients until the code is finished.
+                pool.wait_while_out_of_band_running
+
+                # A well rested herd (cluster) runs faster
+                if @cluster_accept_loop_delay.on? && (busy_threads_plus_todo = pool.busy_threads) > 0
+                  delay = @cluster_accept_loop_delay.calculate(
+                    max_threads: @max_threads,
+                    busy_threads_plus_todo: busy_threads_plus_todo
+                  )
+                  sleep(delay)
+                end
 
                 io = begin
                   sock.accept_nonblock
@@ -365,11 +403,10 @@ module Puma
                   next
                 end
                 drain += 1 if shutting_down?
-                pool << Client.new(io, @binder.env(sock)).tap { |c|
-                  c.listener = sock
-                  c.http_content_length_limit = @http_content_length_limit
-                  c.send(addr_send_name, addr_value) if addr_value
-                }
+
+                client = new_client(io, sock)
+                client.send(addr_send_name, addr_value) if addr_value
+                pool << client
               end
             end
           rescue IOError, Errno::EBADF
@@ -380,7 +417,7 @@ module Puma
           end
         end
 
-        @log_writer.debug "Drained #{drain} additional connections." if drain
+        @log_writer.debug { "Drained #{drain} additional connections." } if drain
         @events.fire :state, @status
 
         if queue_requests
@@ -406,6 +443,16 @@ module Puma
       @events.fire :state, :done
     end
 
+    # :nodoc:
+    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
+
     # :nodoc:
     def handle_check
       cmd = @check.read(1)
@@ -428,25 +475,20 @@ 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[THREAD_LOCAL_KEY] = self
-
-      clean_thread_locals = @options[:clean_thread_locals]
+    def process_client(processor, client)
       close_socket = true
 
       requests = 0
 
       begin
-        if @queue_requests &&
-          !client.eagerly_finish
+        if @queue_requests && !client.eagerly_finish
 
           client.set_timeout(@first_data_timeout)
           if @reactor.add client
@@ -459,38 +501,40 @@ module Puma
           client.finish(@first_data_timeout)
         end
 
-        while true
+        can_loop = true
+        while can_loop
+          can_loop = false
           @requests_count += 1
-          case handle_request(client, requests + 1)
-          when false
-            break
+          case handle_request(processor, client, requests + 1)
+          when :close
           when :async
             close_socket = false
-            break
-          when true
-            ThreadPool.clean_thread_locals if clean_thread_locals
-
+          when :keep_alive
             requests += 1
 
-            # As an optimization, try to read the next request from the
-            # socket for a short time before returning to the reactor.
-            fast_check = @status == :run
-
-            # Always pass the client back to the reactor after a reasonable
-            # number of inline requests if there are other requests pending.
-            fast_check = false if requests >= @max_fast_inline &&
-              @thread_pool.backlog > 0
+            client.reset
 
-            next_request_ready = with_force_shutdown(client) do
-              client.reset(fast_check)
+            # 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
 
-            unless next_request_ready
-              break unless @queue_requests
+            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
-                break
               end
             end
           end
@@ -503,17 +547,21 @@ module Puma
       ensure
         client.io_buffer.reset
 
-        begin
-          client.close if close_socket
-        rescue IOError, SystemCallError
-          Puma::Util.purge_interrupt_queue
-          # Already closed
-        rescue StandardError => e
-          @log_writer.unknown_error e, nil, "Client"
-        end
+        close_client_safely(client) if close_socket
       end
     end
 
+    # :nodoc:
+    def close_client_safely(client)
+      client.close
+    rescue IOError, SystemCallError
+      # Already closed
+    rescue MiniSSL::SSLError => e
+      @log_writer.ssl_error e, client.io
+    rescue StandardError => e
+      @log_writer.unknown_error e, nil, "Client"
+    end
+
     # Triggers a client timeout if the thread-pool shuts down
     # during execution of the provided block.
     def with_force_shutdown(client, &block)
@@ -534,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)
@@ -548,7 +596,7 @@ module Puma
     # A fallback rack response if +@app+ raises as exception.
     #
     def lowlevel_error(e, env, status=500)
-      if handler = @options[:lowlevel_error_handler]
+      if handler = options[:lowlevel_error_handler]
         if handler.arity == 1
           return handler.call(e)
         elsif handler.arity == 2
@@ -567,59 +615,44 @@ 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)
-      client.write_error(status_code)
     end
     private :response_to_error
 
     # 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)
       @notify << message
     rescue IOError, NoMethodError, Errno::EPIPE, Errno::EBADF
       # The server, in another thread, is shutting down
-      Puma::Util.purge_interrupt_queue
     rescue RuntimeError => e
       # Temporary workaround for https://bugs.ruby-lang.org/issues/13239
       if e.message.include?('IOError')
-        Puma::Util.purge_interrupt_queue
+        # ignore
       else
         raise e
       end
     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)
@@ -643,13 +676,33 @@ module Puma
 
     # List of methods invoked by #stats.
     # @version 5.0.0
-    STAT_METHODS = [:backlog, :running, :pool_capacity, :max_threads, :requests_count].freeze
+    STAT_METHODS = [
+      :backlog,
+      :running,
+      :pool_capacity,
+      :busy_threads,
+      :backlog_max,
+      :max_threads,
+      :requests_count,
+      :reactor_max,
+    ].freeze
 
     # Returns a hash of stats about the running server for reporting purposes.
     # @version 5.0.0
     # @!attribute [r] stats
+    # @return [Hash] hash containing stat info from `Server` and `ThreadPool`
     def stats
-      STAT_METHODS.map {|name| [name, send(name) || 0]}.to_h
+      stats = @thread_pool&.stats || {}
+      stats[:max_threads]    = @max_threads
+      stats[:requests_count] = @requests_count
+      stats[:reactor_max] = @reactor.reactor_max if @reactor
+      reset_max
+      stats
+    end
+
+    def reset_max
+      @reactor.reactor_max = 0 if @reactor
+      @thread_pool&.reset_max
     end
 
     # below are 'delegations' to binder
@@ -669,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

@@ -17,7 +17,7 @@ module Puma
     def stats
       {
         started_at: utc_iso8601(@started_at)
-      }.merge(@server.stats).merge(super)
+      }.merge(@server&.stats || {}).merge(super)
     end
 
     def restart
@@ -49,13 +49,16 @@ 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"
+
+      warn_ruby_mn_threads
+
       redirect_io
 
-      @events.fire_on_booted!
+      @events.fire_after_booted!
 
       debug_loaded_extensions("Loaded Extensions:") if @log_writer.debug?
 

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