net WebSocket communication

net WebSocket communication

Function

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

Server syntax

Client syntax

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

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.