puma 7.0.3-java → 7.1.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 57482800b8ce7fafc070a24927cb3348799099a2925ba3d541b078cbb02eaf66
-  data.tar.gz: 2eb44b3d0e0c1e81a9176bd2a04dd7f86e1e21b2c5765c74ca7b51cd25b1a71a
+  metadata.gz: c34ad6eb102937d5162b4ee769397333da4ad801d17fab6cc70226319ad94db2
+  data.tar.gz: 4c4fd1e10d19a1a156a8cd524bcf547e7b0c59cbac7868a21c3cd469ca60c96d
 SHA512:
-  metadata.gz: 60b359191f2c5fd22932e65b506ac1f02946d02cbaa6b905a97d96972abbc8f15b6bb151d6feca804a202c72683000871a3c3023c8b36b5cf545cb92a01fab74
-  data.tar.gz: b29236b5fcea83b4ec0ce75ca878da67466413d05e82b217dd1f5d5d16fe34b5e510c5f43b283ed816005c5b71a1451d0fcdc8581d455b4e5878ce85daabad7c
+  metadata.gz: 5f1f1026adb88d8bae2fb4008a94731b190af258c68270ab4f1c7578457f260612982d102c19b302b2f724b5e8bed7e774a6a3b8effd79d1ed23afa5349928cb
+  data.tar.gz: f01f2c0187729869c45940da06a5a496eaf404889baa0ee4cacbfb704a286b5d2f0852ffb0cf7671a2db8a5263850b83d4d381dc689f05ded5190c27b234afa8

data/History.md

