# net WebSocket communication

## Function

`net.listen({type: 'ws'})` starts the WebSocket server, `net.connect({type: 'ws'})` creates the WebSocket client.

## Server syntax

```bt
server = net.listen({
    type: 'ws',
    bind: '127.0.0.1:9002',
    route: '/ws',
    on_connect: fn(socket) {},
    on_message: fn(socket, message) {},
    on_close: fn(socket) {},
    on_error: fn(message) {}
})
```

## Client syntax

```bt
socket = net.connect({type: 'ws', url: 'ws://127.0.0.1:9002/ws'})
socket.on_message(fn(message) {})
socket.on_close(fn() {})
socket.on_error(fn(message) {})
socket.send('hello')
socket.close()
```

## Server configuration field

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

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `ws`. |
| bind | String | Yes | None | WebSocket server listening address in `host:port` format, such as `127.0.0.1:9002`. When the port is `0`, the operating system allocates an available port. |
| route | String | No | `/ws` | WebSocket handshake path. The client URL path must match this value. |
| binary | Bool | No | false | When true, the message parameter of on_message on the server returns Bytes; the default behavior is to maintain String compatibility. |
| on_connect | Fn | No | None | Called when the client connection is successful, the callback parameter is `socket`. |
| on_message | Fn | No | None | Called when a client message is received, the callback parameter is `socket, message`. |
| on_close | Fn | No | None | Called when the client connection is closed, the callback parameter is `socket`. |
| on_error | Fn | No | None | Called when the server or connection handles errors, the callback parameter is `message`. |

## The client configuration field

`net.connect({type: 'ws', ...})` uses the following fields:

| Field | Type | Required | Default | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `ws`. |
| url | String | Yes | None | WebSocket complete connection address, such as `ws://127.0.0.1:9002/ws`. |

## Return Value

| Type | Description |
|------|------|
| WsServer | WebSocket server handle returned by `net.listen({type:'ws'})`. |
| WsSocket | WebSocket connection handle. Both the socket in the server callback and the client `net.connect({type:'ws'})` return value use this type. |

## WsServer fields and methods

| Name | Type | Description |
|------|------|------|
| addr | String | The actual listening address, the format is usually `host:port`; when the bind port is 0, the port allocated by the system can be read from here. |
| type | String | Fixed to `ws`. |
| close() | Fn -> Bool | Close WebSocket server monitoring, return true successfully. |

## WsSocket fields and methods

| Name | Type | Description |
|------|------|------|
| addr | String | WebSocket peer address or connection target address, usually in the format `host:port`. |
| type | String | Fixed to `ws`. |
| send(data) | Fn -> Bool | Send WebSocket message; String uses text frame, Bytes or byte array uses binary frame, returns true successfully. |
| write(data) | Fn -> Bool | Synonymous method of `send(data)`. |
| close() | Fn -> Bool | Close the WebSocket connection and return true on success. |
| on_message(fn(message) {}, binary) | Fn -> WsSocket | Client connection handle registers message callback; when the second parameter is true, message is Bytes. |
| on_close(fn() {}) | Fn -> WsSocket | Client connection handle registration close callback. |
| on_error(fn(message) {}) | Fn -> WsSocket | Client connection handle registration error callback. |

## Server callback parameters

| Callback | Parameters | Description |
|------|------|------|
| on_connect | socket: WsSocket | Triggered when the new client connection is successful. |
| on_message | socket: WsSocket, message: String/Bytes | Triggered when a client message is received; when `binary: true`, message is Bytes, otherwise it is a compatible string. |
| on_close | socket: WsSocket | Triggered when the client connection is closed. |
| on_error | message: String | Triggered when the server or connection handles errors. |

## Examples

```bt
//Listen to the local random idle port and limit the WebSocket path to /ws.
server = net.listen({
    type: 'ws',
    bind: '127.0.0.1:0',
    route: '/ws'
})

result = server.type
server.close()

// Output: ws
print result
```

## Notes

- Server route defaults to /ws.
 - WebSocket read() does not support synchronous reads; messages are distributed via background event callbacks.
- send/write sends a binary frame when Bytes or a byte array is passed in; sends a text frame when a String is passed in.
- The default message of on_message is a string; when the server listening configuration is `binary: true` or the client `on_message(fn, true)`, it is Bytes.
- WebSocket server monitoring, client connection, and message reading and writing use the shared Tokio runtime.
 - A single text or binary message is limited by `BT_NET_MESSAGE_LIMIT`, default 1048576 bytes.
- send/write will enter a single-connection bounded write queue. The queue length is controlled by `BT_NET_WRITE_QUEUE` and defaults to 1024.
 - When the network event queue is full, the WebSocket message event triggers a connection close and increments `BT.stats().net.event_queue_rejected`.
- When `BT_NET_IDLE_TTL_MS` is greater than 0, if the connection does not receive a message for more than this time, an error callback will be triggered and closed.