ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

ErisPulse.Core.Bases.websocket 模块


模块概述

ErisPulse WebSocket 共享基类

定义客户端和服务端 WebSocket 连接的统一抽象接口。 send/receive/iter 方法签名在两端保持一致,具体实现由子类提供。

提示

  1. 客户端和服务端 WebSocket 共享相同的 send/receive/iter 接口
  2. iter_text/iter_bytes/iter_json 自动在断开时停止迭代
  3. 通过 on_disconnect/on_error 注册生命周期回调
  4. 连接池身份(id/namespace/owner/groups)由 _ConnectionIdentity 混入提供

类列表

class WSMessage

WebSocket 消息抽象

统一的 WebSocket 消息类型,不依赖底层库的消息类型。 用于客户端 WebSocket 的低级消息接收。

示例:

async for msg in ws.iter_messages():
    if msg.type == WSMessage.TEXT:
        print(msg.data)
    elif msg.type == WSMessage.CLOSE:
        break

方法列表

__init__(type: str, data: Any = None)
  • type (str): 消息类型 (WSMessage.TEXT / BINARY / CLOSE / ERROR)
  • data (Any): 消息数据

class _ConnectionIdentity

连接池身份混入

提供连接在 ErisPulse.connections 注册表中登记后的身份信息 (id / namespace / owner / kind / meta / groups)与业务分组操作。 分组的真相源在 ConnectionManager,本混入仅持有只读快照; close 的关闭权归创建者 owner,跨模块共享时仅允许发送与分组操作。

内部方法 WebSocketConnectionBase(服务端/客户端 WS)与 SseEmitter 共用

方法列表

__init__(*, connection_id: str = '', namespace: str = '', owner: str = '', kind: str = '')
  • connection_id (str): 连接池分配的连接 id(未登记时为空串)
  • namespace (str): 服务端路由命名空间(客户端连接为空)
  • owner (str): 归属 owner(模块名 / 平台名),拥有关闭权
  • kind (str): 连接种类("server" / "client" / "sse")

id -> str(property)

连接 id

连接池分配的全局唯一标识,形如 "{namespace}:{hex}"; 未登记的连接为空串。

返回值 (str): 连接 id


namespace -> str(property)

服务端路由命名空间(即注册路由的模块名 / 平台名)

返回值 (str): 命名空间,客户端出站连接为空串


owner -> str(property)

连接归属 owner(模块名 / 平台名)

owner 拥有关闭权;模块卸载时其名下连接由框架统一关闭。

返回值 (str): 归属标识


kind -> str(property)

连接种类

返回值: str "server"(服务端 WS)/ "client"(客户端出站 WS)/ "sse"(SSE 长连接)


meta -> dict[str, Any](property)

业务元数据(自由字典)

业务可在连接存活期内写入任意标注(如用户身份、租户号), 连接断开时随连接一并丢弃。

返回值 (dict): 元数据字典(原对象,非拷贝)


groups -> frozenset[str](property)

当前加入的业务分组

返回值 (frozenset): 分组名集合(只读快照)


_set_conn_groups(groups: frozenset[str]) -> None

内部方法 由连接池维护的分组快照回写(分组真相源在 ConnectionManager)


join_group(*groups: str) -> None

加入业务分组

分组命名完全由业务约定(房间 / 租户 / 主题……),框架不约束格式; 连接断开时自动退出全部分组。等价于 connections.assign(self.id, *groups)。

  • groups (str): 一个或多个分组名

示例:

@router.ws("MyModule", "/ws")
async def handle(ws: WebSocketConnection):
    ws.join_group("room:1")

leave_group(*groups: str) -> None

离开业务分组

  • groups (str): 一个或多个分组名

_check_close_permission() -> None

内部方法 关闭权校验:运行时上下文可归因且 ≠ 连接 owner 时拒绝。

上下文为空(框架内部路径 / 未归因的老代码)一律放行,保证向后兼容。


class WebSocketConnectionBase(_ConnectionIdentity)

WebSocket 连接共享基类

