ThrottlingFilter

Limits the rate that requests pass through a filter. The maximum number of requests that a client is allowed to make in a defined time is called the throttling rate.

When the throttling rate is reached, IG issues an HTTP status code 429 Too Many Requests and a Retry-After header, whose value is rounded up to the number of seconds to wait before trying the request again.

GET http://openig.example.com:8080/home/throttle-scriptable HTTP/1.1
. . .
HTTP/1.1 429 Too Many Requests
Retry-After: 10

Usage

{
    "name": string,
    "type": "ThrottlingFilter",
    "config": {
        "requestGroupingPolicy": runtime expression<string>,
        "throttlingRatePolicy": reference or inline declaration,  //Use either "throttlingRatePolicy"
        "rate": {                                                 //or "rate", but not both.
            "numberOfRequests": integer,
            "duration": duration string
        },
        "cleaningInterval": duration string,
        "executor": executor
    }
}

Properties

"requestGroupingPolicy": runtime expression<string>, optional

An expression to identify the partition to use for the request. In many cases the partition identifies an individual client that sends requests, but it can also identify a group that sends requests. The expression can evaluate to the client IP address or user ID, or an OpenID Connect subject/issuer.

The value for this expression must not be null.

Default: Empty string; all requests share the same partition

See also Expressions.

"throttlingRatePolicy": reference or inline declaration, required if "rate" is not used

A reference to or inline declaration of a policy to apply for throttling rate. The following policies can be used:

This value for this parameter must not be null.

"rate": rate object, required if "throttlingRatePolicy" is not used

The throttling rate to apply to requests. The rate is calculated as the number of requests divided by the duration:

"numberOfRequests": integer, required

The number of requests allowed through the filter in the time specified by "duration".

"duration": duration string, required

A time interval during which the number of requests passing through the filter is counted.

"cleaningInterval": duration, optional

The time to wait before cleaning outdated partitions. The value must be more than zero but not more than one day.

"executor": executor, optional

An executor service to schedule the execution of tasks, such as the clean up of partitions that are no longer used.

Default: ScheduledExecutorService

Examples

The following route defines a throttling rate of 6 requests/10 seconds to requests. For information about how to set up and test this example, see Configure Simple Throttling.

{
  "name": "00-throttle-simple",
  "baseURI": "http://app.example.com:8081",
  "condition": "${matches(request.uri.path, '^/home/throttle-simple')}",
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        {
          "type": "ThrottlingFilter",
          "name": "ThrottlingFilter-1",
          "config": {
            "requestGroupingPolicy": "",
            "rate": {
              "numberOfRequests": 6,
              "duration": "10 s"
            }
          }
        }
      ],
      "handler": "ReverseProxyHandler"
    }
  }
}