Metadata-Version: 2.4
Name: adp-operator
Version: 1.0.7
Summary: ADP operator management and C2C runtime tools
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: docker
Requires-Dist: fastapi
Requires-Dist: pandas
Requires-Dist: pyarrow
Requires-Dist: pyarmor
Requires-Dist: psutil
Requires-Dist: python-dotenv
Requires-Dist: python-multipart
Requires-Dist: requests
Requires-Dist: uvicorn
Requires-Dist: colorlog
Requires-Dist: websockets
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ADP Operator

## C2C 连接首包

C2C TCP 连接建立后，双方必须先交换固定长度的二进制首包。首包校验通过后，连接才允许继续处理 JSON 业务指令。

首包固定为 512 bit，结构如下：

| bit 偏移 | bit 长度 | 字段 | 规则 |
| ---: | ---: | --- | --- |
| 0 | 24 | 固定标识 | 三个 ASCII 字符 `ADP` |
| 24 | 16 | 协议版本 | 16-bit 无符号整数，使用大端序，当前版本为 `7` |
| 40 | 256 | 实例编号 | 当前节点的 `instance_id`，固定32字节 |
| 296 | 8 | 功能控制区 | bit 0–2为功能开关，bit 3–7为保留位 |
| 304 | 208 | 全零保留区 | 必须全部为 `0` |

字符串字段统一使用 UTF-8 编码。字段长度不足时在尾部使用 `0x00` 填充，超过字段长度时按字段长度截断。

### 功能控制区

功能控制区固定为8 bit，每个功能占用一个 bit：

| bit | 功能 | `0` | `1` | 当前默认值 |
| ---: | --- | --- | --- | --- |
| 0 | UDP 主动发现 | 关闭 | 开启 | `1` |
| 1 | 额外 channel 通道 | 不支持 | 支持 | `1` |
| 2 | WebSocket 业务端口 | 关闭 | 开启 | `1` |
| 3–7 | 保留位 | 必须为零 | 不允许 | `0` |

当前默认控制区的二进制内容为：

```text
00000111
```

### 握手流程

1. TCP 客户端连接 C2C 服务端。
2. 客户端发送自己的 512 bit 二进制首包。
3. 服务端读取并校验完整首包。
4. 服务端校验通过后，向客户端返回自己的 512 bit 二进制首包。
5. 客户端校验服务端首包。
6. 双方校验均通过后，才开始发送 JSON 业务指令。

服务端会拒绝以下连接：

- 首包长度不足 512 bit；
- 固定标识不是 `ADP`；
- 目标节点协议版本低于发起连接节点的协议版本；
- `instance_id` 为空；
- 字符串字段的补零格式错误；
- 功能控制区保留位非零；
- 208 bit 全零保留区存在非零数据。

该首包适用于 C2C 直连、反向连接、多跳转发、额外 channel 通道、外部 `C2CSession` 和本地服务探测。未实现该二进制首包的旧节点无法与新协议节点建立连接，因此升级时需要同时更新同一网络中的全部 C2C 节点。

协议版本字段固定为16 bit，使用大端序表示无符号整数，取值范围为 `0`–`65535`。客户端收到服务端首包后比较版本：目标节点版本大于或等于本机版本时允许连接，目标节点版本低于本机版本时拒绝连接。例如本机版本为 `4`、目标版本为 `5` 时允许连接；本机版本为 `5`、目标版本为 `4` 时拒绝连接。
