puma 3.12.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bff4687b24c136075e00b45d5314fd6326b6240733fff22c706096d10d8ec965
-  data.tar.gz: db2020f983ba02f7403e50f9f9391bd2f20e811fa42121147d4cbaf619e1d8d3
+  metadata.gz: 124069677cb83205250fa0e90d7621739cb76da2f594dc661681f9d39e14227e
+  data.tar.gz: c58f64c5d4423ffb14d866bd820aaf4a3c0162f38ee75e638a831f226d9169ff
 SHA512:
-  metadata.gz: d6d7efcb9aeb437c07f49cb5a589ed016d888acab08f130bb382f2d470b301ec40ce3df90fbe4cf989bc84468633b180894c60daca377346d283210e6fedba98
-  data.tar.gz: 2d45380434e8d88d534a27db1a1f843d70b925a64065d55ee637153669b3c78f1539bf4c84ee166ec90636ba3ee948a97540c0bdbac5cc3d68809c86874038f8
+  metadata.gz: 4ff75723d3e55450ba94897c1a0390f3040d74a28d56715ef6bda84af231a714c5739609db57fba443872d69c4bd7029ae0940726fd2b43fd328241cd1068680
+  data.tar.gz: ab2ff29b3181ab5ddea9975eadbdff33f582e7dbca26bd5eb4f429ae1ed31b0cdd10631f32bd4a9760a2a3b37fedef2fa91c3f33bf39fb944aa3041e7550d9b7

data/History.md

