sea: add allowDynamicImportFromFileSystem config option

Signed-off-by: Ali Hassan <ali-hassan27@outlook.com>

Author: thisalihassan

doc/api/single-executable-applications.md

@@ -111,6 +111,7 @@ The configuration currently reads the following top-level fields:
 {
   "main": "/path/to/bundled/script.js",
   "mainFormat": "commonjs", // Default: "commonjs", options: "commonjs", "module"
+  "allowDynamicImportFromFileSystem": false, // Default: false
   "executable": "/path/to/node/binary", // Optional, if not specified, uses the current Node.js binary
   "output": "/path/to/write/the/generated/executable",
   "disableExperimentalSEAWarning": true, // Default: false
@@ -451,9 +452,12 @@ injected main script with the following properties:
 
 <!-- TODO(joyeecheung): support and document module.registerHooks -->
 
-When using `"mainFormat": "module"`, `import()` can be used to dynamically
-load built-in modules. Attempting to use `import()` to load modules from
-the file system will throw an error.
+By default, `import()` in the injected main script can only load built-in
+modules. When `allowDynamicImportFromFileSystem` is set to `true` in the SEA
+configuration, `import()` can also load modules from the file system. This
+works for both `"mainFormat": "commonjs"` and `"mainFormat": "module"`
+entry points. Relative specifiers are resolved relative to the directory of the
+executable.
 
 ### Using native addons in the injected main script
 

lib/internal/modules/esm/utils.js

@@ -48,6 +48,7 @@ const {
 } = require('internal/modules/helpers');
 
 let defaultConditions;
+let seaBinding;
 /**
  * Returns the default conditions for ES module loading.
  * @returns {object}
@@ -68,6 +69,10 @@ function getDefaultConditionsSet() {
   return defaultConditionsSet;
 }
 
+function getSeaBinding() {
+  return seaBinding ??= internalBinding('sea');
+}
+
 /**
  * Initializes the default conditions for ESM module loading.
  * This function is called during pre-execution, before any user code is run.
@@ -238,15 +243,25 @@ function getBuiltinModuleWrapForEmbedder(specifier) {
 }
 
 /**
- * Get the built-in module dynamically for embedder ESM.
+ * Handle dynamic import for embedder entry points.
+ * SEA can opt into the default loader via explicit configuration; other embedder
+ * entry points continue to be limited to built-in modules.
  * @param {string} specifier - The module specifier string.
- * @param {number} phase - The module import phase. Ignored for now.
- * @param {Record<string, string>} attributes - The import attributes object. Ignored for now.
+ * @param {number} phase - The module import phase.
+ * @param {Record<string, string>} attributes - The import attributes object.
  * @param {string|null|undefined} referrerName - name of the referrer.
- * @returns {import('internal/modules/esm/loader.js').ModuleExports} - The imported module object.
+ * @returns {Promise<import('internal/modules/esm/loader.js').ModuleExports>} - The imported module object.
  */
 function importModuleDynamicallyForEmbedder(specifier, phase, attributes, referrerName) {
-  // Ignore phase and attributes for embedder ESM for now, because this only supports loading builtins.
+  const { isSeaDynamicImportFromFileSystemEnabled } = getSeaBinding();
+  if (isSeaDynamicImportFromFileSystemEnabled()) {
+    return defaultImportModuleDynamicallyForScript(
+      specifier,
+      phase,
+      attributes,
+      referrerName,
+    );
+  }
   return getBuiltinModuleWrapForEmbedder(specifier).getNamespace();
 }
 
@@ -277,7 +292,7 @@ async function importModuleDynamicallyCallback(referrerSymbol, specifier, phase,
   if (referrerSymbol === source_text_module_default_hdo) {
     return defaultImportModuleDynamicallyForModule(specifier, phase, attributes, referrerName);
   }
-  // For embedder entry point ESM, only allow built-in modules.
+  // For embedder entry points, proxy dynamic import to the default loader.
   if (referrerSymbol === embedder_module_hdo) {
     return importModuleDynamicallyForEmbedder(specifier, phase, attributes, referrerName);
   }

src/node_sea.cc

@@ -283,6 +283,18 @@ void IsExperimentalSeaWarningNeeded(const FunctionCallbackInfo<Value>& args) {
       sea_resource.flags & SeaFlags::kDisableExperimentalSeaWarning));
 }
 
