process: add capture function for uncaught exceptions

doc/api/cli.md

@@ -183,6 +183,10 @@ added: v0.10
 Aborting instead of exiting causes a core file to be generated for post-mortem
 analysis using a debugger (such as `lldb`, `gdb`, and `mdb`).
 
+*Note*: If this flag is passed, the behavior can still be set to not abort
+through [`process.setUncaughtExceptionCaptureCallback()`][] (and through usage
+of the `domain` module that uses it).
+
 ### `--trace-warnings`
 <!-- YAML
 added: v6.0.0
@@ -598,3 +602,4 @@ greater than `4` (its current default value).  For more information, see the
 [debugger]: debugger.html
 [emit_warning]: process.html#process_process_emitwarning_warning_type_code_ctor
 [libuv threadpool documentation]: http://docs.libuv.org/en/latest/threadpool.html
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn

doc/api/errors.md

@@ -729,6 +729,23 @@ A signing `key` was not provided to the [`sign.sign()`][] method.
 
 `c-ares` failed to set the DNS server.
 
+<a id="ERR_DOMAIN_CALLBACK_NOT_AVAILABLE"></a>
+### ERR_DOMAIN_CALLBACK_NOT_AVAILABLE
+
+The `domain` module was not usable since it could not establish the required
+error handling hooks, because
+[`process.setUncaughtExceptionCaptureCallback()`][] had been called at an
+earlier point in time.
+
+<a id="ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE"></a>
+### ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE
+
+[`process.setUncaughtExceptionCaptureCallback()`][] could not be called
+because the `domain` module has been loaded at an earlier point in time.
+
+The stack trace is extended to include the point in time at which the
+`domain` module had been loaded.
+
 <a id="ERR_ENCODING_INVALID_ENCODED_DATA"></a>
 ### ERR_ENCODING_INVALID_ENCODED_DATA
 
@@ -1459,6 +1476,15 @@ A Transform stream finished while it was still transforming.
 
 A Transform stream finished with data still in the write buffer.
 
+<a id="ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET"></a>
+### ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET
+
+[`process.setUncaughtExceptionCaptureCallback()`][] was called twice,
+without first resetting the callback to `null`.
+
+This error is designed to prevent accidentally overwriting a callback registered
+from another module.
+
 <a id="ERR_UNESCAPED_CHARACTERS"></a>
 ### ERR_UNESCAPED_CHARACTERS
 
