实时通信架构模式

本文引用的文件
- websocket_ingress_runtime.v - websocket_runtime.v - dispatch_session.v - hub_runtime.v - runtime.v - types.v - inproc_vjsx_websocket_affinity_runtime.v - inproc_vjsx_websocket_affinity_state.v - 12-advanced-patterns.md - WEBSOCKET_MVP_PLAN.md - WEBSOCKET_PHASE2_IMPLEMENTATION_PLAN.md

引言

本文件面向在 vhttpd 上构建实时应用的工程师，系统化梳理 WebSocket 长连接管理、房间系统、消息广播、会话亲和性与负载均衡等核心模式。文档同时给出端到端调用序列、关键数据结构与状态机、以及聊天室、在线协作、实时监控等典型应用的设计要点与落地建议。

项目结构

vhttpd 的实时通信能力由“协议接入层 + 运行时上下文 + Hub 状态 + 执行器亲和性”四层构成： - 协议接入层：负责 HTTP Upgrade 到 WebSocket，建立并维护客户端与 worker 或 dispatch 模式的桥接。 - 运行时上下文：封装对 Hub 的操作（注册、加入/离开房间、广播、元数据）和命令执行。 - Hub 状态：进程内连接、房间、成员、元数据、待发送队列的统一管理。 - 执行器亲和性：为 vjsx 执行器提供基于策略的连接亲和与 Lane 绑定，支撑多实例下的路由与负载。

graph TB
Client["浏览器/客户端"] --> Ingress["WebSocket 接入<br/>websocket_ingress_runtime.v"]
Ingress --> RT["运行时上下文<br/>websocket_runtime.v"]
RT --> Hub["Hub 状态与广播<br/>ws/hub_runtime.v, ws/runtime.v"]
Ingress --> Dispatch["Dispatch 会话桥<br/>ws/dispatch_session.v"]
Ingress --> Executor["执行器亲和性<br/>executor/*_affinity*.v"]
Executor --> Worker["Worker/业务逻辑"]
Hub --> Worker

图表来源 - websocket_ingress_runtime.v:1-120 - websocket_runtime.v:1-115 - dispatch_session.v:1-120 - hub_runtime.v:1-120 - runtime.v:1-120 - inproc_vjsx_websocket_affinity_runtime.v:1-120

章节来源 - websocket_ingress_runtime.v:1-120 - WEBSOCKET_MVP_PLAN.md:1-63

核心组件

接入与桥接
HTTP 升级检测与握手接管，支持两种模式：
- 直通 worker 模式：将 TCP 连接交给 net.websocket，并在 worker 间通过帧协议转发。
- dispatch 模式：先向内核派发 open 事件，根据返回的命令列表决定是否接受连接并进入本地会话桥。
运行时上下文 RuntimeContext
统一暴露 register_conn、join/leave、set_meta/clear_meta、send_to、broadcast、presence、rooms、metadata、build_frame、dispatch_event、command_result、close_target 等方法。
Hub 状态 HubState
维护连接表、房间成员表、连接房间映射、连接元数据、待发送队列；提供 join/leave/broadcast/send_to/close_target 等原子操作。
连接生命周期状态机
定义 opening/open/closing/closed 四态，控制 can_send/can_queue/can_process_messages 等访问语义，避免竞态与重复关闭。
亲和性与负载均衡
支持从请求帧计算亲和键，按策略选择是否固定 Lane，维护 key→lane 映射与引用计数，支持迁移与释放。

章节来源 - websocket_ingress_runtime.v:279-411 - websocket_runtime.v:26-99 - hub_runtime.v:174-334 - runtime.v:24-133 - types.v:11-120 - inproc_vjsx_websocket_affinity_runtime.v:80-146

架构总览

下图展示一次典型的 WebSocket 打开流程，包括两种路径：worker 直通与 dispatch 模式。

sequenceDiagram
participant C as "客户端"
participant I as "接入层<br/>websocket_ingress_runtime.v"
participant R as "运行时上下文<br/>websocket_runtime.v"
participant H as "Hub 状态<br/>ws/hub_runtime.v"
participant D as "Dispatch 会话<br/>ws/dispatch_session.v"
participant W as "Worker/业务"
C->>I : "HTTP GET /ws?Upgrade=websocket"
I->>R : "build_websocket_runtime_context()"
alt "dispatch 模式"
I->>R : "dispatch_event(open)"
R-->>I : "accept=true + commands[]"
I->>D : "handle_dispatch_session(..., open_commands)"
D->>R : "register_conn(conn_id,...)"
D->>R : "flush_pending(conn_id)"
D-->>C : "101 Switching Protocols"
else "worker 直通模式"
I->>W : "open 帧"
W-->>I : "accept/close/error/done"
I->>R : "register_conn(conn_id,...)"
I-->>C : "101 Switching Protocols"
end

