🌀 NexusNode

NexusNode is a high-performance, horizontally scalable WebSocket message broker built with Node.js. It implements a distributed Pub/Sub architecture, allowing thousands of concurrent clients to communicate across a cluster of server nodes with sub-millisecond latency.

🚀 Key Features

• Distributed Pub/Sub: Seamless message routing across multiple server instances using Redis-backed synchronization.
• Topic-Based Routing: Clients can subscribe to specific channels (e.g., orders.created, chat.room.5) for granular data streams.
• Horizontal Scalability: Add or remove nodes dynamically; the system utilizes a stateless gateway model to handle traffic spikes.
• Fault Tolerance: Integrated heartbeat monitoring and automated cleanup of stale client connections.
• Observability: High-speed structured JSON logging powered by Pino for production-grade monitoring.

---

🏗️ Architecture & Flow

NexusNode operates as a cluster of independent gateway nodes connected via a common Redis Backbone.

1. Ingress: A client connects to any available node via WebSockets and sends a SUBSCRIBE packet.
2. Local Registration: The node stores the client reference in a local Map for zero-latency lookups.
3. Cross-Node Propagation: When a message is PUBLISHED on Node A, it is instantly broadcast to the Redis layer.
4. Egress: All other nodes (Node B, C, etc.) receive the Redis event and dispatch it to their locally connected subscribers.

---

🛠️ Tech Stack

Component	Technology	Purpose
Runtime	Node.js (LTS)	Non-blocking event loop for I/O
WebSockets	ws library	Native, high-speed socket handling
Message Bus	Redis	Cross-cluster state synchronization
Logging	Pino	High-performance structured logging
Containerization	Docker	Environment parity and easy scaling

---

🚦 Getting Started

Prerequisites

• Docker
• Docker Compose

Installation & Launch

Since NexusNode is built to run in a cluster, the easiest way to start it is via Docker Compose:

1. Clone the repository:

git clone https://github.com/nexus-labs/nexus-node.git
cd nexus-node

2. Spin up the cluster (3 Nodes + Redis):

docker-compose up --build

3. Test the connection: Connect any WebSocket client (like Postman or a browser console) to ws://localhost:3001 or ws://localhost:3002.

---

📡 API Specification

Subscribe to a Topic

{
  "action": "SUBSCRIBE",
  "topic": "market_updates"
}

Publish a Message

{
  "action": "PUBLISH",
  "topic": "market_updates",
  "data": {
    "symbol": "BTC/USD",
    "price": 64000
  }
}

---

🗺️ Roadmap

• Auth Layer: JWT-based authentication for private topics.
• Persistence: Optional MongoDB adapter to store "missed" messages for offline clients.
• Admin Dashboard: Real-time visualization of cluster health and connected clients.
• Binary Support: Protocol Buffers support for lower bandwidth consumption.

📜 License

Distributed under the MIT License. See LICENSE for more information.