sea: mount the assets VFS in workers

A single executable application built with "useVfs" mounted the VFS
serving its assets in the main thread only, at a mount point numbered
in mount order, so a worker started from a script among the assets
could not load it. On Windows this failed as an invalid package.json
at \\.\nul\package.json, because paths under the NUL device open it.

Reserve layer 1 for the assets, as layer 0 is reserved for the
--vfs-load source and the "vfsArchive" archive, and mount them in
workers too. A worker started from a path into a VFS that is not
mounted in it, such as one mounted with vfs.mount() in its parent,
now fails with ERR_VFS_NOT_MOUNTED.

Fixes: #67223
Assisted-by: a coding agent
Signed-off-by: Manjeet Singh <024manjeetsingh@gmail.com>

Author: manusingh090

doc/api/errors.md

@@ -3588,6 +3588,17 @@ entry types are found.
 A `--vfs-load` source does not exist, is neither a regular file nor a
 directory, or is a source no provider claims.
 
+<a id="ERR_VFS_NOT_MOUNTED"></a>
+
+### `ERR_VFS_NOT_MOUNTED`
+
+A path into a virtual file system was used in a thread in which that virtual
+file system is not mounted. Each thread has its own mounts: a virtual file
+system mounted with [`vfs.mount()`][] is not mounted in the [`Worker`][]
+threads, so a worker cannot be started from a script in it. The source
+mounted with [`--vfs-load`][] and the virtual file system of a
+[single executable application][] are mounted in every thread.
+
 <a id="ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING"></a>
 
 ### `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`
@@ -4777,6 +4788,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`--force-fips`]: cli.md#--force-fips
 [`--no-addons`]: cli.md#--no-addons
 [`--unhandled-rejections`]: cli.md#--unhandled-rejectionsmode
+[`--vfs-load`]: cli.md#--vfs-loadsource
 [`ABORT_ERR`]: #abort_err
 [`BoundSocket`]: net.md#class-netboundsocket
 [`Class: DOMException`]: globals.md#class-domexception
