puma 6.4.3 → 8.0.2

data/README.md

@@ -1,18 +1,16 @@
 <p align="center">
-  <img src="https://puma.io/images/logos/puma-logo-large.png">
+  <img src="docs/images/standard-logo.svg" alt="Puma logo">
 </p>
 
 # Puma: A Ruby Web Server Built For Parallelism
 
-[![Actions](https://github.com/puma/puma/workflows/Tests/badge.svg?branch=master)](https://github.com/puma/puma/actions?query=workflow%3ATests)
-[![Code Climate](https://codeclimate.com/github/puma/puma.svg)](https://codeclimate.com/github/puma/puma)
-[![StackOverflow](https://img.shields.io/badge/stackoverflow-Puma-blue.svg)]( https://stackoverflow.com/questions/tagged/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)
 
 Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server for Ruby/Rack applications**.
 
 ## Built For Speed &amp; Parallelism
 
-Puma is a server for [Rack](https://github.com/rack/rack)-powered HTTP applications written in Ruby.  It is: 
+Puma is a server for [Rack](https://github.com/rack/rack)-powered HTTP applications written in Ruby.  It is:
 * **Multi-threaded**. Each request is served in a separate thread. This helps you serve more requests per second with less memory use.
 * **Multi-process**. "Pre-forks" in cluster mode, using less memory per-process thanks to copy-on-write memory.
 * **Standalone**. With SSL support, zero-downtime rolling restarts and a built-in request bufferer, you can deploy Puma without any reverse proxy.
@@ -82,10 +80,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.
@@ -102,9 +100,9 @@ Puma will automatically scale the number of threads, from the minimum until it c
 
 Be aware that additionally Puma creates threads on its own for internal purposes (e.g. handling slow clients). So, even if you specify -t 1:1, expect around 7 threads created in your application.
 
-### Clustered mode
+### Cluster mode
 
-Puma also offers "clustered mode". Clustered mode `fork`s workers from a master process. Each child process still has its own thread pool. You can tune the number of workers with the `-w` (or `--workers`) flag:
+Puma also offers "cluster mode". Cluster mode `fork`s workers from a master process. Each child process still has its own thread pool. You can tune the number of workers with the `-w` (or `--workers`) flag:
 
 ```
 $ puma -t 8:32 -w 3
@@ -116,13 +114,24 @@ Or with the `WEB_CONCURRENCY` environment variable:
 $ WEB_CONCURRENCY=3 puma -t 8:32
 ```
 
-Note that threads are still used in clustered 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.
+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:
 
-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).
+```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 `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).
 
-In clustered 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).
+For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](docs/deployment.md).
 
-If the `WEB_CONCURRENCY` environment variable is set to a value > 1 (and `--prune-bundler` has not been specified), preloading will be enabled by default. Otherwise, you can use the `--preload` flag from the command line:
+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).
+
+If the number of workers is greater than 1 (and `--prune-bundler` has not been specified), preloading will be enabled by default. Otherwise, you can use the `--preload` flag from the command line:
 
 ```
 $ puma -w 3 --preload
@@ -138,51 +147,106 @@ preload_app!
 
 Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preloading copies the code of master into the workers.
 
-When using clustered mode, you can specify a block in your configuration file that will be run on boot of each worker:
+#### Cluster mode hooks
+
+When using clustered mode, Puma's configuration DSL provides `before_fork`, `before_worker_boot`, and `after_worker_shutdown`
+hooks to run code when the master process forks, the child workers are booted, and after each child worker exits respectively.
+
+It is recommended to use these hooks with `preload_app!`, otherwise constants loaded by your
+application (such as `Rails`) will not be available inside the hooks.
 
 ```ruby
 # config/puma.rb
-on_worker_boot do
-  # configuration here
+before_fork do
+  # Add code to run inside the Puma master process before it forks a worker child.
 end
-```
 
-This code can be used to setup the process before booting the application, allowing
-you to do some Puma-specific things that you don't want to embed in your application.
-For instance, you could fire a log notification that a worker booted or send something to statsd. This can be called multiple times.
+before_worker_boot do
+  # Add code to run inside the Puma worker process after forking.
+end
 
-Constants loaded by your application (such as `Rails`) will not be available in `on_worker_boot`
-unless preloading is enabled.
+after_worker_shutdown do |worker_handle|
+  # Add code to run inside the Puma master process after a worker exits. `worker.process_status` can be used to get the
+  # `Process::Status` of the exited worker.
+end
+```
 
-You can also specify a block to be run before workers are forked, using `before_fork`:
+In addition, there is an `before_refork` and `after_refork` hooks which are used only in [`fork_worker` mode](docs/fork_worker.md),
+when the worker 0 child process forks a grandchild worker:
 
 ```ruby
-# config/puma.rb
-before_fork do
-  # configuration here
+before_refork do
+  # Used only when fork_worker mode is enabled. Add code to run inside the Puma worker 0
+  # child process before it forks a grandchild worker.
 end
 ```
 
-You can also specify a block to be run after puma is booted using `on_booted`:
+```ruby
+after_refork do
+  # Used only when fork_worker mode is enabled. Add code to run inside the Puma worker 0
+  # child process after it forks a grandchild worker.
+end
+```
+
+Importantly, note the following considerations when Ruby forks a child process:
+
+1. File descriptors such as network sockets **are** copied from the parent to the forked
+   child process. Dual-use of the same sockets by parent and child will result in I/O conflicts
+   such as `SocketError`, `Errno::EPIPE`, and `EOFError`.
+2. Background Ruby threads, including threads used by various third-party gems for connection
+   monitoring, etc., are **not** copied to the child process. Often this does not cause
+   immediate problems until a third-party connection goes down, at which point there will
+   be no supervisor to reconnect it.
+
+Therefore, we recommend the following:
+
+1. If possible, do not establish any socket connections (HTTP, database connections, etc.)
+   inside Puma's master process when booting.
+2. If (1) is not possible, use `before_fork` and `before_refork` to disconnect the parent's socket
+   connections when forking, so that they are not accidentally copied to the child process.
+3. Use `before_worker_boot` to restart any background threads on the forked child.
+4. Use `after_refork` to restart any background threads on the parent.
+
+#### Master process lifecycle hooks
+
+Puma's configuration DSL provides master process lifecycle hooks `after_booted`, `before_restart`, and `after_stopped`
+which may be used to specify code blocks to run on each event:
 
 ```ruby
 # config/puma.rb
-on_booted do
-  # configuration here
+after_booted do
+  # Add code to run in the Puma master process after it boots,
+  # and also after a phased restart completes.
+end
+
+before_restart do
+  # Add code to run in the Puma master process when it receives
+  # a restart command but before it restarts.
+end
+
+after_stopped do
+  # Add code to run in the Puma master process when it receives
+  # a stop command but before it shuts down.
 end
 ```
 
 ### Error handling
 
-If puma encounters an error outside of the context of your application, it will respond with a 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)).
+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/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)):
 
 ```ruby
-lowlevel_error_handler do |e|
-  Rollbar.critical(e)
-  [500, {}, ["An error has occurred, and engineers have been informed. Please reload the page. If you continue to have problems, contact support@example.com\n"]]
+lowlevel_error_handler do |e, env, status|
+  if status == 400
+    message = "The server could not process the request due to an error, such as an incorrectly typed URL, malformed syntax, or a URL that contains illegal characters.\n"
+  else
+    message = "An error has occurred, and engineers have been informed. Please reload the page. If you continue to have problems, contact support@example.com\n"
+    Rollbar.critical(e)
+  end
+
+  [status, {}, [message]]
 end
 ```
 
