# net.connect

## 功能

建立 TCP、UDP 或 WebSocket 客户端连接。

## 语法

```bt
net.connect(config)
```

## 参数

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ |
| config | Object | 是 | 无 | 连接配置对象。公共字段和协议字段见下方。 |

## 连接配置字段

| 字段 | 类型 | 适用 type | 必填 | 默认值 | 说明 |
| ------ | ------ | ------ | ------ | ------ | ------ |
| type | String | 全部 | 是 | 无 | 连接协议类型。可选值为 `tcp`、`udp`、`ws`。 |
| host | String | tcp/udp | 是 | 无 | 远端主机名或 IP 地址，例如 `127.0.0.1`、`example.com`。 |
| port | Int | tcp/udp | 是 | 无 | 远端端口号，范围为 0 到 65535。 |
| timeout | Int | tcp | 否 | `0` | TCP 连接、读写超时时间，单位毫秒；小于等于 0 表示不设置超时。 |
| url | String | ws | 是 | 无 | WebSocket 完整连接地址，例如 `ws://127.0.0.1:9002/ws`。 |

## 返回值

| 类型 | 说明 |
| ------ | ------ |
| TcpClient/UdpSocket/WsSocket | 按 `type` 返回对应连接句柄。 |

## 连接句柄字段

| 字段 | 类型 | 说明 |
| ------ | ------ | ------ |
| addr | String | 连接目标或本地 socket 地址，格式通常为 `host:port`。 |
| type | String | 连接类型。TCP 返回 `tcp`，UDP 返回 `udp`，WebSocket 返回 `ws`。 |

## 连接句柄方法

| 类型 | 方法 | 返回值 | 说明 |
| ------ | ------ | ------ | ------ |
| TcpClient | write(data) / send(data) | Int | 写入 TCP String、字节数组或 Bytes，返回写入字节数。 |
| TcpClient | read() | String | 同步读取一段 TCP 数据，按 UTF-8 lossy 转为字符串。 |
| TcpClient | read_bytes() | Bytes | 同步读取一段 TCP 原始字节。 |
| TcpClient | close() | Bool | 关闭 TCP 连接。 |
| UdpSocket | send(data) | Int | 向 connect 配置中的默认远端地址发送 UDP 数据，返回发送字节数。 |
| UdpSocket | send(data, addr) | Int | 向指定 `host:port` 发送 UDP 数据，返回发送字节数。 |
| UdpSocket | close() | Bool | 关闭 UDP socket。 |
| WsSocket | send(data) / write(data) | Bool | 发送 WebSocket 消息；String 为文本帧，Bytes 或字节数组为二进制帧。 |
| WsSocket | close() | Bool | 关闭 WebSocket 连接。 |
| WsSocket | on_message(fn(message) {}, binary) | WsSocket | 注册 WebSocket 客户端消息回调；第二个参数为 true 时 message 为 Bytes。 |
| WsSocket | on_close(fn() {}) | WsSocket | 注册 WebSocket 客户端关闭回调。 |
| WsSocket | on_error(fn(message) {}) | WsSocket | 注册 WebSocket 客户端错误回调。 |

## 示例

```bt
// 建立 UDP 连接句柄，host 和 port 是默认发送目标。
client = net.connect({
    type: 'udp',
    host: '127.0.0.1',
    port: 8080
})

result = client.type
client.close()

// 输出：udp
print result
```

## 注意事项

- TCP 和 UDP 使用 `host`、`port` 字段；WebSocket 使用完整 `url` 字段。
- WebSocket 不支持同步 `read()`；请通过 `on_message()` 接收消息。
- 需要接收二进制消息时，TCP 可使用 `read_bytes()`，监听回调可在 `net.listen` 配置中设置 `binary: true`。