puma 7.0.3 → 7.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7a5fc93f89e02a2687f0266b0b9d4bd022ab373468b38fd93ab8c9d93fd3e60
-  data.tar.gz: 27d1faa8805df15e6f0cecea9469c21f99ac3ab971f817062b6f7f4a3f098160
+  metadata.gz: 13d2ebef5879f5ab45b75cadd20e4a72b643ff9f5e6af2cbcf69d655ec4475b8
+  data.tar.gz: 1ce847fac6f3e5f893814462b47792db32f1cb0960b9c8619d7ad26c4057bfec
 SHA512:
-  metadata.gz: df56ab248fda787f6f5a5d68d25a0888cf79aafc2a76302e48d35c684ac8d461519d728016fb7244a993969c08879d22819b73b96a92abef046119e0cbfae82e
-  data.tar.gz: a4aab29ff5d6b87f2c099800fad9a963c785777d9fc8e0f3df33ca51ae04835dfb27f282512294c48dd51e2c34f9b6083fc7e1dd2b42a5e8a99b625c6688b5ab
+  metadata.gz: e67841b0a72c35c6667745e0aad11b152dbd46dc952b51ec811100281f8d93e45bc70fd16861b848918790b2eb0b0b290fa493f82beb0e4ed818abdffcb2f9fc
+  data.tar.gz: cecf1704d003e0f0299811a6c16310bb79fd7ee5ff21ce991bb2b82430f2d31e348a65b4054e57656255af10ac62489e4c4df889367a6c0b967d540522717ea7

data/History.md

@@ -1,3 +1,13 @@
+## 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 +36,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 +2245,11 @@ 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)
 
+[#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/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/cluster_accept_loop_delay.rb

@@ -0,0 +1,92 @@
+# 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"-d
+  # - 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.
+  #
+  # ## 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 the root cause, 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) then 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(s): 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 amound 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_threads, :max_delay
+
+    # Initialize happens once, `call` happens often. Push global calculations here
+    def initialize(
+        # Number of workers in the cluster
+        workers: ,
+        # Maximum delay in seconds i.e. 0.005 is 5 microseconds
+        max_delay: # In seconds i.e. 0.005 is 5 microseconds
+
+      )
+      @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/const.rb

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

data/lib/puma/server.rb

@@ -13,6 +13,7 @@ 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
@@ -58,7 +59,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 +110,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 +249,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
@@ -266,7 +265,11 @@ module Puma
       @thread_pool = ThreadPool.new(thread_name, options) { |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 +294,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 +331,7 @@ module Puma
       end
     rescue StandardError => e
       client_error(e, client)
-      client.close
+      close_client_safely(client)
       true
     end
 
@@ -339,7 +345,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 +389,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 +404,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 +443,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)
@@ -529,16 +538,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)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puma
 version: !ruby/object:Gem::Version
-  version: 7.0.3
+  version: 7.0.4
 platform: ruby
 authors:
 - Evan Phoenix
@@ -87,6 +87,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