puma 6.4.3 → 8.0.2

data/docs/deployment.md

@@ -16,32 +16,34 @@ assume this is how you're using Puma.
 Initially, Puma was conceived as a thread-only web server, but support for
 processes was added in version 2.
 
+In general, use single mode only if:
+
+* You are using JRuby, TruffleRuby or another fully-multithreaded implementation of Ruby
+* You are using MRI but in an environment where only 1 CPU core is available.
+
+Otherwise, you'll want to use cluster mode to utilize all available CPU resources.
+
 To run `puma` in single mode (i.e., as a development environment), set the
 number of workers to 0; anything higher will run in cluster mode.
 
-Here are some tips for cluster mode:
+## Cluster Mode Tips
 
-### MRI
+For the purposes of Puma provisioning, "CPU cores" means:
 
-* Use cluster mode and set the number of workers to 1.5x the number of CPU cores
-  in the machine, starting from a minimum of 2.
-* Set the number of threads to desired concurrent requests/number of workers.
-  Puma defaults to 5, and that's a decent number.
+1. On ARM, the number of physical cores.
+2. On x86, the number of logical cores, hyperthreads, or vCPUs (these words all mean the same thing).
 
-#### Migrating from Unicorn
+Set your config with the following process:
 
-* If you're migrating from unicorn though, here are some settings to start with:
-  * Set workers to half the number of unicorn workers you're using
-  * Set threads to 2
-  * Enjoy 50% memory savings
-* As you grow more confident in the thread-safety of your app, you can tune the
-  workers down and the threads up.
+* Use cluster mode and set `workers :auto` (requires the `concurrent-ruby` gem) to match the number of CPU cores on the machine (minimum 2, otherwise use single mode!). If you can't add the gem, set the worker count manually to the available CPU cores.
+* Set the number of threads to desired concurrent requests/number of workers.
+  Puma defaults to 5, and that's a decent number.
 
-#### Ubuntu / Systemd (Systemctl) Installation
+For most deployments, adding `concurrent-ruby` and using `workers :auto` is the right starting point.
 
-See [systemd.md](systemd.md)
+See [`workers :auto` gotchas](../lib/puma/dsl.rb).
 
-#### Worker utilization
+## Worker utilization
 
 **How do you know if you've got enough (or too many workers)?**
 
@@ -50,14 +52,34 @@ a time. But since so many apps are waiting on IO from DBs, etc., they can
 utilize threads to use the process more efficiently.
 
 Generally, you never want processes that are pegged all the time. That can mean
-there is more work to do than the process can get through. On the other hand, if
-you have processes that sit around doing nothing, then they're just eating up
-resources.
+there is more work to do than the process can get through, and requests will end up with additional latency. On the other hand, if
+you have processes that sit around doing nothing, then you're wasting resources and money.
+
+In general, you are making a tradeoff between:
+
+1. CPU and memory utilization.
+2. Time spent queueing for a Puma worker to `accept` requests and additional latency caused by CPU contention.
+
+If latency is important to you, you will have to accept lower utilization, and vice versa.
 
-Watch your CPU utilization over time and aim for about 70% on average. 70%
-utilization means you've got capacity still but aren't starving threads.
+## Container/VPS sizing
 
-**Measuring utilization**
+You will have to make a decision about how "big" to make each pod/VPS/server/dyno.
+
+**TL:DR;**: 80% of Puma apps will end up deploying "pods" of 4 workers, 5 threads each, 4 vCPU and 8GB of RAM.
+
+For the rest of this discussion, we'll adopt the Kubernetes term of "pods".
+
+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:
+
+* **Increasing worker counts decreases latency, but means you scale in bigger "chunks"**. 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).
+* **Increasing thread counts will increase throughput, but also latency and memory use** 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% of wall clock time) will lead to additional request latency and additional memory usage.
+* **Increasing worker counts decreases memory per worker on average**. 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.
+* **Low worker counts (<4) have exceptionally poor throughput**. Don't run less than 4 processes per pod if you can. Low numbers of processes per pod will lead to high request queueing (see discussion above), which means you will have to run more pods and resources.
+* **CPU-core-to-worker ratios should be around 1**. If running Puma with `threads > 1`, allocate 1 CPU core (see definition above!) 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. Using `workers :auto` will size workers to this guidance on most platforms.
+* **Don't set memory limits unless necessary**. 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).
+
+**Measuring utilization and queue time**
 
 Using a timestamp header from an upstream proxy server (e.g., `nginx` or
 `haproxy`) makes it possible to indicate how long requests have been waiting for
@@ -75,7 +97,7 @@ a Puma thread to become available.
     * `env['puma.request_body_wait']` contains the number of milliseconds Puma
       spent waiting for the client to send the request body.
     * haproxy: `%Th` (TLS handshake time) and `%Ti` (idle time before request)
-      can can also be added as headers.
+      can also be added as headers.
 
 ## Should I daemonize?
 
@@ -100,3 +122,16 @@ or hell, even `monit`.
 You probably will want to deploy some new code at some point, and you'd like
 Puma to start running that new code. There are a few options for restarting
 Puma, described separately in our [restart documentation](restart.md).
