[ADP-373] 伺服器端事件
概述
伺服器端事件（SSE）是向客戶端提供即時通知的方式之一。SSE 允許伺服器通過單一的長期 HTTP 連接向客戶端推送更新。這種機制對於需要及時更新的應用程序特別有用，例如實時資訊流、通知或實時數據監控。
指導
伺服器實現
API 提供者（伺服器）必須(MUST)在回應標頭中指定
Content-Type: text/event-stream，以表明回應是事件流。伺服器應(SHOULD)盡可能保持連接開放，以持續向客戶端推送更新。
流中的每個事件應(SHOULD)遵循 SSE 格式:
數據行:以 "data:" 開頭，後跟事件數據。
事件行:以 "event:" 開頭，後跟事件名稱（可選）。
ID 行:以 "id:" 開頭，後跟事件的唯一標識符（可選）。
重試行:以 "retry:" 開頭，後跟重新連接時間（毫秒）（可選）。
你可以在標頭中設計一個機制來終止連接。
客戶端實現
如果 API 消費者（客戶端）請求持續的伺服器端消息而不是一次性的請求-回應，必須(MUST)在請求標頭中指定
Accept: text/event-stream。客戶端應(SHOULD)優雅地處理重新連接，以應對網絡問題或伺服器重啟。
API 消費者（瀏覽器客戶端）應(SHOULD)使用具有流支持的 Fetch API，而不是 EventSource API，因為後者被認為已過時且靈活性較低。
錯誤處理:如果在流期間發生錯誤，伺服器應(SHOULD)發送錯誤事件。客戶端可以使用此功能適當處理錯誤。
終止標頭:伺服器可(MAY)包含自定義標頭 X-SSE-Terminate，值為 true，以指示應終止連接。
安全考慮
確保適當的授權機制到位。伺服器應在建立 SSE 連接之前驗證客戶端的權限。
必須使用安全傳輸（HTTPS）以保護數據完整性和機密性。
在伺服器上實施速率限制，以防止濫用 SSE 端點。
客戶端應監聽錯誤事件並適當處理，例如重試連接或向用戶顯示錯誤消息。
客戶端應檢查回應中的 X-SSE-Terminate 標頭，如果存在且設置為 true，則終止連接。
示例
OpenAPI 文件示例
openapi: 3.1.0
info:
title: Server Side Events API
version: 1.0.0
paths:
/events:
get:
summary: Subscribe to server side events
operationId: subscribeEvents
responses:
'200':
description: Stream of server side events
content:
text/event-stream:
schema:
type: string
examples:
- |
event: message
data: {"message": "Hello, World!"}
id: 1
event: update
data: {"update": "New data available"}