# net TCP 通信

## 功能

`net.listen({type: 'tcp'})` 启动 TCP 服务端，`net.connect({type: 'tcp'})` 创建 TCP 客户端。

## 服务端语法

```bt
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:9000',
    on_connect: fn(client) {},
    on_message: fn(client, message) {},
    on_close: fn(client) {},
    on_error: fn(message) {}
})
```

## 客户端语法

```bt
client = net.connect({type: 'tcp', host: '127.0.0.1', port: 9000, timeout: 3000})
client.write('ping')
text = client.read()
client.close()
```

## 服务端配置字段

`net.listen({type: 'tcp', ...})` 使用以下字段：

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `tcp`。 |
| bind | String | 是 | 无 | TCP 监听地址，格式为 `主机:端口`，例如 `127.0.0.1:9000`。端口写 `0` 时由系统分配空闲端口。 |
| binary | Bool | 否 | false | 为 true 时，on_message 的 message 参数返回 Bytes；默认保持 String 兼容行为。 |
| on_connect | Fn | 否 | 无 | 客户端连接成功时调用，回调参数为 `client`。 |
| on_message | Fn | 否 | 无 | 收到客户端数据时调用，回调参数为 `client, message`。 |
| on_close | Fn | 否 | 无 | 客户端连接关闭时调用，回调参数为 `client`。 |
| on_error | Fn | 否 | 无 | 服务端监听或连接处理出错时调用，回调参数为 `message`。 |

## 客户端配置字段

`net.connect({type: 'tcp', ...})` 使用以下字段：

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `tcp`。 |
| host | String | 是 | 无 | TCP 服务端主机名或 IP 地址。 |
| port | Int | 是 | 无 | TCP 服务端端口号。 |
| timeout | Int | 否 | `0` | 连接、读取、写入超时时间，单位毫秒；小于等于 0 表示不设置超时。 |

## 返回值

| 类型 | 说明 |
|------|------|
| TcpServer | `net.listen({type:'tcp'})` 返回的 TCP 服务端句柄。 |
| TcpClient | `net.connect({type:'tcp'})` 返回的 TCP 客户端句柄，也会作为服务端回调中的 client 参数。 |

## TcpServer 字段和方法

| 名称 | 类型 | 说明 |
|------|------|------|
| addr | String | 实际监听地址，格式通常为 `host:port`；bind 端口为 0 时可从这里读取系统分配后的端口。 |
| type | String | 固定为 `tcp`。 |
| close() | Fn -> Bool | 关闭 TCP 服务端监听，成功返回 true。 |

## TcpClient 字段和方法

| 名称 | 类型 | 说明 |
|------|------|------|
| addr | String | 客户端连接的远端地址，格式通常为 `host:port`。 |
| type | String | 固定为 `tcp`。 |
| write(data) | Fn -> Int | 写入 String、字节数组或 Bytes，返回写入字节数。 |
| send(data) | Fn -> Int | `write(data)` 的同义方法。 |
| read() | Fn -> String | 同步读取一段数据，按 UTF-8 lossy 转为字符串；用于 `net.connect` 创建的客户端。 |
| read_bytes() | Fn -> Bytes | 同步读取一段原始字节；用于 `net.connect` 创建的客户端。 |
| close() | Fn -> Bool | 关闭 TCP 连接，成功返回 true。 |

## 回调参数

| 回调 | 参数 | 说明 |
|------|------|------|
| on_connect | client: TcpClient | 新客户端连接成功时触发。 |
| on_message | client: TcpClient, message: String/Bytes | 收到客户端数据时触发；`binary: true` 时 message 为 Bytes，否则为兼容字符串。 |
| on_close | client: TcpClient | 客户端连接关闭时触发。 |
| on_error | message: String | 服务端或连接处理错误时触发。 |

## 示例

```bt
// 监听本机随机空闲端口，适合测试。
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:0'
})

result = server.type
server.close()

// 输出：tcp
print result
```

## 注意事项

- on_message 回调参数为 client 和 message。默认 message 是按 UTF-8 lossy 转换后的字符串；监听配置 `binary: true` 时为 Bytes。
- write/send 返回写入字节数。read 返回字符串，read_bytes 返回 Bytes。
- 服务端 `on_connect/on_message/on_close` 回调中的 client 由后台读任务驱动，应通过 `on_message` 接收数据，不要再调用 `client.read()` 双读同一个连接。
- TCP 服务端 accept、连接读取和写入调度使用共享 Tokio runtime，不再为每个连接创建独立读取线程。
- 单条读写消息受 `BT_NET_MESSAGE_LIMIT` 限制，默认 1048576 字节。
- 服务端回调中的连接写入会进入单连接有界写队列，队列长度由 `BT_NET_WRITE_QUEUE` 控制，默认 1024。
- 网络事件队列满时，TCP 消息事件会触发连接关闭，并增加 `BT.stats().net.event_queue_rejected`。
- `BT_NET_IDLE_TTL_MS` 大于 0 时，服务端连接超过该时间没有收到数据会触发错误回调并关闭。