LearnBoost Cluster Manager

Common errors

• TypeError: cluster is not a function

  cause This error often occurs when `require('cluster')` resolves to Node.js's built-in `cluster` module instead of the LearnBoost package, as the native module does not export a top-level function for initialization.
  fix If intending to use the LearnBoost package, ensure it is correctly installed and that the module resolver picks it up. However, due to its abandonment, the recommended fix is to migrate to Node.js's native `cluster` module, which has a different API.

• Error: Cannot find module 'cluster'

  cause The package was not installed or is not resolvable from the current working directory, or the `npm install cluster` command failed.
  fix Run `npm install cluster`. If the issue persists, verify your `node_modules` directory and Node.js environment. (Note: This package is not recommended for new projects).

• Segmentation fault (core dumped) or similar native crashes with modern Node.js.

  cause The LearnBoost `cluster` package makes low-level assumptions about the Node.js internal API and C++ bindings that are fundamentally incompatible with modern Node.js runtime changes.
  fix This package is incompatible with modern Node.js. There is no fix to make this package work on recent Node.js versions. You must migrate to Node.js's native `cluster` module or other modern process management solutions.

Warnings

• breaking This package is abandoned and incompatible with modern Node.js versions (e.g., Node.js 6.x and above). It was last updated for Node.js 0.2.x and 0.4.x. Attempting to use it will result in runtime errors or unexpected behavior.
  Fix: Do not use this package. Migrate to Node.js's built-in `cluster` module or a modern process manager like PM2, Forever, or similar libraries designed for current Node.js runtimes.
• gotcha The package name `cluster` directly conflicts with Node.js's built-in `cluster` module. Importing `require('cluster')` might load the native module instead of this third-party package if not installed or resolved carefully, leading to API mismatches and errors.
  Fix: Ensure explicit installation (`npm install cluster`) and verify `node_modules` resolution if you must use this legacy package. It is strongly recommended to use Node.js's native `cluster` module for modern applications.
• security As an abandoned package with no updates for over a decade, `LearnBoost/cluster` has not received security patches for known vulnerabilities in Node.js or its dependencies. Using it in production could expose applications to significant security risks.
  Fix: Immediately cease using this package. Migrate to actively maintained alternatives to ensure security and stability.

Install

• npm install cluster npm
• yarn add cluster yarn
• pnpm add cluster pnpm

Imports

• cluster
  wrong:

  import cluster from 'cluster';

  correct:

  const cluster = require('cluster');

  This package is CommonJS-only and incompatible with ES Modules. Use `require`.
• Master
  wrong:

  import { Master } from 'cluster';

  correct:

  const Master = require('cluster').Master;

  Internal class, primarily accessed via the `cluster()` initializer, not typically directly imported for use. Exposed for advanced extension.
• cluster('app')
  wrong:

  const cluster = require('cluster');
  cluster('./app').listen(3000);

  correct:

  const serverApp = require('./app');
  const clusterManager = require('cluster');
  clusterManager(serverApp).listen(3000);

  While `cluster('./app')` was shown in old examples, passing an explicit `http.Server` instance from a required module (`./app`) or defining it inline is safer and clearer. The `./app` string was meant to `require` the module internally.

Quickstart

This quickstart demonstrates how to initialize the LearnBoost Cluster manager with an HTTP server and enable several of its bundled plugins for logging, statistics, PID file management, CLI, and REPL. It shows the typical CJS `require` pattern for setting up a multi-process Node.js application, with one master process managing multiple worker processes.

const http = require('http');
const cluster = require('cluster');

// app.js (or inline server definition)
const app = http.createServer(function(req, res){
  console.log('Worker %s handling request for %s %s', process.pid, req.method, req.url);
  const body = 'Hello World from worker ' + process.pid;
  res.writeHead(200, { 'Content-Length': Buffer.byteLength(body) });
  res.end(body);
});

// server.js (main cluster entry point)
if (require.main === module) {
  cluster(app)
    .use(cluster.logger('logs')) // Example plugin: logs master/worker activity
    .use(cluster.stats())     // Example plugin: adds real-time statistics
    .use(cluster.pidfiles('pids')) // Example plugin: writes master/worker pidfiles
    .use(cluster.cli())       // Example plugin: provides a command-line interface
    .use(cluster.repl(8888))  // Example plugin: real-time administration via REPL
    .listen(3000, function(){
      console.log('Cluster listening on port 3000, with %d workers', cluster.workers.length);
    });
  console.log('Master process %s started.', process.pid);
} else {
  // When required by the master, just export the app
  module.exports = app;
}