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, for example, 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	These Interceptors are called after a request has been validated and before it is processed by the CSE. Raising an error will stop further processing of the request. The Request Error Response Interceptors will be called if an error is raised.
Request Post-Processing	These Interceptors are called after a request has been processed by the CSE and a response is ready to be sent to the client.
Request Pre-Sending	These Interceptors are called just before a request is sent from the CSE to a another CSE, an AE, or a any other target. Raising an error will stop further processing of the request. The Request Error Response Interceptors will be called if an error is raised.
Request Post-Sending	These Interceptors are called after receiving a response to a request that has been sent from the CSE to a another CSE, an AE, or a any other target.
Request Error Response	These Interceptors are called when an error response is generated by the CSE in response to a request.

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	Provided 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