process: add --unhandled-rejections flag

This adds a flag to define the default behavior for unhandled
rejections. Three modes exist: `none`, `warn` and `strict`. The first
is going to silence all unhandled rejection warnings. The second
behaves identical to the current default with the excetion that no
deprecation warning will be printed and the last is going to throw
an error for each unhandled rejection, just as regular exceptions do.
It is possible to intercept those with the `uncaughtException` hook
as with all other exceptions as well.

This PR has no influence on the existing `unhandledRejection` hook.
If that is used, it will continue to function as before.

PR-URL: #26599
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Matheus Marchini <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>
Reviewed-By: Сковорода Никита Андреевич <[email protected]>
Reviewed-By: Sakthipriyan Vairamani <[email protected]>

Author: BridgeAR

doc/api/cli.md

@@ -577,6 +577,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
@@ -798,6 +815,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`
@@ -966,6 +984,7 @@ greater than `4` (its current default value). For more information, see the
 [`process.setUncaughtExceptionCaptureCallback()`]: process.html#process_process_setuncaughtexceptioncapturecallback_fn
 [`tls.DEFAULT_MAX_VERSION`]: tls.html#tls_tls_default_max_version
 [`tls.DEFAULT_MIN_VERSION`]: tls.html#tls_tls_default_min_version
+[`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

@@ -205,8 +205,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
@@ -217,12 +226,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(() => {
@@ -274,6 +284,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
@@ -282,15 +296,9 @@ 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);
+process.on('unhandledRejection', (reason, promise) => {
+  console.log('Unhandled Rejection at:', promise, 'reason:', reason);
   // Application specific logging, throwing an error, or other logic here
 });
 
@@ -317,7 +325,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
@@ -2282,7 +2290,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

@@ -292,6 +292,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/main/worker_thread.js

@@ -137,11 +137,11 @@ port.on('message', (message) => {
 });
 
 // Overwrite fatalException
-process._fatalException = (error) => {
+process._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;
   }

lib/internal/modules/cjs/loader.js

@@ -821,7 +821,10 @@ Module.runMain = function() {
       return loader.import(pathToFileURL(process.argv[1]).pathname);
     })
     .catch((e) => {
-      internalBinding('task_queue').triggerFatalException(e);
+      internalBinding('task_queue').triggerFatalException(
+        e,
+        true /* fromPromise */
+      );
     });
     // Handle any nextTicks added in the first tick of the program
     process._tickCallback();

lib/internal/process/execution.js

@@ -117,7 +117,7 @@ function noop() {}
 // before calling into process._fatalException, or this function should
 // take extra care of the async hooks before it schedules a setImmediate.
 function createFatalException() {
-  return (er) => {
+  return (er, fromPromise) => {
     // It's possible that defaultTriggerAsyncId was set for a constructor
     // call that threw and was never cleared. So clear it now.
     clearDefaultTriggerAsyncId();
@@ -138,9 +138,10 @@ function createFatalException() {
       } catch {}  // Ignore the exception. Diagnostic reporting is unavailable.
     }
 
+    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

@@ -1,6 +1,10 @@
 'use strict';
 
-const { safeToString } = internalBinding('util');
+const { Object } = primordials;
+
+const {
+  safeToString
+} = internalBinding('util');
 const {
   tickInfo,
   promiseRejectEvents: {
@@ -9,7 +13,8 @@ const {
     kPromiseResolveAfterResolved,
     kPromiseRejectAfterResolved
   },
-  setPromiseRejectCallback
+  setPromiseRejectCallback,
+  triggerFatalException
 } = internalBinding('task_queue');
 
 // *Must* match Environment::TickInfo::Fields in src/env.h.
@@ -20,6 +25,15 @@ const pendingUnhandledRejections = [];
 const asyncHandledRejections = [];
 let lastPromiseId = 0;
 
+const states = {
+  none: 0,
+  warn: 1,
+  strict: 2,
+  default: 3
+};
+
+let state;
+
 function setHasRejectionToWarn(value) {
   tickInfo[kHasRejectionToWarn] = value ? 1 : 0;
 }
@@ -29,6 +43,10 @@ function hasRejectionToWarn() {
 }
 
 function promiseRejectHandler(type, promise, reason) {
+  if (state === undefined) {
+    const { getOptionValue } = require('internal/options');
+    state = states[getOptionValue('--unhandled-rejections') || 'default'];
+  }
   switch (type) {
     case kPromiseRejectWithNoHandler:
       unhandledRejection(promise, reason);
@@ -59,6 +77,7 @@ function unhandledRejection(promise, reason) {
     uid: ++lastPromiseId,
     warned: false
   });
+  // This causes the promise to be referenced at least for one tick.
   pendingUnhandledRejections.push(promise);
   setHasRejectionToWarn(true);
 }
@@ -85,14 +104,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;
@@ -108,7 +129,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, ' +
@@ -133,18 +154,57 @@ function processPromiseRejections() {
   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';
+  }
+  triggerFatalException(err, true /* fromPromise */);
+}
+
 function listenForRejections() {
   setPromiseRejectCallback(promiseRejectHandler);
 }

lib/internal/process/task_queues.js

@@ -155,11 +155,11 @@ function runMicrotask() {
     try {
       callback();
     } catch (error) {
-      // TODO(devsnek) remove this if
+      // TODO(devsnek): Remove this if
       // https://bugs.chromium.org/p/v8/issues/detail?id=8326
       // is resolved such that V8 triggers the fatal exception
-      // handler for microtasks
-      triggerFatalException(error);
+      // handler for microtasks.
+      triggerFatalException(error, false /* fromPromise */);
     } finally {
       this.emitDestroy();
     }

src/node_errors.cc

@@ -10,6 +10,7 @@
 namespace node {
 
 using errors::TryCatchScope;
+using v8::Boolean;
 using v8::Context;
 using v8::Exception;
 using v8::Function;
@@ -771,7 +772,8 @@ void DecorateErrorStack(Environment* env,
 
 void FatalException(Isolate* isolate,
                     Local<Value> error,
-                    Local<Message> message) {
+                    Local<Message> message,
+                    bool from_promise) {
   CHECK(!error.IsEmpty());
   HandleScope scope(isolate);
 
@@ -794,9 +796,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;
 
@@ -821,4 +826,10 @@ void FatalException(Isolate* isolate,
   }
 }
 
+void FatalException(Isolate* isolate,
+                    Local<Value> error,
+                    Local<Message> message) {
+  FatalException(isolate, error, message, false /* from_promise */);
+}
+
 }  // namespace node