puma 6.4.0 → 6.6.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 (46) hide show
  1. checksums.yaml +4 -4
  2. data/History.md +235 -18
  3. data/README.md +87 -26
  4. data/docs/fork_worker.md +11 -1
  5. data/docs/java_options.md +54 -0
  6. data/docs/kubernetes.md +1 -1
  7. data/docs/plugins.md +4 -0
  8. data/docs/restart.md +1 -0
  9. data/docs/signals.md +2 -2
  10. data/docs/stats.md +8 -3
  11. data/docs/systemd.md +13 -6
  12. data/ext/puma_http11/extconf.rb +21 -14
  13. data/ext/puma_http11/mini_ssl.c +16 -2
  14. data/ext/puma_http11/org/jruby/puma/Http11.java +31 -8
  15. data/ext/puma_http11/org/jruby/puma/MiniSSL.java +2 -1
  16. data/ext/puma_http11/puma_http11.c +4 -1
  17. data/lib/puma/app/status.rb +1 -1
  18. data/lib/puma/binder.rb +12 -4
  19. data/lib/puma/cli.rb +9 -5
  20. data/lib/puma/client.rb +104 -16
  21. data/lib/puma/cluster/worker.rb +9 -6
  22. data/lib/puma/cluster/worker_handle.rb +4 -5
  23. data/lib/puma/cluster.rb +112 -27
  24. data/lib/puma/configuration.rb +37 -21
  25. data/lib/puma/const.rb +22 -3
  26. data/lib/puma/control_cli.rb +4 -4
  27. data/lib/puma/detect.rb +3 -4
  28. data/lib/puma/dsl.rb +303 -58
  29. data/lib/puma/error_logger.rb +4 -4
  30. data/lib/puma/jruby_restart.rb +0 -16
  31. data/lib/puma/launcher.rb +21 -8
  32. data/lib/puma/log_writer.rb +9 -9
  33. data/lib/puma/minissl/context_builder.rb +3 -0
  34. data/lib/puma/minissl.rb +6 -0
  35. data/lib/puma/null_io.rb +42 -2
  36. data/lib/puma/request.rb +35 -14
  37. data/lib/puma/runner.rb +10 -3
  38. data/lib/puma/sd_notify.rb +1 -4
  39. data/lib/puma/server.rb +53 -21
  40. data/lib/puma/single.rb +1 -1
  41. data/lib/puma/state_file.rb +2 -2
  42. data/lib/puma/thread_pool.rb +14 -2
  43. data/lib/puma/util.rb +1 -1
  44. data/lib/rack/handler/puma.rb +8 -5
  45. data/tools/Dockerfile +5 -3
  46. metadata +10 -12
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e58946300296f4d215a5859fcadb101b4fcec6d9012b38fd0af10c5fdb3ce0c2
4
- data.tar.gz: 397fa109025cbc87d7466be97ed91e44789d522db2c4b89d1ef5f4e40db9f772
3
+ metadata.gz: 574e9afd59afd9a6d5b86bd74cc7e524e73982b61ca294884540cb54324771bf
4
+ data.tar.gz: 4702dc966028a0cb7c7f912ba6cdc33446071e8cd13ea63f14070f247f5d4504
5
5
  SHA512:
