src: add initial support for ESM in embedder API

This patch extends `LoadEnvironment` to support loading ES modules,
and adds the following new types:

```cpp
enum class ModuleFormat : uint8_t {
  kCommonJS,
  kModule,
};

// Data for specifying an entry point script for LoadEnvironment().
// This class uses an opaque layout to allow future additions without
// breaking ABI. Use the setter methods to configure the entry point.
class ModuleData {
  void set_source(std::string_view source);
  void set_format(ModuleFormat format);
  void set_resource_name(std::string_view name);

  std::string_view source() const;
  ModuleFormat format() const;
  std::string_view resource_name() const;
};

class StartExecutionCallbackInfoWithModule {
  void set_env(Environment* env);
  void set_process_object(v8::Local<v8::Object> process_object);
  void set_native_require(v8::Local<v8::Function> native_require);
  void set_run_module(v8::Local<v8::Function> run_module);
  void set_data(void* data);

  Environment* env();
  v8::Local<v8::Object> process();
  v8::Local<v8::Function> native_require();
  v8::Local<v8::Function> run_module();
  void* data();
};
```

And two new `LoadEnvironment()` overloads:

```cpp
// Run entry point with ModuleData configuration
MaybeLocal<Value> LoadEnvironment(
    Environment* env,
    const ModuleData* entry_point,
    EmbedderPreloadCallback preload = nullptr);

// Callback-based with new StartExecutionCallbackInfoWithModule
MaybeLocal<Value> LoadEnvironment(
    Environment* env,
    StartExecutionCallbackWithModule cb,
    EmbedderPreloadCallback preload = nullptr,
    void* callback_data = nullptr);
```

Author: joyeecheung

lib/internal/main/embedding.js

