Plugins

Puma 3.0 added support for plugins that can augment configuration and service operations.

There are two canonical plugins to aid in the development of new plugins:

tmp_restart: Restarts the server if the file tmp/restart.txt is touched
heroku: Packages up the default configuration used by Puma on Heroku (being sunset with the release of Puma 5.0)

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 on path requirements so, activating the heroku plugin is much like require "puma/plugin/heroku". This allows gems to provide multiple plugins (as well as unrelated gems to provide Puma plugins).

The tmp_restart plugin comes with Puma, so it is always available.

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 the server level: start and config.

start runs when the server has started and allows the plugin to initiate other functionality to augment Puma.

config runs when the server is being configured and receives a Puma::DSL object that is useful for additional configuration.

Public methods in Puma::Plugin are treated as a public API for plugins.

Binder hooks

There's Puma::Binder#before_parse method that allows to add proc to run before the body of Puma::Binder#parse. Example of usage can be found in that repository (before_parse_hook could be renamed before_parse, making monkey patching of binder.rb is unnecessary).