A Lightweight and Flexible Web Framework

A very flexible framework for building server side logic in R. The framework is unopinionated when it comes to how HTTP requests and WebSocket messages are handled and supports all levels of app complexity; from serving static content to full-blown dynamic web-apps. Fiery does not hold your hand as much as e.g. the shiny package does, but instead sets you free to create your web app the way you want.


Travis-CI Build Status AppVeyor Build Status CRAN_Status_Badge CRAN_Download_Badge Coverage Status

Fiery is a flexible and lightweight framework for building web servers in R. It is relatively unopinionated about how you chose to build your server logic and supports many use cases, from serving static files to being used as a base for a model-view-controller based setup.

Before going any further I will briefly address what most people are thinking of when they think R+web: Shiny:

Is this a competing framework to Shiny?

In a way, yes. Any package that provides functionality for creating web applications in R will be competing for the developers who wish to make web apps. This is of course reinforced by the name of the package, which is a gentle jab at Shiny. But mostly no. I believe Shiny and Fiery will appeal to vastly different use cases, in the same way as automakers and motorbike makers are in theory competing for the customers who wish to acquire the means to transport themselves, but would never be seen as truly competing.

So what is so different about Fiery?

Without falling too much into the trap of defining a project by how it differs from another, there are some very clear differences in approach between Fiery and Shiny.

  • Shiny uses magic to make everything work from R, Fiery lets you do all the hard work.
  • Shiny wants the main app-logic to be server-side, Fiery don't care what you do.
  • Shiny uses a reactive model to define the app-logic, Fiery don't care what you do (see a pattern emerge).
  • Shiny wants you to use htmltools to build the html, Fiery really don't care what you use.

From the above it is quite clear that Fiery to a higher degree gives you the choice and responsibility of building up your app at the cost of higher complexity, but with the goal of giving you more power over what you can do.

So how is this different from httpuv?

Now we're getting somewhere! httpuv is sitting in the bottom of the stack for both Shiny and Fiery, but where Shiny build an elaborate, opinionated and complete framework on top of httpuv, Fiery "merely" adds a lot of convenience to running a httpuv based web server. You could say that Fiery sits between httpuv and Shiny, and that Shiny (or an alternative framework) could in theory be build on top of Fiery.

How to install this

Install the release from CRAN using install.packages('fiery') or get the development version directly from GitHub using devtools:

# install.packages('devtools')
devtools::install_github('thomasp85/fiery')

Design

Fiery is designed around a clear server life-cycle with events being triggered at specific points during the life-cycle that will call the handlers attached to these events. In addition to the life-cycle events, it is possible to trigger custom events and attach handlers to these as well. Fiery is designed with modularity in mind so that plugins can be developed for different tasks and mixed and matched to suit the specific project.

While the intro might indicate that fiery is difficult to use, this is not the case. Much of the hard work of handling http requests has been encapsulated in the reqres that fiery uses to handle http requests and responses. Further, A plugin that will often be used is routr, which provides powerful routing of HTTP requests, thus simplifying the server logic even more.

A minimal example

Following is a very Hello World-ish example of a fiery app (sans routr), that showcases some of the different life-cycle events:

library(fiery)
 
# Create a New App
app <- Fire$new()
 
# 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 (internal loops)
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, request, ...) {
    response <- request$respond()
    response$status <- 200L
    response$body <- paste0('<h1>This is indeed a test. You are number ', server$get_data('visits'), '</h1>')
    response$type <- 'html'
})
 
# Show number of requests in the console
app$on('after-request', function(server, ...) {
    message(server$get_data('visits'))
    flush.console()
})
 
# Terminate the server after 50 cycles
app$on('cycle-end', function(server, ...) {
    if (server$get_data('cycles') > 50) {
        message('Ending...')
        flush.console()
        server$extinguish()
    }
})
 
# Be polite
app$on('end', function(server) {
    message('Goodbye')
    flush.console()
})
 
