PD-172 — Rate limiting distribué Redis multi-dimensions (contractuel V2)¶

1. Objectif¶

La User Story PD-172 définit un contrat de limitation de débit distribué, cohérent multi-instances, pour protéger les endpoints critiques du backend ProbatioVault contre les abus automatisés, tout en préservant la disponibilité globale.

Objectifs contractuels :

• protéger l’authentification contre le bruteforce ;
• plafonner les endpoints coûteux ;
• garantir l’équité entre tenants ;
• rendre chaque blocage observable côté exploitation ;
• fournir des signaux client standard (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) ;
• appliquer une stratégie Redis-down différenciée par famille de routes, avec code HTTP normatif ;
• rester conforme RGPD (minimisation des données dans Redis, diagnostic opérationnel conservé en logs).

2. Périmètre / Hors périmètre¶

Inclus¶

• Évaluation rate-limit avant exécution logique métier.
• Dimensions V1 obligatoires : ip, user_id, tenant, route.
• Politique multi-fenêtres V1 : burst + sustained.
• Garde-fou global tenant : 500 req/min (sustained).
• Réponse 429 en cas de dépassement quota.
• Stratégie Redis indisponible :
• auth : fail-closed 503 + Retry-After
• read : fail-open contrôlé
• costly (upload/export/proof) : fail-closed 503 + Retry-After
• Routes santé /health/* et /ready/* : profil dédié très élevé (pas de whitelist).
• Évaluation atomique multi-dimensions/multi-fenêtres en une seule commande Redis Lua.
• Observabilité : logs structurés + métriques exploitables.
• Configuration statique au boot (V1).

Exclu¶

• Anti-DDoS réseau/CDN/WAF.
• CAPTCHA.
• Device fingerprinting.
• Quotas billing/pricing.
• Limitation BullMQ/jobs.
• Whitelist/bypass ops V1.
• API key en dimension V1 (prévu V2).
• Reload dynamique de configuration sans redéploiement (V2).

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données contractuel (source de vérité unique)¶

Règles de normalisation complémentaires :

• Si user_id est absent : valeur canonique anonymous.
• Si tenant est absent : valeur canonique public.
• Si ip ou route est absent/non fiable : ERR-172-03.

Note C-01 (résolue) :

• Exemple route valide : /api/v1/:id.
• Exemple route_key correspondant : L2FwaS92MS86aWQ.
• La clé Redis reste valide car route n’est jamais injectée brute dans un segment séparé par :.

Note RGPD C-03 (tranchée) :

• Clé Redis : uniquement identifier_hmac.
• Logs sécurité : client_ip_raw autorisé pour diagnostic anti-abus.
• Rétention client_ip_raw : 7 jours max, accès restreint SOC/SRE.
• Base légale : intérêt légitime sécurité (RGPD art. 6(1)(f)), minimisation appliquée.

5.2 Bornes numériques obligatoires¶

Profils contractuels par défaut :

Garde-fou global tenant (contractuel) :

5.3 SLA temporels (fenêtres et expiration)¶

Règle absolue : aucune clé rate_limit:v1:* ne doit survivre au-delà de key_ttl_max_seconds=3600.

5.4 Machine d’états contractuelle (requête)¶

États :

• RECEIVED
• ALLOWED (terminal)
• THROTTLED (terminal)
• BYPASS_DEGRADED (terminal)
• DENIED_DEGRADED (terminal)
• REJECTED_INVALID_CONTEXT (terminal)

Transitions autorisées :

Transitions interdites :

5.4 bis Machine d’états système (inter-requêtes)¶

États :

• HEALTHY
• DEGRADED
• RECOVERING

Transitions autorisées :

Clarification C-02 :

• La machine requête décide la réponse HTTP d’une requête.
• La machine système décrit la santé du sous-système quota entre requêtes.
• Elles sont distinctes et non substituables.

5.5 Atomicité multi-composant¶

Contrat Lua normatif :

1. L’API calcule toutes les clés Redis nécessaires.
2. L’API appelle EVALSHA rate_limit_v1.lua une seule fois.
3. Le script lit toutes les fenêtres/dimensions, détecte tout dépassement, calcule retry_after.
4. Si dépassement : retour THROTTLED, aucune décision partielle multi-clé.
5. Sinon : incrément + TTL de toutes les clés concernées dans la même exécution atomique.

5.6 Stratégie de migration DDL¶

Aucune modification de schéma SQL requise pour PD-172.
Aucune migration DDL applicable.

5.7 Mécanismes de protection distribuée¶

Checklist protection distribuée :

• Lock : raison de non-applicabilité documentée.
• Idempotence : raison de non-applicabilité documentée.
• Réconciliation : intervalle et règles définis.
• Rate-limit : granularité + dépassement définis.
• Clearing : cycles et comportement définis.

5.8 Contraintes inter-modules¶

5bis. Diagrammes (si applicable)¶

Diagramme d’état requête (stateDiagram-v2)¶

stateDiagram-v2
    [*] --> RECEIVED
    RECEIVED --> ALLOWED : quotas OK
    RECEIVED --> THROTTLED : quota depasse
    RECEIVED --> BYPASS_DEGRADED : redis down + route_family=read
    RECEIVED --> DENIED_DEGRADED : redis down + route_family=auth|costly
    RECEIVED --> REJECTED_INVALID_CONTEXT : contexte invalide
    ALLOWED --> [*]
    THROTTLED --> [*]
    BYPASS_DEGRADED --> [*]
    DENIED_DEGRADED --> [*]
    REJECTED_INVALID_CONTEXT --> [*]

Diagramme d’état système (stateDiagram-v2)¶

stateDiagram-v2
    [*] --> HEALTHY
    HEALTHY --> DEGRADED : redis indisponible
    DEGRADED --> RECOVERING : sonde succes
    RECOVERING --> HEALTHY : N succes consecutifs
    RECOVERING --> DEGRADED : sonde echec

Diagramme de séquence (sequenceDiagram)¶

sequenceDiagram
    participant C as Client
    participant API as Backend API (NestJS)
    participant RL as Redis RateLimit (db=2)
    participant OBS as Logs/Metrics

    C->>API: HTTP request(route, ip, auth context)
    API->>API: normalize route + identifier_raw
    API->>API: route_key=base64url(route)
    API->>API: identifier_hmac=HMAC-SHA256(secret, identifier_raw)
    API->>API: compose all redis keys
    API->>RL: EVALSHA rate_limit_v1.lua (single atomic command)
    RL-->>API: {decision, remaining, retry_after, system_state}

    alt decision=ALLOWED
        API->>OBS: metric decision=ALLOWED
        API-->>C: response metier + X-RateLimit-Limit + X-RateLimit-Remaining
    else decision=THROTTLED
        API->>OBS: log+metric decision=THROTTLED
        API-->>C: 429 + X-RateLimit-* + Retry-After
    else decision=BYPASS_DEGRADED
        API->>OBS: log+metric decision=BYPASS_DEGRADED
        API-->>C: response metier (fail-open controle)
    else decision=DENIED_DEGRADED
        API->>OBS: log+metric decision=DENIED_DEGRADED
        API-->>C: 503 + Retry-After
    end

6. Cas d’erreur¶

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

9. Hypothèses explicites¶

10. Points clarifiés¶

10.1 Contraintes techniques (stack réelle)¶

10.2 Décisions tranchées dans cette version¶

10.3 Questions résiduelles (non bloquantes)¶

10.4 Learnings contextuels intégrés¶

Références¶

• Epic : PD-186 — Backend Core sécurisé et modulaire
• JIRA : PD-172
• Repos concernés : ProbatioVault-backend
• Documents associés :
• docs/epics/backend-core/PD-172-rate-limiting-redis/PD-172-besoin.md
• docs/epics/backend-core/PD-172-rate-limiting-redis/PD-172-clarifications.md
• src/config/rate-limit.config.ts
• src/config/config.schema.ts
• src/common/middleware/global-rate-limit.middleware.ts