puma 7.1.0 → 8.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. checksums.yaml +4 -4
  2. data/History.md +132 -0
  3. data/README.md +18 -11
  4. data/docs/5.0-Upgrade.md +98 -0
  5. data/docs/6.0-Upgrade.md +56 -0
  6. data/docs/7.0-Upgrade.md +52 -0
  7. data/docs/8.0-Upgrade.md +100 -0
  8. data/docs/deployment.md +58 -23
  9. data/docs/grpc.md +62 -0
  10. data/docs/images/favicon.svg +1 -0
  11. data/docs/images/running-puma.svg +1 -0
  12. data/docs/images/standard-logo.svg +1 -0
  13. data/docs/jungle/README.md +1 -1
  14. data/docs/kubernetes.md +3 -10
  15. data/docs/plugins.md +2 -2
  16. data/docs/signals.md +10 -10
  17. data/docs/stats.md +1 -1
  18. data/docs/systemd.md +3 -3
  19. data/ext/puma_http11/http11_parser.java.rl +51 -65
  20. data/ext/puma_http11/org/jruby/puma/EnvKey.java +241 -0
  21. data/ext/puma_http11/org/jruby/puma/Http11.java +168 -104
  22. data/ext/puma_http11/org/jruby/puma/Http11Parser.java +71 -85
  23. data/ext/puma_http11/puma_http11.c +101 -109
  24. data/lib/puma/app/status.rb +10 -2
  25. data/lib/puma/binder.rb +2 -2
  26. data/lib/puma/cli.rb +1 -1
  27. data/lib/puma/client.rb +90 -66
  28. data/lib/puma/client_env.rb +171 -0
  29. data/lib/puma/cluster/worker.rb +10 -9
  30. data/lib/puma/cluster.rb +3 -4
  31. data/lib/puma/configuration.rb +86 -17
  32. data/lib/puma/const.rb +2 -2
  33. data/lib/puma/control_cli.rb +1 -1
  34. data/lib/puma/detect.rb +11 -0
  35. data/lib/puma/dsl.rb +90 -14
  36. data/lib/puma/launcher/bundle_pruner.rb +2 -4
  37. data/lib/puma/launcher.rb +7 -7
  38. data/lib/puma/log_writer.rb +8 -2
  39. data/lib/puma/reactor.rb +3 -12
  40. data/lib/puma/{request.rb → response.rb} +25 -194
  41. data/lib/puma/runner.rb +1 -1
  42. data/lib/puma/server.rb +73 -38
  43. data/lib/puma/server_plugin_control.rb +32 -0
  44. data/lib/puma/single.rb +2 -2
  45. data/lib/puma/thread_pool.rb +129 -23
  46. data/lib/rack/handler/puma.rb +1 -1
  47. data/tools/Dockerfile +13 -5
  48. metadata +15 -5
  49. data/ext/puma_http11/ext_help.h +0 -15
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: cb282989c2e0ee20b007c5b0cdf231caf106816210101572346098f6863502c7
4
- data.tar.gz: f4217f8221a64fcd6f5bf2c2249ed8dc6d512ba167e93ef4273b0accb574d26d
3
+ metadata.gz: b4bda2b8a9ed5838776f890077459a3db57a8a581b17516434ba9b9cbd5d0f71
4
+ data.tar.gz: 621365fbc4837c30dc8c7d32de00ceadbcf80db735ae2388aeb0b521414a1b3c
5
5
  SHA512:
