Protocole de messages

Les thèmes Canvas tournent dans une iframe sandbox à origine opaque. L'hôte envoie des données publiques assainies via postMessage ; le thème déclare sa disponibilité, demande des changements de hauteur et lit des ressources publiques de la liste d'autorisation avec des types de messages fixes. Le runtime de plugins n'est pas ouvert.

Table du protocole

Direction	Type	Rôle
Canvas → hôte	nie-sla:ready	demander à l'hôte d'envoyer l'état courant
Hôte → Canvas	nie-sla:status	instantané complet de l'état public
Canvas → hôte	nie-sla:resize	demander un changement de hauteur d'iframe
Canvas → hôte	nie-sla:request	demander une ressource publique de la liste d'autorisation
Hôte → Canvas	nie-sla:response	renvoyer le résultat ou une erreur

Les noms de types et le schéma Manifest nie-sla-theme-v1 sont les constantes de protocole actuelles ; utilisez-les littéralement.

Prêt

parent.postMessage({ type: 'nie-sla:ready' }, '*')

Envoyez-le après l'enregistrement de l'écouteur de messages. L'hôte tente aussi un envoi d'état au load de l'iframe, donc les thèmes doivent accepter des instantanés dupliqués.

Instantané d'état

{
  type: 'nie-sla:status',
  api_version: 'v1',
  payload: { /* même forme que GET /api/v1/status */ }
}

Validation côté récepteur :

window.addEventListener('message', event => {
  if (event.source !== parent) return
  if (!event.data || typeof event.data !== 'object') return
  if (event.data.type !== 'nie-sla:status') return
  if (event.data.api_version !== 'v1') return

  render(event.data.payload)
})

Changements de hauteur

parent.postMessage({
  type: 'nie-sla:resize',
  height: document.documentElement.scrollHeight
}, '*')

Les valeurs non finies retombent sur le défaut ; l'hôte borne la hauteur finale à 400-12000.

Requêtes d'historique

{
  type: 'nie-sla:request',
  request_id: 'checks-vps-a-72h',
  resource: 'checks',
  query: { target_id: 'vps-a', hours: 72, limit: 864 }
}

Règles de champs :

• request_id est requis, jusqu'à 80 caractères ; l'appelant évite les collisions.
• resource n'autorise que status, checks, metrics, pings, latency.
• query lit au plus les 20 premières clés.
• Les clés commencent par une lettre et contiennent lettres, chiffres ou tirets bas, jusqu'à 40 caractères.
• Les valeurs n'acceptent que string, number et boolean ; après conversion, plafond de 200 caractères.

Réponses succès et échec

{
  type: 'nie-sla:response',
  api_version: 'v1',
  request_id: 'checks-vps-a-72h',
  ok: true,
  payload: { /* réponse de l'endpoint v1 correspondant */ }
}

{
  type: 'nie-sla:response',
  api_version: 'v1',
  request_id: 'checks-vps-a-72h',
  ok: false,
  error: 'HTTP 429'
}

Le thème corrèle les promesses par request_id, définit un délai et nettoie les requêtes en attente quand l'iframe est détruite. Le texte d'erreur sert à l'affichage ou aux résumés de journaux, jamais de HTML.

L'hôte abandonne les clés invalides, les valeurs de requête complexes et les éléments au-delà des 20 premiers ; ils ne sont pas transmis à l'API. Les thèmes ne doivent pas traiter le filtrage comme une validation d'entrée ; contraignez les paramètres selon la documentation de chaque endpoint avant d'appeler.

Pourquoi *

Une iframe sans allow-same-origin a une origine opaque, donc l'hôte ne peut pas spécifier une origine de site normale comme targetOrigin. Les émetteurs utilisent * ; les récepteurs vérifient event.source === parent et contraignent strictement les types de messages et les capacités.

Cycle de vie

L'hôte peut envoyer l'état une fois au load de l'iframe et une fois à la réception de nie-sla:ready ; le rendu du thème doit être idempotent. Changer ou désactiver un thème détruit l'ancienne iframe, et les réponses tardives de l'ancienne fenêtre ne doivent pas mettre à jour le nouvel état. Gardez une table de requêtes par instance montée et nettoyez les minuteurs sur pagehide ou au démontage.