puma 6.4.3 → 6.6.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (39) hide show
  1. checksums.yaml +4 -4
  2. data/History.md +139 -3
  3. data/README.md +81 -21
  4. data/docs/fork_worker.md +11 -1
  5. data/docs/java_options.md +54 -0
  6. data/docs/plugins.md +4 -0
  7. data/docs/signals.md +2 -2
  8. data/docs/stats.md +8 -3
  9. data/docs/systemd.md +10 -1
  10. data/ext/puma_http11/extconf.rb +19 -16
  11. data/ext/puma_http11/mini_ssl.c +11 -1
  12. data/ext/puma_http11/org/jruby/puma/Http11.java +28 -7
  13. data/ext/puma_http11/puma_http11.c +4 -1
  14. data/lib/puma/app/status.rb +1 -1
  15. data/lib/puma/binder.rb +12 -4
  16. data/lib/puma/cli.rb +9 -5
  17. data/lib/puma/client.rb +35 -12
  18. data/lib/puma/cluster/worker.rb +9 -6
  19. data/lib/puma/cluster/worker_handle.rb +4 -5
  20. data/lib/puma/cluster.rb +31 -19
  21. data/lib/puma/configuration.rb +36 -18
  22. data/lib/puma/const.rb +14 -3
  23. data/lib/puma/control_cli.rb +4 -4
  24. data/lib/puma/dsl.rb +282 -43
  25. data/lib/puma/error_logger.rb +4 -4
  26. data/lib/puma/jruby_restart.rb +0 -16
  27. data/lib/puma/launcher.rb +21 -8
  28. data/lib/puma/log_writer.rb +9 -9
  29. data/lib/puma/minissl/context_builder.rb +1 -0
  30. data/lib/puma/minissl.rb +1 -0
  31. data/lib/puma/null_io.rb +26 -0
  32. data/lib/puma/request.rb +7 -3
  33. data/lib/puma/runner.rb +9 -2
  34. data/lib/puma/sd_notify.rb +1 -4
  35. data/lib/puma/server.rb +33 -22
  36. data/lib/puma/thread_pool.rb +14 -2
  37. data/lib/puma/util.rb +1 -1
  38. data/lib/rack/handler/puma.rb +8 -5
  39. metadata +10 -12
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: e3cedcd91a2366db019124505992d71ff47717760e4c3f37d9e7ae681c45bbdb
4
- data.tar.gz: 6ad4999caa3542103c8bb2d3a1bd49202e1c8cf71d409ee96e13d23c169f0d32
3
+ metadata.gz: 94e6b5d56525a92e2e279d59467572a254c7c03b9dc14a3e91ec5eba67b54620
4
+ data.tar.gz: 55e78ab10a5d222cce09dc89a92fbbd15d8e8ae7abbec95ca309e2903f68bd97
5
5
  SHA512:
