puma 6.6.0 → 7.2.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.
- checksums.yaml +4 -4
- data/History.md +248 -5
- data/README.md +40 -40
- data/docs/deployment.md +58 -23
- data/docs/fork_worker.md +5 -5
- data/docs/jungle/README.md +1 -1
- data/docs/kubernetes.md +11 -16
- data/docs/plugins.md +2 -2
- data/docs/restart.md +2 -2
- data/docs/signals.md +21 -21
- data/docs/stats.md +4 -3
- data/docs/systemd.md +4 -4
- data/ext/puma_http11/extconf.rb +2 -17
- data/ext/puma_http11/mini_ssl.c +18 -8
- data/ext/puma_http11/org/jruby/puma/Http11.java +10 -2
- data/ext/puma_http11/puma_http11.c +122 -118
- data/lib/puma/app/status.rb +10 -2
- data/lib/puma/binder.rb +10 -8
- data/lib/puma/cli.rb +3 -5
- data/lib/puma/client.rb +122 -72
- data/lib/puma/cluster/worker.rb +17 -17
- data/lib/puma/cluster/worker_handle.rb +38 -7
- data/lib/puma/cluster.rb +43 -29
- data/lib/puma/cluster_accept_loop_delay.rb +91 -0
- data/lib/puma/commonlogger.rb +3 -3
- data/lib/puma/configuration.rb +104 -51
- data/lib/puma/const.rb +11 -11
- data/lib/puma/control_cli.rb +6 -2
- data/lib/puma/detect.rb +2 -0
- data/lib/puma/dsl.rb +151 -100
- data/lib/puma/error_logger.rb +3 -1
- data/lib/puma/events.rb +25 -10
- data/lib/puma/io_buffer.rb +8 -4
- data/lib/puma/launcher/bundle_pruner.rb +1 -1
- data/lib/puma/launcher.rb +54 -49
- data/lib/puma/minissl.rb +0 -1
- data/lib/puma/plugin/systemd.rb +3 -3
- data/lib/puma/rack/urlmap.rb +1 -1
- data/lib/puma/reactor.rb +19 -13
- data/lib/puma/request.rb +54 -39
- data/lib/puma/runner.rb +9 -18
- data/lib/puma/server.rb +114 -64
- data/lib/puma/single.rb +7 -4
- data/lib/puma/state_file.rb +3 -2
- data/lib/puma/thread_pool.rb +47 -82
- data/lib/puma/util.rb +0 -7
- data/lib/puma.rb +10 -0
- data/lib/rack/handler/puma.rb +2 -2
- data/tools/Dockerfile +15 -5
- metadata +7 -6
- data/ext/puma_http11/ext_help.h +0 -15
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: eef4284ed113815501c9e01586a0a0fcd8d2f20e23376598e176effb4b6146a0
|
|
4
|
+
data.tar.gz: 83699a936ba02fbc03c2b2b10306d949f0525713d4a0cc3bbee44ecca6d71664
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a3ae91d6a0b359f450801765ed5cecb8f84204b115609ef41594812597f82211ba28c556ca5139a7bfc2ec9e68b6187a0fec481c228a0aeb40ca0ec25c57d29d
|
|
7
|
+
data.tar.gz: 289b4a1da3eaa061df1a0f7f8d7b5fce12d74e211a23fae0e7b7eae24fab85692b6636ed687ef8f4b833f7ff5ad975f3c17575f1061e1a4dc30ba517125b1788
|
data/History.md
CHANGED
|
@@ -1,3 +1,153 @@
|
|
|
1
|
+
## 7.2.1 / 2026-05-27
|
|
2
|
+
|
|
3
|
+
* Bugfixes
|
|
4
|
+
* Limit and anchor PROXY protocol v1 parsing to prevent abuse via crafted inputs ([#3947])
|
|
5
|
+
* Parse PROXY protocol only once per connection to prevent injection on keep-alive requests ([#3947])
|
|
6
|
+
|
|
7
|
+
## 7.2.0 / 2026-01-20
|
|
8
|
+
|
|
9
|
+
* Features
|
|
10
|
+
* Add workers `:auto` ([#3827])
|
|
11
|
+
* Make it possible to restrict control server commands to stats ([#3787])
|
|
12
|
+
|
|
13
|
+
* Bugfixes
|
|
14
|
+
* Don't break if `WEB_CONCURRENCY` is set to a blank string ([#3837])
|
|
15
|
+
* Don't share server between worker 0 and descendants on refork ([#3602])
|
|
16
|
+
* Fix phase check race condition in `Puma::Cluster#check_workers` ([#3690])
|
|
17
|
+
* Fix advertising of CLI config before config files are loaded ([#3823])
|
|
18
|
+
|
|
19
|
+
* Performance
|
|
20
|
+
* 17% faster HTTP parsing through pre-interning env keys ([#3825])
|
|
21
|
+
* Implement `dsize` and `dcompact` functions for `Puma::HttpParser`, which makes Puma's C-extension GC-compactible ([#3828])
|
|
22
|
+
|
|
23
|
+
* Refactor
|
|
24
|
+
* Remove `NoMethodError` rescue in `Reactor#select_loop` ([#3831])
|
|
25
|
+
* Various cleanups in the C extension ([#3814])
|
|
26
|
+
* Monomorphize `handle_request` return ([#3802])
|
|
27
|
+
|
|
28
|
+
* Docs
|
|
29
|
+
* Change link to `docs/deployment.md` in `README.md` ([#3848])
|
|
30
|
+
* Fix formatting for each signal description in signals.md ([#3813])
|
|
31
|
+
* Update deployment and Kubernetes docs with Puma configuration tips ([#3807])
|
|
32
|
+
* Rename master to main ([#3809], [#3808], [#3800])
|
|
33
|
+
* Fix some minor typos in the docs ([#3804])
|
|
34
|
+
* Add `GOVERNANCE.md`, `MAINTAINERS` ([#3826])
|
|
35
|
+
* Remove Code Climate badge ([#3820])
|
|
36
|
+
* Add @joshuay03 to the maintainer list
|
|
37
|
+
|
|
38
|
+
* CI
|
|
39
|
+
* Use Minitest 6 where applicable ([#3859])
|
|
40
|
+
* Many test suite improvements and flake fixes ([#3861], [#3863], [#3860], [#3852], [#3857], [#3856], [#3845], [#3843], [#3842], [#3841], [#3822], [#3817], [#3764])
|
|
41
|
+
|
|
42
|
+
## 7.1.0 / 2025-10-16
|
|
43
|
+
|
|
44
|
+
* Features
|
|
45
|
+
* Introduce `after_worker_shutdown` hook ([#3707])
|
|
46
|
+
* Reintroduce keepalive "fast inline" behavior. Provides faster (8x on JRuby & 1.4x on Ruby) pipeline processing ([#3794])
|
|
47
|
+
|
|
48
|
+
* Bugfixes
|
|
49
|
+
* Skip reading zero bytes when request body is buffered ([#3795])
|
|
50
|
+
* Fix `PUMA_LOG_CONFIG=1` logging twice with prune_bundler enabled ([#3778])
|
|
51
|
+
* Fix prune_bundler not showing in `PUMA_LOG_CONFIG=1` output ([#3779])
|
|
52
|
+
* Guard ThreadPool method call, which may be nil during shutdown ([#3791], [#3790])
|
|
53
|
+
* Set `Thread.current.puma_server` in Thread init code, not every request ([#3774])
|
|
54
|
+
* Fix race condition while deleting pidfile ([#3657])
|
|
55
|
+
|
|
56
|
+
## 7.0.4 / 2025-09-23
|
|
57
|
+
|
|
58
|
+
* Bugfixes
|
|
59
|
+
* Fix SSL_shutdown error handling ([#3703])
|
|
60
|
+
* Strip whitespace from the beginnings of request header values. ([#3742])
|
|
61
|
+
|
|
62
|
+
* Performance
|
|
63
|
+
* puma_http11.c: Use interned UTF-8 strings for hash keys ([#3754])
|
|
64
|
+
* Move sleep cluster logic to its own class ([#3746], [#3740])
|
|
65
|
+
|
|
66
|
+
## 7.0.3 / 2025-09-13
|
|
67
|
+
|
|
68
|
+
* Performance
|
|
69
|
+
* server.rb - process_client - add ka to todo if readable & complete ([#3748])
|
|
70
|
+
|
|
71
|
+
* Bugfixes
|
|
72
|
+
* Convert PUMA_PERSISTENT_TIMEOUT to an Integer ([#3749])
|
|
73
|
+
|
|
74
|
+
## 7.0.2 / 2025-09-08
|
|
75
|
+
|
|
76
|
+
* Bugfixes
|
|
77
|
+
* bug: control_cli.rb - Fixup `pumactl` code to load puma.rb for `deprecate_method_change` ([#3736], [#3734])
|
|
78
|
+
* Replace sleep spin lock with condition variable ([#3729])
|
|
79
|
+
* Fix Puma not booting if queue_requests disabled ([#3731])
|
|
80
|
+
|
|
81
|
+
## 7.0.1 / 2025-09-06
|
|
82
|
+
|
|
83
|
+
* Bugfixes
|
|
84
|
+
* Add backward compatibility aliases for Events class methods ([#3725])
|
|
85
|
+
|
|
86
|
+
## 7.0.0 / 2025-09-03
|
|
87
|
+
|
|
88
|
+
* Breaking changes
|
|
89
|
+
* Set default `max_keep_alive` to 999 ([#3719])
|
|
90
|
+
* Increase `persistent_timeout` default to 65 seconds ([#3378])
|
|
91
|
+
* Raise an ArgumentError if no block given to hooks ([#3377])
|
|
92
|
+
* Don't set env['HTTP_VERSION'] for Rack > 3.1 ([#3711], [#3576])
|
|
93
|
+
* Runner.rb - remove `ruby_engine` method, deprecated Nov-2024 ([#3701])
|
|
94
|
+
* Config `preload_app!` is now the default for clustered mode ([#3297])
|
|
95
|
+
* Config instance must be `clamp`-d before reading any values ([#3297])
|
|
96
|
+
* Response headers set to lowercase ([#3704])
|
|
97
|
+
* Update minimum Ruby version to 3.0 ([#3698])
|
|
98
|
+
* Rename callback hooks ([#3438])
|
|
99
|
+
|
|
100
|
+
| Old hook name| New hook name|
|
|
101
|
+
|----------|----------|
|
|
102
|
+
| on_worker_boot | before_worker_boot |
|
|
103
|
+
| on_worker_shutdown | before_worker_shutdown |
|
|
104
|
+
| on_restart | before_restart |
|
|
105
|
+
| on_booted | after_booted |
|
|
106
|
+
| on_stopped | after_stopped |
|
|
107
|
+
| on_refork | before_refork |
|
|
108
|
+
| on_thread_start | before_thread_start |
|
|
109
|
+
| on_thread_exit | before_thread_exit |
|
|
110
|
+
| on_worker_fork | before_worker_fork |
|
|
111
|
+
|
|
112
|
+
* Features
|
|
113
|
+
* Fix long tail response problem with keepalive connections ([#3678]) (Previously released in 7.0.0.pre1, this was a high effort change)
|
|
114
|
+
* Introduce support for fiber-per-request. ([#3101])
|
|
115
|
+
* Add support for `rack.response_finished` ([#3681])
|
|
116
|
+
* Feature/support custom logger with request logs ([#3140])
|
|
117
|
+
|
|
118
|
+
* Bugfixes
|
|
119
|
+
* Fix error_logger inproperly logging `env[QUERY_STRING]` ([#3713], [#3625])
|
|
120
|
+
* Fix handling of invalid Transfer-Encoding header errors ([#3702])
|
|
121
|
+
* Fix socket leak on monitor wakeup `NoMethodError` in `Reactor#select_loop` ([#3696], [#3695])
|
|
122
|
+
* CI: puma_socket.rb fixup socket/request writes ([#3684])
|
|
123
|
+
* Warn when RUBY_MN_THREADS env var is set ([#3721])
|
|
124
|
+
* Improve the DSL `preload_app!` doc ([#3712])
|
|
125
|
+
* Fix the ability to focus individual tests ([#3705])
|
|
126
|
+
* Set env['rack.hijack'] to client.method(:full_hijack) ([#3073])
|
|
127
|
+
|
|
128
|
+
* Performance
|
|
129
|
+
* server.rb - initialize ivars `@reactor` and `@env_set_http_version` ([#3714])
|
|
130
|
+
|
|
131
|
+
* Refactor
|
|
132
|
+
* Simplify `Puma::DSL#process_hook` logic ([#3710])
|
|
133
|
+
* Dry up deprecation warnings and fix deprecation warnings when running CI. ([#3709], [#3708])
|
|
134
|
+
* Ensure and enforce that configs are loaded before options are accessed ([#3616])
|
|
135
|
+
|
|
136
|
+
## 7.0.0.pre1 / 2025-07-31
|
|
137
|
+
|
|
138
|
+
* Changed
|
|
139
|
+
* Fix long tail response problem with keepalive connections ([#3678])
|
|
140
|
+
|
|
141
|
+
## 6.6.1 / 2025-07-30
|
|
142
|
+
|
|
143
|
+
* Bugfixes
|
|
144
|
+
* Accept `to_path` to be `nil` on request bodies ([#3635])
|
|
145
|
+
* Fix single runner stats before the server start ([#3572])
|
|
146
|
+
* Fix incomplete worker boot state on refork ([#3601])
|
|
147
|
+
* Improve HttpParserError messages for better debugging ([#3586])
|
|
148
|
+
* Fix refork logs to distinguish from phased restarts ([#3598])
|
|
149
|
+
* Fix `rack.after_reply` so it doesn't interrupt chain on error ([#3680])
|
|
150
|
+
|
|
1
151
|
## 6.6.0 / 2025-01-29
|
|
2
152
|
|
|
3
153
|
* Features
|
|
@@ -163,7 +313,7 @@
|
|
|
163
313
|
|
|
164
314
|
* Features
|
|
165
315
|
* Ability to supply a custom logger ([#2770], [#2511])
|
|
166
|
-
* Warn when
|
|
316
|
+
* Warn when cluster mode-only hooks are defined in single mode ([#3089])
|
|
167
317
|
* Adds the on_booted event ([#2709])
|
|
168
318
|
|
|
169
319
|
* Bugfixes
|
|
@@ -758,7 +908,7 @@ Each patchlevel release contains a separate security fix. We recommend simply up
|
|
|
758
908
|
* Fix Java 8 support ([#1773])
|
|
759
909
|
* Fix error `uninitialized constant Puma::Cluster` ([#1731])
|
|
760
910
|
* Fix `not_token` being able to be set to true ([#1803])
|
|
761
|
-
* Fix "Hang on SIGTERM with ruby 2.6 in
|
|
911
|
+
* Fix "Hang on SIGTERM with ruby 2.6 in cluster mode" (PR [#1741], [#1674], [#1720], [#1730], [#1755])
|
|
762
912
|
|
|
763
913
|
## 3.12.1 / 2019-03-19
|
|
764
914
|
|
|
@@ -1169,7 +1319,7 @@ Each patchlevel release contains a separate security fix. We recommend simply up
|
|
|
1169
1319
|
* 4 minor features:
|
|
1170
1320
|
|
|
1171
1321
|
* Listen to unix socket with provided backlog if any
|
|
1172
|
-
* Improves the
|
|
1322
|
+
* Improves the cluster mode stats to report worker stats
|
|
1173
1323
|
* Pass the env to the lowlevel_error handler. Fixes [#854]
|
|
1174
1324
|
* Treat path-like hosts as unix sockets. Fixes [#824]
|
|
1175
1325
|
|
|
@@ -1896,7 +2046,7 @@ The "clearly I don't have enough tests for the config" release.
|
|
|
1896
2046
|
|
|
1897
2047
|
* 3 doc changes:
|
|
1898
2048
|
* Add note about on_worker_boot hook
|
|
1899
|
-
* Add some documentation for
|
|
2049
|
+
* Add some documentation for Cluster mode
|
|
1900
2050
|
* Added quotes to /etc/puma.conf
|
|
1901
2051
|
|
|
1902
2052
|
## 2.0.1 / 2013-04-30
|
|
@@ -2150,6 +2300,99 @@ be added back in a future date when a java Puma::MiniSSL is added.
|
|
|
2150
2300
|
* Bugfixes
|
|
2151
2301
|
* Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
|
|
2152
2302
|
|
|
2303
|
+
[#3947]:https://github.com/puma/puma/pull/3947 "PR by Nate Berkopec, merged 2026-05-26"
|
|
2304
|
+
[#3863]:https://github.com/puma/puma/pull/3863 "PR by Nate Berkopec, merged 2026-01-20"
|
|
2305
|
+
[#3861]:https://github.com/puma/puma/pull/3861 "PR by MSP-Greg, merged 2026-01-20"
|
|
2306
|
+
[#3860]:https://github.com/puma/puma/pull/3860 "PR by MSP-Greg, merged 2026-01-16"
|
|
2307
|
+
[#3859]:https://github.com/puma/puma/pull/3859 "PR by MSP-Greg, merged 2026-01-16"
|
|
2308
|
+
[#3857]:https://github.com/puma/puma/pull/3857 "PR by Aaron Patterson, merged 2026-01-12"
|
|
2309
|
+
[#3856]:https://github.com/puma/puma/pull/3856 "PR by MSP-Greg, merged 2026-01-12"
|
|
2310
|
+
[#3852]:https://github.com/puma/puma/pull/3852 "PR by Miłosz Bieniek, merged 2026-01-14"
|
|
2311
|
+
[#3848]:https://github.com/puma/puma/pull/3848 "PR by Miłosz Bieniek, merged 2025-12-27"
|
|
2312
|
+
[#3845]:https://github.com/puma/puma/pull/3845 "PR by MSP-Greg, merged 2025-12-19"
|
|
2313
|
+
[#3843]:https://github.com/puma/puma/pull/3843 "PR by MSP-Greg, merged 2025-12-18"
|
|
2314
|
+
[#3842]:https://github.com/puma/puma/pull/3842 "PR by MSP-Greg, merged 2025-12-18"
|
|
2315
|
+
[#3841]:https://github.com/puma/puma/pull/3841 "PR by MSP-Greg, merged 2025-12-18"
|
|
2316
|
+
[#3837]:https://github.com/puma/puma/pull/3837 "PR by John Bachir, merged 2026-01-09"
|
|
2317
|
+
[#3833]:https://github.com/puma/puma/pull/3833 "PR by Patrik Ragnarsson, merged 2025-11-25"
|
|
2318
|
+
[#3831]:https://github.com/puma/puma/pull/3831 "PR by Joshua Young, merged 2025-11-25"
|
|
2319
|
+
[#3828]:https://github.com/puma/puma/pull/3828 "PR by Jean Boussier, merged 2025-11-21"
|
|
2320
|
+
[#3827]:https://github.com/puma/puma/pull/3827 "PR by Nate Berkopec, merged 2026-01-20"
|
|
2321
|
+
[#3826]:https://github.com/puma/puma/pull/3826 "PR by Nate Berkopec, merged 2026-01-20"
|
|
2322
|
+
[#3825]:https://github.com/puma/puma/pull/3825 "PR by Jean Boussier, merged 2025-11-19"
|
|
2323
|
+
[#3823]:https://github.com/puma/puma/pull/3823 "PR by Joshua Young, merged 2025-11-18"
|
|
2324
|
+
[#3822]:https://github.com/puma/puma/pull/3822 "PR by Nate Berkopec, merged 2025-11-17"
|
|
2325
|
+
[#3820]:https://github.com/puma/puma/pull/3820 "PR by Nate Berkopec, merged 2025-11-19"
|
|
2326
|
+
[#3817]:https://github.com/puma/puma/pull/3817 "PR by Nate Berkopec, merged 2025-11-17"
|
|
2327
|
+
[#3814]:https://github.com/puma/puma/pull/3814 "PR by Jean Boussier, merged 2025-11-17"
|
|
2328
|
+
[#3813]:https://github.com/puma/puma/pull/3813 "PR by Masafumi Koba, merged 2025-11-17"
|
|
2329
|
+
[#3809]:https://github.com/puma/puma/pull/3809 "PR by Patrik Ragnarsson, merged 2025-10-26"
|
|
2330
|
+
[#3808]:https://github.com/puma/puma/pull/3808 "PR by Nymuxyzo, merged 2025-10-26"
|
|
2331
|
+
[#3807]:https://github.com/puma/puma/pull/3807 "PR by Nate Berkopec, merged 2025-10-28"
|
|
2332
|
+
[#3804]:https://github.com/puma/puma/pull/3804 "PR by Joe Rafaniello, merged 2025-10-21"
|
|
2333
|
+
[#3802]:https://github.com/puma/puma/pull/3802 "PR by Richard Schneeman, merged 2025-10-20"
|
|
2334
|
+
[#3800]:https://github.com/puma/puma/pull/3800 "PR by MSP-Greg, merged 2025-10-19"
|
|
2335
|
+
[#3787]:https://github.com/puma/puma/pull/3787 "PR by Stan Hu, merged 2025-10-17"
|
|
2336
|
+
[#3764]:https://github.com/puma/puma/pull/3764 "PR by MSP-Greg, merged 2025-10-17"
|
|
2337
|
+
[#3690]:https://github.com/puma/puma/pull/3690 "PR by Joshua Young, merged 2025-11-18"
|
|
2338
|
+
[#3602]:https://github.com/puma/puma/pull/3602 "PR by Joshua Young, merged 2025-11-28"
|
|
2339
|
+
|
|
2340
|
+
[#3707]:https://github.com/puma/puma/pull/3707 "PR by @nerdrew, merged 2025-10-02"
|
|
2341
|
+
[#3794]:https://github.com/puma/puma/pull/3794 "PR by @schneems, merged 2025-10-16"
|
|
2342
|
+
[#3795]:https://github.com/puma/puma/pull/3795 "PR by @MSP-Greg, merged 2025-10-16"
|
|
2343
|
+
[#3778]:https://github.com/puma/puma/pull/3778 "PR by @joshuay03, merged 2025-10-16"
|
|
2344
|
+
[#3779]:https://github.com/puma/puma/pull/3779 "PR by @joshuay03, merged 2025-10-16"
|
|
2345
|
+
[#3791]:https://github.com/puma/puma/pull/3791 "PR by @MSP-Greg, merged 2025-10-09"
|
|
2346
|
+
[#3790]:https://github.com/puma/puma/issues/3790 "Issue by @eric-wtfoxtrot, closed 2025-10-09"
|
|
2347
|
+
[#3774]:https://github.com/puma/puma/pull/3774 "PR by @MSP-Greg, merged 2025-10-16"
|
|
2348
|
+
[#3657]:https://github.com/puma/puma/pull/3657 "PR by @marksmith, merged 2025-10-16"
|
|
2349
|
+
[#3703]:https://github.com/puma/puma/pull/3703 "PR by @marshall-lee, merged 2025-09-20"
|
|
2350
|
+
[#3742]:https://github.com/puma/puma/pull/3742 "PR by @kenballus, merged 2025-09-18"
|
|
2351
|
+
[#3754]:https://github.com/puma/puma/pull/3754 "PR by @byroot, merged 2025-09-18"
|
|
2352
|
+
[#3746]:https://github.com/puma/puma/pull/3746 "PR by @schneems, merged 2025-09-18"
|
|
2353
|
+
[#3740]:https://github.com/puma/puma/issues/3740 "Issue by @joshuay03, closed 2025-09-18"
|
|
2354
|
+
[#3748]:https://github.com/puma/puma/pull/3748 "PR by @MSP-Greg, merged 2025-09-14"
|
|
2355
|
+
[#3749]:https://github.com/puma/puma/pull/3749 "PR by @schneems, merged 2025-09-14"
|
|
2356
|
+
[#3736]:https://github.com/puma/puma/pull/3736 "PR by @MSP-Greg, merged 2025-09-08"
|
|
2357
|
+
[#3734]:https://github.com/puma/puma/issues/3734 "Issue by @espen, closed 2025-09-08"
|
|
2358
|
+
[#3729]:https://github.com/puma/puma/pull/3729 "PR by @bensheldon, merged 2025-09-08"
|
|
2359
|
+
[#3731]:https://github.com/puma/puma/pull/3731 "PR by @stanhu, merged 2025-09-06"
|
|
2360
|
+
[#3725]:https://github.com/puma/puma/pull/3725 "PR by @tannakartikey, merged 2025-09-05"
|
|
2361
|
+
[#3719]:https://github.com/puma/puma/pull/3719 "PR by @schneems, merged 2025-09-03"
|
|
2362
|
+
[#3378]:https://github.com/puma/puma/pull/3378 "PR by @shayonj, merged 2025-08-19"
|
|
2363
|
+
[#3377]:https://github.com/puma/puma/pull/3377 "PR by @joshuay03, merged 2025-08-12"
|
|
2364
|
+
[#3711]:https://github.com/puma/puma/pull/3711 "PR by @MSP-Greg, merged 2025-08-28"
|
|
2365
|
+
[#3576]:https://github.com/puma/puma/issues/3576 "Issue by @pdalberti, closed 2025-08-28"
|
|
2366
|
+
[#3701]:https://github.com/puma/puma/pull/3701 "PR by @MSP-Greg, merged 2025-08-26"
|
|
2367
|
+
[#3297]:https://github.com/puma/puma/pull/3297 "PR by @joshuay03, merged 2025-08-26"
|
|
2368
|
+
[#3704]:https://github.com/puma/puma/pull/3704 "PR by @schneems, merged 2025-08-25"
|
|
2369
|
+
[#3698]:https://github.com/puma/puma/pull/3698 "PR by @schneems, merged 2025-08-21"
|
|
2370
|
+
[#3438]:https://github.com/puma/puma/pull/3438 "PR by @tannakartikey, merged 2025-08-25"
|
|
2371
|
+
[#3678]:https://github.com/puma/puma/pull/3678 "PR by @MSP-Greg, merged 2025-07-31"
|
|
2372
|
+
[#3101]:https://github.com/puma/puma/pull/3101 "PR by @ioquatix, merged 2025-08-25"
|
|
2373
|
+
[#3681]:https://github.com/puma/puma/pull/3681 "PR by @byroot, merged 2025-08-15"
|
|
2374
|
+
[#3140]:https://github.com/puma/puma/pull/3140 "PR by @phyzical, merged 2025-08-12"
|
|
2375
|
+
[#3713]:https://github.com/puma/puma/pull/3713 "PR by @MSP-Greg, merged 2025-08-29"
|
|
2376
|
+
[#3625]:https://github.com/puma/puma/pull/3625 "PR by @bhooshiek-narendiran, closed 2025-08-29"
|
|
2377
|
+
[#3702]:https://github.com/puma/puma/pull/3702 "PR by @marshall-lee, merged 2025-08-25"
|
|
2378
|
+
[#3696]:https://github.com/puma/puma/pull/3696 "PR by @joshuay03, merged 2025-08-22"
|
|
2379
|
+
[#3695]:https://github.com/puma/puma/issues/3695 "Issue by @joshuay03, closed 2025-08-22"
|
|
2380
|
+
[#3684]:https://github.com/puma/puma/pull/3684 "PR by @MSP-Greg, merged 2025-08-02"
|
|
2381
|
+
[#3721]:https://github.com/puma/puma/pull/3721 "PR by @schneems, merged 2025-09-03"
|
|
2382
|
+
[#3712]:https://github.com/puma/puma/pull/3712 "PR by @joshuay03, merged 2025-08-28"
|
|
2383
|
+
[#3705]:https://github.com/puma/puma/pull/3705 "PR by @schneems, merged 2025-08-25"
|
|
2384
|
+
[#3073]:https://github.com/puma/puma/pull/3073 "PR by @MSP-Greg, merged 2025-08-12"
|
|
2385
|
+
[#3714]:https://github.com/puma/puma/pull/3714 "PR by @MSP-Greg, merged 2025-08-29"
|
|
2386
|
+
[#3710]:https://github.com/puma/puma/pull/3710 "PR by @joshuay03, merged 2025-08-28"
|
|
2387
|
+
[#3709]:https://github.com/puma/puma/pull/3709 "PR by @MSP-Greg, merged 2025-08-28"
|
|
2388
|
+
[#3708]:https://github.com/puma/puma/issues/3708 "Issue by @schneems, closed 2025-08-28"
|
|
2389
|
+
[#3616]:https://github.com/puma/puma/pull/3616 "PR by @joshuay03, merged 2025-08-25"
|
|
2390
|
+
[#3635]:https://github.com/puma/puma/pull/3635 "PR by @LevitatingBusinessMan, merged 2025-05-08"
|
|
2391
|
+
[#3572]:https://github.com/puma/puma/pull/3572 "PR by @barthez, merged 2025-02-06"
|
|
2392
|
+
[#3601]:https://github.com/puma/puma/pull/3601 "PR by @joshuay03, merged 2025-01-31"
|
|
2393
|
+
[#3586]:https://github.com/puma/puma/pull/3586 "PR by @MSP-Greg, merged 2025-02-03"
|
|
2394
|
+
[#3598]:https://github.com/puma/puma/pull/3598 "PR by @joshuay03, merged 2025-01-31"
|
|
2395
|
+
[#3680]:https://github.com/puma/puma/pull/3680 "PR by @byroot, merged 2025-07-31"
|
|
2153
2396
|
[#3570]:https://github.com/puma/puma/pull/3570 "PR by @mohamedhafez, merged 2024-12-30"
|
|
2154
2397
|
[#3567]:https://github.com/puma/puma/issues/3567 "Issue by @mohamedhafez, closed 2024-12-30"
|
|
2155
2398
|
[#3383]:https://github.com/puma/puma/pull/3383 "PR by @joshuay03, merged 2024-11-29"
|
|
@@ -2748,7 +2991,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
|
|
|
2748
2991
|
[#1022]:https://github.com/puma/puma/issues/1022 "Issue by @AKovtunov, closed 2017-08-16"
|
|
2749
2992
|
[#958]:https://github.com/puma/puma/issues/958 "Issue by @lalitlogical, closed 2016-04-23"
|
|
2750
2993
|
[#782]:https://github.com/puma/puma/issues/782 "Issue by @Tonkpils, closed 2016-07-19"
|
|
2751
|
-
[#1010]:https://github.com/puma/puma/issues/1010 "Issue by @
|
|
2994
|
+
[#1010]:https://github.com/puma/puma/issues/1010 "Issue by @mirineumark, closed 2016-07-19"
|
|
2752
2995
|
[#959]:https://github.com/puma/puma/issues/959 "Issue by @mwpastore, closed 2016-04-22"
|
|
2753
2996
|
[#840]:https://github.com/puma/puma/issues/840 "Issue by @marisawallace, closed 2016-04-07"
|
|
2754
2997
|
[#1007]:https://github.com/puma/puma/pull/1007 "PR by @willnet, merged 2016-06-24"
|
data/README.md
CHANGED
|
@@ -4,8 +4,7 @@
|
|
|
4
4
|
|
|
5
5
|
# Puma: A Ruby Web Server Built For Parallelism
|
|
6
6
|
|
|
7
|
-
[](https://codeclimate.com/github/puma/puma)
|
|
7
|
+
[](https://github.com/puma/puma/actions/workflows/tests.yml?query=branch%3Amain)
|
|
9
8
|
[]( https://stackoverflow.com/questions/tagged/puma )
|
|
10
9
|
|
|
11
10
|
Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server for Ruby/Rack applications**.
|
|
@@ -82,10 +81,10 @@ $ bundle exec puma
|
|
|
82
81
|
|
|
83
82
|
## Configuration
|
|
84
83
|
|
|
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/
|
|
84
|
+
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
85
|
|
|
87
86
|
You can also find several configuration examples as part of the
|
|
88
|
-
[test](https://github.com/puma/puma/tree/
|
|
87
|
+
[test](https://github.com/puma/puma/tree/main/test/config) suite.
|
|
89
88
|
|
|
90
89
|
For debugging purposes, you can set the environment variable `PUMA_LOG_CONFIG` with a value
|
|
91
90
|
and the loaded configuration will be printed as part of the boot process.
|
|
@@ -102,9 +101,9 @@ Puma will automatically scale the number of threads, from the minimum until it c
|
|
|
102
101
|
|
|
103
102
|
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
103
|
|
|
105
|
-
###
|
|
104
|
+
### Cluster mode
|
|
106
105
|
|
|
107
|
-
Puma also offers "
|
|
106
|
+
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
107
|
|
|
109
108
|
```
|
|
110
109
|
$ puma -t 8:32 -w 3
|
|
@@ -116,15 +115,24 @@ Or with the `WEB_CONCURRENCY` environment variable:
|
|
|
116
115
|
$ WEB_CONCURRENCY=3 puma -t 8:32
|
|
117
116
|
```
|
|
118
117
|
|
|
119
|
-
|
|
118
|
+
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:
|
|
120
119
|
|
|
121
|
-
|
|
120
|
+
```ruby
|
|
121
|
+
# config/puma.rb
|
|
122
|
+
workers :auto
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
See [`workers :auto` gotchas](lib/puma/dsl.rb).
|
|
122
126
|
|
|
123
|
-
|
|
127
|
+
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.
|
|
124
128
|
|
|
125
|
-
|
|
129
|
+
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).
|
|
126
130
|
|
|
127
|
-
|
|
131
|
+
For an in-depth discussion of the tradeoffs of thread and process count settings, [see our docs](docs/deployment.md).
|
|
132
|
+
|
|
133
|
+
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).
|
|
134
|
+
|
|
135
|
+
If the number of workers is greater than 1 (and `--prune-bundler` has not been specified), preloading will be enabled by default. Otherwise, you can use the `--preload` flag from the command line:
|
|
128
136
|
|
|
129
137
|
```
|
|
130
138
|
$ puma -w 3 --preload
|
|
@@ -140,10 +148,10 @@ preload_app!
|
|
|
140
148
|
|
|
141
149
|
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.
|
|
142
150
|
|
|
143
|
-
####
|
|
151
|
+
#### Cluster mode hooks
|
|
144
152
|
|
|
145
|
-
When using clustered mode, Puma's configuration DSL provides `before_fork` and `
|
|
146
|
-
hooks to run code when the master process forks
|
|
153
|
+
When using clustered mode, Puma's configuration DSL provides `before_fork`, `before_worker_boot`, and `after_worker_shutdown`
|
|
154
|
+
hooks to run code when the master process forks, the child workers are booted, and after each child worker exits respectively.
|
|
147
155
|
|
|
148
156
|
It is recommended to use these hooks with `preload_app!`, otherwise constants loaded by your
|
|
149
157
|
application (such as `Rails`) will not be available inside the hooks.
|
|
@@ -154,16 +162,21 @@ before_fork do
|
|
|
154
162
|
# Add code to run inside the Puma master process before it forks a worker child.
|
|
155
163
|
end
|
|
156
164
|
|
|
157
|
-
|
|
165
|
+
before_worker_boot do
|
|
158
166
|
# Add code to run inside the Puma worker process after forking.
|
|
159
167
|
end
|
|
168
|
+
|
|
169
|
+
after_worker_shutdown do |worker_handle|
|
|
170
|
+
# Add code to run inside the Puma master process after a worker exits. `worker.process_status` can be used to get the
|
|
171
|
+
# `Process::Status` of the exited worker.
|
|
172
|
+
end
|
|
160
173
|
```
|
|
161
174
|
|
|
162
|
-
In addition, there is an `
|
|
175
|
+
In addition, there is an `before_refork` and `after_refork` hooks which are used only in [`fork_worker` mode](docs/fork_worker.md),
|
|
163
176
|
when the worker 0 child process forks a grandchild worker:
|
|
164
177
|
|
|
165
178
|
```ruby
|
|
166
|
-
|
|
179
|
+
before_refork do
|
|
167
180
|
# Used only when fork_worker mode is enabled. Add code to run inside the Puma worker 0
|
|
168
181
|
# child process before it forks a grandchild worker.
|
|
169
182
|
end
|
|
@@ -176,7 +189,7 @@ after_refork do
|
|
|
176
189
|
end
|
|
177
190
|
```
|
|
178
191
|
|
|
179
|
-
Importantly, note the following considerations when Ruby forks a child process:
|
|
192
|
+
Importantly, note the following considerations when Ruby forks a child process:
|
|
180
193
|
|
|
181
194
|
1. File descriptors such as network sockets **are** copied from the parent to the forked
|
|
182
195
|
child process. Dual-use of the same sockets by parent and child will result in I/O conflicts
|
|
@@ -190,29 +203,29 @@ Therefore, we recommend the following:
|
|
|
190
203
|
|
|
191
204
|
1. If possible, do not establish any socket connections (HTTP, database connections, etc.)
|
|
192
205
|
inside Puma's master process when booting.
|
|
193
|
-
2. If (1) is not possible, use `before_fork` and `
|
|
206
|
+
2. If (1) is not possible, use `before_fork` and `before_refork` to disconnect the parent's socket
|
|
194
207
|
connections when forking, so that they are not accidentally copied to the child process.
|
|
195
|
-
3. Use `
|
|
208
|
+
3. Use `before_worker_boot` to restart any background threads on the forked child.
|
|
196
209
|
4. Use `after_refork` to restart any background threads on the parent.
|
|
197
210
|
|
|
198
211
|
#### Master process lifecycle hooks
|
|
199
212
|
|
|
200
|
-
Puma's configuration DSL provides master process lifecycle hooks `
|
|
213
|
+
Puma's configuration DSL provides master process lifecycle hooks `after_booted`, `before_restart`, and `after_stopped`
|
|
201
214
|
which may be used to specify code blocks to run on each event:
|
|
202
215
|
|
|
203
216
|
```ruby
|
|
204
217
|
# config/puma.rb
|
|
205
|
-
|
|
218
|
+
after_booted do
|
|
206
219
|
# Add code to run in the Puma master process after it boots,
|
|
207
220
|
# and also after a phased restart completes.
|
|
208
221
|
end
|
|
209
222
|
|
|
210
|
-
|
|
223
|
+
before_restart do
|
|
211
224
|
# Add code to run in the Puma master process when it receives
|
|
212
225
|
# a restart command but before it restarts.
|
|
213
226
|
end
|
|
214
227
|
|
|
215
|
-
|
|
228
|
+
after_stopped do
|
|
216
229
|
# Add code to run in the Puma master process when it receives
|
|
217
230
|
# a stop command but before it shuts down.
|
|
218
231
|
end
|
|
@@ -221,7 +234,7 @@ end
|
|
|
221
234
|
### Error handling
|
|
222
235
|
|
|
223
236
|
If Puma encounters an error outside of the context of your application, it will respond with a 400/500 and a simple
|
|
224
|
-
textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/
|
|
237
|
+
textual error message (see `Puma::Server#lowlevel_error` or [server.rb](https://github.com/puma/puma/blob/main/lib/puma/server.rb)).
|
|
225
238
|
You can specify custom behavior for this scenario. For example, you can report the error to your third-party
|
|
226
239
|
error-tracking service (in this example, [rollbar](https://rollbar.com)):
|
|
227
240
|
|
|
@@ -380,7 +393,7 @@ Puma has a built-in status and control app that can be used to query and control
|
|
|
380
393
|
$ puma --control-url tcp://127.0.0.1:9293 --control-token foo
|
|
381
394
|
```
|
|
382
395
|
|
|
383
|
-
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/
|
|
396
|
+
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.
|
|
384
397
|
|
|
385
398
|
You can also interact with the control server via `pumactl`. This command will restart Puma:
|
|
386
399
|
|
|
@@ -412,7 +425,7 @@ $ puma -C "-"
|
|
|
412
425
|
|
|
413
426
|
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).
|
|
414
427
|
|
|
415
|
-
Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/
|
|
428
|
+
Check out `Puma::DSL` or [dsl.rb](https://github.com/puma/puma/blob/main/lib/puma/dsl.rb) to see all available options.
|
|
416
429
|
|
|
417
430
|
## Restart
|
|
418
431
|
|
|
@@ -432,19 +445,6 @@ Some platforms do not support all Puma features.
|
|
|
432
445
|
* **Windows**: Cluster mode is not supported due to a lack of fork(2).
|
|
433
446
|
* **Kubernetes**: The way Kubernetes handles pod shutdowns interacts poorly with server processes implementing graceful shutdown, like Puma. See the [kubernetes section of the documentation](docs/kubernetes.md) for more details.
|
|
434
447
|
|
|
435
|
-
## Known Bugs
|
|
436
|
-
|
|
437
|
-
For MRI versions 2.2.7, 2.2.8, 2.2.9, 2.2.10, 2.3.4 and 2.4.1, you may see ```stream closed in another thread (IOError)```. It may be caused by a [Ruby bug](https://bugs.ruby-lang.org/issues/13632). It can be fixed with the gem https://rubygems.org/gems/stopgap_13632:
|
|
438
|
-
|
|
439
|
-
```ruby
|
|
440
|
-
if %w(2.2.7 2.2.8 2.2.9 2.2.10 2.3.4 2.4.1).include? RUBY_VERSION
|
|
441
|
-
begin
|
|
442
|
-
require 'stopgap_13632'
|
|
443
|
-
rescue LoadError
|
|
444
|
-
end
|
|
445
|
-
end
|
|
446
|
-
```
|
|
447
|
-
|
|
448
448
|
## Deployment
|
|
449
449
|
|
|
450
450
|
* Puma has support for Capistrano with an [external gem](https://github.com/seuros/capistrano-puma).
|
data/docs/deployment.md
CHANGED
|
@@ -16,32 +16,34 @@ assume this is how you're using Puma.
|
|
|
16
16
|
Initially, Puma was conceived as a thread-only web server, but support for
|
|
17
17
|
processes was added in version 2.
|
|
18
18
|
|
|
19
|
+
In general, use single mode only if:
|
|
20
|
+
|
|
21
|
+
* You are using JRuby, TruffleRuby or another fully-multithreaded implementation of Ruby
|
|
22
|
+
* You are using MRI but in an environment where only 1 CPU core is available.
|
|
23
|
+
|
|
24
|
+
Otherwise, you'll want to use cluster mode to utilize all available CPU resources.
|
|
25
|
+
|
|
19
26
|
To run `puma` in single mode (i.e., as a development environment), set the
|
|
20
27
|
number of workers to 0; anything higher will run in cluster mode.
|
|
21
28
|
|
|
22
|
-
|
|
29
|
+
## Cluster Mode Tips
|
|
23
30
|
|
|
24
|
-
|
|
31
|
+
For the purposes of Puma provisioning, "CPU cores" means:
|
|
25
32
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
* Set the number of threads to desired concurrent requests/number of workers.
|
|
29
|
-
Puma defaults to 5, and that's a decent number.
|
|
33
|
+
1. On ARM, the number of physical cores.
|
|
34
|
+
2. On x86, the number of logical cores, hyperthreads, or vCPUs (these words all mean the same thing).
|
|
30
35
|
|
|
31
|
-
|
|
36
|
+
Set your config with the following process:
|
|
32
37
|
|
|
33
|
-
* If you'
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
* Enjoy 50% memory savings
|
|
37
|
-
* As you grow more confident in the thread-safety of your app, you can tune the
|
|
38
|
-
workers down and the threads up.
|
|
38
|
+
* Use cluster mode and set `workers :auto` (requires the `concurrent-ruby` gem) to match the number of CPU cores on the machine (minimum 2, otherwise use single mode!). If you can't add the gem, set the worker count manually to the available CPU cores.
|
|
39
|
+
* Set the number of threads to desired concurrent requests/number of workers.
|
|
40
|
+
Puma defaults to 5, and that's a decent number.
|
|
39
41
|
|
|
40
|
-
|
|
42
|
+
For most deployments, adding `concurrent-ruby` and using `workers :auto` is the right starting point.
|
|
41
43
|
|
|
42
|
-
See [
|
|
44
|
+
See [`workers :auto` gotchas](../lib/puma/dsl.rb).
|
|
43
45
|
|
|
44
|
-
|
|
46
|
+
## Worker utilization
|
|
45
47
|
|
|
46
48
|
**How do you know if you've got enough (or too many workers)?**
|
|
47
49
|
|
|
@@ -50,14 +52,34 @@ a time. But since so many apps are waiting on IO from DBs, etc., they can
|
|
|
50
52
|
utilize threads to use the process more efficiently.
|
|
51
53
|
|
|
52
54
|
Generally, you never want processes that are pegged all the time. That can mean
|
|
53
|
-
there is more work to do than the process can get through. On the other hand, if
|
|
54
|
-
you have processes that sit around doing nothing, then
|
|
55
|
-
|
|
55
|
+
there is more work to do than the process can get through, and requests will end up with additional latency. On the other hand, if
|
|
56
|
+
you have processes that sit around doing nothing, then you're wasting resources and money.
|
|
57
|
+
|
|
58
|
+
In general, you are making a tradeoff between:
|
|
59
|
+
|
|
60
|
+
1. CPU and memory utilization.
|
|
61
|
+
2. Time spent queueing for a Puma worker to `accept` requests and additional latency caused by CPU contention.
|
|
62
|
+
|
|
63
|
+
If latency is important to you, you will have to accept lower utilization, and vice versa.
|
|
56
64
|
|
|
57
|
-
|
|
58
|
-
utilization means you've got capacity still but aren't starving threads.
|
|
65
|
+
## Container/VPS sizing
|
|
59
66
|
|
|
60
|
-
|
|
67
|
+
You will have to make a decision about how "big" to make each pod/VPS/server/dyno.
|
|
68
|
+
|
|
69
|
+
**TL:DR;**: 80% of Puma apps will end up deploying "pods" of 4 workers, 5 threads each, 4 vCPU and 8GB of RAM.
|
|
70
|
+
|
|
71
|
+
For the rest of this discussion, we'll adopt the Kubernetes term of "pods".
|
|
72
|
+
|
|
73
|
+
Should you run 2 pods with 50 workers each? 25 pods, each with 4 workers? 100 pods, with each Puma running in single mode? Each scenario represents the same total amount of capacity (100 Puma processes that can respond to requests), but there are tradeoffs to make:
|
|
74
|
+
|
|
75
|
+
* **Increasing worker counts decreases latency, but means you scale in bigger "chunks"**. Worker counts should be somewhere between 4 and 32 in most cases. You want more than 4 in order to minimize time spent in request queueing for a free Puma worker, but probably less than ~32 because otherwise autoscaling is working in too large of an increment or they probably won't fit very well into your nodes. In any queueing system, queue time is proportional to 1/n, where n is the number of things pulling from the queue. Each pod will have its own request queue (i.e., the socket backlog). If you have 4 pods with 1 worker each (4 request queues), wait times are, proportionally, about 4 times higher than if you had 1 pod with 4 workers (1 request queue).
|
|
76
|
+
* **Increasing thread counts will increase throughput, but also latency and memory use** Unless you have a very I/O-heavy application (50%+ time spent waiting on IO), use the default thread count (5 for MRI). Using higher numbers of threads with low I/O wait (<50% of wall clock time) will lead to additional request latency and additional memory usage.
|
|
77
|
+
* **Increasing worker counts decreases memory per worker on average**. More processes per pod reduces memory usage per process, because of copy-on-write memory and because the cost of the single master process is "amortized" over more child processes.
|
|
78
|
+
* **Low worker counts (<4) have exceptionally poor throughput**. Don't run less than 4 processes per pod if you can. Low numbers of processes per pod will lead to high request queueing (see discussion above), which means you will have to run more pods and resources.
|
|
79
|
+
* **CPU-core-to-worker ratios should be around 1**. If running Puma with `threads > 1`, allocate 1 CPU core (see definition above!) per worker. If single threaded, allocate ~0.75 cpus per worker. Most web applications spend about 25% of their time in I/O - but when you're running multi-threaded, your Puma process will have higher CPU usage and should be able to fully saturate a CPU core. Using `workers :auto` will size workers to this guidance on most platforms.
|
|
80
|
+
* **Don't set memory limits unless necessary**. Most Puma processes will use about ~512MB-1GB per worker, and about 1GB for the master process. However, you probably shouldn't bother with setting memory limits lower than around 2GB per process, because most places you are deploying will have 2GB of RAM per CPU. A sensible memory limit for a Puma configuration of 4 child workers might be something like 8 GB (1 GB for the master, 7GB for the 4 children).
|
|
81
|
+
|
|
82
|
+
**Measuring utilization and queue time**
|
|
61
83
|
|
|
62
84
|
Using a timestamp header from an upstream proxy server (e.g., `nginx` or
|
|
63
85
|
`haproxy`) makes it possible to indicate how long requests have been waiting for
|
|
@@ -75,7 +97,7 @@ a Puma thread to become available.
|
|
|
75
97
|
* `env['puma.request_body_wait']` contains the number of milliseconds Puma
|
|
76
98
|
spent waiting for the client to send the request body.
|
|
77
99
|
* haproxy: `%Th` (TLS handshake time) and `%Ti` (idle time before request)
|
|
78
|
-
can
|
|
100
|
+
can also be added as headers.
|
|
79
101
|
|
|
80
102
|
## Should I daemonize?
|
|
81
103
|
|
|
@@ -100,3 +122,16 @@ or hell, even `monit`.
|
|
|
100
122
|
You probably will want to deploy some new code at some point, and you'd like
|
|
101
123
|
Puma to start running that new code. There are a few options for restarting
|
|
102
124
|
Puma, described separately in our [restart documentation](restart.md).
|
|
125
|
+
|
|
126
|
+
## Migrating from Unicorn
|
|
127
|
+
|
|
128
|
+
* If you're migrating from unicorn though, here are some settings to start with:
|
|
129
|
+
* Set workers to half the number of unicorn workers you're using
|
|
130
|
+
* Set threads to 2
|
|
131
|
+
* Enjoy 50% memory savings
|
|
132
|
+
* As you grow more confident in the thread-safety of your app, you can tune the
|
|
133
|
+
workers down and the threads up.
|
|
134
|
+
|
|
135
|
+
## Ubuntu / Systemd (Systemctl) Installation
|
|
136
|
+
|
|
137
|
+
See [systemd.md](systemd.md)
|