terminate

A minimalist yet reliable (tested) way to Terminate a Node.js Process (and all Child Processes) based on the Process ID

Usage

Install from NPM

npm install terminate --save

In your script

var terminate = require('terminate');
terminate(process.pid, function (err) {
  if (err) { // you will get an error if you did not supply a valid process.pid
    console.log("Oopsy: " + err); // handle errors in your preferred way.
  }
  else {
    console.log('done'); // terminating the Processes succeeded.
  }
});

tl;dr

Why?

In our Faster project we run the server using Child Process(es). When we want to re-start the server,
we needed to ensure the process (and any Child Processes) were Terminated before attempting to re-start.

Prevents Zombie Processes

Imagine you are running your Node.js app on a Multi-Core Processor and don't want to "waste" the CPU by only using one of those cores
(remember: one of Node's selling points is that its single-process running on a single-core), you can "farm out" tasks to the other cores using Child Process(es)

If you then want to restart your app you naively (we did this!) terminate the "main" process and expect all the "child" processes to be ended too.

Sadly this results in Zombie Processes which you would have to either manually kill or restart the machine/VM to clear.
Instead you need to find all the Process IDs for the child processes that your app created and terminate those before you can re-start your app.

Using terminate you no longer have this problem.

Dependencies

While researching how to get a list of child processes given a Process ID we found ps-tree: https://github.com/indexzero/ps-tree
it was un-maintained and had no tests so we submitted an issue offering to update the module with tests.
Charlie replied welcoming an update so we submitted a Pull Request with 100% test coverage which was Merged by Charlie
ps-tree in turn uses event-stream (by Dominc Tarr) for streaming the result of its process lookups.
event-stream does not publish its' code coverage, but is tested (and more importantly used by millions of people)
has had many itterations and has been stable for a while:

While we don't like the fact that event-stream has dependencies which have limited automated tests,
we are willing to place reliance on the module given how "real-world tested" it is.

If at any point we find that relying event-stream or its underlying dependencies is the source of a bug or sleepless nights,
we can either make time to contribute the tests or write our own version of ps-tree without dependencies
(which should "only" take a day but won't be as elegant...)

Research

Background Reading

• How to terminate node processes: https://github.com/joyent/node/issues/1172 (history lesson)
• nodejs exec command failing with no useful error message: https://github.com/joyent/node/issues/4590

Useful StackOverflow Questions/Answers

• http://stackoverflow.com/questions/27381163/spawning-node-js-child-processes-results-in-zombie-processes-on-cloud-foundry-s
• http://stackoverflow.com/questions/26694100/why-does-my-node-app-process-keep-getting-stopped-when-i-use-forever
• http://stackoverflow.com/questions/18275809/kill-all-child-process-when-node-process-is-killed
• http://stackoverflow.com/questions/26004519/why-doesnt-my-node-js-process-terminate-once-all-listeners-have-been-removed
• http://stackoverflow.com/questions/14319724/nodejs-exec-command-failing-with-no-useful-error-message
• http://stackoverflow.com/questions/9275654/how-many-child-processes-can-a-node-js-cluster-spawn-on-a-64bit-wintel-pc
• http://stackoverflow.com/questions/17959663/why-is-node-js-single-threaded

Other potential modules we could have used:

• node-ps: https://github.com/neekey/ps (has basic tests but no coverage / unmaintained?)
• tree-kill: https://www.npmjs.com/package/tree-kill (no tests!!)
• nexpect: https://github.com/nodejitsu/nexpect (spawn and control child processes looks really good, but we wanted less abstraction)

Name

Terminate seemed like the best (of the available) name,
if you have a better suggestion, please share!