# net UDP 通信

## 功能

`net.listen({type: 'udp'})` 创建 UDP 监听 socket，`net.connect({type: 'udp'})` 创建带默认远端地址的 UDP socket。

## 语法

```bt
server = net.listen({
    type: 'udp',
    bind: '127.0.0.1:9001',
    on_message: fn(message, remote_addr) {},
    on_error: fn(message) {}
})

client = net.connect({type: 'udp', host: '127.0.0.1', port: 9001})
client.send('ping')
client.close()
```

## 监听配置字段

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

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `udp`。 |
| bind | String | 是 | 无 | UDP 本地监听地址，格式为 `主机:端口`，例如 `127.0.0.1:9001`。端口写 `0` 时由系统分配空闲端口。 |
| binary | Bool | 否 | false | 为 true 时，on_message 的 message 参数返回 Bytes；默认保持 String 兼容行为。 |
| on_message | Fn | 否 | 无 | 收到 UDP 数据时调用，回调参数为 `message, remote_addr`。 |
| on_error | Fn | 否 | 无 | UDP socket 出错时调用，回调参数为 `message`。 |

## 连接配置字段

`net.connect({type: 'udp', ...})` 创建带默认远端地址的 UDP socket。

| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|------|------|
| type | String | 是 | 无 | 固定为 `udp`。 |
| host | String | 是 | 无 | 默认远端主机名或 IP 地址。 |
| port | Int | 是 | 无 | 默认远端端口号。 |

## 返回值

| 类型 | 说明 |
|------|------|
| UdpSocket | UDP socket 句柄。`net.listen({type:'udp'})` 返回监听 socket，`net.connect({type:'udp'})` 返回带默认远端地址的 socket。 |

## UdpSocket 字段和方法

| 名称 | 类型 | 说明 |
|------|------|------|
| addr | String | UDP socket 本地地址，格式通常为 `host:port`。 |
| type | String | 固定为 `udp`。 |
| send(data) | Fn -> Int | 向默认远端地址发送 String、字节数组或 Bytes，返回发送字节数；只适用于 `net.connect` 创建的 socket。 |
| send(data, addr) | Fn -> Int | 向指定 `host:port` 地址发送 String、字节数组或 Bytes，返回发送字节数。 |
| close() | Fn -> Bool | 关闭 UDP socket，成功返回 true。 |

## remote_addr 字段

`on_message(message, remote_addr)` 的 `remote_addr` 是对象，字段如下：

| 字段 | 类型 | 说明 |
|------|------|------|
| ip | String | 发送方 IP 地址。地址无法解析时保留原始地址文本。 |
| port | Int/Null | 发送方端口。地址无法解析端口时为 null。 |
| addr | String | 发送方完整地址文本，通常为 `ip:port`。 |

## 示例

```bt
// 创建 UDP 客户端 socket，并把默认远端地址设为 127.0.0.1:9001。
socket = net.connect({
    type: 'udp',
    host: '127.0.0.1',
    port: 9001
})

result = socket.type
socket.close()

// 输出：udp
print result
```

## 注意事项

- send(data, addr) 的 addr 可选；客户端模式未传 addr 时使用 connect 配置的默认远端地址。
- 监听模式的 UDP socket 没有默认远端地址，调用 send(data) 会报缺少目标地址；应使用 send(data, addr)。
- 默认 on_message 的 message 是字符串；监听配置 `binary: true` 时为 Bytes。
- UDP socket 使用共享 Tokio runtime 接收和发送报文。
- UDP 接收缓冲受 `BT_NET_MESSAGE_LIMIT` 限制，但不会超过 UDP 单报文有效负载上限 65507 字节。
- 网络事件队列满时，UDP 报文会被丢弃，并增加 `BT.stats().net.event_queue_rejected`。