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.
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 '/' |
The following fields are accessible in a RouteStack object:
attach_toEither "request" (default), "header", or "message"
that defines which event the router should be attached to when used as a
fiery plugin.
nameThe plugin name (used by fiery). Will return '<attach_to>_routr' (e.g. 'request_routr' if attach_to == 'request')
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.
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.
Route for defining single routes
new()RouteStack$new(..., path_extractor = function(msg, bin) "/")print()# 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)
#> This will always get called first
#> This will get called next if the request asks for /demo/
#> [1] TRUE