puma 6.6.1 → 7.2.0

data/docs/kubernetes.md

@@ -2,16 +2,17 @@
 
 ## Running Puma in Kubernetes
 
-In general running Puma in Kubernetes works as-is, no special configuration is needed beyond what you would write anyway to get a new Kubernetes Deployment going. There is one known interaction between the way Kubernetes handles pod termination and how Puma handles `SIGINT`, where some request might be sent to Puma after it has already entered graceful shutdown mode and is no longer accepting requests. This can lead to dropped requests during rolling deploys. A workaround for this is listed at the end of this article.
+In general running Puma in Kubernetes works as-is, no special configuration is needed beyond what you would write anyway to get a new Kubernetes Deployment going. There is one known interaction between the way Kubernetes handles pod termination and how Puma handles `SIGINT`, where some requests might be sent to Puma after it has already entered graceful shutdown mode and is no longer accepting requests. This can lead to dropped requests during rolling deploys. A workaround for this is listed at the end of this article.
 
 ## Basic setup
 
 Assuming you already have a running cluster and docker image repository, you can run a simple Puma app with the following example Dockerfile and Deployment specification. These are meant as examples only and are deliberately very minimal to the point of skipping many options that are recommended for running in production, like healthchecks and envvar configuration with ConfigMaps. In general you should check the [Kubernetes documentation](https://kubernetes.io/docs/home/) and [Docker documentation](https://docs.docker.com/) for a more comprehensive overview of the available options.
 
-A basic Dockerfile example: 
-```
-FROM ruby:2.5.1-alpine # can be updated to newer ruby versions
-RUN apk update && apk add build-base # and any other packages you need 
+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
 
 # Only rebuild gem bundle if Gemfile changes
 COPY Gemfile Gemfile.lock ./
@@ -26,7 +27,8 @@ CMD bundle exec rackup -o 0.0.0.0
 ```
 
 A sample `deployment.yaml`:
-```
+
+```yaml
 ---
 apiVersion: apps/v1
 kind: Deployment
@@ -47,7 +49,7 @@ spec:
         image: <your image here>
         ports:
         - containerPort: 9292
-``` 
+```
 
 ## Graceful shutdown and pod termination
 
@@ -59,7 +61,7 @@ For some high-throughput systems, it is possible that some HTTP requests will re
 4. The pod has up to `terminationGracePeriodSeconds` (default: 30 seconds) to gracefully shut down. Puma will do this (after it receives SIGTERM) by closing down the socket that accepts new requests and finishing any requests already running before exiting the Puma process.
 5. If the pod is still running after `terminationGracePeriodSeconds` has elapsed, the pod receives `SIGKILL` to make sure the process inside it stops. After that, the container exits and all other Kubernetes objects associated with it are cleaned up.
 
-There is a subtle race condition between step 2 and 3: The replication controller does not synchronously remove the pod from the Services AND THEN call the pre-stop hook of the pod, but rather it asynchronously sends "remove this pod from your endpoints" requests to the Services and then immediately proceeds to invoke the pods' pre-stop hook. If the Service controller (typically something like nginx or haproxy) receives this request handles this request "too" late (due to internal lag or network latency between the replication and Service controllers) then it is possible that the Service controller will send one or more requests to a Puma process which has already shut down its listening socket. These requests will then fail with 5XX error codes.
+There is a subtle race condition between step 2 and 3: The replication controller does not synchronously remove the pod from the Services AND THEN call the pre-stop hook of the pod, but rather it asynchronously sends "remove this pod from your endpoints" requests to the Services and then immediately proceeds to invoke the pods' pre-stop hook. If the Service controller (typically something like nginx or haproxy) receives and handles this request "too" late (due to internal lag or network latency between the replication and Service controllers) then it is possible that the Service controller will send one or more requests to a Puma process which has already shut down its listening socket. These requests will then fail with 5XX error codes.
 
 The way Kubernetes works this way, rather than handling step 2 synchronously, is due to the CAP theorem: in a distributed system there is no way to guarantee that any message will arrive promptly. In particular, waiting for all Service controllers to report back might get stuck for an indefinite time if one of them has already been terminated or if there has been a net split. A way to work around this is to add a sleep to the pre-stop hook of the same time as the `terminationGracePeriodSeconds` time. This will allow the Puma process to keep serving new requests during the entire grace period, although it will no longer receive new requests after all Service controllers have propagated the removal of the pod from their endpoint lists. Then, after `terminationGracePeriodSeconds`, the pod receives `SIGKILL` and closes down. If your process can't handle SIGKILL properly, for example because it needs to release locks in different services, you can also sleep for a shorter period (and/or increase `terminationGracePeriodSeconds`) as long as the time slept is longer than the time that your Service controllers take to propagate the pod removal. The downside of this workaround is that all pods will take at minimum the amount of time slept to shut down and this will increase the time required for your rolling deploy.
 
@@ -67,12 +69,5 @@ More discussions and links to relevant articles can be found in https://github.c
 
 ## Workers Per Pod, and Other Config Issues
 
-With containerization, you will have to make a decision about how "big" to make each pod. Should you run 2 pods with 50 workers each? 25 pods, each with 4 workers? 100 pods, with each Puma running in single mode? Each scenario represents the same total amount of capacity (100 Puma processes that can respond to requests), but there are tradeoffs to make.
-
-* Worker counts should be somewhere between 4 and 32 in most cases. You want more than 4 in order to minimize time spent in request queueing for a free Puma worker, but probably less than ~32 because otherwise autoscaling is working in too large of an increment or they probably won't fit very well into your nodes. In any queueing system, queue time is proportional to 1/n, where n is the number of things pulling from the queue. Each pod will have its own request queue (i.e., the socket backlog). If you have 4 pods with 1 worker each (4 request queues), wait times are, proportionally, about 4 times higher than if you had 1 pod with 4 workers (1 request queue).
-* Unless you have a very I/O-heavy application (50%+ time spent waiting on IO), use the default thread count (5 for MRI). Using higher numbers of threads with low I/O wait (<50%) will lead to additional request queueing time (latency!) and additional memory usage.
-* More processes per pod reduces memory usage per process, because of copy-on-write memory and because the cost of the single master process is "amortized" over more child processes.
-* Don't run less than 4 processes per pod if you can. Low numbers of processes per pod will lead to high request queueing, which means you will have to run more pods.
-* If multithreaded, allocate 1 CPU per worker. If single threaded, allocate 0.75 cpus per worker. Most web applications spend about 25% of their time in I/O - but when you're running multi-threaded, your Puma process will have higher CPU usage and should be able to fully saturate a CPU core.
-* Most Puma processes will use about ~512MB-1GB per worker, and about 1GB for the master process. However, you probably shouldn't bother with setting memory limits lower than around 2GB per process, because most places you are deploying will have 2GB of RAM per CPU. A sensible memory limit for a Puma configuration of 4 child workers might be something like 8 GB (1 GB for the master, 7GB for the 4 children).
+See our [deployment docs](./deployment.md) for more information about how to correctly size your pods and choose the right number of workers and threads.
 

data/docs/plugins.md

@@ -5,13 +5,13 @@ operations.
 
 There are two canonical plugins to aid in the development of new plugins:
 
-* [tmp\_restart](https://github.com/puma/puma/blob/master/lib/puma/plugin/tmp_restart.rb):
+* [tmp\_restart](https://github.com/puma/puma/blob/main/lib/puma/plugin/tmp_restart.rb):
   Restarts the server if the file `tmp/restart.txt` is touched
 * [heroku](https://github.com/puma/puma-heroku/blob/master/lib/puma/plugin/heroku.rb):
   Packages up the default configuration used by Puma on Heroku (being sunset
   with the release of Puma 5.0)
 
-Plugins are activated in a Puma configuration file (such as `config/puma.rb'`)
+Plugins are activated in a Puma configuration file (such as `config/puma.rb`)
 by adding `plugin "name"`, such as `plugin "heroku"`.
 
 Plugins are activated based on path requirements so, activating the `heroku`

data/docs/restart.md

@@ -29,7 +29,7 @@ Any of the following will cause a Puma server to perform a hot restart:
 
 * The newly started Puma process changes its current working directory to the directory specified by the `directory` option. If `directory` is set to symlink, this is automatically re-evaluated, so this mechanism can be used to upgrade the application.
 * Only one version of the application is running at a time.
-* `on_restart` is invoked just before the server shuts down. This can be used to clean up resources (like long-lived database connections) gracefully. Since Ruby 2.0, it is not typically necessary to explicitly close file descriptors on restart. This is because any file descriptor opened by Ruby will have the `FD_CLOEXEC` flag set, meaning that file descriptors are closed on `exec`. `on_restart` is useful, though, if your application needs to perform any more graceful protocol-specific shutdown procedures before closing connections.
+* `before_restart` is invoked just before the server shuts down. This can be used to clean up resources (like long-lived database connections) gracefully. Since Ruby 2.0, it is not typically necessary to explicitly close file descriptors on restart. This is because any file descriptor opened by Ruby will have the `FD_CLOEXEC` flag set, meaning that file descriptors are closed on `exec`. `before_restart` is useful, though, if your application needs to perform any more graceful protocol-specific shutdown procedures before closing connections.
 
 ## Phased restart
 
@@ -59,7 +59,7 @@ Any of the following will cause a Puma server to perform a phased restart:
 
 * When a phased restart begins, the Puma master process changes its current working directory to the directory specified by the `directory` option. If `directory` is set to symlink, this is automatically re-evaluated, so this mechanism can be used to upgrade the application.
 * On a single server, it's possible that two versions of the application are running concurrently during a phased restart.
-* `on_restart` is not invoked
+* `before_restart` is not invoked
 * Phased restarts can be slow for Puma clusters with many workers. Hot restarts often complete more quickly, but at the cost of increased latency during the restart.
 * Phased restarts cannot be used to upgrade any gems loaded by the Puma master process, including `puma` itself, anything in `extra_runtime_dependencies`, or dependencies thereof. Upgrading other gems is safe.
 * If you remove the gems from old releases as part of your deployment strategy, there are additional considerations. Do not put any gems into `extra_runtime_dependencies` that have native extensions or have dependencies that have native extensions (one common example is `puma_worker_killer` and its dependency on `ffi`). Workers will fail on boot during a phased restart. The underlying issue is recorded in [an issue on the rubygems project](https://github.com/rubygems/rubygems/issues/4004). Hot restarts are your only option here if you need these dependencies.

data/docs/signals.md

@@ -33,16 +33,16 @@ Now you will see via `ps` that there is no more `tail` process. Sometimes when r
 
 Puma cluster responds to these signals:
 
-- `TTIN` increment the worker count by 1
-- `TTOU` decrement the worker count by 1
-- `TERM` send `TERM` to worker. The worker will attempt to finish then exit.
-- `USR2` restart workers. This also reloads the Puma configuration file, if there is one.
-- `USR1` restart workers in phases, a rolling restart. This will not reload the configuration file.
-- `HUP ` reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided, it will behave like `INT`
-- `INT ` equivalent of sending Ctrl-C to cluster. Puma will attempt to finish then exit.
-- `CHLD`
-- `URG ` refork workers in phases from worker 0 if `fork_workers` option is enabled.
-- `INFO` print backtraces of all puma threads
+- `TTIN`: Increment the worker count by 1.
+- `TTOU`: Decrement the worker count by 1.
+- `TERM`: Send `TERM` to worker. The worker will attempt to finish then exit.
+- `USR2`: Restart workers. This also reloads the Puma configuration file, if there is one.
+- `USR1`: Restart workers in phases, a rolling restart. This will not reload the configuration file.
+- `HUP`:  Reopen log files defined in `stdout_redirect` configuration parameter. If there is no `stdout_redirect` option provided, it will behave like `INT`.
+- `INT`:  Equivalent of sending Ctrl-C to cluster. Puma will attempt to finish then exit.
+- `CHLD`: Reap zombie child processes and wake event loop in `fork_worker` mode.
+- `URG`:  Refork workers in phases from worker 0 if `fork_worker` option is enabled.
+- `INFO`: Print backtraces of all Puma threads.
 
 ## Callbacks order in case of different signals
 
@@ -54,12 +54,12 @@ puma configuration file reloaded, if there is one
 puma configuration file reloaded, if there is one
 
 before_fork
-on_worker_fork
+before_worker_fork
 after_worker_fork
 
 Gemfile in context
 
-on_worker_boot
+before_worker_boot
 
 Code of the app is loaded and running
 ```
@@ -67,18 +67,18 @@ Code of the app is loaded and running
 ### Send USR2
 
 ```
-on_worker_shutdown
-on_restart
+before_worker_shutdown
+before_restart
 
 puma configuration file reloaded, if there is one
 
 before_fork
-on_worker_fork
+before_worker_fork
 after_worker_fork
 
 Gemfile in context
 
-on_worker_boot
+before_worker_boot
 
 Code of the app is loaded and running
 ```
@@ -86,13 +86,13 @@ Code of the app is loaded and running
 ### Send USR1
 
 ```
-on_worker_shutdown
-on_worker_fork
+before_worker_shutdown
+before_worker_fork
 after_worker_fork
 
 Gemfile in context
 
-on_worker_boot
+before_worker_boot
 
 Code of the app is loaded and running
 ```

data/docs/stats.md

@@ -62,14 +62,15 @@ 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.
+* backlog_max: the maximum number of requests that have been fully buffered by the reactor and placed in a ready queue, but have not yet been picked up by a server thread. This stat is reset on every call, so it's the maximum value observed since the last stat call.
 
 ### cluster mode
 
-* phase: which phase of restart the process is in, during [phased restart](https://github.com/puma/puma/blob/master/docs/restart.md)
+* phase: which phase of restart the process is in, during [phased restart](https://github.com/puma/puma/blob/main/docs/restart.md)
 * workers: ??
 * booted_workers: how many workers currently running?
 * old_workers: ??

data/docs/systemd.md

@@ -119,8 +119,8 @@ or cluster mode.
 ### Sockets and symlinks
 
 When using releases folders, you should set the socket path using the shared
-folder path (ex. `/srv/projet/shared/tmp/puma.sock`), not the release folder
-path (`/srv/projet/releases/1234/tmp/puma.sock`).
+folder path (ex. `/srv/project/shared/tmp/puma.sock`), not the release folder
+path (`/srv/project/releases/1234/tmp/puma.sock`).
 
 Puma will detect the release path socket as different than the one provided by
 systemd and attempt to bind it again, resulting in the exception `There is
@@ -139,7 +139,7 @@ automatically for any activated socket. When systemd socket activation is not
 enabled, this option does nothing.
 
 This also accepts an optional argument `only` (DSL: `'only'`) to discard any
-binds that's not socket activated.
+binds that are not socket activated.
 
 ## Usage
 

data/ext/puma_http11/extconf.rb

@@ -52,29 +52,14 @@ unless ENV["PUMA_DISABLE_SSL"]
     have_func "SSL_get1_peer_certificate"              , ssl_h
 
     puts ''
-
-    # Random.bytes available in Ruby 2.5 and later, Random::DEFAULT deprecated in 3.0
-    if Random.respond_to?(:bytes)
-      $defs.push "-DHAVE_RANDOM_BYTES"
-      puts "checking for Random.bytes... yes"
-    else
-      puts "checking for Random.bytes... no"
-    end
   end
 end
 
 if ENV["PUMA_MAKE_WARNINGS_INTO_ERRORS"]
   # Make all warnings into errors
   # Except `implicit-fallthrough` since most failures comes from ragel state machine generated code
-  if respond_to?(:append_cflags, true) # Ruby 2.5 and later
-    append_cflags(config_string('WERRORFLAG') || '-Werror')
-    append_cflags '-Wno-implicit-fallthrough'
-  else
-    # flag may not exist on some platforms, -Werror may not be defined on some platforms, but
-    # works with all in current CI
-    $CFLAGS << " #{config_string('WERRORFLAG') || '-Werror'}"
-    $CFLAGS << ' -Wno-implicit-fallthrough'
-  end
+  append_cflags(config_string('WERRORFLAG') || '-Werror')
+  append_cflags '-Wno-implicit-fallthrough'
 end
 
 create_makefile("puma/puma_http11")

data/ext/puma_http11/mini_ssl.c

@@ -471,13 +471,8 @@ sslctx_initialize(VALUE self, VALUE mini_ssl_ctx) {
     SSL_CTX_set_verify(ctx, NUM2INT(verify_mode), engine_verify_callback);
   }
 
-  // Random.bytes available in Ruby 2.5 and later, Random::DEFAULT deprecated in 3.0
   session_id_bytes = rb_funcall(
-#ifdef HAVE_RANDOM_BYTES
     rb_cRandom,
-#else
-    rb_const_get(rb_cRandom, rb_intern_const("DEFAULT")),
-#endif
     rb_intern_const("bytes"),
     1, ULL2NUM(SSL_MAX_SSL_SESSION_ID_LENGTH));
 
@@ -665,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);