@afterlink/cluster 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajju (Javali Ajayakumar)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @afterlink/cluster
+
+AfterLink multi-process clustering orchestrator with Redis pub/sub synchronization.
+
+## Installation
+
+```bash
+pnpm add @afterlink/cluster
+```
+
+## Usage
+
+```javascript
+const { createCluster } = require('@afterlink/cluster');
+const Server = require('@afterlink/server');
+
+createCluster({
+  workers: 4,
+  redis: {
+    host: 'localhost',
+    port: 6379
+  }
+}, () => {
+  const server = new Server();
+  server.listen(4000);
+});
+```

package/index.d.ts

@@ -0,0 +1,31 @@
+import { EventEmitter } from 'events';
+
+export interface RedisConfig {
+  host?: string;
+  port?: number;
+  password?: string;
+  tls?: boolean;
+  keyPrefix?: string;
+  [key: string]: any;
+}
+
+export interface ClusterConfig {
+  workers?: number;
+  restartOnCrash?: boolean;
+  restartDelay?: number;
+  gracefulTimeout?: number;
+  redis?: RedisConfig;
+}
+
+export class ClusterManager extends EventEmitter {
+  constructor(config: ClusterConfig);
+  start(): void;
+  forkWorker(): any;
+  getAggregatedStats(): Record<string, any>;
+  shutdown(): void;
+}
+
+export function createCluster(
+  config: ClusterConfig | undefined,
+  workerFn: () => void
+): ClusterManager | null;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@afterlink/cluster",
+  "version": "2.0.1",
+  "description": "AfterLink Cluster — Multi-process clustering with Redis pub/sub",
+  "main": "src/index.js",
+  "types": "index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AJAYMYTH/AfterLink.git",
+    "directory": "packages/cluster"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@afterlink/server": "2.0.1"
+  },
+  "dependencies": {
+    "ioredis": "^5.3.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0",
+    "@afterlink/server": "2.0.1"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/index.js

@@ -0,0 +1,55 @@
+const cluster = require('cluster');
+const os = require('os');
+const ClusterManager = require('./manager');
+
+/**
+ * Creates and starts a multi-process cluster for AfterLink servers.
+ * If the process is primary, it initializes the ClusterManager to coordinate workers.
+ * If the process is a worker, it runs the user-supplied workerFn.
+ *
+ * @param {Object} [config] Cluster configuration options
+ * @param {Function} workerFn Function to run in worker processes (typically starting a Server)
+ * @returns {ClusterManager|null} The ClusterManager instance if primary, otherwise null
+ */
+function createCluster(config = {}, workerFn) {
+  if (typeof workerFn !== 'function') {
+    throw new TypeError('workerFn must be a function');
+  }
+
+  const defaultConfig = {
+    workers: os.cpus().length,
+    restartOnCrash: true,
+    restartDelay: 1000,
+    gracefulTimeout: 10000,
+    redis: {
+      host: 'localhost',
+      port: 6379,
+      password: undefined,
+      tls: false,
+      keyPrefix: 'afterlink:',
+    }
+  };
+
+  const mergedConfig = {
+    ...defaultConfig,
+    ...config,
+    redis: {
+      ...defaultConfig.redis,
+      ...(config.redis || {})
+    }
+  };
+
+  if (cluster.isPrimary || cluster.isMaster) {
+    const manager = new ClusterManager(mergedConfig);
+    manager.start();
+    return manager;
+  } else {
+    workerFn();
+    return null;
+  }
+}
+
+module.exports = {
+  createCluster,
+  ClusterManager
+};

package/src/manager.js

@@ -0,0 +1,141 @@
+const cluster = require('cluster');
+const EventEmitter = require('events');
+const { setupRollingRestart } = require('./rolling-restart');
+
+/**
+ * ClusterManager class responsible for primary process operations,
+ * worker lifecycle monitoring, and IPC metrics aggregation.
+ */
+class ClusterManager extends EventEmitter {
+  constructor(config) {
+    super();
+    this.config = config;
+    this.workers = new Map();
+    this.workerStats = new Map();
+    this.isShuttingDown = false;
+  }
+
+  /**
+   * Starts monitoring exit events and spawns worker processes.
+   */
+  start() {
+    console.log(`[AfterLink Cluster] Starting primary process ${process.pid}`);
+    console.log(`[AfterLink Cluster] Spawning ${this.config.workers} worker processes...`);
+
+    for (let i = 0; i < this.config.workers; i++) {
+      this.forkWorker();
+    }
+
+    cluster.on('exit', (worker, code, signal) => {
+      const pid = worker.process.pid;
+      this.workers.delete(pid);
+      this.workerStats.delete(pid);
+
+      if (this.isShuttingDown) return;
+
+      console.warn(`[AfterLink Cluster] Worker ${pid} exited with code ${code} (signal: ${signal})`);
+
+      if (this.config.restartOnCrash) {
+        console.log(`[AfterLink Cluster] Restarting crashed worker in ${this.config.restartDelay}ms...`);
+        setTimeout(() => {
+          if (this.isShuttingDown) return;
+          this.forkWorker();
+        }, this.config.restartDelay);
+      }
+    });
+
+    setupRollingRestart(cluster, this.config);
+  }
+
+  /**
+   * Forks a new worker and hooks up message handler for stats gathering.
+   */
+  forkWorker() {
+    const worker = cluster.fork();
+    const pid = worker.process.pid;
+    this.workers.set(pid, worker);
+    console.log(`[AfterLink Cluster] Worker ${pid} online`);
+
+    worker.on('message', (msg) => {
+      if (msg && msg.type === 'stats') {
+        this.workerStats.set(pid, msg.data);
+      }
+    });
+
+    return worker;
+  }
+
+  /**
+   * Combines/aggregates metrics reported by individual worker processes.
+   *
+   * @returns {Object} Aggregated cluster statistics
+   */
+  getAggregatedStats() {
+    let connections = 0;
+    let totalRequests = 0;
+    let requestsPerSec = 0;
+    let avgLatencyMsSum = 0;
+    let errorRateSum = 0;
+    const routeStatsMap = new Map();
+
+    const statsArray = Array.from(this.workerStats.values());
+    const count = statsArray.length;
+
+    for (const stats of statsArray) {
+      connections += stats.connections || 0;
+      totalRequests += stats.totalRequests || 0;
+      requestsPerSec += stats.requestsPerSec || 0;
+      avgLatencyMsSum += stats.avgLatencyMs || 0;
+      errorRateSum += stats.errorRate || 0;
+
+      if (stats.routes) {
+        for (const route of stats.routes) {
+          if (!routeStatsMap.has(route.name)) {
+            routeStatsMap.set(route.name, { totalCalls: 0, latencySum: 0, errorCount: 0 });
+          }
+          const current = routeStatsMap.get(route.name);
+          current.totalCalls += route.totalCalls || 0;
+          current.latencySum += (route.avgLatencyMs || 0) * (route.totalCalls || 0);
+          current.errorCount += (route.errorRate || 0) * (route.totalCalls || 0);
+        }
+      }
+    }
+
+    const routes = [];
+    for (const [name, data] of routeStatsMap.entries()) {
+      routes.push({
+        name,
+        totalCalls: data.totalCalls,
+        avgLatencyMs: data.totalCalls > 0 ? parseFloat((data.latencySum / data.totalCalls).toFixed(2)) : 0,
+        errorRate: data.totalCalls > 0 ? parseFloat((data.errorCount / data.totalCalls).toFixed(4)) : 0,
+      });
+    }
+
+    return {
+      workers: count,
+      connections,
+      totalRequests,
+      requestsPerSec: parseFloat(requestsPerSec.toFixed(2)),
+      avgLatencyMs: count > 0 ? parseFloat((avgLatencyMsSum / count).toFixed(2)) : 0,
+      errorRate: count > 0 ? parseFloat((errorRateSum / count).toFixed(4)) : 0,
+      routes
+    };
+  }
+
+  /**
+   * Shuts down the cluster by notifying all workers.
+   */
+  shutdown() {
+    this.isShuttingDown = true;
+    console.log('[AfterLink Cluster] Shutting down cluster...');
+    for (const worker of this.workers.values()) {
+      try {
+        worker.send({ type: 'shutdown', timeout: this.config.gracefulTimeout });
+      } catch (err) {
+        // Channel may already be closed
+      }
+    }
+  }
+}
+
+module.exports = ClusterManager;

package/src/redis-adapter.js

@@ -0,0 +1,135 @@
+const Redis = require('ioredis');
+
+/**
+ * RedisAdapter bridges cluster-wide Pub/Sub using ioredis.
+ * If Redis is disconnected, it falls back to worker-local pub/sub cleanly.
+ */
+class RedisAdapter {
+  constructor(config = {}) {
+    const redisConfig = {
+      host: config.host || 'localhost',
+      port: config.port || 6379,
+      password: config.password,
+      tls: config.tls ? {} : undefined,
+      ...config
+    };
+
+    this.keyPrefix = config.keyPrefix || 'afterlink:';
+    this.channelName = `${this.keyPrefix}pubsub`;
+    this.localBroadcast = () => {};
+    this.degraded = false;
+    this.redisPub = null;
+    this.redisSub = null;
+    
+    this.init(redisConfig);
+  }
+
+  /**
+   * Initializes pub and sub connections to Redis.
+   */
+  init(redisConfig) {
+    try {
+      this.redisPub = new Redis(redisConfig);
+      this.redisSub = new Redis(redisConfig);
+
+      const handleError = (err) => {
+        if (!this.degraded) {
+          console.warn(`[AfterLink Cluster] Redis connection failed, falling back to local-only pub/sub: ${err.message}`);
+          this.degraded = true;
+        }
+      };
+
+      this.redisPub.on('error', handleError);
+      this.redisSub.on('error', handleError);
+
+      this.redisPub.on('connect', () => {
+        this.degraded = false;
+      });
+
+      this.redisSub.on('connect', () => {
+        this.redisSub.subscribe(this.channelName).catch(handleError);
+      });
+
+      this.redisSub.on('message', (channel, message) => {
+        if (channel !== this.channelName) return;
+
+        try {
+          const parsed = JSON.parse(message);
+          if (parsed && parsed.pid !== process.pid) {
+            this.localBroadcast(parsed.topic, parsed.data);
+          }
+        } catch (err) {
+          console.error('[AfterLink Cluster] Failed to parse Redis pubsub message:', err.message);
+        }
+      });
+    } catch (err) {
+      console.warn(`[AfterLink Cluster] Redis initialization failed, falling back to local-only pub/sub: ${err.message}`);
+      this.degraded = true;
+    }
+  }
+
+  /**
+   * Registers local broadcaster callback.
+   */
+  setLocalBroadcast(fn) {
+    if (typeof fn === 'function') {
+      this.localBroadcast = fn;
+    }
+  }
+
+  /**
+   * Publishes message globally across cluster.
+   */
+  async publish(topic, data) {
+    // Always trigger locally
+    this.localBroadcast(topic, data);
+
+    if (!this.degraded && this.redisPub && this.redisPub.status === 'ready') {
+      try {
+        const payload = JSON.stringify({
+          topic,
+          data,
+          pid: process.pid
+        });
+        await this.redisPub.publish(this.channelName, payload);
+      } catch (err) {
+        console.warn('[AfterLink Cluster] Redis publish failed, falling back to local broadcast:', err.message);
+      }
+    }
+  }
+
+  /**
+   * Returns current active state of the Redis connections.
+   */
+  isConnected() {
+    return !this.degraded && 
+           this.redisPub && this.redisPub.status === 'ready' &&
+           this.redisSub && this.redisSub.status === 'ready';
+  }
+
+  /**
+   * Pings redis and returns round-trip latency.
+   */
+  async getLatency() {
+    if (!this.isConnected()) return -1;
+    const start = Date.now();
+    try {
+      await this.redisPub.ping();
+      return Date.now() - start;
+    } catch (err) {
+      return -1;
+    }
+  }
+
+  /**
+   * Closes Redis client connections.
+   */
+  async close() {
+    const promises = [];
+    if (this.redisPub) promises.push(this.redisPub.quit().catch(() => {}));
+    if (this.redisSub) promises.push(this.redisSub.quit().catch(() => {}));
+    await Promise.all(promises);
+  }
+}
+
+module.exports = RedisAdapter;

package/src/rolling-restart.js

@@ -0,0 +1,59 @@
+/**
+ * rolling-restart.js handles zero-downtime restarts.
+ * Sequentially terminates workers and spins up replacements when SIGUSR2 is received.
+ */
+function setupRollingRestart(cluster, config) {
+  process.on('SIGUSR2', async () => {
+    console.log('[AfterLink Cluster] Rolling restart (SIGUSR2) initiated...');
+    
+    const workers = Object.values(cluster.workers);
+    const gracefulTimeout = config.gracefulTimeout || 10000;
+    
+    for (let i = 0; i < workers.length; i++) {
+      const worker = workers[i];
+      if (!worker) continue;
+      
+      console.log(`[AfterLink Cluster] Stopping worker ${worker.process.pid}...`);
+      
+      try {
+        worker.send({ type: 'shutdown', timeout: gracefulTimeout });
+        worker.disconnect();
+      } catch (err) {
+        // Channel may be dead
+      }
+
+      const exitPromise = new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+          try {
+            worker.kill('SIGKILL');
+          } catch (err) {}
+          resolve();
+        }, gracefulTimeout + 1000);
+        
+        worker.on('exit', () => {
+          clearTimeout(timeout);
+          resolve();
+        });
+      });
+
+      await exitPromise;
+      
+      const newWorker = cluster.fork();
+      console.log(`[AfterLink Cluster] Spawned replacement worker ${newWorker.process.pid}`);
+      
+      await new Promise((resolve) => {
+        newWorker.on('online', resolve);
+        setTimeout(resolve, 1000); // Fallback
+      });
+
+      // 500ms stabilization gap
+      await new Promise((resolve) => setTimeout(resolve, 500));
+    }
+    
+    console.log('[AfterLink Cluster] Rolling restart complete.');
+  });
+}
+
+module.exports = {
+  setupRollingRestart
+};

