puma 6.0.0 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c8a1a6014d9e1130e8ba06d5f74d472216448df3dbce4c15c4c24c91fbfe5e30
-  data.tar.gz: f1be3485e37cd230f6c35854aeb959ffeab1dac0162bf482799a4755222bc498
+  metadata.gz: e58946300296f4d215a5859fcadb101b4fcec6d9012b38fd0af10c5fdb3ce0c2
+  data.tar.gz: 397fa109025cbc87d7466be97ed91e44789d522db2c4b89d1ef5f4e40db9f772
 SHA512:
-  metadata.gz: bbdd201a97e5dffccbbb8d8f336693746b87763313422a94ac21f73641ca712b9d2461051cc0bd02771b51af606ce595c2dd09bff0c716146cf9ac56e7ae51f4
-  data.tar.gz: e378848b22d1139559edd6736a9164a5cd98064c6232f0b2cc108122f79c93429ec33b156baa17e6ff82e9b3c77dbddbd22b2a0525a16f749129cf6f70c006da
+  metadata.gz: a0c6a4e6c10522de9a9c7d5eed57d5205a6d4acfe18e9d7c310044d5793a2a67a266c3b69f8ed4c5385559149dc858dbcf1b4307c86459b9723ea49303de5685
+  data.tar.gz: cf7a60331c499a1387414ca2d6955edbc239242a62ea06941bf912714ee4dcb9295a5a1bd9c3561fd396c54a2e04e5a0aa2194ef17b37accb78e049e4cb1ca6b

data/History.md

