Rxprotoplex-pingpong NPM

rxprotoplex-pingpong

A robust RxJS-based ping-pong mechanism leveraging rxprotoplex to maintain reliable, multiplexed connections over potentially unreliable networks. Designed for applications requiring real-time communication with connection health checks, it provides a heartbeat mechanism to detect and handle connectivity issues seamlessly.

Features

Heartbeat Mechanism: Sends "ping" and expects "pong" to confirm connection status, detecting and handling issues.
Reactive Event Handling: Built on RxJS for efficient management of "ping", "pong", and error events via observables.
Multiplexed Streams: Utilizes rxprotoplex to support multiple logical channels over a single physical connection.
Customizable Error Handling: Offers options for soft error handling or propagating failures as needed.
Graceful Cleanup: Ensures proper resource management and disconnection handling.

Installation

npm install rxprotoplex-pingpong

Usage

The library provides two main functions to manage connections:

connectAndPingPong$: Use this function to initiate a connection and periodically send "ping" messages.
listenAndConnectionAndPingPong$: Use this function to listen for incoming connections and respond with "pong" messages.

Each function returns an observable that emits { type, plex } for each event, where type is either "ping" or "pong", and plex is the associated connection.

Example: Initiating a Ping-Pong Connection

Use connectAndPingPong$ to initiate a connection that sends "ping" messages at regular intervals.

import { createPlexPair } from 'rxprotoplex';
import { connectAndPingPong$ } from 'rxprotoplex-pingpong';

// Create Plex instances
const [initiatorPlex, listenerPlex] = createPlexPair();

// Initiator starts ping-pong
const initiatorEvents$ = connectAndPingPong$(initiatorPlex, { 
    channel: '$PINGPONG$', 
    interval: 1000, 
    log: true 
});
initiatorEvents$.subscribe({
    next: ({ type, plex }) => console.log(`Initiator event: ${type} on plex:`, plex),
    error: (err) => console.error(`Initiator error: ${err.message}`),
    complete: () => console.log('Initiator connection completed'),
});

Example: Listening for a Ping-Pong Connection

Use listenAndConnectionAndPingPong$ to set up a listener connection that responds with "pong" to "ping" messages, keeping the connection alive.

import { listenAndConnectionAndPingPong$ } from 'rxprotoplex-pingpong';

const listenerEvents$ = listenAndConnectionAndPingPong$(listenerPlex, { 
    channel: '$PINGPONG$', 
    interval: 1000, 
    log: true 
});
listenerEvents$.subscribe({
    next: ({ type, plex }) => console.log(`Listener event: ${type} on plex:`, plex),
    error: (err) => console.error(`Listener error: ${err.message}`),
    complete: () => console.log('Listener connection completed'),
});

Configuration Options

The functions connectAndPingPong$ and listenAndConnectionAndPingPong$ accept a config object with the following options:

Option	Type	Default	Description
channel	`string \\| Uint8Array \\| Buffer`	$PINGPONG$	The channel identifier for the connection.
interval	`number`	`6000`	Interval (in milliseconds) between "ping" messages.
connectionTimeout	`number`	`1000`	Timeout (in milliseconds) for initial connection setup.
retryDelay	`number`	`1000`	Delay (in milliseconds) between reconnection attempts.
reconnectAttemptCount	`number`	`3`	Maximum number of reconnection attempts before giving up.
log	`boolean`	`false`	Enables console logging for connection events.
onPingPongFailure	`Function`	`undefined`	Custom handler for ping-pong failures (e.g., custom reconnection logic).

Advanced Example: Custom Failure Handling

You can provide a custom handler to manage connection failures without propagating errors, allowing for custom reconnection logic or other actions.

const initiatorEvents$ = connectAndPingPong$(initiatorPlex, {
    channel: '$CUSTOM_CHANNEL$',
    interval: 2000,
    log: true,
    onPingPongFailure: (error) => {
        console.warn('Custom handler: Connection lost.', error.message);
        // Implement reconnection or other fallback logic here
    },
});

Testing

To run tests, ensure brittle is installed as a dev dependency. Then, execute:

npm test

Test Coverage:

Heartbeat Communication: Validates the proper exchange of "ping" and "pong" messages.
Disconnection Handling: Ensures correct handling of connection timeouts or closures.
Error Propagation: Confirms that errors are emitted or handled as per the configuration.