6
- metadata.gz: 2070bae758f22fc8b0784c6b426a7177d65e9039fd2d1969d1241e8f101e46a04afdc5f93f5b6646eb0d9fb15fd6b47f87fb0cee478c3c58e840d3ae852b754a
7
- data.tar.gz: 6d35fd83049a36ec8017fb859899fddd0305b90977a14f707f551b1e802d822100bf10126ce43598bf23bbf17deb581135955f61028ee56d0ba3e161718f9d79
6
+ metadata.gz: 321cc06d7e4f77147aeeb44b29b7de9627b5942ef374b93f64a5aa89c85414c761c79833ba61e6accb0fee53ee68cc91f07121d7a74ab106a1091885e806b123
7
+ data.tar.gz: eb9e6c89473875970b71d2fec792e68c1355ab0dff2dc6d887cd7221449c5c9e20f7030ec3bc3ed8edb18ff50c906697067325a86d040bdc9bfedb5d74566454
data/History.md CHANGED
@@ -1,3 +1,79 @@
1
+ ## 8.0.1 / 2026-04-27
2
+
3
+ * Bugfixes
4
+ * Fix `prune_bundler` stripping user-configured `BUNDLE_*` env vars (e.g. `BUNDLE_WITHOUT`) on re-exec, which caused workers to crash on boot ([#3929])
5
+
6
+ * Performance
7
+ * Use blocks for debug logging to avoid creating log messages when debug is disabled ([#3920])
8
+
9
+ * Docs
10
+ * Fix incorrect hook names in gRPC docs ([#3923])
11
+ * Reword v8 upgrade guide IPv6 bullet for clarity ([#3928])
12
+
13
+ ## 8.0.0 / 2026-03-27
14
+
15
+ * Features
16
+ * Add `env["puma.mark_as_io_bound"]` API and `max_io_threads` config to allow IO-bound requests to exceed the thread pool max, enabling better handling of mixed workloads ([#3816], [#3894])
17
+ * Add `single` and `cluster` DSL hooks for mode-specific configuration ([#3621])
18
+ * Add `on_force` option to `shutdown_debug` to only dump thread backtraces on forced (non-graceful) shutdown ([#3671])
19
+ * Add API to dynamically update min and max thread counts at runtime via `update_thread_pool_min_max` and `ServerPluginControl` ([#3658])
20
+ * Use SIGPWR for thread backtrace dumps on Linux/JRuby where SIGINFO is unavailable ([#3829])
21
+
22
+ * Bugfixes
23
+ * Fix phased restart for `fork_worker` to avoid forking from stale worker 0 when it has been replaced ([#3853])
24
+
25
+ * Performance
26
+ * JRuby HTTP parser improvements: pre-allocated header keys, perfect hash lookup, reduced memory copies ([#3838])
27
+ * Cache downcased header key in `str_headers` to avoid redundant `String#downcase` calls, reducing allocations by ~50% per response ([#3874])
28
+
29
+ * Refactor
30
+ * Collect `env` processing into dedicated `client_env.rb` module ([#3582])
31
+ * Move event to default configuration ([#3872])
32
+
33
+ * Docs
34
+ * Add gRPC guide for configuring gRPC lifecycle hooks in clustered mode ([#3885])
35
+ * Add 7.0 upgrade guide, move 5.0/6.0 upgrade guides to docs directory ([#3900])
36
+ * Correct default values for `persistent_timeout` and `worker_boot_timeout` in DSL docs ([#3912])
37
+ * Add file descriptor limit warning in test helper for contributors ([#3893])
38
+
39
+ * Breaking changes
40
+ * Default production bind address changed from `0.0.0.0` to `::` (IPv6) when a non-loopback IPv6 interface is available; falls back to `0.0.0.0` if IPv6 is unavailable ([#3847])
41
+
42
+ ## 7.2.0 / 2026-01-20
43
+
44
+ * Features
45
+ * Add workers `:auto` ([#3827])
46
+ * Make it possible to restrict control server commands to stats ([#3787])
47
+
48
+ * Bugfixes
49
+ * Don't break if `WEB_CONCURRENCY` is set to a blank string ([#3837])
50
+ * Don't share server between worker 0 and descendants on refork ([#3602])
51
+ * Fix phase check race condition in `Puma::Cluster#check_workers` ([#3690])
52
+ * Fix advertising of CLI config before config files are loaded ([#3823])
53
+
54
+ * Performance
55
+ * 17% faster HTTP parsing through pre-interning env keys ([#3825])
56
+ * Implement `dsize` and `dcompact` functions for `Puma::HttpParser`, which makes Puma's C-extension GC-compactible ([#3828])
57
+
58
+ * Refactor
59
+ * Remove `NoMethodError` rescue in `Reactor#select_loop` ([#3831])
60
+ * Various cleanups in the C extension ([#3814])
61
+ * Monomorphize `handle_request` return ([#3802])
62
+
63
+ * Docs
64
+ * Change link to `docs/deployment.md` in `README.md` ([#3848])
65
+ * Fix formatting for each signal description in signals.md ([#3813])
66
+ * Update deployment and Kubernetes docs with Puma configuration tips ([#3807])
67
+ * Rename master to main ([#3809], [#3808], [#3800])
68
+ * Fix some minor typos in the docs ([#3804])
69
+ * Add `GOVERNANCE.md`, `MAINTAINERS` ([#3826])
70
+ * Remove Code Climate badge ([#3820])
71
+ * Add @joshuay03 to the maintainer list
72
+
73
+ * CI
74
+ * Use Minitest 6 where applicable ([#3859])
75
+ * Many test suite improvements and flake fixes ([#3861], [#3863], [#3860], [#3852], [#3857], [#3856], [#3845], [#3843], [#3842], [#3841], [#3822], [#3817], [#3764])
76
+
1
77
  ## 7.1.0 / 2025-10-16
2
78
 
3
79
  * Features
@@ -2259,6 +2335,62 @@ be added back in a future date when a java Puma::MiniSSL is added.
2259
2335
  * Bugfixes
2260
2336
  * Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
2261
2337
 
2338
+ [#3929]:https://github.com/puma/puma/pull/3929 "PR by Joshua Young, merged 2026-04-26"
2339
+ [#3928]:https://github.com/puma/puma/pull/3928 "PR by Nate Berkopec, merged 2026-04-16"
2340
+ [#3923]:https://github.com/puma/puma/pull/3923 "PR by Joshua Young, merged 2026-04-10"
2341
+ [#3920]:https://github.com/puma/puma/pull/3920 "PR by Petrik de Heus, merged 2026-04-10"
2342
+ [#3912]:https://github.com/puma/puma/pull/3912 "PR by Bengt-Ove Hollaender, merged 2026-03-26"
2343
+ [#3900]:https://github.com/puma/puma/pull/3900 "PR by Nate Berkopec, merged 2026-03-26"
2344
+ [#3894]:https://github.com/puma/puma/pull/3894 "PR by Joshua Young, merged 2026-03-07"
2345
+ [#3893]:https://github.com/puma/puma/pull/3893 "PR by Sasha Stadnyk, merged 2026-03-22"
2346
+ [#3885]:https://github.com/puma/puma/pull/3885 "PR by Joshua Young, merged 2026-02-18"
2347
+ [#3874]:https://github.com/puma/puma/pull/3874 "PR by Hadrien Blanc, merged 2026-01-28"
2348
+ [#3872]:https://github.com/puma/puma/pull/3872 "PR by Nate Berkopec, merged 2026-01-27"
2349
+ [#3853]:https://github.com/puma/puma/pull/3853 "PR by Krzysztof Jablonski, merged 2026-03-09"
2350
+ [#3847]:https://github.com/puma/puma/pull/3847 "PR by Richard Schneeman, merged 2026-03-26"
2351
+ [#3838]:https://github.com/puma/puma/pull/3838 "PR by Charles Oliver Nutter, merged 2026-01-31"
2352
+ [#3829]:https://github.com/puma/puma/pull/3829 "PR by Nate Berkopec, merged 2026-01-27"
2353
+ [#3816]:https://github.com/puma/puma/pull/3816 "PR by Jean Boussier, merged 2026-03-07"
2354
+ [#3671]:https://github.com/puma/puma/pull/3671 "PR by Joshua Young, merged 2026-03-08"
2355
+ [#3658]:https://github.com/puma/puma/pull/3658 "PR by Yuki Nishijima, merged 2026-02-18"
2356
+ [#3621]:https://github.com/puma/puma/pull/3621 "PR by Joshua Young, merged 2026-02-22"
2357
+ [#3582]:https://github.com/puma/puma/pull/3582 "PR by MSP-Greg, merged 2026-02-22"
2358
+ [#3863]:https://github.com/puma/puma/pull/3863 "PR by Nate Berkopec, merged 2026-01-20"
2359
+ [#3861]:https://github.com/puma/puma/pull/3861 "PR by MSP-Greg, merged 2026-01-20"
2360
+ [#3860]:https://github.com/puma/puma/pull/3860 "PR by MSP-Greg, merged 2026-01-16"
2361
+ [#3859]:https://github.com/puma/puma/pull/3859 "PR by MSP-Greg, merged 2026-01-16"
2362
+ [#3857]:https://github.com/puma/puma/pull/3857 "PR by Aaron Patterson, merged 2026-01-12"
2363
+ [#3856]:https://github.com/puma/puma/pull/3856 "PR by MSP-Greg, merged 2026-01-12"
2364
+ [#3852]:https://github.com/puma/puma/pull/3852 "PR by Miłosz Bieniek, merged 2026-01-14"
2365
+ [#3848]:https://github.com/puma/puma/pull/3848 "PR by Miłosz Bieniek, merged 2025-12-27"
2366
+ [#3845]:https://github.com/puma/puma/pull/3845 "PR by MSP-Greg, merged 2025-12-19"
2367
+ [#3843]:https://github.com/puma/puma/pull/3843 "PR by MSP-Greg, merged 2025-12-18"
2368
+ [#3842]:https://github.com/puma/puma/pull/3842 "PR by MSP-Greg, merged 2025-12-18"
2369
+ [#3841]:https://github.com/puma/puma/pull/3841 "PR by MSP-Greg, merged 2025-12-18"
2370
+ [#3837]:https://github.com/puma/puma/pull/3837 "PR by John Bachir, merged 2026-01-09"
2371
+ [#3833]:https://github.com/puma/puma/pull/3833 "PR by Patrik Ragnarsson, merged 2025-11-25"
2372
+ [#3831]:https://github.com/puma/puma/pull/3831 "PR by Joshua Young, merged 2025-11-25"
2373
+ [#3828]:https://github.com/puma/puma/pull/3828 "PR by Jean Boussier, merged 2025-11-21"
2374
+ [#3827]:https://github.com/puma/puma/pull/3827 "PR by Nate Berkopec, merged 2026-01-20"
2375
+ [#3826]:https://github.com/puma/puma/pull/3826 "PR by Nate Berkopec, merged 2026-01-20"
2376
+ [#3825]:https://github.com/puma/puma/pull/3825 "PR by Jean Boussier, merged 2025-11-19"
2377
+ [#3823]:https://github.com/puma/puma/pull/3823 "PR by Joshua Young, merged 2025-11-18"
2378
+ [#3822]:https://github.com/puma/puma/pull/3822 "PR by Nate Berkopec, merged 2025-11-17"
2379
+ [#3820]:https://github.com/puma/puma/pull/3820 "PR by Nate Berkopec, merged 2025-11-19"
2380
+ [#3817]:https://github.com/puma/puma/pull/3817 "PR by Nate Berkopec, merged 2025-11-17"
2381
+ [#3814]:https://github.com/puma/puma/pull/3814 "PR by Jean Boussier, merged 2025-11-17"
2382
+ [#3813]:https://github.com/puma/puma/pull/3813 "PR by Masafumi Koba, merged 2025-11-17"
2383
+ [#3809]:https://github.com/puma/puma/pull/3809 "PR by Patrik Ragnarsson, merged 2025-10-26"
2384
+ [#3808]:https://github.com/puma/puma/pull/3808 "PR by Nymuxyzo, merged 2025-10-26"
2385
+ [#3807]:https://github.com/puma/puma/pull/3807 "PR by Nate Berkopec, merged 2025-10-28"
2386
+ [#3804]:https://github.com/puma/puma/pull/3804 "PR by Joe Rafaniello, merged 2025-10-21"
2387
+ [#3802]:https://github.com/puma/puma/pull/3802 "PR by Richard Schneeman, merged 2025-10-20"
2388
+ [#3800]:https://github.com/puma/puma/pull/3800 "PR by MSP-Greg, merged 2025-10-19"
2389
+ [#3787]:https://github.com/puma/puma/pull/3787 "PR by Stan Hu, merged 2025-10-17"
2390
+ [#3764]:https://github.com/puma/puma/pull/3764 "PR by MSP-Greg, merged 2025-10-17"
2391
+ [#3690]:https://github.com/puma/puma/pull/3690 "PR by Joshua Young, merged 2025-11-18"
2392
+ [#3602]:https://github.com/puma/puma/pull/3602 "PR by Joshua Young, merged 2025-11-28"
2393
+
2262
2394
  [#3707]:https://github.com/puma/puma/pull/3707 "PR by @nerdrew, merged 2025-10-02"
2263
2395
  [#3794]:https://github.com/puma/puma/pull/3794 "PR by @schneems, merged 2025-10-16"
2264
2396
  [#3795]:https://github.com/puma/puma/pull/3795 "PR by @MSP-Greg, merged 2025-10-16"
data/README.md CHANGED
@@ -1,12 +1,10 @@
1
1
  <p align="center">
2
- <img src="https://puma.io/images/logos/puma-logo-large.png">
2
+ <img src="docs/images/standard-logo.svg" alt="Puma logo">
3
3
  </p>
4
4
 
5
5
  # Puma: A Ruby Web Server Built For Parallelism
6
6
 
7
- [![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)
8
- [![Code Climate](https://codeclimate.com/github/puma/puma.svg)](https://codeclimate.com/github/puma/puma)
9
- [![StackOverflow](https://img.shields.io/badge/stackoverflow-Puma-blue.svg)]( https://stackoverflow.com/questions/tagged/puma )
7
+ [![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)
10
8
 
11
9
  Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server for Ruby/Rack applications**.
12
10
 
@@ -82,10 +80,10 @@ $ bundle exec puma
82
80
 
83
81
  ## Configuration
84
82
 
85
- 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).
83
+ 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).
86
84
 
87
85
  You can also find several configuration examples as part of the
88
- [test](https://github.com/puma/puma/tree/master/test/config) suite.
86
+ [test](https://github.com/puma/puma/tree/main/test/config) suite.
89
87
 
90
88
  For debugging purposes, you can set the environment variable `PUMA_LOG_CONFIG` with a value
91
89
  and the loaded configuration will be printed as part of the boot process.
@@ -116,11 +114,20 @@ Or with the `WEB_CONCURRENCY` environment variable:
116
114
  $ WEB_CONCURRENCY=3 puma -t 8:32
117
115
  ```
118
116
 
117
+ 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:
118
+
119
+ ```ruby
120
+ # config/puma.rb
121
+ workers :auto
122
+ ```
123
+
124
+ See [`workers :auto` gotchas](lib/puma/dsl.rb).
125
+
119
126
  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.
120
127
 
121
- 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).
128
+ 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).
122
129
 
123
- 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).
130
+ For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](docs/deployment.md).
124
131
 
125
132
  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).
126
133
 
@@ -226,7 +233,7 @@ end
226
233
  ### Error handling
227
234
 
228
235
  If Puma encounters an error outside of the context of your application, it will respond with a 400/500 and a simple
229
- textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/master/lib/puma/server.rb)).
236
+ textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/main/lib/puma/server.rb)).
230
237
  You can specify custom behavior for this scenario. For example, you can report the error to your third-party
231
238
  error-tracking service (in this example, [rollbar](https://rollbar.com)):
232
239
 
@@ -385,7 +392,7 @@ Puma has a built-in status and control app that can be used to query and control
385
392
  $ puma --control-url tcp://127.0.0.1:9293 --control-token foo
386
393
  ```
387
394
 
388
- 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.
395
+ 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.
389
396
 
390
397
  You can also interact with the control server via `pumactl`. This command will restart Puma:
391
398
 
@@ -417,7 +424,7 @@ $ puma -C "-"
417
424
 
418
425
  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).
419
426
 
420
- Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb) to see all available options.
427
+ Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/main/lib/puma/dsl.rb) to see all available options.
421
428
 
422
429
  ## Restart
423
430
 
data/docs/5.0-Upgrade.md ADDED
@@ -0,0 +1,98 @@
1
+ # Welcome to Puma 5: Spoony Bard.
2
+
3
+ ![Spoony Bard](https://i1.kym-cdn.com/entries/icons/original/000/006/385/Spoony_Bard.jpg "Spoony Bard")
4
+
5
+ >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.
6
+
7
+ Puma 5 brings new experimental performance features, a few quality-of-life features and loads of bugfixes. Here's what you should do:
8
+
9
+ 1. Review the Upgrade section below to see if any of 5.0's breaking changes will affect you.
10
+ 2. Upgrade to version 5.0 in your Gemfile and deploy.
11
+ 3. Try the new performance experiments outlined below and report your results back to the Puma issue tracker.
12
+
13
+ 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 :)
14
+
15
+ 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.
16
+
17
+ ## What's New
18
+
19
+ Puma 5 contains three new "experimental" performance features for cluster-mode Pumas running on MRI.
20
+
21
+ If you try any of these features, please report your results to [our report issue](https://github.com/puma/puma/issues/2258).
22
+
23
+ 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.
24
+
25
+ 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.
26
+
27
+ If any of the features turn out to be particularly beneficial, we may make them defaults in future versions of Puma.
28
+
29
+ ### Lower latency, better throughput
30
+
31
+ 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.
32
+
33
+ Users of this option should see reduced request queue latency and possibly less overall latency.
34
+
35
+ Add the following to your `puma.rb` to try it:
36
+
37
+ ```ruby
38
+ wait_for_less_busy_worker
39
+ # or
40
+ wait_for_less_busy_worker 0.001
41
+ ```
42
+
43
+ Production testing at GitLab suggests values between `0.001` and `0.010` are best.
44
+
45
+ ### Better memory usage
46
+
47
+ 5.0 brings two new options to your config which may improve memory usage.
48
+
49
+ #### nakayoshi_fork
50
+
51
+ `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).
52
+
53
+ To use it, you can add this to your `puma.rb`:
54
+
55
+ ```ruby
56
+ nakayoshi_fork
57
+ ```
58
+
59
+ #### fork_worker
60
+
61
+ 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:
62
+
63
+ ```
64
+ 10000 \_ puma 4.3.3 (tcp://0.0.0.0:9292) [puma]
65
+ 10001 \_ puma: cluster worker 0: 10000 [puma]
66
+ 10002 \_ puma: cluster worker 1: 10000 [puma]
67
+ 10003 \_ puma: cluster worker 2: 10000 [puma]
68
+ 10004 \_ puma: cluster worker 3: 10000 [puma]
69
+ ```
70
+
71
+ It is compatible with phased restarts. It also may improve memory usage because the worker process loads additional code after processing requests.
72
+
73
+ To learn more about using `refork` and `fork_worker`, see ['Fork Worker'](fork_worker.md).
74
+
75
+ ### What else is new?
76
+
77
+ * **Loads of bugfixes**.
78
+ * Faster phased restarts and worker timeouts.
79
+ * pumactl now has a `thread-backtraces` command to print thread backtraces, bringing thread backtrace printing to all platforms, not just *BSD and Mac. (#2053)
80
+ * Added incrementing `requests_count` to `Puma.stats`. (#2106)
81
+ * Faster phased restart and worker timeout. (#2220)
82
+ * Added `state_permission` to config DSL to set state file permissions (#2238)
83
+ * Ruby 2.2 support will be dropped in Puma 6. This is the final major release series for Ruby 2.2.
84
+
85
+ ## Upgrade
86
+
87
+ * Setting the `WEB_CONCURRENCY` environment variable will now configure the number of workers (processes) that Puma will boot and enable preloading of the application.
88
+ * If you did not explicitly set `environment` before, Puma now checks `RAILS_ENV` and will use that, if available in addition to `RACK_ENV`.
89
+ * If you have been using the `--control` CLI option, update your scripts to use `--control-url`.
90
+ * If you are using `worker_directory` in your config file, change it to `directory`.
91
+ * 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.
92
+ * 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.**
93
+ * tcp mode and daemonization have been removed without replacement. For daemonization, please use a modern process management solution, such as systemd or monit.
94
+ * `connected_port` was renamed to `connected_ports` and now returns an Array, not an Integer.
95
+
96
+ Then, update your Gemfile:
97
+
98
+ `gem 'puma', '< 6'`
data/docs/6.0-Upgrade.md ADDED
@@ -0,0 +1,56 @@
1
+ # Welcome to Puma 6: Sunflower.
2
+
3
+ ![Image by Todd Trapani, Unsplash](https://user-images.githubusercontent.com/845662/192706685-774d3d0d-f4a9-4b93-b27b-5a3b7f44ff31.jpg)
4
+
5
+ Puma 6 brings performance improvements for most applications, experimental Rack 3 support, support for Sidekiq 7 Capsules, and more.
6
+
7
+ Here's what you should do:
8
+
9
+ 1. Review the Upgrade section below to look for breaking changes that could affect you.
10
+ 2. Upgrade to version 6.0 in your Gemfile and deploy.
11
+ 3. Open up a new bug issue if you find any problems.
12
+ 4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](../CONTRIBUTING.md).
13
+
14
+ For a complete list of changes, see [History.md](../History.md).
15
+
16
+ ## What's New
17
+
18
+ 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.
19
+
20
+ ### Improved Performance
21
+
22
+ We've improved throughput and latency in Puma 6 in a few areas.
23
+
24
+ 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.
25
+ 2. **File response throughput is 3x higher.** File responses (e.g. assets) should be about 3x faster.
26
+ 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.
27
+
28
+ ### Experimental Rack 3 Support
29
+
30
+ [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.
31
+
32
+ ### Sidekiq 7 Capsules
33
+
34
+ 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).
35
+
36
+ ## Upgrade
37
+
38
+ Check the following list to see if you're depending on any of these behaviors:
39
+
40
+ 1. Configuration constants like `DefaultRackup` removed, see [#2928](https://github.com/puma/puma/pull/2928/files#diff-2dc4e3e83be7fd97cebc482ae07d6a8216944003de82458783fb00b5ae9524c8) for the full list.
41
+ 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`.
42
+ 1. Nakayoshi GC (`nakayoshi_fork` option in config) has been removed without replacement.
43
+ 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.
44
+ 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).
45
+ 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`.
46
+ 1. We no longer support Ruby 2.2, 2.3, or JRuby on Java 1.7 or below.
47
+ 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'
48
+ 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.
49
+ ```
50
+ HEAD GET POST PUT DELETE OPTIONS TRACE PATCH
51
+ ```
52
+ As of Puma 6.2, these can be overridden by `supported_http_methods` in your config file, see `Puma::DSL#supported_http_methods`.
53
+
54
+ Then, update your Gemfile:
55
+
56
+ `gem 'puma', '< 7'`
data/docs/7.0-Upgrade.md ADDED
@@ -0,0 +1,52 @@
1
+ # Welcome to Puma 7: Romantic Warrior.
2
+
3
+ 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.
4
+
5
+ Here's what you should do:
6
+
7
+ 1. Review the Upgrade section below to look for breaking changes that could affect you.
8
+ 2. Upgrade to version 7.0 in your Gemfile and deploy.
9
+ 3. Open up a new bug issue if you find any problems.
10
+ 4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](../CONTRIBUTING.md).
11
+
12
+ For a complete list of changes, see [History.md](../History.md).
13
+
14
+ ## What's New
15
+
16
+ Puma 7 is focused on request lifecycle improvements and long-request correctness.
17
+
18
+ 1. **Better tail behavior for keepalive connections.** Puma 7 includes a high-effort fix for long tail response behavior with keepalive clients.
19
+ 2. **Fiber-per-request support.** Puma now supports fiber-per-request execution.
20
+ 3. **`rack.response_finished` support.** Puma now supports the Rack hook for response completion.
21
+ 4. **Custom request logging support.** You can plug in a custom logger for request logs.
22
+
23
+ ## Upgrade
24
+
25
+ Check the following list to see if you're depending on any of these behaviors:
26
+
27
+ 1. The default `max_keep_alive` is now `999`.
28
+ 1. The default `persistent_timeout` is now `65` seconds.
29
+ 1. Hook methods now raise `ArgumentError` if called without a block.
30
+ 1. For Rack > 3.1, Puma no longer sets `env['HTTP_VERSION']`.
31
+ 1. `Puma::Runner#ruby_engine` has been removed.
32
+ 1. `preload_app!` is now the default in cluster mode. If you need the old behavior, set `preload_app! false` explicitly.
33
+ 1. `Puma::Configuration` must be `clamp`-ed before reading values.
34
+ 1. Response headers are now normalized to lowercase.
35
+ 1. The minimum supported Ruby version is now 3.0.
36
+ 1. Callback hook names have been renamed:
37
+
38
+ | Old hook name | New hook name |
39
+ |---|---|
40
+ | `on_worker_boot` | `before_worker_boot` |
41
+ | `on_worker_shutdown` | `before_worker_shutdown` |
42
+ | `on_restart` | `before_restart` |
43
+ | `on_booted` | `after_booted` |
44
+ | `on_stopped` | `after_stopped` |
45
+ | `on_refork` | `before_refork` |
46
+ | `on_thread_start` | `before_thread_start` |
47
+ | `on_thread_exit` | `before_thread_exit` |
48
+ | `on_worker_fork` | `before_worker_fork` |
49
+
50
+ Then, update your Gemfile:
51
+
52
+ `gem 'puma', '< 8'`
data/docs/8.0-Upgrade.md ADDED
@@ -0,0 +1,100 @@
1
+ # Welcome to Puma 8.0: Into the Arena.
2
+
3
+ Puma 8 brings IPv6 by default, increased control over the threadpool, and more.
4
+
5
+ Here's what you should do:
6
+
7
+ 1. Review the Upgrade section below to look for breaking changes that could affect you.
8
+ 2. Upgrade to version 8.0 in your Gemfile and deploy.
9
+ 3. Open up a new bug issue if you find any problems.
10
+ 4. Join us in building Puma! We welcome first-timers. See [CONTRIBUTING.md](./CONTRIBUTING.md).
11
+
12
+ For a complete list of changes, see [History.md](./History.md).
13
+
14
+ ## What's New
15
+
16
+ ### Smarter concurrency controls
17
+
18
+ **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).
19
+
20
+ ```ruby
21
+ # config/puma.rb
22
+ threads 0, 5
23
+ max_io_threads 5
24
+ ```
25
+
26
+ ```ruby
27
+ # config.ru
28
+ run lambda { |env|
29
+ env['puma.mark_as_io_bound'].call
30
+ report = SlowReportService.fetch
31
+
32
+ [200, { 'content-type' => 'application/json' }, [report]]
33
+ }
34
+ ```
35
+
36
+ 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.
37
+
38
+ **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`.
39
+
40
+ ```ruby
41
+ # from a plugin or other trusted in-process integration
42
+ server.update_thread_pool_min_max(min: 2, max: 12)
43
+ ```
44
+
45
+ If you already use `before_thread_start`, note that hook behavior changed in this release; see the Upgrade section below.
46
+
47
+ ### Cleaner config for single and cluster mode
48
+
49
+ **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).
50
+
51
+ ```ruby
52
+ workers ENV.fetch('WEB_CONCURRENCY', 0)
53
+
54
+ single do
55
+ silence_fork_callback_warning
56
+ end
57
+
58
+ # Only runs if workers > 0
59
+ cluster do
60
+ preload_app!
61
+ before_worker_boot do
62
+ # Do a thing
63
+ end
64
+ end
65
+ ```
66
+
67
+ ### Better debugging and operations
68
+
69
+ **`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).
70
+
71
+ ```ruby
72
+ shutdown_debug on_force: true
73
+ force_shutdown_after 30
74
+ ```
75
+
76
+ **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).
77
+
78
+ **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).
79
+
80
+ ### Networking and performance
81
+
82
+ **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.
83
+
84
+ ```ruby
85
+ bind 'tcp://0.0.0.0:9292'
86
+ ```
87
+
88
+ **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).
89
+
90
+ ## Upgrade
91
+
92
+ Check the following list to see if you're depending on any of these behaviors:
93
+
94
+ 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.
95
+ 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.
96
+ 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.
97
+ 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`.
98
+ 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`.
99
+ 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.
100
+ 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.