@@ -249,7 +313,7 @@ $ puma -b ssl://localhost:9292 -b tcp://localhost:9393 -C config/use_local_host.
 
 #### Controlling SSL Cipher Suites
 
-To use or avoid specific SSL cipher suites, use `ssl_cipher_filter` or `ssl_cipher_list` options.
+To use or avoid specific SSL ciphers for TLSv1.2 and below, use `ssl_cipher_filter` or `ssl_cipher_list` options.
 
 ##### Ruby:
 
@@ -263,6 +327,14 @@ $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&ssl_cipher_fil
 $ puma -b 'ssl://127.0.0.1:9292?keystore=path_to_keystore&keystore-pass=keystore_password&ssl_cipher_list=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA'
 ```
 
+To configure the available TLSv1.3 ciphersuites, use `ssl_ciphersuites` option (not available for JRuby).
+
+##### Ruby:
+
+```
+$ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&ssl_ciphersuites=TLS_AES_256_GCM_SHA384:TLS_AES_128_GCM_SHA256'
+```
+
 See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html for cipher filter format and full list of cipher suites.
 
 Disable TLS v1 with the `no_tlsv1` option:
@@ -279,7 +351,7 @@ To enable verification flags offered by OpenSSL, use `verification_flags` (not a
 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&verification_flags=PARTIAL_CHAIN'
 ```
 
