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, PingGateway 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 https://ig.example.com:8443/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": ThrottlingPolicy reference,  //Use either "throttlingRatePolicy"
        "rate": {                                            //or "rate", but not both.
            "numberOfRequests": configuration expression<number>,
            "duration": configuration expression<duration>
        },
        "cleaningInterval": configuration expression<duration>,
        "executor": ScheduledExecutorService reference
    }
}

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

Learn more in PingGateway expressions.

"throttlingRatePolicy": ThrottlingPolicy reference, required if rate isn’t 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": object, required if throttlingRatePolicy isn’t used

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

"numberOfRequests": configuration expression<integer>, required: The number of requests allowed through the filter in the time specified by "duration".

"duration": configuration expression<duration>, required: A time interval during which the number of requests passing through the filter is counted.

"cleaningInterval": configuration expression<duration>, optional: The time to wait before cleaning outdated partitions. The value must be more than zero but not more than one day.
"executor": ScheduledExecutorService reference, optional: An executor service to schedule the execution of tasks, such as the clean up of partitions that are no longer used.

Default: ScheduledExecutorService

Learn more in ScheduledExecutorService.

Examples

The following route defines a throttling rate of 6 requests/10 seconds to requests. You can find more information about how to set up and test this example in Configure simple throttling.

{
  "name": "00-throttle-simple",
  "baseURI": "http://app.example.com:8081",
  "condition": "${find(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"
    }
  }
}

Source: 00-throttle-simple.json

More information

org.forgerock.openig.filter.throttling.ThrottlingFilterHeaplet