In addition to limiter endpoints for platform rate limiting, the SIP SIS also provides a Java API allowing the implementation of custom overload control plugins. Overload control plugins are invoked by the SIS for every request received from the network prior to the application of regular endpoint rate limiting.
Overload Control Plugin Registration
An overload control plugin is registered with a SIS instance using the SipFactory.registerOverloadControlPlugin(SipOverloadControlPlugin) operation.
At most one plugin may be registered with each SIS instance in each JVM at any one time.
Attempting to register a plugin while one is already registered will replace the existing registration with the new one.
Overload control plugins are expected to be registered with the SIS by an SBB.
For example, the root SBB of a service may respond to a ServiceNodeStartedEvent by instantiating a plugin implementation object and registering that with the SIS when the service is activated.
Later, when the service is deactivated and the ServiceNodeActivity ends, the SBB would deregister the plugin from the SIS.
Overload Control Plugin API
The Java API for the overload control plugin is given here.
The interface contains only a single operation - invoke(SipRequest) - which the SIS invokes when it needs an overload control instruction for an inbound network request.
An overload control plugin may return one of four instructions for each request it considers:
accept |
The request is accepted by the overload control plugin and should be passed up the software stack as a normal request. If the request is an initial request, this means it is subject to regular SIS rate limiting. |
exempt |
The request is accepted by the overload control plugin is considered exempt from regular SIS rate limiting. This means it must be passed up the software stack into the Session and Application layers. |
reject |
The request has been rejected by the overload control plugin and a SIP error response should be returned to the network. The overload control plugin may provide the response to use for the request, otherwise the SIS will use its default rate limiting error response instead. Caution must be used when rejecting requests, as doing so may break various call flows and application state machines. As a rule of thumb, mid-dialog requests should not be rejected, and careful consideration should be given to which initial requests should be exempt from overload control. |
discard |
The request and any associated server transaction state should be discarded with no SIP response sent. Discarded requests may be observable through side effects such as statistics, TCP sequence numbers, etc. Extreme caution must be used when discarding requests. The specific algorithm must be very well thought through. If in doubt, never discard a request. |
Example Overload Control Plugin
A simple overload control plugin example is provided in the Appendix.
