linebridge/docs/client/rtengine/index.md

RTEngineClient Documentation

Overview

RTEngineClient is a WebSocket client for real-time communication with backend services. It provides connection management, automatic reconnection, heartbeat monitoring, event handling, and topic-based subscriptions.

API Reference

Constructor

const client = new RTEngineClient({
  refName: "main",
  url: "wss://example.com/socket",
  token: "auth-token-here",
  autoReconnect: true
});

Parameter	Type	Default	Description
params.refName	string(optional)	"default"	Reference name for this client instance
params.url	string	-	WebSocket server URL to connect to
params.token	string(optional)	-	Authentication token to include in the connection
params.autoReconnect	boolean	true	Whether to automatically attempt reconnection
params.maxConnectRetries	number	Infinity	Maximum number of reconnection attempts
params.heartbeat	boolean	true	Whether to use heartbeat to monitor connection health

Static Properties

Property	Type	Description
version	string	Client library version
heartbeatTimeout	number	Timeout for heartbeat checks (10000ms)
reconnectTimeout	number	Delay between reconnection attempts (5000ms)

State Object

The client state can be accessed via client.state:

Property	Type	Description
id	string|null	Client ID assigned by the server
connected	boolean	Whether the client is currently connected
authenticated	boolean	Whether the client is authenticated
lastPing	number|null	Timestamp of the last ping sent
lastPong	number|null	Timestamp of the last pong received
latency	number|null	Current connection latency in milliseconds
reconnecting	boolean	Whether the client is attempting to reconnect
connectionRetryCount	number	Number of reconnection attempts made

Methods

connect()

Establishes a connection to the WebSocket server.

await client.connect();

Returns	Description
Promise	Resolves when the connection is established

disconnect()

Closes the current WebSocket connection.

await client.disconnect();

Returns	Description
Promise	Resolves to false if no connection exists, true otherwise

on(event, handler)

Registers an event handler.

client.on('message', (data) => {
  console.log('Message received:', data);
});

Parameter	Type	Description
event	string	Event name to listen for
handler	Function	Function to call when the event is received

off(event, handler)

Removes an event handler.

client.off('message', messageHandler);

Parameter	Type	Description
event	string	Event name to stop listening for
handler	Function	Handler function to remove

once(event, handler)

Registers a one-time event handler.

client.once('connected', () => {
  console.log('Connected!');
});

Parameter	Type	Description
event	string	Event name to listen for
handler	Function	Function to call once when the event is received

emit(event, data)

Sends an event to the WebSocket server.

await client.emit('chat:message', { text: 'Hello!' });

Parameter	Type	Description
event	string	Event name to emit
data	any	Data to send with the event
Returns	Promise<null|void>	Promise that resolves when the event is sent, or null if not connected

Topic Management

The client includes a TopicsController instance accessible via client.topics.

// Subscribe to a topic
await client.topics.subscribe('chat/room1');

// Listen for events on a specific topic
client.topics.on('chat/room1', 'message', handleMessage);

// Unsubscribe from a topic
await client.topics.unsubscribe('chat/room1');

Basic Usage Example

import RTEngineClient from './RTEngineClient';

// Initialize the client
const client = new RTEngineClient({
  url: 'wss://api.example.com/socket',
  token: 'user-auth-token'
});

// Connect to the server
await client.connect();

// Subscribe to a topic
await client.topics.subscribe('updates');

// Listen for specific events
client.on('notification', (data) => {
  console.log('New notification:', data);
});

// Listen for events on a specific topic
client.topics.on('updates', 'new_version', (data) => {
  console.log('New version available:', data.version);
});

// Send an event
await client.emit('user:status', { status: 'online' });

// Disconnect when done
await client.disconnect();