Interceptors

development feature

In addition to the standard plugins described in the Plugins Overview and the Plugin Example documentation, the CSE also supports a special type of Plugins called Interceptors.

Interceptors can be used to hook into the CSE's request processing and to, for example, modify requests and responses before they are processed by the CSE or sent to the client. This allows to implement custom behavior that is triggered when certain requests are received by the CSE or when certain responses are sent by the CSE.

Warning

Interceptors are a powerful tool that can be used to modify the behavior of the CSE in a way that may have unintended consequences. It is important to use Interceptors with caution and to thoroughly test them before deploying them in a production environment.

Types of Interceptors

The CSE currently supports the following types of Interceptors:

Interceptor Type	Description
Request Pre-Processing Interceptors	These Interceptors are called after a request has been validated and before it is processed by the CSE. They can be used to modify the incoming request, to perform checks on the request, or to abort the request processing by raising an appropriate error response.
Request Post-Processing Interceptors	These Interceptors are called after a request has been processed by the CSE and a response is ready to be sent to the client. They can be used to modify the outgoing response, to perform checks on the response, or to perform additional actions based on the request and response.
Request Error Response Interceptors	These Interceptors are called when an error response is generated by the CSE in response to a request. They can be used to modify the error response, to perform checks on the error response, or to perform additional actions based on the request and error response.

Writing Interceptors

An interceptor is defined as a method in a plugin class, inheriting from the acmecse.runtime.InterceptorManager.Interceptor base class, decorated with the @intercept decorator.

Arguments of the @intercept Decorator

The @intercept decorator's arguments specify the type of interceptor (i.e., the phase in which the interceptor should be called), the operation and resource type that the interceptor should be applied to, and optionally a priority for the interceptor. The phase, operation and resource type can also be lists, allowing to specify multiple phases, operations and resource types for the same interceptor handler.

Interceptor Handler Method Parameters

The method's parameters depend on the type of interceptor, but they always include the phase identifier and phase-specific parameters. The following table shows the required parameters for each type of interceptor:

Interceptor Type	Required Parameters
Phase.REQUEST_PRE_PROCESSING	request: acmecse.etc.Types.CSERequest
Phase.REQUEST_POST_PROCESSING	request: acmecse.etc.Types.CSERequest result: acmecse.etc.Types.Result
Phase.REQUEST_ERROR_RESPONSE	request: acmecse.etc.Types.CSERequest result: acmecse.etc.Types.Result

Example

The following example shows a plugin class that defines three interceptor handlers, one for each type of interceptor:

MyInterceptorPlugin.py

from acmecse.runtime.PluginSupport import *

@plugin
class MyInterceptorPlugin(Interceptor):

    @intercept(Phase.REQUEST_PRE_PROCESSING, Operation.CREATE, ResourceTypes.AE)
    def preRequestInterceptor(self, request:CSERequest) -> None:
        # This method will be called before processing any CREATE request for an AE resource
        pass

    @intercept(Phase.REQUEST_POST_PROCESSING, Operation.CREATE, [ResourceTypes.AE, ResourceTypes.CNT])
    def postRequestInterceptor(self, request:CSERequest, result: Result) -> None:
        # This method will be called after processing any CREATE request for an AE or CNT resource
        pass

    @intercept(Phase.REQUEST_ERROR_RESPONSE, Operation.ALL, ResourceTypes.ALL)
    def errorResponseInterceptor(self, request:CSERequest, result: Result) -> None:
        # This method will be called when an error response is generated for any request
        pass