Aller au contenu
Krizaka Java
Skip to Content
Krizaka Java

Limitation de débit

krizaka-ratelimit — une limite de requêtes par minute et par clé ; observer d'abord, puis appliquer avec 429 et Retry-After en Problem Details.

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

Ajouter le starter limite chaque requête d'un service Spring MVC, selon l'adresse d'où elle vient, à 600 par minute. Rien d'autre à écrire — promu depuis l'edge d'Sovkora (ADR-083).

krizaka:
  ratelimit:
    mode: observe              # compter et signaler sans refuser : voir qui serait limité, puis passer à enforce
    requests-per-minute: 120
    trusted-proxies: 10.0.0.0/8

Ce que voit un client

RequêteRéponse
dans la limitela réponse, avec RateLimit-Limit et RateLimit-Remaining
au-delà, enforce429 Problem Details, code rate-limit-exceeded, avec Retry-After (secondes avant qu'un appel passe)
au-delà, observela réponse, comme si dans la limite ; l'observation dit observed
/actuator/**jamais limité (krizaka.ratelimit.exclude-paths)

Un seau contient une minute d'appels : un client peut donc faire une rafale jusqu'à la limite, et le seau se remplit en continu. Une requête refusée n'atteint jamais le contrôleur. Chaque clé a son seau ; les clés sont conservées en empreinte SHA-256, jamais en clair. Une table pleine oublie les seaux inactifs et jamais un seau actif : un déluge de nouvelles clés ne remet pas à zéro la dette d'une autre.

Qui est une clé

Par défaut, l'adresse du client. Derrière un proxy, listez-le dans krizaka.ratelimit.trusted-proxies (adresses ou plages CIDR) : seulement alors l'adresse transmise est crue, lue depuis la droite de X-Forwarded-For en sautant les relais de confiance, si bien qu'un en-tête forgé ne peut pas choisir la clé. Tout ce qui n'est pas une adresse littérale est ignoré.

Pour limiter par clé d'API, utilisateur ou locataire — et donner à une clé son propre palier — déclarez un 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 : la limite par défaut
  }
}

Le palier d'une clé est lu à chaque appel : un changement s'applique au suivant. Retournez null pour laisser une requête sans limite.

Limites à connaître

L'état est en mémoire, par instance : avec N instances, une clé peut dépenser N fois sa limite, et un redémarrage oublie tous les seaux. Un stockage partagé (Redis) n'est pas encore fourni. L'intercepteur passe après la chaîne de sécurité, dans une application Spring MVC servlet uniquement. Le verrouillage de connexion du service users est un autre mécanisme et ne fait pas partie de ce module.

Prouvé

RateLimiterTest couvre la rafale, le remplissage, l'attente, les paliers, observe, off et le balayage des inactifs ; ClientIpKeyResolverTest les cas d'en-têtes forgés ; et l'application d'exemple montre le 429 en HTTP, par clé d'API et par palier. Chaque requête est observée : krizaka.ratelimit (étiquette outcome : allowed, limited, observed).

Configuration

PropriétéDescription
krizaka.ratelimit.client-ip-headerStringdéfaut Header a trusted proxy sets to the client's address, read before X-Forwarded-For; blank for none.
krizaka.ratelimit.exclude-pathsList<String>défaut /actuator/**Ant patterns of the paths that never are (health checks, probes).
krizaka.ratelimit.include-pathsList<String>défaut /**Ant patterns of the paths that are limited.
krizaka.ratelimit.max-keysIntegerdéfaut 10000How many keys are tracked per instance before idle ones are forgotten; a busy key is never forgotten.
krizaka.ratelimit.modeRateLimitModedéfaut 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-minuteIntegerdéfaut 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>pas de défautAddresses 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.

Sur cette page