module: support loading entrypoint as url

Co-Authored-By: Antoine du Hamel <[email protected]>
PR-URL: #54933
Refs: #49975
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: LiviaMedeiros <[email protected]>
Reviewed-By: Stephen Belanger <[email protected]>
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>

doc/api/cli.md

@@ -795,6 +795,28 @@ when `Error.stack` is accessed. If you access `Error.stack` frequently
 in your application, take into account the performance implications
 of `--enable-source-maps`.
 
+### `--entry-url`
+
+<!-- YAML
+added:
+  - REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+When present, Node.js will interpret the entry point as a URL, rather than a
+path.
+
+Follows [ECMAScript module][] resolution rules.
+
+Any query parameter or hash in the URL will be accessible via [`import.meta.url`][].
+
+```bash
+node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'
+node --entry-url --experimental-strip-types 'file.ts?query#hash'
+node --entry-url 'data:text/javascript,console.log("Hello")'
+```
+
 ### `--env-file=config`
 
 > Stability: 1.1 - Active development
@@ -3024,6 +3046,7 @@ one is included in the list below.
 * `--enable-fips`
 * `--enable-network-family-autoselection`
 * `--enable-source-maps`
+* `--entry-url`
 * `--experimental-abortcontroller`
 * `--experimental-async-context-frame`
 * `--experimental-default-type`
@@ -3623,6 +3646,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [`dns.lookup()`]: dns.md#dnslookuphostname-options-callback
 [`dns.setDefaultResultOrder()`]: dns.md#dnssetdefaultresultorderorder
 [`dnsPromises.lookup()`]: dns.md#dnspromiseslookuphostname-options
+[`import.meta.url`]: esm.md#importmetaurl
 [`import` specifier]: esm.md#import-specifiers
 [`net.getDefaultAutoSelectFamilyAttemptTimeout()`]: net.md#netgetdefaultautoselectfamilyattempttimeout
 [`node:sqlite`]: sqlite.md

doc/node.1

@@ -160,6 +160,9 @@ Requires Node.js to be built with
 .It Fl -enable-source-maps
 Enable Source Map V3 support for stack traces.
 .
+.It Fl -entry-url
+Interpret the entry point as a URL.
+.
 .It Fl -experimental-default-type Ns = Ns Ar type
 Interpret as either ES modules or CommonJS modules input via --eval or STDIN, when --input-type is unspecified;
 .js or extensionless files with no sibling or parent package.json;

lib/internal/main/run_main_module.js

@@ -9,14 +9,20 @@ const {
   markBootstrapComplete,
 } = require('internal/process/pre_execution');
 const { getOptionValue } = require('internal/options');
+const { emitExperimentalWarning } = require('internal/util');
 
-const mainEntry = prepareMainThreadExecution(true);
+const isEntryURL = getOptionValue('--entry-url');
+const mainEntry = prepareMainThreadExecution(!isEntryURL);
 
 markBootstrapComplete();
 
 // Necessary to reset RegExp statics before user code runs.
 RegExpPrototypeExec(/^/, '');
 
