api.service.Router

This service implements the router of Hitchy's core. It is crucial in dispatching incoming requests to configured handlers for creating a response to be sent to the requesting client.

On bootstrap of your application, the router is used to collect defined routes and create an optimized hierarchy suitable for dispatching requests with improved performance. At runtime, the router is used to normalize every incoming request and to invoke every handler meant to process it.

A separate service called Responder is used to normalize the response manager associated with every dispatched request.

Glossary

This documentation refers to a request or a request descriptor. Both describe the same thing in context of Hitchy and commonly refer to an instance of IncomingMessage with an augmented API.

Static methods

configure()

This method is invoked by Hitchy's bootstrap code during routing stage with the list of discovered plugins as argument. It is extracting the definitions of routes from configurations of provided plugins and combines them with the routes defined in configuration of current application to eventually compile an internally maintained hierarchy of routes grouped by method and by prefix for optimized request dispatching.

await api.service.Router.configure( discoveredPlugins );

It returns a promise resolved once the router is ready for dispatching requests.

dispatch()

The method is invoked on every incoming request to process defined routes for getting a proper response. It is invoked with the received request's context as argument.

Details

Some properties of provided request context are managed by the router's dispatcher internally.

For the described request, routes matching its method and prefix are looked up in router's hierarchy compiled on bootstrap. Handlers of matching routes are sequentially invoked.

• All handlers of matching policy routes are invoked to apply filters, adjust the request descriptor and/or the response manager passed to every invoked handler.
• Only the handler of first matching controller route is invoked to provide a response.

await api.service.Router.dispatch( requestContext );

A promise is returned. It is resolved once the request has been dispatched.

Dispatching local requests

In addition to handling incoming HTTP requests, the router's dispatch() method is invoked to immediately handle locally mocked requests, too.

normalize()

This method is invoked early on every request with the request's context as argument to apply polyfills as necessary to the request itself so that it complies with the API described in this manual.

Due to Hitchy being integrated with an existing server-side framework such as Express or running standalone, the provided request may come with different sets of methods and properties. This method is trying to establish the least common denominator for what routing handlers may expect as the request's API.

api.service.Router.normalize( requestContext );

The method is expected to adjust the request included with provided context descriptor in-place.

A dedicated service implements the polyfills this method is applying on a request's API.