package/test/manager.test.js

@@ -0,0 +1,51 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import ClusterManager from '../src/manager';
+
+describe('ClusterManager', () => {
+  let manager;
+
+  beforeEach(() => {
+    manager = new ClusterManager({ workers: 2 });
+  });
+
+  it('aggregates stats correctly from multiple workers', () => {
+    manager.workerStats.set(1001, {
+      connections: 5,
+      totalRequests: 100,
+      requestsPerSec: 10,
+      avgLatencyMs: 12.5,
+      errorRate: 0.02,
+      routes: [
+        { name: 'users/get', totalCalls: 80, avgLatencyMs: 10, errorRate: 0.01 },
+        { name: 'users/create', totalCalls: 20, avgLatencyMs: 22.5, errorRate: 0.06 }
+      ]
+    });
+
+    manager.workerStats.set(1002, {
+      connections: 3,
+      totalRequests: 50,
+      requestsPerSec: 5,
+      avgLatencyMs: 15.0,
+      errorRate: 0.04,
+      routes: [
+        { name: 'users/get', totalCalls: 40, avgLatencyMs: 12, errorRate: 0.02 },
+        { name: 'users/create', totalCalls: 10, avgLatencyMs: 27.0, errorRate: 0.12 }
+      ]
+    });
+
+    const aggregated = manager.getAggregatedStats();
+
+    expect(aggregated.workers).toBe(2);
+    expect(aggregated.connections).toBe(8);
+    expect(aggregated.totalRequests).toBe(150);
+    expect(aggregated.requestsPerSec).toBe(15);
+    expect(aggregated.avgLatencyMs).toBe(13.75); // (12.5 + 15.0) / 2
+    expect(aggregated.errorRate).toBe(0.03); // (0.02 + 0.04) / 2
+
+    const getRoute = aggregated.routes.find(r => r.name === 'users/get');
+    expect(getRoute).toBeDefined();
+    expect(getRoute.totalCalls).toBe(120);
+    expect(getRoute.avgLatencyMs).toBe(10.67);
+    expect(getRoute.errorRate).toBe(0.0133);
+  });
+});

