Rate Limiting & Throttling

Protéger une API contre les abus, les DDoS et la surconsommation de ressources en limitant le nombre de requêtes par client sur une fenêtre de temps donnée.

Pourquoi limiter ?

Risque	Impact sans limite
Surcharge du backend	Temps de réponse qui explose, crash en cascade
Abus d’API (scraping, crawler)	Coûts infrastructure, bande passante gaspillée
DDoS	Indisponibilité du service
Iniquité entre clients	Un client monopolise les ressources
Surcharge de la base de données	Connexions MySQL/PostgreSQL épuisées

Le rate limiting n’est pas de la sécurité pure — c’est de la résilience opérationnelle. Même une API bien conçue et bien authentifiée peut tuer le service si un seul client envoie 10 000 requêtes par seconde.

Stratégies d’algorithme

Fixed Window

Coupe le temps en fenêtres fixes (ex. 1 minute). Compteur reset à chaque changement de fenêtre.


fenêtre 0: |● ● ● ● ● ● ● ● ● ● | → 10 req, OK
fenêtre 1: |● ● ● ● ● ● ● ● ● ● | → 10 req, OK

Avantage : simple à implémenter (un compteur + timestamp de début de fenêtre).
Inconvénient : pic aux limites de fenêtre. Un client peut envoyer 10 requêtes en 0,5 s juste avant la coupure, puis 10 autres juste après.

Sliding Window Log

Conserve l’historique de chaque requête (timestamp). Compte les requêtes dans la fenêtre glissante.

Avantage : lissage parfait entre les fenêtres.
Inconvénient : coût mémoire (il faut stocker chaque timestamp).

Sliding Window Counter (approximatif)

Combine deux fenêtres fixes (ancienne + nouvelle) pondérées par la proportion du temps écoulé dans la fenêtre courante. Environnement Redis typique pour le gateway.

Token Bucket

Un « seau » se remplit à taux constant (replenishRate). Chaque requête consomme un jeton. Si le seau est vide, la requête est rejetée.


bucket: 20 jetons max, 1 jeton/sec → 20 req immédiates puis 1 req/sec

Avantage : lisse les bursts (le seau se remplit lentement).
Inconvénient : nécessite un système distribué pour fonctionner à plusieurs instances.

Leaky Bucket

File d’attente avec débit de sortie constant. Les requêtes en excès sont rejetées.

Avantage : débit de sortie toujours constant (utile pour protéger des backends fragiles).
Inconvénient : les requêtes en excès sont perdues (pas de mise en file d’attente).

Implémentation Spring Boot — Resilience4j

Dépendance


<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-ratelimiter</artifactId>
</dependency>

Annotation `@RateLimiter` sur un service


@RateLimiter(name = "apiRateLimiter", fallbackMethod = "fallback")
public Mono<ResponseEntity<ProduitDTO>> obtenirProduit(UUID id) {
    ProduitDTO produit = service.obtenir(id);
    return Mono.just(ResponseEntity.ok(produit));
}
 
// Méthode appelée quand le rate limit est atteint
public Mono<ResponseEntity<ProduitDTO>> fallback(
        UUID id, RateLimiterNotPermittedException ex) {
    return Mono.just(ResponseEntity
        .status(HttpStatus.TOO_MANY_REQUESTS)
        .body(null));
}

Configuration YAML


resilience4j:
  ratelimiter:
    instances:
      apiRateLimiter:
        limitForPeriod: 100          # requêtes max par fenêtre
        limitRefreshPeriod: 60s      # durée de la fenêtre
        timeoutDuration: 0s          # attente avant rejet (0 = rejet immédiat)
        registerHealthIndicator: true

En-têtes ajoutés automatiquement (Spring Boot 3.2+)

Depuis Spring Boot 3.2, l’annotation @RateLimiter ajoute automatiquement les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset à la réponse.

Note : les en-têtes sont ajoutés automatiquement depuis Spring Boot 3.2 avec Resilience4j 2.x. Pour les versions antérieures, il faut configurer un filtre personnalisé pour les ajouter.

Implémentation Spring Cloud Gateway

Le gateway est le lieu idéal pour le rate limiting : il voit toutes les requêtes, avant qu’elles n’atteignent les services.

Architecture Redis-backed


Client → Gateway → [RequestRateLimiter] → Service
                    ↓
              Redis (compteur partagé)

Redis permet un compteur partagé entre plusieurs instances du gateway — indispensable en production avec load balancing.

