Route-class: Single route dispatch
In thomasp85/routr: A Simple Router for HTTP and WebSocket Requests
Route R Documentation
Single route dispatch
Description
Class for handling a single route dispatch
Details
The Route class is used to encapsulate a single URL dispatch, that is,
chose a single handler from a range based on a URL path. A handler will be
called with a request, response, and keys argument as well as any additional
arguments passed on to dispatch().
The path will strip the query string prior to assignment of the handler, can
contain wildcards, and can be parameterised using the : prefix. If there
are multiple matches of the request path the most specific will be chosen.
Specificity is based on number of elements (most), number of parameters
(least), and number of wildcards (least), in that order. Parameter
values will be available in the keys argument passed to the handler, e.g. a
path of /user/:user_id will provide list(user_id = 123) for a dispatch on
/user/123 in the keys argument.
Handlers are only called for their side-effects and are expected to return
either TRUE or FALSE indicating whether additional routes in a
RouteStack should be called, e.g. if a handler is returning FALSE all
further processing of the request will be terminated and the response will be
passed along in its current state. Thus, the intend of the handlers is to
modify the request and response objects, in place. All calls to handlers will
be wrapped in try() and if an exception is raised the response code will be
set to 500 with the body of the response being the error message. Further
processing of the request will be terminated. If a different error handling
scheme is wanted it must be implemented within the handler (the standard
approach is chosen to avoid handler errors resulting in a server crash).
A handler is referencing a specific HTTP method (get, post, etc.) but can
also reference all to indicate that it should match all types of requests.
Handlers referencing all have lower precedence than those referencing
specific methods, so will only be called if a match is not found within the
handlers of the specific method.
Initialization
A new 'Route'-object is initialized using the new() method on the
generator or alternatively by using route():
Usage
route <- Route$new(...)
route <- route(...)
Active bindings
rootThe root of the route. Will be removed from the path of any
request before matching a handler
nameAn autogenerated name for the route
emptyIs the route empty
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
Method new()
Create a new Route
Usage
Route$new(..., ignore_trailing_slash = FALSE)
Arguments
...Handlers to add up front. Must be in the form of named lists
where the names corresponds to paths and the elements are the handlers.
The name of the argument itself defines the method to listen on (see
examples)
ignore_trailing_slashLogical. Should the trailing slash of a path
be ignored when adding handlers and handling requests. Setting this will
not change the request or the path associated with but just ensure that
both path/to/ressource and path/to/ressource/ ends up in the same
handler. Because the request is left untouched, setting this to TRUE
will not affect further processing by other routes
Method print()
Pretty printing of the object
Usage
Route$print(...)
Arguments
...Ignored
Method add_handler()
Add a handler to the specified method and path. The special
method 'all' will allow the handler to match all http request methods.
The path is a URL path consisting of strings, parameters (strings
prefixed with :), and wildcards (*), separated by /. A wildcard
will match anything and is thus not restricted to a single path element
(i.e. it will span multiple / if possible). The handler must be a
function containing the arguments request, response, keys, and
..., and must return either TRUE or FALSE. The request argument
will be a reqres::Request object and the response argument will be a
reqres::Response object matching the current exchange. The keys
argument will be a named list with the value of all matched parameters
from the path. Any additional argument passed on to the dispatch method
will be avaiable as well. This method will override an existing handler
with the same method and path.
Usage
Route$add_handler(method, path, handler, reject_missing_methods = FALSE)
Arguments
methodThe http method to match the handler to
pathThe URL path to match to
handlerA handler function
reject_missing_methodsShould requests to this path that doesn't
have a handler for the specific method automatically be rejected with a
405 Method Not Allowed response with the correct Allow header informing
the client of the implemented methods. Assigning a handler to "all" for
the same path at a later point will overwrite this functionality. Be
aware that setting this to TRUE will prevent the request from falling
through to other routes that might have a matching method and path.
Method remove_handler()
Removes the handler assigned to the specified method and
path. If no handler have been assigned it will throw a warning.
Usage
Route$remove_handler(method, path)
Arguments
methodThe http method of the handler to remove
pathThe URL path of the handler to remove
Method get_handler()
Returns a handler already assigned to the specified method
and path. If no handler have been assigned it will throw a warning.
Usage
Route$get_handler(method, path)
Arguments
methodThe http method of the handler to find
pathThe URL path of the handler to find
Method remap_handlers()
Allows you to loop through all added handlers and reassings
them at will. A function with the parameters method, path, and
handler must be provided which is responsible for reassigning the
handler given in the arguments. If the function does not reassign the
handler, then the handler is removed.
Usage
Route$remap_handlers(.f)
Arguments
.fA function performing the remapping of each handler
Method merge_route()
Merge another route into this one, adopting all its handlers.
The other route will be empty after the merge.
Usage
Route$merge_route(route, use_root = TRUE)
Arguments
routeA Route object
use_rootShould the root of route be prepended to all paths from
the route before adding them
Method dispatch()
Based on a reqres::Request object the route will find the
correct handler and call it with the correct arguments. Anything passed
in with ... will be passed along to the handler.
Usage
Route$dispatch(request, ...)
Arguments
requestThe request to route
...Additional arguments to the handlers
Method on_attach()
Method for use by fiery when attached as a plugin. Should
not be called directly. This method creates a RouteStack with the route
as the single route and then mounts that to the app. For more flexibility
create the RouteStack manually
Usage
Route$on_attach(app, on_error = NULL, ...)
Arguments
appThe Fire object to attach the router to
on_errorA function for error handling
...Ignored
Method clone()
The objects of this class are cloneable with this method.
Usage
Route$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
RouteStack for binding multiple routes sequentially
Examples
# Initialise an empty route
route <- Route$new()
# Initialise a route with handlers assigned
route <- Route$new(
all = list(
'/*' = function(request, response, keys, ...) {
message('Request received')
TRUE
}
)
)
# Remove it again
route$remove_handler('all', '/*')
thomasp85/routr documentation built on April 13, 2025, 10:36 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| Route | R Documentation |
Single route dispatch
Description
Class for handling a single route dispatch
Details
The Route class is used to encapsulate a single URL dispatch, that is,
chose a single handler from a range based on a URL path. A handler will be
called with a request, response, and keys argument as well as any additional
arguments passed on to dispatch().
The path will strip the query string prior to assignment of the handler, can
contain wildcards, and can be parameterised using the : prefix. If there
are multiple matches of the request path the most specific will be chosen.
Specificity is based on number of elements (most), number of parameters
(least), and number of wildcards (least), in that order. Parameter
values will be available in the keys argument passed to the handler, e.g. a
path of /user/:user_id will provide list(user_id = 123) for a dispatch on
/user/123 in the keys argument.
Handlers are only called for their side-effects and are expected to return
either TRUE or FALSE indicating whether additional routes in a
RouteStack should be called, e.g. if a handler is returning FALSE all
further processing of the request will be terminated and the response will be
passed along in its current state. Thus, the intend of the handlers is to
modify the request and response objects, in place. All calls to handlers will
be wrapped in try() and if an exception is raised the response code will be
set to 500 with the body of the response being the error message. Further
processing of the request will be terminated. If a different error handling
scheme is wanted it must be implemented within the handler (the standard
approach is chosen to avoid handler errors resulting in a server crash).
A handler is referencing a specific HTTP method (get, post, etc.) but can
also reference all to indicate that it should match all types of requests.
Handlers referencing all have lower precedence than those referencing
specific methods, so will only be called if a match is not found within the
handlers of the specific method.
Initialization
A new 'Route'-object is initialized using the new() method on the
generator or alternatively by using route():
Usage
route <- Route$new(...)
|
route <- route(...)
|
Active bindings
rootThe root of the route. Will be removed from the path of any request before matching a handler
nameAn autogenerated name for the route
emptyIs the route empty
Methods
Public methods
Method new()
Create a new Route
Usage
Route$new(..., ignore_trailing_slash = FALSE)
Arguments
...Handlers to add up front. Must be in the form of named lists where the names corresponds to paths and the elements are the handlers. The name of the argument itself defines the method to listen on (see examples)
ignore_trailing_slashLogical. Should the trailing slash of a path be ignored when adding handlers and handling requests. Setting this will not change the request or the path associated with but just ensure that both
path/to/ressourceandpath/to/ressource/ends up in the same handler. Because the request is left untouched, setting this toTRUEwill not affect further processing by other routes
Method print()
Pretty printing of the object
Usage
Route$print(...)
Arguments
...Ignored
Method add_handler()
Add a handler to the specified method and path. The special
method 'all' will allow the handler to match all http request methods.
The path is a URL path consisting of strings, parameters (strings
prefixed with :), and wildcards (*), separated by /. A wildcard
will match anything and is thus not restricted to a single path element
(i.e. it will span multiple / if possible). The handler must be a
function containing the arguments request, response, keys, and
..., and must return either TRUE or FALSE. The request argument
will be a reqres::Request object and the response argument will be a
reqres::Response object matching the current exchange. The keys
argument will be a named list with the value of all matched parameters
from the path. Any additional argument passed on to the dispatch method
will be avaiable as well. This method will override an existing handler
with the same method and path.
Usage
Route$add_handler(method, path, handler, reject_missing_methods = FALSE)
Arguments
methodThe http method to match the handler to
pathThe URL path to match to
handlerA handler function
reject_missing_methodsShould requests to this path that doesn't have a handler for the specific method automatically be rejected with a 405 Method Not Allowed response with the correct Allow header informing the client of the implemented methods. Assigning a handler to
"all"for the same path at a later point will overwrite this functionality. Be aware that setting this toTRUEwill prevent the request from falling through to other routes that might have a matching method and path.
Method remove_handler()
Removes the handler assigned to the specified method and path. If no handler have been assigned it will throw a warning.
Usage
Route$remove_handler(method, path)
Arguments
methodThe http method of the handler to remove
pathThe URL path of the handler to remove
Method get_handler()
Returns a handler already assigned to the specified method and path. If no handler have been assigned it will throw a warning.
Usage
Route$get_handler(method, path)
Arguments
methodThe http method of the handler to find
pathThe URL path of the handler to find
Method remap_handlers()
Allows you to loop through all added handlers and reassings
them at will. A function with the parameters method, path, and
handler must be provided which is responsible for reassigning the
handler given in the arguments. If the function does not reassign the
handler, then the handler is removed.
Usage
Route$remap_handlers(.f)
Arguments
.fA function performing the remapping of each handler
Method merge_route()
Merge another route into this one, adopting all its handlers. The other route will be empty after the merge.
Usage
Route$merge_route(route, use_root = TRUE)
Arguments
routeA Route object
use_rootShould the root of
routebe prepended to all paths from the route before adding them
Method dispatch()
Based on a reqres::Request object the route will find the
correct handler and call it with the correct arguments. Anything passed
in with ... will be passed along to the handler.
Usage
Route$dispatch(request, ...)
Arguments
requestThe request to route
...Additional arguments to the handlers
Method on_attach()
Method for use by fiery when attached as a plugin. Should
not be called directly. This method creates a RouteStack with the route
as the single route and then mounts that to the app. For more flexibility
create the RouteStack manually
Usage
Route$on_attach(app, on_error = NULL, ...)
Arguments
appThe Fire object to attach the router to
on_errorA function for error handling
...Ignored
Method clone()
The objects of this class are cloneable with this method.
Usage
Route$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
See Also
RouteStack for binding multiple routes sequentially
Examples
# Initialise an empty route
route <- Route$new()
# Initialise a route with handlers assigned
route <- Route$new(
all = list(
'/*' = function(request, response, keys, ...) {
message('Request received')
TRUE
}
)
)
# Remove it again
route$remove_handler('all', '/*')
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.