@@ -15,15 +15,19 @@ const {
 const { isExperimentalSeaWarningNeeded, isSea } = internalBinding('sea');
 const { emitExperimentalWarning } = require('internal/util');
 const { emitWarningSync } = require('internal/process/warning');
-const { BuiltinModule: { normalizeRequirableId } } = require('internal/bootstrap/realm');
+const { BuiltinModule } = require('internal/bootstrap/realm');
+const { normalizeRequirableId } = BuiltinModule;
 const { Module } = require('internal/modules/cjs/loader');
 const { compileFunctionForCJSLoader } = internalBinding('contextify');
 const { maybeCacheSourceMap } = require('internal/source_map/source_map_cache');
-
 const { codes: {
   ERR_UNKNOWN_BUILTIN_MODULE,
 } } = require('internal/errors');
-
+const { pathToFileURL } = require('internal/url');
+const { loadBuiltinModule } = require('internal/modules/helpers');
+const { moduleFormats } = internalBinding('modules');
+const assert = require('internal/assert');
+const path = require('path');
 // Don't expand process.argv[1] because in a single-executable application or an
 // embedder application, the user main script isn't necessarily provided via the
 // command line (e.g. it could be provided via an API or bundled into the executable).
@@ -44,12 +48,11 @@ if (isExperimentalSeaWarningNeeded()) {
 // value of require.main to module.
 //
 // TODO(RaisinTen): Find a way to deduplicate this.
-function embedderRunCjs(content) {
+function embedderRunCjs(content, filename) {
   // The filename of the module (used for CJS module lookup)
   // is always the same as the location of the executable itself
   // at the time of the loading (which means it changes depending
   // on where the executable is in the file system).
-  const filename = process.execPath;
   const customModule = new Module(filename, null);
 
   const {
@@ -86,33 +89,93 @@ function embedderRunCjs(content) {
   customModule.paths = Module._nodeModulePaths(process.execPath);
   embedderRequire.main = customModule;
 
+  // This currently returns what the wrapper returns i.e. if the code
+  // happens to have a return statement, it returns that; Otherwise it's
+  // undefined.
+  // TODO(joyeecheung): we may want to return the customModule or put it in an
+  // out parameter.
   return compiledWrapper(
     customModule.exports,  // exports
     embedderRequire,       // require
     customModule,          // module
-    process.execPath,      // __filename
+    filename,              // __filename
     customModule.path,     // __dirname
   );
 }
 
 let warnedAboutBuiltins = false;
+function warnNonBuiltinInSEA() {
+  if (isBuiltinWarningNeeded && !warnedAboutBuiltins) {
+    emitWarningSync(
+      'Currently the require() provided to the main script embedded into ' +
+      'single-executable applications only supports loading built-in modules.\n' +
+      'To load a module from disk after the single executable application is ' +
+      'launched, use require("module").createRequire().\n' +
+      'Support for bundled module loading or virtual file systems are under ' +
+      'discussions in https://github.com/nodejs/single-executable');
+    warnedAboutBuiltins = true;
+  }
+}
 
 function embedderRequire(id) {
   const normalizedId = normalizeRequirableId(id);
+
   if (!normalizedId) {
-    if (isBuiltinWarningNeeded && !warnedAboutBuiltins) {
-      emitWarningSync(
-        'Currently the require() provided to the main script embedded into ' +
-        'single-executable applications only supports loading built-in modules.\n' +
-        'To load a module from disk after the single executable application is ' +
-        'launched, use require("module").createRequire().\n' +
-        'Support for bundled module loading or virtual file systems are under ' +
-        'discussions in https://github.com/nodejs/single-executable');
-      warnedAboutBuiltins = true;
-    }
+    warnNonBuiltinInSEA();
     throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
   }
   return require(normalizedId);
 }
 
-return [process, embedderRequire, embedderRunCjs];
+function embedderRunESM(content, filename) {
+  let resourceName;
+  if (path.isAbsolute(filename)) {
+    resourceName = pathToFileURL(filename).href;
+  } else {
+    resourceName = filename;
+  }
+  const { compileSourceTextModule } = require('internal/modules/esm/utils');
+  // TODO(joyeecheung): support code cache, dynamic import() and import.meta.
+  const wrap = compileSourceTextModule(resourceName, content);
+  // Cache the source map for the module if present.
+  if (wrap.sourceMapURL) {
+    maybeCacheSourceMap(resourceName, content, wrap, false, undefined, wrap.sourceMapURL);
+  }
+  const requests = wrap.getModuleRequests();
+  const modules = [];
+  for (let i = 0; i < requests.length; ++i) {
+    const { specifier } = requests[i];
+    const normalizedId = normalizeRequirableId(specifier);
+    if (!normalizedId) {
+      warnNonBuiltinInSEA();
+      throw new ERR_UNKNOWN_BUILTIN_MODULE(specifier);
+    }
+    const mod = loadBuiltinModule(normalizedId);
+    if (!mod) {
+      throw new ERR_UNKNOWN_BUILTIN_MODULE(specifier);
+    }
+    modules.push(mod.getESMFacade());
+  }
+  wrap.link(modules);
+  wrap.instantiate();
+  wrap.evaluate(-1, false);
+
+  // TODO(joyeecheung): we may want to return the v8::Module via a vm.SourceTextModule
+  // when vm.SourceTextModule stablizes, or put it in an out parameter.
+  return wrap.getNamespace();
+}
+
+function embedderRunEntryPoint(content, format, filename) {
+  format ||= moduleFormats.kCommonJS;
+  filename ||= process.execPath;
+
+  if (format === moduleFormats.kCommonJS) {
+    return embedderRunCjs(content, filename);
+  } else if (format === moduleFormats.kModule) {
+    return embedderRunESM(content, filename);
+  }
+  assert.fail(`Unknown format: ${format}`);
+
+}
+
+return [process, embedderRequire, embedderRunEntryPoint];

src/api/environment.cc

@@ -572,36 +572,186 @@ NODE_EXTERN std::unique_ptr<InspectorParentHandle> GetInspectorParentHandle(
 }
 
 MaybeLocal<Value> LoadEnvironment(Environment* env,
-                                  StartExecutionCallback cb,
-                                  EmbedderPreloadCallback preload) {
+                                  StartExecutionCallbackWithModule cb,
+                                  EmbedderPreloadCallback preload,
+                                  void* callback_data) {
   env->InitializeLibuv();
   env->InitializeDiagnostics();
   if (preload) {
     env->set_embedder_preload(std::move(preload));
   }
   env->InitializeCompileCache();
 
-  return StartExecution(env, cb);
+  return StartExecution(env, cb, callback_data);
+}
+
+struct StartExecutionCallbackInfoWithModule::Impl {
+  Environment* env = nullptr;
+  Local<Object> process_object;
+  Local<Function> native_require;
+  Local<Function> run_module;
+  void* data = nullptr;
+};
+
+StartExecutionCallbackInfoWithModule::StartExecutionCallbackInfoWithModule()
+    : impl_(std::make_unique<Impl>()) {}
+
+StartExecutionCallbackInfoWithModule::~StartExecutionCallbackInfoWithModule() =
+    default;
+
+StartExecutionCallbackInfoWithModule::StartExecutionCallbackInfoWithModule(
+    StartExecutionCallbackInfoWithModule&&) = default;
+
+StartExecutionCallbackInfoWithModule&
+StartExecutionCallbackInfoWithModule::operator=(
+    StartExecutionCallbackInfoWithModule&&) = default;
+
+void StartExecutionCallbackInfoWithModule::set_env(Environment* env) {
+  impl_->env = env;
+}
+
+void StartExecutionCallbackInfoWithModule::set_process_object(
+    Local<Object> process_object) {
+  impl_->process_object = process_object;
+}
+
+void StartExecutionCallbackInfoWithModule::set_native_require(
+    Local<Function> native_require) {
+  impl_->native_require = native_require;
+}
+
+void StartExecutionCallbackInfoWithModule::set_run_module(
+    Local<Function> run_module) {
+  impl_->run_module = run_module;
+}
+
+void StartExecutionCallbackInfoWithModule::set_data(void* data) {
+  impl_->data = data;
+}
+
+Environment* StartExecutionCallbackInfoWithModule::env() const {
+  return impl_->env;
+}
+
+Local<Object> StartExecutionCallbackInfoWithModule::process_object() const {
+  return impl_->process_object;
+}
+
+Local<Function> StartExecutionCallbackInfoWithModule::native_require() const {
+  return impl_->native_require;
+}
+
+Local<Function> StartExecutionCallbackInfoWithModule::run_module() const {
+  return impl_->run_module;
+}
+
+void* StartExecutionCallbackInfoWithModule::data() const {
+  return impl_->data;
+}
+
+struct ModuleData::Impl {
+  std::string_view source;
+  ModuleFormat format = ModuleFormat::kCommonJS;
+  std::string_view resource_name;
+};
+
+ModuleData::ModuleData() : impl_(std::make_unique<Impl>()) {}
+
+ModuleData::~ModuleData() = default;
+
+ModuleData::ModuleData(ModuleData&&) = default;
+
+ModuleData& ModuleData::operator=(ModuleData&&) = default;
+
+void ModuleData::set_source(std::string_view source) {
+  impl_->source = source;
+}
+
+void ModuleData::set_format(ModuleFormat format) {
+  impl_->format = format;
+}
+
+void ModuleData::set_resource_name(std::string_view name) {
+  impl_->resource_name = name;
+}
+
+std::string_view ModuleData::source() const {
+  return impl_->source;
+}
+
+ModuleFormat ModuleData::format() const {
+  return impl_->format;
+}
+
+std::string_view ModuleData::resource_name() const {
+  return impl_->resource_name;
+}
+
+struct LegacyModuleData {
+  StartExecutionCallback cb;
+  void* callback_data;
+};
+
+MaybeLocal<Value> LoadEnvironment(Environment* env,
+                                  StartExecutionCallback cb,
+                                  EmbedderPreloadCallback preload,
+                                  void* callback_data) {
+  if (cb == nullptr) {
+    return LoadEnvironment(
+        env, StartExecutionCallbackWithModule{}, std::move(preload));
+  }
+
+  LegacyModuleData data{cb, callback_data};
+  return LoadEnvironment(
+      env,
+      [](const StartExecutionCallbackInfoWithModule& info)
+          -> MaybeLocal<Value> {
+        const LegacyModuleData* data =
+            static_cast<const LegacyModuleData*>(info.data());
+        StartExecutionCallbackInfo legacy_info{
+            info.process_object(),
+            info.native_require(),
+            info.run_module(),
+            data->callback_data,
+        };
+        return data->cb(legacy_info);
+      },
+      nullptr,
+      &data);
+}
+
+MaybeLocal<Value> RunModule(const StartExecutionCallbackInfoWithModule& info) {
+  const ModuleData* data = static_cast<const ModuleData*>(info.data());
+  Environment* env = info.env();
+  Local<Context> context = env->context();
+  Isolate* isolate = env->isolate();
+  Local<Value> main_script =
+      ToV8Value(context, data->source()).ToLocalChecked();
+  Local<Value> format =
+      v8::Integer::New(isolate, static_cast<int>(data->format()));
+  Local<Value> resource_name =
+      ToV8Value(context, data->resource_name()).ToLocalChecked();
+  Local<Value> args[] = {main_script, format, resource_name};
+  return info.run_module()->Call(context, Null(isolate), arraysize(args), args);
 }
 
 MaybeLocal<Value> LoadEnvironment(Environment* env,
                                   std::string_view main_script_source_utf8,
                                   EmbedderPreloadCallback preload) {
+  ModuleData data;
+  data.set_source(main_script_source_utf8);
+  data.set_format(ModuleFormat::kCommonJS);
+  data.set_resource_name(env->exec_path());
+  return LoadEnvironment(env, &data, std::move(preload));
+}
+
+MaybeLocal<Value> LoadEnvironment(Environment* env,
+                                  const ModuleData* data,
+                                  EmbedderPreloadCallback preload) {
   // It could be empty when it's used by SEA to load an empty script.
-  CHECK_IMPLIES(main_script_source_utf8.size() > 0,
-                main_script_source_utf8.data());
+  CHECK_IMPLIES(data->source().size() > 0, data->source().data());
   return LoadEnvironment(
-      env,
-      [&](const StartExecutionCallbackInfo& info) -> MaybeLocal<Value> {
-        Local<Value> main_script;
-        if (!ToV8Value(env->context(), main_script_source_utf8)
-                 .ToLocal(&main_script)) {
-          return {};
-        }
-        return info.run_cjs->Call(
-            env->context(), Null(env->isolate()), 1, &main_script);
-      },
-      std::move(preload));
+      env, RunModule, std::move(preload), const_cast<ModuleData*>(data));
 }
 
 Environment* GetCurrentEnvironment(Local<Context> context) {