Aller au contenu

API — Pilotage des chaos (admin)

Cette page documente tous les endpoints d'administration du chaos utilisés par le formateur. Elle couvre sept contrôleurs — toute une façade unifiée pour piloter et observer les 6 familles de chaos.

Contrôleurs couverts

Contrôleur Préfixe Famille chaos
ChaosController /api/admin/chaos Performance (infrastructure backend)
BusinessChaosController /api/admin/chaos/business et /api/chaos/public/business Métier (A1–A16)
FunctionalChaosController /api/admin/chaos/functional et /api/chaos/public/functional Fonctionnel (F1–F4)
SecurityChaosController /api/admin/chaos/security et /api/chaos/public/security Sécurité (S1–S12)
ChaosScriptingController /api/admin/chaos/scripting Scripting
ChaosScriptingPublicController /api/chaos/public/scripting Scripting (lecture publique)
FrontendChaosController /api/chaos/frontend Frontend (navigateur)

La page étudiant (ChaosStudentController — parcours pédagogiques et pilotage self-service) est dans chaos-student.md et pedagogique.md.


Principes transverses

Authentification

Tous les endpoints d'administration (préfixes /api/admin/chaos/*) nécessitent une authentification admin :

  • Cookie de session (admin_logged_in = true) OU
  • Header X-Admin-Token: <uuid>

La vérification est centralisée par AdminAuth.isAdmin(session, token) — voir admin.md.

Endpoints publics de lecture

Tous les endpoints /api/chaos/public/* sont en lecture seule et sans authentification. Ils sont destinés au monitoring étudiant — ce qui permet à l'interface de surveillance de continuer à afficher l'état du chaos même sans connexion admin.

Ces endpoints sont exclus du ChaosInterceptor — ils répondent toujours, même quand le chaos performance est actif à saturation. C'est une propriété critique : sans cette exclusion, un étudiant perdrait l'observabilité au moment où il en a le plus besoin.

Modèle de niveau chaos

La grande majorité des chaos utilisent le même modèle de niveau 0 à 4 :

Niveau Nom Comportement
0 Désactivé Comportement nominal
1 Junior Première anomalie introduite
2 Confirmé Anomalies cumulatives
3 Expert Anomalies avancées
4 Master Niveau maximal (requiert licence Pro)

Le Chaos Performance (infrastructure) utilise plutôt des intensités 0-100 par composant (CPU, mémoire, DB pool, etc.) — voir ci-dessous.

Format standard des réponses

{
  "success": true,
  "message": "...",
  "status": { /* état complet du chaos */ }
}

Les erreurs suivent le format global PerfShop ({"error": "..."}) — voir conventions.md.


Chaos Performance — /api/admin/chaos

Le Chaos Performance (infrastructure backend) est piloté par paramètre d'intensité et non par niveau, car chaque composant se règle indépendamment. Le ChaosController agrège 8 paramètres distincts.

Vue d'ensemble

Méthode Endpoint Description
GET /api/admin/chaos/status État complet (backend + frontend)
GET /api/admin/chaos/public/status Idem, sans auth (monitoring)
POST /api/admin/chaos/reset Remet tous les chaos à 0
POST /api/admin/chaos/cpu Saturation CPU
POST /api/admin/chaos/memory Fuite mémoire contrôlée
POST /api/admin/chaos/gc-pressure Pression GC (pattern en dents de scie)
POST /api/admin/chaos/db-pool Saturation du pool de connexions DB
POST /api/admin/chaos/thread-pool Saturation du pool de threads Tomcat
POST /api/admin/chaos/slow-queries Ralentissement des requêtes SQL
POST /api/admin/chaos/deadlock Probabilité de deadlock DB
POST /api/admin/chaos/network Simulation de timeout réseau

DTO commun — ChaosConfigRequest

Tous les endpoints de ce bloc partagent le même DTO de requête :