+
+## Migrating from Unicorn
+
+* If you're migrating from unicorn though, here are some settings to start with:
+  * Set workers to half the number of unicorn workers you're using
+  * Set threads to 2
+  * Enjoy 50% memory savings
+* As you grow more confident in the thread-safety of your app, you can tune the
+  workers down and the threads up.
+
+## Ubuntu / Systemd (Systemctl) Installation
+
+See [systemd.md](systemd.md)

data/docs/fork_worker.md

@@ -22,10 +22,20 @@ The `fork_worker` option allows your application to be initialized only once for
 
    You can trigger a refork by sending the cluster the `SIGURG` signal or running the `pumactl refork` command at any time. A refork will also automatically trigger once, after a certain number of requests have been processed by worker 0 (default 1000). To configure the number of requests before the auto-refork, pass a positive integer argument to `fork_worker` (e.g., `fork_worker 1000`), or `0` to disable.
 
+### Usage Considerations
+
+- `fork_worker` introduces new `before_refork` and `after_refork` configuration hooks. Note the following:
+    - When initially forking the parent process to the worker 0 child, `before_fork` will trigger on the parent process and `before_worker_boot` will trigger on the worker 0 child as normal.
+    - When forking the worker 0 child to grandchild workers, `before_refork` and `after_refork` will trigger on the worker 0 child, and `before_worker_boot` will trigger on each grandchild worker.
+    - For clarity, `before_fork` does not trigger on worker 0, and `after_refork` does not trigger on the grandchild.
+- As a general migration guide:
+    - Copy any logic within your existing `before_fork` hook to the `before_refork` hook.
+    - Consider to copy logic from your `before_worker_boot` hook to the `after_refork` hook, if it is needed to reset the state of worker 0 after it forks.
+
 ### Limitations
 
 - This mode is still very experimental so there may be bugs or edge-cases, particularly around expected behavior of existing hooks. Please open a [bug report](https://github.com/puma/puma/issues/new?template=bug_report.md) if you encounter any issues.
 
 - In order to fork new workers cleanly, worker 0 shuts down its server and stops serving requests so there are no open file descriptors or other kinds of shared global state between processes, and to maximize copy-on-write efficiency across the newly-forked workers. This may temporarily reduce total capacity of the cluster during a phased restart / refork.
 
-  In a cluster with `n` workers, a normal phased restart stops and restarts workers one by one while the application is loaded in each process, so `n-1` workers are available serving requests during the restart. In a phased restart in fork-worker mode, the application is first loaded in worker 0 while `n-1` workers are available, then worker 0 remains stopped while the rest of the workers are reloaded one by one, leaving only `n-2` workers to be available for a brief period of time. Reloading the rest of the workers should be quick because the application is preloaded at that point, but there may be situations where it can take longer (slow clients, long-running application code, slow worker-fork hooks, etc).
+- In a cluster with `n` workers, a normal phased restart stops and restarts workers one by one while the application is loaded in each process, so `n-1` workers are available serving requests during the restart. In a phased restart in fork-worker mode, the application is first loaded in worker 0 while `n-1` workers are available, then worker 0 remains stopped while the rest of the workers are reloaded one by one, leaving only `n-2` workers to be available for a brief period of time. Reloading the rest of the workers should be quick because the application is preloaded at that point, but there may be situations where it can take longer (slow clients, long-running application code, slow worker-fork hooks, etc).

data/docs/grpc.md

@@ -0,0 +1,62 @@
+# Using gRPC with Puma in Clustered Mode
+
+This guide shows how to set up gRPC with Puma in a clustered environment using Puma's hooks to manage gRPC's lifecycle methods during forking.
+
+## The Problem
+
+In a clustered Puma setup, you might encounter the following error when using gRPC:
+
+```
+grpc cannot be used between calls to GRPC.prefork and GRPC.postfork_child or GRPC.postfork_parent
+```
+
+To work correctly, gRPC needs these methods called at specific points in the process lifecycle:
+- `GRPC.prefork`: Called before forking.
+- `GRPC.postfork_child`: Called in the child process after forking.
+- `GRPC.postfork_parent`: Called in the parent process after forking.
+
+Puma provides hooks such as `before_worker_fork`, `after_worker_fork`, and `before_worker_boot` to execute code during these lifecycle events. Understanding the behavior of these hooks is key to ensuring gRPC operates correctly in a clustered setup.
+
+## The Solution
+
+### Example Configuration
+
+This configuration integrates gRPC's lifecycle methods in a clustered Puma setup and works whether preloading is enabled or not.
+
+```ruby
+# config/puma.rb
+
+is_mac = RUBY_PLATFORM.include?("darwin")
+
+before_worker_fork do |index|
+  GRPC.prefork unless is_mac
+end
+
+after_worker_fork do |index|
+  GRPC.postfork_parent unless is_mac
+end
+
+before_worker_boot do
+  GRPC.postfork_child unless is_mac
+end
+```
+
+### Understanding the Lifecycle and Hooks
+
+Puma's hooks determine when to call gRPC's lifecycle methods. Each hook plays a specific role in managing the lifecycle during forking:
+
+- **`before_worker_fork`**:
+  - This hook runs before forking workers and is where you call `GRPC.prefork`.
+  - In preloading setups (default in Puma v7), it runs in the **master process** before workers are forked, as the application is preloaded in the master process.
+  - Without preloading, it still runs in the **master process** before forking workers, but the application is not preloaded.
+  - `GRPC.prefork` is called here to prepare GRPC for the forking process.
+
+- **`after_worker_fork`**:
+  - This hook always runs in the **master process** after a worker is forked, regardless of whether preloading is enabled.
+  - Call `GRPC.postfork_parent` here to finalize the master process's state after forking.
+
+- **`before_worker_boot`**:
+  - This hook always runs in the **worker process** after it is forked, regardless of whether preloading is enabled.
+  - Call `GRPC.postfork_child` here to finalize the worker's state.
+
+**Note**: On macOS, these methods are skipped because gRPC does not require them due to differences in how forking works.

data/docs/images/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="152.027" height="150.013" viewBox="0 0 114.02 112.51"><defs><clipPath id="a"><path d="M0 .012h63V62H0Zm0 0"/></clipPath><clipPath id="b"><path d="M31.156.004c17.11 0 30.98 13.871 30.98 30.98s-13.87 30.977-30.98 30.977C14.051 61.96.18 48.094.18 30.984S14.05.004 31.156.004m0 0" clip-rule="evenodd"/></clipPath><clipPath id="d"><path d="M52 .012h62V62H52Zm0 0"/></clipPath><clipPath id="e"><path d="M83.043.008c17.105 0 30.977 13.867 30.977 30.976 0 17.11-13.872 30.977-30.977 30.977-17.11 0-30.98-13.867-30.98-30.977S65.933.008 83.043.008m0 0" clip-rule="evenodd"/></clipPath><clipPath id="g"><path d="M52 .012h11V62H52Zm0 0"/></clipPath><clipPath id="h"><path d="M31.156.004c17.11 0 30.98 13.871 30.98 30.98s-13.87 30.977-30.98 30.977C14.051 61.96.18 48.094.18 30.984S14.05.004 31.156.004m0 0" clip-rule="evenodd"/></clipPath><clipPath id="i"><path d="M83.043.008c17.105 0 30.977 13.867 30.977 30.976 0 17.11-13.872 30.977-30.977 30.977-17.11 0-30.98-13.867-30.98-30.977S65.933.008 83.043.008m0 0" clip-rule="evenodd"/></clipPath><clipPath id="k"><path d="M0 50h62v62.512H0Zm0 0"/></clipPath><clipPath id="l"><path d="M30.977 50.555c17.109 0 30.976 13.87 30.976 30.98s-13.867 30.973-30.976 30.973C13.867 112.508 0 98.645 0 81.535s13.867-30.98 30.977-30.98m0 0" clip-rule="evenodd"/></clipPath><clipPath id="n"><path d="M0 50h62v12H0Zm0 0"/></clipPath><clipPath id="o"><path d="M31.156.004c17.11 0 30.98 13.871 30.98 30.98s-13.87 30.977-30.98 30.977C14.051 61.96.18 48.094.18 30.984S14.05.004 31.156.004m0 0" clip-rule="evenodd"/></clipPath><clipPath id="p"><path d="M30.977 50.555c17.109 0 30.976 13.87 30.976 30.98s-13.867 30.973-30.976 30.973C13.867 112.508 0 98.645 0 81.535s13.867-30.98 30.977-30.98m0 0" clip-rule="evenodd"/></clipPath><clipPath id="r"><path d="M51 50h63v62.512H51Zm0 0"/></clipPath><clipPath id="s"><path d="M82.86 50.555c17.109 0 30.98 13.87 30.98 30.98s-13.871 30.977-30.98 30.977c-17.106 0-30.977-13.867-30.977-30.977s13.87-30.98 30.976-30.98m0 0" clip-rule="evenodd"/></clipPath><clipPath id="u"><path d="M52 50h62v12H52Zm0 0"/></clipPath><clipPath id="v"><path d="M83.043.008c17.105 0 30.977 13.867 30.977 30.976 0 17.11-13.872 30.977-30.977 30.977-17.11 0-30.98-13.867-30.98-30.977S65.933.008 83.043.008m0 0" clip-rule="evenodd"/></clipPath><clipPath id="w"><path d="M82.86 50.555c17.109 0 30.98 13.87 30.98 30.98s-13.871 30.977-30.98 30.977c-17.106 0-30.977-13.867-30.977-30.977s13.87-30.98 30.976-30.98m0 0" clip-rule="evenodd"/></clipPath><clipPath id="y"><path d="M51 50h11v62.512H51Zm0 0"/></clipPath><clipPath id="z"><path d="M30.977 50.555c17.109 0 30.976 13.87 30.976 30.98s-13.867 30.973-30.976 30.973C13.867 112.508 0 98.645 0 81.535s13.867-30.98 30.977-30.98m0 0" clip-rule="evenodd"/></clipPath><clipPath id="A"><path d="M82.86 50.555c17.109 0 30.98 13.87 30.98 30.98s-13.871 30.977-30.98 30.977c-17.106 0-30.977-13.867-30.977-30.977s13.87-30.98 30.976-30.98m0 0" clip-rule="evenodd"/></clipPath><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABK0lEQVR4nO3SwQmEQAAEQfUhPg4xFDM0AnM0lIuiWFi6IhiaWb/9WWZ0H+/oCcs2esDMigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaH1On+jN0yr50LFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKC/0BiakDO9qS1OUAAAAASUVORK5CYII=" id="c" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABKElEQVR4nO3dwQmAQBAEQc+3iLmYrCmZlUnYnEhVBEOz/x3Hvi1fcl737AmvWWcP+DNxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuaHztT8SfuNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUMPkcYCz6dHDDoAAAAASUVORK5CYII=" id="f" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABMElEQVR4nO3csQmEUBBAwfNiETO7sli7MrMEWzAZPuibApblsfFO6zL/Rli3nc6/zoPOf+I/eoE3Ky5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFplH/c7+gy4WKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXugG+KwQ7PgO2kwAAAABJRU5ErkJggg==" id="j" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABJ0lEQVR4nO3SsQmAQAAEQTUWEXPB/oszMTOyiuFBdio4lpv3bZ1iLKMH/FlxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouND/3MXoDcV7v6Ak9VyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRc6AM3AgQ7OdMblwAAAABJRU5ErkJggg==" id="m" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABM0lEQVR4nO3dsQnDQBBFQZ1waGSFasP9F+E2lKoDV+BIPA7MTAWfx+Y79u250FhnD/hn4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNzQ4/M6Zm+45X2dsyf85HJD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjc0PAnouNyQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNfQEBTgQ9BPCEIQAAAABJRU5ErkJggg==" id="q" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABJUlEQVR4nO3SsQmAQAAEQRVDEUvQzP4rNDd2eZCZCo7l5mPfJhrL6AF/Jm5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2towe8ndc9esJnPDckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3JC4IXFD4obEDYkbEjckbkjckLghcUPihsQNiRsSNyRuSNyQuCFxQ+KGxA2JGxI3JG5I3NADw1YBfSH2ahsAAAAASUVORK5CYII=" id="t" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABKElEQVR4nO3dMQqAQBAEQZULRQRz//9Mc2OLA+l6wdBsvut57EuMbfaAPysuVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhcbsAW/jumdP+EyXCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kJrfyKcLhcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXOgB/tcBcv0+qHgAAAAASUVORK5CYII=" id="x" width="116" height="116" x="0" y="0"/><image xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHQAAAB0CAIAAADb+IFwAAAABmJLR0QA/wD/AP+gvaeTAAABMklEQVR4nO3SwQmEUAxAwXXxpogdaP9VaRHet4W9DB/kTQFJeGTat/UT4zv6gDcrLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFheZRi89jofOv+6Hz/9HnQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi4UHGh4kLFhYoLFRcqLlRcqLhQcaHiQsWFigsVFyouVFyouFBxoeJCxYWKCxUXKi5UXKi40LRv6+gbXqvPhYoLFRf6AZBxBD0Rzoe7AAAAAElFTkSuQmCC" id="B" width="116" height="116" x="0" y="0"/></defs><g clip-path="url(#a)"><g clip-path="url(#b)"><use xlink:href="#c" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g><g clip-path="url(#d)"><g clip-path="url(#e)"><use xlink:href="#f" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g><g clip-path="url(#g)"><g clip-path="url(#h)"><g clip-path="url(#i)"><use xlink:href="#j" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g></g><g clip-path="url(#k)"><g clip-path="url(#l)"><use xlink:href="#m" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g><g clip-path="url(#n)"><g clip-path="url(#o)"><g clip-path="url(#p)"><use xlink:href="#q" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g></g><g clip-path="url(#r)"><g clip-path="url(#s)"><use xlink:href="#t" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g><g clip-path="url(#u)"><g clip-path="url(#v)"><g clip-path="url(#w)"><use xlink:href="#x" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g></g><g clip-path="url(#y)"><g clip-path="url(#z)"><g clip-path="url(#A)"><use xlink:href="#B" transform="translate(-.61 -1.1)scale(1.00103)"/></g></g></g></svg>

data/docs/images/running-puma.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="596.587" height="219.92" viewBox="0 0 447.44 164.94"><defs><clipPath id="a"><path d="M0 0h437v164.941H0Zm0 0"/></clipPath><clipPath id="b"><path d="M10 0h437.441v164.941H10Zm0 0"/></clipPath><clipPath id="c"><path d="M5 0h438v164.941H5Zm0 0"/></clipPath></defs><g clip-path="url(#a)"><path fill="#e0067f" d="M238.277 102.027c-1.859-1.246-7.484-1.246-13.086-1.906-5.601-.598-8.093-1.844-3.734-4.328 4.363-2.496 12.465-16.813 12.465-16.813 0 3.727 0 9.317 2.496 11.22 2.477 1.835 6.848 1.835 6.848 4.956s-3.121 8.094-4.989 6.871m189.965-55.46c-3.742-3.735-9.965-11.82-13.707-15.555-3.742-3.723-8.71-4.375-18.07-6.23-4.98-7.485-13.703-4.989-16.82 0-3.735 0-18.692 5.609-24.922 10.593-6.22 4.98-32.371 4.98-42.336 0-9.969-4.984-19.93-22.422-36.121-31.145-16.2-8.73-39.88-1.25-39.88-1.25-21.8-4.37-59.144 32.395-74.71 45.454-15.578 13.086-29.899 18.687-43.606 23.062-13.687 4.379-62.902 12.45-81.593 14.293-18.668 1.906-33.63 16.852-36.118 20.582-2.5 3.758 8.715 13.7 13.715 10.606 4.965-3.114 21.164-11.836 29.875-15.602 8.742-3.727 42.367-8.078 55.446-9.34 13.066-1.25 52.32-13.055 54.808-14.922 2.484-1.883 7.473-6.87 8.73 0 1.231 6.832 9.344 16.184 17.415 14.332 8.109-1.89 6.226 1.852 3.742 7.453-2.473 5.598 1.254 15.555 9.976 15.555s28.649 3.121 32.38 3.121c3.745 0 2.48 2.496-4.36 4.989-6.863 2.5-9.332 5.624-1.246 8.714 8.086 3.121 21.187 3.121 26.144-.617 4.996-3.75 3.75-10.59 6.262-14.332 2.461-3.73 4.969 4.988 1.848 10.582-3.114 5.637-6.227 14.973-11.828 14.973-5.61 0-18.7 5.594-23.676 8.094-4.988 2.496-11.215 11.191-3.73 13.699 7.464 2.476 12.452 1.254 16.816-3.113 4.37-4.364 15.562-1.875 24.277-5.61 8.738-3.758 11.871-9.957 12.465-13.07.629-3.145 4.348-3.145 4.348-3.742.648 6.254 3.75 3.742 11.214 8.113 7.477 4.348 17.457 3.723 22.418-1.258 4.989-4.988 0-7.465-6.203-9.348-6.234-1.886-11.855-3.73-16.84-6.238-4.964-2.5 3.13-4.984 9.364-6.23 6.207-1.243 26.148-3.723 30.492-8.727 4.402-4.973 19.344-16.805 25.566-19.902 13.051-4.352 21.16-9.356 30.504-15.57 9.336-6.243 17.43-5.004 20.559-4.368 3.105.617 13.07 6.219 17.437 6.219 4.348 0 11.22-2.473 11.82-8.707.63-6.227 3.762-9.352 6.231-13.086 2.492-3.742-4.36-8.723-8.086-12.473"/></g><g clip-path="url(#b)"><path fill="#f4f014" d="M248.86 102.027c-1.86-1.246-7.485-1.246-13.087-1.906-5.605-.598-8.093-1.844-3.734-4.328C236.402 93.297 244.5 78.98 244.5 78.98c0 3.727 0 9.317 2.5 11.22 2.473 1.835 6.848 1.835 6.848 4.956s-3.121 8.094-4.989 6.871m189.964-55.46c-3.742-3.735-9.969-11.82-13.71-15.555-3.743-3.723-8.708-4.375-18.067-6.23-4.98-7.485-13.703-4.989-16.82 0-3.739 0-18.692 5.609-24.922 10.593-6.22 4.98-32.371 4.98-42.34 0C313 30.391 303.039 12.953 286.848 4.23c-16.2-8.73-39.88-1.25-39.88-1.25-21.8-4.37-59.144 32.395-74.714 45.454-15.574 13.086-29.895 18.687-43.602 23.062-13.687 4.379-62.902 12.45-81.593 14.293-18.668 1.906-33.63 16.852-36.118 20.582-2.5 3.758 8.715 13.7 13.715 10.606 4.965-3.114 21.164-11.836 29.875-15.602 8.742-3.727 42.364-8.078 55.446-9.34 13.062-1.25 52.32-13.055 54.808-14.922 2.485-1.883 7.469-6.87 8.73 0 1.231 6.832 9.344 16.184 17.415 14.332 8.11-1.89 6.226 1.852 3.742 7.453-2.477 5.598 1.254 15.555 9.976 15.555s28.649 3.121 32.375 3.121c3.75 0 2.485 2.496-4.355 4.989-6.863 2.5-9.332 5.624-1.246 8.714 8.086 3.121 21.187 3.121 26.144-.617 4.997-3.75 3.75-10.59 6.262-14.332 2.461-3.73 4.965 4.988 1.848 10.582-3.113 5.637-6.227 14.973-11.828 14.973-5.61 0-18.7 5.594-23.68 8.094-4.984 2.496-11.211 11.191-3.727 13.699 7.465 2.476 12.454 1.254 16.817-3.113 4.37-4.364 15.562-1.875 24.277-5.61 8.738-3.758 11.871-9.957 12.465-13.07.629-3.145 4.348-3.145 4.348-3.742.648 6.254 3.75 3.742 11.214 8.113 7.477 4.348 17.458 3.723 22.418-1.258 4.985-4.988 0-7.465-6.203-9.348-6.234-1.886-11.859-3.73-16.84-6.238-4.964-2.5 3.13-4.984 9.36-6.23 6.21-1.243 26.152-3.723 30.496-8.727 4.402-4.973 19.344-16.805 25.566-19.902 13.051-4.352 21.157-9.356 30.504-15.57 9.336-6.243 17.43-5.004 20.559-4.368 3.105.617 13.07 6.219 17.433 6.219 4.352 0 11.223-2.473 11.825-8.707.629-6.227 3.761-9.352 6.23-13.086 2.492-3.742-4.36-8.723-8.086-12.473"/></g><g clip-path="url(#c)"><path fill="#312f34" d="M244.07 102.027c-1.86-1.246-7.484-1.246-13.09-1.906-5.601-.598-8.09-1.844-3.734-4.328 4.367-2.496 12.465-16.813 12.465-16.813 0 3.727 0 9.317 2.5 11.22 2.473 1.835 6.844 1.835 6.844 4.956s-3.118 8.094-4.985 6.871m189.965-55.46c-3.742-3.735-9.969-11.82-13.71-15.555-3.743-3.723-8.708-4.375-18.067-6.23-4.98-7.485-13.703-4.989-16.824 0-3.735 0-18.688 5.609-24.922 10.593-6.215 4.98-32.367 4.98-42.336 0-9.969-4.984-19.926-22.422-36.121-31.145-16.2-8.73-39.875-1.25-39.875-1.25-21.801-4.37-59.145 32.395-74.715 45.454-15.578 13.086-29.895 18.687-43.606 23.062-13.687 4.379-62.902 12.45-81.59 14.293-18.667 1.906-33.628 16.852-36.12 20.582-2.497 3.758 8.714 13.7 13.718 10.606 4.965-3.114 21.164-11.836 29.871-15.602 8.746-3.727 42.367-8.078 55.45-9.34 13.062-1.25 52.316-13.055 54.808-14.922 2.48-1.883 7.469-6.87 8.727 0 1.234 6.832 9.347 16.184 17.418 14.332 8.105-1.89 6.222 1.852 3.742 7.453-2.477 5.598 1.254 15.555 9.972 15.555 8.723 0 28.653 3.121 32.38 3.121 3.75 0 2.484 2.496-4.36 4.989-6.86 2.5-9.328 5.624-1.242 8.714 8.086 3.121 21.183 3.121 26.144-.617 4.996-3.75 3.75-10.59 6.262-14.332 2.461-3.73 4.965 4.988 1.844 10.582-3.11 5.637-6.223 14.973-11.828 14.973-5.61 0-18.696 5.594-23.676 8.094-4.988 2.496-11.211 11.191-3.727 13.699 7.461 2.476 12.45 1.254 16.813-3.113 4.375-4.364 15.562-1.875 24.277-5.61 8.738-3.758 11.875-9.957 12.465-13.07.633-3.145 4.352-3.145 4.352-3.742.644 6.254 3.75 3.742 11.21 8.113 7.481 4.348 17.461 3.723 22.418-1.258 4.989-4.988 0-7.465-6.203-9.348-6.23-1.886-11.855-3.73-16.836-6.238-4.964-2.5 3.13-4.984 9.36-6.23 6.21-1.243 26.152-3.723 30.496-8.727 4.402-4.973 19.34-16.805 25.566-19.902 13.051-4.352 21.157-9.356 30.5-15.57 9.34-6.243 17.434-5.004 20.559-4.368 3.105.617 13.074 6.219 17.437 6.219 4.352 0 11.22-2.473 11.82-8.707.63-6.227 3.766-9.352 6.235-13.086 2.488-3.742-4.36-8.723-8.086-12.473"/></g></svg>

data/docs/images/standard-logo.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="557.027" height="158.88" viewBox="0 0 417.77 119.16"><defs><clipPath id="a"><path d="M0 0h110v119.16H0Zm0 0"/></clipPath><clipPath id="b"><path d="M109 0h100v119.16H109Zm0 0"/></clipPath><clipPath id="c"><path d="M208 0h101v119.16H208Zm0 0"/></clipPath><clipPath id="d"><path d="M308 0h109.77v119.16H308Zm0 0"/></clipPath></defs><g clip-path="url(#a)"><path fill="#e0067f" d="M59.582 119.16C26.676 119.16 0 92.484 0 59.578S26.676 0 59.582 0c20.86 0 39.215 10.719 49.86 26.953-6.145 9.371-9.72 20.582-9.72 32.625 0 12.047 3.575 23.258 9.72 32.629-10.645 16.234-29 26.953-49.86 26.953"/></g><path fill="#fff" d="M67.008 55.258c0-2.574-2.07-4.031-4.649-4.031h-7.613v8.007h7.613c2.578 0 4.649-1.453 4.649-3.976M45.113 80.18V42.828h18.703c8.399 0 12.993 5.656 12.993 12.43 0 6.722-4.594 12.379-12.993 12.379h-9.07V80.18z"/><g clip-path="url(#b)"><path fill="#43a6d6" d="M159.3 119.16c-20.859 0-39.214-10.719-49.859-26.953 6.145-9.371 9.72-20.582 9.72-32.629 0-12.043-3.575-23.254-9.72-32.625C120.086 10.72 138.441 0 159.301 0c20.742 0 39.008 10.594 49.676 26.672-6.258 9.426-9.907 20.742-9.907 32.906 0 12.168 3.649 23.48 9.907 32.91-10.668 16.075-28.934 26.672-49.676 26.672"/></g><path fill="#21255a" d="M109.441 92.207c-6.144-9.371-9.718-20.582-9.718-32.629 0-12.043 3.574-23.254 9.718-32.625 6.145 9.371 9.72 20.582 9.72 32.625 0 12.047-3.575 23.258-9.72 32.629"/><path fill="#fff" d="M141.477 65.059v-22.23h9.8v21.894c0 4.425 2.688 7.617 7.895 7.617 5.152 0 7.84-3.192 7.84-7.617V42.828h9.746v22.176c0 9.297-5.602 15.848-17.586 15.848s-17.695-6.61-17.695-15.793"/><g clip-path="url(#c)"><path fill="#f4f014" d="M258.652 119.16c-20.742 0-39.004-10.597-49.675-26.672 6.257-9.43 9.906-20.742 9.906-32.91 0-12.164-3.649-23.48-9.906-32.906C219.648 10.594 237.91 0 258.652 0c20.801 0 39.114 10.656 49.77 26.809-6.203 9.402-9.813 20.664-9.813 32.77 0 12.105 3.61 23.37 9.813 32.769-10.656 16.156-28.969 26.812-49.77 26.812"/></g><path fill="#2da140" d="M208.977 92.488c-6.258-9.43-9.907-20.742-9.907-32.91 0-12.164 3.649-23.48 9.907-32.906 6.257 9.426 9.906 20.742 9.906 32.906 0 12.168-3.649 23.48-9.906 32.91"/><path fill="#fff" d="M270.215 80.18V55.484l-9.406 24.696h-4.254l-9.465-24.696V80.18h-9.633V42.828h13.383l7.84 20.606 7.785-20.606h13.383V80.18z"/><g clip-path="url(#d)"><path fill="#312f34" d="M358.188 119.16c-20.801 0-39.11-10.656-49.766-26.812 6.2-9.399 9.812-20.664 9.812-32.77 0-12.105-3.613-23.367-9.812-32.77C319.078 10.657 337.387 0 358.187 0c32.907 0 59.583 26.672 59.583 59.578s-26.676 59.582-59.582 59.582"/></g><path fill="#302d17" d="M308.422 92.348c-6.203-9.399-9.813-20.664-9.813-32.77 0-12.105 3.61-23.367 9.813-32.77 6.2 9.403 9.812 20.665 9.812 32.77s-3.613 23.371-9.812 32.77"/><path fill="#fff" d="m358.215 52.348-4.758 14.054h9.465Zm9.187 27.832-1.851-5.375h-14.727l-1.847 5.375h-10.922l14.058-37.352h12.153L378.32 80.18z"/></svg>

data/docs/java_options.md

@@ -0,0 +1,54 @@
+# Java Options
+
+`System Properties` or `Environment Variables` can be used to change Puma's
+default configuration for its Java extension. The provided values are evaluated
+during initialization, and changes while running the app have no effect.
+Moreover, default values may be used in case of invalid inputs.
+
+## Supported Options
+
+| ENV Name                     | Default Value |        Validation        |
+|------------------------------|:-------------:|:------------------------:|
+| PUMA_QUERY_STRING_MAX_LENGTH |   1024 * 10   | Positive natural number  |
+| PUMA_REQUEST_PATH_MAX_LENGTH |     8192      | Positive natural number  |
+| PUMA_REQUEST_URI_MAX_LENGTH  |   1024 * 12   | Positive natural number  |
+| PUMA_SKIP_SIGUSR2            |   nil         | n/a                      |
+
+## Examples
+
+### Invalid inputs
+
+An empty string will be handled as missing, and the default value will be used instead.
+Puma will print an error message for other invalid values.
+
+```
+foo@bar:~/puma$ PUMA_QUERY_STRING_MAX_LENGTH=abc PUMA_REQUEST_PATH_MAX_LENGTH='' PUMA_REQUEST_URI_MAX_LENGTH=0 bundle exec bin/puma test/rackup/hello.ru
+
+The value 0 for PUMA_REQUEST_URI_MAX_LENGTH is invalid. Using default value 12288 instead.
+The value abc for PUMA_QUERY_STRING_MAX_LENGTH is invalid. Using default value 10240 instead.
+Puma starting in single mode...
+```
+
+### Valid inputs
+
+```
+foo@bar:~/puma$ PUMA_REQUEST_PATH_MAX_LENGTH=9 bundle exec bin/puma test/rackup/hello.ru
+
+Puma starting in single mode...
+```
+```
+foo@bar:~ export path=/123456789 # 10 chars
+foo@bar:~ curl "http://localhost:9292${path}"
+
+Puma caught this error: HTTP element REQUEST_PATH is longer than the 9 allowed length. (Puma::HttpParserError)
+
+foo@bar:~ export path=/12345678 # 9 chars
+foo@bar:~ curl "http://localhost:9292${path}"
+Hello World
+```
+
+### Java Flight Recorder Compatibility
+
+Unfortunately Java Flight Recorder uses `SIGUSR2` internally. If you wish to 
+use JFR, turn off Puma's trapping of `SIGUSR2` by setting the environment variable
+`PUMA_SKIP_SIGUSR2` to any value.

data/docs/jungle/README.md

@@ -2,7 +2,7 @@
 
 ## Systemd
 
-See [/docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md).
+See [/docs/systemd](https://github.com/puma/puma/blob/main/docs/systemd.md).
 
 ## rc.d
 

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`
@@ -36,3 +36,7 @@ object that is useful for additional configuration.
 
 Public methods in [`Puma::Plugin`](../lib/puma/plugin.rb) are treated as a
 public API for plugins.
+
+## Binder hooks
+
+There's `Puma::Binder#before_parse` method that allows to add proc to run before the body of `Puma::Binder#parse`. Example of usage can be found in [that repository](https://github.com/anchordotdev/puma-acme/blob/v0.1.3/lib/puma/acme/plugin.rb#L97-L118) (`before_parse_hook` could be renamed `before_parse`, making monkey patching of [binder.rb](https://github.com/anchordotdev/puma-acme/blob/v0.1.3/lib/puma/acme/binder.rb) is unnecessary).

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

@@ -17,13 +17,13 @@ $ ps aux | grep tail
 schneems        87152   0.0  0.0  2432772    492 s032  S+   12:46PM   0:00.00 tail -f my.log
 ```
 
-You can send a signal in Ruby using the [Process module](https://www.ruby-doc.org/core-2.1.1/Process.html#kill-method):
+You can send a signal in Ruby using the [Process module](https://docs.ruby-lang.org/en/master/Process.html#method-c-kill):
 
 ```
 $ irb
 > puts pid
 => 87152
-Process.detach(pid) # https://ruby-doc.org/core-2.1.1/Process.html#method-c-detach
+Process.detach(pid) # https://docs.ruby-lang.org/en/master/Process.html#method-c-detach
 Process.kill("TERM", pid)
 ```
 
@@ -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` (or `PWR` for systems without `INFO`) print backtraces of all puma threads (if supported on your platform).
 
 ## 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

@@ -55,16 +55,22 @@ end
 
 When Puma runs in single mode, these stats are available at the top level. When Puma runs in cluster mode, these stats are available within the `worker_status` array in a hash labeled `last_status`, in an array of hashes where one hash represents each worker.
 
-* backlog: requests that are waiting for an available thread to be available. if this is above 0, you need more capacity [always true?]
-* running: how many threads are running
-* pool_capacity: the number of requests that the server is capable of taking right now. For example, if the number is 5, then it means there are 5 threads sitting idle ready to take a request. If one request comes in, then the value would be 4 until it finishes processing. If the minimum threads allowed is zero, this number will still have a maximum value of the maximum threads allowed.
+* backlog: requests that are waiting for an available thread to be available. if this is frequently above 0, you need more capacity.
+* running: how many threads are spawned. A spawned thread may be busy processing a request or waiting for a new request. If `min_threads` and `max_threads` are set to the same number,
+  this will be a never-changing number (other than rare cases when a thread dies, etc).
+* busy_threads: `running` - `how many threads are waiting to receive work` + `how many requests are waiting for a thread to pick them up`.
+  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_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

@@ -72,7 +72,7 @@ systemd and Puma also support socket activation, where systemd opens the
 listening socket(s) in advance and provides them to the Puma master process on
 startup. Among other advantages, this keeps listening sockets open across puma
 restarts and achieves graceful restarts, including when upgraded Puma, and is
-compatible with both clustered mode and application preload.
+compatible with both cluster mode and application preload.
 
 **Note:** Any wrapper scripts which `exec`, or other indirections in `ExecStart`
 may result in activated socket file descriptors being closed before reaching the
@@ -99,9 +99,11 @@ ListenStream=0.0.0.0:9293
 # ListenStream=/run/puma.sock
 
 # Socket options matching Puma defaults
-NoDelay=true
 ReusePort=true
 Backlog=1024
+# Enable this if you're using Puma with the "low_latency" option, read more in Puma DSL docs and systemd docs:
+# https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html#NoDelay=
+# NoDelay=true
 
 [Install]
 WantedBy=sockets.target
@@ -117,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
@@ -137,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
 
@@ -239,6 +241,13 @@ cap $stage puma:start --dry-run
 cap $stage puma:stop  --dry-run
 ~~~~
 
+### Disabling Puma Systemd Integration
+
+If you would like to disable Puma's systemd integration, for example if you handle it elsewhere
+in your code yourself, simply set the the environment variable `PUMA_SKIP_SYSTEMD` to any value.
+
+
+
 [Restart]: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=
 [#1367]: https://github.com/puma/puma/issues/1367
 [#1499]: https://github.com/puma/puma/issues/1499