Header-based rate limiting plugin for Kong API Gateway

Description

The plugin enables rate limiting of API requests based on a customizable composition of request headers. The targets of rate limiting are identified using the provided list of headers, supporting more fine-grained settings than the built-in (community edition) plugin.

Configuration

Enabling the plugin

POST http://localhost:8001/plugins

{
    "name": "header-based-rate-limiting",
    "service_id": "...",
    "route_id": "...",
    "config": {
        "redis": {
            "host": "redis-host",
            "port": 6379,
            "db": 0
        },
        "default_rate_limit": 10,
        "log_only": false,
        "identification_headers": [
            "X-Country",
            "X-County",
            "X-City",
            "X-Street",
            "X-House"
        ]
    }
}

Adding rate limit rules

POST http://localhost:8001/header-based-rate-limits

{
    "service_id": "...",
    "route_id": "...",
    "header_composition": [
        "Hungary",
        "Pest",
        "Budapest",
        "Kossuth Lajos",
        "7"
    ],
    "rate_limit": 25
}

Although the service_id and route_id attributes are optional, if they are provided, the related service and route objects must be present in Kong's data store. There may be only one rule configured for a service_id, route_id, and header_composition combination. Rules are bound to the service and/or route object to which the plugin is attached. This enables separate rate limit settings for the same entity (designated by the identification headers) on different routes and/or services.

Header composition

Targets of rate limiting are identified by a configurable composition of request headers. You may think of this as the address of a mail sent through postal services. The addressee is designated by the components of its address, ordered by specificity (Country > County > City > Street > House).

Lookup procedure

The plugin attempts to identify the addressee of each request by determining the most specific rate limit configuration applicable. It first looks for a rule that matches the values of the identification headers. In case no exact match was found, it looks for a rule with the longest possible suffix match. If nothing was found, it discards the most specific element (the last one), and retries the lookup. This process is repeated until a match is found. If matching is unsuccessful and all elements were discarded, the plugin applies the default rate limit value.

As a rule of thumb, a longer rule is considered more specific than a shorter one. If two rules are equally long, then the one with less wildcards is considered to me more specific. (e.g.: *, *, X, Y is more specific than *, *, X and *, *, X, Y is more specific than *, *, *, Y)

Example

Identification headers:

Request headers:

Lookup order:

If no match was found (using the matchers above), the default pool size will be used.

Development environment

Checkout the Git repository

git clone [email protected]:emartech/kong-plugin-header-based-rate-limiting.git

Build / re-build development Docker image

make build

Start / stop / restart Kong

make up / make down / make restart

Set up necessary services, routes, and consumers for manual testing

make dev-env

PostgreSQL shell

make db

Open shell inside Kong container

make ssh

Run tests

make test

Execute just the unit test

make unit

Execute end-to-end tests

make e2e

Publish new release

• set LUAROCKS_API_KEY environment variable
  • retrieve your API key from LuaRocks
  • echo "export LUAROCKS_API_KEY=<my LuaRocks API key>" >> ~/.bash_profile
• set version number
  • rename *.rockspec file
  • change the version and source.tag in rockspec file
  • commit and push changes
    • git commit -m "Bump version"
    • git push
  • tag the current revision
    • git tag x.y.z
    • git push --tags
• publish to LuaRocks
  • make publish