cli: add --use-env-proxy

This does the same as NODE_USE_ENV_PROXY. When both are set, like other options that can be configured from both sides, the CLI flag takes precedence. PR-URL: #59151 Fixes: #59100 Reviewed-By: Ilyas Shabi <ilyasshabi94@gmail.com> Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: joyeecheung

doc/api/cli.md

@@ -2959,6 +2959,21 @@ environment variables.
 
 See `SSL_CERT_DIR` and `SSL_CERT_FILE`.
 
+### `--use-env-proxy`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.1 - Active Development
+
+When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
+environment variables during startup, and tunnels requests over the
+specified proxy.
+
+This is equivalent to setting the [`NODE_USE_ENV_PROXY=1`][] environment variable.
+When both are set, `--use-env-proxy` takes precedence.
+
 ### `--use-largepages=mode`
 
 <!-- YAML
@@ -3458,6 +3473,7 @@ one is included in the list below.
 * `--track-heap-objects`
 * `--unhandled-rejections`
 * `--use-bundled-ca`
+* `--use-env-proxy`
 * `--use-largepages`
 * `--use-openssl-ca`
 * `--use-system-ca`
@@ -3613,8 +3629,8 @@ When enabled, Node.js parses the `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`
 environment variables during startup, and tunnels requests over the
 specified proxy.
 
-This currently only affects requests sent over `fetch()`. Support for other
-built-in `http` and `https` methods is under way.
+This can also be enabled using the [`--use-env-proxy`][] command-line flag.
+When both are set, `--use-env-proxy` takes precedence.
 
 ### `NODE_V8_COVERAGE=dir`
 
@@ -3943,12 +3959,14 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`--print`]: #-p---print-script
 [`--redirect-warnings`]: #--redirect-warningsfile
 [`--require`]: #-r---require-module
+[`--use-env-proxy`]: #--use-env-proxy
 [`AsyncLocalStorage`]: async_context.md#class-asynclocalstorage
 [`Buffer`]: buffer.md#class-buffer
 [`CRYPTO_secure_malloc_init`]: https://www.openssl.org/docs/man3.0/man3/CRYPTO_secure_malloc_init.html
 [`ERR_INVALID_TYPESCRIPT_SYNTAX`]: errors.md#err_invalid_typescript_syntax
 [`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`]: errors.md#err_unsupported_typescript_syntax
 [`NODE_OPTIONS`]: #node_optionsoptions
+[`NODE_USE_ENV_PROXY=1`]: #node_use_env_proxy1
 [`NO_COLOR`]: https://no-color.org
 [`SlowBuffer`]: buffer.md#class-slowbuffer
 [`Web Storage`]: https://developer.mozilla.org/en-US/docs/Web/API/Web_Storage_API

doc/api/errors.md

@@ -2499,7 +2499,7 @@ Failed to proxy a request because the proxy configuration is invalid.
 
 ### `ERR_PROXY_TUNNEL`
 
-Failed to establish proxy tunnel when `NODE_USE_ENV_PROXY` is enabled.
+Failed to establish proxy tunnel when `NODE_USE_ENV_PROXY` or `--use-env-proxy` is enabled.
 
 <a id="ERR_QUIC_APPLICATION_ERROR"></a>
 

doc/api/http.md

@@ -4273,10 +4273,9 @@ added: REPLACEME
 
 > Stability: 1.1 - Active development
 
-When Node.js creates the global agent, it checks the `NODE_USE_ENV_PROXY`
-environment variable. If it is set to `1`, the global agent will be constructed
+When Node.js creates the global agent, if the `NODE_USE_ENV_PROXY` environment variable is
+set to `1` or `--use-env-proxy` is enabled, the global agent will be constructed
 with `proxyEnv: process.env`, enabling proxy support based on the environment variables.
-
 Custom agents can also be created with proxy support by passing a
 `proxyEnv` option when constructing the agent. The value can be `process.env`
 if they just want to inherit the configuration from the environment variables,
@@ -4318,13 +4317,20 @@ Multiple entries should be separated by commas.
 
 ### Example
 
-Starting a Node.js process with proxy support enabled for all requests sent
-through the default global agent:
+To start a Node.js process with proxy support enabled for all requests sent
+through the default global agent, either use the `NODE_USE_ENV_PROXY` environment
+variable:
 
 ```console
 NODE_USE_ENV_PROXY=1 HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node client.js
 ```
 
