@push.rocks/smartsocket 2.1.0 → 4.0.0

package/readme.md

@@ -1,149 +1,295 @@
 # @push.rocks/smartsocket
-easy and secure websocket communication
 
-## Install
+Easy and secure WebSocket communication with native WebSocket support 🔌
+
+## Features
+
+- 🚀 **Native WebSocket** - Uses native WebSocket API (browser) and `ws` library (Node.js)
+- 🔄 **Auto Reconnection** - Exponential backoff with configurable retry limits
+- 📡 **RPC-style Function Calls** - Define and call functions across server/client
+- 🏷️ **Connection Tagging** - Tag connections for easy identification and routing
+- 🔗 **Smartserve Integration** - Works seamlessly with `@push.rocks/smartserve`
+- 🔒 **Secure Communication** - WSS support for encrypted connections
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://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/](https://code.foss.global/) account to submit Pull Requests directly.
 
-To install @push.rocks/smartsocket, you can use npm or yarn as follows:
+## Install
 
 ```shell
 npm install @push.rocks/smartsocket --save
 ```
-or
+
+or with pnpm:
+
 ```shell
-yarn add @push.rocks/smartsocket
+pnpm add @push.rocks/smartsocket
 ```
 
 ## Usage
 
-@push.rocks/smartsocket offers a robust solution for easy and secure WebSocket communication, utilizing Typescript for clean and maintainable code. Below are comprehensive examples covering various scenarios and features provided by the module.
-
-### Getting Started
-
-First, ensure you've installed the module as shown in the "Install" section. Once installed, you can start using @push.rocks/smartsocket in your project.
-
-### Setting Up a WebSocket Server
-
-To create a WebSocket server that clients can connect to:
+### Quick Start - Server
 
 ```typescript
-import { Smartsocket } from '@push.rocks/smartsocket';
+import { Smartsocket, SocketFunction } from '@push.rocks/smartsocket';
 
-// Create a new instance of Smartsocket for the server.
-const server = new Smartsocket({ alias: 'myServer' });
+// Create server
+const server = new Smartsocket({
+  alias: 'myServer',
+  port: 3000
+});
 
-// Define a SocketFunction that clients can call
-server.addSocketFunction({
+// Define a function that clients can call
+const greetFunction = new SocketFunction({
   funcName: 'greet',
-  funcDef: async (data) => {
-    console.log(`Server received: ${data.message}`);
-    return { reply: `Hello, ${data.name}!` };
+  funcDef: async (data, socketConnection) => {
+    console.log(`Received greeting from ${data.name}`);
+    return { message: `Hello, ${data.name}!` };
   }
 });
 
-// Start the Smartsocket server
-server.start().then(() => {
-  console.log('WebSocket server is running...');
-});
-```
+server.addSocketFunction(greetFunction);
 
-### Creating a WebSocket Client
+// Start the server
+await server.start();
+console.log('WebSocket server running on port 3000');
+```
 
-Create a client that connects to the WebSocket server and interacts with it:
+### Quick Start - Client
 
 ```typescript
 import { SmartsocketClient } from '@push.rocks/smartsocket';
 
-// Create a SmartsocketClient instance and connect to the server
+// Create client
 const client = new SmartsocketClient({
-  url: 'ws://localhost',
+  url: 'http://localhost',
   port: 3000,
-  alias: 'myClient'
+  alias: 'myClient',
+  autoReconnect: true
 });
 
-client.connect().then(() => {
-  console.log('Connected to WebSocket server');
+// 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:
+
+```typescript
+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)
 });
+```
 
-// Define a function to call the server's 'greet' function
-async function greetServer(name) {
-  const response = await client.serverCall('greet', { name: name, message: 'Hello!' });
-  console.log(`Server replied: ${response.reply}`);
-}
+### Two-Way Function Calls
+
+Both server and client can define and call functions on each other:
 
-// Use the function
-greetServer('Alice');
+```typescript
+// 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);
 ```
 
-### Handling Disconnections and Reconnections
+### Connection Tagging
 
-@push.rocks/smartsocket provides mechanisms to handle client disconnections and attempt reconnections:
+Tag connections to identify and group them:
 
 ```typescript
-client.on('disconnect', () => {
-  console.log('Disconnected from server. Attempting to reconnect...');
-  client.connect();
+// 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
 });
 ```
 
-### Sending Binary Data
+### Integration with Smartserve
 
-The library supports the transmission of binary data efficiently:
+Use smartsocket with `@push.rocks/smartserve` for advanced HTTP/WebSocket handling:
 
 ```typescript
-import fs from 'fs';
+import { SmartServe } from '@push.rocks/smartserve';
+import { Smartsocket } from '@push.rocks/smartsocket';
 
-// Function to send a binary file to the server
-async function sendBinaryData(filePath) {
-  const fileBuffer = fs.readFileSync(filePath);
-  await client.serverCall('sendFile', { file: fileBuffer });
-}
+// 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:
+
+```typescript
+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'
+});
 
