# HTTP API 接口文档

本文档根据 `src/http` 下各 handler 的 `handle_request/4` 实现整理。

## 通用说明

- HTTP 服务端口由应用配置 `sdlan.http_server.port` 决定。
- 响应 `Content-Type` 为 `application/json;charset=utf-8`。
- 当响应体大小大于等于 1024 字节且请求头 `Accept-Encoding` 包含 `gzip` 时，响应会启用 gzip 压缩。
- GET 参数来自 URL query string。
- POST 请求体支持两种格式：
  - `Content-Type: application/json`：请求体会按 JSON object 解析，数字保持为 JSON number。
  - `Content-Type: application/x-www-form-urlencoded`：请求体会按表单解析，参数值为 binary/string；涉及整型参数的接口建议使用 JSON 请求体。
- 统一成功返回格式：

```json
{
  "result": "<any>"
}
```

- 统一失败返回格式：

```json
{
  "error": {
    "code": -1,
    "message": "错误描述"
  }
}
```

- handler 未匹配到 URL、Method 或参数结构时，通常返回 HTTP 200，并返回如下错误格式：

```json
{
  "error": {
    "code": -1,
    "message": "url: /path not found"
  }
}
```

## binlog_handler

路由配置：`/binlog`

### POST /binlog

接收 binlog 通知，目前只记录请求参数并返回固定结果。

**Method**：`POST`

**参数**：无必填参数。请求体可为 JSON object 或 form。

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| 任意字段 | body | object/string/number/boolean/array | 否 | 当前实现不读取具体字段，仅打印完整请求体参数。 |

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 固定为 `"ok"`。 |

示例：

```json
{
  "result": "ok"
}
```

## test_handler

路由配置：`/test/[...]`

### POST /test/auth_access_token

测试用 access token 校验接口，目前返回固定结果。

**Method**：`POST`

**参数**：无必填参数。请求体可为 JSON object 或 form。

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| 任意字段 | body | object/string/number/boolean/array | 否 | 当前实现不读取具体字段。 |

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 固定为 `"ok"`。 |

示例：

```json
{
  "result": "ok"
}
```

### GET /test/get_all_networks

测试用获取全部网络 ID。

**Method**：`GET`

**参数**：无。

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | array&lt;integer&gt; | 网络 ID 列表。当前实现固定返回 `[8]`。 |

示例：

```json
{
  "result": [8]
}
```

### GET /test/get_network

测试用获取单个网络详情。

**Method**：`GET`

**参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | query | string(integer) | 是 | 网络 ID。实现中会通过 `binary_to_integer/1` 转为 integer；当前仅内置 ID `8`。 |

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | object | 网络详情对象。 |
| result.id | integer | 网络 ID。 |
| result.name | string | 网络名称。 |
| result.domain | string | 网络域名。 |
| result.ipaddr | string | 网络地址段，CIDR 格式。 |
| result.owner_id | integer | 所属用户 ID。 |
| result.algorithm | string | 加密算法。 |
| result.disabled_clients | array&lt;string&gt; | 禁用的客户端 ID 列表。 |

示例：

```json
{
  "result": {
    "id": 8,
    "name": "test1",
    "domain": "punchnet.cn",
    "ipaddr": "10.211.179.0/24",
    "owner_id": 1234,
    "algorithm": "chacha20",
    "disabled_clients": []
  }
}
```

## api_handler

路由配置：`/api/[...]`

注意：当前 `api_handler` 的实现匹配路径为 `/test/auth_token`，但 Cowboy 路由只会把 `/api/[...]` 请求分发给 `api_handler`。因此按当前路由配置，该接口不可达；直接请求 `/test/auth_token` 会被分发到 `test_handler`，也不会命中此实现。

### POST /test/auth_token

获取测试 auth token 信息，返回第一个网络 ID。

**Method**：`POST`

**当前可达性**：不可达，原因见本节说明。