+Or the `--use-env-proxy` flag.
+
+```console
+HTTP_PROXY=http://proxy.example.com:8080 NO_PROXY=localhost,127.0.0.1 node --use-env-proxy client.js
+```
+
 To create a custom agent with built-in proxy support:
 
 ```cjs

doc/node-config-schema.json

@@ -538,6 +538,9 @@
  "use-bundled-ca": {
  "type": "boolean"
  },
+ "use-env-proxy": {
+ "type": "boolean"
+ },
  "use-largepages": {
  "type": "string"
  },

doc/node.1

@@ -600,6 +600,9 @@ See
 and
 .Ev SSL_CERT_FILE .
 .
+.It Fl -use-env-proxy
+Parse proxy settings from HTTP_PROXY/HTTPS_PROXY/NO_PROXY environment variables and apply the setting in global HTTP/HTTPS clients.
+.
 .It Fl -use-largepages Ns = Ns Ar mode
 Re-map the Node.js static code to large memory pages at startup. If supported on
 the target system, this will cause the Node.js static code to be moved onto 2

lib/_http_agent.js

@@ -54,6 +54,7 @@ const {
  validateString,
 } = require('internal/validators');
 const assert = require('internal/assert');
+const { getOptionValue } = require('internal/options');
 
 const kOnKeylog = Symbol('onkeylog');
 const kRequestOptions = Symbol('requestOptions');
@@ -622,6 +623,7 @@ module.exports = {
  Agent,
  globalAgent: new Agent({
  keepAlive: true, scheduling: 'lifo', timeout: 5000,
- proxyEnv: process.env.NODE_USE_ENV_PROXY ? filterEnvForProxies(process.env) : undefined,
+ // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+ proxyEnv: getOptionValue('--use-env-proxy') ? filterEnvForProxies(process.env) : undefined,
  }),
 };

lib/https.js

@@ -70,6 +70,7 @@ const { URL, urlToHttpOptions, isURL } = require('internal/url');
 const { validateObject } = require('internal/validators');
 const { isIP, isIPv6 } = require('internal/net');
 const assert = require('internal/assert');
+const { getOptionValue } = require('internal/options');
 
 function Server(opts, requestListener) {
  if (!(this instanceof Server)) return new Server(opts, requestListener);
@@ -599,7 +600,8 @@ Agent.prototype._evictSession = function _evictSession(key) {
 
 const globalAgent = new Agent({
  keepAlive: true, scheduling: 'lifo', timeout: 5000,
- proxyEnv: process.env.NODE_USE_ENV_PROXY ? filterEnvForProxies(process.env) : undefined,
+ // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+ proxyEnv: getOptionValue('--use-env-proxy') ? filterEnvForProxies(process.env) : undefined,
 });
 
 /**

lib/internal/process/pre_execution.js

@@ -166,19 +166,24 @@ function prepareExecution(options) {
 }
 
 function setupHttpProxy() {
- if (process.env.NODE_USE_ENV_PROXY &&
- (process.env.HTTP_PROXY || process.env.HTTPS_PROXY ||
- process.env.http_proxy || process.env.https_proxy)) {
- const { setGlobalDispatcher, EnvHttpProxyAgent } = require('internal/deps/undici/undici');
- const envHttpProxyAgent = new EnvHttpProxyAgent();
- setGlobalDispatcher(envHttpProxyAgent);
- // For fetch, we need to set the global dispatcher from here.
- // For http/https agents, we'll configure the global agent when they are
- // actually created, in lib/_http_agent.js and lib/https.js.
- // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY. Investigate whether
- // it's possible to enable it by default without stepping on other existing libraries that
- // sets the global dispatcher or monkey patches the global agent.
+ // This normalized from both --use-env-proxy and NODE_USE_ENV_PROXY settings.
+ if (!getOptionValue('--use-env-proxy')) {
+ return;
+ }
+ if (!process.env.HTTP_PROXY && !process.env.HTTPS_PROXY &&
+ !process.env.http_proxy && !process.env.https_proxy) {
+ return;
  }
+
+ const { setGlobalDispatcher, EnvHttpProxyAgent } = require('internal/deps/undici/undici');
+ const envHttpProxyAgent = new EnvHttpProxyAgent();
+ setGlobalDispatcher(envHttpProxyAgent);
+ // For fetch, we need to set the global dispatcher from here.
+ // For http/https agents, we'll configure the global agent when they are
+ // actually created, in lib/_http_agent.js and lib/https.js.
+ // TODO(joyeecheung): This is currently guarded with NODE_USE_ENV_PROXY and --use-env-proxy.
+ // Investigate whether it's possible to enable it by default without stepping on other
+ // existing libraries that sets the global dispatcher or monkey patches the global agent.
 }
 
 function setupUserModules(forceDefaultLoader = false) {

src/node_options.cc

@@ -660,6 +660,12 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
  "emit pending deprecation warnings",
  &EnvironmentOptions::pending_deprecation,
  kAllowedInEnvvar);
+ AddOption("--use-env-proxy",
+ "parse proxy settings from HTTP_PROXY/HTTPS_PROXY/NO_PROXY"
+ "environment variables and apply the setting in global HTTP/HTTPS "
+ "clients",
+ &EnvironmentOptions::use_env_proxy,
+ kAllowedInEnvvar);
  AddOption("--preserve-symlinks",
  "preserve symbolic links when resolving",
  &EnvironmentOptions::preserve_symlinks,
@@ -1875,6 +1881,8 @@ void HandleEnvOptions(std::shared_ptr<EnvironmentOptions> env_options,
  env_options->preserve_symlinks_main =
  opt_getter("NODE_PRESERVE_SYMLINKS_MAIN") == "1";
 
+ env_options->use_env_proxy = opt_getter("NODE_USE_ENV_PROXY") == "1";
+
  if (env_options->redirect_warnings.empty())
  env_options->redirect_warnings = opt_getter("NODE_REDIRECT_WARNINGS");
 }

src/node_options.h

@@ -241,6 +241,7 @@ class EnvironmentOptions : public Options {
  bool force_repl = false;
 
  bool insecure_http_parser = false;
+ bool use_env_proxy = false;
 
  bool tls_min_v1_0 = false;
  bool tls_min_v1_1 = false;