@push.rocks/smartsocket

Provides easy and secure websocket communication mechanisms, including server and client implementation, function call routing, connection management, and tagging.

readme.md for @push.rocks/smartsocket

Easy and secure WebSocket communication with native WebSocket support πŸ”Œ

Features

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

Install

npm install @push.rocks/smartsocket --save

or with pnpm:

pnpm add @push.rocks/smartsocket

Usage

Quick Start - Server

import { Smartsocket, SocketFunction } from '@push.rocks/smartsocket';

// Create server
const server = new Smartsocket({
  alias: 'myServer',
  port: 3000
});

// Define a function that clients can call
const greetFunction = new SocketFunction({
  funcName: 'greet',
  funcDef: async (data, socketConnection) => {
    console.log(`Received greeting from ${data.name}`);
    return { message: `Hello, ${data.name}!` };
  }
});

server.addSocketFunction(greetFunction);

// Start the server
await server.start();
console.log('WebSocket server running on port 3000');

Quick Start - Client

import { SmartsocketClient } from '@push.rocks/smartsocket';

// Create client
const client = new SmartsocketClient({
  url: 'http://localhost',
  port: 3000,
  alias: 'myClient',
  autoReconnect: true
});

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

// Call server function
const response = await client.serverCall('greet', { name: 'Alice' });
console.log(response.message); // "Hello, Alice!"

Connection Options

The SmartsocketClient supports several configuration options:

const client = new SmartsocketClient({
  url: 'http://localhost',           // Server URL (http/https)
  port: 3000,                         // Server port
  alias: 'myClient',                  // Client identifier
  autoReconnect: true,                // Auto-reconnect on disconnect
  maxRetries: 100,                    // Max reconnection attempts (default: 100)
  initialBackoffDelay: 1000,          // Initial backoff in ms (default: 1000)
  maxBackoffDelay: 60000              // Max backoff in ms (default: 60000)
});

Two-Way Function Calls

Both server and client can define and call functions on each other:

// Server calling client
const clientFunction = new SocketFunction({
  funcName: 'clientTask',
  funcDef: async (data) => {
    return { result: 'Task completed' };
  }
});

// On client
client.addSocketFunction(clientFunction);

// On server - call the client
const socketConnection = server.socketConnections.findSync(conn => conn.alias === 'myClient');
const result = await server.clientCall('clientTask', { task: 'doSomething' }, socketConnection);

Connection Tagging

Tag connections to identify and group them:

// On client
await client.addTag({
  id: 'role',
  payload: 'admin'
});

// On server - find tagged connections
const adminConnections = server.socketConnections.getArray().filter(async conn => {
  const tag = await conn.getTagById('role');
  return tag?.payload === 'admin';
});

// Server can also tag connections
await socketConnection.addTag({
  id: 'verified',
  payload: true
});

Integration with Smartserve

Use smartsocket with @push.rocks/smartserve for advanced HTTP/WebSocket handling:

import { SmartServe } from '@push.rocks/smartserve';
import { Smartsocket } from '@push.rocks/smartsocket';

// Create smartsocket without a port (hooks mode)
const smartsocket = new Smartsocket({ alias: 'myServer' });

// Get WebSocket hooks and pass them to SmartServe
const wsHooks = smartsocket.getSmartserveWebSocketHooks();
const smartserve = new SmartServe({
  port: 3000,
  websocket: wsHooks
});

// Add socket functions as usual
smartsocket.addSocketFunction(myFunction);

// Start smartserve (smartsocket hooks mode doesn't need start())
await smartserve.start();

Handling Disconnections

The client automatically handles reconnection with exponential backoff:

const client = new SmartsocketClient({
  url: 'http://localhost',
  port: 3000,
  alias: 'myClient',
  autoReconnect: true,
  maxRetries: 10,
  initialBackoffDelay: 500,
  maxBackoffDelay: 5000
});

// Listen for connection status changes
client.eventSubject.subscribe(status => {
  console.log('Connection status:', status);
  // Status can be: 'new', 'connecting', 'connected', 'disconnecting', 'timedOut'
});

await client.connect();

// Manually disconnect without auto-reconnect
await client.disconnect();

// Stop the client completely (disables auto-reconnect)
await client.stop();

Secure Connections (WSS)

For secure WebSocket connections, use HTTPS URLs:

const client = new SmartsocketClient({
  url: 'https://secure.example.com',  // HTTPS triggers WSS
  port: 443,
  alias: 'secureClient'
});

TypedRequest Integration

For strongly-typed RPC calls, define interfaces:

