RouteStack {routr}R Documentation

Combine multiple routes for sequential routing

Description

The RouteStack class encapsulate multiple Routes and lets a request be passed through each sequentially. If a route is returning FALSE upon dispatch further dispatching is cancelled.

Initialization

A new 'RouteStack'-object is initialized using the new() method on the generator:

Usage

route <- RouteStack$new(..., path_extractor = function(msg, bin) '/')

Arguments

... Routes to add up front. Must be in the form of named arguments containing Route objects.
path_extractor A function that returns a path to dispatch on from a WebSocket message. Will only be used if attach_to == 'message'. Defaults to a function returning '/'

Field

The following fields are accessible in a RouteStack object:

attach_to

Either "request" (default), "header", or "message" that defines which event the router should be attached to when used as a fiery plugin.

name

The plugin name (used by fiery). Will return '<attach_to>_routr' (e.g. 'request_routr' if attach_to == 'request')

Methods

The following methods are accessible in a RouteStack object:

add_route(route, name, after = NULL)

Adds a new route to the stack. route must be a Route object, name must be a string. If after is given the route will be inserted after the given index, if not (or NULL) it will be inserted in the end of the stack.

has_route(name)

Test if the routestack contains a route with the given name.

remove(name)

Removes the route with the given name from the stack.

dispatch(request, ...)

Passes a reqres::Request through the stack of routes in sequence until one of the routes return FALSE or every route have been passed through. ... will be passed on to the dispatch of each Route on the stack.

on_error(fun)

Set the error handling function. This must be a function that accepts an error, request, and reponse argument. The error handler will be called if any of the route handlers throws an error and can be used to modify the 500 response before it is send back. By default, the error will be signaled using message

on_attach(app, on_error = NULL, ...)

Method for use by fiery when attached as a plugin. Should not be called directly.

Fiery plugin

A RouteStack object is a valid fiery plugin and can thus be passed in to the attach() method of a Fire object. When used as a fiery plugin it is important to be concious for what event it is attached to. By default it will be attached to the request event and thus be used to handle HTTP request messaging. An alternative is to attach it to the header event that is fired when all headers have been recieved but before the body is. This allows you to short-circuit request handling and e.g. reject requests above a certain size. When the router is attached to the header event any handler returning FALSE will signal that further handling of the request should be stopped and the response in its current form should be returned without fetching the request body.

One last possibility is to attach it to the message event and thus use it to handle WebSocket messages. This use case is a bit different from that of request and header. As routr uses Request objects as a vessel between routes and WebSocket messages are not HTTP requests, some modification is needed. The way routr achieves this is be modifying the HTTP request that established the WebSocket connection and send this through the routes. Using the path_extractor function provided in the RouteStack constructor it will extract a path to dispatch on and assign it to the request. Furthermore it assigns the message to the body of the request and sets the Content-Type header based on whether the message is binary application/octet-stream or not text/plain. As WebSocket communication is asynchronous the response is ignored when attached to the message event. If communication should be send back, use server$send() inside the handler(s).

How a RouteStack is attached is defined by the attach_to field which must be either 'request', 'header', or 'message'.

When attaching the RouteStack it is possible to modify how errors are handled, using the on_error argument, which will change the error handler set on the RouteStack. By default the error handler will be changed to using the fiery logging system if the Fire object supports it.

Methods

Public methods

Method new()

Usage
RouteStack$new(..., path_extractor = function(msg, bin) "/")

Method print()

Usage
RouteStack$print(...)

Method add_route()

Usage
RouteStack$add_route(route, name, after = NULL)

Method get_route()

Usage
RouteStack$get_route(name)

Method has_route()

Usage
RouteStack$has_route(name)

Method remove_route()

Usage
RouteStack$remove_route(name)

Method dispatch()

Usage
RouteStack$dispatch(request, ...)

Method on_attach()

Usage
RouteStack$on_attach(app, on_error = NULL, ...)

Method on_error()

Usage
RouteStack$on_error(fun)

Method clone()

The objects of this class are cloneable with this method.

Usage
RouteStack$clone(deep = FALSE)
Arguments
deep

Whether to make a deep clone.

See Also

Route for defining single routes

Examples

# Create a new stack
routes <- RouteStack$new()

# Populate it wih routes
first <- Route$new()
first$add_handler('all', '*', function(request, response, keys, ...) {
  message('This will always get called first')
  TRUE
})
second <- Route$new()
second$add_handler('get', '/demo/', function(request, response, keys, ...) {
  message('This will get called next if the request asks for /demo/')
  TRUE
})
routes$add_route(first, 'first')
routes$add_route(second, 'second')

# Send a request through
rook <- fiery::fake_request('http://example.com/demo/', method = 'get')
req <- reqres::Request$new(rook)
routes$dispatch(req)
[Package routr version 0.4.1 Index]