+-------------------------------------------------------+
|  Application Layer (业务逻辑层)                        |
|  - 信令类型: Join, Leave, Offer, Answer, Candidate... |
+-------------------------------------------------------+
|  Schema Layer (Schema 定义层 - FlatBuffers .fbs)       |
|  - Namespace, Table, Struct, Enum, Union 定义         |
|  - 版本字段、扩展字段、废弃字段标记                    |
+-------------------------------------------------------+
|  Framing Layer (帧封装层)                              |
|  - Magic Number (2B) | Version (1B) | Flags (1B)      |
|  - Payload Length (4B, Varint) | Checksum (4B, CRC32) |
|  - Payload (FlatBuffers Binary Buffer)                |
+-------------------------------------------------------+
|  Transport Layer (传输层适配)                          |
|  - WebTransport Stream (Datagram / Bidirectional)     |
|  - WebSocket Frame (Binary Opcode)                    |
+-------------------------------------------------------+

namespace com.company.rtc.signaling;

// 通用元数据，所有信令必带
table SignalMeta {
  req_id: string;           // 全局唯一请求ID，用于幂等与追踪
  timestamp: int64;         // 客户端发送时间戳
  version: uint16;          // 协议子版本号
  token: string;            // 鉴权票据
  ext: [ubyte];             // 透传扩展字段，预留给网关/中间件
}

// 具体业务载荷
table JoinRoomReq {
  meta: SignalMeta;
  room_id: string;
  uid: string;
  media_caps: MediaCapabilities; // 结构体嵌套
}

table MediaCapabilities {
  video_codecs: [string];
  audio_codecs: [string];
  simulcast: bool;
}

// 服务端下发通知
table ServerNotification {
  meta: SignalMeta;
  event_type: NotificationEvent; // Enum
  payload: NotificationPayload;  // Union
}

// Union 实现多态
union NotificationPayload { KickOut, StreamUpdate, RoomStats }
table KickOut { reason: string; }
table StreamUpdate { streams: [StreamInfo]; }

// 根表，用于解析入口
table SignalEnvelope {
  meta: SignalMeta;
  signal_type: SignalType;     // Enum: Request, Response, Notify
  payload: SignalPayload;      // Union: JoinRoomReq, Offer, Answer...
}
root_type SignalEnvelope;

sequenceDiagram
    Client->>Server: HTTPS DNS / Alt-Svc 发现 h3 支持
    alt 支持 QUIC
        Client->>Server: WebTransport CONNECT (0-RTT 可选)
        Server-->>Client: SESSION_ESTABLISHED
        Client->>Server: 发送 SignalEnvelope(Handshake)
    else 降级 TCP
        Client->>Server: WebSocket Upgrade
        Server-->>Client: 101 Switching Protocols
        Client->>Server: 发送 SignalEnvelope(Handshake)
    end
    Server-->>Client: SignalEnvelope(HandshakeAck { supported_versions, features })

// Go 伪代码：传输层抽象
type Transport interface {
    Send(ctx context.Context, payload []byte, opts SendOptions) error
    RecvLoop(handler func([]byte, error))
    Close() error
    Type() TransportType // QUIC / WS
}

// 发送选项，映射到底层流属性
type SendOptions struct {
    Reliable   bool   // true -> Stream, false -> Datagram
    Priority   uint8  // QUIC Stream Priority
    StreamID   uint64 // 指定流复用
}

// 使用 sync.Pool 复用 FlatBuffers Builder
var builderPool = sync.Pool{
    New: func() interface{} {
        return flatbuffers.NewBuilder(1024) // 初始 1KB，自动扩容
    },
}

func BuildJoinResponse(reqID string, code int32) []byte {
    b := builderPool.Get().(*flatbuffers.Builder)
    b.Reset() // 重置而非重新分配
    
    // ... 构建逻辑 ...
    
    buf := make([]byte, len(b.FinishedBytes()))
    copy(buf, b.FinishedBytes()) // 必须拷贝，因 Builder 归池后会被复用覆盖
    builderPool.Put(b)
    return buf
}

+------------------+      +------------------+      +------------------+
|  L4/L7 Load      |      |  Access Gateway  |      |  Logic Gateway   |
|  Balancer        |----->|  (Stateless)     |----->|  (Stateful/Stateless)|
|  (LVS/Cloud LB)  |      |  - TLS/QUIC Term |      |  - Session Mgmt  |
|                  |      |  - Frame Codec   |      |  - Routing/Auth  |
|                  |      |  - Rate Limit    |      |  - Push Fanout   |
+------------------+      +------------------+      +------------------+
                                 |                           |
                                 v                           v
                        +------------------+      +------------------+
                        |  Config Center   |      |  State Store     |
                        |  (Nacos/Etcd)    |      |  (Redis Cluster) |
                        +------------------+      +------------------+

// 扩展 SignalMeta 增加安全字段
table SignalMeta {
  req_id: string;           // UUID v7 (含时间戳)，全局唯一
  timestamp: int64;         // 客户端 Unix 毫秒时间戳
  nonce: string;            // 客户端生成 16 字节随机数
  signature: [ubyte];       // 签名值 (Ed25519: 64B)
  // 签名原文构造规范：Canonicalize(req_id + "|" + timestamp + "|" + nonce + "|" + Payload_Hash)
}

