# softbus_transport

**路径：** `src/softbus_transport`  
**构建目标：** `softbus_transport`（STATIC 库）  
**层级：** L2 服务层

## 1. 概述

`softbus_transport` 实现边缘与守护进程之间的 **TCP 传输层**，定义 UplinkWire JSON 行协议，提供 Server（守护进程监听）与 Client（边缘连接）对称实现。

## 2. CONSTRAINTS

- 传输层仅负责 TCP 连接管理与线消息编解码，不包含业务解析逻辑。
- 消息格式遵循 [UPLINK_WIRE_PROTOCOL.md](UPLINK_WIRE_PROTOCOL.md)，不得引入私有扩展字段而不更新协议文档。
- Server 与 Client 均基于 asio 异步 I/O，不得阻塞调用线程。
- 传输层不得直接操作 OPC UA 或插件。

## 3. 核心组件

### 3.1 UplinkWire — 线协议

| 类型/函数 | 说明 |
|-----------|------|
| `WireMessageType` | 枚举：`RawPacket`、`ExecuteCommand`、`Unknown` |
| `WireMessage` | 解码结果联合体 |
| `encodeWireMessage(RawPacket)` | 上行编码 |
| `encodeWireMessage(ExecuteCommand)` | 下行编码 |
| `decodeWireMessage(line)` | 单行解码 |
| `base64Encode` / `base64Decode` | payload 编解码 |

### 3.2 TcpUplinkServer — 守护进程侧

| 方法 | 说明 |
|------|------|
| `TcpUplinkServer(io_context, host, port)` | 构造，绑定监听地址 |
| `start()` | 启动 acceptor |
| `stop()` | 停止服务 |
| `setRawPacketHandler(handler)` | 注册上行回调 `function<void(RawPacket)>` |
| `sendCommand(ExecuteCommand)` | 向已连接边缘发送下行命令 |

**行为：**

- 监听 TCP 端口，接受边缘连接
- 按 `\n` 分行读取，解码 `rawPacket` 消息
- 触发 `rawHandler` 回调
- 通过 `sendCommand` 向边缘推送 `executeCommand`

### 3.3 TcpUplinkClient — 边缘侧

| 方法 | 说明 |
|------|------|
| `TcpUplinkClient(io_context, host, port)` | 构造，指定守护进程地址 |
| `connect()` | 连接守护进程 |
| `disconnect()` | 断开连接 |
| `sendRawPacket(RawPacket)` | 发送上行原始包 |
| `poll()` | 轮询接收下行命令 |
| `setCommandHandler(handler)` | 注册命令回调 `function<void(ExecuteCommand)>` |

## 4. 数据流

### 4.1 上行

```
Edge: UplinkClient.sendRawPacket(packet)
  → encodeWireMessage(packet) + "\n"
  → TCP send
  → Server: handleLine(line)
  → decodeWireMessage(line)
  → rawHandler(rawPacket)
```

### 4.2 下行

```
Daemon: CommandDispatcher.dispatch(cmd)
  → TcpUplinkServer.sendCommand(cmd)
  → encodeWireMessage(cmd) + "\n"
  → TCP send
  → Client: handleLine(line)
  → decodeWireMessage(line)
  → commandHandler(cmd)
```

## 5. 配置

| 配置项 | 来源 | 默认值 |
|--------|------|--------|
| `uplink.listenHost` | `daemon_profile.json` | `127.0.0.1` |
| `uplink.listenPort` | `daemon_profile.json` | `9000` |
| Edge 连接地址 | CLI `--daemon host:port` | `127.0.0.1:9000` |

## 6. 依赖

- `softbus_core`（RawPacket）
- `softbus_api`（ExecuteCommand）
- `asio`（FetchContent standalone，v1.30.2）
- **被依赖：** softbus_edge, softbus_daemon

## 7. 构建

```cmake
add_library(softbus_transport STATIC ...)
target_link_libraries(softbus_transport PUBLIC softbus_core softbus_api asio)
```

## 8. Phase 2 规划

- 支持多边缘连接与连接池
- 增加断线重连与心跳机制
- 可选迁移至 SBUP 二进制协议