![](reference/figures/fiery.png)

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.

## How to install this

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

``` r
# install.packages('pak')
pak::pak('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`](https://github.com/thomasp85/reqres) that
fiery uses to handle http requests and responses. Further, A plugin that
will often be used is [`routr`](https://github.com/thomasp85/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:

``` r
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> (forest_sacrificial_boa)
```

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.

## Code of Conduct

Please note that the ‘fiery’ project is released with a [Contributor
Code of Conduct](https://fiery.data-imaginist.com/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

# Package index

## The Fire object

fiery is build on top of the R6 class system and all functionality in
the package is more or less part of the Fire class. The understanding of
this class is thus integral to understanding fiery.

- [`Fire`](https://fiery.data-imaginist.com/reference/Fire.md) :
  Generate a New App Object

## Logging

Logs are an important part of many servers and fiery has a central
logging facility where callbacks and handlers can send logging
information to without worrying about where and how the logs get
written.

- [`logger_void()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_null()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_console()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_file()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_otel()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_switch()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`logger_logger()`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`common_log_format`](https://fiery.data-imaginist.com/reference/loggers.md)
  [`combined_log_format`](https://fiery.data-imaginist.com/reference/loggers.md)
  : App Logging

## Request and response objects

A lot of the logic in web servers are concerned with parsing requests
and building up responses. fiery uses the Request and Response classes
defined in the [reqres](https://github.com/thomasp85/reqres) package.
See the documentation there.

## Routing

A central part of many servers is the router that takes care of
recieving requests and directing them at the right handlers for further
processing. Being the minimal server framework that it is, fiery doesn’t
include routing functionality itself. An option is the
[routr](https://github.com/thomasp85/routr) package which is build to
work together with fiery as a plugin.

## Helpers

Most functionality is available to the user through the Fire object or
loggers. Any additional helper functions provided by fiery is documented
here.

- [`session_id_cookie()`](https://fiery.data-imaginist.com/reference/session_id_cookie.md)
  : Use a session cookie to store the id of the session

# Articles

### All vignettes

- [The event cycle in
  fiery](https://fiery.data-imaginist.com/articles/events.md):
- [Creating and using fiery
  plugins](https://fiery.data-imaginist.com/articles/plugins.md):