Hitchy Core Manual

Appearance

api.service.Route ​

This service provides a class generically describing a route associating a particular incoming request with a function meant to handle that request at runtime.

It is serving as a base class for PolicyRoute and ControllerRouter.

Glossary ​

A route consists of a source and a target. On dispatching requests, a route's source is used to detect whether that route must be considered on handling a request or not. The target refers to a function that is invoked for routes that must be considered.

The source is usually a string containing a pattern for matching a request's path. A single HTTP method may be used as a space-separated prefix to that pattern to have the route apply to requests of that method, only.

The target describes a function considered a handler for requests matching the source. It accepts different formats, e.g. literal functions, strings naming a method of a controller or policy component or objects providing such information in separate properties.

Example ​

"GET /api/person/find": someFunction

In this example, the source is "GET /api/person/find" and the target is someFunction.

When dispatching a GET request for path /api/person/find, this route has to be considered due to the request's path matching the route's source. Because of that, the route's target - someFunction - is invoked to handle the request.

On dispatching an incoming POST request addressing the same path, this route must be ignored due to a mismatching source. The same applies to GET requests addressing a different path.

Constructor ​

On constructing an instance of this class, a route's source and target must be provided as arguments.

javascript
const route = new api.service.Route( "/api/:model/:id", myRequestHandlerFn );

The source is usually a string consisting of a pathname template optionally prefixed by an HTTP method. When omitting the method, ALL is assumed to match any HTTP method by default.

javascript
const route = new api.service.Route( "PATCH /api/:model/:id", myRequestHandlerFn );

The target usually is a function or a string naming a method of a controller or policy.

javascript
const route = new api.service.Route( "/api/:model/:id", "ModelController::read" );

Supported values

Eventually supported values for source and target depend on parseSource() and parseTarget() methods described below.

A third argument can be used to provide an object with options customizing route handling:

  • The boolean property isMatchingPrefix controls whether the path template provided in first argument must match the whole path of an incoming request or its leading part, only.

    This option must be provided for matching leading parts of a request's path:

    javascript
    const route = new api.service.Route( "/api/:model/:id", myFn, { 
	isMatchingPrefix: true
} );

    This difference is essential in distinguishing controller routes from policy routes. The former have to match the whole path. The latter already apply on matching the leading part of a request's path.

Static methods ​

parseSource() ​

The route's source as provided in first argument of constructor is parsed using this static method.

javascript
const info = api.service.Route.parseSource( source, isMatchingPrefix );

The second argument indicates, whether the source is meant to match the whole path of a request (false) or matching a leading part of the path is sufficient (true).

The method returns an object with these elements:

  • method provides the all-uppercase HTTP method a dispatched request has to select for matching this route. It may be "ALL" to match any HTTP request.
  • matcher is a function detecting whether some provided request path is matching the source or not.
  • prefix is the leading part of provided source that does not contain any placeholders for request parameters to match. It is used by Hitchy's core on optimizing routing tables.
  • parameters describes named parameters extracted from a matching request's path.
  • pattern is a regular expression suitable for matching request paths with provided source.
  • compile is the counterpart to matcher. It is a function rendering a request path with parameters provided as arguments.

Background

The default source parser is based on 3rd-party path-to-regexp library. You'll find additional information on some of the mentioned elements there.

parseTarget() ​

This method is parsing the route's target as given in second argument of constructor.

javascript
const info = api.service.Route.parseTarget( target );

It returns an object with these elements:

  • handler provides the function to invoke when a dispatched request is matching the route's source.
  • context provides the context to expose as this on invoking that function.
  • args lists arguments to additionally pass on invoking the function.
  • warning is optionally providing a message describing issues encountered on trying to parse and validate provided target

The default implementation accepts functions, strings addressing methods of policy or controller components as well as objects providing those elements returned.

Properties ​

source ​

This is the first argument provided on constructing the route. It expresses a condition some incoming request has to satisfy to be handled by current route.

target ​

This is the second argument provided on constructing the route. It describes some function to be invoked when an incoming request is satisfying the route's source.

method ​

The HTTP method is extracted from provided source. It defaults to special value ALL indicating current route to match any HTTP method of incoming requests.

parameters ​

This property is defining parameters extracted from matching paths.

Methods ​

matcher() ​

The method is detecting whether some path provided as sole argument is matching route's source or not. On matching provided path, parameters extracted from path based on definition in source are included with the result.

javascript
if ( route.matcher( request.path ) ) {
	// TODO e.g. handle the route ...
}

The signature strongly depends on 3rd-party library path-to-regexp.

selectProbablyCoveredPrefixes() ​

This method is invoked with a list of prefixes to return a subset of those prefixes current route is probably covered by.

It is used by service RoutesPerPrefix to optimize the management of routes by maintaining separate lists of routes per prefix.

javascript
const coveredPrefixes = route.selectProbablyCoveredPrefixes( allPrefixes );

A route is considered to probably cover a prefix if incoming requests with a path matching the prefix is probably matching the route's source, too. The resulting set of prefixes is used to include the route with one or more lists. On dispatching an incoming request, the list associated with the longest prefix matching the request's prefix is fetched and all its routes are tested for applying to the request.