By defining an array of mappings, one can decide how the server will process the incoming requests. Each mapping associates a matching criterion defined with a regular expression to a handler that will answer the request.
When a mapping is defined, its association to the handler is made through a specific property (called prefix; for instance :
The value of this property configures how the handler must behave when executed. For instance, the file handler expects a file path.
Capturing groups can be defined in the matching regular expression to extract parts of the URL and reuse them in the property (they are identified with
Consequently, the following mapping will match the URL
/sample/index.html and serve the request with the file
REserve is designed on a simple architecture summarized by the following Block diagram
TAM Block diagram of the technical architecture
There are 4 main building blocks (a.k.a. agents) namely :
- The configuration reader
- The server
- The dispatcher
- The handlers
These are required to run the server but one last additional component enables testing : the mock one.
The configuration agent exposes two methods.
On one hand, it offers the
read method capable of reading JSON configuration files. To enforce reusability, it also supports the inclusion of other files using the
extends keyword. When deserialized this way, every path is relative to the folder where the configuration file is stored.
On the other hand, either after reading the configuration from a file or once it was built from a literal, the agent exposes the
check method to validate the configuration.
In particular :
- handlers are loaded and their definition checked
- each mapping is verified based on the corresponding handler that may provide a schema and a
The serve agent is responsible of :
- building an event emitter object
- instantiating the http(s) server
- forwarding the incoming requests to the dispatcher
Provided you have a verified configuration object, it is the main entry point to start the server.
The dispatcher agent is the heart of REserve; it routes the received requests to the different handlers using the following algorithm :
- it matches the incoming
request.urlwith mappings' regular expressions
- when a is match found, it executes the handler’s
- if the executed handler does an internal redirection (the method returns a promise resolved to a new URL or a status code), it restarts the matching process from the first mapping
- Otherwise, it continues through the list of mappings until the
This cycle is illustrated in the following activity diagram.
TAM Activity diagram of the dispatcher algorithm
Each handler implements an async
redirect method receiving :
- the request object
- the response object
- the mapping being matched
- the regular expression matching result
- the specific property value (where capturing groups are replaced)
- a configuration interface (offering advanced services that will be detailed later)
Five handlers are provided out of the box with REserve.
The file handler answers requests by serving files from the local file system. It supports only the verb
GET and - unless you install - a restricted list of mime types (check the documentation). It also implements helpful behaviors :
- incoming URL parameters are automatically stripped out to simplify the matching expression
- directory access is internally redirected to the inner
index.htmlfile (if any)
This mapping will answer the URL
/sample/index.html?parameter=value#hash with the content of the file
The url handlers forwards the incoming requests to a remote URL, all verbs are supported.
The custom handler offers a simplified interface to create custom handlers. The code might be loaded using(for a JSON configuration file) or by passing a
function. It also provides file monitoring to reload the implementation if changed.
This mapping will add the response header
'Access-Control-Allow-Origin' to all incoming requests and the processing will go through the remaining mappings.
The status handlers ends any request with a given status, see the associated documentation.
The use handler enables the reuse of express middleware functions.
This part will be detailed in a later article with some use cases but it can be seen as an adapter to fit express middleware functions to REserve.
This mapping executes the express-session middleware to create sessions.
The mock component is a substitute to the serve agent designed to provide a controlled environment to test a configuration. It offers a method to simulate a request by dispatching it and waiting for its processing to be completed.