Configuration YAML


spring:
  cloud:
    gateway:
      routes:
        - id: service-public
          uri: lb://service-public
          predicates:
            - Path=/api/public/**
          filters:
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@ipKeyResolver}"
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                redis-rate-limiter.requestedTokens: 1

Clés de résolution


// KeyResolver par IP (prêt à l'emploi)
@Bean
public KeyResolver ipKeyResolver() {
    return exchange -> Mono.just(
        exchange.getRequest().getRemoteAddress()
            .getAddress().getHostAddress()
    );
}
 
// KeyResolver par identifiant utilisateur (après authentification JWT)
@Bean
public KeyResolver userKeyResolver() {
    return exchange -> Mono.just(
        exchange.getAttribute("authenticatedPrincipal")
            .orElse("anonymous")
    );
}
 
// KeyResolver combiné : utilisateur si authentifié, sinon IP
@Bean
public KeyResolver compositeKeyResolver() {
    return exchange -> {
        String principal = exchange.getAttribute("authenticatedPrincipal");
        if (principal != null) {
            return Mono.just(principal);
        }
        return Mono.just(
            exchange.getRequest().getRemoteAddress()
                .getAddress().getHostAddress()
        );
    };
}

Piège : RequestRateLimiter utilise Sliding Window Counter via Redis. replenishRate définit le débit continu, burstCapacity le nombre maximal de requêtes en rafale. requestedTokens: 1 = une requête = un jeton.

Filtrage conditionnel

Appliquer le rate limiting uniquement à certains chemins ou méthodes :


spring:
  cloud:
    gateway:
      routes:
        - id: service-public
          uri: lb://service-public
          predicates:
            - Path=/api/public/**
            - Method=GET,POST
          filters:
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@userKeyResolver}"
                redis-rate-limiter.replenishRate: 5
                redis-rate-limiter.burstCapacity: 10
                redis-rate-limiter.requestedTokens: 1

Implémentation Micronaut

Dépendance


<dependency>
    <groupId>io.micronaut.micrometer</groupId>
    <artifactId>micronaut-micrometer-core</artifactId>
</dependency>
<dependency>
    <groupId>io.micronaut.micrometer</groupId>
    <artifactId>micronaut-micrometer-registry-prometheus</artifactId>
</dependency>

Annotation `@RateLimiter` (Micronaut 4+)


@Singleton
public class ProduitService {
 
    @RateLimiter(name = "produitRateLimiter")
    public ProduitDTO obtenirProduit(UUID id) {
        return repo.obtenir(id)
            .orElseThrow(() -> new NotFoundException("Produit introuvable"));
    }
 
    @ExceptionHandler(RateLimiterExhaustedException.class)
    @Status(HttpStatus.TOO_MANY_REQUESTS)
    public HttpResponse<String> onRateLimit() {
        return HttpResponse.status(HttpStatus.TOO_MANY_REQUESTS)
            .body("Trop de requêtes — réessayez plus tard");
    }
}

Configuration YAML


micronaut:
  time:
    rate-limiter:
      enabled: true
      default:
        maximum-permits: 100
        permit-refresh-period: 60s
        permit-refresh-period-time-unit: SECONDS

En-têtes de réponse standard

RFC 7231 et pratiques courantes. Les clients (react-app, mobile) les lisent pour afficher un spinner ou un message.

En-tête	Signification	Exemple
`X-RateLimit-Limit`	Quota maximum sur la fenêtre	`X-RateLimit-Limit: 100`
`X-RateLimit-Remaining`	Requêtes restantes dans la fenêtre	`X-RateLimit-Remaining: 42`
`X-RateLimit-Reset`	Epoch timestamp (Unix) du reset	`X-RateLimit-Reset: 1720000000`
`Retry-After`	Délai en secondes avant de renvoyer une requête (uniquement sur 429)	`Retry-After: 30`

Exemple de réponse 429


HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720000030
Retry-After: 30
Content-Type: application/json

{"error": "Too many requests", "retryAfterSeconds": 30}

Règle : toujours renvoyer un code 429 Too Many Requests (et jamais un 403 ou 200 caché) quand le quota est dépassé. Les clients doivent être capables de le détecter.

Pièges

1. Spoofing d’IP avec `X-Forwarded-For`

Si le gateway se trouve derrière un proxy (NGINX, AWS ALB), getRemoteAddress() retourne l’adresse du proxy, pas du client.


// ❌ MAUVAIS — facile à spoof
String ip = exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();
 
// ✅ BON — lire le header de confiance (uniquement si le proxy est de confiance)
String forwarded = exchange.getRequest().getHeaders()
    .getFirst("X-Forwarded-For");
String ip = (forwarded != null) ? forwarded.split(",")[0].trim() :
    exchange.getRequest().getRemoteAddress().getAddress().getHostAddress();

Piège : un attaquant peut ajouter l’en-tête X-Forwarded-For dans sa requête pour tromper le rate limiter. Seules les adresses IP de confiance (le proxy) doivent être autorisées à l’envoyer.

2. Rate limiting bypassé par un header tronqué

Certains frameworks ignorent les en-têtes dont la longueur est trop grande. Pour le X-RateLimit-Remaining, un client qui affiche un compteur ne le voit jamais diminuer — mais le serveur continue à compter. Le client doit refaire la requête quand il atteint zéro.

3. Test du rate limit inadapté

Tester avec un seul thread cache la consommation réelle. Utiliser un outil de load test (k6, JMeter, Artillery) pour simuler plusieurs clients simultanément.


# Exemple k6 : 100 requêtes/s pendant 30 secondes
cat <<'EOF' > rate-limit-test.js
import http from 'k6/http';
 
export const options = {
    vus: 100,
    duration: '30s',
};
 
export default function () {
    http.get('http://localhost:8080/api/public/produits');
}
EOF
k6 run rate-limit-test.js

4. Failover Redis → pas de rate limiting

Si Redis devient injoignable, RequestRateLimiter ne bloque pas — il laisse passer toutes les requêtes. Toujours avoir un mécanisme de repli : circuit breaker vers un fallback in-memory ou bloquer les requêtes.


spring:
  cloud:
    gateway:
      routes:
        - id: service-public
          uri: lb://service-public
          predicates:
            - Path=/api/public/**
          filters:
            - name: RequestRateLimiter
              args:
                key-resolver: "#{@userKeyResolver}"
                redis-rate-limiter.replenishRate: 10
                redis-rate-limiter.burstCapacity: 20
                redis-rate-limiter.requestedTokens: 1
            # Circuit breaker en fallback si Redis est mort
            - name: CircuitBreaker
              args:
                name: rateLimiterCircuit
                fallbackUri: forward:/fallback/rate-limit

5. Fenêtre de temps mal calibrée

Fenêtre trop courte (1 s) : le client légitime est pénalisé pour des tests rapides.
Fenêtre trop longue (1 heure) : un attaquant a une fenêtre de tir énorme.
Recommandation : 60 s pour la plupart des APIs, ajuster selon le type d’endpoint (lecture vs écriture).

Checklist de déploiement

Stratégie d’algorithme choisie (token bucket recommandé pour la plupart des cas)
Système distribué de comptage (Redis, Redis Cluster, ou serveur de consensus)
Clé de résolution adaptée (utilisateur authentifié si possible, IP sinon)
En-têtes X-RateLimit-* ajoutés à chaque réponse
Code 429 renvoyé correctement avec Retry-After
Rejet non silencieux : le client reçoit bien un message d’erreur
Test de charge réalisé (k6, JMeter, Artillery)
Fallback défini si le système de comptage devient injoignable
Monitoring des indicateurs (quota utilisé, taux de 429, pics)

Rate Limiting & Throttling

Pourquoi limiter ?

Stratégies d’algorithme

Fixed Window

Sliding Window Log

Sliding Window Counter (approximatif)

Token Bucket

Leaky Bucket

Implémentation Spring Boot — Resilience4j

Dépendance

Annotation @RateLimiter sur un service

Configuration YAML

En-têtes ajoutés automatiquement (Spring Boot 3.2+)

Implémentation Spring Cloud Gateway

Architecture Redis-backed

Configuration YAML

Clés de résolution

Filtrage conditionnel

Implémentation Micronaut

Dépendance

Annotation @RateLimiter (Micronaut 4+)

Configuration YAML

En-têtes de réponse standard

Exemple de réponse 429

Pièges

1. Spoofing d’IP avec X-Forwarded-For

2. Rate limiting bypassé par un header tronqué

3. Test du rate limit inadapté

4. Failover Redis → pas de rate limiting

5. Fenêtre de temps mal calibrée

Checklist de déploiement

Annotation `@RateLimiter` sur un service

Annotation `@RateLimiter` (Micronaut 4+)

1. Spoofing d’IP avec `X-Forwarded-For`