Introducing routr – Routing of HTTP and WebSocket in R

The design

routr is basically build up of two different concepts: routes and route stacks. Routes are a collection of handlers attached to specific HTTP request methods (e.g. GET, POST, PUT) and paths. When a request lands at a route one of the handlers is chosen and called, based on the nature of the request. A route stack is a collection of routes. When a request lands at a route stack it will pass it through all the routes it contains sequentially, potentially stopping if one of the handlers signals it. In the following these two concepts will be discussed in detail.

Routes

In its essence a router is a decision mechanism for redirection HTTP requests into the correct handler function based on the request URL. It makes sure that e.g. requests for http://example.com/info ends up in a different handler than http://example.com/users/thomasp85. This functionality is encapsulated in the Route class. The basic use is illustrated below:

library(routr)
route <- Route$new()
route$add_handler('get', '/info', function(request, response, keys, ...) {
  response$status <- 200L
  response$body <- list(h1 = 'This is a test server')
  TRUE
})
route$add_handler('get', '/users/thomasp85', function(request, response, keys, ...) {
  response$status <- 200L
  response$body <- list(h1 = 'This is the user information for thomasp85')
  TRUE
})
route

## A route with 2 handlers
## get: /users/thomasp85
##    : /info

Let’s walk through what happened here. First we created a new Route object and then we added two handlers to it, using the eponymous add_handler() method. Both of the handlers responds to the GET method, but differs in the path they are listening for. routr uses reqres under the hood so each handler method is passed a Request and Response pair (we’ll get back to the keys argument). Lastly, each handler must return either TRUE indicating that the next route should be called, or FALSE indicating no further routes should be called. As the request and response objects are R6 objects any changes to them will be kept outside of the handler and there is thus no need to return them.

Now, consider the situation where I have build my super fancy web service into a thriving business with millions of users - would I need to add a handler for every user? No. This would be a case for a parameterized path.

route$add_handler('get', '/users/:user_id', function(request, response, keys, ...) {
  response$status <- 200L
  response$body <- list(h1 = paste0('This is the user information for ', keys$user_id))
  TRUE
})
route

## A route with 3 handlers
## get: /users/thomasp85
##    : /users/:user_id
##    : /info

As can be seen, prefixing a path element with : will make it into a variable, matching anything that is put in there and adds it as an element to the keys argument. Paths can contain as many variable elements as wanted in order to reuse handlers as efficiently as possible.

There’s a last piece of path functionality left to discuss: The wildcard. While parameterized path elements only matches as single element (e.g. /users/:user_id will match /users/johndoe but not /users/johndoe/settings) the wildcard matches anything. Let’s try one of these:

route$add_handler('get', '/setting/*', function(request, response, keys, ...) {
  response$status_with_text(403L) # Forbidden
  FALSE
})
route$add_handler('get', '/*', function(request, response, keys, ...) {
  response$status <- 404L
  response$body <- list(h1 = 'We really couldn\'t find your page')
  FALSE
})
route

## A route with 5 handlers
## get: /users/thomasp85
##    : /users/:user_id
##    : /setting/*
##    : /info
##    : /*

Here we add two new handlers, one preventing access to anything under the /settings location, and one implementing a custom 404 - Not found page. Both returns FALSE as they are meant to prevent any further processing.

Now there’s a slight pickle with the current situation. If I ask for /users/thomasp85 it can match three different handlers: /users/thomasp85, /users/:user_id, and /*. Which to chose? routr decides on the handler based on path specificity, where handlers are prioritized based on number of elements in the path (the more the better), number of parameterized elements (the less the better), and existence of wildcards (better with none). In the above case it means that the /users/thomasp85 will be chosen. The handler priority can always be seen when printing the Route object.

The request method is less complicated than the path. It simply matches the method used in the request, ignoring the case. There’s one special method: all. This one will match any method, but only if a handler does not exist for that specific method.

Route Stacks

Conceptually, route stacks are much simpler than routes, in that they are just a sequential collection of routes, with the means to pass requests through them. Let’s create some additional routes and collect them in a RouteStack:

parser <- Route$new()
parser$add_handler('all', '/*', function(request, response, keys, ...) {
  request$parse(reqres::default_parsers)
})
formatter <- Route$new()
formatter$add_handler('all', '/*', function(request, response, keys, ...) {
  response$format(reqres::default_formatters)
})

router <- RouteStack$new()
router$add_route(parser, 'request_prep')
router$add_route(route, 'app_logic')
router$add_route(formatter, 'response_finish')
router

## A RouteStack containing 3 routes
## 1: request_prep
## 2: app_logic
## 3: response_finish

Now, when our router receives a request it will first pass it to the parser route and attempt to parse the body. If it is unsuccessful it will abort (the parse() method returns FALSE if it fails), if not it will pass the request on to the route we build up in the prior section. If the chosen handler returns TRUE the request will then end up in the formatter route and the response body will be formatted based on content negotiation with the request. As can be seen route stacks are an effective way to extract common functionality into well defined handlers.

If you’re using fiery. RouteStack objects are also what will be used as plugins. Whether to use the router for request, header, or message (WebSocket) events is decided by the attach_to field.

app <- fiery::Fire$new()
app$attach(router)
app

## ? A fiery webserver
## ?  ?   ?   ?
## ?           Running on: 127.0.0.1:8080
## ?     Plugins attached: request_routr
## ? Event handlers added
## ?              request: 1