Rate limiting
Count requests per key (an IP address, a user, an API key) in a time window and tell when the limit is reached. The state is in memory and shared by all sessions. Typical uses: protect a web API or a login form against abuse.
rate_limit checkrate_limit checkrate_limit statusrate_limit resetrate_limit statsrate_limit reset_all

rate_limit check <key> <limit> <window_seconds>


Description

    Count one request for a key with the sliding window algorithm, if it is allowed. Returns {allowed, remaining, retry_after_ms, reset_ms, limit, algorithm}

Parameters

    key:   What is limited: an IP address, a user, a user plus an API, ex: login:192.0.2.7. 1 to 256 characters - String - required
    limit:   The number of requests allowed per window, from 1 to 1000000000 - Integer - required
    window_seconds:   The window in seconds, from 1 to 86400 - Integer - required
admin
rate_limit check "doc.login:192.0.2.7" "3" "60"; rate_limit check "doc.login:192.0.2.7" "3" "60"; rate_limit check "doc.login:192.0.2.7" "3" "60"; rate_limit check "doc.login:192.0.2.7" "3" "60"
mentdb
{"allowed": false, "remaining": 0, "retry_after_ms": 79999, "reset_ms": 119999, "limit": 3, "algorithm": "sliding_window"}

rate_limit check <key> <limit> <window_seconds> <json_params>


Description

    Count a request with parameters: algorithm (sliding_window, fixed_window or token_bucket), cost (1 by default: the weight of this request, at most the limit or the burst), burst (token_bucket only: the size of the bucket, the limit by default)

Parameters

    key:   What is limited: an IP address, a user, a user plus an API, ex: login:192.0.2.7. 1 to 256 characters - String - required
    limit:   The number of requests allowed per window, from 1 to 1000000000 - Integer - required
    window_seconds:   The window in seconds, from 1 to 86400 - Integer - required
    json_params:   The parameters - String - required
admin
rate_limit check "doc.api:key9" "10" "3600" "{\"algorithm\": \"token_bucket\", \"burst\": 2}"; rate_limit check "doc.api:key9" "10" "3600" "{\"algorithm\": \"token_bucket\", \"burst\": 2}"; rate_limit check "doc.api:key9" "10" "3600" "{\"algorithm\": \"token_bucket\", \"burst\": 2}"
mentdb
{"allowed": false, "remaining": 0, "retry_after_ms": 360000, "reset_ms": 720000, "limit": 10, "algorithm": "token_bucket"}
an export that costs 5 of 100 per hour, fixed window
admin
rate_limit check "doc.export:user3" "100" "3600" "{\"algorithm\": \"fixed_window\", \"cost\": 5}"
mentdb
{"allowed": true, "remaining": 95, "retry_after_ms": 0, "reset_ms": 3599999, "limit": 100, "algorithm": "fixed_window"}
Used in use cases (1 recipe)

    Security engineer › Slow down password guessing on a login API with a limit per address and per account
Often used with

    rate_limit reset  ·  rate_limit status

rate_limit status <key>


Description

    The state of a key without counting a request: {key, found, algorithm, limit, window_seconds, burst (token_bucket), remaining, reset_ms}, or {key, found: false}

Parameters

    key:   What is limited: an IP address, a user, a user plus an API, ex: login:192.0.2.7. 1 to 256 characters - String - required
admin
rate_limit check "doc.status:u1" "5" "60" "{\"algorithm\": \"fixed_window\"}"; rate_limit status "doc.status:u1"
mentdb
{"key": "doc.status:u1", "found": true, "algorithm": "fixed_window", "limit": 5, "window_seconds": 60, "remaining": 4, "reset_ms": 59999}
an unknown key
admin
rate_limit status "doc.status:nobody"
mentdb
{"key": "doc.status:nobody", "found": false}
Used in use cases (1 recipe)

    Security engineer › Slow down password guessing on a login API with a limit per address and per account
Often used with

    rate_limit check  ·  rate_limit reset

rate_limit reset <key>


Description

    Forget a key: its next request starts from the full limit. Returns 1 if the key was known, else 0

Parameters

    key:   What is limited: an IP address, a user, a user plus an API, ex: login:192.0.2.7. 1 to 256 characters - String - required
admin
rate_limit check "doc.reset:u2" "3" "60"; rate_limit reset "doc.reset:u2"
mentdb
1
Used in use cases (1 recipe)

    Security engineer › Slow down password guessing on a login API with a limit per address and per account
Often used with

    rate_limit check  ·  rate_limit status

rate_limit stats


Description

    The statistics of the rate limiter: {keys, max_keys, allowed, denied, evictions}

admin
rate_limit stats
mentdb
{"keys": 4, "max_keys": 100000, "allowed": 8, "denied": 2, "evictions": 0}

rate_limit reset_all


Description

    Forget all the keys and the counters. Needs the group sys. Returns the number of keys removed

admin
rate_limit reset_all
mentdb
4