Skip to the content
Krizaka Java
Skip to Content
Krizaka Java

Rate limiting

krizaka-ratelimit — a requests-per-minute limit per key; observe first, then enforce with 429 and Retry-After as Problem Details.

<dependency>
  <groupId>com.krizaka</groupId>
  <artifactId>krizaka-spring-boot-starter-ratelimit</artifactId>
</dependency>

Adding the starter limits every request of a Spring MVC service, by the address it comes from, 600 a minute. Nothing else to write — promoted from the Sovkora edge (ADR-083).

krizaka:
  ratelimit:
    mode: observe              # count and flag, never refuse: see who would be limited, then switch to enforce
    requests-per-minute: 120
    trusted-proxies: 10.0.0.0/8

What a client sees

RequestAnswer
within the limitthe response, with RateLimit-Limit and RateLimit-Remaining
over the limit, enforce429 Problem Details, code rate-limit-exceeded, with Retry-After (seconds until a call can succeed)
over the limit, observethe response, as if within; the observation says observed
/actuator/**never limited (krizaka.ratelimit.exclude-paths)

A bucket holds one minute's worth of calls, so a client may burst up to the limit, and it refills continuously. A refused request never reaches the controller. Each key has its own bucket; keys are kept as SHA-256 digests, never in clear. A full table forgets idle buckets and never a busy one, so a flood of new keys cannot reset another key's debt.

Who is a key

By default, the client's address. Behind a proxy, list it in krizaka.ratelimit.trusted-proxies (addresses or CIDR ranges): only then is the forwarded address believed, read from the right of X-Forwarded-For and skipping trusted hops, so a forged header cannot pick the key. Anything that is not a literal address is ignored.

To limit by API key, user or tenant — and give a key its own tier — declare a RateLimitKeyResolver:

@Component
class ApiKeyResolver implements RateLimitKeyResolver {
  public RateLimitKey resolve(HttpServletRequest request) {
    String key = request.getHeader("X-Api-Key");
    return key == null ? RateLimitKey.of("ip:" + request.getRemoteAddr())
        : new RateLimitKey("key:" + key, key.startsWith("pro_") ? 10 : null);   // null: the default limit
  }
}

A key's tier is read at every call, so a change applies on the next one. Return null to leave a request unlimited.

Limits to know

State is in memory, per instance: with N instances a key may spend N times its limit, and a restart forgets every bucket. A shared store (Redis) is not provided yet. The interceptor runs after the security chain and only in a servlet Spring MVC application. The users service's login lockout is a different mechanism and is not part of this module.

Proven

RateLimiterTest covers the burst, the refill, the wait, tiers, observe, off and the idle sweep; ClientIpKeyResolverTest the forged-header cases; and the example app shows the 429 over HTTP, per API key and per tier. Every request is observed as krizaka.ratelimit (tag outcome: allowed, limited, observed).

Configuration

PropertyDescription
krizaka.ratelimit.client-ip-headerStringdefault Header a trusted proxy sets to the client's address, read before X-Forwarded-For; blank for none.
krizaka.ratelimit.exclude-pathsList<String>default /actuator/**Ant patterns of the paths that never are (health checks, probes).
krizaka.ratelimit.include-pathsList<String>default /**Ant patterns of the paths that are limited.
krizaka.ratelimit.max-keysIntegerdefault 10000How many keys are tracked per instance before idle ones are forgotten; a busy key is never forgotten.
krizaka.ratelimit.modeRateLimitModedefault enforceHow the limit is applied: 'enforce' answers 429 once a key's bucket is empty, 'observe' counts and flags but never refuses (roll the limit out with it), 'off' keeps nothing.
krizaka.ratelimit.requests-per-minuteIntegerdefault 600Requests per minute a key may make, for a key that brings no limit of its own. A bucket holds one minute's worth, so a client may burst up to it.
krizaka.ratelimit.trusted-proxiesList<String>no defaultAddresses or CIDR ranges of the proxies in front of the service. Only behind one is the forwarded address of a request trusted as its client; empty, the direct peer is always the client.

On this page