@@ -1565,6 +1591,7 @@ Creation of a [`zlib`][] object failed due to incorrect configuration.
 [`new URLSearchParams(iterable)`]: url.html#url_constructor_new_urlsearchparams_iterable
 [`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
 [`process.send()`]: process.html#process_process_send_message_sendhandle_options_callback
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`require('crypto').setEngine()`]: crypto.html#crypto_crypto_setengine_engine_flags
 [`server.listen()`]: net.html#net_server_listen
 [ES6 module]: esm.html

doc/api/process.md

@@ -1136,6 +1136,16 @@ if (process.getuid) {
 *Note*: This function is only available on POSIX platforms (i.e. not Windows
 or Android).
 
+## process.hasUncaughtExceptionCaptureCallback()
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {boolean}
+
+Indicates whether a callback has been set using
+[`process.setUncaughtExceptionCaptureCallback()`][].
+
 ## process.hrtime([time])
 <!-- YAML
 added: v0.7.6
@@ -1637,6 +1647,29 @@ if (process.getuid && process.setuid) {
 or Android).
 
 
+## process.setUncaughtExceptionCaptureCallback(fn)
+<!-- YAML
+added: REPLACEME
+-->
+
+* `fn` {Function|null}
+
+The `process.setUncaughtExceptionCapture` function sets a function that will
+be invoked when an uncaught exception occurs, which will receive the exception
+value itself as its first argument.
+
+If such a function is set, the [`process.on('uncaughtException')`][] event will
+not be emitted. If `--abort-on-uncaught-exception` was passed from the
+command line or set through [`v8.setFlagsFromString()`][], the process will
+not abort.
+
+To unset the capture function, `process.setUncaughtExceptionCapture(null)`
+may be used. Calling this method with a non-`null` argument while another
+capture function is set will throw an error.
+
+*Note*: Using this function is mutually exclusive with using the
+deprecated [`domain`][] built-in module.
+
 ## process.stderr
 
 * {Stream}
@@ -1921,6 +1954,7 @@ cases:
 [`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
 [`console.error()`]: console.html#console_console_error_data_args
 [`console.log()`]: console.html#console_console_log_data_args
+[`domain`]: domain.html
 [`end()`]: stream.html#stream_writable_end_chunk_encoding_callback
 [`net.Server`]: net.html#net_class_net_server
 [`net.Socket`]: net.html#net_class_net_socket
@@ -1930,11 +1964,14 @@ cases:
 [`process.exit()`]: #process_process_exit_code
 [`process.exitCode`]: #process_process_exitcode
 [`process.kill()`]: #process_process_kill_pid_signal
+[`process.on('uncaughtException')`]: process.html#process_event_uncaughtexception
+[`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`promise.catch()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch
 [`require()`]: globals.html#globals_require
 [`require.main`]: modules.html#modules_accessing_the_main_module
 [`require.resolve()`]: modules.html#modules_require_resolve_request_options
 [`setTimeout(fn, 0)`]: timers.html#timers_settimeout_callback_delay_args
+[`v8.setFlagsFromString()`]: v8.html#v8_v8_setflagsfromstring_flags
 [Child Process]: child_process.html
 [Cluster]: cluster.html
 [Duplex]: stream.html#stream_duplex_and_transform_streams

lib/domain.js

@@ -28,6 +28,7 @@
 
 const util = require('util');
 const EventEmitter = require('events');
+const errors = require('internal/errors');
 const { createHook } = require('async_hooks');
 
 // communicate with events module, but don't require that
@@ -81,19 +82,77 @@ const asyncHook = createHook({
   }
 });
 
+// When domains are in use, they claim full ownership of the
+// uncaught exception capture callback.
+if (process.hasUncaughtExceptionCaptureCallback()) {
+  throw new errors.Error('ERR_DOMAIN_CALLBACK_NOT_AVAILABLE');
+}
+
+// Get the stack trace at the point where `domain` was required.
+const domainRequireStack = new Error('require(`domain`) at this point').stack;
+
+const { setUncaughtExceptionCaptureCallback } = process;
+process.setUncaughtExceptionCaptureCallback = function(fn) {
+  const err =
+      new errors.Error('ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE');
+  err.stack = err.stack + '\n' + '-'.repeat(40) + '\n' + domainRequireStack;
+  throw err;
+};
+
 // It's possible to enter one domain while already inside
 // another one. The stack is each entered domain.
 const stack = [];
 exports._stack = stack;
-process._setupDomainUse(stack);
+process._setupDomainUse();
 
-class Domain extends EventEmitter {
+function updateExceptionCapture() {
+  if (stack.every((domain) => domain.listenerCount('error') === 0)) {
+    setUncaughtExceptionCaptureCallback(null);
+  } else {
+    setUncaughtExceptionCaptureCallback(null);
+    setUncaughtExceptionCaptureCallback((er) => {
+      return process.domain._errorHandler(er);
+    });
+  }
+}
+
+
+process.on('newListener', (name, listener) => {
+  if (name === 'uncaughtException' &&
+      listener !== domainUncaughtExceptionClear) {
+    // Make sure the first listener for `uncaughtException` always clears
+    // the domain stack.
+    process.removeListener(name, domainUncaughtExceptionClear);
+    process.prependListener(name, domainUncaughtExceptionClear);
+  }
+});
+
+process.on('removeListener', (name, listener) => {
+  if (name === 'uncaughtException' &&
+      listener !== domainUncaughtExceptionClear) {
+    // If the domain listener would be the only remaining one, remove it.
+    const listeners = process.listeners('uncaughtException');
+    if (listeners.length === 1 && listeners[0] === domainUncaughtExceptionClear)
+      process.removeListener(name, domainUncaughtExceptionClear);
+  }
+});
 
+function domainUncaughtExceptionClear() {
+  stack.length = 0;
+  exports.active = process.domain = null;
+  updateExceptionCapture();
+}
+
+
+class Domain extends EventEmitter {
   constructor() {
     super();
 
     this.members = [];
     asyncHook.enable();
+
+    this.on('removeListener', updateExceptionCapture);
+    this.on('newListener', updateExceptionCapture);
   }
 }
 
@@ -131,14 +190,14 @@ Domain.prototype._errorHandler = function _errorHandler(er) {
     // prevent the process 'uncaughtException' event from being emitted
     // if a listener is set.
     if (EventEmitter.listenerCount(this, 'error') > 0) {
+      // Clear the uncaughtExceptionCaptureCallback so that we know that, even
+      // if technically the top-level domain is still active, it would
+      // be ok to abort on an uncaught exception at this point
+      setUncaughtExceptionCaptureCallback(null);
       try {
-        // Set the _emittingTopLevelDomainError so that we know that, even
-        // if technically the top-level domain is still active, it would
-        // be ok to abort on an uncaught exception at this point
-        process._emittingTopLevelDomainError = true;
         caught = this.emit('error', er);
       } finally {
-        process._emittingTopLevelDomainError = false;
+        updateExceptionCapture();
       }
     }
   } else {
@@ -161,20 +220,21 @@ Domain.prototype._errorHandler = function _errorHandler(er) {
       if (this === exports.active) {
         stack.pop();
       }
+      updateExceptionCapture();
       if (stack.length) {
         exports.active = process.domain = stack[stack.length - 1];
-        caught = process._fatalException(er2);
+        caught = process.domain._errorHandler(er2);
       } else {
-        caught = false;
+        // Pass on to the next exception handler.
+        throw er2;
       }
     }
   }
 
   // Exit all domains on the stack.  Uncaught exceptions end the
   // current tick and no domains should be left on the stack
   // between ticks.
-  stack.length = 0;
-  exports.active = process.domain = null;
+  domainUncaughtExceptionClear();
 
   return caught;
 };
@@ -185,6 +245,7 @@ Domain.prototype.enter = function() {
   // to push it onto the stack so that we can pop it later.
   exports.active = process.domain = this;
   stack.push(this);
+  updateExceptionCapture();
 };
 
 
@@ -198,6 +259,7 @@ Domain.prototype.exit = function() {
 
   exports.active = stack[stack.length - 1];
   process.domain = exports.active;
+  updateExceptionCapture();
 };
 
 

lib/internal/bootstrap_node.js

@@ -9,6 +9,7 @@
 
 (function(process) {
   let internalBinding;
+  const exceptionHandlerState = { captureFn: null };
 
   function startup() {
     const EventEmitter = NativeModule.require('events');
@@ -35,6 +36,7 @@
     const _process = NativeModule.require('internal/process');
     _process.setupConfig(NativeModule._source);
     _process.setupSignalHandlers();
+    _process.setupUncaughtExceptionCapture(exceptionHandlerState);
     NativeModule.require('internal/process/warning').setup();
     NativeModule.require('internal/process/next_tick').setup();
     NativeModule.require('internal/process/stdio').setup();
@@ -377,8 +379,10 @@
       // that threw and was never cleared. So clear it now.
       async_id_fields[kInitTriggerAsyncId] = 0;
 
-      if (process.domain && process.domain._errorHandler)
-        caught = process.domain._errorHandler(er);
+      if (exceptionHandlerState.captureFn !== null) {
+        exceptionHandlerState.captureFn(er);
+        caught = true;
+      }
 
       if (!caught)
         caught = process.emit('uncaughtException', er);

lib/internal/errors.js

@@ -291,6 +291,13 @@ E('ERR_CRYPTO_SIGN_KEY_REQUIRED', 'No key provided to sign');
 E('ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH',
   'Input buffers must have the same length');
 E('ERR_DNS_SET_SERVERS_FAILED', 'c-ares failed to set servers: "%s" [%s]');
+E('ERR_DOMAIN_CALLBACK_NOT_AVAILABLE',
+  'A callback was registered through ' +
+  'process.setUncaughtExceptionCaptureCallback(), which is mutually ' +
+  'exclusive with using the `domain` module');
+E('ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE',
+  'The `domain` module is in use, which is mutually exclusive with calling ' +
+  'process.setUncaughtExceptionCaptureCallback()');
 E('ERR_ENCODING_INVALID_ENCODED_DATA',
   'The encoded data was not valid for encoding %s');
 E('ERR_ENCODING_NOT_SUPPORTED', 'The "%s" encoding is not supported');
@@ -461,6 +468,9 @@ E('ERR_TRANSFORM_ALREADY_TRANSFORMING',
   'Calling transform done when still transforming');
 E('ERR_TRANSFORM_WITH_LENGTH_0',
   'Calling transform done when writableState.length != 0');
+E('ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET',
+  '`process.setupUncaughtExceptionCapture()` was called while a capture ' +
+  'callback was already active');
 E('ERR_UNESCAPED_CHARACTERS', '%s contains unescaped characters');
 E('ERR_UNHANDLED_ERROR',
   (err) => {

lib/internal/process.js

@@ -247,6 +247,34 @@ function setupRawDebug() {
   };
 }
 
+
+function setupUncaughtExceptionCapture(exceptionHandlerState) {
+  // This is a typed array for faster communication with JS.
+  const shouldAbortOnUncaughtToggle = process._shouldAbortOnUncaughtToggle;
+  delete process._shouldAbortOnUncaughtToggle;
+
+  process.setUncaughtExceptionCaptureCallback = function(fn) {
+    if (fn === null) {
+      exceptionHandlerState.captureFn = fn;
+      shouldAbortOnUncaughtToggle[0] = 1;
+      return;
+    }
+    if (typeof fn !== 'function') {
+      throw new errors.TypeError('ERR_INVALID_ARG_TYPE', 'fn',
+                                 ['Function', 'null']);
+    }
+    if (exceptionHandlerState.captureFn !== null) {
+      throw new errors.Error('ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET');
+    }
+    exceptionHandlerState.captureFn = fn;
+    shouldAbortOnUncaughtToggle[0] = 0;
+  };
+
+  process.hasUncaughtExceptionCaptureCallback = function() {
+    return exceptionHandlerState.captureFn !== null;
+  };
+}
+
 module.exports = {
   setup_performance,
   setup_cpuUsage,
@@ -256,5 +284,6 @@ module.exports = {
   setupKillAndExit,
   setupSignalHandlers,
   setupChannel,
-  setupRawDebug
+  setupRawDebug,
+  setupUncaughtExceptionCapture
 };