# 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` 时由系统分配空闲端口。 |
| 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 | 写入字符串数据，返回写入字节数。 |
| send(data) | Fn -> Int | `write(data)` 的同义方法。 |
| read() | Fn -> String | 同步读取一段数据，按 UTF-8 lossy 转为字符串。 |
| close() | Fn -> Bool | 关闭 TCP 连接，成功返回 true。 |

## 回调参数

| 回调 | 参数 | 说明 |
|------|------|------|
| on_connect | client: TcpClient | 新客户端连接成功时触发。 |
| on_message | client: TcpClient, message: String | 收到客户端数据时触发；message 是按 UTF-8 lossy 转换后的字符串。 |
| 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 转换后的字符串。
- write/send 返回写入字节数。read 返回字符串。