Add Custom Filters¶
Filters are set of execution points in the request and response flow that intercept the request before it goes to the backend service and intercepts the response before forwarding to the client. Filters are applied to all the APIs exposed via Microgateway. Custom filter can be engaged to Microgateway runtime using the Microgateway toolkit. If there is a common functionality required by all the APIs exposed via the Microgateway then custom filter written in ballerina language can be used for that
How to add a custom filter¶
Filters can be defined in the deployment-config.toml
file in the project conf (<PROJECT_HOME>/conf
) folder.
This project is the Microgateway project which is generated by executing the micro-gw init <PROJECT_NAME>
command.
Filter has the following methods to intercept the request and the response. Filter name can be any valid name and it is mandatory to have the
filterRequest
and filterRequest
methods in the filter object.
Info
It is written in Ballerina 1.2.x so follow API docs in Ballerina documentation for language guide.
import ballerina/http;
public type CustomFilter object {
public function filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns boolean {
return true;
}
public function filterResponse(http:Response response, http:FilterContext context) returns boolean {
return true;
}
}
-
Write the custom filter logic in ballerina language. And save the content in a file with a .bal extension.
import ballerina/http; public type CustomFilter object { public function filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns boolean { //Check if particular header present in the request. If header is present allow th request otherwise block the request. if(request.hasHeader("X-Auth")) { return true; } //If header is missing responds to the client. http:Response resp = new; resp.setTextPayload("X-Auth header is missing in the request"); var result = caller->respond(resp); return false; } public function filterResponse(http:Response response, http:FilterContext context) returns boolean { return true; } };
-
Copy the implemented .bal file into the
<PROJECT_HOME>/extensions
folder. -
Define the custom filter in the
deployment-config.toml
as in below. Position starts from index 1.[[filters]] name = "CustomFilter" position = 1
|
4.Then build the project. Custom filter will be engaged in the runtime.
Skip endpoints for custom filters¶
To skip filters for health, token, and other similar APIs you can use the filter implementation given below.
- Add the following inside the
filterRequest
andfilterResponse
methods.string SKIP_ALL_FILTERS = "skip_filters"; if (context.attributes.hasKey(SKIP_ALL_FILTERS) && <boolean>context.attributes[SKIP_ALL_FILTERS]) { return true; }
-
To set the filter position parameter, go to the
deployment.toml
file and add the configuration given below.[[filters]] name = "TestFilter" position = 2
Note
If the custom filter chain is prior to the
pre_authn_filter
, then the context will not have theSKIP_ALL_FILTERS
value set. Therefore, set the custom filterposition
to 2 or greater. -
A sample filter implementation is shown below.
import ballerina/http; public type TestFilter object { public function filterRequest(http:Caller caller, http:Request request, http:FilterContext context) returns boolean { string SKIP_ALL_FILTERS = "skip_filters"; if (context.attributes.hasKey(SKIP_ALL_FILTERS) && <boolean>context.attributes[SKIP_ALL_FILTERS]) { return true; } request.setHeader("customRequestHeader1", "Value1"); return true; } public function filterResponse(http:Response response, http:FilterContext context) returns boolean { string SKIP_ALL_FILTERS = "skip_filters"; if (context.attributes.hasKey(SKIP_ALL_FILTERS) && <boolean>context.attributes[SKIP_ALL_FILTERS]) { return true; } response.setHeader("customResponseHeader1", "Value2"); return true; } };