puma 4.2.0

data/docs/nginx.md

@@ -0,0 +1,80 @@
+# Nginx configuration example file
+
+This is a very common setup using an upstream. It was adapted from some Capistrano recipe I found on the Internet a while ago.
+
+```
+upstream myapp {
+  server unix:///myapp/tmp/puma.sock;
+}
+
+server {
+  listen 80;
+  server_name myapp.com;
+
+  # ~2 seconds is often enough for most folks to parse HTML/CSS and
+  # retrieve needed images/icons/frames, connections are cheap in
+  # nginx so increasing this is generally safe...
+  keepalive_timeout 5;
+
+  # path for static files
+  root /myapp/public;
+  access_log /myapp/log/nginx.access.log;
+  error_log /myapp/log/nginx.error.log info;
+
+  # this rewrites all the requests to the maintenance.html
+  # page if it exists in the doc root. This is for capistrano's
+  # disable web task
+  if (-f $document_root/maintenance.html) {
+    rewrite  ^(.*)$  /maintenance.html last;
+    break;
+  }
+
+  location / {
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header Host $http_host;
+
+    # If the file exists as a static file serve it directly without
+    # running all the other rewrite tests on it
+    if (-f $request_filename) {
+      break;
+    }
+
+    # check for index.html for directory index
+    # if it's there on the filesystem then rewrite
+    # the url to add /index.html to the end of it
+    # and then break to send it to the next config rules.
+    if (-f $request_filename/index.html) {
+      rewrite (.*) $1/index.html break;
+    }
+
+    # this is the meat of the rack page caching config
+    # it adds .html to the end of the url and then checks
+    # the filesystem for that file. If it exists, then we
+    # rewrite the url to have explicit .html on the end
+    # and then send it on its way to the next config rule.
+    # if there is no file on the fs then it sets all the
+    # necessary headers and proxies to our upstream pumas
+    if (-f $request_filename.html) {
+      rewrite (.*) $1.html break;
+    }
+
+    if (!-f $request_filename) {
+      proxy_pass http://myapp;
+      break;
+    }
+  }
+
+  # Now this supposedly should work as it gets the filenames with querystrings that Rails provides.
+  # BUT there's a chance it could break the ajax calls.
+  location ~* \.(ico|css|gif|jpe?g|png|js)(\?[0-9]+)?$ {
+     expires max;
+     break;
+  }
+
+  # Error pages
+  # error_page 500 502 503 504 /500.html;
+  location = /500.html {
+    root /myapp/current/public;
+  }
+}
+```

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

