[v10.x] backport #26599 (process: add --unhandled-rejections flag)

doc/api/cli.md

@@ -401,6 +401,23 @@ added: v2.4.0
 
 Track heap object allocations for heap snapshots.
 
+### `--unhandled-rejections=mode`
+<!-- YAML
+added: REPLACEME
+-->
+
+By default all unhandled rejections trigger a warning plus a deprecation warning
+for the very first unhandled rejection in case no [`unhandledRejection`][] hook
+is used.
+
+Using this flag allows to change what should happen when an unhandled rejection
+occurs. One of three modes can be chosen:
+
+* `strict`: Raise the unhandled rejection as an uncaught exception.
+* `warn`: Always trigger a warning, no matter if the [`unhandledRejection`][]
+  hook is set or not but do not print the deprecation warning.
+* `none`: Silence all warnings.
+
 ### `--use-bundled-ca`, `--use-openssl-ca`
 <!-- YAML
 added: v6.11.0
@@ -614,6 +631,7 @@ Node.js options that are allowed are:
 - `--trace-sync-io`
 - `--trace-warnings`
 - `--track-heap-objects`
+- `--unhandled-rejections`
 - `--use-bundled-ca`
 - `--use-openssl-ca`
 - `--v8-pool-size`
@@ -773,6 +791,7 @@ greater than `4` (its current default value). For more information, see the
 [`Buffer`]: buffer.html#buffer_class_buffer
 [`SlowBuffer`]: buffer.html#buffer_class_slowbuffer
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
+[`unhandledRejection`]: process.html#process_event_unhandledrejection
 [Chrome DevTools Protocol]: https://chromedevtools.github.io/devtools-protocol/
 [REPL]: repl.html
 [ScriptCoverage]: https://chromedevtools.github.io/devtools-protocol/tot/Profiler#type-ScriptCoverage

doc/api/process.md

@@ -200,8 +200,17 @@ most convenient for scripts).
 ### Event: 'uncaughtException'
 <!-- YAML
 added: v0.1.18
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/26599
+    description: Added the `origin` argument.
 -->
 
+* `err` {Error} The uncaught exception.
+* `origin` {string} Indicates if the exception originates from an unhandled
+  rejection or from synchronous errors. Can either be `'uncaughtException'` or
+  `'unhandledRejection'`.
+
 The `'uncaughtException'` event is emitted when an uncaught JavaScript
 exception bubbles all the way back to the event loop. By default, Node.js
 handles such exceptions by printing the stack trace to `stderr` and exiting
@@ -212,12 +221,13 @@ behavior. Alternatively, change the [`process.exitCode`][] in the
 provided exit code. Otherwise, in the presence of such handler the process will
 exit with 0.
 
-The listener function is called with the `Error` object passed as the only
-argument.
-
 ```js
-process.on('uncaughtException', (err) => {
-  fs.writeSync(1, `Caught exception: ${err}\n`);
+process.on('uncaughtException', (err, origin) => {
+  fs.writeSync(
+    process.stderr.fd,
+    `Caught exception: ${err}\n` +
+    `Exception origin: ${origin}`
+  );
 });
 
 setTimeout(() => {
@@ -269,6 +279,10 @@ changes:
                  a process warning.
 -->
 
+* `reason` {Error|any} The object with which the promise was rejected
+  (typically an [`Error`][] object).
+* `promise` {Promise} The rejected promise.
+
 The `'unhandledRejection'` event is emitted whenever a `Promise` is rejected and
 no error handler is attached to the promise within a turn of the event loop.
 When programming with Promises, exceptions are encapsulated as "rejected
@@ -277,16 +291,10 @@ are propagated through a `Promise` chain. The `'unhandledRejection'` event is
 useful for detecting and keeping track of promises that were rejected whose
 rejections have not yet been handled.
 
-The listener function is called with the following arguments:
-
-* `reason` {Error|any} The object with which the promise was rejected
-  (typically an [`Error`][] object).
-* `p` the `Promise` that was rejected.
-
 ```js
