puma 7.1.0-java → 7.2.0-java

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c34ad6eb102937d5162b4ee769397333da4ad801d17fab6cc70226319ad94db2
-  data.tar.gz: 4c4fd1e10d19a1a156a8cd524bcf547e7b0c59cbac7868a21c3cd469ca60c96d
+  metadata.gz: 9a3dac630c4a0e901a7fc0fd84f9e9f9a4d26f97c7053a80295a420028c83990
+  data.tar.gz: 672c76739cd3502a72f9cc9f69a78b0d9c4e17287981dbe64390800f0685c625
 SHA512:
-  metadata.gz: 5f1f1026adb88d8bae2fb4008a94731b190af258c68270ab4f1c7578457f260612982d102c19b302b2f724b5e8bed7e774a6a3b8effd79d1ed23afa5349928cb
-  data.tar.gz: f01f2c0187729869c45940da06a5a496eaf404889baa0ee4cacbfb704a286b5d2f0852ffb0cf7671a2db8a5263850b83d4d381dc689f05ded5190c27b234afa8
+  metadata.gz: f5983d6b00d74e220658943eb2d4a08103af3d034cd3fd32f9693a1dfbbef34e4c11f857d200c120267aad3069a93e8b4ed8681c897db9e6fa46c782ee441871
+  data.tar.gz: 247d27471aa4c0957792c3a5c4609f3e2ef712db02a13c3bff158e5e90ad79ee660b0502b73ac49a307ad2f5b2f6975cbc1f033fbcade3df26e30f49fdc1aa42

data/History.md