@@ -1,3 +1,27 @@
+## 7.1.0 / 2025-10-16
+
+* Features
+  * Introduce `after_worker_shutdown` hook ([#3707])
+  * Reintroduce keepalive "fast inline" behavior. Provides faster (8x on JRuby & 1.4x on Ruby) pipeline processing  ([#3794])
+
+* Bugfixes
+  * Skip reading zero bytes when request body is buffered ([#3795])
+  * Fix `PUMA_LOG_CONFIG=1` logging twice with prune_bundler enabled ([#3778])
+  * Fix prune_bundler not showing in `PUMA_LOG_CONFIG=1` output ([#3779])
+  * Guard ThreadPool method call, which may be nil during shutdown ([#3791], [#3790])
+  * Set `Thread.current.puma_server` in Thread init code, not every request ([#3774])
+  * Fix race condition while deleting pidfile ([#3657])
+
+## 7.0.4 / 2025-09-23
+
+* Bugfixes
+  * Fix SSL_shutdown error handling ([#3703])
+  * Strip whitespace from the beginnings of request header values. ([#3742])
+
+* Performance
+  * puma_http11.c: Use interned UTF-8 strings for hash keys ([#3754])
+  * Move sleep cluster logic to its own class ([#3746], [#3740])
+
 ## 7.0.3 / 2025-09-13
 
 * Performance
@@ -26,7 +50,8 @@
   * Raise an ArgumentError if no block given to hooks ([#3377])
   * Don't set env['HTTP_VERSION'] for Rack > 3.1 ([#3711], [#3576])
   * Runner.rb - remove `ruby_engine` method, deprecated Nov-2024 ([#3701])
-  * Set conditional config defaults after CLI options are parsed and config files are loaded ([#3297])
+  * Config `preload_app!` is now the default for clustered mode ([#3297])
+  * Config instance must be `clamp`-d before reading any values ([#3297])
   * Response headers set to lowercase ([#3704])
   * Update minimum Ruby version to 3.0 ([#3698])
   * Rename callback hooks ([#3438])
@@ -2234,6 +2259,20 @@ be added back in a future date when a java Puma::MiniSSL is added.
 * Bugfixes
   * Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
 
+[#3707]:https://github.com/puma/puma/pull/3707     "PR by @nerdrew, merged 2025-10-02"
+[#3794]:https://github.com/puma/puma/pull/3794     "PR by @schneems, merged 2025-10-16"
+[#3795]:https://github.com/puma/puma/pull/3795     "PR by @MSP-Greg, merged 2025-10-16"
+[#3778]:https://github.com/puma/puma/pull/3778     "PR by @joshuay03, merged 2025-10-16"
+[#3779]:https://github.com/puma/puma/pull/3779     "PR by @joshuay03, merged 2025-10-16"
+[#3791]:https://github.com/puma/puma/pull/3791     "PR by @MSP-Greg, merged 2025-10-09"
+[#3790]:https://github.com/puma/puma/issues/3790   "Issue by @eric-wtfoxtrot, closed 2025-10-09"
+[#3774]:https://github.com/puma/puma/pull/3774     "PR by @MSP-Greg, merged 2025-10-16"
+[#3657]:https://github.com/puma/puma/pull/3657     "PR by @marksmith, merged 2025-10-16"
+[#3703]:https://github.com/puma/puma/pull/3703     "PR by @marshall-lee, merged 2025-09-20"
+[#3742]:https://github.com/puma/puma/pull/3742     "PR by @kenballus, merged 2025-09-18"
+[#3754]:https://github.com/puma/puma/pull/3754     "PR by @byroot, merged 2025-09-18"
+[#3746]:https://github.com/puma/puma/pull/3746     "PR by @schneems, merged 2025-09-18"
+[#3740]:https://github.com/puma/puma/issues/3740   "Issue by @joshuay03, closed 2025-09-18"
 [#3748]:https://github.com/puma/puma/pull/3748     "PR by @MSP-Greg, merged 2025-09-14"
 [#3749]:https://github.com/puma/puma/pull/3749     "PR by @schneems, merged 2025-09-14"
 [#3736]:https://github.com/puma/puma/pull/3736     "PR by @MSP-Greg, merged 2025-09-08"

data/README.md

@@ -142,8 +142,8 @@ Preloading can’t be used with phased restart, since phased restart kills and r
 
 #### Cluster mode hooks
 
-When using clustered mode, Puma's configuration DSL provides `before_fork` and `before_worker_boot`
-hooks to run code when the master process forks and child workers are booted respectively.
+When using clustered mode, Puma's configuration DSL provides `before_fork`, `before_worker_boot`, and `after_worker_shutdown`
+hooks to run code when the master process forks, the child workers are booted, and after each child worker exits respectively.
 
 It is recommended to use these hooks with `preload_app!`, otherwise constants loaded by your
 application (such as `Rails`) will not be available inside the hooks.
@@ -157,6 +157,11 @@ end
 before_worker_boot do
   # Add code to run inside the Puma worker process after forking.
 end
+
+after_worker_shutdown do |worker_handle|
+  # Add code to run inside the Puma master process after a worker exits. `worker.process_status` can be used to get the
+  # `Process::Status` of the exited worker.
+end
 ```
 
 In addition, there is an `before_refork` and `after_refork` hooks which are used only in [`fork_worker` mode](docs/fork_worker.md),

data/docs/kubernetes.md

@@ -10,7 +10,7 @@ Assuming you already have a running cluster and docker image repository, you can
 
 A basic Dockerfile example:
 
-```
+```Dockerfile
 FROM ruby:3.4.5-alpine # can be updated to newer ruby versions
 RUN apk update && apk add build-base # and any other packages you need
 
@@ -28,7 +28,7 @@ CMD bundle exec rackup -o 0.0.0.0
 
 A sample `deployment.yaml`:
 
-```
+```yaml
 ---
 apiVersion: apps/v1
 kind: Deployment

data/docs/stats.md

@@ -62,7 +62,7 @@ When Puma runs in single mode, these stats are available at the top level. When
   this is a "wholistic" stat reflecting the overall current state of work to be done and the capacity to do it.
 * pool_capacity: `how many threads are waiting to receive work` + `max_threads` - `running`. In a typical configuration where `min_threads`
   and `max_threads` are configured to the same number, this is simply `how many threads are waiting to receive work`. This number exists only as a stat
-  and is not used for any internal decisions, unlike `busy_theads`, which is usually a more useful stat.
+  and is not used for any internal decisions, unlike `busy_threads`, which is usually a more useful stat.
 * max_threads: the maximum number of threads Puma is configured to spool per worker
 * requests_count: the number of requests this worker has served since starting
 * reactor_max: the maximum observed number of requests held in Puma's "reactor" which is used for asyncronously buffering request bodies. This stat is reset on every call, so it's the maximum value observed since the last stat call.

data/ext/puma_http11/mini_ssl.c

@@ -660,14 +660,29 @@ VALUE engine_shutdown(VALUE self) {
 
   TypedData_Get_Struct(self, ms_conn, &engine_data_type, conn);
 
+  if (SSL_in_init(conn->ssl)) {
+    // Avoid "shutdown while in init" error
+    // See https://github.com/openssl/openssl/blob/openssl-3.5.2/ssl/ssl_lib.c#L2827-L2828
+    return Qtrue;
+  }
+
   ERR_clear_error();
 
   ok = SSL_shutdown(conn->ssl);
-  if (ok == 0) {
-    return Qfalse;
+  // See https://github.com/openssl/openssl/blob/openssl-3.5.2/ssl/ssl_lib.c#L2792-L2797
+  // for description of SSL_shutdown return values.
+  switch (ok) {
+    case 0:
+      // "close notify" alert is sent by us.
+      return Qfalse;
+    case 1:
+      // "close notify" alert was received from peer.
+      return Qtrue;
+    default:
+      raise_error(conn->ssl, ok);
   }
 
-  return Qtrue;
+  return Qnil;
 }
 
 VALUE engine_init(VALUE self) {

data/ext/puma_http11/org/jruby/puma/Http11.java

@@ -109,6 +109,10 @@ public class Http11 extends RubyObject {
         return (RubyClass)runtime.getModule("Puma").getConstant("HttpParserError");
     }
 
+    private static boolean is_ows(int c) {
+        return c == ' ' || c == '\t';
+    }
+
     public static void http_field(Ruby runtime, RubyHash req, ByteList buffer, int field, int flen, int value, int vlen) {
         RubyString f;
         IRubyObject v;
@@ -127,7 +131,11 @@ public class Http11 extends RubyObject {
             }
         }
 
-        while (vlen > 0 && Character.isWhitespace(buffer.get(value + vlen - 1))) vlen--;
+        while (vlen > 0 && is_ows(buffer.get(value + vlen - 1))) vlen--;
+        while (vlen > 0 && is_ows(buffer.get(value))) {
+            vlen--;
+            value++;
+        }
 
         if (b.equals(CONTENT_LENGTH_BYTELIST) || b.equals(CONTENT_TYPE_BYTELIST)) {
           f = RubyString.newString(runtime, b);

data/ext/puma_http11/puma_http11.c

@@ -7,6 +7,7 @@
 #define RSTRING_NOT_MODIFIED 1
 
 #include "ruby.h"
+#include "ruby/encoding.h"
 #include "ext_help.h"
 #include <assert.h>
 #include <string.h>
@@ -48,8 +49,11 @@ static VALUE global_request_path;
 #define VALIDATE_MAX_LENGTH(len, N) if(len > MAX_##N##_LENGTH) { rb_raise(eHttpParserError, MAX_##N##_LENGTH_ERR, len); }
 
 /** Defines global strings in the init method. */
-#define DEF_GLOBAL(N, val)   global_##N = rb_str_new2(val); rb_global_variable(&global_##N)
-
+static inline void DEF_GLOBAL(VALUE *var, const char *cstr)
+{
+    rb_global_variable(var);
+    *var = rb_enc_interned_str_cstr(cstr, rb_utf8_encoding());
+}
 
 /* Defines the maximum allowed lengths for various input elements.*/
 #ifndef PUMA_REQUEST_URI_MAX_LENGTH
@@ -134,13 +138,13 @@ static void init_common_fields(void)
   memcpy(tmp, HTTP_PREFIX, HTTP_PREFIX_LEN);
 
   for(i = 0; i < ARRAY_SIZE(common_http_fields); cf++, i++) {
+    rb_global_variable(&cf->value);
     if(cf->raw) {
       cf->value = rb_str_new(cf->name, cf->len);
     } else {
       memcpy(tmp + HTTP_PREFIX_LEN, cf->name, cf->len + 1);
       cf->value = rb_str_new(tmp, HTTP_PREFIX_LEN + cf->len);
     }
-    rb_global_variable(&cf->value);
   }
 }
 
@@ -155,6 +159,10 @@ static VALUE find_common_field_value(const char *field, size_t flen)
   return Qnil;
 }
 
+static int is_ows(const char c) {
+    return c == ' ' || c == '\t';
+}
+
 void http_field(puma_parser* hp, const char *field, size_t flen,
                                  const char *value, size_t vlen)
 {
@@ -181,7 +189,11 @@ void http_field(puma_parser* hp, const char *field, size_t flen,
     f = rb_str_new(hp->buf, new_size);
   }
 
-  while (vlen > 0 && isspace(value[vlen - 1])) vlen--;
+  while (vlen > 0 && is_ows(value[vlen - 1])) vlen--;
+  while (vlen > 0 && is_ows(value[0])) {
+      vlen--;
+      value++;
+  }
 
   /* check for duplicate header */
   v = rb_hash_aref(hp->request, f);
@@ -468,15 +480,15 @@ void Init_puma_http11(void)
   VALUE mPuma = rb_define_module("Puma");
   VALUE cHttpParser = rb_define_class_under(mPuma, "HttpParser", rb_cObject);
 
-  DEF_GLOBAL(request_method, "REQUEST_METHOD");
-  DEF_GLOBAL(request_uri, "REQUEST_URI");
-  DEF_GLOBAL(fragment, "FRAGMENT");
-  DEF_GLOBAL(query_string, "QUERY_STRING");
-  DEF_GLOBAL(server_protocol, "SERVER_PROTOCOL");
-  DEF_GLOBAL(request_path, "REQUEST_PATH");
+  DEF_GLOBAL(&global_request_method, "REQUEST_METHOD");
+  DEF_GLOBAL(&global_request_uri, "REQUEST_URI");
+  DEF_GLOBAL(&global_fragment, "FRAGMENT");
+  DEF_GLOBAL(&global_query_string, "QUERY_STRING");
+  DEF_GLOBAL(&global_server_protocol, "SERVER_PROTOCOL");
+  DEF_GLOBAL(&global_request_path, "REQUEST_PATH");
 
-  eHttpParserError = rb_define_class_under(mPuma, "HttpParserError", rb_eStandardError);
   rb_global_variable(&eHttpParserError);
+  eHttpParserError = rb_define_class_under(mPuma, "HttpParserError", rb_eStandardError);
 
   rb_define_alloc_func(cHttpParser, HttpParser_alloc);
   rb_define_method(cHttpParser, "initialize", HttpParser_init, 0);

data/lib/puma/client.rb

@@ -500,40 +500,36 @@ module Puma
       # after this
       remain = @body_remain
 
-      if remain > CHUNK_SIZE
-        want = CHUNK_SIZE
-      else
-        want = remain
-      end
+      # don't bother with reading zero bytes
+      unless remain.zero?
+        begin
+          chunk = @io.read_nonblock(remain.clamp(0, CHUNK_SIZE), @read_buffer)
+        rescue IO::WaitReadable
+          return false
+        rescue SystemCallError, IOError
+          raise ConnectionError, "Connection error detected during read"
+        end
 
-      begin
-        chunk = @io.read_nonblock(want, @read_buffer)
-      rescue IO::WaitReadable
-        return false
-      rescue SystemCallError, IOError
-        raise ConnectionError, "Connection error detected during read"
-      end
+        # No chunk means a closed socket
+        unless chunk
+          @body.close
+          @buffer = nil
+          set_ready
+          raise EOFError
+        end
 
-      # No chunk means a closed socket
-      unless chunk
-        @body.close
-        @buffer = nil
-        set_ready
-        raise EOFError
+        remain -= @body.write(chunk)
       end
 
-      remain -= @body.write(chunk)
-
       if remain <= 0
         @body.rewind
         @buffer = nil
         set_ready
-        return true
+        true
+      else
+        @body_remain = remain
+        false
       end
-
-      @body_remain = remain
-
-      false
     end
 
     def read_chunked_body

data/lib/puma/cluster/worker_handle.rb

@@ -28,10 +28,10 @@ module Puma
         @worker_max = Array.new WORKER_MAX_KEYS.length, 0
       end
 
-      attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status, :started_at
+      attr_reader :index, :pid, :phase, :signal, :last_checkin, :last_status, :started_at, :process_status
 
       # @version 5.0.0
-      attr_writer :pid, :phase
+      attr_writer :pid, :phase, :process_status
 
       def booted?
         @stage == :booted

data/lib/puma/cluster.rb

@@ -23,7 +23,7 @@ module Puma
       @next_check = Time.now
 
       @worker_max = [] # keeps track of 'max' stat values
-      @phased_restart = false
+      @pending_phased_restart = false
     end
 
     # Returns the list of cluster worker handles.
@@ -238,7 +238,7 @@ module Puma
     def phased_restart(refork = false)
       return false if @options[:preload_app] && !refork
 
-      @phased_restart = refork ? :refork : true
+      @pending_phased_restart = refork ? :refork : true
       wakeup!
 
       true
@@ -456,11 +456,11 @@ module Puma
               break
             end
 
-            if @phased_restart
-              start_phased_restart(@phased_restart == :refork)
+            if @pending_phased_restart
+              start_phased_restart(@pending_phased_restart == :refork)
 
-              in_phased_restart = @phased_restart
-              @phased_restart = false
+              in_phased_restart = @pending_phased_restart
+              @pending_phased_restart = false
 
               workers_not_booted = @options[:workers]
               # worker 0 is not restarted on refork
@@ -583,7 +583,9 @@ module Puma
           #    `Process.wait2(-1)` from detecting a terminated process: https://bugs.ruby-lang.org/issues/19837.
           # 2. When `fork_worker` is enabled, some worker may not be direct children,
           #    but grand children.  Because of this they won't be reaped by `Process.wait2(-1)`.
-          if reaped_children.delete(w.pid) || Process.wait(w.pid, Process::WNOHANG)
+          if (status = reaped_children.delete(w.pid) || Process.wait2(w.pid, Process::WNOHANG)&.last)
+            w.process_status = status
+            @config.run_hooks(:after_worker_shutdown, w, @log_writer)
             true
           else
             w.term if w.term?

data/lib/puma/cluster_accept_loop_delay.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Puma
+  # Calculate a delay value for sleeping when running in clustered mode
+  #
+  # The main reason this is a class is so it can be unit tested independently.
+  # This makes modification easier in the future if we can encode properties of the
+  # delay into a test instead of relying on end-to-end testing only.
+  #
+  # This is an imprecise mechanism to address specific goals:
+  #
+  # - Evenly distribute requests across all workers at start
+  # - Evenly distribute CPU resources across all workers
+  #
+  # ## Goal: Distribute requests across workers at start
+  #
+  # There was a perf bug in Puma where one worker would wake up slightly before the rest and accept
+  # all the requests on the socket even though it didn't have enough resources to process all of them.
+  # This was originally fixed by never calling accept when a worker had more requests than threads
+  # already https://github.com/puma/puma/pull/3678/files/2736ebddb3fc8528e5150b5913fba251c37a8bf7#diff-a95f46e7ce116caddc9b9a9aa81004246d5210d5da5f4df90a818c780630166bL251-L291
+  #
+  # With the introduction of true keepalive support, there are two ways a request can come in:
+  # - A new request from a new client comes into the socket and it must be "accept"-ed
+  # - A keepalive request is served and the connection is retained. Another request is then accepted
+  #
+  # Ideally the server handles requests in the order they come in, and ideally it doesn't accept more requests than it can handle.
+  # These goals are contradictory, because when the server is at maximum capacity due to keepalive connections, it could mean we
+  # block all new requests, even if those came in before the new request on the older keepalive connection.
+  #
+  # ## Goal: Distribute CPU resources across all workers
+  #
+  # - This issue was opened https://github.com/puma/puma/issues/2078
+  #
+  # There are several entangled issues and it's not exactly clear what the root cause is, but the observable outcome
+  # was that performance was better with a small sleep, and that eventually became the default.
+  #
+  # An attempt to describe why this works is here: https://github.com/puma/puma/issues/2078#issuecomment-3287032470.
+  #
+  # Summarizing: The delay is for tuning the rate at which "accept" is called on the socket.
+  # Puma works by calling "accept" nonblock on the socket in a loop. When there are multiple workers
+  # (processes), they will "race" to accept a request at roughly the same rate. However, if one
+  # worker has all threads busy processing requests, then accepting a new request might "steal" it from
+  # a less busy worker. If a worker has no work to do, it should loop as fast as possible.
+  #
+  # ## Solution: Distribute requests across workers at start
+  #
+  # For now, both goals are framed as "load balancing" across workers (processes) and achieved through
+  # the same mechanism of sleeping longer to delay busier workers. Rather than the prior Puma 6.x
+  # and earlier behavior of using a binary on/off sleep value, we increase it an amount proportional
+  # to the load the server is under, capping the maximum delay to the scenario where all threads are busy
+  # and the todo list has reached a multiplier of the maximum number of threads.
+  #
+  # Private: API may change unexpectedly
+  class ClusterAcceptLoopDelay
+    attr_reader :max_delay
+
+    # Initialize happens once, `call` happens often. Perform global calculations here.
+    def initialize(
+      # Number of workers in the cluster
+      workers: ,
+      # Maximum delay in seconds i.e. 0.005 is 5 milliseconds
+      max_delay:
+    )
+      @on = max_delay > 0 && workers >= 2
+      @max_delay = max_delay.to_f
+
+      # Reach maximum delay when `max_threads * overload_multiplier` is reached in the system
+      @overload_multiplier = 25.0
+    end
+
+    def on?
+      @on
+    end
+
+    # We want the extreme values of this delay to be known (minimum and maximum) as well as
+    # a predictable curve between the two. i.e. no step functions or hard cliffs.
+    #
+    # Return value is always numeric. Returns 0 if there should be no delay.
+    def calculate(
+      # Number of threads working right now, plus number of requests in the todo list
+      busy_threads_plus_todo:,
+      # Maximum number of threads in the pool, note that the busy threads (alone) may go over this value at times
+      # if the pool needs to be reaped. The busy thread plus todo count may go over this value by a large amount.
+      max_threads:
+    )
+      max_value = @overload_multiplier * max_threads
+      # Approaches max delay when `busy_threads_plus_todo` approaches `max_value`
+      return max_delay * busy_threads_plus_todo.clamp(0, max_value) / max_value
+    end
+  end
+end

data/lib/puma/configuration.rb

@@ -155,6 +155,7 @@ module Puma
       out_of_band: [],
       # Number of seconds for another request within a persistent session.
       persistent_timeout: 65, # PUMA_PERSISTENT_TIMEOUT
+      prune_bundler: false,
       queue_requests: true,
       rackup: 'config.ru'.freeze,
       raise_exception_on_sigterm: true,

data/lib/puma/const.rb

@@ -100,8 +100,8 @@ module Puma
   # too taxing on performance.
   module Const
 
-    PUMA_VERSION = VERSION = "7.0.3"
-    CODE_NAME = "Romantic Warrior"
+    PUMA_VERSION = VERSION = "7.1.0"
+    CODE_NAME = "Neon Witch"
 
     PUMA_SERVER_STRING = ["puma", PUMA_VERSION, CODE_NAME].join(" ").freeze
 

data/lib/puma/dsl.rb

@@ -656,7 +656,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
@@ -818,6 +819,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
@@ -1207,13 +1222,19 @@ module Puma
     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

data/lib/puma/launcher.rb

@@ -42,26 +42,39 @@ 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 for a potential early restart (e.g. when pruning bundle)
 
+      @config = conf
       @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?
 
+      @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
+
       # Advertise the Configuration
       Puma.cli_config = @config if defined?(Puma.cli_config)
       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 +94,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 +141,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 +386,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)

data/lib/puma/server.rb

@@ -13,14 +13,12 @@ require_relative 'binder'
 require_relative 'util'
 require_relative 'request'
 require_relative 'configuration'
+require_relative 'cluster_accept_loop_delay'
 
 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
@@ -58,7 +56,6 @@ module Puma
     attr_accessor :app
     attr_accessor :binder
 
-
     # Create a server for the rack app +app+.
     #
     # +log_writer+ is a Puma::LogWriter object used to log info and error messages.
@@ -110,6 +107,10 @@ module Puma
       @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)
@@ -245,11 +246,6 @@ module Puma
       @thread_pool&.pool_capacity
     end
 
-    # @!attribute [r] busy_threads
-    def busy_threads
-      @thread_pool&.busy_threads
-    end
-
     # Runs the server.
     #
     # If +background+ is true (the default) then a thread is spun
@@ -263,10 +259,14 @@ module Puma
 
       @status = :run
 
-      @thread_pool = ThreadPool.new(thread_name, options) { |client| process_client client }
+      @thread_pool = ThreadPool.new(thread_name, options, server: self) { |client| process_client client }
 
       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
 
@@ -291,6 +291,9 @@ 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
@@ -325,7 +328,7 @@ module Puma
       end
     rescue StandardError => e
       client_error(e, client)
-      client.close
+      close_client_safely(client)
       true
     end
 
@@ -339,7 +342,6 @@ module Puma
         pool = @thread_pool
         queue_requests = @queue_requests
         drain = options[:drain_on_shutdown] ? 0 : nil
-        max_flt = @max_threads.to_f
 
         addr_send_name, addr_value = case options[:remote_address]
         when :value
@@ -384,15 +386,13 @@ module Puma
                 # clients until the code is finished.
                 pool.wait_while_out_of_band_running
 
-                # only use delay when clustered and busy
-                if pool.busy_threads >= @max_threads
-                  if @clustered
-                    delay = 0.0001 * ((@reactor&.reactor_size || 0) + pool.busy_threads * 1.5)/max_flt
-                    sleep delay
-                  else
-                    # use small sleep for busy single worker
-                    sleep 0.0001
-                  end
+                # 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
@@ -401,11 +401,9 @@ 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
@@ -442,6 +440,14 @@ module Puma
       @events.fire :state, :done
     end
 
+    # :nodoc:
+    def new_client(io, sock)
+      client = Client.new(io, @binder.env(sock))
+      client.listener = sock
+      client.http_content_length_limit = @http_content_length_limit
+      client
+    end
+
     # :nodoc:
     def handle_check
       cmd = @check.read(1)
@@ -472,9 +478,6 @@ module Puma
     #
     # Return true if one or more requests were processed.
     def process_client(client)
-      # Advertise this server into the thread
-      Thread.current.puma_server = self
-
       close_socket = true
 
       requests = 0
@@ -493,31 +496,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(client, requests + 1)
+          when false
+          when :async
+            close_socket = false
+          when true
+            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
@@ -529,16 +542,21 @@ module Puma
       ensure
         client.io_buffer.reset
 
-        begin
-          client.close if close_socket
-        rescue IOError, SystemCallError
-          # 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)
@@ -692,7 +710,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

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

@@ -5,6 +5,10 @@ require 'thread'
 require_relative 'io_buffer'
 
 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.
@@ -33,7 +37,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
@@ -134,6 +140,9 @@ module Puma
       trigger_before_thread_start_hooks
       th = Thread.new(@spawned) do |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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: puma
 version: !ruby/object:Gem::Version
-  version: 7.0.3
+  version: 7.1.0
 platform: java
 authors:
 - Evan Phoenix
 bindir: bin
 cert_chain: []
-date: 2025-09-14 00:00:00.000000000 Z
+date: 2025-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   requirement: !ruby/object:Gem::Requirement
@@ -86,6 +86,7 @@ files:
 - lib/puma/cluster.rb
 - lib/puma/cluster/worker.rb
 - lib/puma/cluster/worker_handle.rb
+- lib/puma/cluster_accept_loop_delay.rb
 - lib/puma/commonlogger.rb
 - lib/puma/configuration.rb
 - lib/puma/const.rb
@@ -131,6 +132,7 @@ metadata:
   homepage_uri: https://puma.io
   source_code_uri: https://github.com/puma/puma
   rubygems_mfa_required: 'true'
+  msys2_mingw_dependencies: openssl
 rdoc_options: []
 require_paths:
 - lib