定义客户端和服务端 WebSocket 连接的统一接口。 send/receive 由子类实现,iter 方法提供基于 receive 的默认实现。

提示

  1. 通过 .raw 属性可访问底层框架原生对象
  2. 服务端和客户端共享此基类,接口一致
  3. 使用 on_disconnect/on_error 注册生命周期回调
  4. close 默认校验归属权限,框架内部路径用 close(force=True) 绕过

示例:

# 服务端和客户端共享相同的接口
await ws.send_text("Hello")
async for msg in ws.iter_text():
    await ws.send_text(f"Echo: {msg}")

方法列表

__init__(ws, *, connection_id: str = '', namespace: str = '', owner: str = '', kind: str = '')
  • ws (object): 底层框架 WebSocket 对象
  • connection_id (str): 连接池分配的连接 id(未登记时为空串)
  • namespace (str): 服务端路由命名空间(客户端连接为空)
  • owner (str): 归属 owner(模块名 / 平台名),拥有关闭权
  • kind (str): 连接种类("server" / "client")

url -> Any(property)

连接 URL

返回值: object URL 对象


headers -> Any(property)

请求头

返回值: object Headers 对象


raw -> Any(property)

底层框架原生对象

返回值 (object): 原生 WebSocket 实例


async send_text(data: str) -> None

发送文本消息

  • data (str): 文本内容

async send_bytes(data: bytes) -> None

发送二进制消息

  • data (bytes): 二进制内容

async send_json(data: Any, mode: str = 'text') -> None

发送 JSON 消息

  • data (Any): 要序列化的数据
  • mode (str): 发送模式 ("text" 或 "binary") (默认: "text")

async receive_text() -> str

接收文本消息

返回值 (str): 文本内容

异常: WebSocketDisconnect - 连接断开时


async receive_bytes() -> bytes

接收二进制消息

返回值 (bytes): 二进制内容

异常: WebSocketDisconnect - 连接断开时


async receive_json(mode: str = 'text') -> Any

接收 JSON 消息

  • mode (str): 接收模式 ("text" 或 "binary") (默认: "text")

返回值 (Any): 解析后的 JSON 数据

异常: WebSocketDisconnect - 连接断开时


async iter_text() -> AsyncIterator[str]

迭代文本消息直到断开

返回值: async generator 逐条返回文本消息


async iter_bytes() -> AsyncIterator[bytes]

迭代二进制消息直到断开

返回值: async generator 逐条返回二进制消息


async iter_json() -> AsyncIterator[Any]

迭代 JSON 消息直到断开

返回值: async generator 逐条返回 JSON 数据


async close(code: int = 1000, reason: str | None = None, *, force: bool = False) -> None

关闭 WebSocket 连接(默认校验归属权限)

非 owner 模块关闭他人连接时抛出 :class:~ErisPulse.Core.Bases.errors.ConnectionPermissionError; 运行时上下文为空(框架内部路径 / 未归因代码)时放行。

  • code (int): 关闭码 (默认: 1000)
  • reason (str | None): 关闭原因 (可选)
  • force (bool): 跳过权限校验(框架内部回收路径使用)

异常: ConnectionPermissionError - 跨 owner 关闭且未 force 时


async _close(code: int = 1000, reason: str | None = None) -> None

实际关闭动作(子类实现,绕过权限层)

  • code (int): 关闭码
  • reason (str | None): 关闭原因

on_disconnect(handler: Callable | None = None) -> Callable

注册断开连接回调

可作为装饰器或直接调用。

  • handler (Callable): 断开连接时的回调函数,签名: (ws, reason="") -> None

示例:

@ws.on_disconnect
async def handle_disconnect(ws, reason="unknown"):
    print(f"Disconnected: {reason}")

on_error(handler: Callable | None = None) -> Callable

注册错误回调

  • handler (Callable): 发生错误时的回调函数,签名: (ws, error="") -> None

示例:

@ws.on_error
async def handle_error(ws, error=""):
    print(f"Error: {error}")