Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Browse files
Browse the repository at this point in the history
- Loading branch information
1 parent
17035b0
commit 6bb070b
Showing
1 changed file
with
20 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,28 +1,38 @@ | ||
## Plugins | ||
|
||
Puma 3.0 added support for plugins that can augment configuration and service operations. | ||
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 | ||
* [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 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). | ||
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`. | ||
## Server-wide hooks | ||
|
||
`start` runs when the server has started and allows the plugin to start other functionality to augment puma. | ||
Plugins can use a couple of hooks at server level: `start` and `config`. | ||
|
||
`config` runs when the server is being configured and is passed a `Puma::DSL` object that can be used to add additional configuration. | ||
`start` runs when the server has started and allows the plugin to start other | ||
functionality to augment puma. | ||
|
||
Any public methods in `Puma::Plugin` are the public API that any plugin may use. | ||
`config` runs when the server is being configured and is passed a `Puma::DSL` | ||
object that can be used to add additional configuration. | ||
|
||
In the future, more hooks and APIs will be added. | ||
Any public methods in `Puma::Plugin` are the public API that any plugin may | ||
use. |