6
- metadata.gz: a69d8cec268d2e35444609f2e69e737e47eb1dc30dd2b3a387e5f3e84bc4905d8241ae3b158f39259a9930ca093fff17db927039aaef54583e6c1a30d8b12a61
7
- data.tar.gz: f03e924b53e70ac876c786031b23775e4b91aa5d009d5f40fb9a0c241093a238c4b78a99fc062c8495e634b2cfc8561626e9aaf0888c203d40cf84f9d14c539b
6
+ metadata.gz: 750f9ec059b9710eb5ae739dc04ad600fff8386a40dc3ef83500189caacf8b7413d01eb60d751befd1aa077f3565e60617d13ceba8b9a0c29912abf410b700ff
7
+ data.tar.gz: 1a56b1696333ae86e643bd045ebe83f6a1700ac5df948113a443326e867ce17bf3f4b7e05e01cda6b99605130a2b77ccf49d2ae153ad2e879971c7238d652548
data/History.md CHANGED
@@ -1,3 +1,77 @@
1
+ ## 6.6.0 / 2025-01-29
2
+
3
+ * Features
4
+ * Option to turn off SIGUSR2 trapping ([#3570], [#3567])
5
+ * Shorten `ThreadPool` trimmer and reaper thread names ([#3383])
6
+ * Add after_refork hook ([#3386])
7
+ * Add busy threads stat ([#3517])
8
+ * Add a debug log before running each type of hook ([#3375])
9
+ * Allow alternative schemes in Binder ([#3348], [#3302])
10
+ * Avoid spawning `Threadpool#trim` thread if pool size is fixed ([#3384])
11
+
12
+ * Bugfixes
13
+ * Change `HttpParserError` to be subclass of `StandardError` ([#3590], [#3552])
14
+ * added test cases
15
+ * fix update phased restart symlink folder
16
+
17
+ * Performance
18
+ * Only ping worker 0 during phased restart if using fork worker ([#3568])
19
+
20
+ * Refactor
21
+ * Fix multi-delimiter split to get status app token ([#3505])
22
+ * Change ping to use const ([#3595])
23
+ * Fixup use of Puma::Const::PipeRequest constants ([#3565])
24
+ * Update DSL hook processing logic to be consistent ([#3376])
25
+
26
+ ## 6.5.0 / 2024-11-23
27
+
28
+ * Features
29
+ * Print RUBY_DESCRIPTION when Puma starts ([#3407])
30
+ * Set the worker process count automatically when using WEB_CONCURRENCY=auto ([#3439], [#3437])
31
+ * Mark as ractor-safe ([#3486], [#3422])
32
+ * Add option `enable_keep_alive`. `true` mimics existing behavior, but now can use `false` to disable keepalive to reduce queue tail latency ([#3496])
33
+ * Add parameters to Puma methods to allow CI to change ENV in isolation ([#3485])
34
+ * Add `ssl_ciphersuites` option for TLSv1.3 ciphers ([#3359], [#3343])
35
+ * 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])
36
+ * Option to turn off systemd plugin ([#3425], [#3424])
37
+ * Add `on_stopped` hook ([#3411], [#3380])
38
+
39
+ * Bugfixes
40
+ * Handle blank environment variables when loading config ([#3539])
41
+ * lib/rack/handler/puma.rb - fix for rackup v1.0.1, adjust Gemfile ([#3532], [#3531])
42
+ * null_io.rb - add `external_encoding`, `set_encoding`, `binmode`, `binmode?` ([#3214])
43
+ * Implement NullIO#seek and #pos to mimic IO ([#3468])
44
+ * add support in rack handler & fix regression in binder for linux abstract namespace sockets ([#3508])
45
+ * Use actual thread local for `Puma::Server.current`. ([#3360])
46
+ * client.rb - fix request chunked body handling ([#3338], [#3337])
47
+ * Properly handle two requests seen in the initial buffer ([#3332])
48
+ * Fix response repeated status line when request is invalid or errors are raised ([#3308], [#3307])
49
+ * Fix child processes not being reaped when `Process.detach` used ([#3314], [#3313])
50
+
51
+ * JRuby
52
+ * Make HTTP length constants configurable ([#3518])
53
+ * Fixup jruby_restart.rb & launcher.rb to work with ARM64 macOS JRuby ([#3467])
54
+
55
+ * Performance
56
+ * Avoid checking if all workers reached timeout unless idle timeout is configured ([#3341])
57
+ * Request body - increase read size to 64 kB ([#3548])
58
+ * single mode skip wait_for_less_busy_worker ([#3325])
59
+
60
+ * Refactor
61
+ * A ton of CI/test improvements by @MSP-Greg, as usual.
62
+ * Add ThreadPool#stats and adjust Server#stats to use it ([#3527])
63
+ * normalize whitespace in worker stats string ([#3513])
64
+ * rack/handler/puma.rb - ssl - use `start_with?`, add test ([#3510])
65
+ * extconf.rb - add logging for OpenSSL versions ([#3370])
66
+ * Lazily require `Puma::Rack::Builder` ([#3340])
67
+ * Refactor: Constantize worker pipe request types ([#3318])
68
+
69
+ * Docs
70
+ * stats.md improvements ([#3514])
71
+ * control_cli.rb: Harmonize help message with bin/puma ([#3434])
72
+ * dsl.rb: Clarify a callback's argument ([#3435])
73
+ * lib/rack/handler/puma.rb - relocate and fixup module comment ([#3495])
74
+
1
75
  ## 6.4.3 / 2024-09-19
2
76
 
3
77
  * Security
@@ -182,6 +256,9 @@
182
256
 
183
257
  * Security
184
258
  * 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)
259
+ * JRuby
260
+ * Must use at least Java >= 9 to compile. You can no longer build from source on Java 8.
261
+
185
262
 
186
263
  ## 5.6.8 / 2024-01-08
187
264
 
@@ -2073,6 +2150,65 @@ be added back in a future date when a java Puma::MiniSSL is added.
2073
2150
  * Bugfixes
2074
2151
  * Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
2075
2152
 
2153
+ [#3570]:https://github.com/puma/puma/pull/3570 "PR by @mohamedhafez, merged 2024-12-30"
2154
+ [#3567]:https://github.com/puma/puma/issues/3567 "Issue by @mohamedhafez, closed 2024-12-30"
2155
+ [#3383]:https://github.com/puma/puma/pull/3383 "PR by @joshuay03, merged 2024-11-29"
2156
+ [#3386]:https://github.com/puma/puma/pull/3386 "PR by @Drakula2k, merged 2024-11-27"
2157
+ [#3517]:https://github.com/puma/puma/pull/3517 "PR by @jjb, merged 2024-11-26"
2158
+ [#3375]:https://github.com/puma/puma/pull/3375 "PR by @joshuay03, merged 2024-11-23"
2159
+ [#3348]:https://github.com/puma/puma/pull/3348 "PR by @tomurb, merged 2024-11-23"
2160
+ [#3302]:https://github.com/puma/puma/issues/3302 "Issue by @benburkert, closed 2024-11-23"
2161
+ [#3384]:https://github.com/puma/puma/pull/3384 "PR by @joshuay03, merged 2024-11-23"
2162
+ [#3590]:https://github.com/puma/puma/pull/3590 "PR by @MSP-Greg, merged 2025-01-01"
2163
+ [#3552]:https://github.com/puma/puma/issues/3552 "Issue by @utay, closed 2025-01-01"
2164
+ [#3568]:https://github.com/puma/puma/pull/3568 "PR by @joshuay03, merged 2024-12-11"
2165
+ [#3505]:https://github.com/puma/puma/pull/3505 "PR by @AnthonyClark, merged 2025-01-27"
2166
+ [#3595]:https://github.com/puma/puma/pull/3595 "PR by @nateberkopec, merged 2025-01-07"
2167
+ [#3565]:https://github.com/puma/puma/pull/3565 "PR by @MSP-Greg, merged 2024-11-28"
2168
+ [#3376]:https://github.com/puma/puma/pull/3376 "PR by @joshuay03, merged 2024-11-23"
2169
+ [#3407]:https://github.com/puma/puma/pull/3407 "PR by @JacobEvelyn, merged 2024-11-05"
2170
+ [#3439]:https://github.com/puma/puma/pull/3439 "PR by @codergeek121, merged 2024-11-04"
2171
+ [#3437]:https://github.com/puma/puma/issues/3437 "Issue by @rafaelfranca, closed 2024-11-04"
2172
+ [#3486]:https://github.com/puma/puma/pull/3486 "PR by @mohamedhafez, merged 2024-09-26"
2173
+ [#3422]:https://github.com/puma/puma/issues/3422 "Issue by @mohamedhafez, closed 2024-09-26"
2174
+ [#3496]:https://github.com/puma/puma/pull/3496 "PR by @slizco, merged 2024-09-26"
2175
+ [#3485]:https://github.com/puma/puma/pull/3485 "PR by @MSP-Greg, merged 2024-09-21"
2176
+ [#3359]:https://github.com/puma/puma/pull/3359 "PR by @willayton, merged 2024-04-11"
2177
+ [#3343]:https://github.com/puma/puma/issues/3343 "Issue by @willayton, closed 2024-04-11"
2178
+ [#3309]:https://github.com/puma/puma/pull/3309 "PR by @byroot, merged 2024-01-09"
2179
+ [#3425]:https://github.com/puma/puma/pull/3425 "PR by @mohamedhafez, merged 2024-07-14"
2180
+ [#3424]:https://github.com/puma/puma/issues/3424 "Issue by @mohamedhafez, closed 2024-07-14"
2181
+ [#3411]:https://github.com/puma/puma/pull/3411 "PR by @OuYangJinTing, merged 2024-06-15"
2182
+ [#3380]:https://github.com/puma/puma/pull/3380 "PR by @emilyst, closed 2024-06-15"
2183
+ [#3539]:https://github.com/puma/puma/pull/3539 "PR by @caius, merged 2024-11-20"
2184
+ [#3532]:https://github.com/puma/puma/pull/3532 "PR by @MSP-Greg, merged 2024-10-24"
2185
+ [#3531]:https://github.com/puma/puma/issues/3531 "Issue by @tagliala, closed 2024-10-24"
2186
+ [#3214]:https://github.com/puma/puma/pull/3214 "PR by @MSP-Greg, merged 2024-10-15"
2187
+ [#3468]:https://github.com/puma/puma/pull/3468 "PR by @foca, merged 2024-10-04"
2188
+ [#3508]:https://github.com/puma/puma/pull/3508 "PR by @MayCXC, merged 2024-10-02"
2189
+ [#3360]:https://github.com/puma/puma/pull/3360 "PR by @ioquatix, merged 2024-04-24"
2190
+ [#3338]:https://github.com/puma/puma/pull/3338 "PR by @MSP-Greg, merged 2024-04-11"
2191
+ [#3337]:https://github.com/puma/puma/issues/3337 "Issue by @skliew, closed 2024-04-11"
2192
+ [#3332]:https://github.com/puma/puma/pull/3332 "PR by @evanphx, merged 2024-02-18"
2193
+ [#3308]:https://github.com/puma/puma/pull/3308 "PR by @MSP-Greg, merged 2024-01-31"
2194
+ [#3307]:https://github.com/puma/puma/issues/3307 "Issue by @nateberkopec, closed 2024-01-31"
2195
+ [#3314]:https://github.com/puma/puma/pull/3314 "PR by @stanhu, merged 2024-01-26"
2196
+ [#3313]:https://github.com/puma/puma/issues/3313 "Issue by @stanhu, closed 2024-01-26"
2197
+ [#3518]:https://github.com/puma/puma/pull/3518 "PR by @roque86, merged 2024-11-15"
2198
+ [#3467]:https://github.com/puma/puma/pull/3467 "PR by @MSP-Greg, merged 2024-09-21"
2199
+ [#3341]:https://github.com/puma/puma/pull/3341 "PR by @joshuay03, merged 2024-03-11"
2200
+ [#3548]:https://github.com/puma/puma/pull/3548 "PR by @MSP-Greg, merged 2024-11-21"
2201
+ [#3325]:https://github.com/puma/puma/pull/3325 "PR by @OuYangJinTing, merged 2024-10-22"
2202
+ [#3527]:https://github.com/puma/puma/pull/3527 "PR by @MSP-Greg, merged 2024-10-26"
2203
+ [#3513]:https://github.com/puma/puma/pull/3513 "PR by @jjb, merged 2024-10-11"
2204
+ [#3510]:https://github.com/puma/puma/pull/3510 "PR by @MSP-Greg, merged 2024-10-03"
2205
+ [#3370]:https://github.com/puma/puma/pull/3370 "PR by @MSP-Greg, merged 2024-04-15"
2206
+ [#3340]:https://github.com/puma/puma/pull/3340 "PR by @joshuay03, merged 2024-03-10"
2207
+ [#3318]:https://github.com/puma/puma/pull/3318 "PR by @joshuay03, merged 2024-01-15"
2208
+ [#3514]:https://github.com/puma/puma/pull/3514 "PR by @jjb, merged 2024-10-11"
2209
+ [#3434]:https://github.com/puma/puma/pull/3434 "PR by @olleolleolle, merged 2024-09-19"
2210
+ [#3435]:https://github.com/puma/puma/pull/3435 "PR by @olleolleolle, merged 2024-09-19"
2211
+ [#3495]:https://github.com/puma/puma/pull/3495 "PR by @MSP-Greg, merged 2024-09-19"
2076
2212
  [#3256]:https://github.com/puma/puma/pull/3256 "PR by @MSP-Greg, merged 2023-10-16"
2077
2213
  [#3235]:https://github.com/puma/puma/pull/3235 "PR by @joshuay03, merged 2023-10-03"
2078
2214
  [#3228]:https://github.com/puma/puma/issues/3228 "Issue by @davidalejandroaguilar, closed 2023-10-03"
@@ -2614,14 +2750,14 @@ be added back in a future date when a java Puma::MiniSSL is added.
2614
2750
  [#782]:https://github.com/puma/puma/issues/782 "Issue by @Tonkpils, closed 2016-07-19"
2615
2751
  [#1010]:https://github.com/puma/puma/issues/1010 "Issue by @mneumark, closed 2016-07-19"
2616
2752
  [#959]:https://github.com/puma/puma/issues/959 "Issue by @mwpastore, closed 2016-04-22"
2617
- [#840]:https://github.com/puma/puma/issues/840 "Issue by @maxkwallace, closed 2016-04-07"
2753
+ [#840]:https://github.com/puma/puma/issues/840 "Issue by @marisawallace, closed 2016-04-07"
2618
2754
  [#1007]:https://github.com/puma/puma/pull/1007 "PR by @willnet, merged 2016-06-24"
2619
2755
  [#1014]:https://github.com/puma/puma/pull/1014 "PR by @szymon-jez, merged 2016-07-11"
2620
2756
  [#1015]:https://github.com/puma/puma/pull/1015 "PR by @bf4, merged 2016-07-19"
2621
2757
  [#1017]:https://github.com/puma/puma/pull/1017 "PR by @jorihardman, merged 2016-07-19"
2622
2758
  [#954]:https://github.com/puma/puma/pull/954 "PR by @jf, merged 2016-04-12"
2623
2759
  [#955]:https://github.com/puma/puma/pull/955 "PR by @jf, merged 2016-04-22"
2624
- [#956]:https://github.com/puma/puma/pull/956 "PR by @maxkwallace, merged 2016-04-12"
2760
+ [#956]:https://github.com/puma/puma/pull/956 "PR by @marisawallace, merged 2016-04-12"
2625
2761
  [#960]:https://github.com/puma/puma/pull/960 "PR by @kmayer, merged 2016-04-15"
2626
2762
  [#969]:https://github.com/puma/puma/pull/969 "PR by @frankwong15, merged 2016-05-10"
2627
2763
  [#970]:https://github.com/puma/puma/pull/970 "PR by @willnet, merged 2016-04-26"
@@ -2682,7 +2818,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
2682
2818
  [#845]:https://github.com/puma/puma/pull/845 "PR by @deepj, merged 2016-01-28"
2683
2819
  [#846]:https://github.com/puma/puma/pull/846 "PR by @sriedel, merged 2016-01-15"
2684
2820
  [#850]:https://github.com/puma/puma/pull/850 "PR by @deepj, merged 2016-01-15"
2685
- [#853]:https://github.com/puma/puma/pull/853 "PR by @Jeffrey6052, merged 2016-01-28"
2821
+ [#853]:https://github.com/puma/puma/pull/853 "PR by @xuqiyong666, merged 2016-01-28"
2686
2822
  [#857]:https://github.com/puma/puma/pull/857 "PR by @osheroff, merged 2016-01-15"
2687
2823
  [#858]:https://github.com/puma/puma/pull/858 "PR by @mlarraz, merged 2016-01-28"
2688
2824
  [#860]:https://github.com/puma/puma/pull/860 "PR by @osheroff, merged 2016-01-15"
data/README.md CHANGED
@@ -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.
@@ -118,6 +118,8 @@ $ WEB_CONCURRENCY=3 puma -t 8:32
118
118
 
119
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.
120
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).
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
125
  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).
@@ -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
+ #### Clustered mode hooks
144
+
145
+ When using clustered 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'
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).
data/docs/java_options.md ADDED
@@ -0,0 +1,54 @@
1
+ # Java Options
2
+
3
+ `System Properties` or `Environment Variables` can be used to change Puma's
4
+ default configuration for its Java extension. The provided values are evaluated
5
+ during initialization, and changes while running the app have no effect.
6
+ Moreover, default values may be used in case of invalid inputs.
7
+
8
+ ## Supported Options
9
+
10
+ | ENV Name | Default Value | Validation |
11
+ |------------------------------|:-------------:|:------------------------:|
12
+ | PUMA_QUERY_STRING_MAX_LENGTH | 1024 * 10 | Positive natural number |
13
+ | PUMA_REQUEST_PATH_MAX_LENGTH | 8192 | Positive natural number |
14
+ | PUMA_REQUEST_URI_MAX_LENGTH | 1024 * 12 | Positive natural number |
15
+ | PUMA_SKIP_SIGUSR2 | nil | n/a |
16
+
17
+ ## Examples
18
+
19
+ ### Invalid inputs
20
+
21
+ An empty string will be handled as missing, and the default value will be used instead.
22
+ Puma will print an error message for other invalid values.
23
+
24
+ ```
25
+ foo@bar:~/puma$ PUMA_QUERY_STRING_MAX_LENGTH=abc PUMA_REQUEST_PATH_MAX_LENGTH='' PUMA_REQUEST_URI_MAX_LENGTH=0 bundle exec bin/puma test/rackup/hello.ru
26
+
27
+ The value 0 for PUMA_REQUEST_URI_MAX_LENGTH is invalid. Using default value 12288 instead.
28
+ The value abc for PUMA_QUERY_STRING_MAX_LENGTH is invalid. Using default value 10240 instead.
29
+ Puma starting in single mode...
30
+ ```
31
+
32
+ ### Valid inputs
33
+
34
+ ```
35
+ foo@bar:~/puma$ PUMA_REQUEST_PATH_MAX_LENGTH=9 bundle exec bin/puma test/rackup/hello.ru
36
+
37
+ Puma starting in single mode...
38
+ ```
39
+ ```
40
+ foo@bar:~ export path=/123456789 # 10 chars
41
+ foo@bar:~ curl "http://localhost:9292${path}"
42
+
43
+ Puma caught this error: HTTP element REQUEST_PATH is longer than the 9 allowed length. (Puma::HttpParserError)
44
+
45
+ foo@bar:~ export path=/12345678 # 9 chars
46
+ foo@bar:~ curl "http://localhost:9292${path}"
47
+ Hello World
48
+ ```
49
+
50
+ ### Java Flight Recorder Compatibility
51
+
52
+ Unfortunately Java Flight Recorder uses `SIGUSR2` internally. If you wish to
53
+ use JFR, turn off Puma's trapping of `SIGUSR2` by setting the environment variable
54
+ `PUMA_SKIP_SIGUSR2` to any value.
data/docs/plugins.md CHANGED
@@ -36,3 +36,7 @@ object that is useful for additional configuration.
36
36
 
37
37
  Public methods in [`Puma::Plugin`](../lib/puma/plugin.rb) are treated as a
38
38
  public API for plugins.
39
+
40
+ ## Binder hooks
41
+
42
+ There's `Puma::Binder#before_parse` method that allows to add proc to run before the body of `Puma::Binder#parse`. Example of usage can be found in [that repository](https://github.com/anchordotdev/puma-acme/blob/v0.1.3/lib/puma/acme/plugin.rb#L97-L118) (`before_parse_hook` could be renamed `before_parse`, making monkey patching of [binder.rb](https://github.com/anchordotdev/puma-acme/blob/v0.1.3/lib/puma/acme/binder.rb) is unnecessary).
data/docs/signals.md CHANGED
@@ -17,13 +17,13 @@ $ ps aux | grep tail
17
17
  schneems 87152 0.0 0.0 2432772 492 s032 S+ 12:46PM 0:00.00 tail -f my.log
18
18
  ```
19
19
 
20
- You can send a signal in Ruby using the [Process module](https://www.ruby-doc.org/core-2.1.1/Process.html#kill-method):
20
+ You can send a signal in Ruby using the [Process module](https://ruby-doc.org/3.2.2/Process.html#method-c-kill):
21
21
 
22
22
  ```
23
23
  $ irb
24
24
  > puts pid
25
25
  => 87152
26
- Process.detach(pid) # https://ruby-doc.org/core-2.1.1/Process.html#method-c-detach
26
+ Process.detach(pid) # https://ruby-doc.org/3.2.2/Process.html#method-c-detach
27
27
  Process.kill("TERM", pid)
28
28
  ```
29
29
 
data/docs/stats.md CHANGED
@@ -55,9 +55,14 @@ end
55
55
 
56
56
  When Puma runs in single mode, these stats are available at the top level. When Puma runs in cluster mode, these stats are available within the `worker_status` array in a hash labeled `last_status`, in an array of hashes where one hash represents each worker.
57
57
 
58
- * backlog: requests that are waiting for an available thread to be available. if this is above 0, you need more capacity [always true?]
59
- * running: how many threads are running
60
- * pool_capacity: the number of requests that the server is capable of taking right now. For example, if the number is 5, then it means there are 5 threads sitting idle ready to take a request. If one request comes in, then the value would be 4 until it finishes processing. If the minimum threads allowed is zero, this number will still have a maximum value of the maximum threads allowed.
58
+ * backlog: requests that are waiting for an available thread to be available. if this is frequently above 0, you need more capacity.
59
+ * running: how many threads are spawned. A spawned thread may be busy processing a request or waiting for a new request. If `min_threads` and `max_threads` are set to the same number,
60
+ this will be a never-changing number (other than rare cases when a thread dies, etc).
61
+ * busy_threads: `running` - `how many threads are waiting to receive work` + `how many requests are waiting for a thread to pick them up`.
62
+ this is a "wholistic" stat reflecting the overall current state of work to be done and the capacity to do it.
63
+ * pool_capacity: `how many threads are waiting to receive work` + `max_threads` - `running`. In a typical configuration where `min_threads`
64
+ and `max_threads` are configured to the same number, this is simply `how many threads are waiting to receive work`. This number exists only as a stat
65
+ and is not used for any internal decisions, unlike `busy_theads`, which is usually a more useful stat.
61
66
  * max_threads: the maximum number of threads Puma is configured to spool per worker
62
67
  * requests_count: the number of requests this worker has served since starting
63
68
 
data/docs/systemd.md CHANGED
@@ -99,9 +99,11 @@ ListenStream=0.0.0.0:9293
99
99
  # ListenStream=/run/puma.sock
100
100
 
101
101
  # Socket options matching Puma defaults
102
- NoDelay=true
103
102
  ReusePort=true
104
103
  Backlog=1024
104
+ # Enable this if you're using Puma with the "low_latency" option, read more in Puma DSL docs and systemd docs:
105
+ # https://www.freedesktop.org/software/systemd/man/latest/systemd.socket.html#NoDelay=
106
+ # NoDelay=true
105
107
 
106
108
  [Install]
107
109
  WantedBy=sockets.target
@@ -239,6 +241,13 @@ cap $stage puma:start --dry-run
239
241
  cap $stage puma:stop --dry-run
240
242
  ~~~~
241
243
 
244
+ ### Disabling Puma Systemd Integration
245
+
246
+ If you would like to disable Puma's systemd integration, for example if you handle it elsewhere
247
+ in your code yourself, simply set the the environment variable `PUMA_SKIP_SYSTEMD` to any value.
248
+
249
+
250
+
242
251
  [Restart]: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=
243
252
  [#1367]: https://github.com/puma/puma/issues/1367
244
253
  [#1499]: https://github.com/puma/puma/issues/1499
data/ext/puma_http11/extconf.rb CHANGED
@@ -10,15 +10,13 @@ end
10
10
 
11
11
  unless ENV["PUMA_DISABLE_SSL"]
12
12
  # don't use pkg_config('openssl') if '--with-openssl-dir' is used
13
- # also looks within the Ruby build for directory info
14
13
  has_openssl_dir = dir_config('openssl').any? ||
15
- RbConfig::CONFIG['configure_args']&.include?('openssl') ||
16
- Dir.exist?("#{RbConfig::TOPDIR}/src/main/c/openssl") # TruffleRuby
14
+ RbConfig::CONFIG['configure_args']&.include?('openssl')
17
15
 
18
16
  found_pkg_config = !has_openssl_dir && pkg_config('openssl')
19
17
 
20
18
  found_ssl = if !$mingw && found_pkg_config
21
- puts 'using OpenSSL pkgconfig (openssl.pc)'
19
+ puts '──── Using OpenSSL pkgconfig (openssl.pc) ────'
22
20
  true
23
21
  elsif have_library('libcrypto', 'BIO_read') && have_library('libssl', 'SSL_CTX_new')
24
22
  true
@@ -33,22 +31,27 @@ unless ENV["PUMA_DISABLE_SSL"]
33
31
  if found_ssl
34
32
  have_header "openssl/bio.h"
35
33
 
36
- # below is yes for 1.0.2 & later
37
- have_func "DTLS_method" , "openssl/ssl.h"
38
- have_func "SSL_CTX_set_session_cache_mode(NULL, 0)", "openssl/ssl.h"
34
+ ssl_h = "openssl/ssl.h".freeze
39
35
 
40
- # below are yes for 1.1.0 & later
41
- have_func "TLS_server_method" , "openssl/ssl.h"
42
- have_func "SSL_CTX_set_min_proto_version(NULL, 0)" , "openssl/ssl.h"
36
+ puts "\n──── Below are yes for 1.0.2 & later ────"
37
+ have_func "DTLS_method" , ssl_h
38
+ have_func "SSL_CTX_set_session_cache_mode(NULL, 0)", ssl_h
43
39
 
44
- have_func "X509_STORE_up_ref"
45
- have_func "SSL_CTX_set_ecdh_auto(NULL, 0)" , "openssl/ssl.h"
40
+ puts "\n──── Below are yes for 1.1.0 & later ────"
41
+ have_func "TLS_server_method" , ssl_h
42
+ have_func "SSL_CTX_set_min_proto_version(NULL, 0)" , ssl_h
46
43
 
47
- # below exists in 1.1.0 and later, but isn't documented until 3.0.0
48
- have_func "SSL_CTX_set_dh_auto(NULL, 0)" , "openssl/ssl.h"
44
+ puts "\n──── Below is yes for 1.1.0 and later, but isn't documented until 3.0.0 ────"
45
+ # https://github.com/openssl/openssl/blob/OpenSSL_1_1_0/include/openssl/ssl.h#L1159
46
+ have_func "SSL_CTX_set_dh_auto(NULL, 0)" , ssl_h
49
47
 
50
- # below is yes for 3.0.0 & later
51
- have_func "SSL_get1_peer_certificate" , "openssl/ssl.h"
48
+ puts "\n──── Below is yes for 1.1.1 & later ────"
49
+ have_func "SSL_CTX_set_ciphersuites(NULL, \"\")" , ssl_h
50
+
51
+ puts "\n──── Below is yes for 3.0.0 & later ────"
52
+ have_func "SSL_get1_peer_certificate" , ssl_h
53
+
54
+ puts ''
52
55
 
53
56
  # Random.bytes available in Ruby 2.5 and later, Random::DEFAULT deprecated in 3.0
54
57
  if Random.respond_to?(:bytes)
data/ext/puma_http11/mini_ssl.c CHANGED
@@ -229,7 +229,7 @@ VALUE
229
229
  sslctx_initialize(VALUE self, VALUE mini_ssl_ctx) {
230
230
  SSL_CTX* ctx;
231
231
  int ssl_options;
232
- VALUE key, cert, ca, verify_mode, ssl_cipher_filter, no_tlsv1, no_tlsv1_1,
232
+ VALUE key, cert, ca, verify_mode, ssl_cipher_filter, ssl_ciphersuites, no_tlsv1, no_tlsv1_1,
233
233
  verification_flags, session_id_bytes, cert_pem, key_pem, key_password_command, key_password;
234
234
  BIO *bio;
235
235
  X509 *x509 = NULL;
@@ -269,6 +269,8 @@ sslctx_initialize(VALUE self, VALUE mini_ssl_ctx) {
269
269
 
270
270
  ssl_cipher_filter = rb_funcall(mini_ssl_ctx, rb_intern_const("ssl_cipher_filter"), 0);
271
271
 
272
+ ssl_ciphersuites = rb_funcall(mini_ssl_ctx, rb_intern_const("ssl_ciphersuites"), 0);
273
+
272
274
  no_tlsv1 = rb_funcall(mini_ssl_ctx, rb_intern_const("no_tlsv1"), 0);
273
275
 
274
276
  no_tlsv1_1 = rb_funcall(mini_ssl_ctx, rb_intern_const("no_tlsv1_1"), 0);
@@ -444,6 +446,14 @@ sslctx_initialize(VALUE self, VALUE mini_ssl_ctx) {
444
446
  SSL_CTX_set_cipher_list(ctx, "HIGH:!aNULL@STRENGTH");
445
447
  }
446
448
 
449
+ #if HAVE_SSL_CTX_SET_CIPHERSUITES
450
+ // Only override OpenSSL default ciphersuites if config option is supplied.
451
+ if (!NIL_P(ssl_ciphersuites)) {
452
+ StringValue(ssl_ciphersuites);
453
+ SSL_CTX_set_ciphersuites(ctx, RSTRING_PTR(ssl_ciphersuites));
454
+ }
455
+ #endif
456
+
447
457
  #if OPENSSL_VERSION_NUMBER < 0x10002000L
448
458
  // Remove this case if OpenSSL 1.0.1 (now EOL) support is no longer needed.
449
459
  ecdh = EC_KEY_new_by_curve_name(NID_X9_62_prime256v1);