@@ -0,0 +1,96 @@
+The [unix signal](http://en.wikipedia.org/wiki/Unix_signal) is a method of sending messages between [processes](http://en.wikipedia.org/wiki/Process_(computing)). When a signal is sent, the operating system interrupts the target process's normal flow of execution. There are standard signals that are used to stop a process but there are also custom signals that can be used for other purposes. This document is an attempt to list all supported signals that Puma will respond to. In general, signals need only be sent to the master process of a cluster.
+
+## Sending Signals
+
+If you are new to signals it can be useful to see how they can be used. When a process is created in a *nix like operating system it will have a [PID - or process identifier](http://en.wikipedia.org/wiki/Process_identifier) that can be used to send signals to the process. For demonstration we will create an infinitely running process by tailing a file:
+
+```sh
+$ echo "foo" >> my.log
+$ irb
+> pid = Process.spawn 'tail -f my.log'
+```
+
+From here we can see that the tail process is running by using the `ps` command:
+
+```sh
+$ ps aux | grep tail
+schneems        87152   0.0  0.0  2432772    492 s032  S+   12:46PM   0:00.00 tail -f my.log
+```
+
+You can send a signal in Ruby using the [Process module](http://www.ruby-doc.org/core-2.1.1/Process.html#kill-method):
+
+```
+$ irb
+> puts pid
+=> 87152
+Process.detach(pid) # http://ruby-doc.org/core-2.1.1/Process.html#method-c-detach
+Process.kill("TERM", pid)
+```
+
+Now you will see via `ps` that there is no more `tail` process. Sometimes when referring to signals the `SIG` prefix will be used for instance `SIGTERM` is equivalent to sending `TERM` via `Process.kill`.
+
+## Puma Signals
+
+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. 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

@@ -0,0 +1,290 @@
+# systemd
+
+[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.
+
+## 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
+
+# Uncomment for socket activation (see below)
+# Requires=puma.socket
+
+[Service]
+# Foreground process (do not use --daemon in ExecStart or config.rb)
+Type=simple
+
+# Preferably configure a non-privileged user
+# User=
+
+# 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
+
+# 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
+
+
+Restart=always
+
+[Install]
+WantedBy=multi-user.target
+~~~~
+
+See [systemd.exec](https://www.freedesktop.org/software/systemd/man/systemd.exec.html)
+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, 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
+
+[Socket]
+ListenStream=0.0.0.0:9292
+ListenStream=0.0.0.0:9293
+
+# AF_UNIX domain socket
+# SocketUser, SocketGroup, etc. may be needed for Unix domain sockets
+# ListenStream=/run/puma.sock
+
+# Socket options matching Puma defaults
+NoDelay=true
+ReusePort=true
+Backlog=1024
+
+[Install]
+WantedBy=sockets.target
+~~~~
+
+See [systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html)
+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
+with other system services:
+
+~~~~ sh
+# After installing or making changes to puma.service
+systemctl daemon-reload
+
+# Enable so it starts on boot
+systemctl enable puma.service
+
+# Initial start up.
+systemctl start puma.service
+
+# Check status
+systemctl status puma.service
+
+# A normal restart. Warning: listeners sockets will be closed
+# while a new puma process initializes.
+systemctl restart puma.service
+~~~~
+
+With socket activation, several but not all of these commands should
+be run for both socket and service:
+
+~~~~ sh
+# After installing or making changes to either puma.socket or
+# puma.service.
+systemctl daemon-reload
+
+# Enable both socket and service so they start on boot.  Alternatively
+# you could leave puma.service disabled and systemd will start it on
+# first use (with startup lag on first request)
+systemctl enable puma.socket puma.service
+
+# Initial start up. The Requires directive (see above) ensures the
+# socket is started before the service.
+systemctl start puma.socket puma.service
+
+# Check status of both socket and service.
+systemctl status puma.socket puma.service
+
+# A "hot" restart, with systemd keeping puma.socket listening and
+# providing to the new puma (master) instance.
+systemctl restart puma.service
+
+# A normal restart, needed to handle changes to
+# puma.socket, such as changing the ListenStream ports. Note
+# daemon-reload (above) should be run first.
+systemctl restart puma.socket puma.service
+~~~~
+
+Here is sample output from `systemctl status` with both service and
+socket running:
+
+~~~~
+● puma.socket - Puma HTTP Server Accept Sockets
+   Loaded: loaded (/etc/systemd/system/puma.socket; enabled; vendor preset: enabled)
+   Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
+   Listen: 0.0.0.0:9233 (Stream)
+           0.0.0.0:9234 (Stream)
+
+Apr 07 08:40:19 hx systemd[874]: Listening on Puma HTTP Server Accept Sockets.
+
+● puma.service - Puma HTTP Server
+   Loaded: loaded (/etc/systemd/system/puma.service; enabled; vendor preset: enabled)
+   Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
+ Main PID: 28320 (ruby)
+   CGroup: /system.slice/puma.service
+           ├─28320 puma 3.3.0 (tcp://0.0.0.0:9233,ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem) [app]
+           ├─28323 puma: cluster worker 0: 28320 [app]
+           └─28327 puma: cluster worker 1: 28320 [app]
+
+Apr 07 08:40:19 hx puma[28320]: Puma starting in cluster mode...
+Apr 07 08:40:19 hx puma[28320]: * Version 3.3.0 (ruby 2.2.4-p230), codename: Jovial Platypus
+Apr 07 08:40:19 hx puma[28320]: * Min threads: 0, max threads: 16
+Apr 07 08:40:19 hx puma[28320]: * Environment: production
+Apr 07 08:40:19 hx puma[28320]: * Process workers: 2
+Apr 07 08:40:19 hx puma[28320]: * Phased restart available
+Apr 07 08:40:19 hx puma[28320]: * Activated tcp://0.0.0.0:9233
+Apr 07 08:40:19 hx puma[28320]: * Activated ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem
+Apr 07 08:40:19 hx puma[28320]: Use Ctrl-C to stop
+~~~~
+
+## 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
+
+# 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
+
+# The command to stop Puma
+# (replace "<WD>" below)
+ExecStop=bundle exec pumactl -S <WD>/shared/tmp/pids/puma.state stop
+
+# 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