| Attachment | Type URL (@type) | Per-route override | Build feature |
|---|---|---|---|
HTTP filter chain (http_filters) | type.googleapis.com/arion.extensions.filters.http.user_rate_limit.v3.UserRateLimiter | disabled only | None |
What it does
The user rate limiter is an Arion extension that rate-limits each caller separately. The caller is identified by the value of one request header (user_id_header_name) — a session id, an API key id, or a value written from a JWT claim by claim_to_headers. Each distinct value gets its own token bucket; specific users can have dedicated limits, everyone else falls back to a default entry, and idle buckets are cleaned up automatically.
Minimal configuration
From arion-runtime-user-rate-limit.yaml; the fragment is an entry in http_filters, before the router:
- name: user_rate_limit
typed_config:
"@type": type.googleapis.com/arion.extensions.filters.http.user_rate_limit.v3.UserRateLimiter
user_id_header_name: x-session-id
stat_prefix: user_rate_limiter
user_rate_limits:
- user_id: "premium-tenant"
simple_rate_limit:
max_tokens: 100
rate: 50
- simple_rate_limit: # default for every other caller
max_tokens: 10
rate: 5Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
user_id_header_name | string | Yes | — | Header whose value identifies the caller. A request without the header is not limited and passes through. |
stat_prefix | string | No | — | Prefix for this filter's statistics. |
status | {code} | No | 429 | HTTP status returned to rate-limited requests. |
user_rate_limits | list | Yes | — | Limit entries. Each names a user_id and one limit; an entry without user_id is the default for callers not listed. A caller with no entry and no default is not limited. |
Each entry carries exactly one of:
| Limit | Fields | Description |
|---|---|---|
simple_rate_limit | max_tokens, rate | Shorthand bucket: capacity max_tokens, refilled at rate tokens per second. Both must be greater than zero. |
local_rate_limit | stat_prefix, status, token_bucket | A full local rate limit config, giving explicit tokens_per_fill and fill_interval. |
Ordering and interactions
Place the filter after whatever produces the identifying header. With JWT authentication first in the chain, a claim_to_headers mapping (for example sub to x-user-id) turns this filter into a per-subject limiter for verified callers — and because the header must be present for a limit to apply, put an authorization filter in front if unidentified traffic should not pass freely. Buckets live in one process-wide map shared by all workers, and a caller idle for a while has its bucket reclaimed. Per route the filter supports only the generic FilterConfig override with disabled: true; its configuration cannot be replaced per route.