Throttle Mediator

The Throttle Mediator can be used to restrict access to services. This is useful when services used at the enterprise level and it is required to avoid heavy loads that can cause performance issues in the system. It can also be used when you want to avoid certain user groups (i.e. IP addresses and domains) accessing your system. The Throttle mediator defines a throttle group which includes the following.

A throttle policy which defines the extent to which, individuals and groups of IP addresses/domains should be allowed to access the service.
A mediation sequence to handle requests that were accepted based on the throttle policy.
A mediation sequence to handle requests that were rejected based on the throttle policy.

The Throttle mediator is a content unaware mediator.

Syntax

<throttle [onReject="string"] [onAccept="string"] id="string">
    (<policy key="string"/> | <policy>..</policy>)
    <onReject>..</onReject>?
    <onAccept>..</onAccept>?
</throttle>

Configuration

The configuration of the Throttle mediator are divided into following sections. Before you edit these sections, enter an ID for the Throttle group in the Throttle Group ID parameter.

Throttle Policy

This section is used to specify the throttle policy that should apply to the requests passing through the Throttle mediator. A throttle policy has a number of entries defining the extent to which, an individual or a group of IP addresses/domains should be allowed to access the service.

The parameters available to be configured in this section are as follows.

Parameter Name

Description

Throttle Policy

This section is used to specify the policy for throttling. The following options are available.

In-Lined Policy: If this is selected, the Throttle policy can be defined within the Throttle mediator configuration. Click Throttle Policy Editor to open the Mediator Throttling Configuration dialog box where the details relating to the Throttle policy can be entered. The parameters in this dialog box are described in the table below.
Referring Policy: If this is selected, you can refer to a pre-defined Throttle policy which is saved in the Registry. You can enter the key to access the policy in the Referring Policy parameter. Click on either Configuration Registry or Governance Registry to select the relevant policy from the Resource Tree.

The parameters available in the Mediator Throttling Configuration dialog box to configure the Throttling policy are as follows.

Parameter Name	Description
Maximum Concurrent Accesses	The maximum number of messages that are served at a given time. The number of messages between the inflow throttle handler and the outflow throttle handler cannot exceed the value entered for this parameter at any given time. This parameter value is applied to the entire system. It is not restricted to one or more specific IP addresses/domains. When this parameter is used, the same Throttle mediator ID should be included in the response flow so that the completed responses are deducted from the available limit.
Range	This parameter is used to specify the IP addresses/domains to which the entry in the current row should be applied If you want to apply the entry to a range of IP addresses, enter the range in this parameter, e.g., `8.100.1.30 – 8.100.1.45`. Alternatively, you can enter a single IP address to apply the entry to only one IP address. If you want to apply the entry to a domain, enter the required domain ID in this parameter. If you want to apply the entry to all the IP addresses/domains that are not configured in the other configurations, enter `other` in this parameter.
Type	This parameter is used to specify whether the value(s) entered in the Range parameter refers to IP addresses or domains.
Max Request Count	This parameter specifies the maximum number of requests that should be handled within the time interval specified in the Unit Time parameter. This parameter is applicable only when the value selected for the Access parameter is `Control`.
Unit Time (ms)	The time interval for which the maximum number of requests specified for the Throttle ID in the Max Request Count parameter apply. This parameter is applicable only when the value selected for the Access parameter is `Control`.
Prohibit Time Period (ms)	If the number of requests entered in the Max Request Count parameter is achieved before the time interval entered in the Unit Time (ms) parameter has elapsed, no more requests are taken by the inflow throttle handler for the time period entered in this parameter. Entering a value in this parameter alters the unit time. For example: Max Request Count = 50 Unit Time = 50000 ms Prohibit Time Period = 5000 ms If 50 requests are received within 50000 milliseconds, no requests will be taken for the next 5000 milliseconds. Thus, the time slot considered as the unit time is changed to 40000 milliseconds. If no value is entered in the Prohibit Time Period (ms) parameter, no requests will be taken until 15000 more milliseconds (i.e. the remainder of the unit time) have elapsed. This parameter is applicable only when the value selected for the Access parameter is `Control`.
Access	This parameter is used to specify the extent to which the IP addresses/domains specified in the Range parameter are allowed access to the service to which the throttle policy is applied. Possible values are as follows. Allow: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied without any restrictions. Deny: If this is selected, specified IP addresses/domains are not allowed to access the services to which the throttle ID is applied. Control: If this is selected, the specified IP addresses/domains are allowed to access the services to which the throttle ID is applied. However, the number of times they can access the services is controlled by the Max Request Count, Unit Time (ms) and the Prohibit Time Period (ms) parameters.
Action	This parameter can be used to delete the entry.

