267 lines
13 KiB
Go
267 lines
13 KiB
Go
package wsgateway // 包名声明：服务端连接对象，属于传输层
|
|
|
|
import (
|
|
"context" // 标准库：连接的生命周期上下文，关闭即取消
|
|
"errors" // 标准库：用 errors.Is 判断上下文取消、连接关闭等错误
|
|
"log/slog" // 标准库：结构化日志，记录异常读写与限流踢线
|
|
"net" // 标准库：net.ErrClosed 用于识别「连接已关闭」类错误
|
|
"sync" // 标准库：Mutex 保护活跃时间与限流计数，Once 保证关闭幂等
|
|
"time" // 标准库：超时时间、心跳周期、限流窗口都依赖时间
|
|
|
|
"git.lzcwy.cn/zhengchiliu/zt-online-game-backend/global" // 本项目：读取 global.WSSetting 的传输层参数
|
|
"github.com/coder/websocket" // 第三方：coder/websocket，负责帧读写、ping、关闭
|
|
)
|
|
|
|
// pongWait 返回「多久没收到消息就判死」的时长，对应配置的 ReadTimeout。
|
|
func pongWait() time.Duration {
|
|
if global.WSSetting != nil && global.WSSetting.ReadTimeout > 0 { // 配置存在且为正数
|
|
return time.Duration(global.WSSetting.ReadTimeout) * time.Second // 按配置（秒）换算为 Duration
|
|
}
|
|
return 60 * time.Second // 配置缺失时的兜底值，避免 0 值导致连接立刻被判死
|
|
}
|
|
|
|
// writeWait 返回单次写或 ping 的超时时长，对应配置的 WriteTimeout。
|
|
func writeWait() time.Duration {
|
|
if global.WSSetting != nil && global.WSSetting.WriteTimeout > 0 { // 配置存在且为正数
|
|
return time.Duration(global.WSSetting.WriteTimeout) * time.Second // 按配置换算
|
|
}
|
|
return 10 * time.Second // 兜底 10 秒
|
|
}
|
|
|
|
// pingPeriod 返回服务端主动 ping 的周期，对应配置的 PingInterval。
|
|
func pingPeriod() time.Duration {
|
|
if global.WSSetting != nil && global.WSSetting.PingInterval > 0 { // 配置存在且为正数
|
|
return time.Duration(global.WSSetting.PingInterval) * time.Second // 按配置换算
|
|
}
|
|
return 25 * time.Second // 兜底 25 秒
|
|
}
|
|
|
|
// queueSize 返回发送队列长度，对应配置的 SendQueueSize。
|
|
func queueSize() int {
|
|
if global.WSSetting != nil && global.WSSetting.SendQueueSize > 0 { // 配置存在且为正数
|
|
return global.WSSetting.SendQueueSize // 使用配置值
|
|
}
|
|
return 64 // 兜底 64 条
|
|
}
|
|
|
|
// Connection 表示服务端持有的一条 WebSocket 连接（不是客户端）。
|
|
// 每条连接由两个 goroutine 驱动：ReadPump 收、WritePump 发，中间用 send 队列解耦。
|
|
//
|
|
// 说明：coder/websocket 会自动应答协议级 ping 帧，但该应答对 Read 不可见，
|
|
// 因此「死连接」判定由 WritePump 侧的空闲检查负责。
|
|
type Connection struct {
|
|
hub *Hub // 所属 Hub：用于注销自己、以及业务层反向查找
|
|
conn *websocket.Conn // 底层 ws 连接句柄：真正的帧读写入口
|
|
userID int64 // 该连接归属的用户 ID：由建连时的 JWT 解析得到
|
|
|
|
send chan []byte // 发送队列：业务侧只入队，写 goroutine 负责真正发送
|
|
closed chan struct{} // 关闭信号：close 后所有 select 立即感知
|
|
once sync.Once // 关闭幂等：Close 可能被读泵、写泵、Hub 多处调用
|
|
ctx context.Context // 连接生命周期上下文：关闭时取消，供 handler 起的 goroutine 感知
|
|
cancel context.CancelFunc // 取消函数：Close 时调用，触发 ctx 取消
|
|
|
|
mu sync.Mutex // 保护下面三个字段（活跃时间、限流窗口起点、限流计数）
|
|
lastActive time.Time // 最近一次收到客户端消息的时间：判死连接用
|
|
winStart time.Time // 限流窗口起点：每秒重置一次
|
|
winCount int // 当前窗口内已收到的消息数
|
|
}
|
|
|
|
// NewConnection 为一条已升级的连接创建对象。
|
|
func NewConnection(hub *Hub, conn *websocket.Conn, userID int64) *Connection {
|
|
ctx, cancel := context.WithCancel(context.Background()) // 以根 context 派生可取消的连接上下文
|
|
return &Connection{
|
|
hub: hub, // 绑定所属 Hub
|
|
conn: conn, // 保存底层连接
|
|
userID: userID, // 保存用户 ID
|
|
send: make(chan []byte, queueSize()), // 按配置创建带缓冲的发送队列
|
|
closed: make(chan struct{}), // 创建关闭信号通道
|
|
ctx: ctx, // 保存上下文
|
|
cancel: cancel, // 保存取消函数，供 Close 调用
|
|
lastActive: time.Now(), // 初始活跃时间为当前时间，避免刚连上就被判死
|
|
}
|
|
}
|
|
|
|
// UserID 返回该连接对应的用户 ID。
|
|
func (c *Connection) UserID() int64 {
|
|
return c.userID // 直接返回建立连接时保存的 ID
|
|
}
|
|
|
|
// Context 返回连接生命周期上下文：handler 内起 goroutine 时用它感知断连。
|
|
func (c *Connection) Context() context.Context {
|
|
return c.ctx // 返回内部上下文
|
|
}
|
|
|
|
// Send 把一条已编码的消息放入发送队列；队列满视为慢客户端并断开。
|
|
func (c *Connection) Send(data []byte) bool {
|
|
select {
|
|
case <-c.closed: // 连接已关闭
|
|
return false // 投递失败
|
|
default: // 未关闭则继续往下走，避免阻塞
|
|
}
|
|
|
|
select {
|
|
case c.send <- data: // 尝试入队成功
|
|
return true // 投递成功
|
|
case <-c.closed: // 入队期间连接被关闭
|
|
return false // 投递失败
|
|
default: // 队列已满：说明客户端消费跟不上
|
|
slog.WarnContext(c.ctx, "ws send queue full, close slow client", "user_id", c.userID) // 记录慢客户端日志
|
|
c.Close() // 主动断开，避免内存被堆积消息撑爆
|
|
return false // 投递失败
|
|
}
|
|
}
|
|
|
|
// SendEnvelope 把信封编码后入队发送。
|
|
func (c *Connection) SendEnvelope(typ string, seq int64, payload any) bool {
|
|
data, err := Encode(typ, seq, payload) // 先序列化为 JSON 字节
|
|
if err != nil { // 序列化失败（payload 含不可序列化字段）
|
|
slog.ErrorContext(c.ctx, "ws encode envelope failed", "type", typ, "error", err) // 记录错误日志
|
|
return false // 发送失败
|
|
}
|
|
return c.Send(data) // 入队发送
|
|
}
|
|
|
|
// SendError 便捷地发一条错误下行消息。
|
|
func (c *Connection) SendError(seq int64, code int, msg string) bool {
|
|
return c.SendEnvelope(TypeError, seq, ErrorPayload{Code: code, Msg: msg}) // 组装 ErrorPayload 并以 error 类型下发
|
|
}
|
|
|
|
// Close 关闭连接，多处调用只生效一次。
|
|
func (c *Connection) Close() {
|
|
c.once.Do(func() { // 用 Once 保证幂等，避免重复 close 通道 panic
|
|
close(c.closed) // 广播关闭信号，读写泵立即退出
|
|
c.cancel() // 取消连接上下文，通知所有派生 goroutine
|
|
_ = c.conn.Close(websocket.StatusNormalClosure, "") // 以正常关闭状态码关闭底层连接，忽略返回错误
|
|
})
|
|
}
|
|
|
|
// touch 把活跃时间刷新为当前时间，表示刚收到客户端消息。
|
|
func (c *Connection) touch() {
|
|
c.mu.Lock() // 加锁：与 idleFor 共享字段
|
|
c.lastActive = time.Now() // 更新活跃时间
|
|
c.mu.Unlock() // 解锁
|
|
}
|
|
|
|
// idleFor 返回距上次收到消息已经过去多久。
|
|
func (c *Connection) idleFor() time.Duration {
|
|
c.mu.Lock() // 加锁读取
|
|
defer c.mu.Unlock() // 函数返回时解锁
|
|
return time.Since(c.lastActive) // 计算与当前时间的差值
|
|
}
|
|
|
|
// allow 做固定窗口限流：每秒消息数超过 MaxMsgPerSec 就返回 false。
|
|
func (c *Connection) allow() bool {
|
|
limit := 0 // 默认不限流
|
|
if global.WSSetting != nil { // 配置存在
|
|
limit = global.WSSetting.MaxMsgPerSec // 取配置的每秒上限
|
|
}
|
|
if limit <= 0 { // 未配置或配置为 0
|
|
return true // 不做限制
|
|
}
|
|
|
|
now := time.Now() // 取当前时间
|
|
c.mu.Lock() // 加锁：修改窗口计数
|
|
defer c.mu.Unlock() // 返回时解锁
|
|
|
|
if now.Sub(c.winStart) >= time.Second { // 距窗口起点已超过 1 秒
|
|
c.winStart = now // 开启新窗口
|
|
c.winCount = 0 // 计数归零
|
|
}
|
|
c.winCount++ // 本条消息计入当前窗口
|
|
return c.winCount <= limit // 未超过上限才放行
|
|
}
|
|
|
|
// ReadPump 是读循环：收帧 → 更新活跃时间 → 限流 → 解码 → 心跳 → 路由分发。
|
|
// 该函数阻塞运行，一旦返回就表示连接结束，defer 里完成注销与关闭。
|
|
func (c *Connection) ReadPump() {
|
|
defer func() { // 退出前必定执行清理
|
|
c.hub.Unregister(c) // 从 Hub 表中摘掉自己
|
|
c.Close() // 关闭连接（幂等）
|
|
}()
|
|
|
|
for { // 持续读取，直到出错或连接关闭
|
|
mt, data, err := c.conn.Read(c.ctx) // 阻塞读取一帧；coder/websocket 会自动应答协议级 ping，这里只拿到业务消息
|
|
if err != nil { // 读取出错：可能是正常关闭、上下文取消或对端异常断开
|
|
if !isNormalClose(err) { // 过滤掉正常关闭类错误，避免噪音日志
|
|
slog.WarnContext(c.ctx, "ws read error", "user_id", c.userID, "error", err) // 记录异常读错误
|
|
}
|
|
return // 退出读循环
|
|
}
|
|
|
|
if mt != websocket.MessageText { // 只接受文本帧（业务信封统一用 JSON 文本）
|
|
continue // 二进制帧直接忽略，继续读下一条
|
|
}
|
|
|
|
c.touch() // 收到消息：刷新活跃时间，避免被判死
|
|
if !c.allow() { // 超过每秒消息数上限
|
|
slog.WarnContext(c.ctx, "ws message rate exceeded", "user_id", c.userID) // 记录限流日志
|
|
c.SendError(0, 0, "消息频率超限") // 先回一条错误告知客户端
|
|
return // 再断开连接
|
|
}
|
|
|
|
env, err := Decode(data) // 把 JSON 字节解析成统一信封
|
|
if err != nil { // 信封格式不合法
|
|
c.SendError(0, 0, "消息格式错误: "+err.Error()) // 回错误但不断开，允许客户端继续尝试
|
|
continue // 继续读下一条
|
|
}
|
|
|
|
if env.Type == TypePing { // 应用层心跳
|
|
c.SendEnvelope(TypePong, env.Seq, nil) // 原样带回 seq 回一条 pong
|
|
continue // 心跳不进业务路由
|
|
}
|
|
|
|
// TODO(第二步)：大厅与房间的 handler 都从这里进入（hall.match / room.action 等）。
|
|
c.hub.Route(c.ctx, c, env) // 按类型分发给已注册的业务处理器
|
|
}
|
|
}
|
|
|
|
// WritePump 是写循环：发送队列 + 主动 ping 保活 + 空闲超时判死。
|
|
func (c *Connection) WritePump() {
|
|
ticker := time.NewTicker(pingPeriod()) // 按配置周期触发心跳与空闲检查
|
|
defer func() { // 退出前清理
|
|
ticker.Stop() // 停止定时器，避免泄漏
|
|
c.Close() // 关闭连接（幂等）
|
|
}()
|
|
|
|
for { // 循环处理三类事件
|
|
select {
|
|
case <-c.closed: // 连接被关闭
|
|
return // 退出写循环
|
|
|
|
case msg := <-c.send: // 有待发送的下行消息
|
|
ctx, cancel := context.WithTimeout(c.ctx, writeWait()) // 为本次写操作加超时，防止对端不读导致永久阻塞
|
|
err := c.conn.Write(ctx, websocket.MessageText, msg) // 写出一帧文本消息
|
|
cancel() // 立即释放超时上下文资源
|
|
if err != nil { // 写失败：连接多半已不可用
|
|
return // 退出写循环，由 defer 关闭
|
|
}
|
|
|
|
case <-ticker.C: // 心跳周期到点
|
|
if idle := c.idleFor(); idle > pongWait() { // 超过 ReadTimeout 未收到任何客户端消息
|
|
slog.InfoContext(c.ctx, "ws idle timeout, close connection",
|
|
"user_id", c.userID, "idle", idle.String()) // 记录判死日志
|
|
_ = c.conn.Close(websocket.StatusPolicyViolation, "idle timeout") // 以策略违规码关闭，告知对端原因
|
|
return // 退出写循环
|
|
}
|
|
ctx, cancel := context.WithTimeout(c.ctx, writeWait()) // 为 ping 加超时
|
|
err := c.conn.Ping(ctx) // 发送协议级 ping，探测链路与对端存活
|
|
cancel() // 释放上下文
|
|
if err != nil { // ping 失败：连接已死
|
|
return // 退出写循环
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// isNormalClose 判断错误是否属于「正常结束」，避免把正常断开记成异常告警。
|
|
func isNormalClose(err error) bool {
|
|
if err == nil { // 没有错误
|
|
return true // 视为正常
|
|
}
|
|
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) || errors.Is(err, net.ErrClosed) {
|
|
// 上下文被取消（我们主动关闭）、超时、或底层连接已关闭，都属于预期内的结束
|
|
return true // 视为正常
|
|
}
|
|
return websocket.CloseStatus(err) != -1 // 有明确关闭状态码说明是对端发起的正常关闭
|
|
}
|