0.2.4 • Published 8 months ago

rxprotoplex-pingpong v0.2.4

Weekly downloads
-
License
MIT
Repository
-
Last release
8 months ago

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:

OptionTypeDefaultDescription
channelstring \| Uint8Array \| Buffer$PINGPONG$The channel identifier for the connection.
intervalnumber6000Interval (in milliseconds) between "ping" messages.
connectionTimeoutnumber1000Timeout (in milliseconds) for initial connection setup.
retryDelaynumber1000Delay (in milliseconds) between reconnection attempts.
reconnectAttemptCountnumber3Maximum number of reconnection attempts before giving up.
logbooleanfalseEnables console logging for connection events.
onPingPongFailureFunctionundefinedCustom 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.

API Reference

connectAndPingPong$(plex, config)

Initiates a connection as the initiator on the provided Plex instance and manages a ping-pong mechanism to maintain connection health.

Parameters:

  • plex: The Plex connection object from rxprotoplex.
  • config: Configuration object (see Options).

Returns:

An RxJS Observable that emits:

  • { type: 'ping', plex } for sent pings.
  • { type: 'pong', plex } for received pongs.
  • Error or completion signals when the connection is lost or closed.

listenAndConnectionAndPingPong$(plex, config)

Creates a listening connection on the provided Plex instance, automatically responding to ping messages to maintain connection health.

Parameters:

  • plex: The Plex connection object from rxprotoplex.
  • config: Configuration object (see Options).

Returns:

An RxJS Observable that emits:

  • { type: 'ping', plex } for sent pings.
  • { type: 'pong', plex } for received pongs.
  • Error or completion signals when the connection is lost or closed.

License

MIT License

0.2.4

8 months ago

0.2.2

8 months ago

0.2.1

8 months ago

0.1.0

8 months ago