Combine multiple routes for sequential routing
Combine multiple routes for sequential routing
Details
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) '/') |
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 received 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.
See also
Route for defining single routes
Active bindings
attach_toThe event this routr should respond to
nameAn autogenerated name for the route stack
Methods
Method new()
Create a new RouteStack
Usage
RouteStack$new(..., path_extractor = function(msg, bin) "/")Method add_route()
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.
Method dispatch()
asses a reqres::Request through the stack of routes in s
equence 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.
Method on_attach()
Method for use by fiery when attached as a plugin. Should
not be called directly.
Method on_error()
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
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)
#> This will always get called first
#> This will get called next if the request asks for /demo/
#> [1] TRUE