sea: support execArgv in sea config

The `execArgv` field can be used to specify Node.js-specific
arguments that will be automatically applied when the single
executable application starts. This allows application developers
to configure Node.js runtime options without requiring end users
to be aware of these flags.

Author: joyeecheung

doc/api/single-executable-applications.md

@@ -179,6 +179,7 @@ The configuration currently reads the following top-level fields:
   "disableExperimentalSEAWarning": true, // Default: false
   "useSnapshot": false,  // Default: false
   "useCodeCache": true, // Default: false
+  "execArgv": ["--no-warnings", "--max-old-space-size=4096"], // Optional
   "assets": {  // Optional
     "a.dat": "/path/to/a.dat",
     "b.txt": "/path/to/b.txt"
@@ -276,6 +277,43 @@ execute the script, which would improve the startup performance.
 
 **Note:** `import()` does not work when `useCodeCache` is `true`.
 
+### Execution arguments
+
+The `execArgv` field can be used to specify Node.js-specific
+arguments that will be automatically applied when the single
+executable application starts. This allows application developers
+to configure Node.js runtime options without requiring end users
+to be aware of these flags.
+
+For example, the following configuration:
+
+```json
+{
+  "main": "/path/to/bundled/script.js",
+  "output": "/path/to/write/the/generated/blob.blob",
+  "execArgv": ["--no-warnings", "--max-old-space-size=2048"]
+}
+```
+
+will instruct the SEA to be launched with the `--no-warnings` and
+`--max-old-space-size=2048` flags. In the scripts embedded in the executable, these flags
+can be accessed using the `process.execArgv` property:
+
+```js
+// If the executable is launched with `sea user-arg1 user-arg2`
+console.log(process.execArgv);
+// Prints: ['--no-warnings', '--max-old-space-size=2048']
+console.log(process.argv);
+// Prints ['/path/to/sea', 'path/to/sea', 'user-arg1', 'user-arg2']
+```
+
+The user-provided arguments are in the `process.argv` array starting from index 2,
+similar to what would happen if the application is started with:
+
+```console
+node --no-warnings --max-old-space-size=2048 /path/to/bundled/script.js user-arg1 user-arg2
+```
+
 ## In the injected main script
 
 ### Single-executable application API

src/json_parser.cc

@@ -154,4 +154,46 @@ std::optional<JSONParser::StringDict> JSONParser::GetTopLevelStringDict(
   return result;
 }
 
+std::optional<std::vector<std::string>> JSONParser::GetTopLevelStringList(
+    std::string_view field) {
+  Isolate* isolate = isolate_.get();
+  v8::Locker locker(isolate);
+  v8::Isolate::Scope isolate_scope(isolate);
+  v8::HandleScope handle_scope(isolate);
+  Local<Context> context = context_.Get(isolate);
+  Context::Scope context_scope(context);
+  Local<Object> content_object = content_.Get(isolate);
+  Local<Value> value;
+  bool has_field;
+  // It's not a real script, so don't print the source line.
+  errors::PrinterTryCatch bootstrapCatch(
+      isolate, errors::PrinterTryCatch::kDontPrintSourceLine);
+  Local<Value> field_local;
+  if (!ToV8Value(context, field, isolate).ToLocal(&field_local)) {
+    return std::nullopt;
+  }
+  if (!content_object->Has(context, field_local).To(&has_field)) {
+    return std::nullopt;
+  }
+  if (!has_field) {
+    return std::vector<std::string>();
+  }
+  if (!content_object->Get(context, field_local).ToLocal(&value) ||
+      !value->IsArray()) {
+    return std::nullopt;
+  }
+  Local<Array> array = value.As<Array>();
+  std::vector<std::string> result;
+  uint32_t length = array->Length();
+  for (uint32_t i = 0; i < length; ++i) {
+    Local<Value> element;
+    if (!array->Get(context, i).ToLocal(&element) || !element->IsString()) {
+      return std::nullopt;
+    }
+    Utf8Value element_utf8(isolate, element);
+    result.emplace_back(element_utf8.ToString());
+  }
+  return result;
+}
+
 }  // namespace node

src/json_parser.h

@@ -7,6 +7,7 @@
 #include <optional>
 #include <string>
 #include <unordered_map>
+#include <vector>
 #include "util.h"
 #include "v8.h"
 
