Nachrichtenprotokoll

Canvas-Themes laufen in einer Sandbox-Iframe mit opaker Origin. Der Host sendet entschärfte öffentliche Daten über postMessage; das Theme erklärt Bereitschaft, fordert Höhenänderungen und liest weiße öffentliche Ressourcen mit festen Nachrichtentypen. Der Plugin-Runtime ist nicht offen.

Protokolltabelle

Richtung	Typ	Zweck
Canvas → Host	nie-sla:ready	Host bitten, den aktuellen Zustand zu senden
Host → Canvas	nie-sla:status	vollständiger öffentlicher Zustands-Snapshot
Canvas → Host	nie-sla:resize	Iframe-Höhenänderung anfordern
Canvas → Host	nie-sla:request	eine weiße öffentliche Ressource anfordern
Host → Canvas	nie-sla:response	Ergebnis oder Fehler zurückgeben

Typnamen und das Manifest-Schema nie-sla-theme-v1 sind die aktuellen Protokollkonstanten; wörtlich verwenden.

Bereit

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

Nach der Registrierung des Nachrichten-Listeners senden. Der Host versucht auch einen Zustands-Send beim Iframe-load; Themes müssen doppelte Snapshots akzeptieren.

Zustands-Snapshot

{
  type: 'nie-sla:status',
  api_version: 'v1',
  payload: { /* gleiche Form wie GET /api/v1/status */ }
}

Validierung auf Empfängerseite:

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)
})

Höhenänderungen

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

Nicht endliche Werte fallen auf den Standard zurück; der Host klemmt die endgültige Höhe auf 400-12000.

Historien-Anfragen

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

Feldregeln:

• request_id ist Pflicht, bis 80 Zeichen; der Aufrufer vermeidet Kollisionen.
• resource erlaubt nur status, checks, metrics, pings, latency.
• query liest höchstens die ersten 20 Schlüssel.
• Schlüssel beginnen mit einem Buchstaben und enthalten Buchstaben, Ziffern oder Unterstriche, bis 40 Zeichen.
• Werte akzeptieren nur string, number und boolean; nach Konvertierung auf 200 Zeichen begrenzt.

Erfolgs- und Fehlerantworten

{
  type: 'nie-sla:response',
  api_version: 'v1',
  request_id: 'checks-vps-a-72h',
  ok: true,
  payload: { /* entsprechende v1-Endpoint-Antwort */ }
}

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

Das Theme korreliert Promises über request_id, setzt ein Timeout und räumt ausstehende Anfragen beim Zerstören der Iframe auf. Fehlertext dient nur der Anzeige oder Log-Zusammenfassung, nie HTML.

Der Host verwirft ungültige Schlüssel, komplexe Query-Werte und Elemente über den ersten 20; sie werden nicht an die API weitergegeben. Themes dürfen Filtern nicht als Eingabevalidierung behandeln; Parameter vor dem Aufruf gemäß Endpoint-Doku einschränken.

Warum *

Eine Iframe ohne allow-same-origin hat eine opake Origin, daher kann der Host keine normale Website-Origin als targetOrigin angeben. Sender verwenden *; Empfänger prüfen event.source === parent und schränken Nachrichtentypen und Fähigkeiten streng ein.

Lebenszyklus

Der Host kann den Zustand einmal beim Iframe-load und einmal beim Empfang von nie-sla:ready senden; das Theme-Rendering muss idempotent sein. Wechseln oder Deaktivieren zerstört die alte Iframe, und späte Antworten des alten Fensters dürfen den neuen Zustand nicht aktualisieren. Eine eigene Anfrage-Tabelle pro gemounteter Instanz führen und Timer bei pagehide oder Unmount aufräumen.