Throttle Mediator¶

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

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

Syntax¶

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

Configuration¶

The configuration of the Throttle mediator is divided into the following sections.

General¶

Parameter Name	Description
Group ID	An ID for the throttle group. This is a required 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 multiple 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.

Policy Type

This section is used to specify how the throttle policy is configured. The following options are available.

In-Line: If this is selected, the Throttle policy can be defined within the Throttle mediator configuration.
Referring reference: If this is selected, you can refer to a predefined Throttle policy saved in the Registry. You can enter the key to access the policy in the Policy Key parameter.

Policy Entries

This section is used to add the throttle policy if the In-line option is selected for the policy type. Click on the Add Parameter to add throttle policy. The throttle policy configurations are described below.

The parameters available in the throttle policy entry form to configure the throttle policy are as follows.

Parameter Name	Description
Maximum Request Count	The maximum number of messages 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.
Throttle Type	This parameter is used to specify whether the value(s) entered in the Range parameter refers to IP addresses or domains.
Throttle 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, for example, `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.
Access Type	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.
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	The time interval in milliseconds 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	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 (in milliseconds) entered to 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`.

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.

On Accept Branch Sequence Type

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

In-line Sequence: 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 flow to define the sequence in-line once the throttle mediator is added.
Referring Sequence: If this is selected, you can refer to a predefined mediation sequence.

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.

On Reject Branch Sequence Type

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

In-line Sequence: 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 flow to define the sequence in-line once the throttle mediator is added.
Referring Sequence: If this is selected, you can refer to a predefined mediation sequence.

Examples¶

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 in a single unit of time, and this value applies to all the IP addresses and domains.

REST APIEndpoint

<api xmlns="http://ws.apache.org/ns/synapse" name="ThrottleAPI" context="/throttle">
    <resource methods="GET" uri-template="/getQuote">
        <inSequence>
            <throttle id="A">
                <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>
                    <call>
                        <endpoint key="SimpleStockQuoteServiceEndpoint"/>
                    </call>
                </onAccept>
                <onReject>
                    <log level="custom">
                        <property name="text" value="**Access Denied**"/>
                    </log>
                    <makefault response="true" description="" version="soap12">
                        <code value="soap12Env:Receiver" xmlns:soap12Env="http://www.w3.org/2003/05/soap-envelope"/>
                        <reason value="**Access Denied**"/>
                    </makefault>
                    <drop/>
                </onReject>
            </throttle>
        </inSequence>
    </resource>
</api>

<endpoint xmlns="http://ws.apache.org/ns/synapse" name="SimpleStockQuoteServiceEndpoint">
    <address uri="http://localhost:9000/soap/services/SimpleStockQuoteService"/>
</endpoint>

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.

REST APIEndpoint

<?xml version="1.0" encoding="UTF-8"?>
<api context="/throttle" name="ThrottleAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="GET" uri-template="/getQuote">
        <inSequence>
            <throttle description="" 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 category="INFO" level="custom">
                        <property name="text" value="**Access Accept**"/>
                    </log>
                    <call>
                        <endpoint key="SimpleStockQuoteServiceEP"/>
                    </call>
                </onAccept>
                <onReject>
                    <log category="INFO" level="custom">
                        <property name="text" value="**Access Denied**"/>
                    </log>
                    <makefault response="true" description="" version="soap12">
                        <code value="soap12Env:Receiver" xmlns:soap12Env="http://www.w3.org/2003/05/soap-envelope"/>
                        <reason value="**Access Denied**"/>
                    </makefault>
                    <drop/>
                </onReject>
            </throttle>
        </inSequence>
        <faultSequence>
        </faultSequence>
    </resource>
</api>

<?xml version="1.0" encoding="UTF-8"?>
<endpoint name="SimpleStockQuoteServiceEP" xmlns="http://ws.apache.org/ns/synapse">
    <address uri="http://localhost:9000/services/SimpleStockQuoteService"/>
</endpoint>