how-it-works.md

How it works

Limitador will increment counters for all Limits that apply, if any of these counter is above its Limit's max_value the request will be considered to be rate limited. So think of it as if the most restrictive limit configuration will apply.

Limitador will evaluate whether a Limit applies against its namespace, its conditions and whether all variables are resolvable. The namespace for the descriptors is defined by the domain field from the service.ratelimit.v3.RateLimitRequest. For each matching Limit, its counter is increased and checked against the Limit max_value.

One example to illustrate:

Let's say we have one rate limit:

conditions: [ "descriptors[0].KEY_A == 'VALUE_A'" ]
max_value: 1
seconds: 60
variables: []
namespace: example.org

Limitador Server receives a request with one descriptor with two entries:

domain: example.org
descriptors:
  - entries:
    - KEY_A: VALUE_A
    - OTHER_KEY: OTHER_VALUE

The counter's condition all match. Then, the counter will be increased and the limit checked. If the limit is exceeded, the request will be rejected with 429 Too Many Requests, otherwise accepted.

Note that the counter is being activated even though it does not match all the entries of the descriptor. The same rule applies for the variables field.

Conditions are CEL expressions evaluating to a bool value.

The variables field is a list of keys. The matching rule is defined just as the existence of the list of descriptor entries with the same key values. If variables is variables: ["descriptors[0].A", "descriptors[0].B", "descriptors[0].C]", the limit will match if the first descriptor has at least three entries with the same A, B, C keys.

Few examples to illustrate.

Having the following descriptors:

domain: example.org
descriptors:
  - entries:
    - KEY_A: VALUE_A
    - OTHER_KEY: OTHER_VALUE

the following counters would not be activated.

conditions: [ "descriptors[0].KEY_B == 'VALUE_B'" ]
max_value: 1
seconds: 60
variables: []
namespace: example.org

Reason: conditions key does not exist

conditions:
  - "descriptors[0].KEY_A == 'VALUE_A'"
  - "descriptors[0].OTHER_KEY == 'WRONG_VALUE'"
max_value: 1
seconds: 60
variables: []
namespace: example.org

Reason: not all the conditions match

conditions: []
max_value: 1
seconds: 60
variables: [ "descriptors[0].MY_VAR" ]
namespace: example.org

Reason: the variable name does not exist

conditions: [ "descriptors[0].KEY_B == 'VALUE_B'" ]
max_value: 1
seconds: 60
variables: [ "descriptors[0].MY_VAR" ]
namespace: example.org

Reason: Both variables and conditions must match. In this particular case, only conditions match