From 83a71fd86e8d67e15434e7d37c087b249da2663a Mon Sep 17 00:00:00 2001 From: Joe Lapp Date: Sat, 24 Dec 2016 16:24:23 -0600 Subject: [PATCH] Rewritten to accommodate signal delgation for #3. Added extensive test suite. --- README.md | 129 ++++++++++-- node-cleanup.js | 164 ++++++++++----- package.json | 6 +- tests/bin/grandchild.js | 23 +++ tests/bin/groupable.js | 92 +++++++++ tests/bin/stackable.js | 70 +++++++ tests/lib/library.js | 88 ++++++++ tests/multiple.js | 259 ++++++++++++++++++++++++ tests/nocleanup.js | 139 +++++++++++++ tests/single.js | 431 ++++++++++++++++++++++++++++++++++++++++ 10 files changed, 1334 insertions(+), 67 deletions(-) create mode 100755 tests/bin/grandchild.js create mode 100755 tests/bin/groupable.js create mode 100755 tests/bin/stackable.js create mode 100755 tests/lib/library.js create mode 100644 tests/multiple.js create mode 100644 tests/nocleanup.js create mode 100644 tests/single.js diff --git a/README.md b/README.md index 12c13bb..188f601 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # node-cleanup -installs a cleanup handler that always runs on exiting node +installs custom cleanup handlers that run on exiting node ## Installation @@ -8,46 +8,141 @@ installs a cleanup handler that always runs on exiting node npm install node-cleanup --save ``` -## Usage +## Overview + +`nodeCleanup()` installs functions that perform cleanup activities just before the node process exits. Let's call these functions "cleanup handlers." The cleanup handlers run under the following conditions: + +- When the process exits normally (exit code 0). +- When the process exits due to an error, such as an uncaught exception (exit code 1). +- When the process receives one of the following POSIX signals: SIGINT (e.g. *Ctrl-C*), SIGHUP, SIGQUIT, or SIGTERM. + +This solution has the following features: + +- Allows cleanup handlers to behave as a function of exit code and signal. +- Allows multiple independent subsystems to install cleanup handlers. +- Allows for asynchronous cleanup on receiving a signal by postponing process termination. +- Allows for deferring to child processes the decision about whether a signal terminates the present process. For example, Emacs intercepts *Ctrl-C*, which should prevent its parent process from terminating. +- Allows for writing custom messages to `stderr` on SIGINT (e.g. *Ctrl-C*) and uncaught exceptions, regardless of the number of cleanup handlers installed. +- Allows for uninstalling all cleanup handlers, such as to change termination behavior after having intercepted and cleaned up for a signal. + +The module also has an extensive test suite to help ensure reliability. -nodeCleanup() installs a function that performs cleanup activities just before the node process exits. The cleanup function runs when the process exits normally, when the user presses *ctrl-C*, and when an exception is uncaught. The caller may specify the termination messages to use. +## Usage -You may call nodeCleanup() multiple times to install multiple cleanup handlers, but only the messages provided with the first call get used. +Here is the typical way to use `nodeCleanup()`: ```js var nodeCleanup = require('node-cleanup'); -nodeCleanup(function () { +nodeCleanup(function (exitCode, signal) { // release resources here before node exits }); ``` -nodeCleanup() also ensures that *ctrl-C* is handled gracefully in contexts that already have exit handlers installed, such as Node Express. To receive just this benefit, the caller need not provide a cleanup handler. +If you only want to install your own messages for *Ctrl-C* and uncaught exception (either or both), you can do this: + +```js +nodeCleanup(null, { + ctrl_C: "{^C}", + uncaughtException: "Uh oh. Look what happened:" +}); +``` + +To get just the default `stderr` messages, without installing a cleanup handler: -By default, `nodeCleanup()` writes "[ctrl-C]" to `stderr` when interrupted and "Uncaught exception..." to `stderr` when an uncaught exception occurs. You may override either or both of these values in a second parameter: +```js +nodeCleanup(); +``` + +You may also combine these to install a cleanup handler and `stderr` messages: + +```js +nodeCleanup(function (exitCode, signal) { + // release resources here before node exits +}, { + ctrl_C: "{^C}", + uncaughtException: "Uh oh. Look what happened:" +}); +``` + +You may perform asynchronous cleanup upon receiving a signal, as follows: + +```js +nodeCleanup(function (exitCode, signal) { + if (signal) { + unsavedData.save(function done() { + // calling process.exit() won't inform parent process of signal + process.kill(process.pid, signal); + }); + nodeCleanup.uninstall(); // don't call cleanup handler again + return false; + } +}); +``` + +When you hit *Ctrl-C*, you send a SIGINT signal to each process in the current process group. A process group is set of processes that are all supposed to end together as a group instead of persisting independently. However, some programs, such as Emacs, intercept and repurpose SIGINT so that it does not end the process. In such cases, SIGINT should not end any processes of the group. Here is how you can delegate the decision to terminate to a child process: ```js var nodeCleanup = require('node-cleanup'); +var fork = require('child_process').fork; + +var child = fork('path-to-child-script.js'); +child.on('exit', function (exitCode, signal) { + child = null; // enable the cleanup handler + if (signal === 'SIGINT') + process.kill(process.pid, 'SIGINT'); +}); -nodeCleanup(function () { +nodeCleanup(function (exitCode, signal) { + if (child !== null && signal === 'SIGINT') + return false; // don't exit yet // release resources here before node exits -}, { ctrl_C: '^C' }); +}); ``` ## Reference -`function nodeCleanup(cleanupHandler, messages)` +### `nodeCleanup()` + +`nodeCleanup()` has the following ([FlowType](https://flowtype.org/docs/getting-started.html#_)) signature: + +```js +function nodeCleanup(cleanupHandler?: Function, messages?: object): void +``` + +`nodeCleanup()` installs a cleanup handler. It may also assign messages to write to `stderr` on SIGINT or an uncaught exception. Both parameters are optional. If not `cleanupHandler` is provided, the `stderr` messages are still written. If no `messages` are provided, default `stderr` messages are written. Calling `nodeCleanup()` with no parameters just installs these default messages. + +`cleanupHandler` is a cleanup handler callback and is described in its own section below. When null or undefined, termination events all result in the process terminating, including signals. + +`messages` is an object mapping any of the keys `ctrl_C` and `uncaughtException` to message strings that output to `stderr`. Default messages are provided for omitted messages. Set a message to the empty string `''` inhibit the message. + +`nodeCleanup()` may be called multiple times to install multiple cleanup handlers. Each of these handlers runs for each signal or termination condition. The first call to `nodeCleanup()` establishes the `stderr` messages; messages passed to subsequent calls are ignored. + +### `nodeCleanup.uninstall()` + +`nodeCleanup.uninstall()` uninstalls all installed cleanup handlers and voids the `stderr` message assignments. It may be called multiple times without harm. + +This function is primarily useful when a signal occurs and the cleanup handler performs cleanup but disables immediate process termination. In this case, when it is finally time to terminate the process, the cleanup handlers shouldn't run again, so the process uninstalls the handlers before terminating itself. + +### Cleanup Handlers + +Each cleanup handler has the following ([FlowType](https://flowtype.org/docs/getting-started.html#_)) signature: + +```js +function cleanupHandler(exitCode: number|null, signal: string|null): boolean? +``` + +If the process is terminating for a reason other than a POSIX signal, `exitCode` is the exit code, and `signal` is null. Otherwise, if the process received a signal, `signal` is the signal's string name, and `exitCode` is null. These are the arguments passed to a [child process `exit` event](https://nodejs.org/api/child_process.html#child_process_event_exit) handler, mirrored here in `node-cleanup` for consistency. + +Node.js defines [these standard exit codes](https://nodejs.org/api/process.html#process_exit_codes), but it does not appear to use code values >128 for signals. According to the node.js docs, [these are the possible signals](http://man7.org/linux/man-pages/man7/signal.7.html). -Install a cleanup handler that reliably runs when node exits. Both parameters are optional. Calling `nodeCleanup()` without a `cleanupHandler` still provides the benefit of ensuring that other installed exit handlers run on *ctrl-C*. +The return value of a cleanup handler is only significant for signals. If any cleanup handler returns a boolean `false`, the process does not exit. If they all return `true` (or for backwards compatibility, no return value), the process exits, reporting the signal to the parent process as the reason for the exit. The process always exits after calling the cleanup handlers for non-signals. -Call this function multiple times to install multiple cleanup handlers. Only the messages provided with the first call are used. +When a cleanup handler returns `false` to prevent the process from exiting, the cleanup handler normally takes steps to ensure proper termination later. For example, the process may wait for asynchronous cleanup to complete, or it may wait for a child process to signal termination. Normally in these cases the process would use `nodeCleanup.uninstall()` to uninstall the cleanup handlers prior to the second termination to prevent them from running again. -| Param | Description | -| --- | --- | -| cleanupHandler | A function that performs the final cleanup of resources before the node process exits. The function may write to `stderr` and `stdout`. It takes no parameters and can't abort the exit. The handler is optional, defaulting to a function that does nothing. | -| messages | An optional object mapping any of the keys `ctrl_C` and `uncaughtException` to the message strings that output to stderr. Set a message to the empty string `''` to prevent output to `stderr` for its case. Default messages are provided omitted messages. | +A cleanup handler should never call `process.exit()`. If a handler prevents a signal from terminating the process but later wishes to terminate the process for reason of this signal, the process should call `process.kill(process.pid, signal)`. In particular, the process should **not** call `process.exit(128 + signalNumber)`, because while this does communicate the exit code to the parent process, it does not communicate the exit signal by the means that the [node.js `child_process` expects](https://nodejs.org/api/child_process.html#child_process_event_exit). ## Credit -This code was borrowed and modified from [CanyonCasa](http://stackoverflow.com/users/3319552/canyoncasa)'s answer to a stackoverflow question. I found the code necessary for all my node projects. See [the stackoverflow answer](http://stackoverflow.com/a/21947851/650894) for more examples of use. +This module began by borrowing and modifying code from CanyonCasa's [answer to a stackoverflow question](http://stackoverflow.com/a/21947851/650894). I had found the code necessary for all my node projects. @Banjocat piped in with a [comment](http://stackoverflow.com/questions/14031763/doing-a-cleanup-action-just-before-node-js-exits/21947851#comment68567869_21947851) about how the solution didn't properly handle SIGINT. (See [this detailed explanation](https://www.cons.org/cracauer/sigint.html) of the SIGINT problem). I have completely rewritten the module to properly deal with SIGINT and other signals (I hope!). The rewrite also provides some additional flexibility I found myself needing in my projects. diff --git a/node-cleanup.js b/node-cleanup.js index 45dff29..9d9f032 100644 --- a/node-cleanup.js +++ b/node-cleanup.js @@ -1,61 +1,127 @@ -/** - * nodeCleanup() installs a function that performs cleanup activities just - * before the node process exits. The cleanup function runs when the process - * exits normally, when the user presses ctrl-C, and when an exception is - * uncaught. The caller may specify the termination messages to use. - * - * Call this function multiple times to install multiple cleanup handlers. - * Only the messages provided with the first call are used. - * - * See https://github.com/jtlapp/node-cleanup for more information. Code - * largely borrowed from http://stackoverflow.com/a/21947851/650894. - */ +/****************************************************************************** +nodeCleanup() installs functions -- cleanup handlers -- that perform cleanup activities just before the node process exits, except on SIGKILL, which can't be intercepted. nodeCleanup() can also install messages to be written to stderr on either SIGINT or an uncaught exception. + +Each cleanup handler has the following (FlowType) signature: + + cleanupHandler(exitCode: number|null, signal: string|null): boolean? + +If the process is terminating for a reason other than a signal, exitCode is an integer that provides the reason for termination, and signal is null. If the process received a POSIX signal, signal is the signal's string name, and exitCode is null. These are also the arguments passed to a process' `exit` event handler, mirrored in node-cleanup for consistency. + +The process terminates after cleanup, except possibly on signals. If any cleanup handler returns a boolean false for a signal, the process will not exit; otherwise the process exits. SIGKILL cannot be intercepted. + +Install a cleanup handler as follows: + + var nodeCleanup = require('node-cleanup'); + nodeCleanup(cleanupHandler, terminationMessages); + +nodeCleanup() may be called multiple times to install multiple cleanup handlers. However, only the termination messages established by the first call get used. + +The following uninstalls all cleanup handlers and may be called multiple times in succession: + + nodeCleanup.uninstall(); + +This module has its origin in code by @CanyonCasa at http://stackoverflow.com/a/21947851/650894, but the module was significantly rewritten to resolve issues raised by @Banjocat at http://stackoverflow.com/questions/14031763/doing-a-cleanup-action-just-before-node-js-exits#comment68567869_21947851. It has also been extended for greater configurability. +******************************************************************************/ -var installed = false; +//// CONSTANTS //////////////////////////////////////////////////////////////// -module.exports = function nodeCleanup(cleanupHandler, messages) { +var DEFAULT_SIGINT_MSG = '[ctrl-C]'; +var DEFAULT_EXCEPTION_MSG = 'Uncaught exception...'; + +//// CONFIGURATION //////////////////////////////////////////////////////////// - // attach user callback to the process event emitter. - // if no callback, it will still exit gracefully on Ctrl-C - cleanupHandler = cleanupHandler || noOp; - process.on('cleanup', cleanupHandler); - - // only install the termination handlers once - if (!installed) { - install(messages); - installed = true; - } -}; +var cleanupHandlers = null; // array of cleanup handlers to call +var exceptionMessage = null; // stderr message for uncaught exceptions -function install(messages) { +var sigintHandler; // POSIX signal handlers +var sighupHandler; +var sigquitHandler; +var sigtermHandler; - messages = messages || {}; - if (typeof messages.ctrl_C !== 'string') - messages.ctrl_C = '[ctrl-C]'; - if (typeof messages.uncaughtException !== 'string') - messages.uncaughtException = 'Uncaught exception...'; +//// HANDLERS ///////////////////////////////////////////////////////////////// - // do app-specific cleaning before exiting - process.on('exit', function (code) { - process.emit('cleanup', code); +function signalHandler(signal, message) +{ + var exit = true; + cleanupHandlers.forEach(function (cleanup) { + if (cleanup(null, signal) === false) + exit = false; }); + if (exit) { + if (message !== '') + process.stderr.write(message + "\n"); + uninstall(); // don't cleanup again + // necessary to communicate the signal to the parent process + process.kill(process.pid, signal); + } +} - // catch ctrl+c event and exit normally - process.on('SIGINT', function () { - if (messages.ctrl_C !== '') { - process.stderr.write(messages.ctrl_C + "\n"); - } - process.exit(130); - }); +function exceptionHandler(e) +{ + if (exceptionMessage !== '') + process.stderr.write(exceptionMessage + "\n"); + process.stderr.write(e.stack + "\n"); + process.exit(1); // will call exitHandler() for cleanup +} - //catch uncaught exceptions, trace, then exit normally - process.on('uncaughtException', function(e) { - if (messages.uncaughtException !== '') { - process.stderr.write(messages.uncaughtException + "\n"); - process.stderr.write(e.stack + "\n"); - } - process.exit(99); +function exitHandler(exitCode, signal) +{ + cleanupHandlers.forEach(function (cleanup) { + cleanup(exitCode, signal); }); } -function noOp() {}; // for just the benefit of graceful SIGINTs +//// MAIN ///////////////////////////////////////////////////////////////////// + +function install(cleanupHandler, messages) +{ + if (cleanupHandlers === null) { + cleanupHandlers = []; // establish before installing handlers + + messages = messages || {}; + if (typeof messages.ctrl_C !== 'string') + messages.ctrl_C = DEFAULT_SIGINT_MSG; + if (typeof messages.uncaughtException !== 'string') + messages.uncaughtException = DEFAULT_EXCEPTION_MSG; + exceptionMessage = messages.uncaughtException; + + sigintHandler = signalHandler.bind(this, 'SIGINT', messages.ctrl_C); + sighupHandler = signalHandler.bind(this, 'SIGHUP', ''); + sigquitHandler = signalHandler.bind(this, 'SIGQUIT', ''); + sigtermHandler = signalHandler.bind(this, 'SIGTERM', ''); + + process.on('SIGINT', sigintHandler); + process.on('SIGHUP', sighupHandler); + process.on('SIGQUIT', sigquitHandler); + process.on('SIGTERM', sigtermHandler); + process.on('uncaughtException', exceptionHandler); + process.on('exit', exitHandler); + + cleanupHandlers.push(cleanupHandler || noCleanup); + } + else if (cleanupHandler) + cleanupHandlers.push(cleanupHandler); +} + +function uninstall() +{ + if (cleanupHandlers !== null) { + process.removeListener('SIGINT', sigintHandler); + process.removeListener('SIGHUP', sighupHandler); + process.removeListener('SIGQUIT', sigquitHandler); + process.removeListener('SIGTERM', sigtermHandler); + process.removeListener('uncaughtException', exceptionHandler); + process.removeListener('exit', exitHandler); + cleanupHandlers = null; // null only after uninstalling + } +} + +function noCleanup() +{ + return true; // signals will always terminate process +} + +//// EXPORTS ////////////////////////////////////////////////////////////////// + +module.exports = install; +install.uninstall = uninstall; diff --git a/package.json b/package.json index d8d0784..d2b64c3 100644 --- a/package.json +++ b/package.json @@ -32,5 +32,9 @@ "bugs": { "url": "https://github.com/jtlapp/node-cleanup/issues" }, - "homepage": "https://github.com/jtlapp/node-cleanup#readme" + "homepage": "https://github.com/jtlapp/node-cleanup#readme", + "devDependencies": { + "memory-streams": "^0.1.0", + "tap": "^8.0.1" + } } diff --git a/tests/bin/grandchild.js b/tests/bin/grandchild.js new file mode 100755 index 0000000..90b568c --- /dev/null +++ b/tests/bin/grandchild.js @@ -0,0 +1,23 @@ +#!/usr/bin/env node + +/****************************************************************************** +Grandchild process used to test process group signals. It conditionally ignores SIGINTs in order to emulate programs that catch and discard them. +******************************************************************************/ + +var heedSignal = (process.argv[2] === 'true'); +var waitMillis = parseInt(process.argv[3]); + +if (!heedSignal) { + process.on('SIGINT', function () { + // ignore it + }); +} + +setTimeout(function () { + // disconnect IPC so can exit when stdout, stderr, + // child processes, and other resources complete. + process.disconnect(); + process.exit(0); +}, waitMillis); + +process.send('ready'); diff --git a/tests/bin/groupable.js b/tests/bin/groupable.js new file mode 100755 index 0000000..3c569af --- /dev/null +++ b/tests/bin/groupable.js @@ -0,0 +1,92 @@ +#!/usr/bin/env node + +/****************************************************************************** +Child process that installs node-cleanup for testing in situations that may entail forking a grandchild process in the same process group. It accepts a single argument of serialized JSON having the following (FlowType) structure: + +{ + grandchild: boolean; // whether to fork a grandchild process + grandchildHeedsSIGINT: boolean; // whether grandchild heeds SIGINT + messages: object|null; // messages argument for nodeCleanup() + exception: boolean; // whether to throw an uncaught exception + skipTermination: boolean; // true => cleanup handler returns false + exitReturn: 'true'|'undefined'; // value that cleanup handler should + // return to indicate whether the process should exit + maxDuration: number; // max duration of process in millisecs +} + +exitReturn indicates the type of value that the cleanup handler returns to indicate whether the process should exit on SIGINT. Ideally, the handler would always return a boolean, but for backwards compatibility, for compatibility with the Stackoverflow solution, and to allow programmers some room for laziness when there are no child processes, an undefined return value also indicates 'true'. + +This process implements the WCE solution described for SIGINT at https://www.cons.org/cracauer/sigint.html. That is, the process ignores a SIGINT received while a nested process is running, but sends a SIGINT to itself after a nested process terminates with SIGINT. SIGQUIT is not handled this way because it is not expected that child processes would override and ignore it. + +The process writes behavioral results to stdout for comparison with expectations. The output includes space-delimited strings from the following list, ordered in the string by their order of occurrence: + + cleanup - child's cleanup handler was called and performed cleanup + skipped_cleanup - child's cleanup handler was called for SIGINT but + did not perform cleanup because a child was running. + grandchild= - grandchild exited for the given reason, which is + either an integer exit code or the string name of a signal + +The process also writes to stderr for comparison with expectations. +******************************************************************************/ + +//// MODULES ////////////////////////////////////////////////////////////////// + +var path = require('path'); +var fork = require('child_process').fork; +var nodeCleanup = require('../../'); + +//// CONFIGURATION //////////////////////////////////////////////////////////// + +var config = JSON.parse(process.argv[2]); +var grandchildFile = path.resolve(__dirname, "./grandchild.js"); +var grandchildMaxDuration = Math.round(config.maxDuration*0.65); + +//// STATE //////////////////////////////////////////////////////////////////// + +var grandchild = null; + +//// MAIN ///////////////////////////////////////////////////////////////////// + +nodeCleanup(function (exitCode, signal) { + var reason = (exitCode !== null ? exitCode : signal); + if (grandchild !== null && reason === 'SIGINT') { + process.stdout.write('skipped_cleanup '); + return false; + } + process.stdout.write('cleanup '); + if (config.skipTermination) { + nodeCleanup.uninstall(); // don't cleanup again + return false; + } + if (config.exitReturn === 'true') + return true; +}, config.messages); + +setTimeout(function () { + // disconnect IPC so can exit when stdout, stderr, + // child processes, and other resources complete. + process.disconnect(); + if (config.exception) + throw new Error("unexpected exception"); + process.exit(0); +}, config.maxDuration); + +if (config.grandchild) { + grandchild = fork(grandchildFile, [ + config.grandchildHeedsSIGINT, + grandchildMaxDuration + ]); + grandchild.on('message', function (msg) { + if (msg === 'ready') + process.send('ready'); + }); + grandchild.on('exit', function (exitCode, signal) { + grandchild = null; // allow process to heed forthcoming SIGINT + process.stdout.write('grandchild='+ + (exitCode !== null ? exitCode : signal) +' '); + if (signal === 'SIGINT') + process.kill(process.pid, signal); + }); +} +else + process.send('ready'); diff --git a/tests/bin/stackable.js b/tests/bin/stackable.js new file mode 100755 index 0000000..fb8d466 --- /dev/null +++ b/tests/bin/stackable.js @@ -0,0 +1,70 @@ +#!/usr/bin/env node + +/****************************************************************************** +Child process that installs node-cleanup for testing zero, one, or multiple (two) concurrent cleanup handlers. It accepts a single argument of serialized JSON having the following (FlowType) structure: + +{ + handlers; number; // 0, 1, or 2 concurrent cleanup handlers + messages1: object|null; // messages argument for 1st nodeCleanup() call + messages2: object|null; // messages argument for 2nd nodeCleanup() call + return1: boolean; // return value of 1st cleanup handler + return2: boolean; // return value of 2nd cleanup handler + uninstall: boolean; // whether to uninstall handlers before test + maxDuration: number; // max duration of process in millisecs +} + +The process writes behavioral results to stdout for comparison with expectations. The output includes space-delimited strings from the following list, ordered in the string by their order of occurrence: + + cleanup1 - the first cleanup handler ran + cleanup2 - the second cleanup handler ran + +The process also writes to stderr for comparison with expectations. +******************************************************************************/ + +//// MODULES ////////////////////////////////////////////////////////////////// + +var nodeCleanup = require('../../'); + +//// CONFIGURATION //////////////////////////////////////////////////////////// + +var config = JSON.parse(process.argv[2]); + +//// CLEANUP HANDLERS ///////////////////////////////////////////////////////// + +function cleanup1(exitCode, signal) { + process.stdout.write('cleanup1 '); + if (!config.return1) + nodeCleanup.uninstall(); // don't cleanup again + return config.return1; +} + +function cleanup2(exitCode, signal) { + process.stdout.write('cleanup2 '); + if (!config.return2) + nodeCleanup.uninstall(); // don't cleanup again + return config.return2; +} + +//// MAIN ///////////////////////////////////////////////////////////////////// + +if (config.handlers === 0) + nodeCleanup(); +else { + nodeCleanup(cleanup1, config.messages1); + if (config.handlers > 1) + nodeCleanup(cleanup2, config.messages2); +} + +if (config.uninstall) + nodeCleanup.uninstall(); + +setTimeout(function () { + // disconnect IPC so can exit when stdout, stderr, + // child processes, and other resources complete. + process.disconnect(); + if (config.exception) + throw new Error("unexpected exception"); + process.exit(0); +}, config.maxDuration); + +process.send('ready'); diff --git a/tests/lib/library.js b/tests/lib/library.js new file mode 100755 index 0000000..62aaca4 --- /dev/null +++ b/tests/lib/library.js @@ -0,0 +1,88 @@ +/****************************************************************************** +Library of functions for running child processes. +******************************************************************************/ + +//// MODULES ////////////////////////////////////////////////////////////////// + +var MemoryStream = require('memory-streams').WritableStream; +var path = require('path'); +var spawn = require('child_process').spawn; + +//// PUBLIC CONSTANTS ///////////////////////////////////////////////////////// + +exports.DEFAULT_SIGINT_OUT = "[ctrl-C]\n"; +exports.DEFAULT_EXCEPTION_OUT = /^Uncaught exception\.\.\./; + +//// PRIVATE CONSTANTS //////////////////////////////////////////////////////// + +var MAX_DURATION = 250; // max duration of child process in millisecs + +var childEnv = {}; +Object.keys(process.env).forEach(function (key) { + childEnv[key] = process.env[key]; +}); +var childOptions = { + env: childEnv, + stdio: ['inherit', 'pipe', 'pipe', 'ipc'], + detached: true +}; + +//// FUNCTIONS //////////////////////////////////////////////////////////////// + +/** + * Launch a child process that uses nodeCleanup(), performing an action once the child is running, and provide the results of the run when the child exits. The child runs in a new process group, separate from the test process, so that the caller may signal the group as a whole. + * + * @param config Child process configuration. See the description of this structure in the comments of tests/bin/child.js. + * @param action A callback function(childPID) that may send signals to the child or the child's process group (-childPID). Must be synchronous. + * @param done A callback function(reason, stdoutString, stderrString) providing the output of the child. This callback should test this output against expectations. reason is the exit code, unless the process was terminated by a signal, in which case it is the string name of the signal. + */ + +exports.launch = function (config, action, done) +{ + config.maxDuration = MAX_DURATION; + var childPath = path.resolve(__dirname, "../bin/"+ config.child +".js"); + var childArgs = [ childPath, JSON.stringify(config) ]; + var child = spawn(process.execPath, childArgs, childOptions); + var stdoutStream = new MemoryStream(); + var stderrStream = new MemoryStream(); + child.stdout.pipe(stdoutStream); + child.stderr.pipe(stderrStream); + + child.on('message', function (msg) { + if (msg === 'ready') + action(child.pid); + }); + + child.on('exit', function (exitCode, signal) { + done((exitCode !== null ? exitCode : signal), + stdoutStream.toString(), stderrStream.toString()); + }); +}; + +/** + * Shorthand function for launching a process, optionally sending a signal to it, and testing the resulting output. It calls t.equal() or t.match() on each of the expected results, depending on whether it is a string or a regular expression, and then t.end() to complete the test. + * + * @param t tap test instance + * @param config See launch() config. + * @param action See launch() action. + * @param expectedResults A structure of the form {exitCode, stdout, stderr} containing the expected output of the test. exitCode is an integer. stdout and stderr are strings or regular expressions. stdout is compared against the result trimmed of preceding and trailing whitespace. When stdout or stderr is a string, it is tested for being identical with the actual result. + */ + +exports.test = function (t, config, action, expectedResults) +{ + exports.launch(config, action, function (reason, stdout, stderr) { + t.equal(reason, expectedResults.exitReason, "exit reason"); + + stdout = stdout.trim(); + if (typeof expectedResults.stdout === 'string') + t.equal(stdout, expectedResults.stdout, "stdout"); + else + t.match(stdout, expectedResults.stdout, "stdout"); + + if (typeof expectedResults.stderr === 'string') + t.equal(stderr, expectedResults.stderr, "stderr"); + else + t.match(stderr, expectedResults.stderr, "stderr"); + t.end(); + }); +}; diff --git a/tests/multiple.js b/tests/multiple.js new file mode 100644 index 0000000..e1bf796 --- /dev/null +++ b/tests/multiple.js @@ -0,0 +1,259 @@ +// tests in which spawned child installs multiple cleanup handlers + +var t = require('tap'); +var lib = require('./lib/library'); + +t.test("multiple handlers: normal exit", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "cleanup1 cleanup2", + stderr: "" + }); +}); + +t.test("multiple handlers: uncaught exception - default message", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: true, + uninstall: false + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "cleanup1 cleanup2", + stderr: lib.DEFAULT_EXCEPTION_OUT + }); +}); + +t.test("multiple handlers: uncaught exception - custom message", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: { + uncaughtException: "Look! A surprise!" + }, + messages2: { + uncaughtException: "Not the surprise you're looking for." + }, + return1: true, + return2: true, + exception: true, + uninstall: false + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "cleanup1 cleanup2", + stderr: /^Look! A surprise!/ + }); +}); + +t.test("multiple handlers: child SIGINT - both heeded", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup1 cleanup2", + stderr: lib.DEFAULT_SIGINT_OUT + }); +}); + +t.test("multiple handlers: child SIGINT - first heeded", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: false, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 0, + stdout: "cleanup1 cleanup2", + stderr: "" + }); +}); + +t.test("multiple handlers: child SIGINT - second heeded", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: false, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 0, + stdout: "cleanup1 cleanup2", + stderr: "" + }); +}); + +t.test("multiple handlers: child SIGINT - custom message", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: { + ctrl_C: "{^C1}" + }, + messages2: { + ctrl_C: "{^C2}" + }, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup1 cleanup2", + stderr: "{^C1}\n" + }); +}); + +t.test("multiple handlers: child SIGQUIT", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGQUIT'); + }, { + exitReason: 'SIGQUIT', + stdout: "cleanup1 cleanup2", + stderr: "" + }); +}); + +t.test("multiple handlers: child SIGTERM", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGTERM'); + }, { + exitReason: 'SIGTERM', + stdout: "cleanup1 cleanup2", + stderr: "" + }); +}); + +t.test("multiple handlers: child SIGKILL", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGKILL'); + }, { + exitReason: 'SIGKILL', + stdout: "", + stderr: "" + }); +}); + +t.test("multiple handlers/uninstall: normal child exit", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: true + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "", + stderr: "" + }); +}); + +t.test("multiple handlers/uninstall: uncaught exception", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: true, + uninstall: true + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "", + stderr: /tests[\/\\]bin[\/\\]stackable.js/ + }); +}); + +t.test("multiple handlers/uninstall: child SIGINT", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 2, + messages1: null, + messages2: null, + return1: true, + return2: true, + exception: false, + uninstall: true + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "", + stderr: "" + }); +}); diff --git a/tests/nocleanup.js b/tests/nocleanup.js new file mode 100644 index 0000000..6f85f4c --- /dev/null +++ b/tests/nocleanup.js @@ -0,0 +1,139 @@ +// tests in which spawned child uses the default cleanup handler + +var t = require('tap'); +var lib = require('./lib/library'); + +t.test("nocleanup: normal child exit", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: false + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "", + stderr: "" + }); +}); + +t.test("nocleanup: uncaught exception", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: true, + uninstall: false + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "", + stderr: lib.DEFAULT_EXCEPTION_OUT + }); +}); + +t.test("nocleanup: child SIGINT", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "", + stderr: lib.DEFAULT_SIGINT_OUT + }); +}); + +t.test("nocleanup: child SIGQUIT", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGQUIT'); + }, { + exitReason: 'SIGQUIT', + stdout: "", + stderr: "" + }); +}); + +t.test("nocleanup: child SIGTERM", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGTERM'); + }, { + exitReason: 'SIGTERM', + stdout: "", + stderr: "" + }); +}); + +t.test("nocleanup: child SIGKILL", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: false + }, function (childPID) { + process.kill(childPID, 'SIGKILL'); + }, { + exitReason: 'SIGKILL', + stdout: "", + stderr: "" + }); +}); + +t.test("nocleanup/uninstall: normal child exit", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: true + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "", + stderr: "" + }); +}); + +t.test("nocleanup/uninstall: uncaught exception", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: true, + uninstall: true + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "", + stderr: /tests[\/\\]bin[\/\\]stackable.js/ + }); +}); + +t.test("nocleanup/uninstall: child SIGINT", function (t) { + lib.test(t, { + child: 'stackable', + handlers: 0, + exception: false, + uninstall: true + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "", + stderr: "" + }); +}); diff --git a/tests/single.js b/tests/single.js new file mode 100644 index 0000000..3d06e2f --- /dev/null +++ b/tests/single.js @@ -0,0 +1,431 @@ +// tests in which spawned child installs a custom cleanup handler + +var t = require('tap'); +var lib = require('./lib/library'); + +t.test("single: normal child exit - true return", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: normal child exit - undefined return", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'undefined' + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: normal grandchild exit", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + // no signal + }, { + exitReason: 0, + stdout: "grandchild=0 cleanup", + stderr: "" + }); +}); + +t.test("single: uncaught exception - default message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: true, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "cleanup", + stderr: lib.DEFAULT_EXCEPTION_OUT + }); +}); + +t.test("single: uncaught exception - custom message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: { + uncaughtException: "Oh gosh look what happened:" + }, + exception: true, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "cleanup", + stderr: /^Oh gosh look what happened:/ + }); +}); + +t.test("single: uncaught exception - no message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: { + uncaughtException: "" + }, + exception: true, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + // no signal + }, { + exitReason: 1, + stdout: "cleanup", + stderr: /^Error: unexpected exception/ + }); +}); + +t.test("single: child SIGINT - true return, default message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup", + stderr: lib.DEFAULT_SIGINT_OUT + }); +}); + +t.test("single: child SIGINT - undefined return, default message", + function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'undefined' + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup", + stderr: lib.DEFAULT_SIGINT_OUT + }); + } +); + +t.test("single: child SIGINT - custom message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: { + ctrl_C: "{^C}" + }, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup", + stderr: "{^C}\n" + }); +}); + +t.test("single: child SIGINT - no message", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: { + ctrl_C: "" + }, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: group SIGINT - grandchild ignores", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGINT'); + }, { + exitReason: 0, + stdout: "skipped_cleanup grandchild=0 cleanup", + stderr: "" + }); +}); + +t.test("single: group SIGINT - grandchild heeds", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: true, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGINT'); + }, { + exitReason: 'SIGINT', + stdout: "skipped_cleanup grandchild=SIGINT cleanup", + stderr: lib.DEFAULT_SIGINT_OUT + }); +}); + +t.test("single: child SIGHUP - exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGHUP'); + }, { + exitReason: 'SIGHUP', + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: child SIGHUP - non-exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: true, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGHUP'); + }, { + exitReason: 0, + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: group SIGHUP", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGHUP'); + }, { + exitReason: 'SIGHUP', + // grandchild may exit before,during, or after child exits + stdout: /^(cleanup( grandchild=SIGHUP)?|grandchild=SIGHUP cleanup)$/, + stderr: "" + }); +}); + +t.test("single: child SIGQUIT - exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGQUIT'); + }, { + exitReason: 'SIGQUIT', + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: child SIGQUIT - non-exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: true, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGQUIT'); + }, { + exitReason: 0, + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: group SIGQUIT", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGQUIT'); + }, { + exitReason: 'SIGQUIT', + // grandchild may exit before,during, or after child exits + stdout: /^(cleanup( grandchild=SIGQUIT)?|grandchild=SIGQUIT cleanup)$/, + stderr: "" + }); +}); + +t.test("single: child SIGTERM - exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGTERM'); + }, { + exitReason: 'SIGTERM', + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: child SIGTERM - non-exiting", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: true, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGTERM'); + }, { + exitReason: 0, + stdout: "cleanup", + stderr: "" + }); +}); + +t.test("single: group SIGTERM", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGTERM'); + }, { + exitReason: 'SIGTERM', + // grandchild may exit before,during, or after child exits + stdout: /^(cleanup( grandchild=SIGTERM)?|grandchild=SIGTERM cleanup)$/, + stderr: "" + }); +}); + +t.test("single: child SIGKILL", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: false, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(childPID, 'SIGKILL'); + }, { + exitReason: 'SIGKILL', + stdout: "", + stderr: "" + }); +}); + +t.test("single: group SIGKILL", function (t) { + lib.test(t, { + child: 'groupable', + grandchild: true, + grandchildHeedsSIGINT: false, + messages: null, + exception: false, + skipTermination: false, + exitReturn: 'true' + }, function (childPID) { + process.kill(-childPID, 'SIGKILL'); + }, { + exitReason: 'SIGKILL', + stdout: "", + stderr: "" + }); +});