On Acceptance

This section is used to specify the mediation sequence that should be applied when a request is accepted based on the throttle policy defined for the Throttle mediator. The parameters available to be configured in this section are as follows.

Parameter Name

Description

Specify As

This parameter is used to specify how the On Acceptance sequence is defined. The following options are available.

In-Lined Policy: If this is selected, the mediation sequence to be applied to accepted requests can be defined within the Throttle mediator configuration. Click on the OnAccept node in the mediation tree to define the sequence in-line.
Referring Policy: If this is selected, you can refer to a pre-defined mediation sequence in the registry. Click either Configuration Registry or Governance Registry as relevant to select the required sequence from the Resource Tree.

On Rejection

This section is used to specify the mediation sequence that should be applied when a request is rejected based on the throttle policy defined for the Throttle mediator. The parameters available to be configured in this section are as follows.

Parameter Name

Description

Specify As

This parameter is used to specify how the On Acceptance sequence is defined. The following options are available.

In-Lined Policy: If this is selected, the mediation sequence to be applied to rejected requests can be defined within the Throttle mediator configuration. Click on the OnReject node in the mediation tree to define the sequence in-line.
Referring Policy: If this is selected, you can refer to a pre-defined mediation sequence in the registry. Click either Configuration Registry or Governance Registry as relevant to select the required sequence from the Resource Tree.

Examples

In this example, the Throttle Mediator inside the In Mediator. Therefore, all request messages directed to the main sequence will be subjected to throttling. The Throttle Mediator has policy, onAccept and onReject tags at top level. The policy tag specifies the throttling policy for throttling messages.

The onAccept sequence includes a Log mediator with a custom log to log the accepted requests.Then the Send mediator sends these requests to http://localhost:9000/services/SimpleStockQuoteService.

The OnReject sequence too includes a Log mediator with a custom log to log the rejected requests. Then a Fault mediator is used to convert the message into a fault message. The fault message is then returned to the client as a response using the Respond mediator, and then dropped using the Drop mediator.

Example for a concurrency-based policy

This sample policy only contains a component called MaximumConcurrentAccess. This indicates the maximum number of concurrent requests that can pass through Synapse on a single unit of time, and this value applies to all the IP addresses and domains.

<in>
    <throttle id="A">
        <policy>
            <!-- define throttle policy -->
            <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
                        xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">
                <throttle:ThrottleAssertion>
                    <throttle:MaximumConcurrentAccess>10</throttle:MaximumConcurrentAccess>
                </throttle:ThrottleAssertion>
            </wsp:Policy>
        </policy>
        <onAccept>
            <log level="custom">
                <property name="text" value="**Access Accept**"/>
            </log>
            <send>
                <endpoint>
                    <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                </endpoint>
            </send>
        </onAccept>
        <onReject>
            <log level="custom">
                <property name="text" value="**Access Denied**"/>
            </log>
            <makefault>
                <code value="tns:Receiver"
                      xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
                <reason value="**Access Denied**"/>
            </makefault>
            <respond/>
            <drop/>
        </onReject>
    </throttle>
</in>

Example for a rates-based policy

This sample policy only contains a rates-based policy. This indicates the maximum number of concurrent requests that can pass through Synapse on a single unit of time, and this value applies to all the IP addresses and domains.

<in>
    <throttle id="A">
        <policy>
            <!-- define throttle policy -->
            <wsp:Policy xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy"
                        xmlns:throttle="http://www.wso2.org/products/wso2commons/throttle">
                       <throttle:MaximumCount>4</throttle:MaximumCount>
                       <throttle:UnitTime>800000</throttle:UnitTime>
                       <throttle:ProhibitTimePeriod wsp:Optional="true">1000</throttle:ProhibitTimePeriod>
            </wsp:Policy>
        </policy>
        <onAccept>
            <log level="custom">
                <property name="text" value="**Access Accept**"/>
            </log>
            <send>
                <endpoint>
                    <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
                </endpoint>
            </send>
        </onAccept>
        <onReject>
            <log level="custom">
                <property name="text" value="**Access Denied**"/>
            </log>
            <makefault>
                <code value="tns:Receiver"
                      xmlns:tns="http://www.w3.org/2003/05/soap-envelope"/>
                <reason value="**Access Denied**"/>
            </makefault>
            <respond/>
            <drop/>
        </onReject>
    </throttle>
</in>