cmvr-es/test/quic_gateway/README.md

# CMVR QUIC test Gateway

`cmvr_quic_test_gateway` 是开发和验收工具，不是平台端生产 Gateway。它在本机
监听真实的 MsQuic/TLS/UDP 连接，用来验证 `cmvr_es` 的 QUIC edge v1 客户端。

测试链路：

```text
output/bin/cmvr_es
  ├── reliable QUIC stream ──> cmvr_quic_test_gateway
  │    register / heartbeat / media metadata
  └── QUIC DATAGRAM ─────────> bounded media reassembler
```

Gateway 使用生产代码中的：

- `EdgeControlEnvelope` protobuf；
- `ControlFrameEncoder` / `ControlFrameDecoder`；
- `DatagramPacketizer::decodeHeader`；
- `CMQD` v1 常量和类型。

它不会实现 WebTransport、WebRTC、HTTP API、节点数据库或浏览器播放。

## 构建

该目录的 `CMakeLists.txt` 由项目测试目录加入。MsQuic 通过根目录
`request.txt` 提供。依赖为：

- `msquic`
- `cmvr_es::proto`
- `cmvr_es::quic_edge_service`
- `Threads::Threads`

示例：

```bash
cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMVR_ARCH=x86 \
  -DBUILD_TESTING=ON

cmake --build build --target cmvr_quic_test_gateway -j2
```

默认只生成 build-tree 测试程序，不污染部署目录。如确实希望一同安装：

```bash
cmake -S . -B build \
  -DCMVR_INSTALL_QUIC_TEST_GATEWAY=ON
cmake --build build --target cmvr_quic_test_gateway -j2
cmake --install build
```

安装位置是 `output/bin/cmvr_quic_test_gateway`，可复用
`output/lib/libmsquic.so` 和现有相对 RUNPATH。

## 生成本地测试证书

QUIC 即使使用“不校验证书”的 client 模式，Server 仍必须提供 TLS 证书。
不要提交真实私钥。下面命令只在 build 目录生成 loopback 测试证书：

```bash
mkdir -p build/test/quic_gateway/certs

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout build/test/quic_gateway/certs/server.key \
  -out build/test/quic_gateway/certs/server.crt \
  -days 7 \
  -subj "/CN=127.0.0.1" \
  -addext "subjectAltName=IP:127.0.0.1"
```

MsQuic/OpenSSL 当前要求这里的 PEM 私钥不带密码。

## 启动

固定端口适合人工联调。构建树中请使用 CMake 生成的启动包装器；它会补齐
仓库内 gRPC 等传递动态库的搜索路径：

```bash
build/test/quic_gateway/run_cmvr_quic_test_gateway \
  --bind 127.0.0.1 \
  --port 4433 \
  --cert build/test/quic_gateway/certs/server.crt \
  --key build/test/quic_gateway/certs/server.key \
  --scenario normal \
  --summary-file build/test/quic_gateway/summary.json
```

自动化测试应使用 `--port 0` 避免端口冲突。Gateway 会查询 Listener 实际端口，
在 stdout 和 `--ready-file` 写入一个 JSON 对象：

```bash
build/test/quic_gateway/run_cmvr_quic_test_gateway \
  --bind 127.0.0.1 \
  --port 0 \
  --cert build/test/quic_gateway/certs/server.crt \
  --key build/test/quic_gateway/certs/server.key \
  --ready-file build/test/quic_gateway/ready.json \
  --summary-file build/test/quic_gateway/summary.json \
  --exit-after-heartbeats 3
```

Ready 文件示例：

```json
{"event":"ready","bind":"127.0.0.1:52319","port":52319,"alpn":"cmvr-quic-edge/1","scenario":"normal","datagram_enabled":true}
```

自动 runner 读取 `port`，将它写入临时 `quic_edge_task.pb.txt` 后再启动
`cmvr_es`。不要直接改唯一一份 `output/bin/config/`；普通安装默认会覆盖它。
只更新程序与运行库时，应在配置构建目录时设置
`-DCMVR_INSTALL_DEFAULT_RUNTIME_ASSETS=OFF`。

## cmvr_es 本机配置

第一轮只测试注册、IP 上报和心跳，保持设备和 `tracks` 关闭：

```protobuf
quic_edge {
  id: "quic_edge"
  server_host: "127.0.0.1"
  server_port: 4433
  alpn: "cmvr-quic-edge/1"
  node_id: "local-quic-test"
  software_version: "test"

  grpc_endpoint_host: "127.0.0.1"
  grpc_endpoint_port: 50052
  grpc_endpoint_tls: false
  include_loopback_interfaces: true

  heartbeat_interval_ms: 1000
  control_response_timeout_ms: 1000

  tls {
    allow_insecure: true
  }

  reconnect {
    initial_delay_ms: 100
    maximum_delay_ms: 1000
    multiplier: 2.0
    jitter_percent: 0
    connect_timeout_ms: 3000
  }

  maximum_datagram_bytes: 1200
  maximum_control_frame_bytes: 1048576
  maximum_frame_bytes: 524288
  datagram_send_queue_depth: 512
  media_poll_interval_ms: 2
}
```

在 TaskManager 中将 `quic_edge` entry 设为 `enable: true`。然后运行一份独立的
临时配置树：

```bash
output/bin/cmvr_es /tmp/cmvr-quic-e2e/config/cmvr_es.pb.txt
```

## 场景

`--scenario` 支持：