-sendBinaryData('./path/to/your/file.png');
+await client.connect();
+
+// Manually disconnect without auto-reconnect
+await client.disconnect();
+
+// Stop the client completely (disables auto-reconnect)
+await client.stop();
 ```
 
-### Securing Your WebSocket Communication
+### Secure Connections (WSS)
 
-@push.rocks/smartsocket leverages secure WebSocket (WSS) connections to ensure that data transferred between the client and server is encrypted. When setting up your Smartsocket server or client, use `wss://` in your URL to enable secure communication.
+For secure WebSocket connections, use HTTPS URLs:
 
-### Advanced Usage
+```typescript
+const client = new SmartsocketClient({
+  url: 'https://secure.example.com',  // HTTPS triggers WSS
+  port: 443,
+  alias: 'secureClient'
+});
+```
+
+### TypedRequest Integration
 
-#### Mesh Networking
+For strongly-typed RPC calls, define interfaces:
+
+```typescript
+interface IGreetRequest {
+  method: 'greet';
+  request: { name: string };
+  response: { message: string };
+}
 
-@push.rocks/smartsocket allows for the creation of complex mesh network configurations, enabling servers to communicate with other servers, forming a robust network with multiple nodes.
+// Type-safe server call
+const response = await client.serverCall<IGreetRequest>('greet', { name: 'Bob' });
+// response is typed as { message: string }
+```
 
-#### Scaling with @push.rocks/smartsocket
+## API Reference
 
-To scale your WebSocket services, you can utilize load balancers and ensure your @push.rocks/smartsocket instances are stateless to allow for horizontal scaling.
+### Smartsocket (Server)
 
-### Conclusion
+| 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 |
 
-This guide has covered how to set up basic WebSocket communication with @push.rocks/smartsocket, handle disconnections/reconnections, secure your communication, send binary data, and briefly touched on advanced concepts like mesh networking and scaling.
+### SmartsocketClient
 
-For more detailed documentation, visit [the official @push.rocks/smartsocket GitLab repository](https://gitlab.com/pushrocks/smartsocket).
+| 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 |
 
-Remember, WebSocket communication with @push.rocks/smartsocket is not only about sending and receiving messages. It's about creating a fast, reliable, and secure communication channel for your real-time applications.
+### SocketFunction
 
-Happy coding!
+```typescript
+const fn = new SocketFunction({
+  funcName: 'myFunction',
+  funcDef: async (data, socketConnection) => {
+    // data: the request payload
+    // socketConnection: the calling connection
+    return { result: 'response' };
+  }
+});
+```
 
----
+## Architecture
 
-Please note, the documentation above is a starting point. Depending on the complexity and requirements of your application, you may need to explore more features and configurations provided by @push.rocks/smartsocket. Always refer to the official documentation for the most current information and best practices.
+```
+┌─────────────────┐         WebSocket          ┌─────────────────┐
+│  SmartsocketClient  │◄────────────────────────►│    Smartsocket     │
+│    (Browser/Node)    │     Native WebSocket    │      (Server)       │
+└─────────────────┘                            └─────────────────┘
+        │                                                │
+        │ SocketFunction                    SocketFunction │
+        │ (serverCall)                        (clientCall) │
+        │                                                │
+        └──────────────── RPC-style Calls ──────────────┘
+```
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./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 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, and any usage must be approved in writing by Task Venture Capital GmbH.
+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
+Task Venture Capital GmbH
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 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.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartsocket',
-  version: '2.1.0',
+  version: '4.0.0',
   description: 'Provides easy and secure websocket communication mechanisms, including server and client implementation, function call routing, connection management, and tagging.'
 }

package/ts/interfaces/index.ts

@@ -1,2 +1,3 @@
 export * from './connection.js';
 export * from './tag.js';
+export * from './message.js';

package/ts/interfaces/message.ts

