Intercepting Requests

Besides defining handlers for specific routes, a module can also intercept requests that match one of its routes, both before and after the route is invoked. It is important to understand that these interceptors will only be invoked if the incoming request matches one of the routes in the module.

Note

The interceptors are very useful when you want to perform tasks, per-request, on a module level for things like security, caching and rewriting requests and responses.

Below is shown the statechart with existing extension points. Each point is a stage of the request handling pipeline and you can intercept all of them to customize the handling. The ResultConverter is described previously so here OnBefore, OnAfter and OnError are described.

The Request Handling Flow

OnBefore interceptor

The OnBefore interceptor enables you to intercept the request before it is passed to the appropriate route handler - Action. This gives you a couple of possibilities such as modifying parts of the request or even prematurely aborting the request by returning a response that will be sent back to the caller.

builder.OnBefore = async (IHttpRequest request) =>
{
    // Do something asynchronously and return null or a result object
};

Since the interceptor will be invoked for all routes in the module, there is no need to define a pattern to match. The parameter that is passed into the interceptor is an instance of the current IHttpRequest. A return value of null means that no action is taken by the interceptor and that the request should proceed to be processed by the matching route. However, if the interceptor returns some result of its own, the route will never be processed by the route and the response will be sent back to the client.

OnAfter interceptor

The OnAfter gets an instance of the current IHttpRequest and a result from previous stage. While an OnBefore interceptor is called before the route handler an OnAfter interceptor is called when the route has already been handled and a response has been generated. So here you can modify or replace the result.

builder.OnAfter = async (IHttpRequest request, object result) =>
{
    // Do something asynchronously and return a modified result
};

OnError interceptor

The OnError interceptor enables you to execute code whenever an exception occurs in any of the module routes that are being invoked. It gives you access to the current IHttpRequest and the exception that took place. So here you can handle an exception and build an error result.

builder.OnError = async (IHttpRequest request, Exception exception) =>
{
    // Do something asynchronously and return an error result
};

Global interceptors

The application pipelines enable you to perform tasks before and after routes are executed, and in the event of an error in any of the routes in the application. They behave the same way as the module pipelines (see the statechart above) but they are executed for all invoked routes, not just for the ones that are the module of the route that is being invoked.

To define the application level HTTP handler you need to implement the IHttpGlobalHandler interface and register the implementation in IoC Container.