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 theserver
argument as well as any argument passed on from theignite()
method. Any return value is discarded. -
resume
: Will trigger once after the start event if the app has been started using thereignite()
method. The handlers will receive the app itself as theserver
argument as well as any argument passed on from thereignite()
method. Any return value is discarded. -
end
: Will trigger once after the app is stopped. The handlers will receive the app itself as theserver
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 theserver
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 theserver
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 isTRUE
the request will continue on to normal processing. If the return value isFALSE
the response will be send back and the connection will be closed without retrieving the payload. The handlers will receive the app itself as theserver
argument, the client id as theid
argument and the request object as therequest
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 theheader
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 theserver
argument, the client id as theid
argument and the request object as therequest
argument. -
request
: Will trigger after thebefore-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 a404
error is returned automatically. If the return value is not a valid response, a500
server error is returned instead. The handlers will receive the app itself as theserver
argument, the client id as theid
argument, the request object as therequest
argument, and the list of values created by the before-event handlers as thearg_list
argument. -
after-request
: Will trigger after therequest
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 theserver
argument, the client id as theid
argument, the request object as therequest
argument, and the response as theresponse
argument. Any return value is discarded. -
before-message
: This event is triggered when a websocket message is received. As with thebefore-request
event the return values of the handlers are passed on to themessage
handlers. Specifically if a'binary'
and'message'
value is returned they will override the original values in themessage
andafter-message
handler arguments. This can e.g. be used to decode the message once before passing it through themessage
handlers. Thebefore-message
handlers will receive the app itself as theserver
argument, the client id as theid
argument, a flag indicating whether the message is binary as thebinary
argument, the message itself as themessage
argument, and the request object used to establish the connection with the client as therequest
argument. -
message
: This event is triggered after thebefore-message
event and is used for the primary websocket message handling. As with therequest
event, the handlers for themessage
event receives the return values from thebefore-message
handlers which can be used to e.g. inject session specific data. The message handlers will receive the app itself as theserver
argument, the client id as theid
argument, a flag indicating whether the message is binary as thebinary
argument, the message itself as themessage
argument, the request object used to establish the connection with the client as therequest
argument, and the values returned by the before-message handlers as thearg_list
argument. Contrary to therequest
event the return values of the handlers are ignored as websocket communication is bidirectional. -
after-message
: This event is triggered after themessage
event. It is provided more as an equivalent to theafter-request
event than out of necessity as there is no final response to inspect and handler can thus just as well be attached to themessage
event. For clear division of server logic, message specific handlers should be attached to themessage
event, whereas general handlers should, if possible, be attached to theafter-message
event. Theafter-message
handlers will receive the app itself as theserver
argument, the client id as theid
argument, a flag indicating whether the message is binary as thebinary
argument, the message itself as themessage
argument, and the request object used to establish the connection with the client as therequest
argument. -
send
: This event is triggered after a websocket message is send to a client. The handlers will receive the app itself as theserver
argument, the client id as theid
argument and the send message as themessage
argument. Any return value is discarded. -
websocket-closed
: This event will be triggered every time a websocket connection is closed. The handlers will receive the app itself as theserver
argument, the client id as theid
argument and request used to establish the closed connection as therequest
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/'
: