@sutext/cable

A lightweight JavaScript client library for Cable protocol, providing a simple and reliable way to communicate with Cable servers over WebSocket.

Features

- Easy-to-use API for WebSocket communication
- Support for different Quality of Service (QoS) levels
- Automatic reconnection with configurable backoff strategies
- Request-response communication pattern
- Built-in ping/pong keep-alive mechanism
- TypeScript support with full type definitions
- Lightweight with no external dependencies

Installation

``bash
npm install @sutext/cable
`

Basic Usage

$3

`typescript
import { Client, Identity, Status, Handler } from '@sutext/cable';

// Create a new client instance
const client = new Client('ws://localhost:1881', {
handler: {
onStatus: (status) => {
console.log('Connection status:', Status[status]);
if (status === Status.Opened) {
console.log('Connected to server!');
}
},
onMessage: (message) => {
console.log('Received message:', message);
},
onRequest: (request) => {
// Handle incoming requests
return request.response(0, new Uint8Array());
},
},
});

// Connect to the server
const identity = new Identity('user123', 'client456', 'password789');
client.connect(identity);
`

$3

`typescript
// Send a simple message (QoS 0 - at most once)
client.send({
kind: 1,
payload: new TextEncoder().encode('Hello, server!'),
});

// Send a message with QoS 1 (at least once)
client.send({
qos: 1,
kind: 2,
payload: new TextEncoder().encode('Important message'),
});
`

$3

`typescript
// Send a request and wait for response
client
.request('get_status', new Uint8Array())
.then((response) => {
console.log('Response received:', new TextDecoder().decode(response.body));
})
.catch((error) => {
console.error('Request failed:', error);
});
`

$3

`typescript
import { Client, ExponentialBackoff } from 'js-cable';

const client = new Client('ws://localhost:8080');

// Configure automatic reconnection with exponential backoff
client.autoRetry({
limit: 5, // Maximum 5 retry attempts
backoff: new ExponentialBackoff(2, 0.1), // Exponential backoff with jitter
});
`

API Reference

$3

The Client class is the main entry point for communicating with the Cable server.

#### Constructor

`typescript
constructor(url: string, options?: Options)
`

- url: WebSocket server URL
- options: Optional configuration options
- pingInterval: Ping interval in milliseconds (default: 30000)
- pingTimeout: Ping timeout in milliseconds (default: 5000)
- requestTimeout: Request timeout in milliseconds (default: 10000)
- messageTimeout: Message timeout in milliseconds (default: 10000)
- messageMaxRetry: Maximum number of message retries (default: 5)
- handler: Custom event handler

#### Methods

- connect(identity: Identity): Connect to the server
- close(code?: CloseCode): Close the connection
- autoRetry(opts: { limit?: number; backoff?: Backoff; filter?: RetryFilter }): Configure automatic reconnection
- send(msg: Message): Send a message to the server
- request(method: string, body: Uint8Array, props?: Map): Send a request and wait for response

#### Properties

- id: Client identity information
- status: Current connection status
- isReady: Whether the connection is ready

$3

Represents client identification information.

`typescript
constructor(userID?: string, clientID?: string, password?: string)
`

$3

Interface for sending messages.

`typescript
interface Message {
qos?: MessageQos;
kind?: MessageKind;
props?: Map;
payload?: Uint8Array;
}
`

$3

The library provides several backoff strategies for automatic reconnection:

- ExponentialBackoff: Exponential delay with jitter
- LinearBackoff: Linear delay with jitter
- RandomBackoff: Random delay within a range
- ConstBackoff: Constant delay

Status Codes

$3

- Unknown: Connection status is unknown
- Opening: Connection is being established
- Opened: Connection is established and ready
- Closing: Connection is closing
- Closed: Connection is closed

$3

- NotReady: Connection is not ready
- RequestTimeout: Request timed out
- MessageTimeout`: Message timed out

Protocol

The Cable protocol is a lightweight binary protocol designed for efficient communication over WebSocket. It supports:

- Connection establishment and authentication
- Message publishing with different QoS levels
- Request-response communication
- Ping/pong keep-alive
- Graceful connection closure

License

Apache 2.0