@@ -0,0 +1,67 @@
+/**
+ * Message types for the smartsocket protocol
+ */
+export type TMessageType =
+  | 'authRequest'      // Server requests authentication from client
+  | 'auth'             // Client provides authentication data
+  | 'authResponse'     // Server responds to authentication
+  | 'serverReady'      // Server signals it's fully ready
+  | 'function'         // Function call request
+  | 'functionResponse' // Function call response
+  | 'tagUpdate';       // Tag store synchronization
+
+/**
+ * Base message interface for all smartsocket messages
+ */
+export interface ISocketMessage<T = unknown> {
+  type: TMessageType;
+  id?: string;         // For request/response correlation
+  payload: T;
+}
+
+/**
+ * Authentication request payload (server -> client)
+ */
+export interface IAuthRequestPayload {
+  serverAlias: string;
+}
+
+/**
+ * Authentication data payload (client -> server)
+ */
+export interface IAuthPayload {
+  alias: string;
+}
+
+/**
+ * Authentication response payload (server -> client)
+ */
+export interface IAuthResponsePayload {
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Function call payload
+ */
+export interface IFunctionCallPayload<T = unknown> {
+  funcName: string;
+  funcData: T;
+}
+
+/**
+ * Tag update payload
+ */
+export interface ITagUpdatePayload {
+  tags: Record<string, unknown>;
+}
+
+/**
+ * Helper type for creating typed messages
+ */
+export type TAuthRequestMessage = ISocketMessage<IAuthRequestPayload>;
+export type TAuthMessage = ISocketMessage<IAuthPayload>;
+export type TAuthResponseMessage = ISocketMessage<IAuthResponsePayload>;
+export type TFunctionMessage = ISocketMessage<IFunctionCallPayload>;
+export type TFunctionResponseMessage = ISocketMessage<IFunctionCallPayload>;
+export type TTagUpdateMessage = ISocketMessage<ITagUpdatePayload>;

package/ts/smartsocket.classes.smartsocket.ts

@@ -26,7 +26,6 @@ export class Smartsocket {
   public alias: string;
   public smartenv = new plugins.smartenv.Smartenv();
   public options: ISmartsocketConstructorOptions;
-  public io: pluginsTyped.socketIo.Server;
   public socketConnections = new plugins.lik.ObjectMap<SocketConnection>();
   public socketFunctions = new plugins.lik.ObjectMap<SocketFunction<any>>();
   public socketRequests = new plugins.lik.ObjectMap<SocketRequest<any>>();
@@ -40,26 +39,59 @@ export class Smartsocket {
     this.alias = plugins.isounique.uni(this.options.alias);
   }
 
-  public async setExternalServer(serverType: 'smartexpress', serverArg: any) {
-    await this.socketServer.setExternalServer(serverType, serverArg);
+  /**
+   * Returns WebSocket hooks for integration with smartserve
+   * Pass these hooks to SmartServe's websocket config
+   */
+  public getSmartserveWebSocketHooks(): pluginsTyped.ISmartserveWebSocketHooks {
+    return this.socketServer.getSmartserveWebSocketHooks();
   }
 
   /**
    * starts smartsocket
    */
   public async start() {
-    const socketIoModule = await this.smartenv.getSafeNodeModule('socket.io');
-    this.io = new socketIoModule.Server(await this.socketServer.getServerForSocketIo(), {
-      cors: {
-        allowedHeaders: '*',
-        methods: '*',
-        origin: '*',
-      },
-    });
     await this.socketServer.start();
-    this.io.on('connection', (socketArg) => {
-      this._handleSocketConnection(socketArg);
+  }
+
+  /**
+   * Handle a new WebSocket connection
+   * Called by SocketServer when a new connection is established
+   */
+  public async handleNewConnection(socket: pluginsTyped.TWebSocket | pluginsTyped.IWebSocketLike) {
+    const socketConnection: SocketConnection = new SocketConnection({
+      alias: undefined,
+      authenticated: false,
+      side: 'server',
+      smartsocketHost: this,
+      socket: socket,
     });
+
+    logger.log('info', 'Socket connected. Trying to authenticate...');
+    this.socketConnections.add(socketConnection);
+
+    // Handle disconnection
+    const handleClose = () => {
+      this.socketConnections.remove(socketConnection);
+      socketConnection.eventSubject.next('disconnected');
+    };
+
+    (socket as pluginsTyped.IWebSocketLike).addEventListener('close', handleClose);
+    (socket as pluginsTyped.IWebSocketLike).addEventListener('error', handleClose);
+
+    try {
+      await socketConnection.authenticate();
+      await socketConnection.listenToFunctionRequests();
+
+      // Signal that the server is ready
+      socketConnection.sendMessage({
+        type: 'serverReady',
+        payload: {},
+      });
+    } catch (err) {
+      logger.log('warn', `Authentication failed: ${err}`);
+      this.socketConnections.remove(socketConnection);
+    }
   }
 
   /**
@@ -77,10 +109,9 @@ export class Smartsocket {
       }
     });
     this.socketConnections.wipe();
-    this.io.close();
 
-    // stop the corresponging server
-    this.socketServer.stop();
+    // stop the corresponding server
+    await this.socketServer.stop();
   }
 
   // communication
@@ -110,28 +141,4 @@ export class Smartsocket {
   public addSocketFunction(socketFunction: SocketFunction<any>) {
     this.socketFunctions.add(socketFunction);
   }
-
-  /**
-   * the standard handler for new socket connections
-   */
-  private async _handleSocketConnection(socketArg: pluginsTyped.socketIo.Socket) {
-    const socketConnection: SocketConnection = new SocketConnection({
-      alias: undefined,
-      authenticated: false,
-      side: 'server',
-      smartsocketHost: this,
-      socket: socketArg,
-    });
-    logger.log('info', 'Socket connected. Trying to authenticate...');
-    this.socketConnections.add(socketConnection);
-    const disconnectSubscription = socketConnection.eventSubject.subscribe((eventArg) => {
-      if (eventArg === 'disconnected') {
-        this.socketConnections.remove(socketConnection);
-        disconnectSubscription.unsubscribe();
-      }
-    });
-    await socketConnection.authenticate();
-    await socketConnection.listenToFunctionRequests();
-    await socketConnection.socket.emit('serverFullyReactive');
-  }
 }