# net UDP communication

## Function

`net.listen({type: 'udp'})` creates a UDP listening socket, `net.connect({type: 'udp'})` creates a UDP socket with the default remote address.

## Syntax

```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()
```

## The listener configuration field

`net.listen({type: 'udp', ...})` uses the following fields:

| Field | Type | Required | Default | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `udp`. |
| bind | String | Yes | None | UDP local listening address in `host:port` format, such as `127.0.0.1:9001`. When the port is `0`, the operating system allocates an available port. |
| binary | Bool | No | false | When true, the message parameter of on_message returns Bytes; the default behavior is to maintain String compatibility. |
| on_message | Fn | No | None | Called when UDP data is received, the callback parameter is `message, remote_addr`. |
| on_error | Fn | No | None | Called when UDP socket error occurs, the callback parameter is `message`. |

## Connection configuration field

`net.connect({type: 'udp', ...})` creates a UDP socket with the default remote address.

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `udp`. |
| host | String | Yes | None | Default remote host name or IP address. |
| port | Int | Yes | None | Default remote port number. |

## Return Value

| Type | Description |
|------|------|
| UdpSocket | UDP socket handle. `net.listen({type:'udp'})` returns the listening socket, and `net.connect({type:'udp'})` returns the socket with the default remote address. |

## UdpSocket fields and methods

| Name | Type | Description |
|------|------|------|
| addr | String | UDP socket local address, usually in the format `host:port`. |
| type | String | Fixed to `udp`. |
| send(data) | Fn -> Int | Send String, byte array or Bytes to the default remote address and return the number of bytes sent; only applicable to sockets created by `net.connect`. |
| send(data, addr) | Fn -> Int | Send String, byte array or Bytes to the specified `host:port` address and return the number of bytes sent. |
| close() | Fn -> Bool | Close UDP socket, return true successfully. |

## remote_addr field

`remote_addr` of `on_message(message, remote_addr)` is an object, the fields are as follows:

| Field | Type | Description |
|------|------|------|
| ip | String | Sender IP address. The original address text is retained when the address cannot be resolved. |
| port | Int/Null | Sender port. null if the address cannot resolve the port. |
| addr | String | The sender's complete address text, usually `ip:port`. |

## Examples

```bt
 // Create a UDP client socket and set the default remote address to 127.0.0.1:9001.
socket = net.connect({
    type: 'udp',
    host: '127.0.0.1',
    port: 9001
})

result = socket.type
socket.close()

// Output: udp
print result
```

## Notes

- The addr of send(data, addr) is optional; when addr is not passed in client mode, the default remote address configured by connect is used.
- The UDP socket in listening mode does not have a default remote address, and calling send(data) will report that the target address is missing; send(data, addr) should be used.
- The default message of on_message is a string; when the listener is configured with `binary: true`, it is Bytes.
- UDP socket uses the shared Tokio runtime to receive and send messages.
 - The UDP receive buffer is limited by `BT_NET_MESSAGE_LIMIT`, but will not exceed the UDP single message payload limit of 65507 bytes.
- When the network event queue is full, UDP packets will be discarded and `BT.stats().net.event_queue_rejected` will be added.