@@ -4795,6 +4807,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`REPL`]: repl.md
 [`ServerResponse`]: http.md#class-httpserverresponse
 [`Temporal`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal
+[`Worker`]: worker_threads.md#class-worker
 [`Writable`]: stream.md#class-streamwritable
 [`ZipBuffer`]: zlib.md#class-zlibzipbuffer
 [`ZipFile`]: zlib.md#class-zlibzipfile
@@ -4858,6 +4871,7 @@ An error occurred trying to allocate memory. This should never happen.
 [`util.inspect()`]: util.md#utilinspectobject-options
 [`util.parseArgs()`]: util.md#utilparseargsconfig
 [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
+[`vfs.mount()`]: vfs.md#vfsmount
 [`zlib`]: zlib.md
 [crypto digest algorithm]: crypto.md#cryptogethashes
 [debugger]: debugger.md
@@ -4868,6 +4882,7 @@ An error occurred trying to allocate memory. This should never happen.
 [package map]: packages.md#package-maps
 [relative URL]: https://url.spec.whatwg.org/#relative-url-string
 [self-reference a package using its name]: packages.md#self-referencing-a-package-using-its-name
+[single executable application]: single-executable-applications.md#virtual-file-system-vfs-for-assets
 [special scheme]: https://url.spec.whatwg.org/#special-scheme
 [stream-based]: stream.md
 [syscall]: https://man7.org/linux/man-pages/man2/syscalls.2.html

doc/api/single-executable-applications.md

@@ -261,6 +261,25 @@ Module format detection works the same way as on the real file
 system: name bundled ES modules with the `.mjs` extension (or provide the
 relevant `package.json` files as assets) so they are interpreted as ESM.
 
+#### Worker threads
+
+Worker threads mount the virtual file system as well, at the same mount
+point as the main thread. A path into it, such as the main script's
+`__filename` or a worker script bundled as an asset, can therefore be loaded
+in a [`Worker`][], which reaches the other assets the same way the main
+script does:
+
+```cjs
+const { Worker } = require('node:worker_threads');
+const path = require('node:path');
+
+// worker.js is bundled as an asset, at the root of the mount.
+new Worker(path.join(__dirname, 'worker.js'));
+```
+
+A virtual file system mounted with [`vfs.mount()`][] in one thread is not
+mounted in the others, so a worker cannot load a script from it.
+
 #### Serving the assets from a ZIP archive with `"vfsArchive"`
 
 Instead of listing individual `"assets"`, the configuration can point
@@ -296,10 +315,10 @@ executable only embeds the archive; read the files through the file system
 APIs instead. `"vfsArchive"` requires `"useVfs": true` and cannot be
 combined with `"assets"`.
 
-The archive is mounted at the mount point reserved for [`--vfs-load`][], which
-is the same in every thread, and worker threads mount it as well. A path into
-the archive, such as the main script's `__filename`, can therefore be loaded
-in a worker:
+The archive is mounted at the mount point reserved for [`--vfs-load`][], and,
+like the assets, it is mounted in [worker threads](#worker-threads) as well.
+A path into the archive, such as the main script's `__filename`, can therefore
+be loaded in a worker:
 
 ```cjs
 const { Worker, isMainThread } = require('node:worker_threads');
@@ -808,6 +827,7 @@ to help us document them.
 [VFS documentation]: vfs.md
 [Windows SDK]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
 [`--vfs-load`]: cli.md#--vfs-loadsource
+[`Worker`]: worker_threads.md#class-worker
 [`node:zlib`]: zlib.md
 [`process.execPath`]: process.md#processexecpath
 [`require()`]: modules.md#requireid
@@ -818,6 +838,7 @@ to help us document them.
 [`sea.getRawAsset()`]: #seagetrawassetkey
 [`v8.startupSnapshot.setDeserializeMainFunction()`]: v8.md#v8startupsnapshotsetdeserializemainfunctioncallback-data
 [`v8.startupSnapshot` API]: v8.md#startup-snapshot-api
+[`vfs.mount()`]: vfs.md#vfsmount
 [documentation about startup snapshot support in Node.js]: cli.md#--build-snapshot
 [fuse]: https://www.electronjs.org/docs/latest/tutorial/fuses
 [module loader integration]: vfs.md#module-loader-integration

lib/internal/errors.js

@@ -1962,6 +1962,8 @@ E('ERR_VALID_PERFORMANCE_ENTRY_TYPE',
   'At least one valid performance entry type is required', Error);
 E('ERR_VFS_INVALID_TARGET',
   '%s is not a valid --vfs-load source: must be an existing file or directory', Error);
+E('ERR_VFS_NOT_MOUNTED',
+  '%s is in a virtual file system that is not mounted in this thread', Error);
 E('ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING',
   'A dynamic import callback was not specified.', TypeError);
 E('ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING_FLAG',

lib/internal/main/worker_thread.js

@@ -11,6 +11,7 @@ const {
   ObjectDefineProperty,
   PromisePrototypeThen,
   RegExpPrototypeExec,
+  StringPrototypeIncludes,
 } = primordials;
 
 const {
@@ -153,9 +154,10 @@ port.on('message', (message) => {
       if (getOptionValue('--import').length === 0) {
         finishVfsMounts();
       }
-      // Unlike the --vfs-load source, a SEA archive needs no provider that a
+      // Unlike the --vfs-load source, the SEA VFS needs no provider that a
       // preload could register, so its mount is never deferred.
-      if (getOptionValue('[sea_vfs_archive]')) {
+      if (getOptionValue('[sea_vfs_archive]') ||
+          getOptionValue('[sea_vfs_assets]')) {
         require('internal/vfs/sea').initSeaVfsInWorker();
       }
     }
@@ -247,6 +249,13 @@ port.on('message', (message) => {
           runWebWorkerScript(source, webWorkerData);
           break;
         }
+        // A worker does not share the VFS mounts of its parent. Report a path
+        // into one that is not mounted here instead of letting the real file
+        // system answer for it. Every such path contains the reserved `vfs`
+        // directory, which spares other workers from loading the VFS.
+        if (StringPrototypeIncludes(filename, 'vfs')) {
+          require('internal/vfs/setup').assertVFSPathMounted(filename);
+        }
         // script filename
         // runMain here might be monkey-patched by users in --require.
         // XXX: the monkey-patchability here should probably be deprecated.

lib/internal/vfs/file_system.js

@@ -40,6 +40,7 @@ const { VirtualReadStream, VirtualWriteStream } = require('internal/vfs/streams'
 const { VirtualDir } = require('internal/vfs/dir');
 const { emitExperimentalWarning, kEmptyObject } = require('internal/util');
 const { validateBoolean } = require('internal/validators');
+const { getOptionValue } = require('internal/options');
 let debug = require('internal/util/debuglog').debuglog('vfs', (fn) => {
   debug = fn;
 });
@@ -54,13 +55,23 @@ const kPromises = Symbol('kPromises');
 const kLayerId = Symbol('kLayerId');
 const kReservedRoot = Symbol('kReservedRoot');
 const kLoadLayer = Symbol('kLoadLayer');
+const kSeaLayer = Symbol('kSeaLayer');
 
 // Layer 0 is reserved for the file system --vfs-load mounts, so that source is
 // at the same mount point in every thread whatever else a thread mounts, and a
-// path into it stays valid in a worker. Everything else is numbered from 1, in
-// the order it is mounted.
+// path into it stays valid in a worker. For the same reason, in a single
+// executable application whose VFS serves its assets, layer 1 is reserved for
+// them. Everything else is numbered from the next free id, in the order it is
+// mounted.
 const kLoadLayerId = 0;
-let nextLayerId = kLoadLayerId + 1;
+const kSeaLayerId = 1;
+let nextLayerId;
+
+function allocateLayerId() {
+  nextLayerId ??= getOptionValue('[sea_vfs_assets]') ?
+    kSeaLayerId + 1 : kLoadLayerId + 1;
+  return nextLayerId++;
+}
 
 /**
  * Normalizes paths for mount-point comparisons. On Windows, `path.resolve('/x')`
@@ -147,7 +158,13 @@ class VirtualFileSystem {
     this[kMountPoint] = null;
     this[kNormalizedMountPoint] = null;
     this[kMounted] = false;
-    this[kLayerId] = options[kLoadLayer] === true ? kLoadLayerId : nextLayerId++;
+    if (options[kLoadLayer] === true) {
+      this[kLayerId] = kLoadLayerId;
+    } else if (options[kSeaLayer] === true) {
+      this[kLayerId] = kSeaLayerId;
+    } else {
+      this[kLayerId] = allocateLayerId();
+    }
   }
 
   /**
@@ -1404,5 +1421,6 @@ module.exports = {
   kLayerId,
   kLoadLayer,
   kReservedRoot,
+  kSeaLayer,
   normalizeMountedPath,
 };

lib/internal/vfs/sea.js

@@ -45,7 +45,11 @@ function initSeaVfs(mainCode) {
     return null;
   }
 
-  const { VirtualFileSystem, kLoadLayer } = require('internal/vfs/file_system');
+  const {
+    VirtualFileSystem,
+    kLoadLayer,
+    kSeaLayer,
+  } = require('internal/vfs/file_system');
 
   const extraFiles = { __proto__: null, [getSeaMainName()]: mainCode };
   const isArchive = isVfsArchiveEnabled();
@@ -58,27 +62,27 @@ function initSeaVfs(mainCode) {
   }
   // The SEA warning already covers the feature; don't emit the
   // VirtualFileSystem experimental warning for the implicit SEA mount.
-  // An archive is mounted where --vfs-load mounts its source, which is the
-  // same mount point in every thread, so a worker can reach the code in it.
+  // An archive is mounted where --vfs-load mounts its source, and the assets
+  // at the mount point reserved for them. Either is the same mount point in
+  // every thread, so a worker can reach the code in it.
   const vfs = new VirtualFileSystem(provider, {
     __proto__: null,
     emitExperimentalWarning: false,
     [kLoadLayer]: isArchive,
+    [kSeaLayer]: !isArchive,
   });
   vfs.mount();
 
   return vfs;
 }
 
 /**
- * Mounts the SEA virtual file system in a worker, when it is backed by a
- * `"vfsArchive"`, so that a path into the mount in the main thread, such as
- * the main script's `__filename`, is also valid in the worker.
+ * Mounts the SEA virtual file system in a worker, so that a path into the
+ * mount in the main thread, such as the main script's `__filename`, is also
+ * valid in the worker.
  */
 function initSeaVfsInWorker() {
-  if (isVfsArchiveEnabled()) {
-    initSeaVfs(getMainCode());
-  }
+  initSeaVfs(getMainCode());
 }
 
 /**

lib/internal/vfs/setup.js

@@ -22,6 +22,7 @@ const {
     ERR_INVALID_ARG_TYPE,
     ERR_INVALID_STATE,
     ERR_MODULE_NOT_FOUND,
+    ERR_VFS_NOT_MOUNTED,
   },
 } = require('internal/errors');
 const { createENOENT, createEROFS, createEXDEV } = require('internal/vfs/errors');
@@ -176,6 +177,27 @@ function findVFSOrRoot(inputPath) {
   return { vfs, normalized };
 }
 
+/**
+ * Throws if `filename` is under the reserved VFS root but no layer mounted in
+ * this thread owns it. Each thread has its own mounts, so this is the case of
+ * a path a worker is handed into a VFS its parent mounted. Left to the native
+ * loader, such a path fails confusingly: on Windows, where the root sits under
+ * `\\.\nul`, the NUL device is found as the file and as an empty, invalid
+ * package.json above it.
+ * @param {string} filename
+ */
+function assertVFSPathMounted(filename) {
+  const normalized = normalizeMountedPath(filename);
+  const root = getNormalizedVfsRoot();
+  if (normalized !== root && !StringPrototypeStartsWith(normalized, root + sep)) {
+    return;
+  }
+  const layerId = getLayerIdFromPath(normalized);
+  if (layerId === -1 || !activeVFSLayers.has(layerId)) {
+    throw new ERR_VFS_NOT_MOUNTED(filename);
+  }
+}
+
 /**
  * Resolves a path string to the VFS that serves it for the fs functions,
  * or null for a path outside the reserved VFS root. Unlike the loader, the
@@ -1164,6 +1186,7 @@ function uninstallHooks() {
 }
 
 module.exports = {
+  assertVFSPathMounted,
   registerVFS,
   deregisterVFS,
 };

src/node_options.cc

@@ -319,6 +319,11 @@ void EnvironmentOptions::CheckOptions(std::vector<std::string>* errors,
 #ifndef DISABLE_SINGLE_EXECUTABLE_APPLICATION
   sea_vfs_archive = sea::IsSingleExecutable() &&
                     sea::FindSingleExecutableResource().use_vfs_archive();
+  // Without an archive, the VFS serves the assets themselves, and takes the
+  // mount point reserved for them.
+  sea_vfs_assets = sea::IsSingleExecutable() &&
+                   sea::FindSingleExecutableResource().use_vfs() &&
+                   !sea_vfs_archive;
   // The archive takes the mount point reserved for the --vfs-load source.
   if (!vfs_load_source.empty() && sea_vfs_archive) {
     errors->push_back(
@@ -828,6 +833,7 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
   AddOption("[vfs_load_set]", "", BOOL_FIELD(vfs_load));
   Implies("--vfs-load", "[vfs_load_set]");
   AddOption("[sea_vfs_archive]", "", BOOL_FIELD(sea_vfs_archive));
+  AddOption("[sea_vfs_assets]", "", BOOL_FIELD(sea_vfs_assets));
   AddOption("--experimental-quic",
 #ifndef OPENSSL_NO_QUIC
             "experimental QUIC support",

src/node_options.h

@@ -218,6 +218,7 @@ class EnvironmentOptions : public Options {
   DEFINE_BOOL_FIELD(experimental_vfs) = true;
   DEFINE_BOOL_FIELD(vfs_load) = false;
   DEFINE_BOOL_FIELD(sea_vfs_archive) = false;
+  DEFINE_BOOL_FIELD(sea_vfs_assets) = false;
   DEFINE_BOOL_FIELD(webstorage) = HAVE_SQLITE;
   DEFINE_BOOL_FIELD(experimental_dtls) = EXPERIMENTALS_DEFAULT_VALUE;
   DEFINE_BOOL_FIELD(experimental_quic) = EXPERIMENTALS_DEFAULT_VALUE;

src/node_sea.cc

@@ -250,6 +250,10 @@ bool SeaResource::use_code_cache() const {
   return static_cast<bool>(flags & SeaFlags::kUseCodeCache);
 }
 
+bool SeaResource::use_vfs() const {
+  return static_cast<bool>(flags & SeaFlags::kEnableVfs);
+}
+
 bool SeaResource::use_vfs_archive() const {
   return static_cast<bool>(flags & SeaFlags::kVfsArchive);
 }