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¶
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 :
| 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¶
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¶
Cas spécial — intensity: 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¶
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¶
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¶
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¶
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¶
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¶
Réponse — 200 OK¶
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¶
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 backendmemoryLeakSimulator.clearLeakedMemory()→ libère la mémoire fuitéegcPressureSimulator.clearBuffer()→ vide le buffer GCfrontendChaosController.resetState()→ réinitialise les états frontendchaosScriptingService.resetAll()→ efface les tokens scriptingbusinessChaosService.reset()→ niveau métier → 0securityChaosService.reset()→ niveau sécurité → 0functionalChaosService.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¶
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¶
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¶
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¶
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¶
Seules les clés transmises sont mises à jour — les autres conservent leur valeur. Les valeurs hors [0,100] sont bornées :
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¶
chaos/performance.md— détail des 8 paramètres Chaos Performancechaos/business.md— catalogue A1–A16chaos/functional.md— catalogue F1–F4chaos/security.md— catalogue S1–S12chaos/scripting.md— headers et bundleschaos/frontend.md— détail des 5 chaos navigateurchaos-student.md— pilotage self-service côté étudiantadmin-portal.md— portail caché activé par le niveau Sécurité 4