# OmniSocket

OmniSocket 当前包含 3 个核心程序：
- `omni_peer`
- `omni_hub`
- `omni_bridge`

三者统一支持 `tcp | udp | kcp` 三种传输协议。

## 构建

本地构建：

```bash
make
```

生成文件：
- `build/omni_peer`
- `build/omni_hub`
- `build/omni_bridge`

Jetson 场景常用 ARM64 交叉编译：

```bash
make arm64
```

生成文件：
- `build/arm64/omni_peer`
- `build/arm64/omni_hub`
- `build/arm64/omni_bridge`

## 程序说明

### `omni_peer`

`omni_peer` 支持两种工作模式：
- `hub` 模式：连接 `hub` 或 `bridge`
- `direct` 模式：`peer` 之间直接互连

常见用途：
- 发送文本命令
- 发送文件
- 接收文件

### `omni_hub`

`omni_hub` 是中心注册与转发节点，通常部署在公网服务器或中心网络位置。

主要职责：
- 维护 `client_id -> session`
- 转发 `peer` 之间的 `bind / tunnel / status`

### `omni_bridge`

`omni_bridge` 是桥接节点，用于将远端 `peer` 接入上游 `hub`。

主要职责：
- 上游连接 `hub`
- 下游监听本地入口供 `peer` 接入
- 适用于 `A <-> C <-> D <-> B` 这类桥接链路

当前限制：
- 一个 `bridge` 仅支持一个下游 `peer`
- 下游 `peer` 的 `-i` 必须与 `bridge -i` 保持一致
- 上下游必须使用同一种协议，不支持协议转换
- 当前实现更接近“单下游、单身份桥接”，而不是通用多租户中继

## 角色说明

- `A`：本地电脑
- `B`：Jetson
- `C`：公网 Hub 服务器
- `D`：公网 Bridge 服务器

下面示例中的 `<proto>` 可替换为 `tcp`、`udp` 或 `kcp`。

说明：
- 以下 `omni_peer` 示例统一采用长连接交互模式
- 启动后连接会保持，不再使用“传输一次后自动退出”的一次性写法
- 文本和文件传输通过终端中的交互命令完成
- 若启动命令中使用了 `-m` 或 `-F`，程序会执行启动动作模式，而不是进入当前 README 使用的交互模式

## 常用参数与命令

| 分类 | 写法 | 含义 |
| --- | --- | --- |
| 启动参数 | `-i <client_id>` | 当前 `peer` 的逻辑身份。Hub 会根据这个 ID 记录 `client_id -> session` 映射，例如 `-i pc` 表示“我是 pc”，`-i jetson` 表示“我是 jetson”。 |
| 启动参数 | `-b <peer_id>` | 启动后默认绑定的目标 `peer`。例如 `-b jetson` 表示后续直接输入 `send ...` 或 `put ...` 时，默认发给 `jetson`。 |
| 启动参数 | `-d <peer_id>` | 启动动作模式下的显式目标。通常与 `-m` 或 `-F` 配合使用，表示把启动时的那条消息或那个文件直接发给指定目标。 |
| 启动参数 | `-o <output_file>` | 本地接收文件时的落盘路径。收到文件后会写入当前机器上的这个路径，例如 `-o /tmp/from_pc.bin`。 |
| 交互命令 | `bind <peer_id>` | 将默认目标切换到指定 `peer`，后续 `send` 或 `put` 默认发给它。 |
| 交互命令 | `send <text>` | 向当前默认目标发送一条文本消息。 |
| 交互命令 | `say <peer_id> <text>` | 向指定 `peer` 发送一条文本消息，不修改当前默认目标。 |
| 交互命令 | `put <file>` | 将当前机器上的文件发送给当前默认目标。 |
| 交互命令 | `push <peer_id> <file>` | 将当前机器上的文件发送给指定 `peer`，不修改当前默认目标。 |
| 交互命令 | `show` | 显示当前本地状态，例如 `client_id`、当前绑定目标和输出路径。 |
| 交互命令 | `quit` | 退出当前 `omni_peer` 进程。 |

## 场景 1：点对点直传

`A <-> B`

B 端监听：

```bash
./build/omni_peer -M direct -p <proto> -L 9001 -i jetson -o /tmp/from_pc.bin
```

A 端连接：

```bash
./build/omni_peer -M direct -p <proto> -H <B_IP> -P 9001 -i pc -b jetson -o /tmp/from_jetson.bin
```

连接建立后，可在 A 端输入：

```text
send start
put /tmp/input.bin
```

如需反向 `B -> A`，可在 B 端输入：

```text
put /path/to/file.bin
```

## 场景 2：通过 Hub 中转

`A <-> C <-> B`

C 端启动 Hub：
- C 维护着一张 `client_id -> session` 映射表，用于记录谁是 `pc`、谁是 `jetson`，并据此转发 `bind / tunnel / status`

```bash
./build/omni_hub -p <proto> -P 9002
```

B 端连接 Hub：

```bash
./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i jetson -o /tmp/from_pc.bin
```

A 端连接 Hub：

```bash
./build/omni_peer -p <proto> -H <C_IP> -P 9002 -i pc -b jetson -o /tmp/from_jetson.bin
```

连接建立后，可在 A 端输入：

```text
send start
put /tmp/input.bin
```

如需反向 `B -> A`，可在 B 端输入：

```text
bind pc
put /path/to/file.bin
```

## 场景 3：通过 Bridge 桥接

`A <-> C <-> D <-> B`

C 端启动 Hub：
- C 仍然维护 `client_id -> session` 映射表；A 以 `pc` 注册到 C，Bridge 以 `jetson` 这个逻辑身份注册到 C

```bash
./build/omni_hub -p <proto> -P 9003
```

D 端启动 Bridge：

```bash
./build/omni_bridge -p <proto> -H <C_IP> -P 9003 -i jetson -L 9004
```

B 端连接 Bridge：

```bash
./build/omni_peer -p <proto> -H <D_IP> -P 9004 -i jetson -o /tmp/from_pc.bin
```

A 端连接 Hub：

```bash
./build/omni_peer -p <proto> -H <C_IP> -P 9003 -i pc -b jetson -o /tmp/from_jetson.bin
```

连接建立后，可在 A 端输入：

```text
send start
put /tmp/input.bin
```

如需反向 `B -> A`，可在 B 端输入：

```text
bind pc
put /path/to/file.bin
```

说明：
- 该场景已经实现 `A -> C -> D -> B` 与 `B -> D -> C -> A` 的桥接转发
- 但当前 `bridge` 仍是单下游、单身份模型，不是完整的多节点桥接网络