-process.on('unhandledRejection', (reason, p) => {
-  console.log('Unhandled Rejection at:', p, 'reason:', reason);
-  // application specific logging, throwing an error, or other logic here
+process.on('unhandledRejection', (reason, promise) => {
+  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
+  // Application specific logging, throwing an error, or other logic here
 });
 
 somePromise.then((res) => {
@@ -312,7 +320,7 @@ as would typically be the case for other `'unhandledRejection'` events. To
 address such failures, a non-operational
 [`.catch(() => { })`][`promise.catch()`] handler may be attached to
 `resource.loaded`, which would prevent the `'unhandledRejection'` event from
-being emitted. Alternatively, the [`'rejectionHandled'`][] event may be used.
+being emitted.
 
 ### Event: 'warning'
 <!-- YAML
@@ -2134,7 +2142,6 @@ cases:
 
 [`'exit'`]: #process_event_exit
 [`'message'`]: child_process.html#child_process_event_message
-[`'rejectionHandled'`]: #process_event_rejectionhandled
 [`'uncaughtException'`]: #process_event_uncaughtexception
 [`ChildProcess.disconnect()`]: child_process.html#child_process_subprocess_disconnect
 [`ChildProcess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback

doc/node.1

@@ -218,6 +218,9 @@ Print stack traces for process warnings (including deprecations).
 .It Fl -track-heap-objects
 Track heap object allocations for heap snapshots.
 .
+.It Fl --unhandled-rejections=mode
+Define the behavior for unhandled rejections. Can be one of `strict` (raise an error), `warn` (enforce warnings) or `none` (silence warnings).
+.
 .It Fl -use-bundled-ca , Fl -use-openssl-ca
 Use bundled Mozilla CA store as supplied by current Node.js version or use OpenSSL's default CA store.
 The default store is selectable at build-time.

lib/internal/bootstrap/node.js

@@ -486,14 +486,15 @@
       emitAfter
     } = NativeModule.require('internal/async_hooks');
 
-    process._fatalException = (er) => {
+    process._fatalException = (er, fromPromise) => {
       // It's possible that defaultTriggerAsyncId was set for a constructor
       // call that threw and was never cleared. So clear it now.
       clearDefaultTriggerAsyncId();
 
+      const type = fromPromise ? 'unhandledRejection' : 'uncaughtException';
       if (exceptionHandlerState.captureFn !== null) {
         exceptionHandlerState.captureFn(er);
-      } else if (!process.emit('uncaughtException', er)) {
+      } else if (!process.emit('uncaughtException', er, type)) {
         // If someone handled it, then great.  otherwise, die in C++ land
         // since that means that we'll exit the process, emit the 'exit' event.
         try {

lib/internal/process/promises.js

@@ -11,11 +11,24 @@ let lastPromiseId = 0;
 exports.setup = setupPromises;
 
 function setupPromises(_setupPromises) {
-  _setupPromises(handler, promiseRejectEvents);
+  _setupPromises(promiseRejectHandler, promiseRejectEvents);
   return emitPromiseRejectionWarnings;
 }
 
-function handler(type, promise, reason) {
+const states = {
+  none: 0,
+  warn: 1,
+  strict: 2,
+  default: 3
+};
+
+let state;
+
+function promiseRejectHandler(type, promise, reason) {
+  if (state === undefined) {
+    const { getOptionValue } = require('internal/options');
+    state = states[getOptionValue('--unhandled-rejections') || 'default'];
+  }
   switch (type) {
     case promiseRejectEvents.kPromiseRejectWithNoHandler:
       return unhandledRejection(promise, reason);
@@ -42,6 +55,7 @@ function unhandledRejection(promise, reason) {
     uid: ++lastPromiseId,
     warned: false
   });
+  // This causes the promise to be referenced at least for one tick.
   pendingUnhandledRejections.push(promise);
   return true;
 }
@@ -67,14 +81,16 @@ function handledRejection(promise) {
 
 const unhandledRejectionErrName = 'UnhandledPromiseRejectionWarning';
 function emitWarning(uid, reason) {
-  // eslint-disable-next-line no-restricted-syntax
-  const warning = new Error(
+  if (state === states.none) {
+    return;
+  }
+  const warning = getError(
+    unhandledRejectionErrName,
     'Unhandled promise rejection. This error originated either by ' +
-    'throwing inside of an async function without a catch block, ' +
-    'or by rejecting a promise which was not handled with .catch(). ' +
-    `(rejection id: ${uid})`
+      'throwing inside of an async function without a catch block, ' +
+      'or by rejecting a promise which was not handled with .catch(). ' +
+      `(rejection id: ${uid})`
   );
-  warning.name = unhandledRejectionErrName;
   try {
     if (reason instanceof Error) {
       warning.stack = reason.stack;
@@ -90,7 +106,7 @@ function emitWarning(uid, reason) {
 
 let deprecationWarned = false;
 function emitDeprecationWarning() {
-  if (!deprecationWarned) {
+  if (state === states.default && !deprecationWarned) {
     deprecationWarned = true;
     process.emitWarning(
       'Unhandled promise rejections are deprecated. In the future, ' +
@@ -113,14 +129,56 @@ function emitPromiseRejectionWarnings() {
   while (len--) {
     const promise = pendingUnhandledRejections.shift();
     const promiseInfo = maybeUnhandledPromises.get(promise);
-    if (promiseInfo !== undefined) {
-      promiseInfo.warned = true;
-      const { reason, uid } = promiseInfo;
-      if (!process.emit('unhandledRejection', reason, promise)) {
-        emitWarning(uid, reason);
-      }
-      maybeScheduledTicks = true;
+    if (promiseInfo === undefined) {
+      continue;
+    }
+    promiseInfo.warned = true;
+    const { reason, uid } = promiseInfo;
+    if (state === states.strict) {
+      fatalException(reason);
     }
+    if (!process.emit('unhandledRejection', reason, promise) ||
+        // Always warn in case the user requested it.
+        state === states.warn) {
+      emitWarning(uid, reason);
+    }
+    maybeScheduledTicks = true;
   }
   return maybeScheduledTicks || pendingUnhandledRejections.length !== 0;
 }
+
+function getError(name, message) {
+  // Reset the stack to prevent any overhead.
+  const tmp = Error.stackTraceLimit;
+  Error.stackTraceLimit = 0;
+  // eslint-disable-next-line no-restricted-syntax
+  const err = new Error(message);
+  Error.stackTraceLimit = tmp;
+  Object.defineProperty(err, 'name', {
+    value: name,
+    enumerable: false,
+    writable: true,
+    configurable: true,
+  });
+  return err;
+}
+
+function fatalException(reason) {
+  let err;
+  if (reason instanceof Error) {
+    err = reason;
+  } else {
+    err = getError(
+      'UnhandledPromiseRejection',
+      'This error originated either by ' +
+        'throwing inside of an async function without a catch block, ' +
+        'or by rejecting a promise which was not handled with .catch().' +
+        ` The promise rejected with the reason "${safeToString(reason)}".`
+    );
+    err.code = 'ERR_UNHANDLED_REJECTION';
+  }
+
+  if (!process._fatalException(err, true /* fromPromise */)) {
+    throw err;
+  }
+}

lib/internal/worker.js

@@ -479,33 +479,35 @@ function setupChild(evalScript) {
   originalFatalException = process._fatalException;
   process._fatalException = fatalException;
 
-  function fatalException(error) {
+  function fatalException(error, fromPromise) {
     debug(`[${threadId}] gets fatal exception`);
     let caught = false;
     try {
-      caught = originalFatalException.call(this, error);
+      caught = originalFatalException.call(this, error, fromPromise);
     } catch (e) {
       error = e;
     }
     debug(`[${threadId}] fatal exception caught = ${caught}`);
 
-    if (!caught) {
-      let serialized;
-      try {
-        serialized = serializeError(error);
-      } catch {}
-      debug(`[${threadId}] fatal exception serialized = ${!!serialized}`);
-      if (serialized)
-        port.postMessage({
-          type: messageTypes.ERROR_MESSAGE,
-          error: serialized
-        });
-      else
-        port.postMessage({ type: messageTypes.COULD_NOT_SERIALIZE_ERROR });
-      clearAsyncIdStack();
-
-      process.exit();
+    if (caught) {
+      return true;
     }
+
+    let serialized;
+    try {
+      serialized = serializeError(error);
+    } catch {}
+    debug(`[${threadId}] fatal exception serialized = ${!!serialized}`);
+    if (serialized)
+      port.postMessage({
+        type: messageTypes.ERROR_MESSAGE,
+        error: serialized
+      });
+    else
+      port.postMessage({ type: messageTypes.COULD_NOT_SERIALIZE_ERROR });
+    clearAsyncIdStack();
+
+    process.exit();
   }
 }
 

src/node.cc

@@ -1370,7 +1370,8 @@ FatalTryCatch::~FatalTryCatch() {
 
 void FatalException(Isolate* isolate,
                     Local<Value> error,
-                    Local<Message> message) {
+                    Local<Message> message,
+                    bool from_promise) {
   HandleScope scope(isolate);
 
   Environment* env = Environment::GetCurrent(isolate);
@@ -1391,9 +1392,12 @@ void FatalException(Isolate* isolate,
     // Do not call FatalException when _fatalException handler throws
     fatal_try_catch.SetVerbose(false);
 
+    Local<Value> argv[2] = { error,
+                             Boolean::New(env->isolate(), from_promise) };
+
     // This will return true if the JS layer handled it, false otherwise
     MaybeLocal<Value> caught = fatal_exception_function.As<Function>()->Call(
-        env->context(), process_object, 1, &error);
+        env->context(), process_object, arraysize(argv), argv);
 
     if (fatal_try_catch.HasTerminated())
       return;
@@ -1418,6 +1422,11 @@ void FatalException(Isolate* isolate,
   }
 }
 
+void FatalException(Isolate* isolate,
+                    Local<Value> error,
+                    Local<Message> message) {
+  FatalException(isolate, error, message, false /* from_promise */);
+}
 
 void FatalException(Isolate* isolate, const TryCatch& try_catch) {
   // If we try to print out a termination exception, we'd just get 'null',