+if (isEntryURL) {
+  emitExperimentalWarning('--entry-url');
+}
+
 if (getOptionValue('--experimental-default-type') === 'module') {
   require('internal/modules/run_main').executeUserEntryPoint(mainEntry);
 } else {

lib/internal/modules/run_main.js

@@ -8,7 +8,7 @@ const {
 const { getNearestParentPackageJSONType } = internalBinding('modules');
 const { getOptionValue } = require('internal/options');
 const path = require('path');
-const { pathToFileURL } = require('internal/url');
+const { pathToFileURL, URL } = require('internal/url');
 const { kEmptyObject, getCWDURL } = require('internal/util');
 const {
   hasUncaughtExceptionCaptureCallback,
@@ -154,9 +154,14 @@ function runEntryPointWithESMLoader(callback) {
  * @param {string} main - First positional CLI argument, such as `'entry.js'` from `node entry.js`
  */
 function executeUserEntryPoint(main = process.argv[1]) {
-  const resolvedMain = resolveMainPath(main);
-  const useESMLoader = shouldUseESMLoader(resolvedMain);
-  let mainURL;
+  let useESMLoader;
+  let resolvedMain;
+  if (getOptionValue('--entry-url')) {
+    useESMLoader = true;
+  } else {
+    resolvedMain = resolveMainPath(main);
+    useESMLoader = shouldUseESMLoader(resolvedMain);
+  }
   // Unless we know we should use the ESM loader to handle the entry point per the checks in `shouldUseESMLoader`, first
   // try to run the entry point via the CommonJS loader; and if that fails under certain conditions, retry as ESM.
   if (!useESMLoader) {
@@ -165,9 +170,7 @@ function executeUserEntryPoint(main = process.argv[1]) {
     wrapModuleLoad(main, null, true);
   } else {
     const mainPath = resolvedMain || main;
-    if (mainURL === undefined) {
-      mainURL = pathToFileURL(mainPath).href;
-    }
+    const mainURL = getOptionValue('--entry-url') ? new URL(mainPath, getCWDURL()) : pathToFileURL(mainPath);
 
     runEntryPointWithESMLoader((cascadedLoader) => {
       // Note that if the graph contains unsettled TLA, this may never resolve

src/node_options.cc

@@ -406,6 +406,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "Source Map V3 support for stack traces",
             &EnvironmentOptions::enable_source_maps,
             kAllowedInEnvvar);
+  AddOption("--entry-url",
+            "Treat the entrypoint as a URL",
+            &EnvironmentOptions::entry_is_url,
+            kAllowedInEnvvar);
   AddOption("--experimental-abortcontroller", "", NoOp{}, kAllowedInEnvvar);
   AddOption("--experimental-eventsource",
             "experimental EventSource API",

src/node_options.h

@@ -133,6 +133,7 @@ class EnvironmentOptions : public Options {
   bool experimental_import_meta_resolve = false;
   std::string input_type;  // Value of --input-type
   std::string type;        // Value of --experimental-default-type
+  bool entry_is_url = false;
   bool experimental_permission = false;
   std::vector<std::string> allow_fs_read;
   std::vector<std::string> allow_fs_write;

test/es-module/test-esm-loader-entry-url.mjs

@@ -0,0 +1,97 @@
+import { spawnPromisified } from '../common/index.mjs';
+import * as fixtures from '../common/fixtures.mjs';
+import assert from 'node:assert';
+import { execPath } from 'node:process';
+import { describe, it } from 'node:test';
+
+// Helper function to assert the spawned process
+async function assertSpawnedProcess(args, options = {}, expected = {}) {
+  const { code, signal, stderr, stdout } = await spawnPromisified(execPath, args, options);
+
+  if (expected.stderr) {
+    assert.match(stderr, expected.stderr);
+  }
+
+  if (expected.stdout) {
+    assert.match(stdout, expected.stdout);
+  }
+
+  assert.strictEqual(code, expected.code ?? 0);
+  assert.strictEqual(signal, expected.signal ?? null);
+}
+
+// Common expectation for experimental feature warning in stderr
+const experimentalFeatureWarning = { stderr: /--entry-url is an experimental feature/ };
+
+describe('--entry-url', { concurrency: true }, () => {
+  it('should reject loading a path that contains %', async () => {
+    await assertSpawnedProcess(
+      ['--entry-url', './test-esm-double-encoding-native%20.mjs'],
+      { cwd: fixtures.fileURL('es-modules') },
+      {
+        code: 1,
+        stderr: /ERR_MODULE_NOT_FOUND/,
+      }
+    );
+  });
+
+  it('should support loading properly encoded Unix path', async () => {
+    await assertSpawnedProcess(
+      ['--entry-url', fixtures.fileURL('es-modules/test-esm-double-encoding-native%20.mjs').pathname],
+      {},
+      experimentalFeatureWarning
+    );
+  });
+
+  it('should support loading absolute URLs', async () => {
+    await assertSpawnedProcess(
+      ['--entry-url', fixtures.fileURL('printA.js')],
+      {},
+      {
+        ...experimentalFeatureWarning,
+        stdout: /^A\r?\n$/,
+      }
+    );
+  });
+
+  it('should support loading relative URLs', async () => {
+    await assertSpawnedProcess(
+      ['--entry-url', 'es-modules/print-entrypoint.mjs?key=value#hash'],
+      { cwd: fixtures.fileURL('./') },
+      {
+        ...experimentalFeatureWarning,
+        stdout: /print-entrypoint\.mjs\?key=value#hash\r?\n$/,
+      }
+    );
+  });
+
+  it('should support loading `data:` URLs', async () => {
+    await assertSpawnedProcess(
+      ['--entry-url', 'data:text/javascript,console.log(import.meta.url)'],
+      {},
+      {
+        ...experimentalFeatureWarning,
+        stdout: /^data:text\/javascript,console\.log\(import\.meta\.url\)\r?\n$/,
+      }
+    );
+  });
+
+  it('should support loading TypeScript URLs', async () => {
+    const typescriptUrls = [
+      'typescript/cts/test-require-ts-file.cts',
+      'typescript/mts/test-import-ts-file.mts',
+    ];
+
+    for (const url of typescriptUrls) {
+      await assertSpawnedProcess(
+        ['--entry-url', '--experimental-strip-types', fixtures.fileURL(url)],
+        {},
+        {
+          ...experimentalFeatureWarning,
+          stdout: /Hello, TypeScript!/,
+        }
+      );
+    }
+  });
+
+});

test/fixtures/es-modules/print-entrypoint.mjs

@@ -0,0 +1 @@
+console.log(import.meta.url);