interface IGreetRequest {
  method: 'greet';
  request: { name: string };
  response: { message: string };
}

// Type-safe server call
const response = await client.serverCall<IGreetRequest>('greet', { name: 'Bob' });
// response is typed as { message: string }

API Reference

Smartsocket (Server)

Method Description
start() Start the WebSocket server (not needed in hooks mode)
stop() Stop the server and close all connections
addSocketFunction(fn) Register a function that clients can call
clientCall(funcName, data, connection) Call a function on a specific client
getSmartserveWebSocketHooks() Get hooks for smartserve integration

SmartsocketClient

Method Description
connect() Connect to the server
disconnect() Disconnect from the server
stop() Disconnect and disable auto-reconnect
serverCall(funcName, data) Call a function on the server
addSocketFunction(fn) Register a function the server can call
addTag(tag) Add a tag to the connection
getTagById(id) Get a tag by its ID
removeTagById(id) Remove a tag by its ID

SocketFunction

const fn = new SocketFunction({
  funcName: 'myFunction',
  funcDef: async (data, socketConnection) => {
    // data: the request payload
    // socketConnection: the calling connection
    return { result: 'response' };
  }
});

Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”         WebSocket          β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚  SmartsocketClient  │◄────────────────────────►│    Smartsocket     β”‚
β”‚    (Browser/Node)    β”‚     Native WebSocket    β”‚      (Server)       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                            β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
        β”‚                                                β”‚
        β”‚ SocketFunction                    SocketFunction β”‚
        β”‚ (serverCall)                        (clientCall) β”‚
        β”‚                                                β”‚
        └──────────────── RPC-style Calls β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the LICENSE file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

Company Information

Task Venture Capital GmbH Registered at District Court Bremen HRB 35230 HB, Germany

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

changelog.md for @push.rocks/smartsocket

2025-12-04 - 4.0.0 - BREAKING CHANGE(socketconnection)

Stricter typings, smartserve hooks, connection fixes, and tag API change

2025-12-03 - 3.0.0 - BREAKING CHANGE(smartsocket)

Replace setExternalServer with hooks-based SmartServe integration and refactor SocketServer to support standalone and hooks modes

2025-03-10 - 2.1.0 - feat(SmartsocketClient)

Improve client reconnection logic with exponential backoff and jitter; update socket.io and @types/node dependencies

2024-05-29 - 2.0.27 - docs

update description

2024-04-26 to 2024-03-30 - 2.0.26 … 2.0.24 - core & configuration

A series of internal fixes and configuration tweaks.

2023-09-10 to 2023-07-21 - 2.0.23 … 2.0.20 - core

Multiple minor core fixes were applied in rapid succession.

2023-07-21 to 2023-03-20 - 2.0.19 … 2.0.15 - core

Routine internal updates addressing core functionality.

2023-02-07 to 2022-03-24 - 2.0.14 … 2.0.0 - core

Further minor core updates were rolled out over several versions.

2022-03-14 - 1.2.22 - esm

A breaking change was introduced to switch the module system.

2022-01-20 to 2021-01-23 - 1.2.21 … 1.2.0 - core

A range of minor core fixes.

2020-12-26 - 1.1.71 - SmartsocketClient

New functionality in the socket client was added.

2020-12-26 to 2020-09-24 - 1.1.70 … 1.1.58 - core & test

A group of updates addressing both core mechanics and tests.

2019-11-08 to 2019-04-23 - 1.1.57 … 1.1.27 - core

Numerous versions in this period included only internal core fixes.

2019-01-31 to 2019-01-30 - 1.1.26 … 1.1.19 - build, docs & configuration

Updates went beyond the core, affecting build tooling and package metadata.

2018-03-19 to 2018-03-15 - 1.1.18 … 1.1.12 - core & docs

Several improvements touching both functionality and documentation.

2017-10-09 to 2017-07-07 - 1.1.11 … 1.1.07 - core & docs

Updates in this range improved both the internal mechanics and the developer‐facing materials.

2016-09-25 to 2016-09-03 - 1.1.6 … 1.1.3 - docs & core

Minor improvements in documentation and code quality.

2016-09-02 to 2016-08-16 - 1.1.2 … 1.1.1 - dependencies & security

Several housekeeping tasks to update dependencies and improve security.

2016-08-15 - 1.1.0 - docs

A documentation update was published.

2016-08-15 - 1.0.7 - networking

A key update made the socket client work bi-directionally, enabling mesh setups.

2016-08-14 to 2016-08-07 - 1.0.6 … 1.0.0 - internal changes

From the initial release onward, several internal improvements were introduced: