# net 网络通信库

## 功能

net 提供 Web 服务适配、TCP、UDP、WebSocket、DNS 解析和本机网络信息能力。既可以使用 net.listen() 短写，也可以使用 net().listen()。

## API 列表

| API | 说明 |
| ------ | ------ |
| [net.listen](/zh-hans/docs/net/listen) | 启动 Web、TCP、UDP 或 WebSocket 监听服务。 |
| [net.connect](/zh-hans/docs/net/connect) | 建立 TCP、UDP 或 WebSocket 客户端连接。 |
| [net.resolve](/zh-hans/docs/net/resolve) | 解析主机名并返回去重后的 IP 地址数组。 |
| [net.interfaces](/zh-hans/docs/net/interfaces) | 读取本机网络接口信息。 |
| [net.local_ip](/zh-hans/docs/net/local_ip) | 读取默认本机 IP。 |

## 示例

```bt
ips = net.resolve('localhost')
result = type(ips)

// 输出：Array
print result
```

## 注意事项

- 所有协议类型字段使用小写字符串：web、tcp、udp、ws。
- 后台网络服务会让 VM 等待事件并分发回调。
- TCP、UDP、WebSocket 后台 I/O 使用共享 Tokio runtime；脚本 API 仍保持同步调用表面。
- TCP、UDP、WebSocket 监听配置支持 `binary: true`，on_message 回调会直接收到 Bytes，避免二进制报文提前按字符串转换。
- 网络事件队列是有界队列，默认 `BT_NET_EVENT_QUEUE=4096`。队列满时不会无限堆积内存；TCP/WebSocket 消息事件会触发连接关闭，UDP 报文会被丢弃，并可通过 `BT.stats().net.event_queue_rejected` 观察。
- 资源上限可通过 `BT_NET_CONNECTION_LIMIT`、`BT_NET_MESSAGE_LIMIT`、`BT_NET_WRITE_QUEUE`、`BT_NET_IDLE_TTL_MS` 调整，配置错误会在第一次使用 net 能力时报错。
- TCP、UDP、WebSocket 的常见错误会输出中文标准化信息，包括端口占用、权限不足、连接拒绝/重置、握手失败、写队列满和消息超限。
- `examples/net-stress-*.bt` 提供 TCP、UDP、WebSocket 压测脚本；需要验证队列满或消息超限时，可在启动前调低 `BT_NET_EVENT_QUEUE`、`BT_NET_WRITE_QUEUE` 或 `BT_NET_MESSAGE_LIMIT`。