The Fire generator creates a new Fire-object, which is the class containing
all the app logic. The class is based on the R6 OO-system and
is thus reference-based with methods and data attached to each object, in
contrast to the more well known S3 and S4 systems. A fiery server is event
driven, which means that it is build up and manipulated by adding event
handlers and triggering events. To learn more about the fiery event model,
read the event vignette.
fiery servers can be modified directly or by attaching plugins. As with
events, plugins has its own vignette.
Active bindings
hostA string giving a valid IPv4 address owned by the server, or
'0.0.0.0'to listen on all addresses. The default is'127.0.0.1'portAn integer giving the port number the server should listen on (defaults to
8080L)refresh_rateThe interval in seconds between run cycles when running a blocking server (defaults to
0.001)refresh_rate_nbThe interval in seconds between run cycles when running a non-blocking server (defaults to
1)trigger_dirA valid folder where trigger files can be put when running a blocking server (defaults to
NULL). See the The event cycle in fiery vignette for more information.pluginsA named list of the already attached plugins. Read Only - can only be modified using the
attach()method.data_storeAccess the environment that holds the global data store
rootThe location of the app. Setting this will remove the root value from requests (or decline them with
400if the request does not match the root). E.g. the path of a request will be changed from/demo/testto/testifroot == '/demo'access_log_formatA glue string defining how requests will be logged. For standard formats see common_log_format and combined_log_format. Defaults to the Common Log Format
keyThe encryption key to use for request/response encryption
session_cookie_settingsGet or set the session cookie settings
trustA logical indicating whether incoming requests are trusted.
compression_limitThe size threshold in bytes for trying to compress the response body (it is still dependant on content negotiation)
Methods
Method format()
Human readable description of the app
Method ignite()
Begin running the server. Will trigger the start event
Arguments
blockShould the console be blocked while running (alternative is to run in the background)
showcaseShould the default browser open up at the server address. If
TRUEthen a browser opens at the root of the app. If a string the string is used as a path to add to the root before opening...Arguments passed on to the
starthandlersilentShould startup messaging by silenced
Method start()
Synonymous method to ignite()
Method reignite()
Resume a session. This is equivalent to ignite() but will also trigger the resume event
Method on()
Add a handler to an event. See the The event cycle in fiery vignette for more information.
Method trigger()
Trigger an event in the app. This will cause any handler attached to the event to be called. See the The event cycle in fiery vignette for more information.
Method serve_static()
Serve a file or directory of files at a specified url path. Requests matching a file on the system never enters into the request loop but are served directly (and fast). Due to this, logging for these requests are also turned off
Usage
Fire$serve_static(
at,
path,
use_index = TRUE,
fallthrough = FALSE,
html_charset = "utf-8",
headers = list(),
validation = NULL
)Arguments
atThe url path to listen to requests on
pathThe path to the file or directory on the file system
use_indexShould an
index.htmlfile be served if present when a client requests the folderfallthroughShould requests that doesn't match a file enter the request loop or have a 404 response send directly
html_charsetThe charset to report for serving html files
headersA list of headers to add to the response. Will be combined with the global headers of the app
validationAn optional validation pattern. Presently, the only type of validation supported is an exact string match of a header. For example, if validation is
"abc" = "xyz", then HTTP requests must have a header namedabc(case-insensitive) with the value"xyz"(case-sensitive). If a request does not have a matching header, than httpuv will give a 403 Forbidden response. Ifcharacter(0)(the default), then no validation check will be performed.
Method exclude_static()
Exclude a url path from serving static content. Only meaningful to exclude sub paths of path that are set to serve static content
Method attach()
Attach a plugin to the app. See the Creating and using fiery plugins vignette for more information
Method time()
Add a timed evaluation that will be evaluated after the given number of seconds.
Method delay()
Add a delayed evaluation to be evaluated immediately at the end of the loop cycle.
Method async()
![[Deprecated]](figures/lifecycle-deprecated.svg)
Add an asynchronous evaluation to be evaluated in another process without blocking the server. This function has been deprecated in favor of using your own async framework of choice, e.g. mirai or promises
Method set_client_id_converter()
Sets the function that converts an HTTP request into a specific client id
Method log()
Log a message with the logger attached to the app. See loggers for build in functionality
Usage
Fire$log(
event,
message,
request = NULL,
...,
.logcall = sys.call(),
.topcall = sys.call(-1),
.topenv = parent.frame()
)Arguments
eventThe event associated with the message
messageThe message to log
requestThe
Requestobject associated with the message, if any....Additional arguments passed on to the logger.
.logcallThe call that send the log request
.topcallThe call in which
.logcallis called from.topenvThe environment associated with
.topcall
Method safe_call()
Evaluate an expression safely, logging any errors, warnings, or messages that bubbles up
Method test_request()
Send a request directly to the request logic of a non-running app. Only intended for testing the request logic
Method test_header()
Send a request directly to the header logic of a non-running app. Only intended for testing the request logic
Method test_message()
Send a message directly to the message logic of a non-running app. Only intended for testing the websocket logic
Method test_websocket()
Send a message directly from a non-running app. Only intended for testing the websocket logic
Examples
# Create a New App
app <- Fire$new(port = 4689)
# Setup the data every time it starts
app$on('start', function(server, ...) {
server$set_data('visits', 0)
server$set_data('cycles', 0)
})
# Count the number of cycles
app$on('cycle-start', function(server, ...) {
server$set_data('cycles', server$get_data('cycles') + 1)
})
# Count the number of requests
app$on('before-request', function(server, ...) {
server$set_data('visits', server$get_data('visits') + 1)
})
# Handle requests
app$on('request', function(server, ...) {
list(
status = 200L,
headers = list('Content-Type' = 'text/html'),
body = paste('This is indeed a test. You are number', server$get_data('visits'))
)
})
# Show number of requests in the console
app$on('after-request', function(server, ...) {
message(server$get_data('visits'))
flush.console()
})
# Terminate the server after 300 cycles
app$on('cycle-end', function(server, ...) {
if (server$get_data('cycles') > 300) {
message('Ending...')
flush.console()
server$extinguish()
}
})
# Be polite
app$on('end', function(server) {
message('Goodbye')
flush.console()
})
if (FALSE) { # \dontrun{
app$ignite(showcase = TRUE)
} # }