# net.listen

## Function

Start the Web, TCP, UDP or WebSocket listening service.

## Syntax

```bt
net.listen(config)
```

## Parameters

| Parameter | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| config | Object | Yes | None | The listening configuration object. The public fields are shown below. For protocol-specific fields, please see the corresponding protocol document. |

## Public configuration field

 All listening types of `net.listen(config)` select the protocol through `type` and specify the listening address through `bind`. It is recommended that all listening configurations explicitly write out `type` and `bind`, so that codes, documents and AI tools can stably identify the service entrance.

| Field | Type | Required | Default value | Description |
| ------ | ------ | ------ | ------ | ------ |
| type | String | Yes | None | The listening protocol type. Optional values are `web`, `tcp`, `udp`, `ws`. |
| bind | String | Required for tcp/udp/ws; recommended for web | web defaults to `0.0.0.0:8080` | Listening address in `host:port` format, such as `127.0.0.1:9000` or `0.0.0.0:8080`. When the port is `0`, the operating system allocates an available port. |
| binary | Bool | tcp/udp/ws Optional | false | When true, the message callback receives Bytes; the default behavior is to maintain String compatibility. |

Protocol exclusive fields are placed on the corresponding page description:

| type | Exclusive document | Description |
| ------ | ------ | ------ |
| web | [Web service ](/en/docs/net/web) | Site sites, static directory, upload temporary directory, TLS and other Web service configurations. |
| tcp | [TCP communication ](/en/docs/net/tcp) | TCP server event callback and client reading and writing. |
| udp | [UDP communication ](/en/docs/net/udp) | UDP message callback and sending target address. |
| ws | [WebSocket communication ](/en/docs/net/websocket) | WebSocket routing, connection callbacks and message callbacks. |

## Return Value

| Type | Description |
| ------ | ------ |
| `WebServer` `TcpServer` `UdpSocket` `WsServer` | Press type to return the corresponding service handle. |

## Service handle public field

| Field | Type | Description |
| ------ | ------ | ------ |
| addr | String | Actual listening address, usually in the format `host:port`; `bind` port When writing `0`, the port allocated by the system can be read from here. |
| type | String | Service type. Web returns `web`, TCP returns `tcp`, UDP returns `udp`, and WebSocket returns `ws`. |

## Service handle public method

| Method | Return value | Description |
| ------ | ------ | ------ |
| close() | Bool | Close the listening service or socket, return true on success. |

## Examples

```bt
//Listen to the local random idle port; the real port can be read through server.addr.
server = net.listen({
    type: 'tcp',
    bind: '127.0.0.1:0'
})
result = server.addr
server.close()

//Output example: 127.0.0.1:52341
print result
```

## Notes

- The shorthand net.listen is equivalent to net().listen.
- `bind` must contain the port; missing or invalid port will throw an error.
- `127.0.0.1` only allows local access, `0.0.0.0` will listen to all network card addresses.
 - TCP, UDP, WebSocket listening services use a shared Tokio runtime, and background events are delivered to the VM through bounded queues.
- It is recommended to set `binary: true` for TCP, UDP, and WebSocket binary protocols to avoid early conversion of callback parameters into strings.
 - Network event queue and connection resource limits are described in the net configuration description of [BT.stats](/en/docs/bt/stats).