REPL

Provides live administration tools for inspecting state, spawning and killing workers, and more. The REPL plugin itself is extensible, for example the stats() plugin provides a REPL function named stats().

Usage

The repl([port | path]) accepts a port or unix domain socket path, after which you may telnet to at any time.

Launch the REPL with a local socket:

  cluster(server)
    .use(cluster.repl('/var/run/cluster.sock'))
    .listen(3000);

Start a telnet session:

$ telnet /var/run/cluster.sock

cluster> help()

  Commands
  help(): Display help information
  spawn(n): Spawn one or more additional workers
  pids(): Output process ids
  kill(id, signal): Send signal or SIGTERM to the given worker
  shutdown(): Gracefully shutdown server
  stop(): Hard shutdown
  restart(): Gracefully restart all workers
  echo(msg): echo the given message
  stats(): Display server statistics

NOTE: a local socket is recommended, otherwise this may be a secure hole.

pids()

Outputs the master / worker process ids.

cluster> pids()

  pids
  master: 1799
  worker #0: 1801
  worker #1: 1802
  worker #2: 1803
  worker #3: 1804

spawn()

Spawn an additional worker.

cluster> spawn()
spawning 1 worker
cluster> pids()

  pids
  master: 1799
  worker #0: 1801
  worker #1: 1802
  worker #2: 1803
  worker #3: 1804
  worker #4: 1809

spawn(n)

Spawn n workers:

 cluster> spawn(4)
 spawning 4 workers
 cluster> pids()

   pids
   master: 1817
   worker #0: 1818
   worker #1: 1819
   worker #2: 1820
   worker #3: 1821
   worker #4: 1825
   worker #5: 1826
   worker #6: 1827
   worker #7: 1828

kill(id[, signal])

Kill worker id with the given signal or SIGTERM. For graceful termination use SIGQUIT.

cluster> pids()

  pids
  master: 1835
  worker #0: 1837
  worker #1: 1838
  worker #2: 1839
  worker #3: 1840

cluster> kill(2)
sent SIGTERM to worker #2
cluster> kill(3)
sent SIGTERM to worker #3
cluster> pids()

  pids
  master: 1835
  worker #0: 1837
  worker #1: 1838
  worker #2: 1843
  worker #3: 1844

restart()

Gracefully restart all workers.

 cluster> pids()

   pids
   master: 1835
   worker #0: 1837
   worker #1: 1838
   worker #2: 1843
   worker #3: 1844

 cluster> restart()
 restarting 4 workers
 cluster> pids()

   pids
   master: 1835
   worker #0: 1845
   worker #1: 1849
   worker #2: 1848
   worker #3: 1847

Defining REPL Functions

To define a function accessible to the REPL, all we need to do is call cluster.repl.define(), passing the function, as well as a description string.

Below we define the echo() function, simply printing the input msg given. As you can see our function receivers the Master instance, the REPL sock, and any arguments that were passed. For example echo("test") would pass the msg as "test", and echo("foo", "bar") would pass msg as "foo", and arguments[3] as "bar".

   repl.define('echo', function(master, sock, msg){
     sock.write(msg + '\n');
   }, 'echo the given message');

Shown below is a more complete example.

  var cluster = require('../')
    , repl = cluster.repl
    , http = require('http');

  var server = http.createServer(function(req, res){
    var body = 'Hello World';
    res.writeHead(200, { 'Content-Length': body.length });
    res.end(body);
  });

  // custom repl function

  repl.define('echo', function(master, sock, msg){
    sock.write(msg + '\n');
  }, 'echo the given message');

  // $ telnet localhots 8888

  cluster(server)
    .use(repl(8888))
    .listen(3000);