图表来源 - websocket_ingress_runtime.v:341-411 - websocket_runtime.v:96-99 - dispatch_session.v:11-48 - hub_runtime.v:174-215

详细组件分析

组件一：WebSocket 接入与桥接

职责
识别 Upgrade 请求，决定走 dispatch 还是 worker 直通。
建立 BridgeState，注册连接、处理消息与关闭事件。
将 worker 侧命令（send/join/broadcast/close 等）转换为实际网络写入或状态变更。
关键点
使用 ctx.takeover_conn() 接管 TCP 连接，交由 net.websocket 完成握手。
在 worker 模式下，通过帧编解码器与 worker 双向通信。
在 dispatch 模式下，先派发 open，再根据命令列表决定是否接受连接。

flowchart TD
Start(["收到 HTTP 请求"]) --> Check["检查是否为 WebSocket 升级"]
Check --> |否| Reject["返回 426/错误响应"]
Check --> |是| Mode{"是否启用 dispatch?"}
Mode --> |是| OpenFrame["构造 open 帧并派发"]
OpenFrame --> Accept{"是否 accept?"}
Accept --> |否| CloseResp["返回 403/自定义状态码"]
Accept --> |是| BuildSession["创建本地会话桥<br/>handle_dispatch_session"]
BuildSession --> Ready["注册连接并 flush 待发消息"]
Mode --> |否| ProxyToWorker["代理到 worker 直通模式"]
ProxyToWorker --> Ready
Ready --> End(["进入消息循环"])

图表来源 - websocket_ingress_runtime.v:16-30 - websocket_ingress_runtime.v:341-411 - dispatch_session.v:11-48

章节来源 - websocket_ingress_runtime.v:279-411 - dispatch_session.v:11-124

组件二：运行时上下文 RuntimeContext

职责
对外暴露统一的 Hub 操作接口，屏蔽底层锁与并发细节。
将命令结果（commands）转译为 send/join/broadcast/close 等动作。
关键点
presence/rooms/metadata 快照用于在派发时携带上下文信息。
build_frame 将业务帧包装为 WorkerWebSocketFrame。
command_result 驱动后续动作（如关闭目标连接）。

classDiagram
class RuntimeContext {
+dispatch_targets(room, except_id) []HubDispatchTarget
+presence(conn_id) PresenceSnapshot
+rooms(conn_id) []string
+metadata(conn_id) map[string]string
+register_conn(...)
+conn_open(conn_id) bool
+mark_closing(conn_id) bool
+flush_pending(conn_id) void
+cleanup_conn(conn_id) void
+unregister_conn(conn_id) void
+send_to(conn_id, data, opcode) bool
+join(conn_id, room) bool
+leave(conn_id, room) bool
+set_meta(conn_id, key, value) bool
+clear_meta(conn_id, key) bool
+broadcast(room, data, opcode, except_id) int
+build_frame(...) WorkerWebSocketFrame
+dispatch_event(frame) !WorkerWebSocketDispatchResponse
+command_result(commands) WorkerWebSocketDispatchCommandsResult
+followup_failure(...) ?WorkerWebSocketFrame
+close_target(conn_id, code, reason) void
}

图表来源 - websocket_runtime.v:26-99

章节来源 - websocket_runtime.v:26-99

组件三：Hub 状态与广播

职责
维护连接、房间、成员、元数据与待发送队列。
提供 send_to、broadcast、join/leave、presence 等原子操作。
关键点
写路径加互斥锁，读快照也加锁保证一致性。
pending 队列用于连接尚未就绪时的消息缓冲，待 conn_open 后 flush。
broadcast_dispatch 将广播转为对房间内每个连接的 dispatch 事件，便于复杂路由。

