@cocreate/server-mesh 1.2.1 → 1.2.2

package/README.md

@@ -1,65 +1,355 @@
-# CoCreate-socket-mesh
+# @cocreate/server-mesh
 
-A pluggable, event-driven WebSocket clustering and P2P mesh driver for CoCreate Server, enabling dynamic server-to-server state synchronization across multi-cloud and bare-metal environments.
+A high-performance, self-healing, peer-to-peer (P2P) encrypted transport fabric built for distributed cluster orchestration, real-time tenant routing, and inter-node event synchronization across the CoCreate ecosystem.
 
-![GitHub latest release](https://img.shields.io/github/v/release/CoCreate-app/CoCreate-socket-mesh?style=flat-square)
-![GitHub contributors](https://img.shields.io/github/contributors/CoCreate-app/CoCreate-socket-mesh?style=flat-square)
-![License](https://img.shields.io/static/v1?style=flat-square&label=license&message=SSPL&color=green)
-![Hiring](https://img.shields.io/static/v1?style=flat-square&label=&message=Hiring&color=blueviolet)
+---
 
-![CoCreate](https://cdn.cocreate.app/logo.png)
+## Documentation
 
-[CoCreate Docs](https://cocreate.app/docs/socket-mesh)
+For complete API references, deployment guides, and architecture documentation, visit the CoCreate Server Mesh documentation.
 
-We want this library to be community-driven, and CoCreate led. We need your help to realize this goal. To help make sure we are building the right things in the right order, we ask that you create [issues](https://github.com/CoCreate-app/Realtime_Admin_CRM_and_CMS/issues) and [pull requests](https://github.com/CoCreate-app/Realtime_Admin_CRM_and_CMS/pulls) or merely upvote or comment on existing issues or pull requests.
+## Table of Contents
 
-We appreciate your continued support, thank you!
+- [Overview](#overview)
+- [Key Features](#key-features)
+- [Architecture & Message Pipeline](#architecture--message-pipeline)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Routing Directives & Targeting Matrix](#routing-directives--targeting-matrix)
+- [Tenant-Aware Routing Protocols](#tenant-aware-routing-protocols)
+- [Self-Healing & Reconnection Logic](#self-healing--reconnection-logic)
+- [Programmatic API Reference](#programmatic-api-reference)
+- [Security & TLS Specification](#security--tls-specification)
+- [Environment Variables](#environment-variables)
+- [Announcements](#announcements)
+- [Roadmap](#roadmap)
+- [How to Contribute](#how-to-contribute)
+- [About](#about)
+- [License](#license)
 
-# Table of Contents
+---
 
--   [Table of Contents](#table-of-contents)
--   [Announcements](#announcements)
--   [Roadmap](#roadmap)
--   [How to Contribute](#how-to-contribute)
--   [About](#about)
--   [License](#license)
+## Overview
 
-<a name="announcements"></a>
+`@cocreate/server-mesh` serves as the real-time inter-server transport plane for `@cocreate/server`. It establishes zero-trust, mutual P2P encrypted WebSocket tunnels between cluster nodes, enabling seamless multi-tenant data propagation, worker thread relays, and distributed cluster command execution.
 
-# Announcements
+Designed as a pure transport fabric, `@cocreate/server-mesh` blindly routes and emits network payloads as standard `EventEmitter` events across the cluster without introducing business-logic overhead.
 
-All updates to this library are documented in our [CHANGELOG](https://github.com/CoCreate-app/CoCreate-socket-mesh/blob/master/CHANGELOG.md) and [releases](https://github.com/CoCreate-app/CoCreate-socket-mesh/releases). You may also subscribe to email for releases and breaking changes.
+---
 
-<a name="roadmap"></a>
+## Key Features
 
-# Roadmap
+- **Zero-Trust Ephemeral TLS:** Automatically generates temporary TLS credentials for secure node-to-node communication over the mesh network.
+- **Polymorphic Target Directives:** Unicast, multicast, broadcast, worker-specific, or tenant-aware routing using a unified payload format.
+- **Cryptographic Traceability:** Automatically stamps every outgoing frame with a unique `crypto.randomUUID()` identifier for distributed tracing and replay protection.
+- **Tenant Isolation:** Dynamically tracks tenant-to-worker and tenant-to-server mappings so messages are only delivered to nodes actively serving an organization.
+- **Self-Healing Reconnection:** Uses exponential backoff with randomized jitter to prevent reconnection storms after network interruptions.
+- **Cluster IPC Integration:** Transparently bridges Node.js Primary and Worker processes while extending communication across distributed servers.
+- **EventEmitter API:** Receive mesh messages using familiar Node.js event listeners.
 
-If you are interested in the future direction of this project, please take a look at our open [issues](https://github.com/CoCreate-app/CoCreate-socket-mesh/issues) and [pull requests](https://github.com/CoCreate-app/CoCreate-socket-mesh/pulls). We would love to hear your feedback.
+---
 
-<a name="about"></a>
+## Architecture & Message Pipeline
 
-# About
+When a payload is dispatched through `@cocreate/server-mesh`, the routing engine evaluates execution context (Primary vs Worker), determines the target destination, and forwards the payload through IPC or encrypted peer connections.
 
-CoCreate-socket-mesh is guided and supported by the CoCreate Developer Experience Team.
+$$
+\text{Worker Thread}
+\xrightarrow{\text{IPC}}
+\text{Primary Process}
+\xrightarrow{\text{Route Resolution}}
+\begin{cases}
+\text{Local Workers} \\
+\text{Remote Peer Servers}
+\end{cases}
+$$
 
-Please Email the Developer Experience Team [here](mailto:develop@cocreate.app) in case of any queries.
+### Worker Context
 
-CoCreate-socket-mesh is maintained and funded by CoCreate. The names and logos for CoCreate are trademarks of CoCreate, LLC.
+Worker processes:
 
-<a name="contribute"></a>
+- Send outbound messages through native `process.send()`
+- Receive inbound mesh traffic through IPC
+- Never establish direct peer connections
 
-# How to Contribute
+### Primary Context
 
-We encourage contribution to our libraries (you might even score some nifty swag), please see our [CONTRIBUTING](https://github.com/CoCreate-app/CoCreate-socket-mesh/blob/master/CONTRIBUTING.md) guide for details.
+The Primary process:
 
-<a name="license"></a>
+- Hosts the secure mesh WebSocket server
+- Maintains encrypted peer connections
+- Tracks tenant routing information
+- Routes messages between workers and remote servers
 
-# License
+---
+
+## Installation
+
+### NPM
+
+```bash
+npm install @cocreate/server-mesh
+```
+
+### Yarn
+
+```bash
+yarn add @cocreate/server-mesh
+```
+
+> **Note**
+>
+> `@cocreate/server-mesh` integrates directly with `@cocreate/server`, but it can also be initialized independently.
+
+---
+
+## Quick Start
+
+### Initialize
+
+```javascript
+import CoCreateServer from "@cocreate/server";
+import ServerMesh from "@cocreate/server-mesh";
+
+await ServerMesh.init(CoCreateServer);
+```
+
+### Send a Message
+
+Unicast to a single server:
+
+```javascript
+ServerMesh.send({
+	method: "cache.flush",
+	server: "srv_64f8a1bc90d1",
+	data: {
+		cache: "users"
+	}
+});
+```
+
+Multicast to multiple servers:
+
+```javascript
+ServerMesh.send({
+	method: "worker.task",
+	server: ["srv_64f8a1bc90d1", "srv_90e3b2ac81f4"],
+	worker: 2,
+	data: {
+		taskId: 1042
+	}
+});
+```
+
+Broadcast to every node:
+
+```javascript
+ServerMesh.send({
+	broadcast: true,
+	method: "reload.configuration"
+});
+```
+
+### Listen for Messages
+
+```javascript
+ServerMesh.on("cache.flush", (message) => {
+	console.log(message.data);
+});
+```
+
+---
+
+## Routing Directives & Targeting Matrix
+
+| Target | Payload | Description |
+| --- | --- | --- |
+| Single Server | `{ server: "srv1" }` | Routes only to the specified server. |
+| Multiple Servers | `{ server: ["srv1","srv2"] }` | Sends to every listed server. |
+| Worker | `{ server: "srv1", worker: 2 }` | Routes to a specific worker on the target server. |
+| Local Workers | `{ worker: [1,3] }` | Sends only to selected local workers. |
+| Broadcast | `{ broadcast: true }` | Delivers to every connected server and local worker. |
+
+---
+
+## Tenant-Aware Routing Protocols
+
+The mesh minimizes unnecessary network traffic by maintaining live organization routing maps.
+
+```text
+Client Connect
+        │
+        ▼
+mesh.registerOrg
+        │
+        ▼
+Map Organization → Worker
+        │
+        ▼
+Client Disconnect
+        │
+        ▼
+60 Second Grace Timer
+        │
+        ▼
+mesh.deregisterOrg
+        │
+        ▼
+mesh.orgDeleted Broadcast
+```
+
+### Organization Events
+
+| Event | Description |
+| --- | --- |
+| `mesh.registerOrg` | Registers a worker serving an organization. |
+| `mesh.deregisterOrg` | Removes a worker's organization mapping after all connections close. |
+| `mesh.orgAdded` | Broadcast to peer servers when an organization becomes active. |
+| `mesh.orgDeleted` | Broadcast when an organization is no longer active on a server. |
+| `mesh.orgData` | Routes organization-specific payloads only to subscribed servers and workers. |
+
+---
+
+## Self-Healing & Reconnection Logic
+
+When peer servers disconnect, reconnection attempts use exponential backoff combined with randomized jitter to prevent synchronized reconnect storms.
+
+$$
+T_{delay}
+=
+\min\left(30000,\,
+1000\times1.5^{attempt}
+\right)
++
+random(500,4500)
+$$
+
+Connections automatically retry until:
+
+- the peer becomes available,
+- the server shuts down,
+- or the connection is intentionally closed.
+
+---
+
+## Programmatic API Reference
+
+### `ServerMesh.init(server)`
+
+Initializes the mesh networking layer.
+
+```javascript
+await ServerMesh.init(server);
+```
+
+---
+
+### `ServerMesh.send(payload)`
+
+Routes a payload across the cluster.
+
+```javascript
+ServerMesh.send({
+	method: "custom.command",
+	server: "srv123",
+	data: {
+		key: "value"
+	}
+});
+```
+
+---
+
+### `ServerMesh.close()`
+
+Gracefully closes all mesh connections and releases resources.
+
+```javascript
+await ServerMesh.close();
+```
+
+---
+
+### Events
+
+```javascript
+ServerMesh.on("mesh.orgAdded", handler);
+
+ServerMesh.on("mesh.orgDeleted", handler);
+
+ServerMesh.on("mesh.orgData", handler);
+
+ServerMesh.on("mesh.raw_message", handler);
+```
+
+---
+
+## Security & TLS Specification
+
+- **Encrypted Transport:** All peer communication occurs over mutually authenticated encrypted WebSocket connections.
+- **Dedicated Mesh Port:** Mesh traffic is isolated from public HTTP and HTTPS traffic.
+- **Ephemeral Certificates:** Temporary TLS certificates are generated during startup and automatically replaced on restart.
+- **Server Authentication:** Incoming peers must successfully complete server identity validation before joining the mesh.
+- **UUID Tracing:** Every transmitted frame receives a unique identifier for distributed tracing and replay protection.
+
+---
+
+## Environment Variables
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `MESH_PORT` | `8090` | Port used for mesh communication. |
+| `CLUSTER_SECRET` | — | Shared secret used during mesh authentication. |
+| `SERVER_ID` | Auto Generated | Persistent identifier for the current server node. |
+
+---
+
+## Announcements
+
+Release notes, performance improvements, protocol updates, and networking enhancements are published with every release. Follow the repository to stay informed about new features and compatibility changes.
+
+---
+
+## Roadmap
+
+Upcoming enhancements include:
+
+- Native QUIC / HTTP/3 transport
+- Adaptive routing based on latency measurements
+- Automatic peer discovery across local networks
+- Streaming binary frame optimizations
+- Dynamic topology-aware routing
+
+---
+
+## How to Contribute
+
+We welcome pull requests, bug reports, documentation improvements, performance optimizations, and security reviews.
+
+Please review the project's `CONTRIBUTING.md` before submitting changes, and use the GitHub Issues page to report bugs or request new features.
+
+Community feedback helps prioritize development and improve the platform.
+
+---
+
+## About
+
+`@cocreate/server-mesh` is designed, built, and maintained by the CoCreate Developer Experience Team.
+
+It serves as the distributed communication backbone of the CoCreate ecosystem, providing secure, low-latency messaging between clustered servers.
+
+For questions, architecture discussions, or deployment guidance, visit the project's GitHub Discussions or join the CoCreate community.
+
+---
+
+## License
 
 This software is dual-licensed under the GNU Affero General Public License version 3 (AGPLv3) and a commercial license.
 
--   **Open Source Use**: For open-source projects and non-commercial use, this software is available under the AGPLv3. The AGPLv3 allows you to freely use, modify, and distribute this software, provided that all modifications and derivative works are also licensed under the AGPLv3. For the full license text, see the [LICENSE file](https://github.com/CoCreate-app/CoCreate-socket-mesh/blob/master/LICENSE).
+### Open Source
+
+For open-source projects and non-commercial use, this software is available under the AGPLv3. See the `LICENSE` file for the complete license text.
 
--   **Commercial Use**: For-profit companies and individuals intending to use this software for commercial purposes must obtain a commercial license. The commercial license is available when you sign up for an API key on our [website](https://cocreate.app). This license permits proprietary use and modification of the software without the copyleft requirements of the AGPLv3. It is ideal for integrating this software into proprietary commercial products and applications.
+### Commercial
 
-If you have not purchased a commercial license and intend to use this software for commercial purposes, you are required to sign up for an API key on our website.
+Organizations requiring proprietary use may obtain a commercial license from CoCreate.

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@cocreate/server-mesh",
-  "version": "1.2.1",
-  "description": "Pluggable, event-driven WebSocket clustering and P2P mesh driver for CoCreate Server, enabling dynamic server-to-server state synchronization across multi-cloud and bare-metal environments.",
+  "version": "1.2.2",
+  "description": "Decentralized, event-driven P2P server mesh and transport fabric for CoCreate Server. Optimizes multi-tenant cluster concurrency with dynamic, tenant-isolated WebSocket data tunnels.",
   "keywords": [
-    "cocreate-socket",
-    "low-code",
-    "realtime",
-    "realtime-framework",
-    "collaboration",
-    "shared-editing",
-    "html5-framework",
-    "javascript-framework"
+    "cocreate",
+    "cocreate-server",
+    "websocket-clustering",
+    "p2p-mesh",
+    "multi-tenancy",
+    "realtime-collaboration",
+    "state-synchronization",
+    "distributed-systems",
+    "service-mesh",
+    "headless-server",
+    "crdt",
+    "zero-dependency"
   ],
   "publishConfig": {
     "access": "public"

package/src/inbound.js

@@ -0,0 +1,226 @@
+import { WebSocketServer } from 'ws';
+import https from 'node:https';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import crypto from 'node:crypto';
+
+/**
+ * ServerMeshInbound manages inbound HTTPS and WebSocket secure listening transports,
+ * ephemeral TLS certificate generation, inbound socket heartbeats, and inbound message processing.
+ */
+export class ServerMeshInbound {
+    constructor(mesh) {
+        this.mesh = mesh;
+        this.server = null;
+        this.meshPort = process.env.MESH_PORT || 8090;
+        this.secureMeshServer = null;
+        this.meshWss = null;
+        this.heartbeatInterval = null;
+        this.heartbeatMs = 30000;
+    }
+
+    /**
+     * Initializes the inbound server transport with host server context and IPC listeners.
+     * 
+     * @param {Object} server - CoCreateServer instance context
+     * @returns {Promise<void>}
+     */
+    async init(server) {
+        this.server = server;
+
+        if (this.server && typeof this.server.on === 'function') {
+            this.server.on('mesh.inbound.status', () => {
+                console.log(`[@cocreate/server-mesh/inbound] Inbound transport status: ${this.secureMeshServer ? 'listening' : 'stopped'}`);
+            });
+
+            // Fallback listener for legacy event name
+            this.server.on('mesh.server.status', () => {
+                console.log(`[@cocreate/server-mesh/inbound] Inbound transport status: ${this.secureMeshServer ? 'listening' : 'stopped'}`);
+            });
+
+            this.server.on('mesh.inbound.relay', (payload) => {
+                if (payload && payload.data) {
+                    this.broadcastInboundLocal(payload);
+                }
+            });
+        }
+
+        await this.startServer();
+        this.startHeartbeat();
+    }
+
+    /**
+     * Generates short-lived RSA-2048 X.509 TLS credentials in temporary storage.
+     * 
+     * @returns {{key: Buffer, cert: Buffer}|null}
+     */
+    generateTLSCredentials() {
+        const tmpDir = os.tmpdir();
+        const keyPath = path.join(tmpDir, `mesh-key-${Date.now()}-${crypto.randomBytes(4).toString('hex')}.pem`);
+        const certPath = path.join(tmpDir, `mesh-cert-${Date.now()}-${crypto.randomBytes(4).toString('hex')}.pem`);
+
+        try {
+            execSync(`openssl req -x509 -newkey rsa:2048 -keyout "${keyPath}" -out "${certPath}" -days 1 -nodes -subj "/CN=localhost"`, { stdio: 'ignore' });
+            const key = fs.readFileSync(keyPath);
+            const cert = fs.readFileSync(certPath);
+
+            try { fs.unlinkSync(keyPath); } catch {}
+            try { fs.unlinkSync(certPath); } catch {}
+
+            return { key, cert };
+        } catch (err) {
+            console.error('[@cocreate/server-mesh/inbound] Failed to generate ephemeral TLS credentials:', err.message);
+            return null;
+        }
+    }
+
+    /**
+     * Binds HTTPS and WebSocketServer listeners on MESH_PORT and configures inbound socket handlers.
+     */
+    async startServer() {
+        const credentials = this.generateTLSCredentials();
+        if (!credentials) {
+            throw new Error("Unable to boot secure mesh server: TLS credential generation failed.");
+        }
+
+        this.secureMeshServer = https.createServer(credentials);
+
+        this.secureMeshServer.on('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                console.error(`\n[@cocreate/server-mesh/inbound] [FATAL] Port ${this.meshPort} is already in use!`);
+                process.exit(1);
+            } else {
+                console.error(`[@cocreate/server-mesh/inbound] HTTPS transport error:`, err);
+            }
+        });
+
+        await new Promise((resolve) => {
+            this.secureMeshServer.listen(this.meshPort, '0.0.0.0', () => {
+                console.log(`[@cocreate/server-mesh/inbound] [PRIMARY] Inbound mesh listening on 0.0.0.0:${this.meshPort}`);
+                resolve();
+            });
+        });
+
+        this.meshWss = new WebSocketServer({ server: this.secureMeshServer });
+
+        this.meshWss.on('connection', (ws, req) => {
+            const ip = req.socket.remoteAddress;
+            let remoteServerId = null;
+
+            const protocolHeader = req.headers['sec-websocket-protocol'];
+            if (protocolHeader) {
+                try {
+                    const parsed = JSON.parse(decodeURIComponent(protocolHeader));
+                    remoteServerId = parsed.id;
+                } catch (err) {
+                    // Ignore protocol decoding errors
+                }
+            }
+
+            const identifier = remoteServerId || ip;
+            console.log(`[@cocreate/server-mesh/inbound] Secure inbound peer connection established: ${identifier}`);
+
+            ws.isAlive = true;
+            ws.remoteAddress = ip;
+            ws.on('pong', () => { ws.isAlive = true; });
+
+            ws.on('message', (rawData) => {
+                this.handleInboundSocketMessage(rawData, ws);
+            });
+
+            ws.on('close', () => {
+                console.log(`[@cocreate/server-mesh/inbound] Inbound peer connection ${identifier} dropped.`);
+                this.mesh.activeConnections.delete(identifier);
+                if (remoteServerId) this.mesh.activeConnections.delete(ip);
+                this.mesh.removeSocketFromAllOrgServers(ws);
+            });
+
+            ws.on('error', (err) => {
+                console.error(`[@cocreate/server-mesh/inbound] Inbound socket error (${identifier}):`, err.message);
+            });
+
+            this.mesh.activeConnections.set(identifier, ws);
+            if (remoteServerId) this.mesh.activeConnections.set(ip, ws);
+        });
+    }
+
+// ... existing code ...
+
+    /**
+     * Relays inbound payloads down to local worker processes.
+     * 
+     * @param {Object} payload 
+     */
+    broadcastInboundLocal(payload) {
+        if (this.server && typeof this.server.send === 'function') {
+            try {
+                this.server.send({
+                    method: 'mesh.inbound',
+                    broadcast: payload.broadcast ?? true,
+                    workers: payload.workers,
+                    master: false,
+                    data: typeof payload.data === 'string' ? payload.data : JSON.stringify(payload.data)
+                });
+            } catch (err) {
+                console.error("[@cocreate/server-mesh/inbound] Failed to relay inbound message to workers:", err.message);
+            }
+        }
+    }
+
+    /**
+     * Starts interval timer to ping connected clients and evict dead sockets.
+     */
+    startHeartbeat() {
+        if (this.heartbeatInterval) clearInterval(this.heartbeatInterval);
+
+        this.heartbeatInterval = setInterval(() => {
+            if (!this.meshWss) return;
+
+            this.meshWss.clients.forEach((ws) => {
+                if (ws.isAlive === false) {
+                    console.warn(`[@cocreate/server-mesh/inbound] Unresponsive client socket detected. Terminating connection.`);
+                    return ws.terminate();
+                }
+                ws.isAlive = false;
+                try {
+                    ws.ping();
+                } catch (err) {
+                    console.error("[@cocreate/server-mesh/inbound] Ping error:", err.message);
+                }
+            });
+        }, this.heartbeatMs);
+
+        if (this.heartbeatInterval.unref) {
+            this.heartbeatInterval.unref();
+        }
+    }
+
+    /**
+     * Tears down the server instance, ending heartbeats and closing listening sockets.
+     * 
+     * @returns {Promise<void>}
+     */
+    async close() {
+        if (this.heartbeatInterval) {
+            clearInterval(this.heartbeatInterval);
+            this.heartbeatInterval = null;
+        }
+
+        if (this.meshWss) {
+            try { this.meshWss.close(); } catch {}
+        }
+
+        return new Promise((resolve) => {
+            if (this.secureMeshServer) {
+                this.secureMeshServer.close(() => {
+                    console.log(`[@cocreate/server-mesh/inbound] Secure port ${this.meshPort} successfully released.`);
+                    resolve();
+                });
+            } else {
+                resolve();
+            }
+        });
+    }
+}