連接池與廣播
Tip
什麼時候需要讀這篇:需要 WebSocket/SSE 連接池、廣播分組、跨模組推送或查看連接時。不需要則跳過,不影響其它功能的使用。
讀完你會知道:三種連接如何自動登記進註冊表、分組訂閱與廣播 API、 跨模組復用與關閉權歸屬,以及模組卸載時連接的清理語義。
本篇不涉及:WebSocket / SSE 路由的註冊寫法與連接生命週期鉤子 (見路由管理器);客戶端 HTTP 請求(見網路客戶端)。
連接(伺服端 WebSocket / SSE / 客戶端出站 WebSocket)在 ErisPulse 中是框架級一等資源:
隨連接建立自動登記進統一註冊表,支援廣播、業務分組訂閱與跨模組傳遞/復用,
模組卸載時由框架自動關閉回收——業務不再自建 _ws_clients 集合,也不會因忘記清理而洩漏。
本文件範例均為根導入寫法(2.10+ 推薦):
from ErisPulse import connections, router, client, WebSocketConnection
概述
from ErisPulse import connections, router, WebSocketConnection
# 伺服端:連接自動登記,handler 內加入業務分組
@router.ws("MyModule", "/ws")
async def handle(ws: WebSocketConnection):
ws.join_group("room:1") # 分組命名完全由業務約定
async for msg in ws.iter_text():
... # 斷開時框架自動註銷、清理分組
# 任意位置:向分組廣播(返回成敗明細)
result = await connections.broadcast({"type": "notify"}, group="room:1")
if not result.ok:
... # result.failed: {連接id: 異常}
三種連接統一進入註冊表:
| kind | 來源 | 歸屬 owner | 說明 |
|---|---|---|---|
server |
@router.ws(...) / register_websocket(...) |
註冊路由的模組名 | 斷開自動註銷 |
sse |
@router.sse(...) / register_sse(...) |
註冊路由的模組名 | 廣播走 sse.send() |
client |
await client.ws_connect(url) |
當前模組(或顯式 owner=) |
關閉/遠端斷開自動註銷;適配器停止時框架統一關閉 |
不想要自動登記時:路由傳 track=False,出站連接傳 track=False,舊程式碼行為完全不變。
查看連接池
from ErisPulse import connections
# 查看某模組的連接池("某模組現在有幾條活連接")
conns = connections.list(namespace="Dashboard")
for conn in conns:
print(conn.id, conn.kind, conn.groups, conn.meta)
# 按其它維度過濾(各條件 AND)
connections.list(owner="MyAdapter", kind="client")
connections.list(group="tenant:acme")
# 全域統計(各維度計數)
stats = connections.stats()
# {'total': 5, 'by_kind': {...}, 'by_namespace': {...}, 'by_owner': {...}, 'groups': {...}}
# 歸屬權審計計數(ownership 門面同樣可見)
from ErisPulse import ownership
ownership.counts("Dashboard") # {'connections': 3, ...}
每條連接可讀的身份資訊:conn.id(形如 Dashboard:1a2b3c4d)、conn.namespace、
conn.owner、conn.kind、conn.groups、conn.meta(業務自由字典)。
廣播與訂閱
分組(訂閱模型)
分組是扁平字串,命名完全由業務約定(房間 / 租戶 / 主題……),
巢狀層級用命名約定表達(如 tenant:acme/room:1),框架不約束格式。
兩個方向都可以操作:
# 方向一:連接側主動加入/退出(handler 內)
@router.ws("Chat", "/ws")
async def handle(ws: WebSocketConnection):
ws.join_group("room:1") # 等價 connections.assign(ws.id, "room:1")
ws.leave_group("room:1")
# 方向二:管理側被動分配(路由側 / 其它模組)
connections.assign(conn_id, "tenant:acme")
connections.dismiss(conn_id, "tenant:acme") # 不傳分組名 = 退出全部分組
連接斷開時自動退出全部分組,無需業務清理。
廣播
result = await connections.broadcast(
data, # WS 走 send_json;SSE 走 send(自動 JSON 序列化)
namespace="Dashboard", # 按命名空間過濾
group="room:1", # 按分組過濾
kind="sse", # 按連接種類過濾
owner="MyAdapter", # 按歸屬過濾
ids={conn_id, ...}, # 顯式指定候選集(過濾條件仍生效)
exclude={conn_id}, # 排除某些連接
timeout=10.0, # 單條連接發送逾時(非總時長)
concurrency=64, # 並發發送上限
raise_on_error=False, # True 時有失敗項則拋出首個異常
)
result.total # 目標連接總數(排除前)
result.sent # 成功的連接 id 列表
result.failed # {連接 id: 異常物件}(逾時/已斷開/發送失敗)
result.excluded # 被排除的連接 id
result.ok # 是否全部送達
過濾條件之間是 AND;單條失敗不影響其它連接;ids 中已不存在的連接會計入
failed(讓業務知道全貌)。
生命週期事件
連接登記/註銷/分組變化會發射標準生命週期事件,Dashboard 等可訂閱做即時呈現:
from ErisPulse import lifecycle
@lifecycle.on("connection.registered")
async def on_registered(data): ...
@lifecycle.on("connection.unregistered")
async def on_unregistered(data): ...
@lifecycle.on("connection.group.joined")
async def on_joined(data): ...
@lifecycle.on("connection.group.left")
async def on_left(data): ...
跨模組傳遞 / 復用
連接是框架登記的資源,任何模組都可以透過連接 id 拿到它並復用—— 不需要自己再建一條,也不需要知道連接是誰建的:
from ErisPulse import connections
conn = connections.get("Dashboard:1a2b3c4d") # 不存在/已斷開拋 ConnectionNotFoundError
await conn.send_json({"ping": 1}) # 任何模組都可發送
conn.join_group("someone-elses-room") # 也可參與分組
歸屬與關閉權:
- 連接的
owner(建立它的模組)獨占關閉權。非 owner 呼叫close()拋ConnectionPermissionError(from ErisPulse import ConnectionPermissionError); - 發送與分組操作對所有模組開放,不需要授權;
- owner 模組卸載 / 適配器停止時,框架統一關閉並註銷其名下全部連接
(伺服端 + 出站),已拿到的引用再發送會得到失敗結果,監聽
connection.unregistered事件可感知; - 框架內部回收路徑用
close(force=True)繞過驗證。
歸因說明:關閉權驗證依賴執行時 owner 上下文(
owner_scope/ 事件分發 /spawn_background等自動攜帶)。上下文不可歸因的呼叫(未歸因的舊程式碼)會放行, 保證 0 破壞;新程式碼在 owner 上下文中呼叫即受保護。
出站連接(Client 側)
from ErisPulse import client
ws = await client.ws_connect("wss://example.com/ws")
ws.id # 已登記,可被 connections 查詢/廣播
ws.owner # 當前模組(owner 上下文不可用時建議顯式傳)
# owner 上下文不可用(如工具執行緒回呼)時顯式指定,卸載才能自動回收:
ws = await client.ws_connect("wss://example.com/ws", owner="MyAdapter")
遠端主動斷開、本地 close() 都會自動註銷登記;模組卸載時框架關閉其名下
全部出站連接。等舊程式碼裸建連接各自管理、忘記清理導致洩漏的日子到此為止。
跨執行緒投遞
從子執行緒觸達連接(廣播 / 推送 / 關閉)時,用框架標準工具投遞回主迴圈,
**不要手寫 run_coroutine_threadsafe**:
from ErisPulse import run_main_loop, spawn_later, spawn_thread
# 子執行緒阻塞取結果:
run_main_loop(connections.broadcast({"tick": 1}, group="room:1"), timeout=5)
# 背景執行緒 + 延遲任務(owner 歸屬,卸載自動取消):
def push_tick():
return connections.broadcast({"tick": 1}, group="room:1")
spawn_later(30, push_tick, owner="MyModule")
卸載與清理語義
模組卸載 / 適配器停止的歸屬權回收鏈會依序:取消歸屬背景任務與計時器 → 關閉並註銷歸屬連接 → 觸發 on_cleanup 鉤子 → 註銷路由/處理器等註冊類資源。 詳見 歸屬權(owner)系統。
Warning
2.10 起,模組卸載會關閉其名下登記的 WS/SSE/出站連接。依賴「卸載後連接仍存活」的 下游元件(如舊版 Dashboard 推送)需知悉——這是杜絕連接洩漏的預期行為。
API 一覽
| API | 說明 |
|---|---|
connections.get(id) |
取連接(跨模組入口),不存在拋 ConnectionNotFoundError |
connections.list(namespace=, owner=, group=, kind=) |
過濾查詢連接列表 |
connections.stats(namespace=, owner=) |
各維度計數統計 |
connections.assign(id, *groups) / dismiss(id, *groups) |
管理側加入/移出分組 |
await connections.broadcast(data, ...) |
廣播,返回 BroadcastResult |
await connections.close(id, force=False) |
關閉並註銷(權限驗證) |
await connections.close_owner(owner) |
關閉註銷某 owner 名下全部連接(框架卸載鏈呼叫) |
conn.join_group(*groups) / conn.leave_group(*groups) |
連接側分組 |
conn.send_json / send_text / iter_text / ... |
收發(伺服端/客戶端介面一致) |
conn.meta |
業務元資料字典 |
conn.close(force=False) |
關閉(非 owner 拋 ConnectionPermissionError) |
相關文件
- 註冊伺服端 WS / SSE 路由 → 路由管理器
- 建立客戶端出站 WebSocket → 網路客戶端
- 模組卸載時連接如何被回收 → 歸屬權(owner)系統
- 連接相關異常(
ConnectionNotFoundError/ConnectionPermissionError) → 異常體系與捕獲指南