classDiagram
class HubState {
+mu sync.Mutex
+send_mu sync.Mutex
+conns map[string]HubConn
+room_members map[string]map[string]bool
+conn_rooms map[string]map[string]bool
+conn_meta map[string]map[string]string
+pending map[string][]HubPendingMessage
+register_conn(...)
+cleanup_conn(conn_id)
+conn_open(conn_id) bool
+mark_closing(conn_id) bool
+flush_pending(conn_id)
+unregister_conn(conn_id)
+join(conn_id, room) bool
+leave(conn_id, room) bool
+set_meta(conn_id, key, value) bool
+clear_meta(conn_id, key) bool
+presence_snapshot(conn_id) (room_members, member_metadata, room_counts, presence_users)
+rooms_snapshot(conn_id) []string
+meta_snapshot(conn_id) map[string]string
+send_client(conn_id, client, data, opcode) bool
}
class RuntimeContext
RuntimeContext --> HubState : "封装调用"

图表来源 - runtime.v:24-133 - hub_runtime.v:174-334 - types.v:361-377

章节来源 - runtime.v:24-133 - hub_runtime.v:174-334 - types.v:361-377

组件四：连接生命周期状态机

状态
opening → open → closing → closed
行为
can_send/can_queue/can_process_messages 控制不同阶段的读写权限。
begin_peer_close 区分对端发起与 worker 发起的关闭，避免重复通知。
mark_closing 与 begin_cleanup 确保清理只执行一次。

stateDiagram-v2
[*] --> opening
opening --> open : "mark_open()"
open --> closing : "begin_worker_close()/begin_peer_close()"
closing --> closed : "begin_cleanup()"
open --> closing : "mark_closing()"

图表来源 - types.v:11-120

章节来源 - types.v:11-120

组件五：亲和性与负载均衡

目标
在多 Lane/多实例环境下，保持同一会话的请求落在同一执行单元，提升缓存命中与状态一致性。
机制
从请求帧计算 affinity_key（可来自配置或应用层）。
should_pin_lane 决定是否固定 Lane；否则仅记录 key 以辅助路由。
维护 key→lane 映射与引用计数，支持迁移与释放。
适用场景
需要会话级状态（如协作文档、游戏房间）的应用。

flowchart TD
A["收到帧 frame.id"] --> B["读取已有关联 key"]
B --> C{"key 为空?"}
C --> |是| D{"source='app'?"}
D --> |是| E["调用应用层解析 key"]
D --> |否| F["按策略从帧字段计算 key"]
E --> G["得到 key"]
F --> G
G --> H{"should_pin_lane?"}
H --> |是| I["固定 lane 并记录映射"]
H --> |否| J["普通分配 lane，保留 key 以便下次复用"]
I --> K["返回 lane,key"]
J --> K

图表来源 - inproc_vjsx_websocket_affinity_runtime.v:80-146 - inproc_vjsx_websocket_affinity_state.v:6-42

章节来源 - inproc_vjsx_websocket_affinity_runtime.v:80-146 - inproc_vjsx_websocket_affinity_state.v:6-42

依赖关系分析

模块耦合
websocket_ingress_runtime.v 依赖 executor、ws、transport、net.websocket 等。
ws 内部解耦：RuntimeContext 作为薄封装，HubState 承载状态，types 定义共享类型。
亲和性模块独立于 ws，通过 executor 状态进行关联。
外部依赖
V 标准库 net.websocket 负责握手与帧收发。
transport.WorkerWebSocketFrame 作为跨进程/跨模块的消息载体。

graph LR
Ingress["websocket_ingress_runtime.v"] --> WSRT["websocket_runtime.v"]
Ingress --> Dispatch["ws/dispatch_session.v"]
WSRT --> HubRT["ws/hub_runtime.v"]
HubRT --> HubCore["ws/runtime.v"]
HubCore --> Types["ws/types.v"]
Ingress --> Affinity["executor/*_affinity*.v"]

图表来源 - websocket_ingress_runtime.v:1-120 - websocket_runtime.v:1-115 - dispatch_session.v:1-120 - hub_runtime.v:1-120 - runtime.v:1-120 - types.v:1-120 - inproc_vjsx_websocket_affinity_runtime.v:1-120

章节来源 - websocket_ingress_runtime.v:1-120 - websocket_runtime.v:1-115 - dispatch_session.v:1-120 - hub_runtime.v:1-120 - runtime.v:1-120 - types.v:1-120 - inproc_vjsx_websocket_affinity_runtime.v:1-120