# Tinode 协议详解

> 本文档详细介绍 Tinode 支持的所有通信协议，包括协议原理、消息格式、实现细节和使用方法。

---

## 目录

- [协议概述](#协议概述)
- [WebSocket 协议](#websocket-协议)
- [gRPC 协议](#grpc-协议)
- [长轮询协议](#长轮询协议)
- [HTTP 文件传输协议](#http-文件传输协议)
- [消息格式](#消息格式)
- [协议对比](#协议对比)

---

## 协议概述

Tinode 支持四种主要的通信协议：

| 协议 | 端点 | 用途 | 特点 |
|------|------|------|------|
| **WebSocket** | `/v0/channels` | 实时消息推送 | 双向通信、低延迟 |
| **gRPC** | `grpc_listen` 端口 | 高性能客户端通信 | 强类型、流式传输 |
| **长轮询** | `/v0/channels/lp` | 兼容性客户端 | HTTP 兼容、防火墙友好 |
| **HTTP** | `/v0/file/*` | 文件上传下载 | RESTful、大文件支持 |

### 协议架构图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              客户端层                                        │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
│  │ Web App   │  │  Android  │  │    iOS    │  │  CLI/Bot  │               │
│  │ (WS/LP)   │  │ (WS/gRPC) │  │ (WS/gRPC) │  │  (gRPC)   │               │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘               │
└────────┼──────────────┼──────────────┼──────────────┼──────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              协议层                                          │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
│  │ WebSocket │  │   gRPC    │  │Long Polling│  │   HTTP    │               │
│  │JSON/Text │  │ Protobuf  │  │ JSON/Text │  │Multipart │               │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘               │
└────────┼──────────────┼──────────────┼──────────────┼──────────────────────┘
         │              │              │              │
         ▼              ▼              ▼              ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              会话层                                          │
│  ┌───────────────────────────────────────────────────────────────────────┐ │
│  │                           Session Store                                 │ │
│  │                    (统一会话管理，协议无关)                              │ │
│  └───────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              业务层                                          │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐               │
│  │    Hub    │  │   Topic   │  │   User    │  │   Auth    │               │
│  │ 连接中心  │  │  消息路由 │  │  用户管理 │  │  认证模块 │               │
│  └───────────┘  └───────────┘  └───────────┘  └───────────┘               │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## WebSocket 协议

### 概述

WebSocket 是 Tinode 主要的实时通信协议，用于 Web 应用和移动应用的实时消息推送。

WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议，它通过 HTTP 升级握手建立连接，然后切换到 WebSocket 协议进行双向数据传输。

### 端点

```
ws://host:port/v0/channels
wss://host:port/v0/channels  (TLS)
```

---

### 协议层交互详解

#### 1. 握手阶段（HTTP Upgrade）

WebSocket 连接通过 HTTP Upgrade 机制建立：

```
客户端请求：
GET /v0/channels?apikey=xxx HTTP/1.1
Host: server.example.com
Upgrade: websocket                    ← 请求升级协议
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZQ==   ← 随机 Base64 值
Sec-WebSocket-Version: 13             ← 协议版本
Origin: https://example.com

服务器响应：
HTTP/1.1 101 Switching Protocols      ← 同意切换
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ... ← 根据Key计算出的验证值
```

**验证值计算**：

```
Sec-WebSocket-Accept = base64(sha1(Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))
```

#### 2. 数据帧格式

WebSocket 数据帧格式（RFC 6455）：

```
  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-------+-+-------------+-------------------------------+
 |F|R|R|R| opcode|M| Payload len |    Extended payload length    |
 |I|S|S|S|  (4)  |A|     (7)     |             (16/64)           |
 |N|V|V|V|       |S|             |   (if payload len==126/127)   |
 |1|2|3|4|       |K|             |                               |
 +-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
 |     Extended payload length continued...                       |
 +-------------------------------+-------------------------------+
 |                               |Masking-key (if MASK set)      |
 +-------------------------------+-------------------------------+
 | Masking-key (continued)       |          Payload Data         |
 +-------------------------------- - - - - - - - - - - - - - - - +
```

**关键字段**：

| 字段 | 位数 | 说明 |
|------|------|------|
| FIN | 1 | 是否为最后一帧（消息可能分多帧） |
| RSV1-3 | 3 | 保留位（用于扩展） |
| opcode | 4 | 帧类型 |
| MASK | 1 | 是否掩码（客户端必须掩码） |
| Payload len | 7+ | 数据长度 |

**Opcode 类型**：

| Opcode | 类型 | 说明 |
|--------|------|------|
| 0x0 | Continuation | 续帧（分片消息的后续部分） |
| 0x1 | Text | 文本帧（Tinode 使用此类型传输 JSON） |
| 0x2 | Binary | 二进制帧 |
| 0x8 | Close | 连接关闭 |
| 0x9 | Ping | 心跳请求 |
| 0xA | Pong | 心跳响应 |

#### 3. 心跳机制

WebSocket 协议层的 Ping/Pong 心跳：

```
客户端                                     服务器
    │                                         │
    │────── Ping 帧 (opcode=0x9) ────────────>│
    │                                         │
    │<───── Pong 帧 (opcode=0xA) ─────────────│
    │                                         │
```

Tinode 的心跳配置：

```go
const (
    writeWait   = 10 * time.Second              // 写操作超时
    pongWait    = idleSessionTimeout             // 等待 Pong 超时（默认 45 秒）
    pingPeriod  = 15 * time.Second               // 发送 Ping 周期（15 秒）
)
```

**心跳流程**：

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           WebSocket 心跳流程                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  服务器 writeLoop:                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ for {                                                               │   │
│  │   select {                                                          │   │
│  │     case <-ticker.C:        // 每 15 秒                             │   │
│  │       ws.WriteMessage(PingMessage, nil)  // 发送 Ping               │   │
│  │     case msg <- sess.send:  // 有消息待发送                          │   │
│  │       ws.WriteMessage(TextMessage, msg)   // 发送消息                │   │
│  │   }                                                                 │   │
│  │ }                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
│  服务器 readLoop:                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ ws.SetReadDeadline(time.Now().Add(pongWait))  // 设置读取超时        │   │
│  │                                                                     │   │
│  │ ws.SetPongHandler(func(string) error {      // 收到 Pong 时          │   │
│  │   ws.SetReadDeadline(time.Now().Add(pongWait))  // 重置超时          │   │
│  │   return nil                                                        │   │
│  │ })                                                                  │   │
│  │                                                                     │   │
│  │ for {                                                               │   │
│  │   _, raw, err := ws.ReadMessage()  // 读取消息                      │   │
│  │   sess.dispatchRaw(raw)            // 处理消息                      │   │
│  │ }                                                                   │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

#### 4. 消息分片

大消息会被分成多帧传输：

```
帧1: FIN=0, opcode=0x1, payload="Hello "
帧2: FIN=0, opcode=0x0 (continuation), payload="World "
帧3: FIN=1, opcode=0x0 (continuation), payload="!"
```

接收方根据 FIN 位判断消息是否完整。

#### 5. 连接关闭

正常关闭流程：

```
客户端                                     服务器
    │                                         │
    │────── Close 帧 (opcode=0x8) ───────────>│
    │      payload: 1000 (正常关闭)            │
    │                                         │
    │<───── Close 帧 (opcode=0x8) ────────────│
    │      payload: 1000                       │
    │                                         │
    │====== TCP 连接断开 =====================│
```

**状态码**：

| 状态码 | 说明 |
|--------|------|
| 1000 | 正常关闭 |
| 1001 | 端点离开 |
| 1002 | 协议错误 |
| 1003 | 不支持的数据类型 |
| 1008 | 策略违规 |
| 1011 | 服务器错误 |

---

### WebSocket vs 应用层

Tinode 在 WebSocket 之上有一套应用层协议：

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           协议层次结构                                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    应用层 (Tinode 协议)                              │   │
│  │                                                                     │   │
│  │  消息类型: {hi}, {login}, {sub}, {pub}, {get}, {set}, {del}...     │   │
│  │  数据格式: JSON 文本                                                 │   │
│  │  业务逻辑: 认证、订阅、消息路由、权限控制                             │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    WebSocket 协议层                                  │   │
│  │                                                                     │   │
│  │  帧类型: Text (0x1), Binary (0x2), Ping (0x9), Pong (0xA)          │   │
│  │  传输: 建立连接、心跳保活、分片传输、关闭连接                         │   │
│  │  特性: 掩码、压缩扩展                                                │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    TCP 传输层                                        │   │
│  │                                                                     │   │
│  │  可靠传输、流控制、拥塞控制                                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

**示例：发送一条聊天消息**

```
应用层 JSON:
{"pub": {"id": "msg123", "topic": "grpTechGroup", "content": "Hello!"}}

        │
        ▼
WebSocket 帧:
┌────────────────────────────────────────────────┐
│ FIN=1 | opcode=0x1 | MASK=1 | payload='...'   │
│ payload = {"pub": {"id": "msg123", ...}}       │
└────────────────────────────────────────────────┘

        │
        ▼
TCP 数据包:
[WebSocket 握手 + TLS 加密 + TCP 头 + IP 头]
```

---

### 消息流转完整流程

#### 前端发送消息

```javascript
// 1. 构造 JSON 消息
const message = {
  pub: {
    id: "msg123",
    topic: "grpTechGroup",
    content: "Hello World"
  }
};

// 2. 通过 WebSocket 发送
websocket.send(JSON.stringify(message));
```

#### 后端接收处理流程

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              消息流转全景图                                  │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ① WebSocket 帧到达                                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ TCP → WebSocket 帧 → JSON 文本                                       │   │
│  │ opcode=0x1, payload='{"pub":{"id":"msg123",...}}'                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ② hdl_websock.go: serveWebSocket()                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ • HTTP Upgrade 握手                                                  │   │
│  │ • 创建 Session                                                       │   │
│  │ • 启动 readLoop() + writeLoop()                                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ③ readLoop() 读取消息                                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ _, raw, err := sess.ws.ReadMessage()                                 │   │
│  │ // raw = []byte('{"pub":{"id":"msg123",...}}')                      │   │
│  │ sess.dispatchRaw(raw)                                                │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ④ dispatchRaw() 解析 JSON                                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ var msg ClientComMessage                                             │   │
│  │ json.Unmarshal(raw, &msg)                                            │   │
│  │ // msg.Pub = {Id: "msg123", Topic: "grpTechGroup", ...}             │   │
│  │ sess.dispatch(&msg)                                                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ⑤ dispatch() 路由到处理器                                                  │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ switch {                                                             │   │
│  │   case msg.Pub != nil:                                               │   │
│  │     handler = checkVers(checkUser(s.publish))                        │   │
│  │     msg.Id = msg.Pub.Id                                              │   │
│  │     msg.Original = msg.Pub.Topic                                     │   │
│  │ }                                                                    │   │
│  │ handler(msg)                                                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ⑥ publish() 业务处理                                                       │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ • 验证用户权限 (W)                                                    │   │
│  │ • 获取 Topic: hub.topicGet("grpTechGroup")                           │   │
│  │ • 发送到 Topic 消息通道: topic.clientMsg <- msg                      │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ⑦ Topic 处理并广播                                                         │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ • 生成消息 ID (lastID++)                                              │   │
│  │ • 存储到数据库                                                        │   │
│  │ • 遍历所有订阅者:                                                     │   │
│  │   for session := range topic.sessions {                              │   │
│  │     session.send <- ServerComMessage{Data: {...}}                    │   │
│  │   }                                                                  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    ▼                                        │
│  ⑧ writeLoop() 发送给客户端                                                 │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │ case msg := <-sess.send:                                             │   │
│  │   bits := json.Marshal(msg)                                          │   │
│  │   ws.WriteMessage(TextMessage, bits)                                 │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

### 连接流程

```
┌─────────┐                    ┌─────────┐
│ Client  │                    │ Server  │
└────┬────┘                    └────┬────┘
     │                              │
     │──── HTTP GET /v0/channels ──>│  WebSocket 握手
     │<─── HTTP 101 Switching ─────│
     │                              │
     │<─────── {ctrl} ──────────────│  服务器响应 (含 sid, ver)
     │                              │
     │─────── {hi} ────────────────>│  客户端握手
     │<─────── {ctrl} ──────────────│  握手确认
     │                              │
     │─────── {login} ─────────────>│  用户认证
     │<─────── {ctrl} ──────────────│  认证结果
     │                              │
     │─────── {sub} ───────────────>│  订阅话题
     │<─────── {ctrl} ──────────────│
     │<─────── {meta} ──────────────│  话题元数据
     │                              │
     │─────── {pub} ───────────────>│  发送消息
     │<─────── {ctrl} ──────────────│
     │<─────── {data} ──────────────│  消息推送
     │                              │
```

### 核心实现

**文件**: `server/hdl_websock.go`

#### 1. 连接升级

```go
// WebSocket 升级器配置
var upgrader = websocket.Upgrader{
    ReadBufferSize:    1024,
    WriteBufferSize:   1024,
    EnableCompression: globals.wsCompression,
    // 允许来自任意 Origin 的连接
    CheckOrigin: func(r *http.Request) bool { return true },
}

func serveWebSocket(wrt http.ResponseWriter, req *http.Request) {
    // 1. 验证 API Key
    if isValid, _ := checkAPIKey(getAPIKey(req)); !isValid {
        wrt.WriteHeader(http.StatusForbidden)
        return
    }

    // 2. 升级 HTTP 连接为 WebSocket
    ws, err := upgrader.Upgrade(wrt, req, nil)

    // 3. 创建新会话
    sess, count := globals.sessionStore.NewSession(ws, "")

    // 4. 启动读写循环
    go sess.writeLoop()  // 发送消息
    go sess.readLoop()   // 接收消息
}
```

#### 2. 读循环（接收消息）

```go
func (sess *Session) readLoop() {
    defer func() {
        sess.closeWS()
        sess.cleanUp(false)
    }()

    // 设置读取限制和超时
    sess.ws.SetReadLimit(globals.maxMessageSize)
    sess.ws.SetReadDeadline(time.Now().Add(pongWait))

    // Pong 处理器：收到 Pong 后重置超时
    sess.ws.SetPongHandler(func(string) error {
        sess.ws.SetReadDeadline(time.Now().Add(pongWait))
        return nil
    })

    for {
        // 读取客户端消息
        _, raw, err := sess.ws.ReadMessage()
        if err != nil {
            return
        }

        // 统计
        statsInc("IncomingMessagesWebsockTotal", 1)

        // 分发消息到业务层
        sess.dispatchRaw(raw)
    }
}
```

#### 3. 写循环（发送消息）

```go
func (sess *Session) writeLoop() {
    ticker := time.NewTicker(pingPeriod)  // 定时发送 Ping
    defer ticker.Stop()

    for {
        select {
        case msg := <-sess.send:
            // 发送消息到客户端
            if !sess.sendMessage(msg) {
                return
            }

        case <-ticker.C:
            // 发送 Ping 保持连接
            if err := wsWrite(sess.ws, websocket.PingMessage, nil); err != nil {
                return
            }

        case msg := <-sess.stop:
            // 关闭会话
            if msg != nil {
                wsWrite(sess.ws, websocket.TextMessage, msg)
            }
            return

        case topic := <-sess.detach:
            // 从话题分离
            sess.delSub(topic)
        }
    }
}
```

### 心跳机制

| 参数 | 值 | 说明 |
|------|-----|------|
| `writeWait` | 10秒 | 写操作超时 |
| `pongWait` | `idleSessionTimeout` | 等待 Pong 超时（默认 45 秒） |
| `pingPeriod` | 15 秒 | 发送 Ping 周期 |

### 消息格式

WebSocket 消息使用 **JSON 文本格式**：

```json
{
  "sub": {
    "id": "unique-id",
    "topic": "me",
    "get": {
      "what": "desc sub data"
    }
  }
}
```

### 配置项

| 配置项 | 说明 |
|--------|------|
| `listen` | WebSocket 监听地址 |
| `ws_compression` | 是否启用压缩 |
| `max_message_size` | 最大消息大小 |

---

## gRPC 协议

### 概述

gRPC 提供高性能、强类型的客户端通信，适合移动应用、CLI 工具和插件系统。

### 端点

```
host:grpc_listen_port
```

默认端口：`16060`

### 服务定义

**文件**: `pbx/model.proto`

#### Node 服务（客户端实现）

```protobuf
service Node {
    // 消息循环：双向流
    rpc MessageLoop(stream ClientMsg) returns (stream ServerMsg) {}

    // 大文件上传：客户端流
    rpc LargeFileReceive(stream FileUpReq) returns (FileUpResp) {}

    // 大文件下载：服务端流
    rpc LargeFileServe(FileDownReq) returns (stream FileDownResp) {}
}
```

#### Plugin 服务（插件实现）

```protobuf
service Plugin {
    // 消息管道：处理所有客户端消息
    rpc FireHose(ClientReq) returns (ServerResp) {}

    // 用户发现
    rpc Find(SearchQuery) returns (SearchFound) {}

    // 事件通知
    rpc Account(AccountEvent) returns (Unused) {}
    rpc Topic(TopicEvent) returns (Unused) {}
    rpc Subscription(SubscriptionEvent) returns (Unused) {}
    rpc Message(MessageEvent) returns (Unused) {}
}
```

### 核心实现

**文件**: `server/hdl_grpc.go`

#### 1. 消息循环

```go
func (*grpcNodeServer) MessageLoop(stream pbx.Node_MessageLoopServer) error {
    // 1. 创建新会话
    sess, count := globals.sessionStore.NewSession(stream, "")
    if p, ok := peer.FromContext(stream.Context()); ok {
        sess.remoteAddr = p.Addr.String()
    }

    defer func() {
        sess.closeGrpc()
        sess.cleanUp(false)
    }()

    // 2. 启动写循环
    go sess.writeGrpcLoop()

    // 3. 读循环
    for {
        in, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }

        // 统计
        statsInc("IncomingMessagesGrpcTotal", 1)

        // 分发消息
        sess.dispatch(pbCliDeserialize(in))
    }
}
```

#### 2. 服务器启动

```go
func serveGrpc(addr string, kaEnabled bool, tlsConf *tls.Config) (*grpc.Server, error) {
    lis, err := netListener(addr)

    var opts []grpc.ServerOption
    opts = append(opts, grpc.MaxRecvMsgSize(int(globals.maxMessageSize)))

    // TLS 配置
    if tlsConf != nil {
        opts = append(opts, grpc.Creds(credentials.NewTLS(tlsConf)))
    }

    // Keepalive 配置
    if kaEnabled {
        kepConfig := keepalive.EnforcementPolicy{
            MinTime:             1 * time.Second,
            PermitWithoutStream: true,
        }
        opts = append(opts, grpc.KeepaliveEnforcementPolicy(kepConfig))

        kpConfig := keepalive.ServerParameters{
            Time:    60 * time.Second,
            Timeout: 20 * time.Second,
        }
        opts = append(opts, grpc.KeepaliveParams(kpConfig))
    }

    srv := grpc.NewServer(opts...)
    pbx.RegisterNodeServer(srv, &grpcNodeServer{})

    go srv.Serve(lis)
    return srv, nil
}
```

### 消息类型

#### 客户端消息 (ClientMsg)

```protobuf
message ClientMsg {
    oneof Message {
        ClientHi hi = 1;         // 握手
        ClientAcc acc = 2;       // 账户
        ClientLogin login = 3;   // 登录
        ClientSub sub = 4;       // 订阅
        ClientLeave leave = 5;   // 离开
        ClientPub pub = 6;       // 发布
        ClientGet get = 7;       // 查询
        ClientSet set = 8;       // 更新
        ClientDel del = 9;       // 删除
        ClientNote note = 10;    // 通知
    }
    ClientExtra extra = 13;      // 额外参数
}
```

#### 服务器消息 (ServerMsg)

```protobuf
message ServerMsg {
    oneof Message {
        ServerCtrl ctrl = 1;     // 控制响应
        ServerData data = 2;     // 数据消息
        ServerPres pres = 3;     // 在线状态
        ServerMeta meta = 4;     // 元数据
        ServerInfo info = 5;     // 信息通知
    }
}
```

### 文件传输

#### 上传（客户端流）

```protobuf
message FileUpReq {
    string id = 1;              // 请求 ID
    Auth auth = 2;              // 认证信息
    string topic = 3;           // 所属话题
    FileMeta meta = 4;          // 文件元数据
    bytes content = 5;          // 文件内容（分块）
}

message FileUpResp {
    string id = 1;
    int32 code = 2;             // 状态码
    string text = 3;
    FileMeta meta = 4;
    string redir_url = 5;       // 重定向 URL
}
```

#### 下载（服务端流）

```protobuf
message FileDownReq {
    string id = 1;
    Auth auth = 2;
    string uri = 3;             // 文件 URI
    string if_modified = 4;     // ETag
}

message FileDownResp {
    string id = 1;
    int32 code = 2;
    string text = 3;
    FileMeta meta = 4;
    string redir_url = 5;
    bytes content = 6;          // 文件内容（分块）
}
```

### Keepalive 配置

| 参数 | 值 | 说明 |
|------|-----|------|
| `MinTime` | 1秒 | 客户端最小 Ping 间隔 |
| `PermitWithoutStream` | true | 允许无活动流时 Ping |
| `Time` | 60秒 | 服务端 Ping 间隔 |
| `Timeout` | 20秒 | Ping 超时时间 |

### 特殊功能

gRPC 协议支持 WebSocket 不支持的功能：

| 功能 | 说明 |
|------|------|
| **代理发送** | root 用户可代表其他用户发送消息 |
| **用户删除** | 完整删除用户账户 |
| **文件流式传输** | 高效的大文件传输 |

---

## 长轮询协议

### 概述

长轮询是 WebSocket 的兼容替代方案，适用于不支持 WebSocket 的环境（如老旧浏览器、严格防火墙）。

### 端点

```
POST/GET http://host:port/v0/channels/lp
```

### 工作原理

```
┌─────────┐                    ┌─────────┐
│ Client  │                    │ Server  │
└────┬────┘                    └────┬────┘
     │                              │
     │── POST /v0/channels/lp ────>│  创建会话
     │<── 201 Created + sid ───────│
     │                              │
     │── POST /v0/channels/lp ────>│  登录 (sid + {login})
     │<── {ctrl} ──────────────────│
     │                              │
     │── GET /v0/channels/lp?sid=X │  长轮询（等待消息）
     │                              │  (阻塞等待)
     │<── {data} ──────────────────│  有消息时返回
     │                              │
     │── GET /v0/channels/lp?sid=X │  继续轮询
     │<── (超时返回空) ─────────────│
     │                              │
```

### 核心实现

**文件**: `server/hdl_longpoll.go`

#### 1. 会话创建

```go
func serveLongPoll(wrt http.ResponseWriter, req *http.Request) {
    // 获取会话 ID
    sid := req.FormValue("sid")

    if sid == "" {
        // 创建新会话
        sess, count := globals.sessionStore.NewSession(wrt, "")
        sess.remoteAddr = getRemoteAddr(req)

        // 返回会话 ID
        wrt.WriteHeader(http.StatusCreated)
        pkt := NoErrCreated(req.FormValue("id"), "", now)
        pkt.Ctrl.Params = map[string]string{"sid": sess.sid}
        enc.Encode(pkt)
        return
    }

    // 获取已有会话
    sess = globals.sessionStore.Get(sid)
    if sess == nil {
        wrt.WriteHeader(http.StatusForbidden)
        enc.Encode(ErrSessionNotFound(now))
        return
    }

    // 处理请求
    if req.ContentLength != 0 {
        // 有消息体：读取并处理
        sess.readOnce(wrt, req)
        return
    }

    // 无消息体：长轮询等待
    sess.writeOnce(wrt, req)
}
```

#### 2. 消息读取

```go
func (sess *Session) readOnce(wrt http.ResponseWriter, req *http.Request) (int, error) {
    // 检查消息大小
    if req.ContentLength > globals.maxMessageSize {
        return http.StatusExpectationFailed, errors.New("request too large")
    }

    // 读取消息体
    raw, err := io.ReadAll(req.Body)
    if err == nil {
        sess.lock.Lock()
        statsInc("IncomingMessagesLongpollTotal", 1)
        sess.dispatchRaw(raw)
        sess.lock.Unlock()
        return 0, nil
    }
    return 0, err
}
```

#### 3. 长轮询等待

```go
func (sess *Session) writeOnce(wrt http.ResponseWriter, req *http.Request) {
    for {
        select {
        case msg := <-sess.send:
            // 有消息待发送
            sess.sendMessageLp(wrt, msg)
            return

        case <-time.After(pingPeriod):
            // 超时：返回空包
            wrt.Write([]byte{})
            return

        case msg := <-sess.stop:
            // 会话关闭
            globals.sessionStore.Delete(sess)
            if msg != nil {
                lpWrite(wrt, msg)
            }
            return

        case <-req.Context().Done():
            // HTTP 请求取消
            return
        }
    }
}
```

### HTTP 头设置

```go
// CORS 支持
wrt.Header().Set("Access-Control-Allow-Origin", "*")

// 禁用缓存
wrt.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
wrt.Header().Set("Pragma", "no-cache")
wrt.Header().Set("Expires", "0")

// 内容类型
wrt.Header().Set("Content-Type", "text/plain")
```

### 请求参数

| 参数 | 方法 | 说明 |
|------|------|------|
| `sid` | GET/POST | 会话 ID（创建后必需） |
| `id` | GET/POST | 客户端消息 ID |
| `apikey` | GET/POST/Header | API Key |

### 消息格式

与 WebSocket 相同，使用 JSON 文本格式。

---

## HTTP 文件传输协议

### 概述

HTTP 文件传输协议用于大文件的带外上传和下载，独立于主消息通道。

### 端点

| 端点 | 方法 | 用途 |
|------|------|------|
| `/v0/file/u` | POST | 文件上传 |
| `/v0/file/s/[id]` | GET | 文件下载 |

### 核心实现

**文件**: `server/hdl_files.go`

#### 1. 文件上传

```go
func largeFileReceiveHTTP(wrt http.ResponseWriter, req *http.Request) {
    // 1. 验证 API Key
    if isValid, _ := checkAPIKey(getAPIKey(req)); !isValid {
        writeHttpResponse(ErrAPIKeyRequired(now), nil)
        return
    }

    // 2. 认证检查
    authMethod, secret := getHttpAuth(req)
    uid, challenge, err := authFileRequest(authMethod, secret, req.FormValue("sid"), getRemoteAddr(req))

    // 3. 读取文件
    file, header, err := req.FormFile("file")

    // 4. 检测 MIME 类型
    buff := make([]byte, 512)
    file.Read(buff)
    mimeType := http.DetectContentType(buff)

    // 5. 创建文件定义
    fdef := &types.FileDef{
        Id:       store.Store.GetUidString(),
        User:     uid.String(),
        MimeType: mimeType,
    }

    // 6. 调用媒体处理器上传
    url, size, err := mh.Upload(fdef, file)

    // 7. 完成上传
    fdef, err = store.Files.FinishUpload(fdef, true, size)

    // 8. 返回结果
    params := map[string]string{"url": url}
    writeHttpResponse(NoErrParams(msgID, "", now, params), nil)
}
```

#### 2. 文件下载

```go
func largeFileServeHTTP(wrt http.ResponseWriter, req *http.Request) {
    // 1. 验证 API Key
    if isValid, _ := checkAPIKey(getAPIKey(req)); !isValid {
        writeHttpResponse(ErrAPIKeyRequired(now), err)
        return
    }

    // 2. 认证检查
    authMethod, secret := getHttpAuth(req)
    uid, challenge, err := authFileRequest(authMethod, secret, req.FormValue("sid"), getRemoteAddr(req))

    // 3. 调用媒体处理器下载
    fd, rsc, err := mh.Download(req.URL.String())
    defer rsc.Close()

    // 4. 设置响应头
    wrt.Header().Set("Content-Type", fd.MimeType)
    if asAttachment {
        wrt.Header().Set("Content-Disposition", "attachment")
    }

    // 5. 流式传输文件
    http.ServeContent(wrt, req, "", fd.UpdatedAt, rsc)
}
```

#### 3. gRPC 文件传输

```go
// 文件上传（gRPC）
func (*grpcNodeServer) LargeFileReceive(stream pbx.Node_LargeFileReceiveServer) error {
    // 接收第一个请求（包含元数据）
    req, err := stream.Recv()

    // 认证
    authMethod, secret := req.Auth.Scheme, req.Auth.Secret
    uid, challenge, err := authFileRequest(authMethod, secret, "", remoteAddr)

    // 创建管道用于流式读取
    reader, writer := io.Pipe()

    // 后台协程读取分块数据
    go func() {
        defer writer.Close()
        for {
            if req, err := stream.Recv(); err == nil {
                chunk := req.GetContent()
                writer.Write(chunk)
            }
        }
    }()

    // 上传到媒体处理器
    url, size, err := mh.Upload(fdef, reader)

    // 关闭并返回
    stream.SendAndClose(&pbx.FileUpResp{...})
}

// 文件下载（gRPC）
func (*grpcNodeServer) LargeFileServe(req *pbx.FileDownReq, stream pbx.Node_LargeFileServeServer) error {
    // 认证
    uid, challenge, err := authFileRequest(...)

    // 下载文件
    fd, rsc, err := mh.Download(req.GetUri())
    defer rsc.Close()

    // 分块发送
    resp.Content = make([]byte, 1024*1024*2)  // 2MB 缓冲
    for {
        n, err := rsc.Read(resp.Content)
        if err == io.EOF {
            break
        }
        resp.Content = resp.Content[:n]
        stream.Send(&resp)
    }
}
```

### 认证方式

HTTP 文件传输支持多种认证方式（按优先级）：

| 优先级 | 方式 | 格式 |
|--------|------|------|
| 1 | HTTP 头 | `Authorization: Basic base64(scheme:secret)` |
| 2 | URL 参数 | `?auth=basic&secret=xxx` |
| 3 | 表单值 | `auth=basic&secret=xxx` |
| 4 | Cookie | `auth=basic; secret=xxx` |
| 5 | 会话 ID | `sid=xxx`（已认证会话） |

### MIME 类型限制

允许的 MIME 类型前缀：

```go
var allowedMimeTypes = []string{
    "application/",
    "audio/",
    "font/",
    "image/",
    "text/",
    "video/",
}
```

其他类型自动转换为 `application/octet-stream`。

### 响应格式

#### 上传成功

```json
{
    "ctrl": {
        "code": 200,
        "text": "ok",
        "params": {
            "url": "/v0/file/s/abcdef12345.jpg",
            "expires": "2024-01-02T00:00:00.000Z"
        }
    }
}
```

#### 重定向（307）

某些情况下媒体处理器返回重定向：

```json
{
    "ctrl": {
        "code": 307,
        "text": "Temporary Redirect",
        "params": {
            "url": "https://s3.amazonaws.com/bucket/file.jpg"
        }
    }
}
```

### 文件垃圾回收

```go
func largeFileRunGarbageCollection(period time.Duration, blockSize int) chan<- bool {
    stop := make(chan bool)
    go func() {
        // 添加随机抖动避免集群节点同时运行
        period = (period >> 1) + (period >> 2) + time.Duration(rand.Intn(int(period>>1)))
        gcTicker := time.Tick(period)
        for {
            select {
            case <-gcTicker:
                // 删除未使用的文件
                store.Files.DeleteUnused(time.Now().Add(-time.Hour), blockSize)
            case <-stop:
                return
            }
        }
    }()
    return stop
}
```

---

## 消息格式

### 通用消息结构

所有协议共享相同的消息语义，只是序列化格式不同：

| 协议 | 序列化格式 | 特点 |
|------|-----------|------|
| WebSocket | JSON | 文本、易调试 |
| 长轮询 | JSON | 与 WebSocket 相同 |
| gRPC | Protobuf | 二进制、高效 |

### 消息类型总览

#### 客户端到服务端

| 消息 | 说明 | 用途 |
|------|------|------|
| `{hi}` | 握手 | 建立连接 |
| `{acc}` | 账户 | 创建/修改账户 |
| `{login}` | 登录 | 认证 |
| `{sub}` | 订阅 | 订阅话题 |
| `{leave}` | 离开 | 离开话题 |
| `{pub}` | 发布 | 发送消息 |
| `{get}` | 查询 | 获取数据 |
| `{set}` | 更新 | 修改数据 |
| `{del}` | 删除 | 删除数据 |
| `{note}` | 通知 | 临时通知 |

#### 服务端到客户端

| 消息 | 说明 | 用途 |
|------|------|------|
| `{ctrl}` | 控制响应 | 请求响应 |
| `{data}` | 数据消息 | 消息内容 |
| `{meta}` | 元数据 | 话题信息 |
| `{pres}` | 在线状态 | 状态变更 |
| `{info}` | 信息 | 转发的通知 |

---

## 协议对比

### 功能对比

| 功能 | WebSocket | gRPC | 长轮询 | HTTP |
|------|-----------|------|--------|------|
| 实时消息 | ✅ | ✅ | ⚠️ | ❌ |
| 双向通信 | ✅ | ✅ | ❌ | ❌ |
| 流式传输 | ❌ | ✅ | ❌ | ⚠️ |
| 文件传输 | ❌ | ✅ | ❌ | ✅ |
| 浏览器支持 | ✅ | ❌ | ✅ | ✅ |
| 防火墙友好 | ⚠️ | ❌ | ✅ | ✅ |
| 性能 | 高 | 最高 | 低 | 中 |
| 带宽效率 | 中 | 高 | 低 | 中 |

### 使用场景

| 场景 | 推荐协议 | 原因 |
|------|----------|------|
| Web 应用 | WebSocket | 实时性、浏览器原生支持 |
| 移动应用 | gRPC | 高性能、省流量 |
| CLI 工具 | gRPC | 强类型、易开发 |
| 聊天机器人 | gRPC | Plugin API、流式事件 |
| 老旧浏览器 | 长轮询 | 兼容性 |
| 严格防火墙环境 | 长轮询 | 纯 HTTP |
| 文件上传下载 | HTTP | 大文件支持 |

### 性能对比

| 指标 | WebSocket | gRPC | 长轮询 |
|------|-----------|------|--------|
| 连接建立 | ~50ms | ~30ms | ~100ms |
| 消息延迟 | ~10ms | ~5ms | ~100ms |
| CPU 占用 | 中 | 低 | 高 |
| 内存占用 | 中 | 低 | 中 |
| 带宽占用 | 中 | 低 | 高 |

---

## 附录

### 配置示例

```json
{
    "listen": ":6060",
    "grpc_listen": ":16060",
    "max_message_size": 262144,
    "idle_session_timeout": 45000,
    "ws_compression": true,

    "api_key_salt": "your-hmac-salt",
    "expvar": "/debug/vars"
}
```

### 调试技巧

#### 1. WebSocket 调试

使用浏览器控制台：

```javascript
const ws = new WebSocket('ws://localhost:6060/v0/channels');
ws.onopen = () => console.log('Connected');
ws.onmessage = (e) => console.log('Received:', e.data);
ws.send(JSON.stringify({hi: {ver: "0.22", ua: "test"}}));
```

#### 2. gRPC 调试

使用 `grpcurl` 工具：

```bash
# 列出服务
grpcurl -plaintext localhost:16060 list

# 调用方法
grpcurl -plaintext -d '{"hi": {"ver": "0.22"}}' localhost:16060 pbx.Node/MessageLoop
```

#### 3. 长轮询调试

使用 `curl`：

```bash
# 创建会话
curl -X POST http://localhost:6060/v0/channels/lp

# 发送消息
curl -X POST "http://localhost:6060/v0/channels/lp?sid=SESSION_ID" \
    -d '{"login": {"scheme": "basic", "secret": "dGVzdDp0ZXN0"}}'

# 长轮询
curl "http://localhost:6060/v0/channels/lp?sid=SESSION_ID"
```

### 相关文件

| 文件 | 说明 |
|------|------|
| `server/hdl_websock.go` | WebSocket 处理 |
| `server/hdl_grpc.go` | gRPC 处理 |
| `server/hdl_longpoll.go` | 长轮询处理 |
| `server/hdl_files.go` | 文件传输处理 |
| `pbx/model.proto` | gRPC 协议定义 |
| `server/http.go` | HTTP 服务器 |
| `server/session.go` | 会话管理 |
| `server/datamodel.go` | 消息结构定义 |