6
- metadata.gz: a0c6a4e6c10522de9a9c7d5eed57d5205a6d4acfe18e9d7c310044d5793a2a67a266c3b69f8ed4c5385559149dc858dbcf1b4307c86459b9723ea49303de5685
7
- data.tar.gz: cf7a60331c499a1387414ca2d6955edbc239242a62ea06941bf912714ee4dcb9295a5a1bd9c3561fd396c54a2e04e5a0aa2194ef17b37accb78e049e4cb1ca6b
6
+ metadata.gz: 89dccb7f7cde9cc70904c28cf6026022239eac61fe8c903d924f10e50a59d17876d181feb4c80c7b4315c46d166fdcca7743dca16a3c52e27827f2e2d39a8ec3
7
+ data.tar.gz: c30aa7e48f3b6c191351ebe5c9b407fec7b2523c679bc915c21aefb854b0b43e7b9d776fcc3fdef574da70df71225ae4dbb78ed7045f4b178ae8a8578ae48efd
data/History.md CHANGED
@@ -1,8 +1,126 @@
1
+ ## 6.6.1 / 2025-07-30
2
+
3
+ * Bugfixes
4
+ * Accept `to_path` to be `nil` on request bodies ([#3635])
5
+ * Fix single runner stats before the server start ([#3572])
6
+ * Fix incomplete worker boot state on refork ([#3601])
7
+ * Improve HttpParserError messages for better debugging ([#3586])
8
+ * Fix refork logs to distinguish from phased restarts ([#3598])
9
+ * Fix `rack.after_reply` so it doesn't interrupt chain on error ([#3680])
10
+
11
+ ## 6.6.0 / 2025-01-29
12
+
13
+ * Features
14
+ * Option to turn off SIGUSR2 trapping ([#3570], [#3567])
15
+ * Shorten `ThreadPool` trimmer and reaper thread names ([#3383])
16
+ * Add after_refork hook ([#3386])
17
+ * Add busy threads stat ([#3517])
18
+ * Add a debug log before running each type of hook ([#3375])
19
+ * Allow alternative schemes in Binder ([#3348], [#3302])
20
+ * Avoid spawning `Threadpool#trim` thread if pool size is fixed ([#3384])
21
+
22
+ * Bugfixes
23
+ * Change `HttpParserError` to be subclass of `StandardError` ([#3590], [#3552])
24
+ * added test cases
25
+ * fix update phased restart symlink folder
26
+
27
+ * Performance
28
+ * Only ping worker 0 during phased restart if using fork worker ([#3568])
29
+
30
+ * Refactor
31
+ * Fix multi-delimiter split to get status app token ([#3505])
32
+ * Change ping to use const ([#3595])
33
+ * Fixup use of Puma::Const::PipeRequest constants ([#3565])
34
+ * Update DSL hook processing logic to be consistent ([#3376])
35
+
36
+ ## 6.5.0 / 2024-11-23
37
+
38
+ * Features
39
+ * Print RUBY_DESCRIPTION when Puma starts ([#3407])
40
+ * Set the worker process count automatically when using WEB_CONCURRENCY=auto ([#3439], [#3437])
41
+ * Mark as ractor-safe ([#3486], [#3422])
42
+ * Add option `enable_keep_alive`. `true` mimics existing behavior, but now can use `false` to disable keepalive to reduce queue tail latency ([#3496])
43
+ * Add parameters to Puma methods to allow CI to change ENV in isolation ([#3485])
44
+ * Add `ssl_ciphersuites` option for TLSv1.3 ciphers ([#3359], [#3343])
45
+ * You can now use `--threads 5` or `threads 5` to config max/min threads with a single number (used to need to say `5:5`) ([#3309])
46
+ * Option to turn off systemd plugin ([#3425], [#3424])
47
+ * Add `on_stopped` hook ([#3411], [#3380])
48
+
49
+ * Bugfixes
50
+ * Handle blank environment variables when loading config ([#3539])
51
+ * lib/rack/handler/puma.rb - fix for rackup v1.0.1, adjust Gemfile ([#3532], [#3531])
52
+ * null_io.rb - add `external_encoding`, `set_encoding`, `binmode`, `binmode?` ([#3214])
53
+ * Implement NullIO#seek and #pos to mimic IO ([#3468])
54
+ * add support in rack handler & fix regression in binder for linux abstract namespace sockets ([#3508])
55
+ * Use actual thread local for `Puma::Server.current`. ([#3360])
56
+ * client.rb - fix request chunked body handling ([#3338], [#3337])
57
+ * Properly handle two requests seen in the initial buffer ([#3332])
58
+ * Fix response repeated status line when request is invalid or errors are raised ([#3308], [#3307])
59
+ * Fix child processes not being reaped when `Process.detach` used ([#3314], [#3313])
60
+
61
+ * JRuby
62
+ * Make HTTP length constants configurable ([#3518])
63
+ * Fixup jruby_restart.rb & launcher.rb to work with ARM64 macOS JRuby ([#3467])
64
+
65
+ * Performance
66
+ * Avoid checking if all workers reached timeout unless idle timeout is configured ([#3341])
67
+ * Request body - increase read size to 64 kB ([#3548])
68
+ * single mode skip wait_for_less_busy_worker ([#3325])
69
+
70
+ * Refactor
71
+ * A ton of CI/test improvements by @MSP-Greg, as usual.
72
+ * Add ThreadPool#stats and adjust Server#stats to use it ([#3527])
73
+ * normalize whitespace in worker stats string ([#3513])
74
+ * rack/handler/puma.rb - ssl - use `start_with?`, add test ([#3510])
75
+ * extconf.rb - add logging for OpenSSL versions ([#3370])
76
+ * Lazily require `Puma::Rack::Builder` ([#3340])
77
+ * Refactor: Constantize worker pipe request types ([#3318])
78
+
79
+ * Docs
80
+ * stats.md improvements ([#3514])
81
+ * control_cli.rb: Harmonize help message with bin/puma ([#3434])
82
+ * dsl.rb: Clarify a callback's argument ([#3435])
83
+ * lib/rack/handler/puma.rb - relocate and fixup module comment ([#3495])
84
+
85
+ ## 6.4.3 / 2024-09-19
86
+
87
+ * Security
88
+ * Discards any headers using underscores if the non-underscore version also exists. Without this, an attacker could overwrite values set by intermediate proxies (e.g. X-Forwarded-For). ([CVE-2024-45614](https://github.com/puma/puma/security/advisories/GHSA-9hf4-67fc-4vf4)/GHSA-9hf4-67fc-4vf4)
89
+
90
+ ## 6.4.2 / 2024-01-08
91
+
92
+ * Security
93
+ * Limit the size of chunk extensions. Without this limit, an attacker could cause unbounded resource (CPU, network bandwidth) consumption. ([GHSA-c2f4-cvqm-65w2](https://github.com/puma/puma/security/advisories/GHSA-c2f4-cvqm-65w2))
94
+
95
+ ## 6.4.1 / 2024-01-03
96
+
97
+ * Bugfixes
98
+ * DSL#warn_if_in_single_mode - fixup when workers set via CLI ([#3256])
99
+ * Fix `idle-timeout` not working in cluster mode ([#3235], [#3228], [#3282], [#3283])
100
+ * Fix worker 0 timing out during phased restart ([#3225], [#2786])
101
+ * context_builder.rb - require openssl if verify_mode != 'none' ([#3179])
102
+ * Make puma cluster process suitable as PID 1 ([#3255])
103
+ * Improve Puma::NullIO consistency with real IO ([#3276])
104
+ * extconf.rb - fixup to detect openssl info in Ruby build ([#3271], [#3266])
105
+ * MiniSSL.java - set serialVersionUID, fix RaiseException deprecation ([#3270])
106
+ * dsl.rb - fix warn_if_in_single_mode when WEB_CONCURRENCY is set ([#3265], [#3264])
107
+
108
+ * Maintenance
109
+ * LOTS of test refactoring to make tests more stable and easier to write - thanks to @MSP-Greg!
110
+ * Fix bug in tests re: TestPuma::HOST4 ([#3254])
111
+ * Dockerfile for minimal repros: use Ruby 3.2, expect bundler installed ([#3245])
112
+ * fix define_method calls, use Symbol parameter instead of String ([#3293])
113
+
114
+ * Docs
115
+ * README.md - add the puma-acme plugin ([#3301])
116
+ * Remove `--keep-file-descriptors` flag from systemd docs ([#3248])
117
+ * Note symlink mechanism in restart documentation for hot restart ([#3298])
118
+
1
119
  ## 6.4.0 / 2023-09-21
2
120
 
3
121
  * Features
4
122
  * on_thread_exit hook ([#2920])
5
- * on_thread_start_hook ([#3195])
123
+ * on_thread_start_hook ([#3195])
6
124
  * Shutdown on idle ([#3209], [#2580])
7
125
  * New error message when control server port taken ([#3204])
8
126
 
@@ -12,13 +130,13 @@
12
130
 
13
131
  * Bugfixes
14
132
  * Bring the cert_pem: parameter into parity with the cert: parameter to ssl_bind. ([#3174])
15
- * Fix using control server with IPv6 host ([#3181])
133
+ * Fix using control server with IPv6 host ([#3181])
16
134
  * control_cli.rb - add require_relative 'log_writer' ([#3187])
17
135
  * Fix cases where fallback Rack response wasn't sent to the client ([#3094])
18
-
136
+
19
137
  ## 6.3.1 / 2023-08-18
20
138
 
21
- * Security
139
+ * Security
22
140
  * Address HTTP request smuggling vulnerabilities with zero-length Content Length header and trailer fields ([GHSA-68xg-gqqm-vgj8](https://github.com/puma/puma/security/advisories/GHSA-68xg-gqqm-vgj8))
23
141
 
24
142
  ## 6.3.0 / 2023-05-31
@@ -55,7 +173,7 @@
55
173
 
56
174
  * Features
57
175
  * Ability to supply a custom logger ([#2770], [#2511])
58
- * Warn when clustered-only hooks are defined in single mode ([#3089])
176
+ * Warn when cluster mode-only hooks are defined in single mode ([#3089])
59
177
  * Adds the on_booted event ([#2709])
60
178
 
61
179
  * Bugfixes
@@ -92,12 +210,12 @@
92
210
  * Refactor const.rb - freeze ([#3016])
93
211
 
94
212
  ## 6.0.1 / 2022-12-20
95
-
213
+
96
214
  * Bugfixes
97
215
  * Handle waking up a closed selector in Reactor#add ([#3005])
98
216
  * Fixup response processing, enumerable bodies ([#3004], [#3000])
99
217
  * Correctly close app body for all code paths ([#3002], [#2999])
100
- * Refactor
218
+ * Refactor
101
219
  * Add IOBuffer to Client, remove from ThreadPool thread instances ([#3013])
102
220
 
103
221
  ## 6.0.0 / 2022-10-14
@@ -126,12 +244,12 @@
126
244
  * Allow header values to be arrays (Rack 3) ([#2936], [#2931])
127
245
  * Export Puma/Ruby versions in /stats ([#2875])
128
246
  * Allow configuring request uri max length & request path max length ([#2840])
129
- * Add a couple of public accessors ([#2774])
247
+ * Add a couple of public accessors ([#2774])
130
248
  * Log entire backtrace when worker start fails ([#2891])
131
249
  * [jruby] Enable TLSv1.3 support ([#2886])
132
250
  * [jruby] support setting TLS protocols + rename ssl_cipher_list ([#2899])
133
251
  * [jruby] Support a truststore option ([#2849], [#2904], [#2884])
134
-
252
+
135
253
  * Bugfixes
136
254
  * Load the configuration before passing it to the binder ([#2897])
137
255
  * Do not raise error raised on HTTP methods we don't recognize or support, like CONNECT ([#2932], [#1441])
@@ -144,9 +262,22 @@
144
262
  * Ruby 3.2 will have native IO#wait_* methods, don't require io/wait ([#2903])
145
263
  * Various internal API refactorings ([#2942], [#2921], [#2922], [#2955])
146
264
 
265
+ ## 5.6.9 / 2024-09-19
266
+
267
+ * Security
268
+ * Discards any headers using underscores if the non-underscore version also exists. Without this, an attacker could overwrite values set by intermediate proxies (e.g. X-Forwarded-For). ([CVE-2024-45614](https://github.com/puma/puma/security/advisories/GHSA-9hf4-67fc-4vf4)/GHSA-9hf4-67fc-4vf4)
269
+ * JRuby
270
+ * Must use at least Java >= 9 to compile. You can no longer build from source on Java 8.
271
+
272
+
273
+ ## 5.6.8 / 2024-01-08
274
+
275
+ * Security
276
+ * Limit the size of chunk extensions. Without this limit, an attacker could cause unbounded resource (CPU, network bandwidth) consumption. ([GHSA-c2f4-cvqm-65w2](https://github.com/puma/puma/security/advisories/GHSA-c2f4-cvqm-65w2))
277
+
147
278
  ## 5.6.7 / 2023-08-18
148
279
 
149
- * Security
280
+ * Security
150
281
  * Address HTTP request smuggling vulnerabilities with zero-length Content Length header and trailer fields ([GHSA-68xg-gqqm-vgj8](https://github.com/puma/puma/security/advisories/GHSA-68xg-gqqm-vgj8))
151
282
 
152
283
  ## 5.6.6 / 2023-06-21
@@ -637,7 +768,7 @@ Each patchlevel release contains a separate security fix. We recommend simply up
637
768
  * Fix Java 8 support ([#1773])
638
769
  * Fix error `uninitialized constant Puma::Cluster` ([#1731])
639
770
  * Fix `not_token` being able to be set to true ([#1803])
640
- * Fix "Hang on SIGTERM with ruby 2.6 in clustered mode" (PR [#1741], [#1674], [#1720], [#1730], [#1755])
771
+ * Fix "Hang on SIGTERM with ruby 2.6 in cluster mode" (PR [#1741], [#1674], [#1720], [#1730], [#1755])
641
772
 
642
773
  ## 3.12.1 / 2019-03-19
643
774
 
@@ -1048,7 +1179,7 @@ Each patchlevel release contains a separate security fix. We recommend simply up
1048
1179
  * 4 minor features:
1049
1180
 
1050
1181
  * Listen to unix socket with provided backlog if any
1051
- * Improves the clustered stats to report worker stats
1182
+ * Improves the cluster mode stats to report worker stats
1052
1183
  * Pass the env to the lowlevel_error handler. Fixes [#854]
1053
1184
  * Treat path-like hosts as unix sockets. Fixes [#824]
1054
1185
 
@@ -1775,7 +1906,7 @@ The "clearly I don't have enough tests for the config" release.
1775
1906
 
1776
1907
  * 3 doc changes:
1777
1908
  * Add note about on_worker_boot hook
1778
- * Add some documentation for Clustered mode
1909
+ * Add some documentation for Cluster mode
1779
1910
  * Added quotes to /etc/puma.conf
1780
1911
 
1781
1912
  ## 2.0.1 / 2013-04-30
@@ -2029,6 +2160,92 @@ be added back in a future date when a java Puma::MiniSSL is added.
2029
2160
  * Bugfixes
2030
2161
  * Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
2031
2162
 
2163
+ [#3680]:https://github.com/puma/puma/pull/3680 "PR by @byroot, merged 2025-07-31"
2164
+ [#3572]:https://github.com/puma/puma/pull/3572 "PR by @barthez, merged 2025-02-06"
2165
+ [#3586]:https://github.com/puma/puma/pull/3586 "PR by @MSP-Greg, merged 2025-02-03"
2166
+ [#3598]:https://github.com/puma/puma/pull/3598 "PR by @joshuay03, merged 2025-01-31"
2167
+ [#3601]:https://github.com/puma/puma/pull/3601 "PR by @joshuay03, merged 2025-01-31"
2168
+ [#3635]:https://github.com/puma/puma/pull/3635 "PR by @LevitatingBusinessMan, merged 2025-05-08"
2169
+ [#3570]:https://github.com/puma/puma/pull/3570 "PR by @mohamedhafez, merged 2024-12-30"
2170
+ [#3567]:https://github.com/puma/puma/issues/3567 "Issue by @mohamedhafez, closed 2024-12-30"
2171
+ [#3383]:https://github.com/puma/puma/pull/3383 "PR by @joshuay03, merged 2024-11-29"
2172
+ [#3386]:https://github.com/puma/puma/pull/3386 "PR by @Drakula2k, merged 2024-11-27"
2173
+ [#3517]:https://github.com/puma/puma/pull/3517 "PR by @jjb, merged 2024-11-26"
2174
+ [#3375]:https://github.com/puma/puma/pull/3375 "PR by @joshuay03, merged 2024-11-23"
2175
+ [#3348]:https://github.com/puma/puma/pull/3348 "PR by @tomurb, merged 2024-11-23"
2176
+ [#3302]:https://github.com/puma/puma/issues/3302 "Issue by @benburkert, closed 2024-11-23"
2177
+ [#3384]:https://github.com/puma/puma/pull/3384 "PR by @joshuay03, merged 2024-11-23"
2178
+ [#3590]:https://github.com/puma/puma/pull/3590 "PR by @MSP-Greg, merged 2025-01-01"
2179
+ [#3552]:https://github.com/puma/puma/issues/3552 "Issue by @utay, closed 2025-01-01"
2180
+ [#3568]:https://github.com/puma/puma/pull/3568 "PR by @joshuay03, merged 2024-12-11"
2181
+ [#3505]:https://github.com/puma/puma/pull/3505 "PR by @AnthonyClark, merged 2025-01-27"
2182
+ [#3595]:https://github.com/puma/puma/pull/3595 "PR by @nateberkopec, merged 2025-01-07"
2183
+ [#3565]:https://github.com/puma/puma/pull/3565 "PR by @MSP-Greg, merged 2024-11-28"
2184
+ [#3376]:https://github.com/puma/puma/pull/3376 "PR by @joshuay03, merged 2024-11-23"
2185
+ [#3407]:https://github.com/puma/puma/pull/3407 "PR by @JacobEvelyn, merged 2024-11-05"
2186
+ [#3439]:https://github.com/puma/puma/pull/3439 "PR by @codergeek121, merged 2024-11-04"
2187
+ [#3437]:https://github.com/puma/puma/issues/3437 "Issue by @rafaelfranca, closed 2024-11-04"
2188
+ [#3486]:https://github.com/puma/puma/pull/3486 "PR by @mohamedhafez, merged 2024-09-26"
2189
+ [#3422]:https://github.com/puma/puma/issues/3422 "Issue by @mohamedhafez, closed 2024-09-26"
2190
+ [#3496]:https://github.com/puma/puma/pull/3496 "PR by @slizco, merged 2024-09-26"
2191
+ [#3485]:https://github.com/puma/puma/pull/3485 "PR by @MSP-Greg, merged 2024-09-21"
2192
+ [#3359]:https://github.com/puma/puma/pull/3359 "PR by @willayton, merged 2024-04-11"
2193
+ [#3343]:https://github.com/puma/puma/issues/3343 "Issue by @willayton, closed 2024-04-11"
2194
+ [#3309]:https://github.com/puma/puma/pull/3309 "PR by @byroot, merged 2024-01-09"
2195
+ [#3425]:https://github.com/puma/puma/pull/3425 "PR by @mohamedhafez, merged 2024-07-14"
2196
+ [#3424]:https://github.com/puma/puma/issues/3424 "Issue by @mohamedhafez, closed 2024-07-14"
2197
+ [#3411]:https://github.com/puma/puma/pull/3411 "PR by @OuYangJinTing, merged 2024-06-15"
2198
+ [#3380]:https://github.com/puma/puma/pull/3380 "PR by @emilyst, closed 2024-06-15"
2199
+ [#3539]:https://github.com/puma/puma/pull/3539 "PR by @caius, merged 2024-11-20"
2200
+ [#3532]:https://github.com/puma/puma/pull/3532 "PR by @MSP-Greg, merged 2024-10-24"
2201
+ [#3531]:https://github.com/puma/puma/issues/3531 "Issue by @tagliala, closed 2024-10-24"
2202
+ [#3214]:https://github.com/puma/puma/pull/3214 "PR by @MSP-Greg, merged 2024-10-15"
2203
+ [#3468]:https://github.com/puma/puma/pull/3468 "PR by @foca, merged 2024-10-04"
2204
+ [#3508]:https://github.com/puma/puma/pull/3508 "PR by @MayCXC, merged 2024-10-02"
2205
+ [#3360]:https://github.com/puma/puma/pull/3360 "PR by @ioquatix, merged 2024-04-24"
2206
+ [#3338]:https://github.com/puma/puma/pull/3338 "PR by @MSP-Greg, merged 2024-04-11"
2207
+ [#3337]:https://github.com/puma/puma/issues/3337 "Issue by @skliew, closed 2024-04-11"
2208
+ [#3332]:https://github.com/puma/puma/pull/3332 "PR by @evanphx, merged 2024-02-18"
2209
+ [#3308]:https://github.com/puma/puma/pull/3308 "PR by @MSP-Greg, merged 2024-01-31"
2210
+ [#3307]:https://github.com/puma/puma/issues/3307 "Issue by @nateberkopec, closed 2024-01-31"
2211
+ [#3314]:https://github.com/puma/puma/pull/3314 "PR by @stanhu, merged 2024-01-26"
2212
+ [#3313]:https://github.com/puma/puma/issues/3313 "Issue by @stanhu, closed 2024-01-26"
2213
+ [#3518]:https://github.com/puma/puma/pull/3518 "PR by @roque86, merged 2024-11-15"
2214
+ [#3467]:https://github.com/puma/puma/pull/3467 "PR by @MSP-Greg, merged 2024-09-21"
2215
+ [#3341]:https://github.com/puma/puma/pull/3341 "PR by @joshuay03, merged 2024-03-11"
2216
+ [#3548]:https://github.com/puma/puma/pull/3548 "PR by @MSP-Greg, merged 2024-11-21"
2217
+ [#3325]:https://github.com/puma/puma/pull/3325 "PR by @OuYangJinTing, merged 2024-10-22"
2218
+ [#3527]:https://github.com/puma/puma/pull/3527 "PR by @MSP-Greg, merged 2024-10-26"
2219
+ [#3513]:https://github.com/puma/puma/pull/3513 "PR by @jjb, merged 2024-10-11"
2220
+ [#3510]:https://github.com/puma/puma/pull/3510 "PR by @MSP-Greg, merged 2024-10-03"
2221
+ [#3370]:https://github.com/puma/puma/pull/3370 "PR by @MSP-Greg, merged 2024-04-15"
2222
+ [#3340]:https://github.com/puma/puma/pull/3340 "PR by @joshuay03, merged 2024-03-10"
2223
+ [#3318]:https://github.com/puma/puma/pull/3318 "PR by @joshuay03, merged 2024-01-15"
2224
+ [#3514]:https://github.com/puma/puma/pull/3514 "PR by @jjb, merged 2024-10-11"
2225
+ [#3434]:https://github.com/puma/puma/pull/3434 "PR by @olleolleolle, merged 2024-09-19"
2226
+ [#3435]:https://github.com/puma/puma/pull/3435 "PR by @olleolleolle, merged 2024-09-19"
2227
+ [#3495]:https://github.com/puma/puma/pull/3495 "PR by @MSP-Greg, merged 2024-09-19"
2228
+ [#3256]:https://github.com/puma/puma/pull/3256 "PR by @MSP-Greg, merged 2023-10-16"
2229
+ [#3235]:https://github.com/puma/puma/pull/3235 "PR by @joshuay03, merged 2023-10-03"
2230
+ [#3228]:https://github.com/puma/puma/issues/3228 "Issue by @davidalejandroaguilar, closed 2023-10-03"
2231
+ [#3282]:https://github.com/puma/puma/issues/3282 "Issue by @bensheldon, closed 2024-01-02"
2232
+ [#3283]:https://github.com/puma/puma/pull/3283 "PR by @joshuay03, merged 2024-01-02"
2233
+ [#3225]:https://github.com/puma/puma/pull/3225 "PR by @joshuay03, merged 2023-09-27"
2234
+ [#2786]:https://github.com/puma/puma/issues/2786 "Issue by @vitiokss, closed 2023-09-27"
2235
+ [#3179]:https://github.com/puma/puma/pull/3179 "PR by @MSP-Greg, merged 2023-09-26"
2236
+ [#3255]:https://github.com/puma/puma/pull/3255 "PR by @casperisfine, merged 2023-10-19"
2237
+ [#3276]:https://github.com/puma/puma/pull/3276 "PR by @casperisfine, merged 2023-11-16"
2238
+ [#3271]:https://github.com/puma/puma/pull/3271 "PR by @MSP-Greg, merged 2023-10-30"
2239
+ [#3266]:https://github.com/puma/puma/issues/3266 "Issue by @Dragonicity, closed 2023-10-30"
2240
+ [#3270]:https://github.com/puma/puma/pull/3270 "PR by @MSP-Greg, merged 2023-10-30"
2241
+ [#3265]:https://github.com/puma/puma/pull/3265 "PR by @MSP-Greg, merged 2023-10-25"
2242
+ [#3264]:https://github.com/puma/puma/issues/3264 "Issue by @dentarg, closed 2023-10-25"
2243
+ [#3254]:https://github.com/puma/puma/pull/3254 "PR by @casperisfine, merged 2023-10-11"
2244
+ [#3245]:https://github.com/puma/puma/pull/3245 "PR by @olleolleolle, merged 2023-10-02"
2245
+ [#3293]:https://github.com/puma/puma/pull/3293 "PR by @MSP-Greg, merged 2023-12-21"
2246
+ [#3301]:https://github.com/puma/puma/pull/3301 "PR by @benburkert, merged 2023-12-29"
2247
+ [#3248]:https://github.com/puma/puma/pull/3248 "PR by @dentarg, merged 2023-10-04"
2248
+ [#3298]:https://github.com/puma/puma/pull/3298 "PR by @til, merged 2023-12-26"
2032
2249
  [#2920]:https://github.com/puma/puma/pull/2920 "PR by @biinari, merged 2023-07-11"
2033
2250
  [#3195]:https://github.com/puma/puma/pull/3195 "PR by @binarygit, merged 2023-08-15"
2034
2251
  [#3209]:https://github.com/puma/puma/pull/3209 "PR by @joshuay03, merged 2023-09-04"
@@ -2213,7 +2430,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
2213
2430
  [#2563]:https://github.com/puma/puma/pull/2563 "PR by @MSP-Greg, merged 2021-03-06"
2214
2431
  [#2504]:https://github.com/puma/puma/issues/2504 "Issue by @fsateler, closed 2021-03-06"
2215
2432
  [#2591]:https://github.com/puma/puma/pull/2591 "PR by @MSP-Greg, merged 2021-05-05"
2216
- [#2572]:https://github.com/puma/puma/issues/2572 "Issue by @josefbilendo, closed 2021-05-05"
2433
+ [#2572]:https://github.com/puma/puma/issues/2572 "Issue by @josef-krabath, closed 2021-05-05"
2217
2434
  [#2613]:https://github.com/puma/puma/pull/2613 "PR by @smcgivern, merged 2021-04-27"
2218
2435
  [#2605]:https://github.com/puma/puma/pull/2605 "PR by @pascalbetz, merged 2021-04-26"
2219
2436
  [#2584]:https://github.com/puma/puma/issues/2584 "Issue by @kaorihinata, closed 2021-04-26"
@@ -2529,7 +2746,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
2529
2746
  [#1110]:https://github.com/puma/puma/pull/1110 "PR by @montdidier, merged 2016-12-12"
2530
2747
  [#1135]:https://github.com/puma/puma/pull/1135 "PR by @jkraemer, merged 2016-11-19"
2531
2748
  [#1081]:https://github.com/puma/puma/pull/1081 "PR by @frodsan, merged 2016-09-08"
2532
- [#1138]:https://github.com/puma/puma/pull/1138 "PR by @steakknife, merged 2016-12-13"
2749
+ [#1138]:https://github.com/puma/puma/pull/1138 "PR by @skull-squadron, merged 2016-12-13"
2533
2750
  [#1118]:https://github.com/puma/puma/pull/1118 "PR by @hiroara, merged 2016-11-20"
2534
2751
  [#1075]:https://github.com/puma/puma/issues/1075 "Issue by @pvalena, closed 2016-09-06"
2535
2752
  [#932]:https://github.com/puma/puma/issues/932 "Issue by @everplays, closed 2016-07-24"
@@ -2549,14 +2766,14 @@ be added back in a future date when a java Puma::MiniSSL is added.
2549
2766
  [#782]:https://github.com/puma/puma/issues/782 "Issue by @Tonkpils, closed 2016-07-19"
2550
2767
  [#1010]:https://github.com/puma/puma/issues/1010 "Issue by @mneumark, closed 2016-07-19"
2551
2768
  [#959]:https://github.com/puma/puma/issues/959 "Issue by @mwpastore, closed 2016-04-22"
2552
- [#840]:https://github.com/puma/puma/issues/840 "Issue by @maxkwallace, closed 2016-04-07"
2769
+ [#840]:https://github.com/puma/puma/issues/840 "Issue by @marisawallace, closed 2016-04-07"
2553
2770
  [#1007]:https://github.com/puma/puma/pull/1007 "PR by @willnet, merged 2016-06-24"
2554
2771
  [#1014]:https://github.com/puma/puma/pull/1014 "PR by @szymon-jez, merged 2016-07-11"
2555
2772
  [#1015]:https://github.com/puma/puma/pull/1015 "PR by @bf4, merged 2016-07-19"
2556
2773
  [#1017]:https://github.com/puma/puma/pull/1017 "PR by @jorihardman, merged 2016-07-19"
2557
2774
  [#954]:https://github.com/puma/puma/pull/954 "PR by @jf, merged 2016-04-12"
2558
2775
  [#955]:https://github.com/puma/puma/pull/955 "PR by @jf, merged 2016-04-22"
2559
- [#956]:https://github.com/puma/puma/pull/956 "PR by @maxkwallace, merged 2016-04-12"
2776
+ [#956]:https://github.com/puma/puma/pull/956 "PR by @marisawallace, merged 2016-04-12"
2560
2777
  [#960]:https://github.com/puma/puma/pull/960 "PR by @kmayer, merged 2016-04-15"
2561
2778
  [#969]:https://github.com/puma/puma/pull/969 "PR by @frankwong15, merged 2016-05-10"
2562
2779
  [#970]:https://github.com/puma/puma/pull/970 "PR by @willnet, merged 2016-04-26"
@@ -2617,7 +2834,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
2617
2834
  [#845]:https://github.com/puma/puma/pull/845 "PR by @deepj, merged 2016-01-28"
2618
2835
  [#846]:https://github.com/puma/puma/pull/846 "PR by @sriedel, merged 2016-01-15"
2619
2836
  [#850]:https://github.com/puma/puma/pull/850 "PR by @deepj, merged 2016-01-15"
2620
- [#853]:https://github.com/puma/puma/pull/853 "PR by @Jeffrey6052, merged 2016-01-28"
2837
+ [#853]:https://github.com/puma/puma/pull/853 "PR by @xuqiyong666, merged 2016-01-28"
2621
2838
  [#857]:https://github.com/puma/puma/pull/857 "PR by @osheroff, merged 2016-01-15"
2622
2839
  [#858]:https://github.com/puma/puma/pull/858 "PR by @mlarraz, merged 2016-01-28"
2623
2840
  [#860]:https://github.com/puma/puma/pull/860 "PR by @osheroff, merged 2016-01-15"
data/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  # Puma: A Ruby Web Server Built For Parallelism
6
6
 
7
- [![Actions](https://github.com/puma/puma/workflows/Tests/badge.svg?branch=master)](https://github.com/puma/puma/actions?query=workflow%3ATests)
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
8
  [![Code Climate](https://codeclimate.com/github/puma/puma.svg)](https://codeclimate.com/github/puma/puma)
9
9
  [![StackOverflow](https://img.shields.io/badge/stackoverflow-Puma-blue.svg)]( https://stackoverflow.com/questions/tagged/puma )
10
10
 
@@ -12,7 +12,7 @@ Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server fo
12
12
 
13
13
  ## Built For Speed &amp; Parallelism
14
14
 
15
- Puma is a server for [Rack](https://github.com/rack/rack)-powered HTTP applications written in Ruby. It is:
15
+ Puma is a server for [Rack](https://github.com/rack/rack)-powered HTTP applications written in Ruby. It is:
16
16
  * **Multi-threaded**. Each request is served in a separate thread. This helps you serve more requests per second with less memory use.
17
17
  * **Multi-process**. "Pre-forks" in cluster mode, using less memory per-process thanks to copy-on-write memory.
18
18
  * **Standalone**. With SSL support, zero-downtime rolling restarts and a built-in request bufferer, you can deploy Puma without any reverse proxy.
@@ -102,9 +102,9 @@ Puma will automatically scale the number of threads, from the minimum until it c
102
102
 
103
103
  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.
104
104
 
105
- ### Clustered mode
105
+ ### Cluster mode
106
106
 
107
- 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:
107
+ 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:
108
108
 
109
109
  ```
110
110
  $ puma -t 8:32 -w 3
@@ -116,11 +116,13 @@ Or with the `WEB_CONCURRENCY` environment variable:
116
116
  $ WEB_CONCURRENCY=3 puma -t 8:32
117
117
  ```
118
118
 
119
- 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.
119
+ 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
+
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).
120
122
 
121
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).
122
124
 
123
- 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).
125
+ 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).
124
126
 
125
127
  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:
126
128
 
@@ -138,51 +140,101 @@ preload_app!
138
140
 
139
141
  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.
140
142
 
141
- When using clustered mode, you can specify a block in your configuration file that will be run on boot of each worker:
143
+ #### Cluster mode hooks
144
+
145
+ When using cluster mode, Puma's configuration DSL provides `before_fork` and `on_worker_boot`
146
+ hooks to run code when the master process forks and child workers are booted respectively.
147
+
148
+ It is recommended to use these hooks with `preload_app!`, otherwise constants loaded by your
149
+ application (such as `Rails`) will not be available inside the hooks.
142
150
 
143
151
  ```ruby
144
152
  # config/puma.rb
153
+ before_fork do
154
+ # Add code to run inside the Puma master process before it forks a worker child.
155
+ end
156
+
145
157
  on_worker_boot do
146
- # configuration here
158
+ # Add code to run inside the Puma worker process after forking.
147
159
  end
148
160
  ```
149
161
 
150
- This code can be used to setup the process before booting the application, allowing
151
- you to do some Puma-specific things that you don't want to embed in your application.
152
- For instance, you could fire a log notification that a worker booted or send something to statsd. This can be called multiple times.
162
+ In addition, there is an `on_refork` and `after_refork` hooks which are used only in [`fork_worker` mode](docs/fork_worker.md),
163
+ when the worker 0 child process forks a grandchild worker:
153
164
 
154
- Constants loaded by your application (such as `Rails`) will not be available in `on_worker_boot`
155
- unless preloading is enabled.
156
-
157
- You can also specify a block to be run before workers are forked, using `before_fork`:
165
+ ```ruby
166
+ on_refork do
167
+ # Used only when fork_worker mode is enabled. Add code to run inside the Puma worker 0
168
+ # child process before it forks a grandchild worker.
169
+ end
170
+ ```
158
171
 
159
172
  ```ruby
160
- # config/puma.rb
161
- before_fork do
162
- # configuration here
173
+ after_refork do
174
+ # Used only when fork_worker mode is enabled. Add code to run inside the Puma worker 0
175
+ # child process after it forks a grandchild worker.
163
176
  end
164
177
  ```
165
178
 
166
- You can also specify a block to be run after puma is booted using `on_booted`:
179
+ Importantly, note the following considerations when Ruby forks a child process:
180
+
181
+ 1. File descriptors such as network sockets **are** copied from the parent to the forked
182
+ child process. Dual-use of the same sockets by parent and child will result in I/O conflicts
183
+ such as `SocketError`, `Errno::EPIPE`, and `EOFError`.
184
+ 2. Background Ruby threads, including threads used by various third-party gems for connection
185
+ monitoring, etc., are **not** copied to the child process. Often this does not cause
186
+ immediate problems until a third-party connection goes down, at which point there will
187
+ be no supervisor to reconnect it.
188
+
189
+ Therefore, we recommend the following:
190
+
191
+ 1. If possible, do not establish any socket connections (HTTP, database connections, etc.)
192
+ inside Puma's master process when booting.
193
+ 2. If (1) is not possible, use `before_fork` and `on_refork` to disconnect the parent's socket
194
+ connections when forking, so that they are not accidentally copied to the child process.
195
+ 3. Use `on_worker_boot` to restart any background threads on the forked child.
196
+ 4. Use `after_refork` to restart any background threads on the parent.
197
+
198
+ #### Master process lifecycle hooks
199
+
200
+ Puma's configuration DSL provides master process lifecycle hooks `on_booted`, `on_restart`, and `on_stopped`
201
+ which may be used to specify code blocks to run on each event:
167
202
 
168
203
  ```ruby
169
204
  # config/puma.rb
170
205
  on_booted do
171
- # configuration here
206
+ # Add code to run in the Puma master process after it boots,
207
+ # and also after a phased restart completes.
208
+ end
209
+
210
+ on_restart do
211
+ # Add code to run in the Puma master process when it receives
212
+ # a restart command but before it restarts.
213
+ end
214
+
215
+ on_stopped do
216
+ # Add code to run in the Puma master process when it receives
217
+ # a stop command but before it shuts down.
172
218
  end
173
219
  ```
174
220
 
175
221
  ### Error handling
176
222
 
177
- If puma encounters an error outside of the context of your application, it will respond with a 500 and a simple
223
+ If Puma encounters an error outside of the context of your application, it will respond with a 400/500 and a simple
178
224
  textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/master/lib/puma/server.rb)).
179
225
  You can specify custom behavior for this scenario. For example, you can report the error to your third-party
180
226
  error-tracking service (in this example, [rollbar](https://rollbar.com)):
181
227
 
182
228
  ```ruby
183
- lowlevel_error_handler do |e|
184
- Rollbar.critical(e)
185
- [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"]]
229
+ lowlevel_error_handler do |e, env, status|
230
+ if status == 400
231
+ 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"
232
+ else
233
+ 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"
234
+ Rollbar.critical(e)
235
+ end
236
+
237
+ [status, {}, [message]]
186
238
  end
187
239
  ```
188
240
 
@@ -249,7 +301,7 @@ $ puma -b ssl://localhost:9292 -b tcp://localhost:9393 -C config/use_local_host.
249
301
 
250
302
  #### Controlling SSL Cipher Suites
251
303
 
252
- To use or avoid specific SSL cipher suites, use `ssl_cipher_filter` or `ssl_cipher_list` options.
304
+ To use or avoid specific SSL ciphers for TLSv1.2 and below, use `ssl_cipher_filter` or `ssl_cipher_list` options.
253
305
 
254
306
  ##### Ruby:
255
307
 
@@ -263,6 +315,14 @@ $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&ssl_cipher_fil
263
315
  $ 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'
264
316
  ```
265
317
 
318
+ To configure the available TLSv1.3 ciphersuites, use `ssl_ciphersuites` option (not available for JRuby).
319
+
320
+ ##### Ruby:
321
+
322
+ ```
323
+ $ 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'
324
+ ```
325
+
266
326
  See https://www.openssl.org/docs/man1.1.1/man1/ciphers.html for cipher filter format and full list of cipher suites.
267
327
 
268
328
  Disable TLS v1 with the `no_tlsv1` option:
@@ -279,7 +339,7 @@ To enable verification flags offered by OpenSSL, use `verification_flags` (not a
279
339
  $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&verification_flags=PARTIAL_CHAIN'
280
340
  ```
281
341
 
282
- You can also set multiple verification flags (by separating them with coma):
342
+ You can also set multiple verification flags (by separating them with a comma):
283
343
 
284
344
  ```
285
345
  $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&verification_flags=PARTIAL_CHAIN,CRL_CHECK'
@@ -410,6 +470,7 @@ Community guides:
410
470
  * [puma-plugin-statsd](https://github.com/yob/puma-plugin-statsd) — send Puma metrics to statsd
411
471
  * [puma-plugin-systemd](https://github.com/sj26/puma-plugin-systemd) — deeper integration with systemd for notify, status and watchdog. Puma 5.1.0 integrated notify and watchdog, which probably conflicts with this plugin. Puma 6.1.0 added status support which obsoletes the plugin entirely.
412
472
  * [puma-plugin-telemetry](https://github.com/babbel/puma-plugin-telemetry) - telemetry plugin for Puma offering various targets to publish
473
+ * [puma-acme](https://github.com/anchordotdev/puma-acme) - automatic SSL/HTTPS certificate provisioning and setup
413
474
 
414
475
  ### Monitoring
415
476
 
data/docs/fork_worker.md CHANGED
@@ -22,10 +22,20 @@ The `fork_worker` option allows your application to be initialized only once for
22
22
 
23
23
  You can trigger a refork by sending the cluster the `SIGURG` signal or running the `pumactl refork` command at any time. A refork will also automatically trigger once, after a certain number of requests have been processed by worker 0 (default 1000). To configure the number of requests before the auto-refork, pass a positive integer argument to `fork_worker` (e.g., `fork_worker 1000`), or `0` to disable.
24
24
 
25
+ ### Usage Considerations
26
+
27
+ - `fork_worker` introduces new `on_refork` and `after_refork` configuration hooks. Note the following:
28
+ - When initially forking the parent process to the worker 0 child, `before_fork` will trigger on the parent process and `on_worker_boot` will trigger on the worker 0 child as normal.
29
+ - When forking the worker 0 child to grandchild workers, `on_refork` and `after_refork` will trigger on the worker 0 child, and `on_worker_boot` will trigger on each grandchild worker.
30
+ - For clarity, `before_fork` does not trigger on worker 0, and `after_refork` does not trigger on the grandchild.
31
+ - As a general migration guide:
32
+ - Copy any logic within your existing `before_fork` hook to the `on_refork` hook.
33
+ - Consider to copy logic from your `on_worker_boot` hook to the `after_refork` hook, if it is needed to reset the state of worker 0 after it forks.
34
+
25
35
  ### Limitations
26
36
 
27
37
  - This mode is still very experimental so there may be bugs or edge-cases, particularly around expected behavior of existing hooks. Please open a [bug report](https://github.com/puma/puma/issues/new?template=bug_report.md) if you encounter any issues.
28
38
 
29
39
  - In order to fork new workers cleanly, worker 0 shuts down its server and stops serving requests so there are no open file descriptors or other kinds of shared global state between processes, and to maximize copy-on-write efficiency across the newly-forked workers. This may temporarily reduce total capacity of the cluster during a phased restart / refork.
30
40
 
31
- In a cluster with `n` workers, a normal phased restart stops and restarts workers one by one while the application is loaded in each process, so `n-1` workers are available serving requests during the restart. In a phased restart in fork-worker mode, the application is first loaded in worker 0 while `n-1` workers are available, then worker 0 remains stopped while the rest of the workers are reloaded one by one, leaving only `n-2` workers to be available for a brief period of time. Reloading the rest of the workers should be quick because the application is preloaded at that point, but there may be situations where it can take longer (slow clients, long-running application code, slow worker-fork hooks, etc).
41
+ - In a cluster with `n` workers, a normal phased restart stops and restarts workers one by one while the application is loaded in each process, so `n-1` workers are available serving requests during the restart. In a phased restart in fork-worker mode, the application is first loaded in worker 0 while `n-1` workers are available, then worker 0 remains stopped while the rest of the workers are reloaded one by one, leaving only `n-2` workers to be available for a brief period of time. Reloading the rest of the workers should be quick because the application is preloaded at that point, but there may be situations where it can take longer (slow clients, long-running application code, slow worker-fork hooks, etc).