-You can also set multiple verification flags (by separating them with coma):
+You can also set multiple verification flags (by separating them with a comma):
 
 ```
 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&verification_flags=PARTIAL_CHAIN,CRL_CHECK'
@@ -320,7 +392,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:
 
@@ -352,7 +424,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
 
@@ -372,19 +444,6 @@ Some platforms do not support all Puma features.
   * **Windows**: Cluster mode is not supported due to a lack of fork(2).
   * **Kubernetes**: The way Kubernetes handles pod shutdowns interacts poorly with server processes implementing graceful shutdown, like Puma. See the [kubernetes section of the documentation](docs/kubernetes.md) for more details.
 
-## Known Bugs
-
-For MRI versions 2.2.7, 2.2.8, 2.2.9, 2.2.10, 2.3.4 and 2.4.1, you may see ```stream closed in another thread (IOError)```. It may be caused by a [Ruby bug](https://bugs.ruby-lang.org/issues/13632). It can be fixed with the gem https://rubygems.org/gems/stopgap_13632:
-
-```ruby
-if %w(2.2.7 2.2.8 2.2.9 2.2.10 2.3.4 2.4.1).include? RUBY_VERSION
-  begin
-    require 'stopgap_13632'
-  rescue LoadError
-  end
-end
-```
-
 ## Deployment
 
  * Puma has support for Capistrano with an [external gem](https://github.com/seuros/capistrano-puma).

data/docs/5.0-Upgrade.md

@@ -0,0 +1,98 @@
+# Welcome to Puma 5: Spoony Bard.
+
+![Spoony Bard](https://i1.kym-cdn.com/entries/icons/original/000/006/385/Spoony_Bard.jpg "Spoony Bard")
+
+>Note: Puma 5 now automatically uses `WEB_CONCURRENCY` env var if set see [this post for an explanation](https://github.com/puma/puma/issues/2393#issuecomment-702352208). If your memory use goes up after upgrading to Puma 5 it indicates you're now running with multiple workers (processes). You can decrease memory use by tuning this number to be lower.
+
+Puma 5 brings new experimental performance features, a few quality-of-life features and loads of bugfixes. Here's what you should do:
+
+1. Review the Upgrade section below to see if any of 5.0's breaking changes will affect you.
+2. Upgrade to version 5.0 in your Gemfile and deploy.
+3. Try the new performance experiments outlined below and report your results back to the Puma issue tracker.
+
+Puma 5 was named Spoony Bard by our newest supercontributor, [@wjordan](https://github.com/puma/puma/commits?author=wjordan). Will brought you one of our new perf features for this release, as well as [many other fixes and refactors.](https://github.com/puma/puma/commits?author=wjordan) If you'd like to name a Puma release in the future, take a look at [CONTRIBUTING.md](../CONTRIBUTING.md) and get started helping us out :)
+
+Puma 5 also welcomes [@MSP-Greg](https://github.com/puma/puma/commits?author=MSP-Greg) as our newest committer. Greg has been instrumental in improving our CI setup and SSL features. Greg also [named our 4.3.0 release](https://github.com/puma/puma/releases/tag/v4.3.0): Mysterious Traveller.
+
+## What's New
+
+Puma 5 contains three new "experimental" performance features for cluster-mode Pumas running on MRI.
+
+If you try any of these features, please report your results to [our report issue](https://github.com/puma/puma/issues/2258).
+
+Part of the reason we're calling them _experimental_ is because we're not sure if they'll actually have any benefit. People's workloads in the real world are often not what we anticipate, and synthetic benchmarks are usually not of any help in figuring out if a change will be beneficial or not.
+
+We do not believe any of the new features will have a negative effect or impact the stability of your application. This is either a "it works" or "it does nothing" experiment.
+
+If any of the features turn out to be particularly beneficial, we may make them defaults in future versions of Puma.
+
+### Lower latency, better throughput
+
+From our friends at GitLab, the new experimental `wait_for_less_busy_worker` config option may reduce latency and improve throughput for high-load Puma apps on MRI. See the [pull request](https://github.com/puma/puma/pull/2079) for more discussion.
+
+Users of this option should see reduced request queue latency and possibly less overall latency.
+
+Add the following to your `puma.rb` to try it:
+
+```ruby
+wait_for_less_busy_worker
+# or
+wait_for_less_busy_worker 0.001
+```
+
+Production testing at GitLab suggests values between `0.001` and `0.010` are best.
+
+### Better memory usage
+
+5.0 brings two new options to your config which may improve memory usage.
+
+#### nakayoshi_fork
+
+`nakayoshi_fork` calls GC a handful of times and compacts the heap on Ruby 2.7+ before forking. This may reduce memory usage of Puma on MRI with preload enabled. It's inspired by [Koichi Sasada's work](https://github.com/ko1/nakayoshi_fork).
+
+To use it, you can add this to your `puma.rb`:
+
+```ruby
+nakayoshi_fork
+```
+
+#### fork_worker
+
+Puma 5 introduces an experimental new cluster-mode configuration option, `fork_worker` (`--fork-worker` from the CLI). This mode causes Puma to fork additional workers from worker 0, instead of directly from the master process:
+
+```
+10000   \_ puma 4.3.3 (tcp://0.0.0.0:9292) [puma]
+10001       \_ puma: cluster worker 0: 10000 [puma]
+10002           \_ puma: cluster worker 1: 10000 [puma]
+10003           \_ puma: cluster worker 2: 10000 [puma]
+10004           \_ puma: cluster worker 3: 10000 [puma]
+```
+
+It is compatible with phased restarts. It also may improve memory usage because the worker process loads additional code after processing requests.
+
+To learn more about using `refork` and `fork_worker`, see ['Fork Worker'](fork_worker.md).
+
+### What else is new?
+
+* **Loads of bugfixes**.
+* Faster phased restarts and worker timeouts.
+* pumactl now has a `thread-backtraces` command to print thread backtraces, bringing thread backtrace printing to all platforms, not just *BSD and Mac. (#2053)
+* Added incrementing `requests_count` to `Puma.stats`. (#2106)
+* Faster phased restart and worker timeout. (#2220)
+* Added `state_permission` to config DSL to set state file permissions (#2238)
+* Ruby 2.2 support will be dropped in Puma 6. This is the final major release series for Ruby 2.2.
+
+## Upgrade
+
+* Setting the `WEB_CONCURRENCY` environment variable will now configure the number of workers (processes) that Puma will boot and enable preloading of the application.
+* If you did not explicitly set `environment` before, Puma now checks `RAILS_ENV` and will use that, if available in addition to `RACK_ENV`.
+* If you have been using the `--control` CLI option, update your scripts to use `--control-url`.
+* If you are using `worker_directory` in your config file, change it to `directory`.
+* If you are running MRI, default thread count on Puma is now 5, not 16. This may change the amount of threads running in your threadpool. We believe 5 is a better default for most Ruby web applications on MRI. Higher settings increase latency by causing GVL contention.
+* If you are using a worker count of more than 1, set using `WEB_CONCURRENCY`, Puma will now preload the application by default (disable with `preload_app! false`). We believe this is a better default, but may cause issues in non-Rails applications if you do not have the proper `before` and `after` fork hooks configured. See documentation for your framework. Rails users do not need to change anything. **Please note that it is not possible to use [the phased restart](restart.md) with preloading.**
+* tcp mode and daemonization have been removed without replacement. For daemonization, please use a modern process management solution, such as systemd or monit.
+* `connected_port` was renamed to `connected_ports` and now returns an Array, not an Integer.
+
+Then, update your Gemfile:
+
+`gem 'puma', '< 6'`

data/docs/6.0-Upgrade.md

@@ -0,0 +1,56 @@
+# Welcome to Puma 6: Sunflower.
+
+![Image by Todd Trapani, Unsplash](https://user-images.githubusercontent.com/845662/192706685-774d3d0d-f4a9-4b93-b27b-5a3b7f44ff31.jpg)
+
+Puma 6 brings performance improvements for most applications, experimental Rack 3 support, support for Sidekiq 7 Capsules, and more.
+
+Here's what you should do:
+
+1. Review the Upgrade section below to look for breaking changes that could affect you.
+2. Upgrade to version 6.0 in your Gemfile and deploy.
+3. Open up a new bug issue if you find any problems.
+4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+For a complete list of changes, see [History.md](../History.md).
+
+## What's New
+
+Puma 6 is mostly about a few nice-to-have performance changes, and then a few breaking API changes we've been putting off for a while.
+
+### Improved Performance
+
+We've improved throughput and latency in Puma 6 in a few areas.
+
+1. **Large chunked response body throughput 3-10x higher** Chunked response bodies >100kb should be 3 to 10 times faster than in Puma 5. String response bodies should be ~10% faster.
+2. **File response throughput is 3x higher.** File responses (e.g. assets) should be about 3x faster.
+3. **wait_for_less_busy_worker is now default, meaning lower latencies for high-utilization servers** `wait_for_less_busy_worker` was an experimental feature in Puma 5 and it's now the default in Puma 6. This feature makes each Puma child worker in cluster mode wait before listening on the socket, and that wait time is proportional to N * `number_of_threads_responding_to_requests`. This means that it's more likely that a request is picked up by the least-loaded Puma child worker listening on the socket. Many users reported back that this option was stable and decreased average latency, particularly in environments with high load and utilization.
+
+### Experimental Rack 3 Support
+
+[Rack 3 is now out](https://github.com/rack/rack/blob/main/UPGRADE-GUIDE.md) and we've started on Rack 3 support. Please open a bug if you find any incompatibilites.
+
+### Sidekiq 7 Capsules
+
+Sidekiq 7 (releasing soon) introduces Capsules, which allows you to run a Sidekiq server inside your Puma server (or any other Ruby process for that matter). We've added support by allowing you to pass data into `run_hooks`, see [issue #2915](https://github.com/puma/puma/issues/2915).
+
+## Upgrade
+
+Check the following list to see if you're depending on any of these behaviors:
+
+1. Configuration constants like `DefaultRackup` removed, see [#2928](https://github.com/puma/puma/pull/2928/files#diff-2dc4e3e83be7fd97cebc482ae07d6a8216944003de82458783fb00b5ae9524c8) for the full list.
+1. We have changed the names of the following environment variables: `DISABLE_SSL` is now `PUMA_DISABLE_SSL`, and `MAKE_WARNINGS_INTO_ERRORS` is now `PUMA_MAKE_WARNINGS_INTO_ERRORS`.
+1. Nakayoshi GC (`nakayoshi_fork` option in config) has been removed without replacement.
+1. `wait_for_less_busy_worker` is now on by default. If you don't want to use this feature, you must add `wait_for_less_busy_worker 0` in your config.
+1. We've removed the following public methods on Puma::Server: `Puma::Server#min_threads`, `Puma::Server#max_threads`. Instead, you can pass in configuration as an option to Puma::Server#new. This might make certain gems break (`capybara` for example).
+1. We've removed the following constants: `Puma::StateFile::FIELDS`, `Puma::CLI::KEYS_NOT_TO_PERSIST_IN_STATE` and `Puma::Launcher::KEYS_NOT_TO_PERSIST_IN_STATE`, and `Puma::ControlCLI::COMMANDS`.
+1. We no longer support Ruby 2.2, 2.3, or JRuby on Java 1.7 or below.
+1. The behavior of `remote_addr` has changed. When using the set_remote_address header: "header_name" functionality, if the header is not passed, REMOTE_ADDR is now set to the physical peeraddr instead of always being set to 127.0.0.1. When an error occurs preventing the physical peeraddr from being fetched, REMOTE_ADDR is now set to the unspecified source address ('0.0.0.0') instead of to '127.0.0.1'
+1. Previously, Puma supported anything as an HTTP method and passed it to the app. We now only accept the following 8 HTTP methods, based on [RFC 9110, section 9.1](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.1).  The [IANA HTTP Method Registry](https://www.iana.org/assignments/http-methods/http-methods.xhtml) contains a full list of HTTP methods.
+   ```
+   HEAD GET POST PUT DELETE OPTIONS TRACE PATCH
+   ```
+   As of Puma 6.2, these can be overridden by `supported_http_methods` in your config file, see `Puma::DSL#supported_http_methods`.
+
+Then, update your Gemfile:
+
+`gem 'puma', '< 7'`

data/docs/7.0-Upgrade.md

@@ -0,0 +1,52 @@
+# Welcome to Puma 7: Romantic Warrior.
+
+Puma 7 brings better tail latency for keepalive-heavy traffic, support for fiber-per-request runtimes, and a handful of cleanup and compatibility changes across the server.
+
+Here's what you should do:
+
+1. Review the Upgrade section below to look for breaking changes that could affect you.
+2. Upgrade to version 7.0 in your Gemfile and deploy.
+3. Open up a new bug issue if you find any problems.
+4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](../CONTRIBUTING.md).
+
+For a complete list of changes, see [History.md](../History.md).
+
+## What's New
+
+Puma 7 is focused on request lifecycle improvements and long-request correctness.
+
+1. **Better tail behavior for keepalive connections.** Puma 7 includes a high-effort fix for long tail response behavior with keepalive clients.
+2. **Fiber-per-request support.** Puma now supports fiber-per-request execution.
+3. **`rack.response_finished` support.** Puma now supports the Rack hook for response completion.
+4. **Custom request logging support.** You can plug in a custom logger for request logs.
+
+## Upgrade
+
+Check the following list to see if you're depending on any of these behaviors:
+
+1. The default `max_keep_alive` is now `999`.
+1. The default `persistent_timeout` is now `65` seconds.
+1. Hook methods now raise `ArgumentError` if called without a block.
+1. For Rack > 3.1, Puma no longer sets `env['HTTP_VERSION']`.
+1. `Puma::Runner#ruby_engine` has been removed.
+1. `preload_app!` is now the default in cluster mode. If you need the old behavior, set `preload_app! false` explicitly.
+1. `Puma::Configuration` must be `clamp`-ed before reading values.
+1. Response headers are now normalized to lowercase.
+1. The minimum supported Ruby version is now 3.0.
+1. Callback hook names have been renamed:
+
+| Old hook name | New hook name |
+|---|---|
+| `on_worker_boot` | `before_worker_boot` |
+| `on_worker_shutdown` | `before_worker_shutdown` |
+| `on_restart` | `before_restart` |
+| `on_booted` | `after_booted` |
+| `on_stopped` | `after_stopped` |
+| `on_refork` | `before_refork` |
+| `on_thread_start` | `before_thread_start` |
+| `on_thread_exit` | `before_thread_exit` |
+| `on_worker_fork` | `before_worker_fork` |
+
+Then, update your Gemfile:
+
+`gem 'puma', '< 8'`

data/docs/8.0-Upgrade.md

@@ -0,0 +1,100 @@
+# Welcome to Puma 8.0: Into the Arena.
+
+Puma 8 brings IPv6 by default, increased control over the threadpool, and more.
+
+Here's what you should do:
+
+1. Review the Upgrade section below to look for breaking changes that could affect you.
+2. Upgrade to version 8.0 in your Gemfile and deploy.
+3. Open up a new bug issue if you find any problems.
+4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+For a complete list of changes, see [History.md](./History.md).
+
+## What's New
+
+### Smarter concurrency controls
+
+**IO-bound requests can now go past your normal thread ceiling.** Puma 8 adds `max_io_threads` and injects `env["puma.mark_as_io_bound"]` into the Rack env so your app or middleware can tell Puma when a request has become mostly I/O wait. That helps mixed workloads a lot: slow API calls, report generation, and similar wait-heavy requests no longer need to crowd out CPU-bound work as aggressively. This landed in [#3816](https://github.com/puma/puma/pull/3816) and was refined in [#3894](https://github.com/puma/puma/pull/3894).
+
+```ruby
+# config/puma.rb
+threads 0, 5
+max_io_threads 5
+```
+
+```ruby
+# config.ru
+run lambda { |env|
+  env['puma.mark_as_io_bound'].call
+  report = SlowReportService.fetch
+
+  [200, { 'content-type' => 'application/json' }, [report]]
+}
+```
+
+We anticipate this will mainly by used by framework authors who have threads or types of requests they know are extremely IO-bound, and don't recommend it for use at the application level.
+
+**Thread pool limits can be changed at runtime.** Puma now exposes `Puma::Server#update_thread_pool_min_max`, and hook/plugin code can do the same through `Puma::ServerPluginControl`.
+
+```ruby
+# from a plugin or other trusted in-process integration
+server.update_thread_pool_min_max(min: 2, max: 12)
+```
+
+If you already use `before_thread_start`, note that hook behavior changed in this release; see the Upgrade section below.
+
+### Cleaner config for single and cluster mode
+
+**New `single` and `cluster` blocks let one config file express both modes cleanly.** These blocks run after config files are loaded, so you can keep the mode-specific settings in one obvious place instead of scattering `if` logic through `config/puma.rb`. This makes shared configs much easier to read and reuse across development, review apps, and production. See [#3621](https://github.com/puma/puma/pull/3621).
+
+```ruby
+workers ENV.fetch('WEB_CONCURRENCY', 0)
+
+single do
+  silence_fork_callback_warning
+end
+
+# Only runs if workers > 0
+cluster do
+  preload_app!
+  before_worker_boot do
+    # Do a thing
+  end
+end
+```
+
+### Better debugging and operations
+
+**`shutdown_debug` can now be limited to forced shutdowns.** If you want thread backtraces only when a graceful shutdown turns into a forced one, use `shutdown_debug on_force: true`. That keeps normal deploy logs quieter while still giving you the "what is hanging?" escape hatch when you need it. See [#3671](https://github.com/puma/puma/pull/3671).
+
+```ruby
+shutdown_debug on_force: true
+force_shutdown_after 30
+```
+
+**Thread backtrace via signal works on more platforms.** On systems without `SIGINFO`, Puma now uses `SIGPWR` for thread backtrace dumps. See [#3829](https://github.com/puma/puma/pull/3829).
+
+**Phased restart is safer with `fork_worker`.** Puma no longer reforks from a stale worker 0 during phased restarts in `fork_worker` mode. There is nothing new to configure, but if you have tooling that watches worker order, check the Upgrade section because the rollout sequence changed. See [#3853](https://github.com/puma/puma/pull/3853).
+
+### Networking and performance
+
+**Puma now prefers IPv6 wildcard binds when the host supports them.** When Puma detects a non-loopback IPv6 interface, the default TCP host becomes `::` and the default bind becomes `tcp://[::]:PORT`. That lines Puma up better with modern dual-stack hosts, while still falling back to IPv4 when IPv6 is unavailable. See [#3847](https://github.com/puma/puma/pull/3847). If you need IPv4-only behavior, pin the bind explicitly.
+
+```ruby
+bind 'tcp://0.0.0.0:9292'
+```
+
+**There are also a couple of hot-path performance wins.** JRuby gets a faster HTTP parser with fewer copies and cheaper lookups, and Puma now avoids redundant header key downcasing when building responses. See [#3838](https://github.com/puma/puma/pull/3838) and [#3874](https://github.com/puma/puma/pull/3874).
+
+## Upgrade
+
+Check the following list to see if you're depending on any of these behaviors:
+
+1. Puma will now listen on `::` (IPv6) by default. Previously, it listened to `0.0.0.0` (IPv4). Systems that support both IPv6 and IPv4 (Ubuntu and Mac commonly do) will still support receiving to `0.0.0.0`. See [[the support table in the PR](https://github.com/puma/puma/pull/3847)](https://github.com/puma/puma/pull/3847) for a binding compatibility. For systems that ONLY bind to IPv6 (without IPv4 support) this may be a breaking change. You can overwrite this default behavior by setting `bind 'tcp://0.0.0.0:9292'`, `port ENV.fetch('PORT', 9292), '0.0.0.0'`, or `set_default_host '0.0.0.0'` explicitly to remain IPv4 only. Review any firewall rules, health checks, deploy scripts, or host-string parsing code that assumed `0.0.0.0`, `127.0.0.1`, or unbracketed `HOST:PORT` formatting.
+2. If you explicitly configure `bind 'tcp://[::]:...'`, `bind 'ssl://[::]:...'`, or equivalent `ssl_bind '::', ...`, Puma will now rewrite that unspecified IPv6 bind to `0.0.0.0` when the host has no non-loopback IPv6 interface, and it will warn on boot. If you were using `::` to force IPv6-only behavior or to detect IPv6 availability, switch to a concrete IPv6 address instead of `::`, or ensure the machine actually has a usable IPv6 interface before Puma starts.
+3. `before_thread_start` hooks now receive a `Puma::ServerPluginControl` argument. Update any zero-arity lambdas, method objects, or other strict-arity hook code to accept one argument, for example `before_thread_start { |_control| ... }`, or Puma can raise `ArgumentError` when the hook runs.
+4. On platforms without `SIGINFO`, Puma now traps `SIGPWR`, and `pumactl info` sends `SIGPWR` there. If your supervisor, init script, or container tooling already uses `SIGPWR` for something else, change that wiring before upgrading and update any runbooks that assumed Puma would ignore `SIGPWR`.
+5. Requests rejected by `supported_http_methods` are now treated as parser/client errors earlier in request processing. If you use `supported_http_methods`, re-test unsupported-method requests and do not depend on the old 501 timing, connection handling, or `lowlevel_error_handler` behavior; if your error handler still sees these requests, make sure it tolerates a less-normalized Rack `env`.
+6. `http_content_length_limit` enforcement is stricter now. A `413` on an HTTP/1.1 keep-alive request now forces `connection: close`, and chunked request bodies are rejected as soon as they cross the limit during parsing. Update clients, proxies, and tests not to reuse the socket after a `413`, and re-test any upload flows or custom error handling that depended on Puma's previous oversized-body behavior.
+7. If you use `fork_worker`, phased restart order changed. During `USR1` or `pumactl phased-restart`, worker `0` is now reinserted and restarted/reforked first after replacement. Update deployment scripts, canary logic, or monitoring that assumed the old worker sequence or keyed rollout steps off worker index order.