# Creating and using fiery plugins

In order to facilitate encapsulate functionality that can be shared between fiery servers fiery implements a plugin interface. Indeed, the reason why fiery is so minimal in functionality is because it is intended as a foundation for separate plugins that can add convenience and power. This approach allows fiery itself to remain unopinionated and flexible.

## Using Plugins

Plugins are added to a `Fire` object using the `attach()` method. Any parameters passed along with the plugin to the `attach()` method will be passed on to the plugins `on_attach()` method (see below).

    app$attach(plugin)

## Creating Plugins

The fiery plugin specification is rather simple. A plugin is either a list or environment (e.g. a `RefClas` or `R6` object) with the following elements:

- `on_attach(server, ...)`: A function that will get called when the plugin is attached to the server. It is passed the server object as the first argument along with any arguments passed to the `attach()` method.
- `name`: A string giving the name of the plugin.
- `require`: Optional A character vector giving names of other plugins that must be attached for this plugin to work.

Apart from this, the list/environment can contain anything you desires. For an example of a relatively complex plugin, have a look at the source code for the `routr` package.

## Accessing Plugins

When a plugin is attached to a `Fire` object, two things happens. First, the `on_attach()` function in the plugin is called modifying the server in different ways, then the plugin object is saved internally, so that it can later be retrieved. All plugins are accessible in the `plugins` field under the name of the plugin. This is useful for plugins that modifies other plugins, or are dependent on functionality in other plugins. A minimal example of a plugin using another plugin could be (This will add a route that prints “Hello” to the console everytime any ressource is requested):

    plugin <- list(
      on_attach = function(server) {
        router <- server$plugins$request_routr
        route <- Route$new()
        route$add_handler('all', '*', function(request, response, arg_list, ...) {
          message('Hello')
          TRUE
        })
        router$add_route(route, 1)
      },
      name = 'Hello_plugin',
      require = 'request_routr'
    )

The `Hello_plugin` depends on the routr plugin for its functionality as it modifies the request router to always say hello when processing requests. If the `reques_routr` plugin has not already been attached it is not possible to use the `Hello_plugin` plugin.

It is also possible to have a soft dependency to another plugin, by not listing it in `require` and instead use the `has_plugin()` method in the server to modify the behaviour of the plugin. We could rewrite the `Hello_plugin` to add the routr plugin by itself if missing:

    plugin <- list(
      on_attach = function(server) {
        if (!server$has_plugin('request_routr')) {
          server$attach(RouteStack$new())
        }
        router <- server$plugins$request_routr
        route <- Route$new()
        route$add_handler('all', '*', function(request, response, arg_list, ...) {
          message('Hello')
          TRUE
        })
        router$add_route(route, 1)
      },
      name = 'Hello_plugin2'
    )