@@ -23,6 +24,8 @@ class JSONParser {
   std::optional<std::string> GetTopLevelStringField(std::string_view field);
   std::optional<bool> GetTopLevelBoolField(std::string_view field);
   std::optional<StringDict> GetTopLevelStringDict(std::string_view field);
+  std::optional<std::vector<std::string>> GetTopLevelStringList(
+      std::string_view field);
 
  private:
   // We might want a lighter-weight JSON parser for this use case. But for now

src/node_sea.cc

@@ -123,6 +123,18 @@ size_t SeaSerializer::Write(const SeaResource& sea) {
       written_total += WriteStringView(content, StringLogMode::kAddressOnly);
     }
   }
+
+  if (static_cast<bool>(sea.flags & SeaFlags::kIncludeExecArgv)) {
+    Debug("Write SEA resource exec argv size %zu\n", sea.exec_argv.size());
+    written_total += WriteArithmetic<size_t>(sea.exec_argv.size());
+    for (const auto& arg : sea.exec_argv) {
+      Debug("Write SEA resource exec arg %s at %p, size=%zu\n",
+            arg.data(),
+            arg.data(),
+            arg.size());
+      written_total += WriteStringView(arg, StringLogMode::kAddressAndContent);
+    }
+  }
   return written_total;
 }
 
@@ -185,7 +197,22 @@ SeaResource SeaDeserializer::Read() {
       assets.emplace(key, content);
     }
   }