@@ -1,3 +1,38 @@
+## 7.2.0 / 2026-01-20
+
+* Features
+  * Add workers `:auto` ([#3827])
+  * Make it possible to restrict control server commands to stats ([#3787])
+
+* Bugfixes
+  * Don't break if `WEB_CONCURRENCY` is set to a blank string ([#3837])
+  * Don't share server between worker 0 and descendants on refork ([#3602])
+  * Fix phase check race condition in `Puma::Cluster#check_workers` ([#3690])
+  * Fix advertising of CLI config before config files are loaded ([#3823])
+
+* Performance
+  * 17% faster HTTP parsing through pre-interning env keys ([#3825])
+  * Implement `dsize` and `dcompact` functions for `Puma::HttpParser`, which makes Puma's C-extension GC-compactible ([#3828])
+
+* Refactor
+  * Remove `NoMethodError` rescue in `Reactor#select_loop` ([#3831])
+  * Various cleanups in the C extension ([#3814])
+  * Monomorphize `handle_request` return ([#3802])
+
+* Docs
+  * Change link to `docs/deployment.md` in `README.md` ([#3848])
+  * Fix formatting for each signal description in signals.md ([#3813])
+  * Update deployment and Kubernetes docs with Puma configuration tips ([#3807])
+  * Rename master to main ([#3809], [#3808], [#3800])
+  * Fix some minor typos in the docs ([#3804])
+  * Add `GOVERNANCE.md`, `MAINTAINERS` ([#3826])
+  * Remove Code Climate badge ([#3820])
+  * Add @joshuay03 to the maintainer list
+
+* CI
+  * Use Minitest 6 where applicable ([#3859])
+  * Many test suite improvements and flake fixes ([#3861], [#3863], [#3860], [#3852], [#3857], [#3856], [#3845], [#3843], [#3842], [#3841], [#3822], [#3817], [#3764])
+
 ## 7.1.0 / 2025-10-16
 
 * Features
@@ -2259,6 +2294,42 @@ 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)
 
+[#3863]:https://github.com/puma/puma/pull/3863     "PR by Nate Berkopec, merged 2026-01-20"
+[#3861]:https://github.com/puma/puma/pull/3861     "PR by MSP-Greg, merged 2026-01-20"
+[#3860]:https://github.com/puma/puma/pull/3860     "PR by MSP-Greg, merged 2026-01-16"
+[#3859]:https://github.com/puma/puma/pull/3859     "PR by MSP-Greg, merged 2026-01-16"
+[#3857]:https://github.com/puma/puma/pull/3857     "PR by Aaron Patterson, merged 2026-01-12"
+[#3856]:https://github.com/puma/puma/pull/3856     "PR by MSP-Greg, merged 2026-01-12"
+[#3852]:https://github.com/puma/puma/pull/3852     "PR by Miłosz Bieniek, merged 2026-01-14"
+[#3848]:https://github.com/puma/puma/pull/3848     "PR by Miłosz Bieniek, merged 2025-12-27"
+[#3845]:https://github.com/puma/puma/pull/3845     "PR by MSP-Greg, merged 2025-12-19"
+[#3843]:https://github.com/puma/puma/pull/3843     "PR by MSP-Greg, merged 2025-12-18"
+[#3842]:https://github.com/puma/puma/pull/3842     "PR by MSP-Greg, merged 2025-12-18"
+[#3841]:https://github.com/puma/puma/pull/3841     "PR by MSP-Greg, merged 2025-12-18"
+[#3837]:https://github.com/puma/puma/pull/3837     "PR by John Bachir, merged 2026-01-09"
+[#3833]:https://github.com/puma/puma/pull/3833     "PR by Patrik Ragnarsson, merged 2025-11-25"
+[#3831]:https://github.com/puma/puma/pull/3831     "PR by Joshua Young, merged 2025-11-25"
+[#3828]:https://github.com/puma/puma/pull/3828     "PR by Jean Boussier, merged 2025-11-21"
+[#3827]:https://github.com/puma/puma/pull/3827     "PR by Nate Berkopec, merged 2026-01-20"
+[#3826]:https://github.com/puma/puma/pull/3826     "PR by Nate Berkopec, merged 2026-01-20"
+[#3825]:https://github.com/puma/puma/pull/3825     "PR by Jean Boussier, merged 2025-11-19"
+[#3823]:https://github.com/puma/puma/pull/3823     "PR by Joshua Young, merged 2025-11-18"
+[#3822]:https://github.com/puma/puma/pull/3822     "PR by Nate Berkopec, merged 2025-11-17"
+[#3820]:https://github.com/puma/puma/pull/3820     "PR by Nate Berkopec, merged 2025-11-19"
+[#3817]:https://github.com/puma/puma/pull/3817     "PR by Nate Berkopec, merged 2025-11-17"
+[#3814]:https://github.com/puma/puma/pull/3814     "PR by Jean Boussier, merged 2025-11-17"
+[#3813]:https://github.com/puma/puma/pull/3813     "PR by Masafumi Koba, merged 2025-11-17"
+[#3809]:https://github.com/puma/puma/pull/3809     "PR by Patrik Ragnarsson, merged 2025-10-26"
+[#3808]:https://github.com/puma/puma/pull/3808     "PR by Nymuxyzo, merged 2025-10-26"
+[#3807]:https://github.com/puma/puma/pull/3807     "PR by Nate Berkopec, merged 2025-10-28"
+[#3804]:https://github.com/puma/puma/pull/3804     "PR by Joe Rafaniello, merged 2025-10-21"
+[#3802]:https://github.com/puma/puma/pull/3802     "PR by Richard Schneeman, merged 2025-10-20"
+[#3800]:https://github.com/puma/puma/pull/3800     "PR by MSP-Greg, merged 2025-10-19"
+[#3787]:https://github.com/puma/puma/pull/3787     "PR by Stan Hu, merged 2025-10-17"
+[#3764]:https://github.com/puma/puma/pull/3764     "PR by MSP-Greg, merged 2025-10-17"
+[#3690]:https://github.com/puma/puma/pull/3690     "PR by Joshua Young, merged 2025-11-18"
+[#3602]:https://github.com/puma/puma/pull/3602     "PR by Joshua Young, merged 2025-11-28"
+
 [#3707]:https://github.com/puma/puma/pull/3707     "PR by @nerdrew, merged 2025-10-02"
 [#3794]:https://github.com/puma/puma/pull/3794     "PR by @schneems, merged 2025-10-16"
 [#3795]:https://github.com/puma/puma/pull/3795     "PR by @MSP-Greg, merged 2025-10-16"

data/README.md

@@ -4,8 +4,7 @@
 
 # Puma: A Ruby Web Server Built For Parallelism
 
-[![Actions](https://github.com/puma/puma/actions/workflows/tests.yml/badge.svg?branch=master)](https://github.com/puma/puma/actions/workflows/tests.yml?query=branch%3Amaster)
-[![Code Climate](https://codeclimate.com/github/puma/puma.svg)](https://codeclimate.com/github/puma/puma)
+[![Actions](https://github.com/puma/puma/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/puma/puma/actions/workflows/tests.yml?query=branch%3Amain)
 [![StackOverflow](https://img.shields.io/badge/stackoverflow-Puma-blue.svg)]( https://stackoverflow.com/questions/tagged/puma )
 
 Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server for Ruby/Rack applications**.
@@ -82,10 +81,10 @@ $ bundle exec puma
 
 ## Configuration
 
-Puma provides numerous options. Consult `puma -h` (or `puma --help`) for a full list of CLI options, or see `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb).
+Puma provides numerous options. Consult `puma -h` (or `puma --help`) for a full list of CLI options, or see `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/main/lib/puma/dsl.rb).
 
 You can also find several configuration examples as part of the
-[test](https://github.com/puma/puma/tree/master/test/config) suite.
+[test](https://github.com/puma/puma/tree/main/test/config) suite.
 
 For debugging purposes, you can set the environment variable `PUMA_LOG_CONFIG` with a value
 and the loaded configuration will be printed as part of the boot process.
@@ -116,11 +115,20 @@ Or with the `WEB_CONCURRENCY` environment variable:
 $ WEB_CONCURRENCY=3 puma -t 8:32
 ```
 
+When using a config file, most applications can simply set `workers :auto` (requires the `concurrent-ruby` gem) to match the number of worker processes to the available processors:
+
+```ruby
+# config/puma.rb
+workers :auto
+```
+
+See [`workers :auto` gotchas](lib/puma/dsl.rb).
+
 Note that threads are still used in cluster mode, and the `-t` thread flag setting is per worker, so `-w 2 -t 16:16` will spawn 32 threads in total, with 16 in each worker process.
 
-If the `WEB_CONCURRENCY` environment variable is set to `"auto"` and the `concurrent-ruby` gem is available in your application, Puma will set the worker process count to the result of [available processors](https://ruby-concurrency.github.io/concurrent-ruby/master/Concurrent.html#available_processor_count-class_method).
+If `workers` is set to `:auto`, or the `WEB_CONCURRENCY` environment variable is set to `"auto"`, and the `concurrent-ruby` gem is available in your application, Puma will set the worker process count to the result of [available processors](https://msp-greg.github.io/concurrent-ruby/Concurrent.html#available_processor_count-class_method).
 
-For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](https://github.com/puma/puma/blob/9282a8efa5a0c48e39c60d22ca70051a25df9f55/docs/kubernetes.md#workers-per-pod-and-other-config-issues).
+For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](docs/deployment.md).
 
 In cluster mode, Puma can "preload" your application. This loads all the application code *prior* to forking. Preloading reduces total memory usage of your application via an operating system feature called [copy-on-write](https://en.wikipedia.org/wiki/Copy-on-write).
 
@@ -226,7 +234,7 @@ end
 ### Error handling
 
 If Puma encounters an error outside of the context of your application, it will respond with a 400/500 and a simple
-textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/master/lib/puma/server.rb)).
+textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/main/lib/puma/server.rb)).
 You can specify custom behavior for this scenario. For example, you can report the error to your third-party
 error-tracking service (in this example, [rollbar](https://rollbar.com)):
 
@@ -385,7 +393,7 @@ Puma has a built-in status and control app that can be used to query and control
 $ puma --control-url tcp://127.0.0.1:9293 --control-token foo
 ```
 
-Puma will start the control server on localhost port 9293. All requests to the control server will need to include control token (in this case, `token=foo`) as a query parameter. This allows for simple authentication. Check out `Puma::App::Status` or [status.rb](https://github.com/puma/puma/blob/master/lib/puma/app/status.rb) to see what the status app has available.
+Puma will start the control server on localhost port 9293. All requests to the control server will need to include control token (in this case, `token=foo`) as a query parameter. This allows for simple authentication. Check out `Puma::App::Status` or [status.rb](https://github.com/puma/puma/blob/main/lib/puma/app/status.rb) to see what the status app has available.
 
 You can also interact with the control server via `pumactl`. This command will restart Puma:
 
@@ -417,7 +425,7 @@ $ puma -C "-"
 
 The other side-effects of setting the environment are whether to show stack traces (in `development` or `test`), and setting RACK_ENV may potentially affect middleware looking for this value to change their behavior. The default puma RACK_ENV value is `development`. You can see all config default values in `Puma::Configuration#puma_default_options` or [configuration.rb](https://github.com/puma/puma/blob/61c6213fbab/lib/puma/configuration.rb#L182-L204).
 
-Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb) to see all available options.
+Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/main/lib/puma/dsl.rb) to see all available options.
 
 ## Restart
 

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/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,7 +2,7 @@
 
 ## 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
 
@@ -61,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.
 
@@ -69,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/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
 

data/docs/stats.md

@@ -70,7 +70,7 @@ When Puma runs in single mode, these stats are available at the top level. When
 
 ### 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