@@ -1,3 +1,225 @@
+## 5.0.0
+
+* Features
+  * Allow compiling without OpenSSL and dynamically load files needed for SSL, add 'no ssl' CI (#2305)
+  * EXPERIMENTAL: Add `fork_worker` option and `refork` command for reduced memory usage by forking from a worker process instead of the master process. (#2099)
+  * EXPERIMENTAL: Added `wait_for_less_busy_worker` config. This may reduce latency on MRI through inserting a small delay before re-listening on the socket if worker is busy (#2079).
+  * EXPERIMENTAL: Added `nakayoshi_fork` option. Reduce memory usage in preloaded cluster-mode apps by GCing before fork and compacting, where available. (#2093, #2256)
+  * Added pumactl `thread-backtraces` command to print thread backtraces (#2054)
+  * Added incrementing `requests_count` to `Puma.stats`. (#2106)
+  * Increased maximum URI path length from 2048 to 8192 bytes (#2167, #2344)
+  * `lowlevel_error_handler` is now called during a forced threadpool shutdown, and if a callable with 3 arguments is set, we now also pass the status code (#2203)
+  * Faster phased restart and worker timeout (#2220)
+  * Added `state_permission` to config DSL to set state file permissions (#2238)
+  * Added `Puma.stats_hash`, which returns a stats in Hash instead of a JSON string (#2086, #2253)
+  * `rack.multithread` and `rack.multiprocess` now dynamically resolved by `max_thread` and `workers` respectively (#2288)
+
+* Deprecations, Removals and Breaking API Changes
+  * `--control` has been removed. Use `--control-url` (#1487)
+  * `worker_directory` has been removed. Use `directory`.
+  * min_threads now set by environment variables PUMA_MIN_THREADS and MIN_THREADS. (#2143)
+  * max_threads now set by environment variables PUMA_MAX_THREADS and MAX_THREADS. (#2143)
+  * max_threads default to 5 in MRI or 16 for all other interpreters. (#2143)
+  * preload by default if workers > 1 (#2143)
+  * Puma::Plugin.workers_supported? has been removed. Use Puma.forkable? instead. (#2143)
+  * `tcp_mode` has been removed without replacement. (#2169)
+  * Daemonization has been removed without replacement. (#2170)
+  * Changed #connected_port to #connected_ports (#2076)
+  * Configuration: `environment` is read from `RAILS_ENV`, if `RACK_ENV` can't be found (#2022)
+  * Log binding on http:// for TCP bindings to make it clickable
+
+* Bugfixes
+  * Fix JSON loading issues on phased-restarts (#2269)
+  * Improve shutdown reliability (#2312, #2338)
+  * Close client http connections made to an ssl server with TLSv1.3 (#2116)
+  * Do not set user_config to quiet by default to allow for file config (#2074)
+  * Always close SSL connection in Puma::ControlCLI (#2211)
+  * Windows update extconf.rb for use with ssp and varied Ruby/MSYS2 combinations (#2069)
+  * Ensure control server Unix socket is closed on shutdown (#2112)
+  * Preserve `BUNDLE_GEMFILE` env var when using `prune_bundler` (#1893)
+  * Send 408 request timeout even when queue requests is disabled (#2119)
+  * Rescue IO::WaitReadable instead of EAGAIN for blocking read (#2121)
+  * Ensure `BUNDLE_GEMFILE` is unspecified in workers if unspecified in master when using `prune_bundler` (#2154)
+  * Rescue and log exceptions in hooks defined by users (on_worker_boot, after_worker_fork etc) (#1551)
+  * Read directly from the socket in #read_and_drop to avoid raising further SSL errors (#2198)
+  * Set `Connection: closed` header when queue requests is disabled (#2216)
+  * Pass queued requests to thread pool on server shutdown (#2122)
+  * Fixed a few minor concurrency bugs in ThreadPool that may have affected non-GVL Rubies (#2220)
+  * Fix `out_of_band` hook never executed if the number of worker threads is > 1 (#2177)
+  * Fix ThreadPool#shutdown timeout accuracy (#2221)
+  * Fix `UserFileDefaultOptions#fetch` to properly use `default` (#2233)
+  * Improvements to `out_of_band` hook (#2234)
+  * Prefer the rackup file specified by the CLI (#2225)
+  * Fix for spawning subprocesses with fork_worker option (#2267)
+  * Set `CONTENT_LENGTH` for chunked requests (#2287)
+  * JRuby - Add Puma::MiniSSL::Engine#init? and #teardown methods, run all SSL tests (#2317)
+  * Improve shutdown reliability (#2312)
+  * Resolve issue with threadpool waiting counter decrement when thread is killed
+  * Constrain rake-compiler version to 0.9.4 to fix `ClassNotFound` exception when using MiniSSL with Java8.
+  * Fix recursive `prune_bundler` (#2319).
+  * Ensure that TCP_CORK is usable
+  * Fix corner case when request body is chunked (#2326)
+  * Fix filehandle leak in MiniSSL (#2299)
+
+* Refactor
+  * Remove unused loader argument from Plugin initializer (#2095)
+  * Simplify `Configuration.random_token` and remove insecure fallback (#2102)
+  * Simplify `Runner#start_control` URL parsing (#2111)
+  * Removed the IOBuffer extension and replaced with Ruby (#1980)
+  * Update `Rack::Handler::Puma.run` to use `**options` (#2189)
+  * ThreadPool concurrency refactoring (#2220)
+  * JSON parse cluster worker stats instead of regex (#2124)
+  * Support parallel tests in verbose progress reporting (#2223)
+  * Refactor error handling in server accept loop (#2239)
+
+## 4.3.6 / 2020-09-05
+
+* Bugfixes
+  * Explicitly include ctype.h to fix compilation warning and build error on macOS with Xcode 12 (#2304)
+  * Don't require json at boot (#2269)
+
+## 4.3.4/4.3.5 and 3.12.5/3.12.6 / 2020-05-22
+
+Each patchlevel release contains a separate security fix. We recommend simply upgrading to 4.3.5/3.12.6.
+
+* Security
+  * Fix: Fixed two separate HTTP smuggling vulnerabilities that used the Transfer-Encoding header. CVE-2020-11076 and CVE-2020-11077.
+
+## 4.3.3 and 3.12.4 / 2020-02-28
+
+* Bugfixes
+  * Fix: Fixes a problem where we weren't splitting headers correctly on newlines (#2132)
+* Security
+  * Fix: Prevent HTTP Response splitting via CR in early hints. CVE-2020-5249.
+
+## 4.3.2 and 3.12.3 / 2020-02-27 (YANKED)
+
+* Security
+  * Fix: Prevent HTTP Response splitting via CR/LF in header values. CVE-2020-5247.
+
+## 4.3.1 and 3.12.2 / 2019-12-05
+
+* Security
+  * Fix: a poorly-behaved client could use keepalive requests to monopolize Puma's reactor and create a denial of service attack. CVE-2019-16770.
+
+## 4.3.0 / 2019-11-07
+
+* Features
+  * Strip whitespace at end of HTTP headers (#2010)
+  * Optimize HTTP parser for JRuby (#2012)
+  * Add SSL support for the control app and cli (#2046, #2052)
+
+* Bugfixes
+  * Fix Errno::EINVAL when SSL is enabled and browser rejects cert (#1564)
+  * Fix pumactl defaulting puma to development if an environment was not specified (#2035)
+  * Fix closing file stream when reading pid from pidfile (#2048)
+  * Fix a typo in configuration option `--extra_runtime_dependencies` (#2050)
+
+## 4.2.1 / 2019-10-07
+
+* 3 bugfixes
+  * Fix socket activation of systemd (pre-existing) unix binder files (#1842, #1988)
+  * Deal with multiple calls to bind correctly (#1986, #1994, #2006)
+  * Accepts symbols for `verify_mode` (#1222)
+
+## 4.2.0 / 2019-09-23
+
+* 6 features
+  * Pumactl has a new -e environment option and reads `config/puma/<environment>.rb` config files (#1885)
+  * Semicolons are now allowed in URL paths (MRI only), useful for Angular or Redmine (#1934)
+  * Allow extra dependencies to be defined when using prune_bundler (#1105)
+  * Puma now reports the correct port when binding to port 0, also reports other listeners when binding to localhost (#1786)
+  * Sending SIGINFO to any Puma worker now prints currently active threads and their backtraces (#1320)
+  * Puma threads all now have their name set on Ruby 2.3+ (#1968)
+* 4 bugfixes
+  * Fix some misbehavior with phased restart and externally SIGTERMed workers (#1908, #1952)
+  * Fix socket closing on error (#1941)
+  * Removed unnecessary SIGINT trap for JRuby that caused some race conditions (#1961)
+  * Fix socket files being left around after process stopped (#1970)
+* Absolutely thousands of lines of test improvements and fixes thanks to @MSP-Greg
+
+## 4.1.1 / 2019-09-05
+
+* 3 bugfixes
+  * Revert our attempt to not dup STDOUT/STDERR (#1946)
+  * Fix socket close on error (#1941)
+  * Fix workers not shutting down correctly (#1908)
+
+## 4.1.0 / 2019-08-08
+
+* 4 features
+  * Add REQUEST_PATH on parse error message (#1831)
+  * You can now easily add custom log formatters with the `log_formatter` config option (#1816)
+  * Puma.stats now provides process start times (#1844)
+  * Add support for disabling TLSv1.1 (#1836)
+
+* 7 bugfixes
+  * Fix issue where Puma was creating zombie process entries (#1887)
+  * Fix bugs with line-endings and chunked encoding (#1812)
+  * RACK_URL_SCHEME is now set correctly in all conditions (#1491)
+  * We no longer mutate global STDOUT/STDERR, particularly the sync setting (#1837)
+  * SSL read_nonblock no longer blocks (#1857)
+  * Swallow connection errors when sending early hints (#1822)
+  * Backtrace no longer dumped when invalid pumactl commands are run (#1863)
+
+* 5 other
+  * Avoid casting worker_timeout twice (#1838)
+  * Removed a call to private that wasn't doing anything (#1882)
+  * README, Rakefile, docs and test cleanups (#1848, #1847, #1846, #1853, #1859, #1850, #1866, #1870, #1872, #1833, #1888)
+  * Puma.io has proper documentation now (https://puma.io/puma/)
+  * Added the Contributor Covenant CoC
+
+* 1 known issue
+  * Some users are still experiencing issues surrounding socket activation and Unix sockets (#1842)
+
+## 4.0.1 / 2019-07-11
+
+* 2 bugfixes
+  * Fix socket removed after reload - should fix problems with systemd socket activation. (#1829)
+  * Add extconf tests for DTLS_method & TLS_server_method, use in minissl.rb. Should fix "undefined symbol: DTLS_method" when compiling against old OpenSSL versions. (#1832)
+* 1 other
+  * Removed unnecessary RUBY_VERSION checks. (#1827)
+
+## 4.0.0 / 2019-06-25
+
+* 9 features
+  * Add support for disabling TLSv1.0 (#1562)
+  * Request body read time metric (#1569)
+  * Add out_of_band hook (#1648)
+  * Re-implement (native) IOBuffer for JRuby (#1691)
+  * Min worker timeout (#1716)
+  * Add option to suppress SignalException on SIGTERM (#1690)
+  * Allow mutual TLS CA to be set using `ssl_bind` DSL (#1689)
+  * Reactor now uses nio4r instead of `select` (#1728)
+  * Add status to pumactl with pidfile (#1824)
+
+* 10 bugfixes
+  * Do not accept new requests on shutdown (#1685, #1808)
+  * Fix 3 corner cases when request body is chunked (#1508)
+  * Change pid existence check's condition branches (#1650)
+  * Don't call .stop on a server that doesn't exist (#1655)
+  * Implemented NID_X9_62_prime256v1 (P-256) curve over P-521 (#1671)
+  * Fix @notify.close can't modify frozen IOError (RuntimeError) (#1583)
+  * Fix Java 8 support (#1773)
+  * Fix error `uninitialized constant Puma::Cluster` (#1731)
+  * Fix `not_token` being able to be set to true (#1803)
+  * Fix "Hang on SIGTERM with ruby 2.6 in clustered mode" ([PR #1741], [#1674], [#1720], [#1730], [#1755])
+
+[PR #1741]: https://github.com/puma/puma/pull/1741
+[#1674]: https://github.com/puma/puma/issues/1674
+[#1720]: https://github.com/puma/puma/issues/1720
+[#1730]: https://github.com/puma/puma/issues/1730
+[#1755]: https://github.com/puma/puma/issues/1755
+
+## 3.12.1 / 2019-03-19
+
+* 1 features
+  * Internal strings are frozen (#1649)
+* 3 bugfixes
+  * Fix chunked ending check (#1607)
+  * Rack handler should use provided default host (#1700)
+  * Better support for detecting runtimes that support `fork` (#1630)
+
 ## 3.12.0 / 2018-07-13
 
 * 5 features:
@@ -1395,3 +1617,12 @@ be added back in a future date when a java Puma::MiniSSL is added.
 ## 1.0.0 / 2012-03-29
 
 * Released!
+
+## Ignore - this is for maintainers to copy-paste during release
+## Master
+
+* Features
+  * Your feature goes here (#Github Number)
+
+* Bugfixes
+  * Your bugfix goes here (#Github Number)

data/LICENSE

@@ -1,26 +1,29 @@
-Some code copyright (c) 2005, Zed Shaw
-Copyright (c) 2011, Evan Phoenix
+BSD 3-Clause License
+
+Copyright (c) 2019, Evan Phoenix. Some code by Zed Shaw, (c) 2005.
 All rights reserved.
 
-Redistribution and use in source and binary forms, with or without 
+Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-* Redistributions in binary form must reproduce the above copyright notice
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-* Neither the name of the Evan Phoenix nor the names of its contributors 
-  may be used to endorse or promote products derived from this software 
-  without specific prior written permission.
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -1,45 +1,55 @@
 <p align="center">
-  <img src="http://puma.io/images/logos/puma-logo-large.png">
+  <img src="https://puma.io/images/logos/puma-logo-large.png">
 </p>
 
 # Puma: A Ruby Web Server Built For Concurrency
 
-[![Gitter](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/puma/puma?utm\_source=badge&utm\_medium=badge&utm\_campaign=pr-badge)
-[![Build Status](https://secure.travis-ci.org/puma/puma.svg)](http://travis-ci.org/puma/puma)
-[![AppVeyor](https://img.shields.io/appveyor/ci/nateberkopec/puma.svg)](https://ci.appveyor.com/project/nateberkopec/puma)
-[![Dependency Status](https://gemnasium.com/puma/puma.svg)](https://gemnasium.com/puma/puma)
+[![Actions Build Status](https://github.com/puma/puma/workflows/CI/badge.svg?branch=master)](https://github.com/puma/puma/actions)
 [![Code Climate](https://codeclimate.com/github/puma/puma.svg)](https://codeclimate.com/github/puma/puma)
+[![SemVer](https://api.dependabot.com/badges/compatibility_score?dependency-name=puma&package-manager=bundler&version-scheme=semver)](https://dependabot.com/compatibility-score.html?dependency-name=puma&package-manager=bundler&version-scheme=semver)
+[![StackOverflow](https://img.shields.io/badge/stackoverflow-Puma-blue.svg)]( https://stackoverflow.com/questions/tagged/puma )
 
-Puma is a **simple, fast, threaded, and highly concurrent HTTP 1.1 server for Ruby/Rack applications** in development and production.
+Puma is a **simple, fast, multi-threaded, and highly concurrent HTTP 1.1 server for Ruby/Rack applications**.
 
 ## Built For Speed &amp; Concurrency
 
-Under the hood, 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 in a thread from an internal thread pool. Since each request is served in a separate thread, truly concurrent Ruby implementations (JRuby, Rubinius) will use all available CPU cores.
+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 concurrent Ruby implementations (JRuby, Rubinius) will use all available CPU cores.
 
-Puma was designed to be the go-to server for [Rubinius](http://rubini.us), but also works well with JRuby and MRI.
+Puma was designed to be the go-to server for [Rubinius](https://rubinius.com), but also works well with JRuby and MRI.
 
-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 blocking IO to be run concurrently.
+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.
 
 ## Quick Start
 
 ```
 $ gem install puma
-$ puma <any rackup (*.ru) file>
-```  
+$ puma
+```
+
+Without arguments, puma will look for a rackup (.ru) file in
+working directory called `config.ru`.
+
+## SSL Connection Support
+
+Puma will install/compile with support for ssl sockets, assuming OpenSSL
+development files are installed on the system.
+
+If the system does not have OpenSSL development files installed, Puma will
+install/compile, but it will not allow ssl connections.
 
 ## Frameworks
 
 ### Rails
 
-Puma is the default server for Rails, and should already be included in your Gemfile.
+Puma is the default server for Rails, included in the generated Gemfile.
 
-Then start your server with the `rails` command:
+Start your server with the `rails` command:
 
 ```
-$ rails s
+$ rails server
 ```
 
-Many configuration options are not available when using `rails s`. It is recommended that you use Puma's executable instead:
+Many configuration options and Puma features are not available when using `rails server`. It is recommended that you use Puma's executable instead:
 
 ```
 $ bundle exec puma
@@ -53,7 +63,7 @@ You can run your Sinatra application with Puma from the command line like this:
 $ ruby app.rb -s Puma
 ```
 
-Or you can configure your application to always use Puma:
+Or you can configure your Sinatra application to always use Puma:
 
 ```ruby
 require 'sinatra'
@@ -64,6 +74,9 @@ configure { set :server, :puma }
 
 Puma provides numerous options. Consult `puma -h` (or `puma --help`) for a full list of CLI options, or see [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb).
 
+You can also find several configuration examples as part of the
+[test](https://github.com/puma/puma/tree/master/test/config) suite.
+
 ### Thread Pool
 
 Puma uses a thread pool. You can set the minimum and maximum number of threads that are available in the pool with the `-t` (or `--threads`) flag:
@@ -72,9 +85,9 @@ Puma uses a thread pool. You can set the minimum and maximum number of threads t
 $ puma -t 8:32
 ```
 
-Puma will automatically scale the number of threads, from the minimum until it caps out at the maximum, based on how much traffic is present. The current default is `0:16`. Feel free to experiment, but be careful not to set the number of maximum threads to a large number, as you may exhaust resources on the system (or hit resource limits).
+Puma will automatically scale the number of threads, from the minimum until it caps out at the maximum, based on how much traffic is present. The current default is `0:16` and on MRI is `0:5`. Feel free to experiment, but be careful not to set the number of maximum threads to a large number, as you may exhaust resources on the system (or cause contention for the Global VM Lock, when using MRI).
 
-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.
+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.
 
 ### Clustered mode
 
@@ -84,9 +97,9 @@ Puma also offers "clustered mode". Clustered mode `fork`s workers from a master
 $ puma -t 8:32 -w 3
 ```
 
-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.
+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.
 
-In clustered mode, Puma may "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) (Ruby 2.0+ only). Use the `--preload` flag from the command line:
+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) (Ruby 2.0+ only). Use the `--preload` flag from the command line:
 
 ```
 $ puma -w 3 --preload
@@ -111,40 +124,42 @@ end
 
 This code can be used to setup the process before booting the application, allowing
 you to do some Puma-specific things that you don't want to embed in your application.
-For instance, you could fire a log notification that a worker booted or send something to statsd.
-This can be called multiple times.
+For instance, you could fire a log notification that a worker booted or send something to statsd. This can be called multiple times.
 
-If you're preloading your application and using ActiveRecord, it's recommended that you setup your connection pool here:
+`before_fork` specifies a block to be run before workers are forked:
 
 ```ruby
 # config/puma.rb
-on_worker_boot do
-  ActiveSupport.on_load(:active_record) do
-    ActiveRecord::Base.establish_connection
-  end
+before_fork do
+  # configuration here
 end
 ```
 
-On top of that, you can specify a block in your configuration file that will be run before workers are forked:
+Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preload_app copies the code of master into the workers.
+
+### Error handling
+
+If puma encounters an error outside of the context of your application, it will respond with a 500 and a simple
+textual error message (see `lowlevel_error` in [this file](https://github.com/puma/puma/blob/master/lib/puma/server.rb)).
+You can specify custom behavior for this scenario. For example, you can report the error to your third-party
+error-tracking service (in this example, [rollbar](https://rollbar.com)):
 
 ```ruby
-# config/puma.rb
-before_fork do
-  # configuration here
+lowlevel_error_handler do |e|
+  Rollbar.critical(e)
+  [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"]]
 end
 ```
 
-Preloading can’t be used with phased restart, since phased restart kills and restarts workers one-by-one, and preload_app copies the code of master into the workers.
-
 ### Binding TCP / Sockets
 
-In contrast to many other server configs which require multiple flags, Puma simply uses one URI parameter with the `-b` (or `--bind`) flag:
+Bind Puma to a socket with the `-b` (or `--bind`) flag:
 
 ```
 $ puma -b tcp://127.0.0.1:9292
 ```
 
-Want to use UNIX Sockets instead of TCP (which can provide a 5-10% performance boost)?
+To use a UNIX Socket instead of TCP:
 
 ```
 $ puma -b unix:///var/run/puma.sock
@@ -157,30 +172,44 @@ $ puma -b 'unix:///var/run/puma.sock?umask=0111'
 ```
 
 Need a bit of security? Use SSL sockets:
+
 ```
 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert'
 ```
+
 #### Controlling SSL Cipher Suites
-Need to use or avoid specific SSL cipher suites? Use ssl_cipher_filter or ssl_cipher_list options.
-#####Ruby:
+
+To use or avoid specific SSL cipher suites, use `ssl_cipher_filter` or `ssl_cipher_list` options.
+
+##### Ruby:
+
 ```
 $ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&ssl_cipher_filter=!aNULL:AES+SHA'
 ```
-#####JRuby:
+
+##### JRuby:
+
 ```
 $ 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'
 ```
+
 See https://www.openssl.org/docs/man1.0.2/apps/ciphers.html for cipher filter format and full list of cipher suites.
 
+Disable TLS v1 with the `no_tlsv1` option:
+
+```
+$ puma -b 'ssl://127.0.0.1:9292?key=path_to_key&cert=path_to_cert&no_tlsv1=true'
+```
+
 ### Control/Status Server
 
-Puma has a built-in status/control app that can be used to query and control Puma itself.
+Puma has a built-in status and control app that can be used to query and control Puma.
 
 ```
 $ puma --control-url tcp://127.0.0.1:9293 --control-token foo
 ```
 
-Puma will start the control server on localhost port 9293. All requests to the control server will need to include `token=foo` as a query parameter. This allows for simple authentication. Check out [status.rb](https://github.com/puma/puma/blob/master/lib/puma/app/status.rb) to see what the app has available.
+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 [status.rb](https://github.com/puma/puma/blob/master/lib/puma/app/status.rb) to see what the status app has available.
 
 You can also interact with the control server via `pumactl`. This command will restart Puma:
 
@@ -192,13 +221,13 @@ To see a list of `pumactl` options, use `pumactl --help`.
 
 ### Configuration File
 
-You can also provide a configuration file which Puma will use with the `-C` (or `--config`) flag:
+You can also provide a configuration file with the `-C` (or `--config`) flag:
 
 ```
 $ puma -C /path/to/config
 ```
 
-If no configuration file is specified, Puma will look for a configuration file at `config/puma.rb`. If an environment is specified, either via the `-e` and `--environment` flags, or through the `RACK_ENV` environment variable, the default file location will be `config/puma/environment_name.rb`.
+If no configuration file is specified, Puma will look for a configuration file at `config/puma.rb`. If an environment is specified, either via the `-e` and `--environment` flags, or through the `RACK_ENV` or the `RAILS_ENV` environment variables, Puma looks for configuration at `config/puma/<environment_name>.rb`.
 
 If you want to prevent Puma from looking for a configuration file in those locations, provide a dash as the argument to the `-C` (or `--config`) flag:
 
@@ -206,7 +235,9 @@ If you want to prevent Puma from looking for a configuration file in those locat
 $ puma -C "-"
 ```
 
-Take the following [sample configuration](https://github.com/puma/puma/blob/master/examples/config.rb) as inspiration or check out [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb) to see all available options.
+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 [here](https://github.com/puma/puma/blob/12d1706ddc71b89ed2ee26275e31c788e94ff541/lib/puma/configuration.rb#L170).
+
+Check out [dsl.rb](https://github.com/puma/puma/blob/master/lib/puma/dsl.rb) to see all available options.
 
 ## Restart
 
@@ -223,11 +254,11 @@ Puma responds to several signals. A detailed guide to using UNIX signals with Pu
 Some platforms do not support all Puma features.
 
   * **JRuby**, **Windows**: server sockets are not seamless on restart, they must be closed and reopened. These platforms have no way to pass descriptors into a new process that is exposed to Ruby. Also, cluster mode is not supported due to a lack of fork(2).
-  * **Windows**: daemon mode is not supported due to a lack of fork(2).
+  * **Windows**: Cluster mode is not supported due to a lack of fork(2).
 
 ## Known Bugs
 
-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:
+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:
 
 ```ruby
 if %w(2.2.7 2.2.8 2.2.9 2.2.10 2.3.4 2.4.1).include? RUBY_VERSION
@@ -246,17 +277,27 @@ It is common to use process monitors with Puma. Modern process monitors like sys
 provide continuous monitoring and restarts for increased
 reliability in production environments:
 
-* [tools/jungle](https://github.com/puma/puma/tree/master/tools/jungle) for sysvinit (init.d) and upstart
+* [docs/jungle](https://github.com/puma/puma/tree/master/docs/jungle) for rc.d and upstart
 * [docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md)
 
+## Community Extensions
+
+### Plugins
+
+* [puma-heroku](https://github.com/puma/puma-heroku) — default Puma configuration for running on Heroku
+* [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
+
+### Monitoring
+
+* [puma-status](https://github.com/ylecuyer/puma-status) — Monitor CPU/Mem/Load of running puma instances from the CLI
+
 ## Contributing
 
-To run the test suite:
+Find details for contributing in the [contribution guide].
 
-```bash
-$ bundle install
-$ bundle exec rake
-```
+[contribution guide]: https://github.com/puma/puma/blob/master/CONTRIBUTING.md
 
 ## License