puma 3.8.2 → 4.0.0

data/docs/architecture.md

@@ -0,0 +1,37 @@
+# Architecture
+
+## Overview
+
+![http://bit.ly/2iJuFky](images/puma-general-arch.png)
+
+Puma is a threaded web server, processing requests across a TCP or UNIX socket.
+
+Workers accept connections from the socket and a thread in the worker's thread pool processes the client's request.
+
+Clustered mode is shown/discussed here. Single mode is analogous to having a single worker process.
+
+## Connection pipeline
+
+![http://bit.ly/2zwzhEK](images/puma-connection-flow.png)
+
+* Upon startup, Puma listens on a TCP or UNIX socket.
+  * The backlog of this socket is configured (with a default of 1024), determining how many established but unaccepted connections can exist concurrently.
+  * This socket backlog is distinct from the "backlog" of work as reported by the control server stats. The latter is the number of connections in that worker's "todo" set waiting for a worker thread.
+* By default, a single, separate thread is used to receive HTTP requests across the socket.
+  * When at least one worker thread is available for work, a connection is accepted and placed in this request buffer
+  * This thread waits for entire HTTP requests to be received over the connection
+    * The time spent waiting for the HTTP request body to be received is exposed to the Rack app as `env['puma.request_body_wait']` (milliseconds)
+  * Once received, the connection is pushed into the "todo" set
+* Worker threads pop work off the "todo" set for processing
+  * The thread processes the request via the rack application (which generates the HTTP response)
+  * The thread writes the response to the connection
+  * Finally, the thread become available to process another connection in the "todo" set
+
+### Disabling `queue_requests`
+
+![http://bit.ly/2zxCJ1Z](images/puma-connection-flow-no-reactor.png)
+
+The `queue_requests` option is `true` by default, enabling the separate thread used to buffer requests as described above.
+
+If set to `false`, this buffer will not be used for connections while waiting for the request to arrive.
+In this mode, when a connection is accepted, it is added to the "todo" queue immediately, and a worker will synchronously do any waiting necessary to read the HTTP request from the socket.

data/{DEPLOYMENT.md → docs/deployment.md}

@@ -38,22 +38,42 @@ Here are some rules of thumb:
 * As you grow more confident in the thread safety of your app, you can tune the
   workers down and the threads up.
 
+#### Ubuntu / Systemd (Systemctl) Installation
+
+See [systemd.md](systemd.md)
+
 #### Worker utilization
 
-**How do you know if you're got enough (or too many workers)?**
+**How do you know if you've got enough (or too many workers)?**
 
 A good question. Due to MRI's GIL, only one thread can be executing Ruby code at a time.
 But since so many apps are waiting on IO from DBs, etc., they can utilize threads
 to make better use of the process.
 
 The rule of thumb is you never want processes that are pegged all the time. This
-means that there is more work to do that the process can get through. On the other
+means that there is more work to do than the process can get through. On the other
 hand, if you have processes that sit around doing nothing, then they're just eating
 up resources.
 
-Watching your CPU utilization over time and aim for about 70% on average. This means
+Watch your CPU utilization over time and aim for about 70% on average. This means
 you've got capacity still but aren't starving threads.
 
+**Measuring utilization**
+
+Using a timestamp header from an upstream proxy server (eg. nginx or haproxy), it's
+possible to get an indication of how long requests have been waiting for a Puma
+thread to become available.
+
+* Have your upstream proxy set a header with the time it received the request:
+    * nginx: `proxy_set_header X-Request-Start "${msec}";`
+    * haproxy: `http-request set-header X-Request-Start "%t";`
+* In your Rack middleware, determine the amount of time elapsed since `X-Request-Start`.
+* To improve accuracy, you will want to subtract time spent waiting for slow clients:
+    * `env['puma.request_body_wait']` contains the number of milliseconds Puma spent
+      waiting for the client to send the request body.
+    * haproxy: `%Th` (TLS handshake time) and `%Ti` (idle time before request) can
+      can also be added as headers.
+
 ## Daemonizing
 
 I prefer to not daemonize my servers and use something like `runit` or `upstart` to
@@ -62,7 +82,7 @@ makes it easy to figure out what is going on. Additionally, unlike `unicorn`,
 puma does not require daemonization to do zero-downtime restarts.
 
 I see people using daemonization because they start puma directly via capistrano
-task and thus want it to live on past the `cap deploy`. To this people I said:
+task and thus want it to live on past the `cap deploy`. To these people I say:
 You need to be using a process monitor. Nothing is making sure puma stays up in
 this scenario! You're just waiting for something weird to happen, puma to die,
 and to get paged at 3am. Do yourself a favor, at least the process monitoring

data/docs/plugins.md

@@ -0,0 +1,28 @@
+## Plugins
+
+Puma 3.0 added support for plugins that can augment configuration and service operations.
+
+2 canonical plugins to look to aid in development of further plugins:
+
+* [tmp\_restart](https://github.com/puma/puma/blob/master/lib/puma/plugin/tmp_restart.rb): Restarts the server if the file `tmp/restart.txt` is touched
+* [heroku](https://github.com/puma/puma-heroku/blob/master/lib/puma/plugin/heroku.rb): Packages up the default configuration used by puma on Heroku
+
+Plugins are activated in a puma configuration file (such as `config/puma.rb'`) by adding `plugin "name"`, such as `plugin "heroku"`.
+
+Plugins are activated based simply on path requirements so, activating the `heroku` plugin will simply be doing `require "puma/plugin/heroku"`. This allows gems to provide multiple plugins (as well as unrelated gems to provide puma plugins).
+
+The `tmp_restart` plugin is bundled with puma, so it can always be used.
+
+To use the `heroku` plugin, add `puma-heroku` to your Gemfile or install it.
+
+### API
+
+At present, there are 2 hooks that plugins can use: `start` and `config`.
+
+`start` runs when the server has started and allows the plugin to start other functionality to augment puma.
+
+`config` runs when the server is being configured and is passed a `Puma::DSL` object that can be used to add additional configuration.
+
+Any public methods in `Puma::Plugin` are the public API that any plugin may use.
+
+In the future, more hooks and APIs will be added.

data/docs/restart.md

@@ -0,0 +1,41 @@
+# Restarts
+
+To perform a restart, there are 3 builtin mechanisms:
+
+  * Send the `puma` process the `SIGUSR2` signal (normal restart)
+  * Send the `puma` process the `SIGUSR1` signal (restart in phases (a "rolling restart"), cluster mode only)
+  * Use the status server and issue `/restart`
+
+No code is shared between the current and restarted process, so it should be safe to issue a restart any place where you would manually stop Puma and start it again.
+
+If the new process is unable to load, it will simply exit. You should therefore run Puma under a process monitor (see below) when using it in production.
+
+### Normal vs Hot vs Phased Restart
+
+A hot restart means that no requests will be lost while deploying your new code, since the server socket is kept open between restarts.
+
+But beware, hot restart does not mean that the incoming requests won’t hang for multiple seconds while your new code has not fully deployed. If you need a zero downtime and zero hanging requests deploy, you must use phased restart.
+
+When you run pumactl phased-restart, Puma kills workers one-by-one, meaning that at least another worker is still available to serve requests, which lead to zero hanging requests (yay!).
+
+But again beware, upgrading an application sometimes involves upgrading the database schema. With phased restart, there may be a moment during the deployment where processes belonging to the previous version and processes belonging to the new version both exist at the same time. Any database schema upgrades you perform must therefore be backwards-compatible with the old application version.
+
+If you perform a lot of database migrations, you probably should not use phased restart and use a normal/hot restart instead (`pumactl restart`). That way, no code is shared while deploying (in that case, `preload_app!` might help for quicker deployment, see ["Clustered Mode" in the README](../README.md#clustered-mode)).
+
+**Note**: Hot and phased restarts are only available on MRI, not on JRuby. They are also unavailable on Windows servers.
+
+### Release Directory
+
+If your symlink releases into a common working directory (i.e., `/current` from Capistrano), Puma won't pick up your new changes when running phased restarts without additional configuration. You should set your working directory within Puma's config to specify the directory it should use. This is a change from earlier versions of Puma (< 2.15) that would infer the directory for you.
+
+```ruby
+# config/puma.rb
+
+directory '/var/www/current'
+```
+
+### Cleanup Code
+
+Puma isn't able to understand all the resources that your app may use, so it provides a hook in the configuration file you pass to `-C` called `on_restart`. The block passed to `on_restart` will be called, unsurprisingly, just before Puma restarts itself.
+
+You should place code to close global log files, redis connections, etc. in this block so that their file descriptors don't leak into the restarted process. Failure to do so will result in slowly running out of descriptors and eventually obscure crashes as the server is restarted many times.

data/docs/signals.md

@@ -36,8 +36,61 @@ Puma cluster responds to these signals:
 - `TTIN` increment the worker count by 1
 - `TTOU` decrement the worker count by 1
 - `TERM` send `TERM` to worker. Worker will attempt to finish then exit.
-- `USR2` restart workers
-- `USR1` restart workers in phases, a rolling restart.
-- `HUP`  reopen log files defined in stdout_redirect configuration parameter
+- `USR2` restart workers. This also reloads puma configuration file, if there is one.
+- `USR1` restart workers in phases, a rolling restart. This will not reload configuration file.
+- `HUP`  reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided it will behave like `INT`
 - `INT` equivalent of sending Ctrl-C to cluster. Will attempt to finish then exit.
 - `CHLD`
+
+## Callbacks order in case of different signals
+
+### Start application
+
+```
+puma configuration file reloaded, if there is one
+* Pruning Bundler environment
+puma configuration file reloaded, if there is one
+
+before_fork
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```
+
+### Send USR2
+
+```
+on_worker_shutdown
+on_restart
+
+puma configuration file reloaded, if there is one
+
+before_fork
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```
+
+### Send USR1
+
+```
+on_worker_shutdown
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```

data/docs/systemd.md

@@ -3,10 +3,21 @@
 [systemd](https://www.freedesktop.org/wiki/Software/systemd/) is a
 commonly available init system (PID 1) on many Linux distributions. It
 offers process monitoring (including automatic restarts) and other
-useful features for running Puma in production. Below is a sample
-puma.service configuration file for systemd:
+useful features for running Puma in production.
 
-~~~~
+## Service Configuration
+
+Below is a sample puma.service configuration file for systemd, which
+can be copied or symlinked to /etc/systemd/system/puma.service, or if
+desired, using an application or instance specific name.
+
+Note that this uses the systemd preferred "simple" type where the
+start command remains running in the foreground (does not fork and
+exit). See also, the
+[Alternative Forking Configuration](#alternative-forking-configuration)
+below.
+
+~~~~ ini
 [Unit]
 Description=Puma HTTP Server
 After=network.target
@@ -21,22 +32,26 @@ Type=simple
 # Preferably configure a non-privileged user
 # User=
 
-# Specify the path to your puma application root
-# WorkingDirectory=
+# The path to the your application code root directory.
+# Also replace the "<YOUR_APP_PATH>" place holders below with this path.
+# Example /home/username/myapp
+WorkingDirectory=<YOUR_APP_PATH>
 
 # Helpful for debugging socket activation, etc.
 # Environment=PUMA_DEBUG=1
 
-# The command to start Puma
-# Here we are using a binstub generated via:
-# `bundle binstubs puma --path ./sbin`
-# in the WorkingDirectory (replace <WD> below)
-# You can alternatively use `bundle exec --keep-file-descriptors puma`
-# ExecStart=<WD>/sbin/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
+# SystemD will not run puma even if it is in your path. You must specify
+# an absolute URL to puma. For example /usr/local/bin/puma
+# Alternatively, create a binstub with `bundle binstubs puma --path ./sbin` in the WorkingDirectory
+ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/puma.rb
+
+# Variant: Rails start.
+# ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/config/puma.rb ../config.ru
+
+# Variant: Use `bundle exec --keep-file-descriptors puma` instead of binstub
+# Variant: Specify directives inline.
+# ExecStart=/<FULLPATH>/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
 
-# Alternatively with a config file (in WorkingDirectory) and
-# comparable `bind` directives
-# ExecStart=<WD>/sbin/puma -C config.rb
 
 Restart=always
 
@@ -50,14 +65,29 @@ for additional details.
 ## Socket Activation
 
 systemd and puma also support socket activation, where systemd opens
-the listening socket(s) in advance and provides them to the puma master
-process on startup. Among other advantages, this keeps listening
-sockets open across puma restarts and achieves graceful restarts. To
-use socket activation, configure one or more `ListenStream`
-sockets in a companion `*.socket` systemd config file. Here is a sample
-puma.socket, matching the ports used in the above puma.service:
-
-~~~~
+the listening socket(s) in advance and provides them to the puma
+master process on startup. Among other advantages, this keeps
+listening sockets open across puma restarts and achieves graceful
+restarts, including when upgraded puma, and is compatible with both
+clustered mode and application preload.
+
+**Note:** Any wrapper scripts which `exec`, or other indirections in
+`ExecStart`, may result in activated socket file descriptors being closed
+before they reach the puma master process. For example, if using `bundle exec`,
+pass the `--keep-file-descriptors` flag. `bundle exec` can be avoided by using a
+`puma` executable generated by `bundle binstubs puma`. This is tracked in
+[#1499].
+
+**Note:** Socket activation doesn't currently work on jruby. This is
+tracked in [#1367].
+
+To use socket activation, configure one or more `ListenStream` sockets
+in a companion `*.socket` unit file. Also uncomment the associated
+`Requires` directive for the socket unit in the service file (see
+above.) Here is a sample puma.socket, matching the ports used in the
+above puma.service:
+
+~~~~ ini
 [Unit]
 Description=Puma HTTP Server Accept Sockets
 
@@ -84,6 +114,16 @@ for additional configuration details.
 Note that the above configurations will work with Puma in either
 single process or cluster mode.
 
+### Sockets and symlinks
+
+When using releases folders, you should set the socket path using the
+shared folder path (ex. `/srv/projet/shared/tmp/puma.sock`), not the
+release folder path (`/srv/projet/releases/1234/tmp/puma.sock`).
+
+Puma will detect the release path socket as different than the one provided by
+systemd and attempt to bind it again, resulting in the exception
+ `There is already a server bound to:`.
+
 ## Usage
 
 Without socket activation, use `systemctl` as root (e.g. via `sudo`) as
@@ -169,29 +209,82 @@ Apr 07 08:40:19 hx puma[28320]: * Activated ssl://0.0.0.0:9234?key=key.pem&cert=
 Apr 07 08:40:19 hx puma[28320]: Use Ctrl-C to stop
 ~~~~
 
-## Alternative background process configuration
-
-If Capistrano and [capistrano3-puma](https://github.com/seuros/capistrano-puma) tasks are used you can use the following configuration. In this case, you would skip systemd Socket Activation, since Puma handles the socket by itself:
+## Alternative Forking Configuration
+
+Other systems/tools might expect or need puma to be run as a
+"traditional" forking server, for example so that the `pumactl`
+command can be used directly and outside of systemd for
+stop/start/restart. This use case is incompatible with systemd socket
+activation, so it should not be configured. Below is an alternative
+puma.service config sample, using `Type=forking` and the `--daemon`
+flag in `ExecStart`. Here systemd is playing a role more equivalent to
+SysV init.d, where it is responsible for starting Puma on boot
+(multi-user.target) and stopping it on shutdown, but is not performing
+continuous restarts. Therefore running Puma in cluster mode, where the
+master can restart workers, is highly recommended. See the systemd
+[Restart] directive for details.
+
+~~~~ ini
+[Unit]
+Description=Puma HTTP Forking Server
+After=network.target
 
-~~~~
 [Service]
 # Background process configuration (use with --daemon in ExecStart)
 Type=forking
 
-# To learn which exact command is to be used to execute at "ExecStart" of this
-# Service, ask Capistrano: `cap <stage> puma:start --dry-run`. Your result
-# may differ from this example, for example if you use a Ruby version
-# manager. `<WD>` is short for "your working directory". Replace it with your
-# path.
+# Preferably configure a non-privileged user
+# User=
+
+# The path to the puma application root
+# Also replace the "<WD>" place holders below with this path.
+WorkingDirectory=
+
+# The command to start Puma
+# (replace "<WD>" below)
 ExecStart=bundle exec puma -C <WD>/shared/puma.rb --daemon
 
-# To learn which exact command is to be used to execute at "ExecStop" of this
-# Service, ask Capistrano: `cap <stage> puma:stop --dry-run`. Your result
-# may differ from this example, for example if you use a Ruby version
-# manager. `<WD>` is short for "your working directory". Replace it with your
-# path.
+# The command to stop Puma
+# (replace "<WD>" below)
 ExecStop=bundle exec pumactl -S <WD>/shared/tmp/pids/puma.state stop
 
-# PIDFile setting is required in order to work properly
+# Path to PID file so that systemd knows which is the master process
 PIDFile=<WD>/shared/tmp/pids/puma.pid
+
+# Should systemd restart puma?
+# Use "no" (the default) to ensure no interference when using
+# stop/start/restart via `pumactl`.  The "on-failure" setting might
+# work better for this purpose, but you must test it.
+# Use "always" if only `systemctl` is used for start/stop/restart, and
+# reconsider if you actually need the forking config.
+Restart=no
+
+# `puma_ctl restart` wouldn't work without this. It's because `pumactl`
+# changes PID on restart and systemd stops the service afterwards
+# because of the PID change. This option prevents stopping after PID
+# change.
+RemainAfterExit=yes
+
+[Install]
+WantedBy=multi-user.target
+~~~~
+
+### capistrano3-puma
+
+By default,
+[capistrano3-puma](https://github.com/seuros/capistrano-puma) uses
+`pumactl` for deployment restarts, outside of systemd.  To learn the
+exact commands that this tool would use for `ExecStart` and
+`ExecStop`, use the following `cap` commands in dry-run mode, and
+update from the above forking service configuration accordingly. Note
+also that the configured `User` should likely be the same as the
+capistrano3-puma `:puma_user` option.
+
+~~~~ sh
+stage=production # or different stage, as needed
+cap $stage puma:start --dry-run
+cap $stage puma:stop  --dry-run
 ~~~~
+
+[Restart]: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=
+[#1367]: https://github.com/puma/puma/issues/1367