当前 CTest 自动回归仅运行 `normal` 场景；其余场景保留为手工故障注入和验收入口，
尚未纳入自动回归。

| 名称 | 行为 | 预期 Edge 行为 |
| --- | --- | --- |
| `normal` | 接受注册并精确 ACK 心跳 | 保持同一连接 |
| `reject-registration` | 返回 `accepted=false` | 退避后重新注册 |
| `drop-heartbeat-ack` | 接收但不回复心跳 | response timeout 后重连 |
| `wrong-ack-session` | ACK 使用错误 session ID | 判定协议错误并重连 |
| `fatal-protocol-error` | 注册成功后发送 fatal `ProtocolError` | 重连 |
| `nonfatal-protocol-error` | 注册成功后发送 nonfatal `ProtocolError` | 保持连接并继续心跳 |
| `datagram-disabled` | 不协商 QUIC DATAGRAM | 注册和心跳正常，媒体不发送 |

可以用以下条件让程序自动成功退出：

- `--exit-after-registrations N`
- `--exit-after-heartbeats N`
- `--run-for-ms N`

收到 `SIGINT` 或 `SIGTERM` 时，Gateway 会停止 Listener、关闭活动连接、排空工作
队列并写 summary。

## 协议验证

每个连接独立维护：

- control framing buffer；
- Edge 和 Gateway 各自的严格递增 `message_sequence`；
- node、boot、registration session；
- media session epoch；
- track descriptor generation token；
- DATAGRAM 重组缓存。

Gateway 要求：

1. `NodeRegisterRequest` 是第一条应用消息；
2. protocol version 为 1；
3. 后续 envelope sequence 严格增加；
4. heartbeat 的 node、boot 和 session 与注册一致；
5. media session 先于 descriptor；
6. DATAGRAM 的 epoch、track、kind 和 generation token 与可靠元数据一致。

`observed_source_ip` 从 MsQuic peer address 获取，不从 Edge 上报字段复制。
Heartbeat 中存在 `device_manager` 时，Gateway 会记录 Manager 元数据以及设备
总数、启用数、禁用数、确认异常数和未知健康数；该字段是 v1 的兼容性追加项，
并在最终 summary 的 `heartbeat_devices` 数组中保留最近一次完整设备行。测试
Gateway 仍接受没有该字段的旧 Edge。当前 Edge 只发送已启用设备，因此正常情况
下禁用数为 0；该统计仍用于兼容旧发送端和发现协议违规。
summary 还会保留每类媒体最近一次 descriptor，以及已完成帧中的最大
`frame_sequence`、长度、flags、采集时间戳和 FNV-1a 64 位载荷哈希。这里的哈希
只用于测试中精确比对字节，不用于安全认证。真实 E2E 会先发送 discovery 帧并等
descriptor 到达，再发送 priming/validation 帧，从而避免 reliable stream 与
DATAGRAM 跨通道乱序造成偶发误判。

## DATAGRAM 安全边界

MsQuic callback 只复制收到的数据并进入有界队列；控制消息使用高优先级队列，
不会被媒体洪峰长期阻塞。后台线程完成 protobuf 处理和媒体重组。

重组 key 是：

```text
(session_epoch, track_id, frame_sequence)
```

接收器限制：

- 总缓存字节；
- 在途帧数；
- 单帧大小；
- 单帧最多 8192 个分片；
- 不完整帧超时；
- fragment index 冲突；
- byte range 重叠；
- 新 session epoch 清理旧分片。

相关 CLI：

```text
--max-reassembly-bytes
--max-reassembly-frames
--max-frame-bytes
--max-work-queue-bytes
--reassembly-timeout-ms
```

## 输出与判定

stdout 每行都是一个 JSON 对象或 JSON-compatible 单行事件。最终 summary 包含：

- connection/register/heartbeat 计数；
- 注册和最近一次心跳上报的网卡数量、gRPC endpoint 与对端源 IP；
- 最近一次 DeviceManager 名称/版本/描述，以及已上报设备总数、启用数、兼容性
  禁用数、确认异常数、未知健康数和 `heartbeat_devices` 完整设备行；
- ACK、故障场景和协议错误计数；
- media session/descriptor/DATAGRAM 计数；
- 完整帧（含视频/音频分项）、无效包、队列丢包；
- 超时、容量淘汰和 session 清理的不完整帧。

自动化脚本至少应检查：

```text
runtime_failed == false
registrations_accepted >= 1        # normal 场景
heartbeats_received >= 1
heartbeat_acks_sent >= 1
protocol_violations == 0
```

媒体场景还应检查：

```text
media_sessions_opened >= 1
track_descriptors_received >= 1
datagrams_received >= 1
frames_completed >= 1
```

## 无设备主机的限制

关闭全部设备时，实际 `output/bin/cmvr_es` 可以完整验证 TLS、ALPN、控制 stream、
注册、IP 上报、心跳和重连，但不会产生音视频。

要在无硬件环境验证媒体 DATAGRAM，测试侧还需要 synthetic MediaSourceHub producer
或测试专用 fake camera/microphone。该 Gateway 已具备媒体接收和重组能力，但不会
伪造 Edge 发出的媒体。

## 安全说明

- 仅监听 loopback 是默认值；
- `allow_insecure` 仅限本机开发；
- 不要将测试 Gateway 暴露到不受信任网络；
- 不要复用或提交生产证书、生产私钥；
- 该工具没有生产级认证、授权、持久化和多租户隔离。