Contrat API — QoE RADIUS (intégration uniquement)

Base : https://live.jmoai.net/api/v1/radius.

Ce module est réservé au VPS d’intégration isolé. Il ne fait pas partie de l’offre commerciale STARLINK X MikroTik tant que sa validation sur NAS réel n’est pas achevée. Une action est acceptée seulement après un rapport du bridge ; 202 signifie « reçue/enregistrée », jamais « bridage appliqué ».

Télémétrie routeur

POST /qoe/telemetry exige l’en-tête x-vpn-bridge-token et le corps :

{
  "nas_id": "uuid",
  "observed_at": "2026-08-28T10:00:00Z",
  "rtt_ms": 250,
  "jitter_ms": 20,
  "packet_loss_pct": 2,
  "tx_bps": 9000000,
  "rx_bps": 12000000,
  "wan_rx_bytes": 150323855360,
  "wan_tx_bytes": 18323855360,
  "top_consumers": [{ "username": "u1", "ip": "10.0.0.4", "rx_bps": 6000000 }]
}

Réponse : 202 { "accepted": true, "event": { "id": "…", "observed_at": "…" } }. Le client_id est dérivé du NAS enregistré, jamais accepté depuis le routeur ; aucune adresse d’un autre client n’est exposée.

wan_rx_bytes et wan_tx_bytes sont des compteurs WAN cumulés en octets depuis le dernier redémarrage du routeur. Ils doivent être transmis ensemble. Le serveur ignore le premier point, les intervalles inférieurs à 15 s ou supérieurs à 15 min, et les retours à zéro : ils ne créent donc jamais artificiellement des gigaoctets consommés.

État et règles (JWT client + licence RADIUS active)

GET /qoe/status : dernières mesures par NAS et congested_nas.
GET /qoe/usage : consommation du jour par NAS, volume des deux dernières heures, état de congestion et indicateurs daily_warning / accelerating.
POST /qoe/rules : crée { name, nas_id, enabled?, condition, action }.
PUT /qoe/rules/:id et DELETE /qoe/rules/:id : modifient/suppriment seulement la règle du client connecté.

Une condition minimale est { "metric":"rtt_ms", "operator":">", "threshold":150 }. Une action déclare son type, par exemple { "type":"COA_RATE_LIMIT", "rate_limit":"1M/1M", "duration_seconds":300 }. Le moteur d’exécution CoA asynchrone est volontairement séparé de cette première livraison : il ne doit pas être activé avant validation réelle du NAS compatible CoA.

Alertes d’usage, rapports et préférences

GET /qoe/reports?limit=30 retourne les rapports quotidiens du client connecté (maximum 90).
GET /qoe/preferences retourne urgent_push, daily_report_push, usage_alert_push, quiet_start, quiet_end.
PUT /qoe/preferences modifie uniquement ces cinq champs. Les heures sont entre 0 et 23.

Le rapport quotidien est produit à 23 h 59 et est unique par client/date. Désactiver daily_report_push conserve le rapport mais ne déclenche pas de notification.

Une alerte quotidienne est créée à partir de 100 GiB. Une alerte d’accélération exige en plus au moins 5 GiB durant les deux dernières heures et une hausse d’au moins 35 % par rapport au volume déjà consommé plus tôt dans la journée. Chaque type d’alerte est unique par NAS et par jour. Les alertes respectent urgent_push et usage_alert_push.

L’alerte contient seulement une recommandation (SUGGEST_ONLY) : examen d’une file équitable et planification éventuelle pour le lendemain. Elle ne bloque ni torrent, ni application, ni utilisateur, et ne déclenche pas de CoA/PoD automatiquement.

Déconnexion manuelle

POST /qoe/actions/kick avec { "nas_id":"uuid", "username":"ticket", "session_id?":"…" } enregistre une action POD_DISCONNECT, appelle le bridge et renvoie 202 avec l’état RUNNING. Un réconciliateur devra constater la fin de session avant de la marquer SUCCEEDED.

Déviation volontaire

Le fallback PoD automatique après un échec CoA n’est pas livré : il couperait un client sur une panne de transport ou une incompatibilité NAS. Il sera ajouté seulement avec preuve CoA/PoD sur NAS réel, politique explicite et rollback de débit.