{
  "intensity": 80,
  "guardrail": 80,
  "ratio": 2
}
Champ Type Requis Contrainte Usage
intensity Integer oui 0–105 Intensité principale (0 = off, 100 = max, 105 = OOM volontaire pour la mémoire)
guardrail Integer non 0–100 Plafond de sécurité mémoire (% du heap max) — défaut 80
ratio Integer non 1–5 Multiplicateur CPU — nombre de threads simultanés

POST /api/admin/chaos/cpu

Génère une charge CPU via CpuChaosScheduler. L'intensité représente un pourcentage de temps CPU consommé, et ratio multiplie le nombre de threads de charge pour saturer plusieurs cœurs.

Requête

{ "intensity": 80, "ratio": 2 }

Réponse — 200 OK

{
  "success": true,
  "message": "CPU intensité 80 ratio=2x",
  "status": {
    "cpu": 80,
    "cpuRatio": 2,
    "memoryLeakTarget": 0,
    "memoryGuardrail": 80,
    "gcPressure": 0,
    "dbPool": 0,
    "threadPool": 0,
    "slowQueries": 0,
    "deadlock": 0,
    "network": 0
  }
}

Le message est construit par chaos.infra.cpu.set avec les valeurs intensity et ratio.


POST /api/admin/chaos/memory

Déclenche une fuite mémoire progressive via MemoryLeakSimulator. Le champ intensity est la cible (en % du heap max), et guardrail est le plafond de sécurité au-delà duquel le simulateur refuse d'allouer.

Requête

{ "intensity": 90, "guardrail": 80 }

