# net WebSocket 通信

## 功能

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

## 服务端语法

```bt
server = net.listen({
    type: 'ws',
    bind: '127.0.0.1:9002',
    route: '/ws',
    on_connect: fn(socket) {},
    on_message: fn(socket, message) {},
    on_close: fn(socket) {},
    on_error: fn(message) {}
})
```

## 客户端语法

```bt
socket = net.connect({type: 'ws', url: 'ws://127.0.0.1:9002/ws'})
socket.on_message(fn(message) {})
socket.on_close(fn() {})
socket.on_error(fn(message) {})
socket.send('hello')
socket.close()
```

## 服务端配置字段

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

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `ws`。 |
| bind | String | 是 | 无 | WebSocket 服务端监听地址，格式为 `主机:端口`，例如 `127.0.0.1:9002`。端口写 `0` 时由系统分配空闲端口。 |
| route | String | 否 | `/ws` | WebSocket 握手路径。客户端 URL 路径必须与该值一致。 |
| binary | Bool | 否 | false | 为 true 时，服务端 on_message 的 message 参数返回 Bytes；默认保持 String 兼容行为。 |
| on_connect | Fn | 否 | 无 | 客户端连接成功时调用，回调参数为 `socket`。 |
| on_message | Fn | 否 | 无 | 收到客户端消息时调用，回调参数为 `socket, message`。 |
| on_close | Fn | 否 | 无 | 客户端连接关闭时调用，回调参数为 `socket`。 |
| on_error | Fn | 否 | 无 | 服务端或连接处理错误时调用，回调参数为 `message`。 |

## 客户端配置字段

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

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `ws`。 |
| url | String | 是 | 无 | WebSocket 完整连接地址，例如 `ws://127.0.0.1:9002/ws`。 |

## 返回值

| 类型 | 说明 |
|------|------|
| WsServer | `net.listen({type:'ws'})` 返回的 WebSocket 服务端句柄。 |
| WsSocket | WebSocket 连接句柄。服务端回调中的 socket 和客户端 `net.connect({type:'ws'})` 返回值都使用该类型。 |

## WsServer 字段和方法

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

## WsSocket 字段和方法

| 名称 | 类型 | 说明 |
|------|------|------|
| addr | String | WebSocket 对端地址或连接目标地址，格式通常为 `host:port`。 |
| type | String | 固定为 `ws`。 |
| send(data) | Fn -> Bool | 发送 WebSocket 消息；String 走文本帧，Bytes 或字节数组走二进制帧，成功返回 true。 |
| write(data) | Fn -> Bool | `send(data)` 的同义方法。 |
| close() | Fn -> Bool | 关闭 WebSocket 连接，成功返回 true。 |
| on_message(fn(message) {}, binary) | Fn -> WsSocket | 客户端连接句柄注册消息回调；第二个参数为 true 时 message 为 Bytes。 |
| on_close(fn() {}) | Fn -> WsSocket | 客户端连接句柄注册关闭回调。 |
| on_error(fn(message) {}) | Fn -> WsSocket | 客户端连接句柄注册错误回调。 |

## 服务端回调参数

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

## 示例

```bt
// 监听本机随机空闲端口，并限定 WebSocket 路径为 /ws。
server = net.listen({
    type: 'ws',
    bind: '127.0.0.1:0',
    route: '/ws'
})

result = server.type
server.close()

// 输出：ws
print result
```

## 注意事项

- 服务端 route 默认 /ws。
- WebSocket read() 不支持同步读取；消息通过后台事件回调分发。
- send/write 传入 Bytes 或字节数组时发送二进制帧；传入 String 时发送文本帧。
- 默认 on_message 的 message 是字符串；服务端监听配置 `binary: true` 或客户端 `on_message(fn, true)` 时为 Bytes。
- WebSocket 服务端监听、客户端连接和消息读写使用共享 Tokio runtime。
- 单条文本或二进制消息受 `BT_NET_MESSAGE_LIMIT` 限制，默认 1048576 字节。
- send/write 会进入单连接有界写队列，队列长度由 `BT_NET_WRITE_QUEUE` 控制，默认 1024。
- 网络事件队列满时，WebSocket 消息事件会触发连接关闭，并增加 `BT.stats().net.event_queue_rejected`。
- `BT_NET_IDLE_TTL_MS` 大于 0 时，连接超过该时间没有收到消息会触发错误回调并关闭。