src: extend --env-file to also accept sections

Author: dario-piotrowicz

doc/api/cli.md

@@ -905,6 +905,29 @@ Export keyword before a key is ignored:
 export USERNAME="nodejs" # will result in `nodejs` as the value.
 ```
 
+Additionally sections can be used to have a more granular control of
+the environment variables within a single file.
+
+Sections can be defined in the file and then targeted by including a hash character
+followed by their name as the flag's argument. Multiple sections can be specified and
+if a variable is defined in multiple sections the latest instance of the variable in
+the file overrides the others.
+
+For example given the following file:
+
+```text
+MY_VAR = 'my top-level variable'
+
+[dev]
+MY_VAR = 'my variable for development'
+
+[prod]
+MY_VAR = 'my variable for production'
+```
+
+`--env-file=config#dev` will make it so that the variable's value being used is
+taken from the `dev` section.
+
 If you want to load environment variables from a file that may not exist, you
 can use the [`--env-file-if-exists`][] flag instead.
 

src/node.cc

@@ -873,7 +873,7 @@ static ExitCode InitializeNodeWithArgsInternal(
     CHECK(!per_process::v8_initialized);
 
     for (const auto& file_data : env_files) {
-      switch (per_process::dotenv_file.ParsePath(file_data.path)) {
+      switch (per_process::dotenv_file.ParsePath(file_data.path, file_data.sections)) {
         case Dotenv::ParseResult::Valid:
           break;
         case Dotenv::ParseResult::InvalidContent:

src/node_dotenv.cc

@@ -26,6 +26,31 @@ std::vector<Dotenv::env_file_data> Dotenv::GetDataFromArgs(
            arg.starts_with("--env-file-if-exists=");
   };
 
+  const auto get_sections = [](const std::string& path) {
+    std::set<std::string> sections = {};
+    std::int8_t start_index = 0;
+
+    while (true) {
+      auto hash_char_index = path.find('#', start_index);
+      if (hash_char_index == std::string::npos) {
+        return sections;
+      }
+      auto next_hash_char_index = path.find('#', hash_char_index + 1);
+      if (next_hash_char_index == std::string::npos) {
+        // We've arrived to the last section
+        auto section = path.substr(hash_char_index + 1);
+        sections.insert(section);
+        return sections;
+      }
+      // There are more sections, so let's save the current one and update the index
+      auto section = path.substr(hash_char_index+1, next_hash_char_index - 1 - hash_char_index);
+      sections.insert(section);
+      start_index = next_hash_char_index;
+    }
+
+    return sections;
+  };
+
   std::vector<Dotenv::env_file_data> 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);
@@ -42,19 +67,35 @@ std::vector<Dotenv::env_file_data> Dotenv::GetDataFromArgs(
       auto flag = matched_arg->substr(0, equal_char_index);
       auto file_path = matched_arg->substr(equal_char_index + 1);
 
+      auto sections = get_sections(file_path);
+
+      auto hash_char_index = file_path.find('#');
+      if (hash_char_index != std::string::npos) {
+        file_path = file_path.substr(0, hash_char_index);
+      }
+
       struct env_file_data env_file_data = {
-          file_path, flag.starts_with(optional_env_file_flag)};
+          file_path, flag.starts_with(optional_env_file_flag), sections};
       env_files.push_back(env_file_data);
     } else {
       // `--env-file path`
-      auto file_path = std::next(matched_arg);
+      auto file_path_ptr = std::next(matched_arg);
 
-      if (file_path == args.end()) {
+      if (file_path_ptr == args.end()) {
         return env_files;
       }
 
+      std::string file_path = file_path_ptr->c_str();
+
+      auto sections = get_sections(file_path);
+
+      auto hash_char_index = file_path.find('#');
+      if (hash_char_index != std::string::npos) {
+        file_path = file_path.substr(0, hash_char_index);
+      }
+
       struct env_file_data env_file_data = {
-          *file_path, matched_arg->starts_with(optional_env_file_flag)};
+          file_path, matched_arg->starts_with(optional_env_file_flag), sections};
       env_files.push_back(env_file_data);
     }
 
@@ -124,9 +165,19 @@ std::string_view trim_spaces(std::string_view input) {
   return input.substr(pos_start, pos_end - pos_start + 1);
 }
 
-void Dotenv::ParseContent(const std::string_view input) {
+void Dotenv::ParseContent(const std::string_view input, const std::set<std::string> sections) {
   std::string lines(input);
 
+  // Variable to track the current section ("" indicates that we're in the global/top-level section)
+  std::string current_section = "";
+
+  // Insert/Assign a value in the store, but only if it's in the global section or in an included section
+  auto maybe_insert_or_assign_to_store = [&](const std::string& key, const std::string_view& value) {
+    if (current_section.empty() || (sections.find(current_section.c_str()) != sections.end())) {
+      store_.insert_or_assign(key, value);
+    }
+  };
+
   // Handle windows newlines "\r\n": remove "\r" and keep only "\n"
   lines.erase(std::remove(lines.begin(), lines.end(), '\r'), lines.end());
 
@@ -154,6 +205,18 @@ void Dotenv::ParseContent(const std::string_view input) {
       continue;
     }
 
+    if (content.front() == '[') {
+        auto closing_bracket_idx = content.find_first_of(']');
+        if (closing_bracket_idx != std::string_view::npos) {
+            if(content.at(closing_bracket_idx + 1) == '\n') {
+              // We've enterer a new section of the file
+              current_section = content.substr(1, closing_bracket_idx - 1);
+              content.remove_prefix(closing_bracket_idx + 1);
+              continue;
+            }
+        }
+    }
+
     // Find the next equals sign or newline in a single pass.
     // This optimizes the search by avoiding multiple iterations.
     auto equal_or_newline = content.find_first_of("=\n");
@@ -176,7 +239,7 @@ void Dotenv::ParseContent(const std::string_view input) {
 
     // If the value is not present (e.g. KEY=) set it to an empty string
     if (content.empty() || content.front() == '\n') {
-      store_.insert_or_assign(std::string(key), "");
+      maybe_insert_or_assign_to_store(std::string(key), "");
       continue;
     }
 
@@ -201,7 +264,7 @@ void Dotenv::ParseContent(const std::string_view input) {
     if (content.empty()) {
       // In case the last line is a single key without value
       // Example: KEY= (without a newline at the EOF)
-      store_.insert_or_assign(std::string(key), "");
+      maybe_insert_or_assign_to_store(std::string(key), "");
       break;
     }
 
@@ -221,7 +284,7 @@ void Dotenv::ParseContent(const std::string_view input) {
           pos += 1;
         }
 
-        store_.insert_or_assign(std::string(key), multi_line_value);
+        maybe_insert_or_assign_to_store(std::string(key), multi_line_value);
         auto newline = content.find('\n', closing_quote + 1);
         if (newline != std::string_view::npos) {
           content.remove_prefix(newline + 1);
@@ -248,18 +311,18 @@ void Dotenv::ParseContent(const std::string_view input) {
         auto newline = content.find('\n');
         if (newline != std::string_view::npos) {
           value = content.substr(0, newline);
-          store_.insert_or_assign(std::string(key), value);
+          maybe_insert_or_assign_to_store(std::string(key), value);
           content.remove_prefix(newline + 1);
         } else {
           // No newline - take rest of content
           value = content;
-          store_.insert_or_assign(std::string(key), value);
+          maybe_insert_or_assign_to_store(std::string(key), value);
           break;
         }
       } else {
         // Found closing quote - take content between quotes
         value = content.substr(1, closing_quote - 1);
-        store_.insert_or_assign(std::string(key), value);
+        maybe_insert_or_assign_to_store(std::string(key), value);
         auto newline = content.find('\n', closing_quote + 1);
         if (newline != std::string_view::npos) {
           // Use +1 to discard the '\n' itself => next line
@@ -285,7 +348,7 @@ void Dotenv::ParseContent(const std::string_view input) {
           value = value.substr(0, hash_character);
         }
         value = trim_spaces(value);
-        store_.insert_or_assign(std::string(key), std::string(value));
+        maybe_insert_or_assign_to_store(std::string(key), std::string(value));
         content.remove_prefix(newline + 1);
       } else {
         // Last line without newline
@@ -294,7 +357,7 @@ void Dotenv::ParseContent(const std::string_view input) {
         if (hash_char != std::string_view::npos) {
           value = content.substr(0, hash_char);
         }
-        store_.insert_or_assign(std::string(key), trim_spaces(value));
+        maybe_insert_or_assign_to_store(std::string(key), trim_spaces(value));
         content = {};
       }
     }
@@ -303,7 +366,7 @@ void Dotenv::ParseContent(const std::string_view input) {
   }
 }
 
-Dotenv::ParseResult Dotenv::ParsePath(const std::string_view path) {
+Dotenv::ParseResult Dotenv::ParsePath(const std::string_view path, const std::set<std::string> sections) {
   uv_fs_t req;
   auto defer_req_cleanup = OnScopeLeave([&req]() { uv_fs_req_cleanup(&req); });
 
@@ -337,7 +400,7 @@ Dotenv::ParseResult Dotenv::ParsePath(const std::string_view path) {
     result.append(buf.base, r);
   }
 
-  ParseContent(result);
+  ParseContent(result, sections);
   return ParseResult::Valid;
 }
 

src/node_dotenv.h

@@ -6,6 +6,7 @@
 #include "util-inl.h"
 #include "v8.h"
 
+#include <set>
 #include <map>
 
 namespace node {
@@ -16,6 +17,7 @@ class Dotenv {
   struct env_file_data {
     std::string path;
     bool is_optional;
+    std::set<std::string> sections;
   };
 
   Dotenv() = default;
@@ -25,8 +27,8 @@ class Dotenv {
   Dotenv& operator=(const Dotenv& d) = delete;
   ~Dotenv() = default;
 
-  void ParseContent(const std::string_view content);
-  ParseResult ParsePath(const std::string_view path);
+  void ParseContent(const std::string_view content, const std::set<std::string> sections);
+  ParseResult ParsePath(const std::string_view path, const std::set<std::string>);
   void AssignNodeOptionsIfAvailable(std::string* node_options) const;
   v8::Maybe<void> SetEnvironment(Environment* env);
   v8::MaybeLocal<v8::Object> ToObject(Environment* env) const;

src/node_process_methods.cc

@@ -604,7 +604,8 @@ static void LoadEnvFile(const v8::FunctionCallbackInfo<v8::Value>& args) {
 
   Dotenv dotenv{};
 
-  switch (dotenv.ParsePath(path)) {
+  // TODO(dario-piotrowicz): update `process.loadEnvFile` to also accept sections
+  switch (dotenv.ParsePath(path, {})) {
     case dotenv.ParseResult::Valid: {
       USE(dotenv.SetEnvironment(env));
       break;

src/node_util.cc

@@ -243,7 +243,8 @@ static void ParseEnv(const FunctionCallbackInfo<Value>& args) {
   CHECK(args[0]->IsString());
   Utf8Value content(env->isolate(), args[0]);
   Dotenv dotenv{};
-  dotenv.ParseContent(content.ToStringView());
+  // TODO(dario-piotrowicz): update `parseEnv` to also accept sections
+  dotenv.ParseContent(content.ToStringView(), {});
   Local<Object> obj;
   if (dotenv.ToObject(env).ToLocal(&obj)) {
     args.GetReturnValue().Set(obj);

test/fixtures/dotenv/sections.env

@@ -0,0 +1,10 @@
+_ENV_TEST_A = 'A (top-level)'
+_ENV_TEST_B = 'B (top-level)'
+
+[dev]
+_ENV_TEST_A = 'A (development)'
+_ENV_TEST_C = 'C (development)'
+
+[prod]
+_ENV_TEST_A = 'A (production)'
+_ENV_TEST_D = 'D (production)'

test/parallel/test-dotenv-sections.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const common = require('../common');
+const assert = require('node:assert');
+const { describe, it } = require('node:test');
+
+const envFilePath = '../fixtures/dotenv/sections.env';
+
+async function getProcessEnvTestEntries(envFileArg) {
+    const code = `
+      console.log(
+        JSON.stringify(
+          Object.fromEntries(Object.entries(process.env).filter(([key]) => key.startsWith('_ENV_TEST_')))
+        )
+      );
+    `.trim();
+    const child = await common.spawnPromisified(
+      process.execPath,
+      [ `--env-file=${envFileArg}`, '--eval', code ],
+      { cwd: __dirname },
+    );
+    assert.strictEqual(child.code, 0);
+    return JSON.parse(child.stdout.replace(/\n/g, ''));
+}
+
+describe('.env sections support', () => {
+  it('should only get the top-level variables if a section is not specified', async () => {
+    const env = await getProcessEnvTestEntries(envFilePath);
+    assert.deepStrictEqual(env, {
+      _ENV_TEST_A: 'A (top-level)',
+      _ENV_TEST_B: 'B (top-level)',
+    });
+  });
+
+  it('should get section specific variables if a section is specified', async () => {
+    const env = await getProcessEnvTestEntries(`${envFilePath}#dev`);
+    assert.strictEqual(env._ENV_TEST_A, 'A (development)');
+    assert.strictEqual(env._ENV_TEST_C, 'C (development)');
+    assert(!('_ENV_TEST_D' in env), 'the _ENV_TEST_D should not be present for the dev section');
+  });
+
+  it('should allow top-level variables to be inherited if not specified in a section', async () => {
+    const env = await getProcessEnvTestEntries(`${envFilePath}#dev`);
+    assert.strictEqual(env._ENV_TEST_B, 'B (top-level)');
+  });
+
+  it('should allow multiple sections to be specified (values are overridden as per the file order)', async () => {
+    const env = await getProcessEnvTestEntries(`${envFilePath}#dev#prod`);
+    assert.deepStrictEqual(env, {
+      _ENV_TEST_A: 'A (production)',
+      _ENV_TEST_B: 'B (top-level)',
+      _ENV_TEST_C: 'C (development)',
+      _ENV_TEST_D: 'D (production)'
+    });
+  });
+});