package/test/redis-adapter.test.js

@@ -0,0 +1,101 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+const mockOn = vi.fn();
+const mockPublish = vi.fn().mockResolvedValue(1);
+const mockSubscribe = vi.fn().mockResolvedValue(null);
+const mockPing = vi.fn().mockResolvedValue('PONG');
+const mockQuit = vi.fn().mockResolvedValue(null);
+
+class MockRedis {
+  constructor() {
+    this.status = 'ready';
+    this.on = mockOn;
+    this.publish = mockPublish;
+    this.subscribe = mockSubscribe;
+    this.ping = mockPing;
+    this.quit = mockQuit;
+  }
+}
+MockRedis.default = MockRedis;
+
+// Hijack the Node require cache for ioredis
+const ioredisPath = require.resolve('ioredis');
+require.cache[ioredisPath] = {
+  id: ioredisPath,
+  filename: ioredisPath,
+  loaded: true,
+  exports: MockRedis
+};
+
+// Import after cache hijacking
+const RedisAdapter = require('../src/redis-adapter');
+
+describe('RedisAdapter', () => {
+  let adapter;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    adapter = new RedisAdapter({ host: 'mockhost', port: 6379 });
+  });
+
+  it('initializes redis connections', () => {
+    expect(adapter.redisPub).toBeDefined();
+    expect(adapter.redisSub).toBeDefined();
+    expect(adapter.degraded).toBe(false);
+  });
+
+  it('triggers local broadcast on publish', async () => {
+    const broadcastSpy = vi.fn();
+    adapter.setLocalBroadcast(broadcastSpy);
+
+    await adapter.publish('test-topic', { foo: 'bar' });
+
+    expect(broadcastSpy).toHaveBeenCalledWith('test-topic', { foo: 'bar' });
+    expect(mockPublish).toHaveBeenCalledWith(
+      'afterlink:pubsub',
+      expect.stringContaining('"topic":"test-topic"')
+    );
+  });
+
+  it('ignores pubsub messages from same PID', () => {
+    const broadcastSpy = vi.fn();
+    adapter.setLocalBroadcast(broadcastSpy);
+
+    const messageCall = mockOn.mock.calls.find(call => call[0] === 'message');
+    expect(messageCall).toBeDefined();
+    
+    // Trigger message event handler
+    messageCall[1]('afterlink:pubsub', JSON.stringify({
+      topic: 'test-topic',
+      data: { hello: 'world' },
+      pid: process.pid
+    }));
+
+    expect(broadcastSpy).not.toHaveBeenCalled();
+  });
+
+  it('triggers local broadcast for messages from other PID', () => {
+    const broadcastSpy = vi.fn();
+    adapter.setLocalBroadcast(broadcastSpy);
+
+    const messageCall = mockOn.mock.calls.find(call => call[0] === 'message');
+    const messageHandler = messageCall[1];
+
+    messageHandler('afterlink:pubsub', JSON.stringify({
+      topic: 'test-topic',
+      data: { hello: 'world' },
+      pid: 99999
+    }));
+
+    expect(broadcastSpy).toHaveBeenCalledWith('test-topic', { hello: 'world' });
+  });
+
+  it('marks adapter degraded on error', () => {
+    const errorCall = mockOn.mock.calls.find(call => call[0] === 'error');
+    expect(errorCall).toBeDefined();
+    const errorHandler = errorCall[1];
+
+    errorHandler(new Error('Connection lost'));
+    expect(adapter.degraded).toBe(true);
+  });
+});