# net TCP communication

## Function

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

## Server syntax

```bt
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:9000',
    on_connect: fn(client) {},
    on_message: fn(client, message) {},
    on_close: fn(client) {},
    on_error: fn(message) {}
})
```

## Client syntax

```bt
client = net.connect({type: 'tcp', host: '127.0.0.1', port: 9000, timeout: 3000})
client.write('ping')
text = client.read()
client.close()
```

## Server configuration field

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

| Field | Type | Required | Default value | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `tcp`. |
| bind | String | Yes | None | TCP listening address in `host:port` format, for example `127.0.0.1:9000`. 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_connect | Fn | No | None | Called when the client connection is successful, the callback parameter is `client`. |
| on_message | Fn | No | None | Called when client data is received, the callback parameter is `client, message`. |
| on_close | Fn | No | None | Called when the client connection is closed, the callback parameter is `client`. |
| on_error | Fn | No | None | Called when there is an error in server monitoring or connection processing, the callback parameter is `message`. |

## The client configuration field

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

| Field | Type | Required | Default | Description |
|------|------|------|------|------|
| type | String | Yes | None | Fixed to `tcp`. |
| host | String | Yes | None | TCP server host name or IP address. |
| port | Int | Yes | None | TCP server port number. |
| timeout | Int | No | `0` | Connection, read, and write timeout, in milliseconds; less than or equal to 0 means no timeout is set. |

## Return Value

| Type | Description |
|------|------|
| TcpServer | The TCP server handle returned by `net.listen({type:'tcp'})`. |
| TcpClient | The TCP client handle returned by `net.connect({type:'tcp'})` will also be used as the client parameter in the server callback. |

## TcpServer 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 `tcp`. |
| close() | Fn -> Bool | Close TCP server monitoring, return true successfully. |

## TcpClient fields and methods

| Name | Type | Description |
|------|------|------|
| addr | String | The remote address of the client connection, usually in the format `host:port`. |
| type | String | Fixed to `tcp`. |
| write(data) | Fn -> Int | Write to String, byte array or Bytes and return the number of bytes written. |
| send(data) | Fn -> Int | Synonymous method for `write(data)`. |
| read() | Fn -> String | Synchronously read a piece of data and convert it to a string according to UTF-8 lossy; used for clients created by `net.connect`. |
| read_bytes() | Fn -> Bytes | Synchronously read a segment of raw bytes; used for clients created by `net.connect`. |
| close() | Fn -> Bool | Close the TCP connection and return true on success. |

## Callback parameter

| Callback | Parameter | Description |
|------|------|------|
| on_connect | client: TcpClient | Triggered when the new client connection is successful. |
| on_message | client: TcpClient, message: String/Bytes | Triggered when client data is received; when `binary: true`, message is Bytes, otherwise it is a compatible string. |
| on_close | client: TcpClient | 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, suitable for testing.
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:0'
})

result = server.type
server.close()

// Output: tcp
print result
```

## Notes

- The on_message callback parameters are client and message. The default message is a string converted by UTF-8 lossy; it is Bytes when the monitoring configuration is `binary: true`.
- write/send returns the number of bytes written. read returns a string and read_bytes returns Bytes.
- The client in the server-side `on_connect/on_message/on_close` callback is driven by the background read task and should receive data through `on_message`. Do not call `client.read()` to double read the same connection.
- TCP server accept, connection read and write scheduling use the shared Tokio runtime, no longer creating independent read threads for each connection.
-A single read and write message is limited by `BT_NET_MESSAGE_LIMIT` and defaults to 1048576 bytes.
- Connection writes in the server callback will enter the 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 TCP message event will trigger the connection to be closed and `BT.stats().net.event_queue_rejected` will be added.
- When `BT_NET_IDLE_TTL_MS` is greater than 0, if the server connection does not receive data for more than this time, an error callback will be triggered and closed.