stable · guide · 0.1.0

Security、expiry、reconnect 與 backpressure

Grant security

Grant 使用 RS256 簽署，gateway 驗證 issuer、minicenter-realtime audience、expiry 與 JWKS key。Grant 有效期為 five minutes，並綁定 Project Client、subject、channels、capabilities 與 connection_limit。Gateway 會把 Project Client ID 加入內部 channel namespace，避免不同 client 使用相同 channel 名稱互通。

Browser Realtime 只對該 Project Client 已註冊的 Project Client Browser Origin 開放 CORS。Origin 採 exact match；回應 echo 該 origin 並包含 Vary: Origin，不使用 wildcard。Production 只接受 HTTPS；sandbox 額外只容許明確的 localhost 或 127.0.0.1 HTTP loopback。Browser Origin 不含 path、query、fragment 或 credentials，且與完整 OIDC callback redirect URI 不同。

Project Credential 不得送到 browser。Project Backend 必須先驗證登入狀態與 membership，再核發最小權限 grant。不要把 grant 放在 URL、log、analytics 或 telemetry；只透過 Authorization: Bearer header 傳送。

Expiry、quota 與 reconnect

Grant 到期時既有連線會關閉。Client 應向 Project Backend 取得新 grant，使用有上限的 exponential backoff 與 jitter reconnect；401 表示 grant 無效或過期，403 表示 channel/capability 未授權，429 表示 connection_limit 已滿。

BrowserRealtimeClient 將 401／expiry、403、429、503、network loss、transport_closed、malformed frame、oversized message/buffer 與 abort 正規化；transport_closed 明確涵蓋 wire contract 無法進一步區分的 gateway restart 或 backpressure closure。Error message 不包含 grant、payload 或 malformed input。Parser 可處理跨 chunk frame、同 chunk 多 frames與 unpadded base64url，以 input bytes 限制 ASCII-only unfinished SSE buffer，並限制 decoded message。Abort/close 正常結束，非 retryable authorization 或 parser error 不會無限 reconnect。

Gateway 為每個 connection 保留 16-message backpressure buffer；慢速 consumer 滿載時連線會關閉。Redis 或 gateway restart 也可能使連線與尚未送達的訊息消失。Reconnect 後必須先讀 authoritative API 取得最新狀態，再重新 subscribe；Realtime 不提供 message history 或 replay cursor。

Publish 在 Redis fanout 不可用時回 503。只有可安全重建的 UI signal 適合重新 publish；業務狀態應先持久化在 Project Backend 或使用 durable Domain Event。