メッセージプロトコル

Canvas テーマは opaque origin の sandbox iframe で動作します。ホストは postMessage でサニタイズ済みの公開データを送り、テーマは固定メッセージタイプで準備完了・高さ変更・ホワイトリスト公開リソースの読み取りを宣言します。プラグインランタイムは現在未開放です。

プロトコル表

方向	タイプ	用途
Canvas → ホスト	nie-sla:ready	現在状態の送信を要求
ホスト → Canvas	nie-sla:status	完全な公開状態スナップショット
Canvas → ホスト	nie-sla:resize	iframe の高さ変更を要求
Canvas → ホスト	nie-sla:request	ホワイトリスト公開リソースを要求
ホスト → Canvas	nie-sla:response	結果またはエラーを返す

タイプ名とマニフェストスキーマ nie-sla-theme-v1 は現在のプロトコル定数です。リテラルで使用してください。

準備完了

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

メッセージリスナーの登録後に送信します。ホストは iframe load 時にも一度状態を送信しようとするため、テーマは重複スナップショットを受け入れる必要があります。

状態スナップショット

{
  type: 'nie-sla:status',
  api_version: 'v1',
  payload: { /* GET /api/v1/status と同じ形 */ }
}

受信側の検証：

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

高さ変更

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

非有限値は既定に戻り、ホストは最終的に 400-12000 に制限します。

履歴リクエスト

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

フィールドルール：

• request_id は必須。最大 80 文字。呼び出し側が並行衝突を避ける。
• resource は status・checks・metrics・pings・latency のみ。
• query は先頭 20 キーまで読み取る。
• キーは英字始まりの英字・数字・アンダースコアのみ。最大 40 文字。
• 値は string・number・boolean のみ。変換後は最大 200 文字。

成功・失敗レスポンス

{
  type: 'nie-sla:response',
  api_version: 'v1',
  request_id: 'checks-vps-a-72h',
  ok: true,
  payload: { /* 対応する v1 エンドポイントのレスポンス */ }
}

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

テーマは request_id で Promise を対応付け、タイムアウトを設定し、iframe 破棄時に保留リクエストを破棄します。エラーテキストは表示またはログ要約のみに使い、HTML としては扱いません。

ホストは不正キー・複雑なクエリ値・先頭 20 を超えるクエリ項目を無視し、API に渡しません。テーマはフィルタリングを入力検証と見なさず、呼び出し前に各エンドポイントのドキュメントに従ってパラメータを制約してください。

なぜ * なのか

allow-same-origin のない iframe は opaque Origin を持つため、ホストは targetOrigin に通常のサイト Origin を指定できません。送信側は * を使い、受信側は event.source === parent で送信元を検証し、メッセージタイプと能力を厳しく制限します。

ライフサイクル

ホストは iframe load と nie-sla:ready 受信時にそれぞれ一度ずつ状態を送ることがあります。テーマの描画は冪等である必要があります。テーマの切り替え・無効化で旧 iframe は破棄され、旧ウィンドウからの遅延レスポンスが新テーマの状態を更新してはいけません。マウントインスタンスごとに独立したリクエスト対応表を持ち、pagehide またはアンマウント時にタイマーを破棄してください。