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
routesGices the name of all routes in the stack
emptyIs the route stack empty
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 add_redirect()
Adds a permanent (308) or temporary (307) redirect from a
path to another. The paths can contain path arguments and wildcards, but
all those present in to must also be present in from (the reverse is
not required)
Arguments
methodThe http method to match the handler to
fromThe path the redirect should respond to
toThe path the redirect should signal to the client as the new path
permanentLogical. If
TRUEthen a 308 Permanent Redirect is send back, instructing the client to update the URL in the browser to show the new path as well as avoid sending requests to the old URL again. IfFALSEthen a 307 Temporary Redirect is send back, instructing the client to proceed as if the response comes from the old path
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.
![[Deprecated]](figures/lifecycle-deprecated.svg)
Method merge_stack()
Merge two route stacks together adding all routes from the other route to this. The other route stack will be empty after this.
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