puma 3.8.2 → 4.3.12

data/docs/plugins.md

@@ -0,0 +1,38 @@
+## 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
+
+## Server-wide hooks
+
+Plugins can use a couple of hooks at server level: `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.

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

data/docs/tcp_mode.md

@@ -0,0 +1,96 @@
+# TCP mode
+
+Puma also could be used as a TCP server to process incoming TCP
+connections.
+
+
+## Configuration
+
+TCP mode can be enabled with CLI option `--tcp-mode`:
+
+```
+$ puma --tcp-mode
+```
+
+Default ip and port to listen to are `0.0.0.0` and `9292`. You can configure
+them with `--port` and `--bind` options:
+
+```
+$ puma --tcp-mode --bind tcp://127.0.0.1:9293
+$ puma --tcp-mode --port 9293
+```
+
+TCP mode could be set with a configuration file as well with `tcp_mode`
+and `tcp_mode!` methods:
+
+```
+# config/puma.rb
+tcp_mode
+```
+
+When Puma starts in the TCP mode it prints the corresponding message:
+
+```
+puma --tcp-mode
+Puma starting in single mode...
+...
+* Mode: Lopez Express (tcp)
+```
+
+
+## How to declare an application
+
+An application to process TCP connections should be declared as a
+callable object which accepts `env` and `socket` arguments.
+
+`env` argument is a Hash with following structure:
+
+```ruby
+{ "thread" => {}, "REMOTE_ADDR" => "127.0.0.1:51133", "log" => "#<Proc:0x000..." }
+```
+
+It consists of:
+* `thread` - a Hash for each thread in the thread pool that could be
+  used to store information between requests
+* `REMOTE_ADDR` - a client ip address
+* `log` - a proc object to write something down
+
+`log` object could be used this way:
+
+```ruby
+env['log'].call('message to log')
+#> 19/Oct/2019 20:28:53 - 127.0.0.1:51266 - message to log
+```
+
+
+## Example of an application
+
+Let's look at an example of a simple application which just echoes
+incoming string:
+
+```ruby
+# config/puma.rb
+app do |env, socket|
+  s = socket.gets
+  socket.puts "Echo #{s}"
+end
+```
+
+We can easily access the TCP server with `telnet` command and receive an
+echo:
+
+```shell
+telnet 0.0.0.0 9293
+Trying 0.0.0.0...
+Connected to 0.0.0.0.
+Escape character is '^]'.
+sssss
+Echo sssss
+^CConnection closed by foreign host.
+```
+
+
+## Socket management
+
+After the application finishes, Puma closes the socket. In order to
+prevent this, the application should set `env['detach'] = true`.

data/ext/puma_http11/PumaHttp11Service.java

@@ -6,11 +6,13 @@ import org.jruby.Ruby;
 import org.jruby.runtime.load.BasicLibraryService;
 
 import org.jruby.puma.Http11;
+import org.jruby.puma.IOBuffer;
 import org.jruby.puma.MiniSSL;
 
 public class PumaHttp11Service implements BasicLibraryService { 
     public boolean basicLoad(final Ruby runtime) throws IOException {
         Http11.createHttp11(runtime);
+        IOBuffer.createIOBuffer(runtime);
         MiniSSL.createMiniSSL(runtime);
         return true;
     }

data/ext/puma_http11/extconf.rb

@@ -1,6 +1,11 @@
 require 'mkmf'
 
 dir_config("puma_http11")
+if $mingw && RUBY_VERSION >= '2.4'
+  append_cflags '-D_FORTIFY_SOURCE=2'
+  append_ldflags '-fstack-protector'
+  have_library 'ssp'
+end
 
 unless ENV["DISABLE_SSL"]
   dir_config("openssl")
@@ -9,6 +14,22 @@ unless ENV["DISABLE_SSL"]
       %w'ssl ssleay32'.find {|ssl| have_library(ssl, 'SSL_CTX_new')}
 
     have_header "openssl/bio.h"
+
+    # below is  yes for 1.0.2 & later
+    have_func  "DTLS_method"                  , "openssl/ssl.h"
+
+    # below are yes for 1.1.0 & later, may need to check func rather than macro
+    # with versions after 1.1.1
+    have_func  "TLS_server_method"            , "openssl/ssl.h"
+    have_macro "SSL_CTX_set_min_proto_version", "openssl/ssl.h"
+
+    # Random.bytes available in Ruby 2.5 and later, Random::DEFAULT deprecated in 3.0
+    if Random.respond_to?(:bytes)
+      $defs.push("-DHAVE_RANDOM_BYTES")
+      puts "checking for Random.bytes... yes"
+    else
+      puts "checking for Random.bytes... no"
+    end
   end
 end