func VerifyAndAntiReplay(meta *SignalMeta, payloadHash []byte, pubKey ed25519.PublicKey) error {
    // 1. 时间窗口校验（防重放核心）：允许 ±300s 漂移，需客户端校时
    if abs(time.Now().UnixMilli() - meta.Timestamp) > 300_000 {
        return ErrTimestampExpired
    }

    // 2. 防重放：Redis SetNX (req_id, ttl=300s) 原子操作
    //    利用 Redis 单线程特性保证幂等，Value 存 timestamp 便于审计
    added, err := redis.SetNX(ctx, "replay:"+meta.ReqID, meta.Timestamp, 300*time.Second).Result()
    if err != nil || !added {
        return ErrReplayAttack
    }

    // 3. 签名验签（零拷贝构造签名原文）
    //    避免 fmt.Sprintf 分配，使用 bytes.Buffer 或预分配 []byte
    if !ed25519.Verify(pubKey, BuildSigningContent(meta, payloadHash), meta.Signature) {
        return ErrInvalidSignature
    }
    return nil
}

[DISCONNECTED] 
     | Connect()
     v
[CONNECTING] --(Timeout/Fail)--> [RECONNECT_SCHEDULED] --(Backoff)--> [CONNECTING]
     | Success (HandshakeAck)
     v
[CONNECTED] <------------------- [MIGRATING] (收到 MigrateHint / 网络切换)
     | Heartbeat Timeout / Error
     v
[RECONNECT_SCHEDULED] --(指数退避 + 抖动)--> [CONNECTING]
     | MaxRetry / UserLogout
     v
[DISCONNECTED]

// iOS/Swift 伪代码：离线队列持久化
class OfflineQueue {
    private let db: SQLiteDatabase // 或 MMKV/Realm
    private let maxSize = 500 // 防止 OOM
    
    func enqueue(_ frame: Data, meta: SignalMeta) {
        // 1. 丢弃策略：心跳、统计上报等低优先级可丢弃
        if meta.priority == .low && count >= maxSize { return }
        
        // 2. 落盘（WAL 模式保证写入性能）
        try db.execute("INSERT INTO offline_q (payload, meta_json, created_at) VALUES (?, ?, ?)", 
                       frame, meta.toJSON(), Date().timeIntervalSince1970)
    }
    
    func drain(onSend: (Data) -> Bool) {
        // 连接恢复后批量发送，发送成功再删除
        let rows = try db.query("SELECT id, payload FROM offline_q ORDER BY created_at LIMIT 50")
        for row in rows {
            if onSend(row.payload) { try db.execute("DELETE FROM offline_q WHERE id=?", row.id) }
            else { break } // 发送失败（如网络再次中断），保留下次重试
        }
    }
}

# .github/workflows/schema-check.yml
jobs:
  schema-compatibility:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Download FlatBuffers Compiler
        run: wget -q https://github.com/google/flatbuffers/releases/download/v24.3.25/Linux.flatc.binary.g++-11.zip && unzip ...
      - name: Generate Code (All Languages)
        run: |
          flatc --go --gen-object-api -o gen/go schema/signaling.fbs
          flatc --java -o gen/java schema/signaling.fbs
          flatc --cpp -o gen/cpp schema/signaling.fbs
          flatc --ts -o gen/ts schema/signaling.fbs
          flatc --swift -o gen/swift schema/signaling.fbs
      - name: Compile Check (Fail Fast)
        run: |
          cd gen/go && go build ./...
          cd gen/java && ./gradlew compileJava
          cd gen/cpp && cmake . && make
          cd gen/ts && tsc --noEmit
          cd gen/swift && swift build
      - name: Compatibility Test (Golden Files)
        run: |
          # 使用固定二进制 Golden File 校验各语言解析一致性
          python3 tools/test_cross_lang.py --golden testdata/golden.bin --schema schema/signaling.fbs

# Python (Hypothesis) 示例
from hypothesis import given, strategies as st
from flatbuffers import Builder
import signaling_generated as sg

@given(st.data())
def test_roundtrip_join_room(data):
    # 1. 构造随机合法数据
    room_id = data.draw(st.text(min_size=1, max_size=64))
    uid = data.draw(st.text(min_size=1, max_size=32))
    
    # 2. 编码
    builder = Builder(1024)
    room_off = builder.CreateString(room_id)
    uid_off = builder.CreateString(uid)
    sg.JoinRoomReqStart(builder)
    sg.JoinRoomReqAddRoomId(builder, room_off)
    sg.JoinRoomReqAddUid(builder, uid_off)
    req_off = sg.JoinRoomReqEnd(builder)
    builder.Finish(req_off)
    buf = builder.Output()
    
    # 3. 解码
    req = sg.JoinRoomReq.GetRootAsJoinRoomReq(buf, 0)
    
    # 4. 断言核心字段一致性
    assert req.RoomId().decode('utf-8') == room_id
    assert req.Uid().decode('utf-8') == uid
    
    # 5. 再次编码对比二进制一致性 (验证确定性序列化)
    builder2 = Builder(1024)
    # ... 重新构建 ...
    assert builder2.Output() == buf  # 要求 FlatBuffers 确定性输出