Cas spécialintensity: 105 déclenche une OOM volontaire (le simulateur alloue au-delà du heap max jusqu'à OutOfMemoryError). C'est réservé aux démonstrations de récupération et aux analyses de heap dump post-mortem.

Formule effective

effectivePct = (intensity × guardrail) / 100

Exemple : intensity=90, guardrail=80 → heap cible = 72% du heap max. Cette double contrainte permet au formateur de régler la cible pédagogique (intensity) et la cible sécurité (guardrail) indépendamment.

Si intensity == 0, le simulateur appelle clearLeakedMemory() qui libère progressivement la mémoire allouée.

Réponse — 200 OK

{
  "success": true,
  "message": "Fuite mémoire cible 90%, garde-fou=80%",
  "status": { "memoryLeakTarget": 90, "memoryGuardrail": 80, "...": "..." }
}

Si intensity == 105, le message devient Fuite mémoire cible OOM, garde-fou=80%.


POST /api/admin/chaos/gc-pressure

Active le GcPressureSimulator qui alloue des objets à durée de vie courte pour forcer le GC à travailler. Le pattern résultant dans Grafana est caractéristique : dents de scie avec période ~4 secondes (buffer circulaire 4 slots × 1s de rétention).

Requête

{ "intensity": 70 }

Réponse — 200 OK

{
  "success": true,
  "message": "Pression GC intensité 70",
  "status": { "gcPressure": 70, "...": "..." }
}

Ajout récent au catalogue

L'endpoint gc-pressure a été ajouté après la rédaction des prompts de refonte documentaire. Il complète le chaos mémoire traditionnel : memory génère une fuite linéaire (courbe croissante), gc-pressure génère une oscillation stable (dents de scie). Les deux peuvent être combinés pour simuler un service sous pression GC et sous fuite mémoire.

Si intensity == 0, le simulateur appelle clearBuffer() qui vide le buffer circulaire.


POST /api/admin/chaos/db-pool

Sature le pool de connexions HikariCP via DbPoolChaosScheduler. L'intensité représente le % de connexions occupées en permanence par des « dormantes » qui monopolisent le pool sans libérer.

Requête

{ "intensity": 60 }

Réponse — 200 OK

{
  "success": true,
  "message": "Saturation pool DB intensité 60",
  "status": { "dbPool": 60, "...": "..." }
}

POST /api/admin/chaos/thread-pool

Sature le pool de threads Tomcat. Les requêtes entrantes doivent attendre qu'un thread se libère.

Requête

{ "intensity": 80 }

Réponse — 200 OK

{
  "success": true,
  "message": "Saturation pool threads intensité 80",
  "status": { "threadPool": 80, "...": "..." }
}

POST /api/admin/chaos/slow-queries

Ralentit certaines requêtes SQL en insérant des SLEEP() ou en forçant le planner à faire des full scans. L'intensité est la probabilité qu'une requête soit ralentie et la durée du ralentissement.

Requête

{ "intensity": 50 }

Réponse — 200 OK

{
  "success": true,
  "message": "Requêtes lentes intensité 50",
  "status": { "slowQueries": 50, "...": "..." }
}

POST /api/admin/chaos/deadlock

Injecte une probabilité de deadlock dans les transactions concurrentes (typiquement sur orders et order_items). Déclenche des SQLIntegrityConstraintViolationException côté client.

Requête

{ "intensity": 30 }

Réponse — 200 OK

{
  "success": true,
  "message": "Deadlock intensité 30",
  "status": { "deadlock": 30, "...": "..." }
}

Les deadlocks affectent directement OrderController.getUserOrders() via applyDeadlockChaosPublic() — voir orders.md.


POST /api/admin/chaos/network

Simule des timeouts réseau sur les appels sortants (base de données, services externes simulés). L'intensité contrôle la probabilité et la durée des ralentissements.

Requête

{ "intensity": 40 }

Réponse — 200 OK

{
  "success": true,
  "message": "Timeout réseau intensité 40",
  "status": { "network": 40, "...": "..." }
}

GET /api/admin/chaos/status

Retourne l'état consolidé backend + frontend.

Auth : admin

Réponse — 200 OK

{
  "backend": {
    "cpu": 80,
    "cpuRatio": 2,
    "memoryLeakTarget": 0,
    "memoryGuardrail": 80,
    "gcPressure": 0,
    "dbPool": 0,
    "threadPool": 0,
    "slowQueries": 0,
    "deadlock": 0,
    "network": 0
  },
  "frontend": {
    "cpuBurn": 0,
    "memoryLeak": 0,
    "domFlood": 0,
    "fetchFlood": 0,
    "doubleFetch": 0
  }
}

GET /api/admin/chaos/public/status

Endpoint public (sans authentification) retournant l'état consolidé backend + frontend + métier + fonctionnel. Utilisé par le monitoring étudiant.

Path sous /admin mais public

L'endpoint est exposé sous le préfixe /api/admin/chaos/public/status — sous /admin/ par cohérence de routage, mais sans auth. Ce choix paraît contre-intuitif mais il permet de garder tous les status chaos sous une même arborescence dans ChaosController.

Réponse — 200 OK

{
  "backend":    { "...": "..." },
  "frontend":   { "...": "..." },
  "business":   { "level": 0, "anomalies": [], "activeCount": 0 },
  "functional": { "level": 0, "anomalies": [], "activeCount": 0 }
}

POST /api/admin/chaos/reset

Remet tous les chaos à 0 en une seule opération :

  • chaosService.resetAll() → infrastructure backend
  • memoryLeakSimulator.clearLeakedMemory() → libère la mémoire fuitée
  • gcPressureSimulator.clearBuffer() → vide le buffer GC
  • frontendChaosController.resetState() → réinitialise les états frontend
  • chaosScriptingService.resetAll() → efface les tokens scripting
  • businessChaosService.reset() → niveau métier → 0
  • securityChaosService.reset() → niveau sécurité → 0
  • functionalChaosService.reset() → niveau fonctionnel → 0

Réponse — 200 OK

{
  "success": true,
  "message": "All chaos intensities reset to 0",
  "status": { /* état complet à 0 */ }
}

Reset DB non inclus

Le reset ne modifie pas la base de données. Les modifications déjà appliquées par les chaos (A15 corruption historique, S12 promotion superadmin, stocks non recrédités A16) restent persistantes. Un vrai « reset propre » nécessite en plus un docker compose down -v pour tout remettre à neuf.


Chaos Métier — /api/admin/chaos/business et /api/chaos/public/business

Le Chaos Métier est piloté par un seul paramètre : le niveau global (0–4). Chaque niveau active un ensemble cumulatif d'anomalies A1–A16. Voir la liste complète dans chaos/business.md.

Vue d'ensemble

Méthode Endpoint Auth Description
POST /api/admin/chaos/business Admin Définir le niveau (0-4)
GET /api/admin/chaos/business/status Admin Statut + compteurs
POST /api/admin/chaos/business/reset Admin Reset niveau et compteurs
POST /api/admin/chaos/business/logs/clear Admin Vider le log d'activité
GET /api/chaos/public/business/status Aucune Statut public (monitoring)
GET /api/chaos/public/business/logs Aucune Log d'activité public
GET /api/chaos/public/business/anomalies Aucune Catalogue pédagogique pour un niveau

POST /api/admin/chaos/business

Requête

{ "level": 3 }

Réponse — 200 OK

{
  "success": true,
  "status": {
    "level": 3,
    "levelName": "Niveau 3 — Expert",
    "anomaliesActive": ["A1", "A2", "A3", "A4", "A5", "A6", "A7", "A8", "A9", "A10", "A11"],
    "counters": {
      "A1": 0, "A2": 0, "A3": 0, "A4": 0, "A5": 0,
      "A6": 0, "A7": 0, "A8": 0, "A9": 0, "A10": 0, "A11": 0
    }
  }
}

Codes d'erreur

Code Cause
400 Level hors [0–4] (chaos.error.level_range)
401 Non authentifié

GET /api/chaos/public/business/anomalies

Catalogue pédagogique : retourne la liste des anomalies actives pour un niveau donné, avec leurs descriptions localisées.

Paramètres

Paramètre Type Défaut Description
level (query) integer 3 Niveau pour lequel récupérer le catalogue

Réponse — 200 OK

{
  "level": 3,
  "levelName": "Niveau 3 — Expert",
  "count": 11,
  "anomalies": [
    { "id": "A1", "name": "TVA incorrecte", "detail": "Taux TVA 19,6% applique au lieu de 20% — montant TTC legerement sous-evalue" },
    { "id": "A11", "name": "Token session non invalide", "detail": "Token valide 30s apres logout — replay attack possible" }
  ]
}

Cet endpoint est utilisé par le frontend du monitoring étudiant pour afficher la fiche pédagogique de chaque niveau.


Chaos Fonctionnel — /api/admin/chaos/functional et /api/chaos/public/functional

Même modèle que le Chaos Métier, avec 4 anomalies F1–F4 au lieu de 16.

Vue d'ensemble

Méthode Endpoint Description
POST /api/admin/chaos/functional Définir niveau
GET /api/admin/chaos/functional/status Statut
POST /api/admin/chaos/functional/reset Reset
POST /api/admin/chaos/functional/logs/clear Vider log
GET /api/chaos/public/functional/status Statut public
GET /api/chaos/public/functional/logs Log public
GET /api/chaos/public/functional/anomalies?level=N Catalogue

Structure identique au Chaos Métier — voir les exemples ci-dessus. La seule différence est que level=4 inclut F4 (corruption silencieuse), l'anomalie la plus vicieuse du catalogue. Voir chaos/functional.md.


Chaos Sécurité — /api/admin/chaos/security et /api/chaos/public/security

Même modèle, avec 12 failles S1–S12. Le niveau 4 active les failles S10/S11/S12 qui rendent AdminPortalController visible et vulnérable — voir admin-portal.md.

Vue d'ensemble

Méthode Endpoint Description
POST /api/admin/chaos/security Définir niveau
GET /api/admin/chaos/security/status Statut
POST /api/admin/chaos/security/reset Reset
POST /api/admin/chaos/security/logs/clear Vider log
GET /api/chaos/public/security/status Statut public
GET /api/chaos/public/security/logs Log public
GET /api/chaos/public/security/faults?level=N Catalogue

Niveau 4 = portail caché actif

Passer le Chaos Sécurité au niveau 4 active immédiatement AdminPortalController — les endpoints /api/admin/portal/* arrêtent de renvoyer 404 et deviennent exploitables. Passer le niveau sous 4 remasque le portail.

Réponse de GET /public/security/faults?level=4

{
  "level": 4,
  "levelName": "Niveau 4 — Master",
  "count": 12,
  "faults": [
    { "id": "S1", "name": "Injection SQL", "detail": "Parametre q= injecte en SQL native — /api/products/search" },
    { "id": "S12", "name": "IDOR Elevation Privileges", "detail": "PUT /api/admin/portal/accounts/{id}/promote — verification superAdmin contournable" }
  ]
}

Chaos Scripting — /api/admin/chaos/scripting et /api/chaos/public/scripting

Le Chaos Scripting contrôle la complexité des headers anti-rejeu requis sur le parcours checkout. Les noms de niveaux suivent une gradation spécifique, définie dans les clés i18n chaos.scripting.level.* :

Niveau Nom Headers requis
0 Désactivé Aucun
1 Junior X-Session-Token, X-Request-ID
2 Confirmé + X-Action-Token renouvelé à chaque étape
3 Expert + X-CSRF-Token, X-Step-Token, X-Signature (HMAC)
4 Maestro Idem + clé HMAC dérivée du sessionToken

Vue d'ensemble

Méthode Endpoint Auth Description
POST /api/admin/chaos/scripting Admin Définir niveau (0-4)
GET /api/admin/chaos/scripting/status Admin Statut + bundles actifs
POST /api/admin/chaos/scripting/reset Admin Efface tous les bundles
GET /api/admin/chaos/scripting/logs Admin Log d'activité
DELETE /api/admin/chaos/scripting/logs Admin Vider le log
GET /api/chaos/public/scripting/status Aucune Statut public
GET /api/chaos/public/scripting/logs Aucune Log public

Contrôleur public séparé

Contrairement aux autres familles où le même contrôleur gère admin et public via des routes distinctes, le Chaos Scripting utilise deux contrôleurs séparés :

  • ChaosScriptingController/api/admin/chaos/scripting (admin)
  • ChaosScriptingPublicController/api/chaos/public/scripting (public)

Ce découpage reflète une séparation stricte entre l'interface de pilotage et l'interface de monitoring.

POST /api/admin/chaos/scripting

Requête

{ "level": 2 }

Réponse — 200 OK

{
  "success": true,
  "status": {
    "level": 2,
    "levelName": "Confirme",
    "activeBundles": 0,
    "rotationCount": 0
  }
}

Codes d'erreur

Code Cause
400 Level hors [0–4] (chaos.scripting.error.level_range) — message en anglais : level must be 0, 1, 2, 3 or 4
401 Non authentifié

POST /api/admin/chaos/scripting/reset

Efface tous les bundles actifs (tokens de session de tous les utilisateurs en parcours checkout) et remet le niveau à 0.

Réponse — 200 OK

{
  "success": true,
  "message": "All scripting tokens cleared"
}

Effet immédiat sur les étudiants

Un reset pendant qu'un étudiant est en cours de checkout casse immédiatement sa session — la prochaine étape retournera une erreur Chaos Scripting (token invalide). C'est acceptable en formation car les étudiants peuvent recommencer le parcours, mais à éviter en démonstration live sans prévenir.


Chaos Frontend — /api/chaos/frontend

Le Chaos Frontend est géré par un contrôleur relais : le backend ne fait que stocker un état qui est ensuite pollé par le frontend React toutes les 5 secondes et interprété côté navigateur.

Vue d'ensemble

Méthode Endpoint Auth Description
GET /api/chaos/frontend/state Aucune État courant (pollé par le frontend)
POST /api/chaos/frontend/state Admin Mise à jour de l'état

GET /api/chaos/frontend/state

Retourne l'état courant des 4 chaos frontend. Endpoint pollé en permanence par le frontend React, sans authentification.

Réponse — 200 OK

{
  "cpuBurn": 0,
  "memoryLeak": 0,
  "domFlood": 0,
  "fetchFlood": 0,
  "doubleFetch": 0
}

Chaque valeur est une intensité 0–100.

Chaos Description
cpuBurn Boucles JavaScript qui consomment le CPU du navigateur
memoryLeak Allocation progressive d'objets JS non libérés
domFlood Insertion massive d'éléments DOM
fetchFlood Multiplication des appels fetch() vers /api/products
doubleFetch Double-appel systématique des requêtes (race conditions)

POST /api/chaos/frontend/state

Met à jour les intensités frontend.

Auth : admin

Requête

{
  "cpuBurn": 50,
  "domFlood": 30
}

Seules les clés transmises sont mises à jour — les autres conservent leur valeur. Les valeurs hors [0,100] sont bornées :

state.put(k, Math.max(0, Math.min(100, v)));

Réponse — 200 OK

{
  "success": true,
  "state": {
    "cpuBurn": 50,
    "memoryLeak": 0,
    "domFlood": 30,
    "fetchFlood": 0,
    "doubleFetch": 0
  }
}

Exemple curl — séquence complète de pilotage

# 1. Login admin et récupérer le token
TOKEN=$(curl -s -H "Content-Type: application/json" \
  -d '{"email":"admin@perfshop.fr","password":"admin"}' \
  http://localhost:9080/api/admin/login | jq -r '.adminToken')

# 2. Activer Chaos Performance CPU à 80% avec ratio 2
curl -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"intensity":80,"ratio":2}' \
     http://localhost:9080/api/admin/chaos/cpu

# 3. Activer Chaos Métier niveau 3 (11 anomalies)
curl -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"level":3}' \
     http://localhost:9080/api/admin/chaos/business

# 4. Activer Chaos Sécurité niveau 4 (active portail caché)
curl -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"level":4}' \
     http://localhost:9080/api/admin/chaos/security

# 5. Activer Chaos Frontend — CPU burn 50%
curl -H "X-Admin-Token: $TOKEN" -H "Content-Type: application/json" \
     -d '{"cpuBurn":50,"domFlood":30}' \
     http://localhost:9080/api/chaos/frontend/state

# 6. Vérifier l'état consolidé
curl -H "X-Admin-Token: $TOKEN" http://localhost:9080/api/admin/chaos/status

# 7. Reset global quand on a fini
curl -H "X-Admin-Token: $TOKEN" -X POST \
     http://localhost:9080/api/admin/chaos/reset

Points d'attention transverses

Ordre de reset recommandé

Pour une remise à zéro complète, préférer POST /api/admin/chaos/reset qui appelle tous les resets individuels dans le bon ordre. Les reset par famille (business/reset, security/reset, etc.) ne touchent pas le chaos performance ou le frontend — un reset partiel peut laisser des artefacts.

Le reset ne touche pas la base

Aucun endpoint de reset ne modifie la base de données. Les corrections de stock (A16), les promotions de compte (S12), les corruptions d'historique (A15) sont persistantes. Seul un docker compose down -v restaure l'état initial.

Observabilité : le monitoring utilise les endpoints publics

Les 4 contrôleurs chaos (Performance, Métier, Fonctionnel, Sécurité) + Scripting exposent des endpoints /api/chaos/public/* que le monitoring étudiant poll périodiquement. Ces endpoints sont conçus pour être surveillés sans authentification — ils n'exposent que l'état du chaos, jamais de données sensibles.


Liens associés