Fire: Generate a New App Object
In fiery: A Lightweight and Flexible Web Framework
Fire R Documentation
Generate a New App Object
Description
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.
Initialization
A new 'Fire'-object is initialized using the new() method on the generator:
app <- Fire$new(host = '127.0.0.1', port = 8080L)
Copying
As Fire objects are using reference semantics new copies of an app cannot
be made simply be assigning it to a new variable. If a true copy of a Fire
object is desired, use the clone() method.
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.
rootThe location of the app. Setting this will remove the root value from requests (or decline them with 400 if the request does not match the root). E.g. the path of a request will be changed from /demo/test to /test if root == '/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
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Create a new Fire app
Usage
Fire$new(host = "127.0.0.1", port = 8080)
Arguments
hostA string overriding the default host
portAn port number overriding the default port
Returns
A Fire object
Method format()
Human readable description of the app
Usage
Fire$format(...)
Arguments
...ignored
Returns
A character vector
Method ignite()
Begin running the server. Will trigger the start event
Usage
Fire$ignite(block = TRUE, showcase = FALSE, ..., silent = FALSE)
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
...Arguments passed on to the start handler
silentShould startup messaging by silenced
Method start()
Synonymous method to ignite()
Usage
Fire$start(...)
Arguments
...passed on to ignite()
Method reignite()
Resume a session. This is equivalent to ignite() but will also trigger the resume event
Usage
Fire$reignite(...)
Arguments
...passed on to ignite()
Method resume()
Synonymous method to reignite()
Usage
Fire$resume(...)
Arguments
...passed on to ignite()
Method extinguish()
Stop the server. Will trigger the end event
Usage
Fire$extinguish()
Method stop()
Synonymous method to extinguish()
Usage
Fire$stop()
Method on()
Add a handler to an event. See the The event cycle in fiery vignette for more information.
Usage
Fire$on(event, handler, pos = NULL)
Arguments
eventThe name of the event that should trigger the handler
handlerThe handler function that should be triggered
posThe position in the handler stack to place it at. NULL will place it at the end.
Returns
A unique string identifying the handler
Method off()
Remove an event handler from the app.
Usage
Fire$off(handlerId)
Arguments
handlerIdThe unique id identifying the handler
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.
Usage
Fire$trigger(event, ...)
Arguments
eventThe name of the event
...Arguments passed on to the handlers
Returns
A named list containing the return values of all handlers attached to the event
Method send()
Send a Websocket message to a client. Will trigger the send event.
Usage
Fire$send(message, id)
Arguments
messageThe message to send
idThe id of the client to send to. If missing, the message will be send to all clients
Method close_ws_con()
Close a Websocket connection. Will trigger the websocket-closed event
Usage
Fire$close_ws_con(id)
Arguments
idThe id of the client to close the websocket connection to
Method attach()
Attach a plugin to the app. See the Creating and using fiery plugins vignette for more information
Usage
Fire$attach(plugin, ..., force = FALSE)
Arguments
pluginThe plugin to attach
...Arguments to pass into the plugins on_attach() method
forceIf the plugin has already been attached an error is thrown, unless force = TRUE which tells the app to reattach it
Method has_plugin()
Check if the app has a plugin attached
Usage
Fire$has_plugin(name)
Arguments
nameThe name of the plugin
Returns
A boolean indicating if the given plugin is already attached
Method header()
Add a global http header that will be applied to all responses
Usage
Fire$header(name, value)
Arguments
nameThe name of the header
valueThe value of the header. Use NULL to remove the global header
Method set_data()
Add data to the global data store
Usage
Fire$set_data(name, value)
Arguments
nameThe name identifying the data
valueThe data to add
Method get_data()
Retrieve data from the global data store
Usage
Fire$get_data(name)
Arguments
nameThe name identifying the data
Returns
The data requested. Returns NULL if the store does not contain the requested data
Method remove_data()
Remove data from the global data store
Usage
Fire$remove_data(name)
Arguments
nameThe name identifying the data to be removed
Method time()
Add a timed evaluation that will be evaluated after the given number of seconds. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$time(expr, then, after, loop = FALSE)
Arguments
exprThe expression to evaluate when the time has passed
thenA handler to call once expr has been evaluated
afterThe time in second to wait before evaluating expr
loopShould expr be called repeatedly with the interval given by after
Returns
A unique id identifying the handler
Method remove_time()
Remove a timed evaluation
Usage
Fire$remove_time(id)
Arguments
idThe unique id identifying the handler
Method delay()
Add a delayed evaluation to be evaluated immediately at the end of the loop cycle. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$delay(expr, then)
Arguments
exprThe expression to evaluate at the end of the cycle
thenA handler to call once expr has been evaluated
Returns
A unique id identifying the handler
Method remove_delay()
Remove a delayed evaluation
Usage
Fire$remove_delay(id)
Arguments
idThe unique id identifying the handler
Method async()
Add an asynchronous evaluation to be evaluated in another process without blocking the server. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$async(expr, then)
Arguments
exprThe expression to evaluate at the end of the cycle
thenA handler to call once expr has been evaluated
Returns
A unique id identifying the handler
Method remove_async()
Remove an async evaluation
Usage
Fire$remove_async(id)
Arguments
idThe unique id identifying the handler
Method set_client_id_converter()
Sets the function that converts an HTTP request into a specific client id
Usage
Fire$set_client_id_converter(converter)
Arguments
converterA function with the argument request
Method set_logger()
Sets the logging function to use
Usage
Fire$set_logger(logger)
Arguments
loggerA function with the arguments event, message, request, and ...
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, ...)
Arguments
eventThe event associated with the message
messageThe message to log
requestThe Request object associated with the message, if any.
...Additional arguments passed on to the logger.
Method is_running()
Test if an app is running
Usage
Fire$is_running()
Method test_request()
Send a request directly to the request logic of a non-running app. Only intended for testing the request logic
Usage
Fire$test_request(request)
Arguments
requestThe request to send
Method test_header()
Send a request directly to the header logic of a non-running app. Only intended for testing the request logic
Usage
Fire$test_header(request)
Arguments
requestThe request to send
Method test_message()
Send a message directly to the message logic of a non-running app. Only intended for testing the websocket logic
Usage
Fire$test_message(request, binary, message, withClose = TRUE)
Arguments
requestThe request to use to establish the connection
binaryIs the message send in binary or character format
messageThe message to send. If binary = FALSE a character vector, if binary = TRUE a raw vector
withCloseShould the websocket connection be closed at the end by the client
Method test_websocket()
Send a message directly from a non-running app. Only intended for testing the websocket logic
Usage
Fire$test_websocket(request, message, close = TRUE)
Arguments
requestThe request to use to establish the connection
messageThe message to send from the app
closeShould the websocket connection be closed at the end by the server
Method clone()
The objects of this class are cloneable with this method.
Usage
Fire$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
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()
})
## Not run:
app$ignite(showcase = TRUE)
## End(Not run)
fiery documentation built on March 31, 2023, 6:54 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Fire | R Documentation |
Generate a New App Object
Description
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.
Initialization
A new 'Fire'-object is initialized using the new() method on the generator:
app <- Fire$new(host = '127.0.0.1', port = 8080L)
|
Copying
As Fire objects are using reference semantics new copies of an app cannot
be made simply be assigning it to a new variable. If a true copy of a Fire
object is desired, use the clone() method.
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.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
Methods
Public methods
Method new()
Create a new Fire app
Usage
Fire$new(host = "127.0.0.1", port = 8080)
Arguments
hostA string overriding the default host
portAn port number overriding the default port
Returns
A Fire object
Method format()
Human readable description of the app
Usage
Fire$format(...)
Arguments
...ignored
Returns
A character vector
Method ignite()
Begin running the server. Will trigger the start event
Usage
Fire$ignite(block = TRUE, showcase = FALSE, ..., silent = FALSE)
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
...Arguments passed on to the
starthandlersilentShould startup messaging by silenced
Method start()
Synonymous method to ignite()
Usage
Fire$start(...)
Arguments
...passed on to
ignite()
Method reignite()
Resume a session. This is equivalent to ignite() but will also trigger the resume event
Usage
Fire$reignite(...)
Arguments
...passed on to
ignite()
Method resume()
Synonymous method to reignite()
Usage
Fire$resume(...)
Arguments
...passed on to
ignite()
Method extinguish()
Stop the server. Will trigger the end event
Usage
Fire$extinguish()
Method stop()
Synonymous method to extinguish()
Usage
Fire$stop()
Method on()
Add a handler to an event. See the The event cycle in fiery vignette for more information.
Usage
Fire$on(event, handler, pos = NULL)
Arguments
eventThe name of the event that should trigger the handler
handlerThe handler function that should be triggered
posThe position in the handler stack to place it at.
NULLwill place it at the end.
Returns
A unique string identifying the handler
Method off()
Remove an event handler from the app.
Usage
Fire$off(handlerId)
Arguments
handlerIdThe unique id identifying the handler
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.
Usage
Fire$trigger(event, ...)
Arguments
eventThe name of the event
...Arguments passed on to the handlers
Returns
A named list containing the return values of all handlers attached to the event
Method send()
Send a Websocket message to a client. Will trigger the send event.
Usage
Fire$send(message, id)
Arguments
messageThe message to send
idThe id of the client to send to. If missing, the message will be send to all clients
Method close_ws_con()
Close a Websocket connection. Will trigger the websocket-closed event
Usage
Fire$close_ws_con(id)
Arguments
idThe id of the client to close the websocket connection to
Method attach()
Attach a plugin to the app. See the Creating and using fiery plugins vignette for more information
Usage
Fire$attach(plugin, ..., force = FALSE)
Arguments
pluginThe plugin to attach
...Arguments to pass into the plugins
on_attach()methodforceIf the plugin has already been attached an error is thrown, unless
force = TRUEwhich tells the app to reattach it
Method has_plugin()
Check if the app has a plugin attached
Usage
Fire$has_plugin(name)
Arguments
nameThe name of the plugin
Returns
A boolean indicating if the given plugin is already attached
Method header()
Add a global http header that will be applied to all responses
Usage
Fire$header(name, value)
Arguments
nameThe name of the header
valueThe value of the header. Use
NULLto remove the global header
Method set_data()
Add data to the global data store
Usage
Fire$set_data(name, value)
Arguments
nameThe name identifying the data
valueThe data to add
Method get_data()
Retrieve data from the global data store
Usage
Fire$get_data(name)
Arguments
nameThe name identifying the data
Returns
The data requested. Returns NULL if the store does not contain the requested data
Method remove_data()
Remove data from the global data store
Usage
Fire$remove_data(name)
Arguments
nameThe name identifying the data to be removed
Method time()
Add a timed evaluation that will be evaluated after the given number of seconds. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$time(expr, then, after, loop = FALSE)
Arguments
exprThe expression to evaluate when the time has passed
thenA handler to call once
exprhas been evaluatedafterThe time in second to wait before evaluating
exprloopShould
exprbe called repeatedly with the interval given byafter
Returns
A unique id identifying the handler
Method remove_time()
Remove a timed evaluation
Usage
Fire$remove_time(id)
Arguments
idThe unique id identifying the handler
Method delay()
Add a delayed evaluation to be evaluated immediately at the end of the loop cycle. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$delay(expr, then)
Arguments
exprThe expression to evaluate at the end of the cycle
thenA handler to call once
exprhas been evaluated
Returns
A unique id identifying the handler
Method remove_delay()
Remove a delayed evaluation
Usage
Fire$remove_delay(id)
Arguments
idThe unique id identifying the handler
Method async()
Add an asynchronous evaluation to be evaluated in another process without blocking the server. See the Delaying code execution in Fiery vignette for more information
Usage
Fire$async(expr, then)
Arguments
exprThe expression to evaluate at the end of the cycle
thenA handler to call once
exprhas been evaluated
Returns
A unique id identifying the handler
Method remove_async()
Remove an async evaluation
Usage
Fire$remove_async(id)
Arguments
idThe unique id identifying the handler
Method set_client_id_converter()
Sets the function that converts an HTTP request into a specific client id
Usage
Fire$set_client_id_converter(converter)
Arguments
converterA function with the argument
request
Method set_logger()
Sets the logging function to use
Usage
Fire$set_logger(logger)
Arguments
loggerA function with the arguments
event,message,request, and...
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, ...)
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.
Method is_running()
Test if an app is running
Usage
Fire$is_running()
Method test_request()
Send a request directly to the request logic of a non-running app. Only intended for testing the request logic
Usage
Fire$test_request(request)
Arguments
requestThe request to send
Method test_header()
Send a request directly to the header logic of a non-running app. Only intended for testing the request logic
Usage
Fire$test_header(request)
Arguments
requestThe request to send
Method test_message()
Send a message directly to the message logic of a non-running app. Only intended for testing the websocket logic
Usage
Fire$test_message(request, binary, message, withClose = TRUE)
Arguments
requestThe request to use to establish the connection
binaryIs the message send in binary or character format
messageThe message to send. If
binary = FALSEa character vector, ifbinary = TRUEa raw vectorwithCloseShould the websocket connection be closed at the end by the client
Method test_websocket()
Send a message directly from a non-running app. Only intended for testing the websocket logic
Usage
Fire$test_websocket(request, message, close = TRUE)
Arguments
requestThe request to use to establish the connection
messageThe message to send from the app
closeShould the websocket connection be closed at the end by the server
Method clone()
The objects of this class are cloneable with this method.
Usage
Fire$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
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()
})
## Not run:
app$ignite(showcase = TRUE)
## End(Not run)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.