src: add option to disable loading native addons

PR-URL: https://github.com/nodejs/node/pull/39977
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Guy Bedford <guybedford@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>

3 files changed, 35 insertions, 4 deletions

diff --git a/doc/api/cli.md b/doc/api/cli.md
index f87b2476e0f..3ab4750d8d6 100644
--- a/doc/api/cli.md
+++ b/doc/api/cli.md
@@ -598,6 +598,15 @@ added: v7.10.0
 
 This option is a no-op. It is kept for compatibility.
 
+### `--no-addons`
+<!-- YAML
+added: REPLACEME
+-->
+
+Disable the `node-addons` exports condition as well as disable loading
+native addons. When `--no-addons` is specified, calling `process.dlopen` or
+requiring a native C++ addon will fail and throw an exception.
+
 ### `--no-deprecation`
 <!-- YAML
 added: v0.8.0
@@ -1428,6 +1437,7 @@ Node.js options that are allowed are:
 * `--inspect`
 * `--max-http-header-size`
 * `--napi-modules`
+* `--no-addons`
 * `--no-deprecation`
 * `--no-experimental-repl-await`
 * `--no-extra-info-on-fatal-exception`
diff --git a/doc/api/errors.md b/doc/api/errors.md
index adef81caa6d..a03b1f6fc25 100644
--- a/doc/api/errors.md
+++ b/doc/api/errors.md
@@ -1027,6 +1027,14 @@ added:
 
 The [debugger][] timed out waiting for the required host/port to be free.
 
+<a id="ERR_DLOPEN_DISABLED"></a>
+### `ERR_DLOPEN_DISABLED`
+<!-- YAML
+added: REPLACEME
+-->
+
+Loading native addons has been disabled using [`--no-addons`][].
+
 <a id="ERR_DLOPEN_FAILED"></a>
 ### `ERR_DLOPEN_FAILED`
 <!-- YAML
@@ -2879,6 +2887,7 @@ The native call from `process.cpuUsage` could not be processed.
 [`'uncaughtException'`]: process.md#event-uncaughtexception
 [`--disable-proto=throw`]: cli.md#--disable-protomode
 [`--force-fips`]: cli.md#--force-fips
+[`--no-addons`]: cli.md#--no-addons
 [`Class: assert.AssertionError`]: assert.md#class-assertassertionerror
 [`ERR_INVALID_ARG_TYPE`]: #err_invalid_arg_type
 [`ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST`]: #err_missing_message_port_in_transfer_list
diff --git a/doc/api/packages.md b/doc/api/packages.md
index 5268772de15..4aee6b77ecb 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -537,6 +537,11 @@ Node.js implements the following conditions:
 * `"node"` - matches for any Node.js environment. Can be a CommonJS or ES
    module file. _This condition should always come after `"import"` or
    `"require"`._
+* `"node-addons"` - similar to `"node"` and matches for any Node.js environment.
+   This condition can be used to provide an entry point which uses native C++
+   addons as opposed to an entry point which is more universal and doesn't rely
+   on native addons. This condition can be disabled via the
+   [`--no-addons` flag][].
 * `"default"` - the generic fallback that always matches. Can be a CommonJS
    or ES module file. _This condition should always come last._
 
@@ -615,17 +620,23 @@ node --conditions=development main.js
 ```
 
 which would then resolve the `"development"` condition in package imports and
-exports, while resolving the existing `"node"`, `"default"`, `"import"`, and
-`"require"` conditions as appropriate.
+exports, while resolving the existing `"node"`, `"node-addons"`, `"default"`,
+`"import"`, and `"require"` conditions as appropriate.
 
 Any number of custom conditions can be set with repeat flags.
 
 ### Conditions Definitions
 
-The `"import"`, `"require"`, `"node"` and `"default"` conditions are defined
-and implemented in Node.js core,
+The `"import"`, `"require"`, `"node"`, `"node-addons"` and `"default"`
+conditions are defined and implemented in Node.js core,
 [as specified above](#conditional-exports).
 
+The `"node-addons"` condition can be used to provide an entry point which
+uses native C++ addons. However, this condition can be disabled via the
+[`--no-addons` flag][]. When using `"node-addons"`, it's recommended to treat
+`"default"` as an enhancement that provides a more universal entry point, e.g.
+using WebAssembly instead of a native addon.
+
 Other condition strings are unknown to Node.js and thus ignored by default.
 Runtimes or tools other than Node.js can use them at their discretion.
 
@@ -1249,6 +1260,7 @@ This field defines [subpath imports][] for the current package.
 [`"packageManager"`]: #packagemanager
 [`"type"`]: #type
 [`--conditions` flag]: #resolving-user-conditions
+[`--no-addons` flag]: cli.md#--no-addons
 [`ERR_PACKAGE_PATH_NOT_EXPORTED`]: errors.md#err_package_path_not_exported
 [`esm`]: https://github.com/standard-things/esm#readme
 [`package.json`]: #nodejs-packagejson-field-definitions