src: add --optional-env-file flag

Fixes: nodejs#50993
Refs: nodejs#51451

Author: BoscoDomingo

doc/api/cli.md

@@ -818,6 +818,8 @@ in the file, the value from the environment takes precedence.
 You can pass multiple `--env-file` arguments. Subsequent files override
 pre-existing variables defined in previous files.
 
+An error is thrown if the file does not exist.
+
 ```bash
 node --env-file=.env --env-file=.development.env index.js
 ```
@@ -857,6 +859,9 @@ Export keyword before a key is ignored:
 export USERNAME="nodejs" # will result in `nodejs` as the value.
 ```
 
+If you want to load environment variables from a file that does not exist, you
+can use the [`--optional-env-file`](#optional-env-fileconfig) flag instead.
+
 ### `-e`, `--eval "script"`
 
 <!-- YAML
@@ -1692,6 +1697,12 @@ is being linked to Node.js. Sharing the OpenSSL configuration may have unwanted
 implications and it is recommended to use a configuration section specific to
 Node.js which is `nodejs_conf` and is default when this option is not used.
 
+### `--optional-env-file=config`
+
+Behaviour is the same as [`--env-file`](#env-fileconfig), but an error is not thrown if the file
+does not exist.
+
+
 ### `--pending-deprecation`
 
 <!-- YAML

src/node.cc

@@ -832,20 +832,21 @@ static ExitCode InitializeNodeWithArgsInternal(
   HandleEnvOptions(per_process::cli_options->per_isolate->per_env);
 
   std::string node_options;
-  auto file_paths = node::Dotenv::GetPathFromArgs(*argv);
+  auto env_files = node::Dotenv::GetEnvFileDataFromArgs(*argv);
 
-  if (!file_paths.empty()) {
+  if (!env_files.empty()) {
     CHECK(!per_process::v8_initialized);
 
-    for (const auto& file_path : file_paths) {
-      switch (per_process::dotenv_file.ParsePath(file_path)) {
+    for (const auto& file_data : env_files) {
+      switch (per_process::dotenv_file.ParsePath(file_data.path)) {
         case Dotenv::ParseResult::Valid:
           break;
         case Dotenv::ParseResult::InvalidContent:
-          errors->push_back(file_path + ": invalid format");
+          errors->push_back(file_data.path + ": invalid format");
           break;
         case Dotenv::ParseResult::FileError:
-          errors->push_back(file_path + ": not found");
+          if (!file_data.is_required) continue;
+          errors->push_back(file_data.path + ": not found");
           break;
         default:
           UNREACHABLE();

src/node_dotenv.cc

@@ -11,34 +11,51 @@ using v8::NewStringType;
 using v8::Object;
 using v8::String;
 
-std::vector<std::string> Dotenv::GetPathFromArgs(
+std::vector<Dotenv::EnvFileData> Dotenv::GetEnvFileDataFromArgs(
     const std::vector<std::string>& args) {
+  const std::string_view env_file_flag = "--env-file";
+
   const auto find_match = [](const std::string& arg) {
-    const std::string_view flag = "--env-file";
-    return strncmp(arg.c_str(), flag.data(), flag.size()) == 0;
+    const std::string_view env_file_flag = "--env-file";
+    const std::string_view optional_env_file_flag = "--optional-env-file";
+    return strncmp(arg.c_str(), env_file_flag.data(), env_file_flag.size()) == 0 ||
+           strncmp(arg.c_str(),
+                   optional_env_file_flag.data(),
+                   optional_env_file_flag.size()) == 0;
   };
-  std::vector<std::string> paths;
-  auto path = std::find_if(args.begin(), args.end(), find_match);
 
-  while (path != args.end()) {
-    auto equal_char = path->find('=');
+  std::vector<Dotenv::EnvFileData> env_files;
+  // This will be an iterator, pointing to args.end() if no matches are found
+  auto matched_arg = std::find_if(args.begin(), args.end(), find_match);
+
+  while (matched_arg != args.end()) {
+    auto equal_char = matched_arg->find('=');
 
     if (equal_char != std::string::npos) {
-      paths.push_back(path->substr(equal_char + 1));
+      auto flag = matched_arg->substr(0, equal_char);
+      struct EnvFileData env_file_data = {
+        matched_arg->substr(equal_char + 1),
+        strncmp(flag.c_str(), env_file_flag.data(), env_file_flag.size()) == 0
+      };
+      env_files.push_back(env_file_data);
     } else {
-      auto next_path = std::next(path);
+      auto file_path = std::next(matched_arg);
 
-      if (next_path == args.end()) {
-        return paths;
+      if (file_path == args.end()) {
+        return env_files;
       }
 
-      paths.push_back(*next_path);
+      struct EnvFileData env_file_data = {
+        *file_path,
+        strncmp(matched_arg->c_str(), env_file_flag.data(), env_file_flag.size()) == 0
+      };
+      env_files.push_back(env_file_data);
     }
 
-    path = std::find_if(++path, args.end(), find_match);
+    matched_arg = std::find_if(++matched_arg, args.end(), find_match);
   }
 
-  return paths;
+  return env_files;
 }
 
 void Dotenv::SetEnvironment(node::Environment* env) {

src/node_dotenv.h

@@ -13,6 +13,10 @@ namespace node {
 class Dotenv {
  public:
   enum ParseResult { Valid, FileError, InvalidContent };
+  struct EnvFileData {
+    std::string path;
+    bool is_required;
+  };
 
   Dotenv() = default;
   Dotenv(const Dotenv& d) = delete;
@@ -27,7 +31,7 @@ class Dotenv {
   void SetEnvironment(Environment* env);
   v8::Local<v8::Object> ToObject(Environment* env) const;
 
-  static std::vector<std::string> GetPathFromArgs(
+  static std::vector<EnvFileData> GetEnvFileDataFromArgs(
       const std::vector<std::string>& args);
 
  private:

src/node_options.cc

@@ -624,6 +624,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "set environment variables from supplied file",
             &EnvironmentOptions::env_file);
   Implies("--env-file", "[has_env_file_string]");
+  AddOption("--optional-env-file",
+            "set environment variables from supplied file, but won't fail if the file doesn't exist",
+            &EnvironmentOptions::optional_env_file);
+  Implies("--optional-env-file", "[has_env_file_string]");
   AddOption("--test",
             "launch test runner on startup",
             &EnvironmentOptions::test_runner);

src/node_options.h

@@ -170,6 +170,7 @@ class EnvironmentOptions : public Options {
   std::string redirect_warnings;
   std::string diagnostic_dir;
   std::string env_file;
+  std::string optional_env_file;
   bool has_env_file_string = false;
   bool test_runner = false;
   uint64_t test_runner_concurrency = 0;

test/fixtures/dotenv/optional.env

@@ -0,0 +1 @@
+BASIC="OPTIONALLY LOADED"

test/parallel/test-dotenv-edge-cases.js

@@ -8,6 +8,7 @@ const fixtures = require('../common/fixtures');
 
 const validEnvFilePath = '../fixtures/dotenv/valid.env';
 const nodeOptionsEnvFilePath = '../fixtures/dotenv/node-options.env';
+const optionalEnvFilePath = '../fixtures/dotenv/optional.env';
 
 describe('.env supports edge cases', () => {
 
@@ -27,6 +28,22 @@ describe('.env supports edge cases', () => {
     assert.strictEqual(child.code, 0);
   });
 
+  it('supports multiple declarations, including optional ones', async () => {
+    // process.env.BASIC is equal to `OPTIONALLY LOADED` because the third .env file overrides it.
+    const code = `
+      const assert = require('assert');
+      assert.strictEqual(process.env.BASIC, 'OPTIONALLY LOADED');
+      assert.strictEqual(process.env.NODE_NO_WARNINGS, '1');
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ `--env-file=${nodeOptionsEnvFilePath}`, `--optional-env-file=${optionalEnvFilePath}`, '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
   it('supports absolute paths', async () => {
     const code = `
       require('assert').strictEqual(process.env.BASIC, 'basic');
@@ -52,6 +69,19 @@ describe('.env supports edge cases', () => {
     assert.strictEqual(child.code, 9);
   });
 
+  it('should handle non-existent optional .env file', async () => {
+    const code = `
+      require('assert').strictEqual(1, 1)
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ '--optional-env-file=.env', '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.stderr, '');
+    assert.strictEqual(child.code, 0);
+  });
+
   it('should not override existing environment variables but introduce new vars', async () => {
     const code = `
       require('assert').strictEqual(process.env.BASIC, 'existing');