+void IsSeaDynamicImportFromFileSystemEnabled(
+    const FunctionCallbackInfo<Value>& args) {
+  if (!IsSingleExecutable()) {
+    args.GetReturnValue().Set(false);
+    return;
+  }
+
+  SeaResource sea_resource = FindSingleExecutableResource();
+  args.GetReturnValue().Set(static_cast<bool>(
+      sea_resource.flags & SeaFlags::kAllowDynamicImportFromFileSystem));
+}
+
 std::tuple<int, char**> FixupArgsForSEA(int argc, char** argv) {
   // Repeats argv[0] at position 1 on argv as a replacement for the missing
   // entry point file path.
@@ -444,6 +456,18 @@ std::optional<SeaConfig> ParseSingleExecutableConfig(
       if (use_code_cache_value) {
         result.flags |= SeaFlags::kUseCodeCache;
       }
+    } else if (key == "allowDynamicImportFromFileSystem") {
+      bool allow_dynamic_import_from_file_system;
+      if (field.value().get_bool().get(allow_dynamic_import_from_file_system)) {
+        FPrintF(stderr,
+                "\"allowDynamicImportFromFileSystem\" field of %s is not a "
+                "Boolean\n",
+                config_path);
+        return std::nullopt;
+      }
+      if (allow_dynamic_import_from_file_system) {
+        result.flags |= SeaFlags::kAllowDynamicImportFromFileSystem;
+      }
     } else if (key == "assets") {
       simdjson::ondemand::object assets_object;
       if (field.value().get_object().get(assets_object)) {
@@ -918,13 +942,18 @@ void Initialize(Local<Object> target,
             target,
             "isExperimentalSeaWarningNeeded",
             IsExperimentalSeaWarningNeeded);
+  SetMethod(context,
+            target,
+            "isSeaDynamicImportFromFileSystemEnabled",
+            IsSeaDynamicImportFromFileSystemEnabled);
   SetMethod(context, target, "getAsset", GetAsset);
   SetMethod(context, target, "getAssetKeys", GetAssetKeys);
 }
 
 void RegisterExternalReferences(ExternalReferenceRegistry* registry) {
   registry->Register(IsSea);
   registry->Register(IsExperimentalSeaWarningNeeded);
+  registry->Register(IsSeaDynamicImportFromFileSystemEnabled);
   registry->Register(GetAsset);
   registry->Register(GetAssetKeys);
 }

src/node_sea.h

@@ -30,6 +30,7 @@ enum class SeaFlags : uint32_t {
   kUseCodeCache = 1 << 2,
   kIncludeAssets = 1 << 3,
   kIncludeExecArgv = 1 << 4,
+  kAllowDynamicImportFromFileSystem = 1 << 5,
 };
 
 enum class SeaExecArgvExtension : uint8_t {

test/fixtures/sea/dynamic-import-cjs/sea-config-opt-in-code-cache.json

@@ -0,0 +1,7 @@
+{
+  "main": "sea.js",
+  "output": "sea",
+  "allowDynamicImportFromFileSystem": true,
+  "useCodeCache": true,
+  "disableExperimentalSEAWarning": true
+}

test/fixtures/sea/dynamic-import-cjs/sea-config-opt-in.json

@@ -0,0 +1,6 @@
+{
+  "main": "sea.js",
+  "output": "sea",
+  "allowDynamicImportFromFileSystem": true,
+  "disableExperimentalSEAWarning": true
+}

test/fixtures/sea/dynamic-import-cjs/sea-config.json

@@ -0,0 +1,5 @@
+{
+  "main": "sea.js",
+  "output": "sea",
+  "disableExperimentalSEAWarning": true
+}

test/fixtures/sea/dynamic-import-cjs/sea.js

@@ -0,0 +1,15 @@
+const { pathToFileURL } = require('node:url');
+const { dirname, join } = require('node:path');
+
+const userURL = pathToFileURL(
+  join(dirname(process.execPath), 'user.mjs'),
+).href;
+
+import(userURL)
+  .then(({ message }) => {
+    console.log(message);
+  })
+  .catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });

test/fixtures/sea/dynamic-import-cjs/user.mjs

@@ -0,0 +1,3 @@
+await Promise.resolve();
+
+export const message = 'CJS SEA dynamic import executed successfully';

test/fixtures/sea/dynamic-import-esm/sea-config-opt-in.json

@@ -0,0 +1,7 @@
+{
+  "main": "sea.mjs",
+  "output": "sea",
+  "mainFormat": "module",
+  "allowDynamicImportFromFileSystem": true,
+  "disableExperimentalSEAWarning": true
+}