-  return {flags, code_path, code, code_cache, assets};
+
+  std::vector<std::string_view> exec_argv;
+  if (static_cast<bool>(flags & SeaFlags::kIncludeExecArgv)) {
+    size_t exec_argv_size = ReadArithmetic<size_t>();
+    Debug("Read SEA resource exec args size %zu\n", exec_argv_size);
+    exec_argv.reserve(exec_argv_size);
+    for (size_t i = 0; i < exec_argv_size; ++i) {
+      std::string_view arg = ReadStringView(StringLogMode::kAddressAndContent);
+      Debug("Read SEA resource exec arg %s at %p, size=%zu\n",
+            arg.data(),
+            arg.data(),
+            arg.size());
+      exec_argv.emplace_back(arg);
+    }
+  }
+  return {flags, code_path, code, code_cache, assets, exec_argv};
 }
 
 std::string_view FindSingleExecutableBlob() {
@@ -269,8 +296,27 @@ std::tuple<int, char**> FixupArgsForSEA(int argc, char** argv) {
   // entry point file path.
   if (IsSingleExecutable()) {
     static std::vector<char*> new_argv;
-    new_argv.reserve(argc + 2);
+    static std::vector<std::string> exec_argv_storage;
+
+    SeaResource sea_resource = FindSingleExecutableResource();
+
+    new_argv.clear();
+    exec_argv_storage.clear();
+
+    // Reserve space for argv[0], exec argv, original argv, and nullptr
+    new_argv.reserve(argc + sea_resource.exec_argv.size() + 2);
     new_argv.emplace_back(argv[0]);
+
+    // Insert exec argv from SEA config
+    if (!sea_resource.exec_argv.empty()) {
+      exec_argv_storage.reserve(sea_resource.exec_argv.size());
+      for (const auto& arg : sea_resource.exec_argv) {
+        exec_argv_storage.emplace_back(arg);
+        new_argv.emplace_back(exec_argv_storage.back().data());
+      }
+    }
+
+    // Add actual run time arguments.
     new_argv.insert(new_argv.end(), argv, argv + argc);
     new_argv.emplace_back(nullptr);
     argc = new_argv.size() - 1;
@@ -287,6 +333,7 @@ struct SeaConfig {
   std::string output_path;
   SeaFlags flags = SeaFlags::kDefault;
   std::unordered_map<std::string, std::string> assets;
+  std::vector<std::string> exec_argv;
 };
 
 std::optional<SeaConfig> ParseSingleExecutableConfig(
@@ -378,6 +425,17 @@ std::optional<SeaConfig> ParseSingleExecutableConfig(
     result.assets = std::move(assets_opt.value());
   }
 
+  auto exec_argv_opt = parser.GetTopLevelStringList("execArgv");
+  if (!exec_argv_opt.has_value()) {
+    FPrintF(stderr,
+            "\"execArgv\" field of %s is not an array of strings\n",
+            config_path);
+    return std::nullopt;
+  } else if (!exec_argv_opt.value().empty()) {
+    result.flags |= SeaFlags::kIncludeExecArgv;
+    result.exec_argv = std::move(exec_argv_opt.value());
+  }
+
   return result;
 }
 
@@ -546,14 +604,19 @@ ExitCode GenerateSingleExecutableBlob(
   for (auto const& [key, content] : assets) {
     assets_view.emplace(key, content);
   }
+  std::vector<std::string_view> exec_argv_view;
+  for (const auto& arg : config.exec_argv) {
+    exec_argv_view.emplace_back(arg);
+  }
   SeaResource sea{
       config.flags,
       config.main_path,
       builds_snapshot_from_main
           ? std::string_view{snapshot_blob.data(), snapshot_blob.size()}
           : std::string_view{main_script.data(), main_script.size()},
       optional_sv_code_cache,
-      assets_view};
+      assets_view,
+      exec_argv_view};
 
   SeaSerializer serializer;
   serializer.Write(sea);

src/node_sea.h

@@ -28,6 +28,7 @@ enum class SeaFlags : uint32_t {
   kUseSnapshot = 1 << 1,
   kUseCodeCache = 1 << 2,
   kIncludeAssets = 1 << 3,
+  kIncludeExecArgv = 1 << 4,
 };
 
 struct SeaResource {
@@ -36,6 +37,7 @@ struct SeaResource {
   std::string_view main_code_or_snapshot;
   std::optional<std::string_view> code_cache;
   std::unordered_map<std::string_view, std::string_view> assets;
+  std::vector<std::string_view> exec_argv;
 
   bool use_snapshot() const;
   bool use_code_cache() const;

test/fixtures/sea-exec-argv-empty.js

@@ -0,0 +1,6 @@
+const assert = require('assert');
+
+console.log('process.argv:', JSON.stringify(process.argv));
+assert.strictEqual(process.argv[2], 'user-arg');
+assert.deepStrictEqual(process.execArgv, []);
+console.log('empty execArgv test passed');

test/fixtures/sea-exec-argv.js

@@ -0,0 +1,18 @@
+const assert = require('assert');
+
+process.emitWarning('This warning should not be shown in the output', 'TestWarning');
+
+console.log('process.argv:', JSON.stringify(process.argv));
+console.log('process.execArgv:', JSON.stringify(process.execArgv));
+
+assert.deepStrictEqual(process.execArgv, [ '--no-warnings', '--max-old-space-size=2048' ]);
+
+// We start from 2, because in SEA, the index 1 would be the same as the execPath
+// to accommodate the general expectation that index 1 is the path to script for
+// applications.
+assert.deepStrictEqual(process.argv.slice(2), [
+  'user-arg1',
+  'user-arg2'
+]);
+
+console.log('multiple execArgv test passed');

test/sequential/test-single-executable-application-exec-argv-empty.js

@@ -0,0 +1,61 @@
+'use strict';
+
+require('../common');
+
+const {
+  generateSEA,
+  skipIfSingleExecutableIsNotSupported,
+} = require('../common/sea');
+
+skipIfSingleExecutableIsNotSupported();
+
+// This tests the execArgv functionality with empty array in single executable applications.
+
+const fixtures = require('../common/fixtures');
+const tmpdir = require('../common/tmpdir');
+const { copyFileSync, writeFileSync, existsSync } = require('fs');
+const { spawnSyncAndAssert, spawnSyncAndExitWithoutError } = require('../common/child_process');
+const { join } = require('path');
+const assert = require('assert');
+
+const configFile = tmpdir.resolve('sea-config.json');
+const seaPrepBlob = tmpdir.resolve('sea-prep.blob');
+const outputFile = tmpdir.resolve(process.platform === 'win32' ? 'sea.exe' : 'sea');
+
+tmpdir.refresh();
+
+// Copy test fixture to working directory
+copyFileSync(fixtures.path('sea-exec-argv-empty.js'), tmpdir.resolve('sea.js'));
+
+writeFileSync(configFile, `
+{
+  "main": "sea.js",
+  "output": "sea-prep.blob",
+  "disableExperimentalSEAWarning": true,
+  "execArgv": []
+}
+`);
+
+spawnSyncAndExitWithoutError(
+  process.execPath,
+  ['--experimental-sea-config', 'sea-config.json'],
+  { cwd: tmpdir.path });
+
+assert(existsSync(seaPrepBlob));
+
+generateSEA(outputFile, process.execPath, seaPrepBlob);
+
+// Test that empty execArgv work correctly
+spawnSyncAndAssert(
+  outputFile,
+  ['user-arg'],
+  {
+    env: {
+      COMMON_DIRECTORY: join(__dirname, '..', 'common'),
+      NODE_DEBUG_NATIVE: 'SEA',
+      ...process.env,
+    }
+  },
+  {
+    stdout: /empty execArgv test passed/
+  });