**参数**：无必填参数。请求体可为 JSON object 或 form。

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| 任意字段 | body | object/string/number/boolean/array | 否 | 当前实现不读取具体字段，仅打印完整请求体参数。 |

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | object | 返回数据对象。 |
| result.network_id | integer | `network_bo:get_all_networks/0` 返回列表中的第一个网络 ID。 |

示例：

```json
{
  "result": {
    "network_id": 8
  }
}
```

## network_handler

路由配置：`/network/[...]`

### POST /network/create

启动或确保指定网络已启动。

**Method**：`POST`

**参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | body | integer | 是 | 网络 ID，需大于 0。建议使用 JSON number。 |

请求示例：

```json
{
  "id": 8
}
```

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 固定为 `"success"`。 |

示例：

```json
{
  "result": "success"
}
```

**失败返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| error.code | integer | 固定为 `-1`。 |
| error.message | string | 固定为 `"error"`。 |

### POST /network/delete

删除指定网络；如果网络未启动，也视为删除成功。

**Method**：`POST`

**参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | body | integer | 是 | 网络 ID，需大于 0。建议使用 JSON number。 |

请求示例：

```json
{
  "id": 8
}
```

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 固定为 `"success"`。 |

示例：

```json
{
  "result": "success"
}
```

**失败返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| error.code | integer | 固定为 `-1`。 |
| error.message | string | 固定为 `"error"`。 |

### POST /network/exit_node_control

向指定客户端下发出口节点控制命令，并等待客户端 ACK。

**Method**：`POST`

**参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| id | body | integer | 是 | 网络 ID，需大于 0。建议使用 JSON number。 |
| action | body | integer | 是 | 出口节点动作，传入 `SDLCommand.ExitNodeControl.action`。历史文档约定：`0` 表示关闭，`1` 表示开启。 |
| client_id | body | string | 是 | 目标客户端 ID。 |
| remark | body | string | 是 | 下发备注，用于跟踪命令；可传空字符串。 |
| timeout | body | integer | 是 | 等待 ACK 的超时时间，单位秒。实现中会转换为毫秒。 |

请求示例：

```json
{
  "id": 8,
  "action": 1,
  "client_id": "client-id",
  "remark": "trace remark",
  "timeout": 10
}
```

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 正常 ACK 时固定为 `"success"`。 |

示例：

```json
{
  "result": "success"
}
```

**其他返回**：

| 场景 | 返回格式 | 字段类型 | 说明 |
| --- | --- | --- | --- |
| 网络不存在 | `{"result":"network not found"}` | result: string | 当前实现将网络不存在作为 result 返回，而不是 error。 |
| 命令发送失败 | `{"error":{"code":-1,"message":"..."}}` | code: integer, message: string | message 为底层返回的 Reason，需为可 JSON 编码值。 |
| 客户端 ACK 失败 | `{"error":{"code":<Code>,"message":"<Message>"}}` | code: integer, message: string | Code 和 Message 来自 `SDLCommandAck`。 |
| 等待 ACK 超时 | `{"error":{"code":-1,"message":"任务执行超时"}}` | code: integer, message: string | 超过 `timeout` 秒未收到 ACK。 |

## node_handler

路由配置：`/node/[...]`

### POST /node/disable

禁用指定网络中的客户端节点。

**Method**：`POST`

**参数**：

| 参数 | 位置 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- | --- |
| network_id | body | integer | 是 | 网络 ID，需大于 0。建议使用 JSON number。 |
| client_id | body | string | 是 | 客户端 ID。 |

请求示例：

```json
{
  "network_id": 8,
  "client_id": "client-id"
}
```

**成功返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| result | string | 固定为 `"success"`。 |

示例：

```json
{
  "result": "success"
}
```

**失败返回**：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| error.code | integer | 固定为 `-1`。 |
| error.message | string | 当前实现中网络不存在时为 `"network not found"`。 |