terminate

A minimalist yet reliable way to Terminate a Node.js Process (and all Child Processes) by Process ID.

Usage

Install from NPM

npm install terminate --save

In your script

const 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.
    // NOTE: The above won't be run in this example as the process itself will be killed before.
  }
});

Usage

All the available parameters and their descriptions are viewable in the TypeScript definition file: index.d.ts.

// Function signature
terminate(pid: number, signal?: string, opts?: TerminateOptions, callback?: DoneCallback): void

// Function signature of the Promise version
terminate(pid: number, signal?: string, opts?: TerminateOptions): Promise<void>

• pid - The Process ID you want to terminate.
• signal - The signal to kill the processes with. Defaults to "SIGKILL" if it's empty or not defined.
• opts.pollInterval - Interval to poll whether pid and all of the childs pids have been killed. Defaults to 500 (0.5s).
• opts.timeout - Max time (in milliseconds) to wait for process to exit before timing out and calling back with an error. Defaults to 5000 (5s).
• callback - The callback function to call when the termination is done. It has this signature: (error: Error | null): void whereas error will be null if the operation succeeds.

Promise API

If you are using Node.js 8+, you can load the Promise version importing the module terminate/promise.js like this:

const terminate = require('terminate/promise');

(async () => {
  try {
    await terminate(process.pid);
    console.log('done');
  } catch (err) {
    console.log('Oopsy:', err);
  }
})();

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

• spawning node.js child processes results in zombie processes on cloud foundry
• Why does my node app process keep getting stopped when I use forever?
• kill all child_process when node process is killed
• Why doesn't my Node.js process terminate once all listeners have been removed?
• nodejs exec command failing with no useful error message
• How many child processes can a node.js cluster spawn on a 64bit Wintel PC?
• 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!

This Project Reminded me of Two xkcd Comics: