# The event cycle in fiery

fiery is using an event-based model to allow you to program the logic. During the life cycle of an app a range of different events will be triggered and it is possible to add event handlers to these using the `on()` method. An event handler is simply a function that will get called every time an event is fired. Apart from the predefined life cycle events it is also possible to trigger custom events using the `trigger()` method. Manual triggering of life cycle events is not allowed.

## Life cycle Events

Following is a list of all life cycle events. These cannot be triggered manually, but is fired as part of the normal lifetime of a fiery server:

- `start`: Will trigger once when the app is started but before it is running. The handlers will receive the app itself as the `server` argument as well as any argument passed on from the `ignite()` method. Any return value is discarded.
- `resume`: Will trigger once after the start event if the app has been started using the `reignite()` method. The handlers will receive the app itself as the `server` argument as well as any argument passed on from the `reignite()` method. Any return value is discarded.
- `end`: Will trigger once after the app is stopped. The handlers will receive the app itself as the `server` argument. Any return value is discarded.
- `cycle-start`: Will trigger in the beginning of each loop, before the request queue is flushed. The handlers will receive the app itself as the `server` argument. Any return value is discarded.
- `cycle-end`: Will trigger in the end of each loop, after the request queue is flushed and all delayed, timed, and asynchronous calls have been executed. The handlers will receive the app itself as the `server` argument. Any return value is discarded.
- `header`: Will trigger every time the header of a request is received. The return value of the last called handler is used to determine if further processing of the request will be done. If the return value is `TRUE` the request will continue on to normal processing. If the return value is `FALSE` the response will be send back and the connection will be closed without retrieving the payload. The handlers will receive the app itself as the `server` argument, the client id as the `id` argument and the request object as the `request` argument.
- `before-request`: Will trigger prior to handling of a request (that is, every time a request is received unless it is short-circuited by the `header` handlers). The return values of the handlers will be passed on to the request handlers and can thus be used to inject data into the request handlers (e.g. session specific data). The handlers will receive the app itself as the `server` argument, the client id as the `id` argument and the request object as the `request` argument.
- `request`: Will trigger after the `before-request` event. This is where the main request handling is done. The return value of the last handler is send back to the client as response. If no handler is registered a `404` error is returned automatically. If the return value is not a valid response, a `500` server error is returned instead. The handlers will receive the app itself as the `server` argument, the client id as the `id` argument, the request object as the `request` argument, and the list of values created by the before-event handlers as the `arg_list` argument.
- `after-request`: Will trigger after the `request` event. This can be used to inspect the response (but not modify it) before it is send to the client. The handlers will receive the app itself as the `server` argument, the client id as the `id` argument, the request object as the `request` argument, and the response as the `response` argument. Any return value is discarded.
- `before-message`: This event is triggered when a websocket message is received. As with the `before-request` event the return values of the handlers are passed on to the `message` handlers. Specifically if a `'binary'` and `'message'` value is returned they will override the original values in the `message` and `after-message` handler arguments. This can e.g. be used to decode the message once before passing it through the `message` handlers. The `before-message` handlers will receive the app itself as the `server` argument, the client id as the `id` argument, a flag indicating whether the message is binary as the `binary` argument, the message itself as the `message` argument, and the request object used to establish the connection with the client as the `request` argument.
- `message`: This event is triggered after the `before-message` event and is used for the primary websocket message handling. As with the `request` event, the handlers for the `message` event receives the return values from the `before-message` handlers which can be used to e.g. inject session specific data. The message handlers will receive the app itself as the `server` argument, the client id as the `id` argument, a flag indicating whether the message is binary as the `binary` argument, the message itself as the `message` argument, the request object used to establish the connection with the client as the `request` argument, and the values returned by the before-message handlers as the `arg_list` argument. Contrary to the `request` event the return values of the handlers are ignored as websocket communication is bidirectional.
- `after-message`: This event is triggered after the `message` event. It is provided more as an equivalent to the `after-request` event than out of necessity as there is no final response to inspect and handler can thus just as well be attached to the `message` event. For clear division of server logic, message specific handlers should be attached to the `message` event, whereas general handlers should, if possible, be attached to the `after-message` event. The `after-message` handlers will receive the app itself as the `server` argument, the client id as the `id` argument, a flag indicating whether the message is binary as the `binary` argument, the message itself as the `message` argument, and the request object used to establish the connection with the client as the `request` argument.
- `send`: This event is triggered after a websocket message is send to a client. The handlers will receive the app itself as the `server` argument, the client id as the `id` argument and the send message as the `message` argument. Any return value is discarded.
- `websocket-opened`: This event is triggered when a client tries to establish a WebSocket connection to the server. The handler will receive the app itself as the `server` argument, the client id as the `id` argument, and the WebSocket class provided by httpuv as the `connection` argument. Any return value is discarded. Since this event exposes logic from the httpuv package through the `connection` argument it is liable to changes in the httpuv API.
- `websocket-closed`: This event will be triggered every time a websocket connection is closed. The handlers will receive the app itself as the `server` argument, the client id as the `id` argument and request used to establish the closed connection as the `request` argument. Any return value is discarded.

## Custom Events

Apart from the predefined events, it is also possible to trigger and listen to custom events. The syntax is as follows:

    # Add a handler to the 'new-event' event
    id <- app$on('new-event', function() {
      message('Event fired')
    })

    # Trigger the event
    app$trigger('new-event')

    # Remove the handler
    app$off(id)

Additional parameters passed on to the `trigger()` method will be passed on to the handler. There is no limit to the number of handlers that can be attached to custom events. When an event is triggered they will simply be called in the order they have been added. Triggering a non-existing event is not an error, so plugins are free to fire off events without worrying about whether handlers have been added.

## Triggering Events Externally:

If a fiery server is running in blocking mode it is not possible to communicate with it using the `trigger()` method (though these can be fired by other callbacks in the server logic). Instead it is possible to assign a directory to look in for event trigger instructions. The trigger directory is set using the `trigger_dir` field, e.g.:

    app$trigger_dir <- '/some/path/to/dir/'

Events are triggered by placing an `rds` file named after the event in the trigger directory. The file must contain a list, and the elements of the list will be passed on as arguments to the event handlers. After the event has been triggered the file will be deleted. The following command will trigger the `external-event` on a server looking in `'/some/path/to/dir/'`:

    saveRDS(list(arg1 = 'test'), '/some/path/to/dir/external-event.rds')