Rate Limit

This module provides support for request rate limits.

Example configuration

The following configuration will allow:

5000 requests per hour from the consumer foo.
1 request per second from the consumer bar.
200 requests per minute or 10 requests per second from any other consumer or client.

{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "name": "rate-limit",
            "order": 0,
            "consumers": {
                "foo": {
                    "hour": 5000
                },
                "bar": {
                    "second": 1
                }
            },
            "default": {
                "minute": 200,
                "second": 10
            }
        }
    ]
}

Configuration attributes

Attribute	Required	Type	Default	Description
`hour`	No	Int		Number of requests allowed per hour.
`minute`	No	Int		Number of requests allowed per minute.
`second`	No	Int		Number of requests allowed per second.
`limit-by`	No	String	`consumer id ip`	Whitespace separated string containing keys to use for rate limits. This is used to select which keys to use for limits, and also their priority (from left to right). The first match is used. The reserved keywords are: `consumer` is the username of the consumer, `id` is the session id as set by one of the authentication modules and `ip` is the client IP.

Limit-by explained

The limit-by configuration attribute is used to specify how requests are counted for the rate limits. Its value is a whitespace separated string containing keywords. There are some reserved keywords with special meaning:

Keyword	Description
`consumer`	The consumer name will be used if the request is authenticated using one of the authentication modules.
`id`	The session id will be used if the request has a session from one of the authentication modules.
`ip`	The client IP will be used. Keep in mind that the client IP might not be the IP of the end user, depending on the environment.

The default value of limit-by will count incoming requests like this:

If the request is authenticated using one of the auth modules, the rate limit will apply to the consumer.
If the request has a session id, the rate limit will apply to the session id.
The rate limit will apply to the source IP address of the policy request.

Values that do not match any reserved keywords will be matched with the request headers. An example:

{
    "name": "example",
    "host": "example.com",
    "path": "/*",
    "modules": [
        {
            "name": "rate-limit",
            "order": 0,
            "default": {
                "minute": 100,
            },
            "general": {
                "limit-by": "foo ip" 
            }
        }
    ]
}

The configuration above will count incoming requests like this:

If the request contains the request header foo, the rate limit will count based on the value of foo.
If the request does not contain the request header foo, the rate limit will count based on the client IP.

If the client request does not match any of the keywords specified in limit-by, the request will not be counted for any rate limits.

When applying rate limits on specific request headers, it is important to ensure that the end users cannot manipulate these headers.

Response status

Status	Description
`200`	Quota not reached.
`429`	Too many requests.

Response headers

If multiple rate limits apply, the various limits will be separated in the response headers by whitespace.

Header	Description
`X-RateLimit-Limit`	The number of requests allowed per period.
`X-RateLimit-Remaining`	The number of requests remaining in the limits.
`X-RateLimit-Reset`	The number of seconds remaining of the periods before the limits are reset.