app$ignite(showcase = TRUE)
#> Fire started at 127.0.0.1:8080
#> message: 1
#> message: 2
#> message: 3
#> message: 4
#> message: Goodbye

In general much of the logic will happen in the request and message handlers and you are free to ignore the other life-cycle events if they are not needed.

Feedback

I would love some feedback on this - open an issue or reach out to me on twitter.

News

fiery 1.1.0.9999

  • Fix bug with root mounting of app where the root would be stripped before checking if it exists.
  • Fix a bug when evaluating multiple futures at once, where the removal of the futures would throw an error (#28)
  • Fix a bug preventing setting loggers on cloned apps (#30)
  • The call that raises a caught error is now recorded in the log (#33)

fiery 1.1.0

  • Add logging API. Set custom loggers with set_logger() and send messages to the log with log(). Logging is automatically delayed so it doesn't slow down request and message handling (#18).
  • Added access_log_format field to define how requests are logged.
  • Added is_running() method to query the state of the server.
  • Capture errors in each handler for events and delayed execution, so that evaluation of the other handlers are unaffected (#20).
  • Document the use of delayed evaluation. See ?delay_doc

fiery 1.0.0

  • Fire$new() now takes a port and host argument to set these fields on initialisation. (fixes #5)
  • BREAKING Results from before-request and before-message events are now passed on to the request and message handlers as a list in the arg_list argument rather than as single arguments.
  • The host and port are now advertised when a server is started/resumed (#11)
  • Fire objects now has a print method (#12)
  • BREAKING fiery now uses the reqres Request and Response classes for handling http exchange.
  • BREAKING attach() now expect a on_attach() method rather than a onAttach() method from the plugin. It also expects a name field and optionally a require field
  • BREAKING The header event now expect handlers to return a logical, with TRUE indicating further processing, and FALSE indicating termination.
  • Cycle events are now triggered when running with block = FALSE making the two run modes identical in their life cycle events.
  • BREAKING The after-request event will no longer pass the response to handlers. This can be retrieved from the request object.
  • The server can now be mounted at a path, which will strip that path from request paths thus making the app logic independent on mounting. Use the root field to access and change the root location.
  • Websocket connections can now be closed from the server by using the close_ws_con() method.
  • Better documentation. Events and plugins now has their own documentation entries (fixes #10).
  • Convert roxygen documentation to md format
  • BREAKING fields now uses snake_case rather than camelCase for a more consistent interface. This means refreshRate -> refresh_rate, triggerDir -> trigger_dir.
  • Switch to MIT License
  • Catch errors in start and resume event handlers

fiery 0.2.3

  • DelayStack uses sequential futures with lazy = TRUE because previously used lazy futures are deprecated

fiery 0.2.2

  • Changed default host to 127.0.0.1
  • Fixed test errors on Windows builders

fiery 0.2.0

  • Added fake_request to generate fake, rook-compliant, request objects. Useful for testing
  • Added header method to Fire for setting global header policies
  • Added standard 4xx responses
  • Added FutureStack class and subclasses to capture expressions for later, timed, and async evaluation
  • Added delay, remove_delay, time, remove_time, async, and remove_async methods to Fire for adding delayed, timed, and async expressions for evaluation

fiery 0.1.0

  • Added Fire class encapsulating the server runtime
  • Added HandlerStack class to store and trigger event handlers

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.

install.packages("fiery")

1.1.1 by Thomas Lin Pedersen, 4 months ago


https://github.com/thomasp85/fiery


Report a bug at https://github.com/thomasp85/fiery/issues


Browse source code at https://github.com/cran/fiery


Authors: Thomas Lin Pedersen [aut, cre]


Documentation:   PDF Manual  


Task views: Web Technologies and Services


MIT + file LICENSE license


Imports R6, assertthat, httpuv, uuid, utils, stringi, future, later, stats, reqres, glue, crayon

Suggests testthat, covr


Suggested by reqres, routr.


See at CRAN