# net.connect

## Function

 Establish a TCP, UDP or WebSocket client connection.

## Syntax

```bt
net.connect(config)
```

## Parameters

| Parameters | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| config | Object | Yes | None | Connection configuration object. Public fields and protocol fields are shown below. |

## Connection configuration field

| Field | Type | Applicable type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ | ------ |
| type | String | All | Yes | None | The connection protocol type. Optional values are `tcp`, `udp`, `ws`. |
| host | String | tcp/udp | Yes | None | Remote host name or IP address, such as `127.0.0.1`, `example.com`. |
| port | Int | tcp/udp | Yes | None | The remote port number, ranging from 0 to 65535. |
| timeout | Int | tcp | No | `0` | TCP connection, read and write timeout, in milliseconds; less than or equal to 0 means no timeout is set. |
| url | String | ws | Yes | None | WebSocket full connection address, such as `ws://127.0.0.1:9002/ws`. |

## Return Value

| Type | Description |
| ------ | ------ |
| TcpClient/UdpSocket/WsSocket | Press `type` to return the corresponding connection handle. |

## Connection handle field

| Field | Type | Description |
| ------ | ------ | ------ |
| addr | String | Connection target or local socket address, usually in the format `host:port`. |
| type | String | Connection type. TCP returns `tcp`, UDP returns `udp`, and WebSocket returns `ws`. |

## Connection handle method

| Type | Method | Return value | Description |
| ------ | ------ | ------ | ------ |
| TcpClient | write(data) / send(data) | Int | Writes a TCP String, byte array, or Bytes, returning the number of bytes written. |
| TcpClient | read() | String | Synchronously read a piece of TCP data and convert it to a string according to UTF-8 lossy. |
| TcpClient | read_bytes() | Bytes | Synchronously read a segment of TCP raw bytes. |
| TcpClient | close() | Bool | Close the TCP connection. |
| UdpSocket | send(data) | Int | Send UDP data to the default remote address in the connect configuration and return the number of bytes sent. |
| UdpSocket | send(data, addr) | Int | Send UDP data to the specified `host:port` and return the number of bytes sent. |
| UdpSocket | close() | Bool | Close UDP socket. |
| WsSocket | send(data) / write(data) | Bool | Send WebSocket message; String is text frame, Bytes or byte array is binary frame. |
| WsSocket | close() | Bool | Close the WebSocket connection. |
| WsSocket | on_message(fn(message) {}, binary) | WsSocket | Register WebSocket client message callback; when the second parameter is true, message is Bytes. |
| WsSocket | on_close(fn() {}) | WsSocket | Register the WebSocket client close callback. |
| WsSocket | on_error(fn(message) {}) | WsSocket | Register WebSocket client error callback. |

## Examples

```bt
 // Create UDP The connection handle, host and port are the default destinations.
client = net.connect({
    type: 'udp',
    host: '127.0.0.1',
    port: 8080
})

result = client.type
client.close()

// Output: udp
print result
```

## Notes

 - TCP and UDP use the `host`, `port` fields; WebSocket uses the full `url` field.
 - WebSocket does not support synchronous `read()`; please receive messages via `on_message()`.
- When you need to receive binary messages, TCP can use `read_bytes()`, and the listening callback can set `binary: true` in the `net.listen` configuration.