A / 外部系統通知
業務事件送到外部系統
訂單、票務或帳務狀態要通知別的系統時，用 Webhook 投遞。失敗會自動重試，用盡後進入死信佇列，可查看、可重放。
邊界：死信佇列只收 Webhook 投遞失敗；publish 與長輪詢消費失敗不會進去。
深入了解 Webhook 重試與 DLQ →先看它真的動起來
不用先相信這頁。親手發一筆事件。
三個 Demo 都連到公開服務，不是預錄畫面。先用事件牆看懂收發，再試聊天室與客服工單的 room 隔離。
即時事件牆
自動事件、其他訪客與你送出的訊息會進入同一條事件流。可切換 SSE 與 WebSocket，免註冊。
使用場景
事件要去哪裡，決定你該選哪條路。
五種常見的事件交付方式，每一種都先說明適用情境與限制，方便你直接判斷。
B / 前端即時狀態
前端即時顯示後端發生的事
聊天訊息、任務進度、頁面狀態走 SSE 或 WebSocket 下行。斷線後會從 cursor 補回；官方 SDK 會依 partition cursor 去重。
邊界：WebSocket 是單向下行，上行訊息會被丟棄；SSE 補回受保留期與單次 5,000 則上限約束。
比較 SSE 與 WebSocket →C / AI agent 訂閱
agent 直接訂閱業務事件
agent 透過官方 MCP Server 訂閱事件，不必另寫「事件轉 LLM」的橋接服務。新訊息一到就能處理，不必每隔幾分鐘輪詢。
邊界：MCP 的治理類工具需要 admin scope 金鑰，而金鑰要先有帳號才能建立。
查看 AI agent 事件訂閱 →D / 多房間隔離
一個 topic 切成多個互不干擾的房間
同一條事件流可用 room 分房。發布與 SSE／WebSocket 訂閱都能限定房間，不必每群開一個 topic。
邊界：HTTP 長輪詢沒有房間概念，一律接收整個 topic；在線人數也是整個 topic 的彙總，不分房間。
E / 最小權限
一把金鑰只開一條路
金鑰可限定動作與 topic；支援房間的介面還能限定 room。越權請求會回 403，因此金鑰外流時，影響範圍只限於它開放的能力。
邊界：面板目前無法建立限定房間的金鑰，需要使用 API 或 SDK。
運作方式
事件只需送進來一次，就能分送到多個接收端。
MsgMesh 位在發布端與接收端之間：先保存事件，再按接收端選擇的協議與交付規則送出。
事件保留
訊息在保留期內留著；接收端晚到，仍可依 cursor 回放。
重試與死信
Webhook 暫時失敗會自動重試；用盡後進入可查看、可重放的死信佇列。
斷線補回
SSE 重連時從同一個 cursor 接上，在有界重播窗內補回漏掉的訊息。
金鑰權限
金鑰可限定動作與 topic；支援 room 的介面可再縮小範圍，越權回 403。
為什麼不自己接 Kafka
Kafka 讓你掌控串流基礎設施；MsgMesh 讓你直接把事件交付給應用程式。
自行接 Kafka，要負責叢集、offset、重連、重試與權限；MsgMesh 把這些包成 HTTP、SSE、WebSocket、Webhook 與 MCP，直接提供給接收端使用。
| 自己接 Kafka | 用 MsgMesh | |
|---|---|---|
| 部署維運 | 自建叢集、監控、升級、擴容 | 託管，不用自己顧 Kafka |
| 重試與死信 | 自己設計退避、落地、重放 | Webhook 投遞失敗自動重試，用盡進死信可重放 |
| 斷線續傳 | 自己記位移、處理重連補齊 | SSE 依 cursor 在有界重播窗內自動補回 |
| 歷史補齊 | 自己另建歷史儲存 | 歷史查詢，再用同一個 cursor 接上即時流 |
| 權限 | 自己做 ACL 與多租戶隔離 | 金鑰可限定動作與 topic；支援 room 的介面可進一步限定 room，越權回 403 |
| AI 接入 | 自己寫一層事件橋接到 LLM | 官方 MCP Server，agent 可直接訂閱 |
room 範圍適用於發布、SSE / WebSocket 訂閱，以及帶 room 的歷史查詢；HTTP 長輪詢以整個 topic 為單位。
快速上手
發出第一則事件
先建立 topic，再發布事件。兩步要分開執行；topic 已存在時，建立步驟會回 409，寫在同一段腳本會讓第二次執行停在第一行。
首次設定（只執行一次）
curl -X POST 'https://msgmesh-api.alderflux.com/v1/topics' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"name": "orders"}'
日常發布（可重複執行）
curl -X POST 'https://msgmesh-api.alderflux.com/v1/topics/orders/messages' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{"orderId": "order_12345", "currency": "TWD", "status": "paid"}'
TypeScript、JavaScript、Python 與 MCP 的完整片段，以及三個服務網址的設定方式，都在快速上手。
接收方式與限制
四種接收協議，差在誰主動連線、能否補回，以及失敗後怎麼處理。
| 接收方式 | 投遞語義 | 可用環境 | 備註 |
|---|---|---|---|
| Webhook | at-least-once | 需公開可達 URL | 失敗自動重試，用盡進死信可重放 |
| SSE stream() | at-least-once | 瀏覽器；JavaScript SDK 目前在 Node 不支援 SSE | 斷線在有界重播窗內自動補回 |
| WebSocket streamWs() | at-least-once | 瀏覽器，或 Node 22+ | 單向下行，發布走 HTTP |
| HTTP 長輪詢 subscribe() | at-most-once | Node 與瀏覽器都可 | 位移取回即提交，回應遺失就取不回 |
正式環境請明確指定 consumer group。同一 group 內的消費者會分攤訊息；不同的邏輯訂閱者應各自使用不同 group，避免意外共用 default。
Python 的 WebSocket 需要額外安裝選用依賴，詳細執行環境請見文件。
接入方式
發布與接收不必使用同一種協議，各端都能選最適合的方式。
INGEST
- HTTP API任何後端與既有系統
- SDKTypeScript 與 Python
- MCP Serveragent 直接訂閱與治理
DELIVER
- SSE瀏覽器即時，有界補回
- WebSocket單向下行
- HTTP 長輪詢不維持長連線
- Webhook平台主動打你的端點
Public Beta 產品邊界
先把邊界說清楚，再決定適不適合。
投遞語義
不提供 exactly-once。SSE、WebSocket 與 Webhook 為至少送達一次；HTTP 長輪詢為至多一次。官方 SDK 會依 partition cursor 去重。
單一機房 · RF=1
部署在台灣單一機房，Kafka 採單副本。磁碟或 broker 故障時，保留期內的訊息可能永久遺失。
SSE 是有界重播
補回受保留期與單次 5,000 則上限約束。超出時會收到 msgmesh-resync，應用需自行從業務系統重建狀態；平台沒有快照。
保留期限
Free 保留 3 天；Paid 保留 30 天。兩者都不是永久事件儲存。
room 的適用範圍
適用於發布、SSE／WebSocket 訂閱，以及帶 room 的歷史查詢。HTTP 長輪詢以整個 topic 為單位，在線人數也是整個 topic 的彙總。
死信只收 Webhook
死信佇列只處理 Webhook 投遞失敗。publish 失敗與長輪詢消費失敗都不會進去。
如果事件會直接影響付款、庫存或其他核心交易，請先評估 RF=1 與單一機房是否符合你的風險要求。