# net network communication library

## Function

net provides Web service adaptation, TCP, UDP, WebSocket, DNS resolution and native network information capabilities. You can use either the net.listen() shorthand or net().listen().

## API List

| API | Description |
| ------ | ------ |
| [net.listen](/en/docs/net/listen) | Start the Web, TCP, UDP or WebSocket listening service. |
| [net.connect](/en/docs/net/connect) | Establish a TCP, UDP, or WebSocket client connection. |
| [net.resolve](/en/docs/net/resolve) | Resolve the host name and return the deduplicated IP address array. |
| [net.interfaces](/en/docs/net/interfaces) | Read the local network interface information. |
| [net.local_ip](/en/docs/net/local_ip) | Read the default local IP. |

## Examples

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

// Output: Array
print result
```

## Notes

- Use lowercase strings for all protocol type fields: web, tcp, udp, ws.
 - The background network service causes the VM to wait for events and dispatch callbacks.
 - TCP, UDP, WebSocket background I/O uses shared Tokio runtime; scripting API still maintains synchronous call surface.
 - TCP, UDP, and WebSocket listening configurations support `binary: true`. The on_message callback will directly receive Bytes to avoid binary messages being converted into strings in advance.
 - The network event queue is a bounded queue, defaulting to `BT_NET_EVENT_QUEUE=4096`. When the queue is full, the memory will not accumulate indefinitely; TCP/WebSocket message events will trigger the connection to be closed, UDP packets will be discarded, and can be observed through `BT.stats().net.event_queue_rejected`.
- The resource limit can be adjusted through `BT_NET_CONNECTION_LIMIT`, `BT_NET_MESSAGE_LIMIT`, `BT_NET_WRITE_QUEUE`, `BT_NET_IDLE_TTL_MS`. Configuration errors will cause an error when using the net capability for the first time.
 - Common errors of TCP, UDP, and WebSocket will output Chinese standardized information, including port occupation, insufficient permissions, connection refused/reset, handshake failure, write queue full, and message limit exceeded.
- `examples/net-stress-*.bt` provides TCP, UDP, and WebSocket stress test scripts; when you need to verify that the queue is full or the message exceeds the limit, you can reduce `BT_NET_EVENT_QUEUE`, `BT_NET_WRITE_QUEUE`, or `BT_NET_MESSAGE_LIMIT` before starting.