@@ -1,4 +1,106 @@
-## 6.0.0 / 2022-10-XX
+## 6.4.0 / 2023-09-21
+
+* Features
+  * on_thread_exit hook ([#2920])
+  * on_thread_start_hook ([#3195]) 
+  * Shutdown on idle ([#3209], [#2580])
+  * New error message when control server port taken ([#3204])
+
+* Refactor
+  * Remove `Forwardable` dependency ([#3191], #3190)
+  * Update URLMap Regexp usage for Ruby v3.3 ([#3165])
+
+* Bugfixes
+  * Bring the cert_pem: parameter into parity with the cert: parameter to ssl_bind. ([#3174])
+  * Fix using control server with IPv6 host ([#3181]) 
+  * control_cli.rb - add require_relative 'log_writer' ([#3187])
+  * Fix cases where fallback Rack response wasn't sent to the client ([#3094])
+  
+## 6.3.1 / 2023-08-18
+
+* Security 
+  * 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))
+
+## 6.3.0 / 2023-05-31
+
+* Features
+  * Add dsl method `supported_http_methods` ([#3106], [#3014])
+  * Puma error responses no longer have any fingerprints to indicate Puma ([#3161], [#3037])
+  * Support decryption of SSL key ([#3133], [#3132])
+
+* Bugfixes
+  * Don't send 103 early hints response when only invalid headers are used ([#3163])
+  * Handle malformed request path ([#3155], [#3148])
+  * Misc lib file fixes - trapping additional errors, CI helper ([#3129])
+  * Fixup req form data file upload with "r\n" line endings ([#3137])
+  * Restore rack 1.6 compatibility ([#3156])
+
+* Refactor
+  * const.rb - Update Puma::HTTP_STATUS_CODES ([#3162])
+  * Clarify Reactor#initialize ([#3151])
+
+## 6.2.2 / 2023-04-17
+
+* Bugfixes
+  * Fix Rack-related NameError by adding :: operator ([#3118], [#3117])
+
+## 6.2.1 / 2023-03-31
+
+* Bugfixes
+  * Fix java 8 compatibility ([#3109], [#3108])
+  * Always write io_buffer when in "enum bodies" branch. ([#3113], [#3112])
+  * Fix warn_if_in_single_mode incorrect message ([#3111])
+
+## 6.2.0 / 2023-03-29
+
+* Features
+  * Ability to supply a custom logger ([#2770], [#2511])
+  * Warn when clustered-only hooks are defined in single mode ([#3089])
+  * Adds the on_booted event ([#2709])
+
+* Bugfixes
+  * Loggers - internal_write - catch Errno::EINVAL ([#3091])
+  * commonlogger.rb - fix HIJACK time format, use constants, not strings ([#3074])
+  * Fixed some edge cases regarding request hijacking ([#3072])
+
+## 6.1.1 / 2023-02-28
+
+* Bugfixes
+  * We no longer try to use the systemd plugin for JRuby ([#3079])
+  * Allow ::Rack::Handler::Puma.run to work regardless of whether Rack/Rackup are loaded ([#3080])
+
+## 6.1.0 / 2023-02-12
+
+* Features
+  * WebSocket support via partial hijack ([#3058], [#3007])
+  * Add built-in systemd notify support ([#3011])
+  * Periodically send status to systemd ([#3006], [#2604])
+  * Introduce the ability to return 413: payload too large for requests ([#3040])
+  * Log loaded extensions when `PUMA_DEBUG` is set ([#3036], [#3020])
+
+* Bugfixes
+  * Fix issue with rack 3 compatibility re: rackup ([#3061], [#3057])
+  * Allow setting TCP low_latency with SSL listener ([#3065])
+
+* Performance
+  * Reduce memory usage for large file uploads ([#3062])
+
+## 6.0.2 / 2023-01-01
+
+* Refactor
+  * Remove use of etc and time gems in Puma ([#3035], [#3033])
+  * Refactor const.rb - freeze ([#3016])
+
+## 6.0.1 / 2022-12-20
+ 
+* Bugfixes
+  * Handle waking up a closed selector in Reactor#add ([#3005])
+  * Fixup response processing, enumerable bodies ([#3004], [#3000])
+  * Correctly close app body for all code paths ([#3002], [#2999])
+* Refactor 
+  * Add IOBuffer to Client, remove from ThreadPool thread instances ([#3013])
+
+## 6.0.0 / 2022-10-14
 
 * Breaking Changes
   * Dropping Ruby 2.2 and 2.3 support (now 2.4+) ([#2919])
@@ -9,6 +111,9 @@
   * Prefix all environment variables with `PUMA_` ([#2924], [#2853])
   * Removed some constants ([#2957], [#2958], [#2959], [#2960])
   * The following classes are now part of Puma's private API: `Client`, `Cluster::Worker`, `Cluster::Worker`, `HandleRequest`. ([#2988])
+  * Configuration constants like `DefaultRackup` removed ([#2928])
+  * Extracted `LogWriter` from `Events` ([#2798])
+  * Only accept the standard 8 HTTP methods, others rejected with 501. ([#2932])
 
 * Features
   * Increase throughput on large (100kb+) response bodies by 3-10x ([#2896], [#2892])
@@ -34,12 +139,21 @@
 
 * Refactor
   * log_writer.rb - add internal_write method ([#2888])
-  * [WIP] Refactor: Split out LogWriter from Events (no logic change) ([#2798])
   * Extract prune_bundler code into it's own class. ([#2797])
   * Refactor Launcher#run to increase readability (no logic change) ([#2795])
   * Ruby 3.2 will have native IO#wait_* methods, don't require io/wait ([#2903])
   * Various internal API refactorings ([#2942], [#2921], [#2922], [#2955])
 
+## 5.6.7 / 2023-08-18
+
+* Security 
+  * 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))
+
+## 5.6.6 / 2023-06-21
+
+* Bugfix
+  * Prevent loading with rack 3 ([#3166])
+
 ## 5.6.5 / 2022-08-23
 
 * Feature
@@ -1915,6 +2029,68 @@ be added back in a future date when a java Puma::MiniSSL is added.
 * Bugfixes
   * Your bugfix goes here <Most recent on the top, like GitHub> (#Github Number)
 
+[#2920]:https://github.com/puma/puma/pull/2920     "PR by @biinari, merged 2023-07-11"
+[#3195]:https://github.com/puma/puma/pull/3195     "PR by @binarygit, merged 2023-08-15"
+[#3209]:https://github.com/puma/puma/pull/3209     "PR by @joshuay03, merged 2023-09-04"
+[#2580]:https://github.com/puma/puma/issues/2580   "Issue by @schuetzm, closed 2023-09-04"
+[#3204]:https://github.com/puma/puma/pull/3204     "PR by @dhavalsingh, merged 2023-08-25"
+[#3191]:https://github.com/puma/puma/pull/3191     "PR by @MSP-Greg, merged 2023-08-31"
+[#3165]:https://github.com/puma/puma/pull/3165     "PR by @fallwith, merged 2023-06-06"
+[#3174]:https://github.com/puma/puma/pull/3174     "PR by @copiousfreetime, merged 2023-06-11"
+[#3181]:https://github.com/puma/puma/pull/3181     "PR by @MSP-Greg, merged 2023-06-23"
+[#3187]:https://github.com/puma/puma/pull/3187     "PR by @MSP-Greg, merged 2023-06-30"
+[#3094]:https://github.com/puma/puma/pull/3094     "PR by @Vuta, merged 2023-07-23"
+[#3106]:https://github.com/puma/puma/pull/3106     "PR by @MSP-Greg, merged 2023-05-29"
+[#3014]:https://github.com/puma/puma/issues/3014   "Issue by @kyledrake, closed 2023-05-29"
+[#3161]:https://github.com/puma/puma/pull/3161     "PR by @MSP-Greg, merged 2023-05-27"
+[#3037]:https://github.com/puma/puma/issues/3037   "Issue by @daisy1754, closed 2023-05-27"
+[#3133]:https://github.com/puma/puma/pull/3133     "PR by @stanhu, merged 2023-04-30"
+[#3132]:https://github.com/puma/puma/issues/3132   "Issue by @stanhu, closed 2023-04-30"
+[#3163]:https://github.com/puma/puma/pull/3163     "PR by @MSP-Greg, merged 2023-05-27"
+[#3155]:https://github.com/puma/puma/pull/3155     "PR by @dentarg, merged 2023-05-14"
+[#3148]:https://github.com/puma/puma/issues/3148   "Issue by @dentarg, closed 2023-05-14"
+[#3129]:https://github.com/puma/puma/pull/3129     "PR by @MSP-Greg, merged 2023-05-02"
+[#3137]:https://github.com/puma/puma/pull/3137     "PR by @MSP-Greg, merged 2023-04-30"
+[#3156]:https://github.com/puma/puma/pull/3156     "PR by @severin, merged 2023-05-16"
+[#3162]:https://github.com/puma/puma/pull/3162     "PR by @MSP-Greg, merged 2023-05-23"
+[#3151]:https://github.com/puma/puma/pull/3151     "PR by @nateberkopec, merged 2023-05-12"
+[#3118]:https://github.com/puma/puma/pull/3118     "PR by @ninoseki, merged 2023-04-01"
+[#3117]:https://github.com/puma/puma/issues/3117   "Issue by @ninoseki, closed 2023-04-01"
+[#3109]:https://github.com/puma/puma/pull/3109     "PR by @ahorek, merged 2023-03-31"
+[#3108]:https://github.com/puma/puma/issues/3108   "Issue by @treviateo, closed 2023-03-31"
+[#3113]:https://github.com/puma/puma/pull/3113     "PR by @collinsauve, merged 2023-03-31"
+[#3112]:https://github.com/puma/puma/issues/3112   "Issue by @dmke, closed 2023-03-31"
+[#3111]:https://github.com/puma/puma/pull/3111     "PR by @adzap, merged 2023-03-30"
+[#2770]:https://github.com/puma/puma/pull/2770     "PR by @vzajkov, merged 2023-03-29"
+[#2511]:https://github.com/puma/puma/issues/2511   "Issue by @jchristie55332, closed 2021-12-12"
+[#3089]:https://github.com/puma/puma/pull/3089     "PR by @Vuta, merged 2023-03-06"
+[#2709]:https://github.com/puma/puma/pull/2709     "PR by @rodzyn, merged 2023-02-20"
+[#3091]:https://github.com/puma/puma/pull/3091     "PR by @MSP-Greg, merged 2023-03-28"
+[#3074]:https://github.com/puma/puma/pull/3074     "PR by @MSP-Greg, merged 2023-03-14"
+[#3072]:https://github.com/puma/puma/pull/3072     "PR by @MSP-Greg, merged 2023-02-17"
+[#3079]:https://github.com/puma/puma/pull/3079     "PR by @mohamedhafez, merged 2023-02-24"
+[#3080]:https://github.com/puma/puma/pull/3080     "PR by @MSP-Greg, merged 2023-02-16"
+[#3058]:https://github.com/puma/puma/pull/3058     "PR by @dentarg, merged 2023-01-29"
+[#3007]:https://github.com/puma/puma/issues/3007   "Issue by @MSP-Greg, closed 2023-01-29"
+[#3011]:https://github.com/puma/puma/pull/3011     "PR by @joaomarcos96, merged 2023-01-03"
+[#3006]:https://github.com/puma/puma/pull/3006     "PR by @QWYNG, merged 2023-02-09"
+[#2604]:https://github.com/puma/puma/issues/2604   "Issue by @dgoetz, closed 2023-02-09"
+[#3040]:https://github.com/puma/puma/pull/3040     "PR by @shayonj, merged 2023-01-02"
+[#3036]:https://github.com/puma/puma/pull/3036     "PR by @MSP-Greg, merged 2023-01-13"
+[#3020]:https://github.com/puma/puma/issues/3020   "Issue by @dentarg, closed 2023-01-13"
+[#3061]:https://github.com/puma/puma/pull/3061     "PR by @MSP-Greg, merged 2023-02-12"
+[#3057]:https://github.com/puma/puma/issues/3057   "Issue by @mmarvb8h, closed 2023-02-12"
+[#3065]:https://github.com/puma/puma/pull/3065     "PR by @MSP-Greg, merged 2023-02-11"
+[#3062]:https://github.com/puma/puma/pull/3062     "PR by @willkoehler, merged 2023-01-29"
+[#3035]:https://github.com/puma/puma/pull/3035     "PR by @MSP-Greg, merged 2022-12-24"
+[#3033]:https://github.com/puma/puma/issues/3033   "Issue by @jules-w2, closed 2022-12-24"
+[#3016]:https://github.com/puma/puma/pull/3016     "PR by @MSP-Greg, merged 2022-12-24"
+[#3005]:https://github.com/puma/puma/pull/3005     "PR by @JuanitoFatas, merged 2022-11-04"
+[#3004]:https://github.com/puma/puma/pull/3004     "PR by @MSP-Greg, merged 2022-11-24"
+[#3000]:https://github.com/puma/puma/issues/3000   "Issue by @dentarg, closed 2022-11-24"
+[#3002]:https://github.com/puma/puma/pull/3002     "PR by @MSP-Greg, merged 2022-11-03"
+[#2999]:https://github.com/puma/puma/issues/2999   "Issue by @aymeric-ledorze, closed 2022-11-03"
+[#3013]:https://github.com/puma/puma/pull/3013     "PR by @MSP-Greg, merged 2022-11-13"
 [#2919]:https://github.com/puma/puma/pull/2919     "PR by @MSP-Greg, merged 2022-08-30"
 [#2652]:https://github.com/puma/puma/issues/2652   "Issue by @Roguelazer, closed 2022-09-04"
 [#2653]:https://github.com/puma/puma/pull/2653     "PR by @Roguelazer, closed 2022-03-07"
@@ -1928,7 +2104,10 @@ be added back in a future date when a java Puma::MiniSSL is added.
 [#2958]:https://github.com/puma/puma/pull/2958     "PR by @JuanitoFatas, merged 2022-09-16"
 [#2959]:https://github.com/puma/puma/pull/2959     "PR by @JuanitoFatas, merged 2022-09-16"
 [#2960]:https://github.com/puma/puma/pull/2960     "PR by @JuanitoFatas, merged 2022-09-16"
-[#2988]:https://github.com/puma/puma/issues/2988   "Issue by @MSP-Greg, merged 2022-10-12"
+[#2988]:https://github.com/puma/puma/pull/2988     "PR by @MSP-Greg, merged 2022-10-12"
+[#2928]:https://github.com/puma/puma/pull/2928     "PR by @nateberkopec, merged 2022-09-10"
+[#2798]:https://github.com/puma/puma/pull/2798     "PR by @johnnyshields, merged 2022-02-05"
+[#2932]:https://github.com/puma/puma/pull/2932     "PR by @mrzasa, merged 2022-09-12"
 [#2896]:https://github.com/puma/puma/pull/2896     "PR by @MSP-Greg, merged 2022-09-13"
 [#2892]:https://github.com/puma/puma/pull/2892     "PR by @guilleiguaran, closed 2022-09-13"
 [#2923]:https://github.com/puma/puma/pull/2923     "PR by @nateberkopec, merged 2022-09-09"
@@ -1949,11 +2128,9 @@ be added back in a future date when a java Puma::MiniSSL is added.
 [#2904]:https://github.com/puma/puma/pull/2904     "PR by @kares, merged 2022-08-27"
 [#2884]:https://github.com/puma/puma/pull/2884     "PR by @kares, merged 2022-05-30"
 [#2897]:https://github.com/puma/puma/pull/2897     "PR by @Edouard-chin, merged 2022-08-27"
-[#2932]:https://github.com/puma/puma/pull/2932     "PR by @mrzasa, merged 2022-09-12"
 [#1441]:https://github.com/puma/puma/issues/1441   "Issue by @nirvdrum, closed 2022-09-12"
 [#2956]:https://github.com/puma/puma/pull/2956     "PR by @MSP-Greg, merged 2022-09-15"
 [#2888]:https://github.com/puma/puma/pull/2888     "PR by @MSP-Greg, merged 2022-06-01"
-[#2798]:https://github.com/puma/puma/pull/2798     "PR by @johnnyshields, merged 2022-02-05"
 [#2797]:https://github.com/puma/puma/pull/2797     "PR by @johnnyshields, merged 2022-02-01"
 [#2795]:https://github.com/puma/puma/pull/2795     "PR by @johnnyshields, merged 2022-01-31"
 [#2903]:https://github.com/puma/puma/pull/2903     "PR by @MSP-Greg, merged 2022-08-27"
@@ -1961,6 +2138,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
 [#2921]:https://github.com/puma/puma/issues/2921   "Issue by @MSP-Greg, closed 2022-09-15"
 [#2922]:https://github.com/puma/puma/issues/2922   "Issue by @MSP-Greg, closed 2022-09-10"
 [#2955]:https://github.com/puma/puma/pull/2955     "PR by @cafedomancer, merged 2022-09-15"
+[#3166]:https://github.com/puma/puma/pull/3166     "PR by @JoeDupuis, merged 2023-06-08"
 [#2868]:https://github.com/puma/puma/pull/2868     "PR by @MSP-Greg, merged 2022-06-02"
 [#2866]:https://github.com/puma/puma/issues/2866   "Issue by @slondr, closed 2022-06-02"
 [#2883]:https://github.com/puma/puma/pull/2883     "PR by @MSP-Greg, merged 2022-06-02"
@@ -1987,7 +2165,7 @@ be added back in a future date when a java Puma::MiniSSL is added.
 [#2794]:https://github.com/puma/puma/pull/2794     "PR by @johnnyshields, merged 2022-01-10"
 [#2759]:https://github.com/puma/puma/pull/2759     "PR by @ob-stripe, merged 2021-12-11"
 [#2731]:https://github.com/puma/puma/pull/2731     "PR by @baelter, merged 2021-11-02"
-[#2341]:https://github.com/puma/puma/issues/2341   "Issue by @cjlarose, closed 2021-11-02"
+[#2341]:https://github.com/puma/puma/issues/2341   "Issue by @cjlarose, closed 2023-07-23"
 [#2728]:https://github.com/puma/puma/pull/2728     "PR by @dalibor, merged 2021-10-31"
 [#2733]:https://github.com/puma/puma/pull/2733     "PR by @ob-stripe, merged 2021-12-12"
 [#2807]:https://github.com/puma/puma/pull/2807     "PR by @MSP-Greg, merged 2022-01-25"

data/README.md

@@ -12,11 +12,15 @@ Puma is a **simple, fast, multi-threaded, and highly parallel HTTP 1.1 server fo
 
 ## Built For Speed & Parallelism
 
-Puma processes requests using a C-optimized Ragel extension (inherited from Mongrel) that provides fast, accurate HTTP 1.1 protocol parsing in a portable way. Puma then serves the request using a thread pool. Each request is served in a separate thread, so truly parallel Ruby implementations (JRuby, Rubinius) will use all available CPU cores.
+Puma is a server for [Rack](https://github.com/rack/rack)-powered HTTP applications written in Ruby.  It is: 
+* **Multi-threaded**. Each request is served in a separate thread. This helps you serve more requests per second with less memory use.
+* **Multi-process**. "Pre-forks" in cluster mode, using less memory per-process thanks to copy-on-write memory.
+* **Standalone**. With SSL support, zero-downtime rolling restarts and a built-in request bufferer, you can deploy Puma without any reverse proxy.
+* **Battle-tested**. Our HTTP parser is inherited from Mongrel and has over 15 years of production use. Puma is currently the most popular Ruby webserver, and is the default server for Ruby on Rails.
 
 Originally designed as a server for [Rubinius](https://github.com/rubinius/rubinius), Puma also works well with Ruby (MRI) and JRuby.
 
-On MRI, there is a Global VM Lock (GVL) that ensures only one thread can run Ruby code at a time. But if you're doing a lot of blocking IO (such as HTTP calls to external APIs like Twitter), Puma still improves MRI's throughput by allowing IO waiting to be done in parallel.
+On MRI, there is a Global VM Lock (GVL) that ensures only one thread can run Ruby code at a time. But if you're doing a lot of blocking IO (such as HTTP calls to external APIs like Twitter), Puma still improves MRI's throughput by allowing IO waiting to be done in parallel. Truly parallel Ruby implementations (TruffleRuby, JRuby) don't have this limitation.
 
 ## Quick Start
 
@@ -114,6 +118,8 @@ $ WEB_CONCURRENCY=3 puma -t 8:32
 
 Note that threads are still used in clustered mode, and the `-t` thread flag setting is per worker, so `-w 2 -t 16:16` will spawn 32 threads in total, with 16 in each worker process.
 
+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).
+
 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).
 
 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:
@@ -157,6 +163,15 @@ before_fork do
 end
 ```
 
+You can also specify a block to be run after puma is booted using `on_booted`:
+
+```ruby
+# config/puma.rb
+on_booted do
+  # configuration here
+end
+```
+
 ### Error handling
 
 If puma encounters an error outside of the context of your application, it will respond with a 500 and a simple
@@ -202,29 +217,32 @@ Puma supports the [`localhost`] gem for self-signed certificates. This is partic
 
 Puma automatically configures SSL when the [`localhost`] gem is loaded in a `development` environment:
 
+Add the gem to your Gemfile:
 ```ruby
-# Add the gem to your Gemfile
 group(:development) do
   gem 'localhost'
 end
+```
 
-# And require it implicitly using bundler
+And require it implicitly using bundler:
+```ruby
 require "bundler"
 Bundler.require(:default, ENV["RACK_ENV"].to_sym)
+```
 
-# Alternatively, you can require the gem in config.ru:
-require './app'
+Alternatively, you can require the gem in your configuration file, either `config/puma/development.rb`, `config/puma.rb`, or set via the `-C` cli option:
+```ruby
 require 'localhost'
-run Sinatra::Application
+# configuration methods (from Puma::DSL) as needed
 ```
 
 Additionally, Puma must be listening to an SSL socket:
 
 ```shell
-$ puma -b 'ssl://localhost:9292' config.ru
+$ puma -b 'ssl://localhost:9292' -C config/use_local_host.rb
 
 # The following options allow you to reach Puma over HTTP as well:
-$ puma -b ssl://localhost:9292 -b tcp://localhost:9393 config.ru
+$ puma -b ssl://localhost:9292 -b tcp://localhost:9393 -C config/use_local_host.rb
 ```
 
 [`localhost`]: https://github.com/socketry/localhost
@@ -270,6 +288,30 @@ $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&verification_f
 List of available flags: `USE_CHECK_TIME`, `CRL_CHECK`, `CRL_CHECK_ALL`, `IGNORE_CRITICAL`, `X509_STRICT`, `ALLOW_PROXY_CERTS`, `POLICY_CHECK`, `EXPLICIT_POLICY`, `INHIBIT_ANY`, `INHIBIT_MAP`, `NOTIFY_POLICY`, `EXTENDED_CRL_SUPPORT`, `USE_DELTAS`, `CHECK_SS_SIGNATURE`, `TRUSTED_FIRST`, `SUITEB_128_LOS_ONLY`, `SUITEB_192_LOS`, `SUITEB_128_LOS`, `PARTIAL_CHAIN`, `NO_ALT_CHAINS`, `NO_CHECK_TIME`
 (see https://www.openssl.org/docs/manmaster/man3/X509_VERIFY_PARAM_set_hostflags.html#VERIFICATION-FLAGS).
 
+#### Controlling OpenSSL Password Decryption
+
+To enable runtime decryption of an encrypted SSL key (not available for JRuby), use `key_password_command`:
+
+```
+$ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&key_password_command=/path/to/command.sh'
+```
+
+`key_password_command` must:
+
+1. Be executable by Puma.
+2. Print the decryption password to stdout.
+
+ For example:
+
+```shell
+#!/bin/sh
+
+echo "this is my password"
+```
+
+`key_password_command` can be used with `key` or `key_pem`. If the key
+is not encrypted, the executable will not be called.
+
 ### Control/Status Server
 
 Puma has a built-in status and control app that can be used to query and control Puma.
@@ -345,11 +387,13 @@ end
 
 ## Deployment
 
-Puma has support for Capistrano with an [external gem](https://github.com/seuros/capistrano-puma).
+ * Puma has support for Capistrano with an [external gem](https://github.com/seuros/capistrano-puma).
+
+ * Additionally, Puma has support for built-in daemonization via the [puma-daemon](https://github.com/kigster/puma-daemon) ruby gem. The gem restores the `daemonize` option that was removed from Puma starting version 5, but only for MRI Ruby.
+
 
 It is common to use process monitors with Puma. Modern process monitors like systemd or rc.d
-provide continuous monitoring and restarts for increased
-reliability in production environments:
+provide continuous monitoring and restarts for increased reliability in production environments:
 
 * [rc.d](docs/jungle/rc.d/README.md)
 * [systemd](docs/systemd.md)
@@ -364,7 +408,8 @@ Community guides:
 
 * [puma-metrics](https://github.com/harmjanblok/puma-metrics) — export Puma metrics to Prometheus
 * [puma-plugin-statsd](https://github.com/yob/puma-plugin-statsd) — send Puma metrics to statsd
-* [puma-plugin-systemd](https://github.com/sj26/puma-plugin-systemd) — deeper integration with systemd for notify, status and watchdog
+* [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.
+* [puma-plugin-telemetry](https://github.com/babbel/puma-plugin-telemetry) - telemetry plugin for Puma offering various targets to publish
 
 ### Monitoring
 

data/docs/kubernetes.md

@@ -64,3 +64,15 @@ There is a subtle race condition between step 2 and 3: The replication controlle
 The way Kubernetes works this way, rather than handling step 2 synchronously, is due to the CAP theorem: in a distributed system there is no way to guarantee that any message will arrive promptly. In particular, waiting for all Service controllers to report back might get stuck for an indefinite time if one of them has already been terminated or if there has been a net split. A way to work around this is to add a sleep to the pre-stop hook of the same time as the `terminationGracePeriodSeconds` time. This will allow the Puma process to keep serving new requests during the entire grace period, although it will no longer receive new requests after all Service controllers have propagated the removal of the pod from their endpoint lists. Then, after `terminationGracePeriodSeconds`, the pod receives `SIGKILL` and closes down. If your process can't handle SIGKILL properly, for example because it needs to release locks in different services, you can also sleep for a shorter period (and/or increase `terminationGracePeriodSeconds`) as long as the time slept is longer than the time that your Service controllers take to propagate the pod removal. The downside of this workaround is that all pods will take at minimum the amount of time slept to shut down and this will increase the time required for your rolling deploy.
 
 More discussions and links to relevant articles can be found in https://github.com/puma/puma/issues/2343.
+
+## Workers Per Pod, and Other Config Issues
+
+With containerization, you will have to make a decision about how "big" to make each pod. 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.
+
+* 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.
+* 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%) will lead to additional request queueing time (latency!) and additional memory usage.
+* 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.
+* Don't run less than 4 processes per pod if you can. Low numbers of processes per pod will lead to high request queueing, which means you will have to run more pods.
+* If multithreaded, allocate 1 CPU 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.
+* 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).
+

data/docs/nginx.md

@@ -2,7 +2,7 @@
 
 This is a very common setup using an upstream. It was adapted from some Capistrano recipe I found on the Internet a while ago.
 
-```
+```nginx
 upstream myapp {
   server unix:///myapp/tmp/puma.sock;
 }

data/docs/systemd.md

@@ -24,8 +24,7 @@ After=network.target
 
 [Service]
 # Puma supports systemd's `Type=notify` and watchdog service
-# monitoring, if the [sd_notify](https://github.com/agis/ruby-sdnotify) gem is installed,
-# as of Puma 5.1 or later.
+# monitoring, as of Puma 5.1 or later.
 # On earlier versions of Puma or JRuby, change this to `Type=simple` and remove
 # the `WatchdogSec` line.
 Type=notify