API Admin

Le serveur HTTP admin s’exécute aux côtés de chaque simulation Miravo. Liaison par défaut : http://127.0.0.1:8080.

Endpoints

Méthode	Chemin	Fonction
GET	/healthz	Vérification de vivacité
GET	/readyz	Vérification de disponibilité (moteur + adaptateurs)
GET	/metrics	Snapshot des métriques du moteur
GET	/state	Snapshot de l’état du moteur
POST	/commands	Exécuter une commande du moteur
POST	/shutdown	Arrêt gracieux (mode daemon)
GET	/instances/:id	Détail complet d’une instance
GET	/models/:name	Schéma du modèle
GET	/events	Journal d’événements paginé
GET	/ws	Upgrade WebSocket pour le streaming en temps réel

Vérifications de santé

GET /healthz

Retourne 200 quand le moteur est en cours et que la boucle de tick progresse. Retourne 503 quand arrêté ou bloqué.

curl -s http://127.0.0.1:8080/healthz | jq .

GET /readyz

Retourne 200 quand le moteur est running et tous les adaptateurs activés sont connectés. Retourne 503 si un adaptateur est déconnecté ou si le moteur est en pause/arrêté.

État et métriques

GET /state

Snapshot structurel avec les modèles, instances, configuration et adaptateurs disponibles.

curl -s http://127.0.0.1:8080/state | jq .

GET /metrics

Métriques d’exécution incluant le nombre de ticks, le nombre d’instances et les statistiques par adaptateur.

GET /instances/:id

Détail complet d’une instance : valeurs des membres, paramètres, méthodes, cycle de vie, défaillances.

curl -s http://127.0.0.1:8080/instances/pump-001 | jq .

GET /models/:name

Schéma du modèle avec paramètres, membres, méthodes, défaillances et définition du cycle de vie.

curl -s http://127.0.0.1:8080/models/centrifugal-pump | jq .

Commandes

POST /commands

Exécuter une commande du moteur. Accepte un objet JSON de commande — voir les types de commandes supportés ci-dessous.

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{"type":"pause"}'

Types de commandes supportés :

Commande	Champs clés
pause	—
resume	—
setSpeed	multiplier
spawn	model, count, variation, parameterOverrides
removeInstance	instanceId
setParameter	instanceId, parameter, value
triggerFault	instanceId, fault
clearFault	instanceId, fault
unquarantine	instanceId
invokeMethod	instanceId, method, arguments
loadTemplate	templatePath, count
unloadTemplateRun	templateRunId
resetSimulation	clearPersistence
enableAdapter	adapter, config
disableAdapter	adapter

Exemple — appeler une méthode de modèle :

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -d '{
    "type": "invokeMethod",
    "instanceId": "pump-001",
    "method": "SetSpeed",
    "arguments": {"speed_rpm": 900}
  }'

Journal d’événements

GET /events

Journal d’événements paginé avec pagination par curseur.

Récupérer les événements de défaillance récents :

curl -s 'http://127.0.0.1:8080/events?type=fault:triggered&limit=10'

Paramètres de requête :

Paramètre	Description
type	Filtre : fault:triggered, fault:cleared, lifecycle:changed, instance:created, instance:removed, engine:state-changed
instanceId	Filtrer par instance
limit	Taille de page (défaut 100, max 1000)
cursor	Curseur pour la pagination vers l’arrière

Réponse : { "events", "nextCursor", "total" }

WebSocket

GET /ws

Upgrade en WebSocket pour le streaming d’événements en temps réel.

websocat ws://127.0.0.1:8080/ws

À la connexion, le serveur envoie un message snapshot avec l’état actuel. Il pousse ensuite les événements sur les canaux souscrits.

Canaux : tick, faults, lifecycle, instances, engine, adapters (tous activés par défaut).

Changer les souscriptions :

{"type": "subscribe", "channels": ["faults", "lifecycle"]}

Maximum 10 connexions WebSocket simultanées. Les messages portent des numéros de revision monotones pour l’ordonnancement.

Authentification

Définissez MIRAVO_ADMIN_TOKEN pour exiger une authentification par jeton bearer sur les endpoints de mutation :

export MIRAVO_ADMIN_TOKEN=my-secret-token

Les commandes requièrent maintenant le jeton :

curl -s http://127.0.0.1:8080/commands \
  -H 'content-type: application/json' \
  -H 'Authorization: Bearer my-secret-token' \
  -d '{"type":"pause"}'

Les endpoints en lecture seule (/healthz, /readyz, /metrics, /state, /instances/*, /models/*, /events) ne requièrent pas d’authentification.

Quand vous vous liez à une adresse non-loopback, MIRAVO_ADMIN_TOKEN est requis pour les endpoints de mutation. Sans lui, POST /commands et POST /shutdown retournent 403.

Configuration

Option	Variable d’env	Défaut	Description
--admin-port	MIRAVO_ADMIN_PORT	8080	Port du serveur admin
--admin-host	MIRAVO_ADMIN_HOST	127.0.0.1	Hôte de liaison du serveur admin
—	MIRAVO_ADMIN_TOKEN	—	Jeton bearer pour les endpoints de mutation