sea,vfs: address review feedback from Joyee

- Make SEA VFS opt-in via `"useVfs": true` config field with
  corresponding `kEnableVfs` flag in C++ and `isVfsEnabled()` binding
- Replace manual VFS path resolution in embedderRequire with
  wrapModuleLoad() that flows through registered module hooks,
  supporting transitive requires
- Set main module filename to VFS path when VFS is active so
  relative require('./foo.js') resolves correctly
- Convert _-prefixed methods to # private in file_system.js
- Fix inaccurate code caching docs per reviewer suggestion
- Replace supported sync method list with unsupported method list
- Add native addon limitation note for VFS in SEA docs

Author: mcollina

doc/api/single-executable-applications.md

@@ -115,6 +115,7 @@ The configuration currently reads the following top-level fields:
   "disableExperimentalSEAWarning": true, // Default: false
   "useSnapshot": false,  // Default: false
   "useCodeCache": true, // Default: false
+  "useVfs": true, // Default: false
   "execArgv": ["--no-warnings", "--max-old-space-size=4096"], // Optional
   "execArgvExtension": "env", // Default: "env", options: "none", "env", "cli"
   "assets": {  // Optional
@@ -180,9 +181,10 @@ See documentation of the [`sea.getAsset()`][], [`sea.getAssetAsBlob()`][],
 
 Instead of using the `node:sea` API to access individual assets, you can use
 the Virtual File System (VFS) to access bundled assets through standard `fs`
-APIs. When running as a Single Executable Application, the VFS is automatically
-initialized and mounted at `/sea`. All assets defined in the SEA configuration
-are accessible through this virtual path.
+APIs. To enable VFS, set `"useVfs": true` in the SEA configuration. When
+enabled, the VFS is automatically initialized and mounted at `/sea`. All
+assets defined in the SEA configuration are accessible through this virtual
+path.
 
 ```cjs
 const fs = require('node:fs');
@@ -224,16 +226,27 @@ const myModule = require('/sea/lib/mymodule.js');
 const utils = require('/sea/utils/helpers.js');
 ```
 
-The SEA's `require()` function automatically detects VFS paths (paths starting
-with `/sea/`) and loads modules from the virtual file system.
+When `useVfs` is enabled, `require()` in the injected main script uses the
+registered module hooks to load modules from the virtual file system. This
+supports both absolute VFS paths and relative requires (e.g.,
+`require('./helper.js')` from a VFS module).
+
+When `useVfs` is enabled, `__filename` and `__dirname` in the injected main
+script reflect VFS paths (e.g., `/sea/main.js`) instead of
+[`process.execPath`][].
 
 #### Code caching limitations
 
 The `useCodeCache` option in the SEA configuration does not apply to modules
-loaded from the VFS. Code caching requires executing modules during the SEA
-build process to generate cached code, but VFS modules are only available at
-runtime after the SEA is built. If performance is critical, consider using
-`useCodeCache` for your main entry point and `useSnapshot` for initialization.
+loaded from the VFS. Consider bundling the application to enable code caching
+and do not rely on module loading in VFS.
+
+#### Native addon limitations
+
+Native addons (`.node` files) cannot be loaded directly from the VFS because
+`process.dlopen()` requires files on the real file system. To use native
+addons in a SEA with VFS, write the asset to a temporary file first. See
+[Using native addons in the injected main script][] for an example.
 
 ### Startup snapshot support
 
@@ -665,6 +678,7 @@ to help us document them.
 [Mach-O]: https://en.wikipedia.org/wiki/Mach-O
 [PE]: https://en.wikipedia.org/wiki/Portable_Executable
 [Windows SDK]: https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
+[Using native addons in the injected main script]: #using-native-addons-in-the-injected-main-script
 [`process.execPath`]: process.md#processexecpath
 [`require()`]: modules.md#requireid
 [`require.main`]: modules.md#accessing-the-main-module

doc/api/vfs.md

@@ -164,9 +164,9 @@ files exist only in memory.
 ### Code caching in SEA
 
 When using VFS with Single Executable Applications, the `useCodeCache` option
-in the SEA configuration does not apply to modules loaded from the VFS. Code
-caching requires executing modules during the SEA build process, but VFS
-modules are only available at runtime.
+in the SEA configuration does not apply to modules loaded from the VFS.
+Consider bundling the application to enable code caching and do not rely on
+module loading in VFS.
 
 ## `vfs.create([provider][, options])`
 
@@ -464,26 +464,19 @@ before VFS operations.
 
 #### Synchronous Methods
 
-* `vfs.accessSync(path[, mode])` - Check file accessibility
-* `vfs.appendFileSync(path, data[, options])` - Append to a file
-* `vfs.closeSync(fd)` - Close a file descriptor
-* `vfs.copyFileSync(src, dest[, mode])` - Copy a file
-* `vfs.existsSync(path)` - Check if path exists
-* `vfs.lstatSync(path[, options])` - Get file stats (no symlink follow)
-* `vfs.mkdirSync(path[, options])` - Create a directory
-* `vfs.openSync(path, flags[, mode])` - Open a file
-* `vfs.readdirSync(path[, options])` - Read directory contents
-* `vfs.readFileSync(path[, options])` - Read a file
-* `vfs.readlinkSync(path[, options])` - Read symlink target
-* `vfs.readSync(fd, buffer, offset, length, position)` - Read from fd
-* `vfs.realpathSync(path[, options])` - Resolve symlinks
-* `vfs.renameSync(oldPath, newPath)` - Rename a file or directory
-* `vfs.rmdirSync(path)` - Remove a directory
-* `vfs.statSync(path[, options])` - Get file stats
-* `vfs.symlinkSync(target, path[, type])` - Create a symlink
-* `vfs.unlinkSync(path)` - Remove a file
-* `vfs.writeFileSync(path, data[, options])` - Write a file
-* `vfs.writeSync(fd, buffer, offset, length, position)` - Write to fd
+The `VirtualFileSystem` class supports all common synchronous `fs` methods
+for reading, writing, and managing files and directories. Methods mirror the
+`fs` module API.
+
+The following `fs` sync methods have **no** VFS equivalent:
+
+* `chmodSync()` / `fchmodSync()` - VFS does not support permission changes
+* `chownSync()` / `fchownSync()` - VFS does not support ownership changes
+* `truncateSync()` / `ftruncateSync()` - Use `writeFileSync()` instead
+* `utimesSync()` / `futimesSync()` / `lutimesSync()` - VFS does not support
+  changing timestamps
+* `linkSync()` - VFS does not support hard links (use `symlinkSync()`)
+* `fdatasyncSync()` / `fsyncSync()` - Not applicable to in-memory storage
 
 #### Promise Methods
 
@@ -790,8 +783,9 @@ operations without file descriptor collisions.
 
 ## Use with Single Executable Applications
 
-When running as a Single Executable Application (SEA), bundled assets are
-automatically mounted at `/sea`. No additional setup is required:
+When running as a Single Executable Application (SEA) with `"useVfs": true` in
+the SEA configuration, bundled assets are automatically mounted at `/sea`. No
+additional setup is required:
 
 ```cjs
 // In your SEA entry script

lib/internal/main/embedding.js

@@ -12,7 +12,7 @@
 const {
   prepareMainThreadExecution,
 } = require('internal/process/pre_execution');
-const { isExperimentalSeaWarningNeeded, isSea } = internalBinding('sea');
+const { isExperimentalSeaWarningNeeded, isSea, isVfsEnabled } = internalBinding('sea');
 const { emitExperimentalWarning } = require('internal/util');
 const { emitWarningSync } = require('internal/process/warning');
 const { Module, wrapModuleLoad } = require('internal/modules/cjs/loader');
@@ -85,9 +85,16 @@ function embedderRunCjs(content, filename) {
   }
 
   // Patch the module to make it look almost like a regular CJS module
-  // instance.
-  customModule.filename = process.execPath;
-  customModule.paths = Module._nodeModulePaths(process.execPath);
+  // instance. When VFS is active, set the filename to a VFS path so that
+  // relative require('./foo.js') resolves under the VFS mount point.
+  if (seaVfsActive && seaVfsMountPoint) {
+    customModule.filename = seaVfsMountPoint + '/' + path.basename(filename);
+    customModule.paths = Module._nodeModulePaths(
+      path.dirname(customModule.filename));
+  } else {
+    customModule.filename = process.execPath;
+    customModule.paths = Module._nodeModulePaths(process.execPath);
+  }
   embedderRequire.main = customModule;
 
   // This currently returns what the wrapper returns i.e. if the code
@@ -99,8 +106,8 @@ function embedderRunCjs(content, filename) {
     customModule.exports,  // exports
     embedderRequire,       // require
     customModule,          // module
-    filename,              // __filename
-    customModule.path,     // __dirname
+    customModule.filename, // __filename
+    path.dirname(customModule.filename),  // __dirname
   );
 }
 
@@ -120,19 +127,20 @@ function warnNonBuiltinInSEA() {
 
 // Lazy-loaded SEA VFS support
 let seaVfsInitialized = false;
-let seaVfs = null;
+let seaVfsActive = false;
 let seaVfsMountPoint = null;
 
 function initSeaVfs() {
   if (seaVfsInitialized) return;
   seaVfsInitialized = true;
 
-  if (!isLoadingSea) return;
+  if (!isLoadingSea || !isVfsEnabled()) return;
 
   // Check if SEA has VFS support
   const { getSeaVfs } = require('internal/vfs/sea');
-  seaVfs = getSeaVfs();
+  const seaVfs = getSeaVfs();
   if (seaVfs) {
+    seaVfsActive = true;
     seaVfsMountPoint = seaVfs.mountPoint;
   }
 }
@@ -144,31 +152,14 @@ function embedderRequire(id) {
     return require(normalizedId);
   }
 
-  // Not a built-in module - check if it's a VFS path in SEA
-  if (isLoadingSea) {
-    initSeaVfs();
-
-    if (seaVfs && seaVfsMountPoint) {
-      // Check if the path is within the VFS mount point
-      // Support both absolute paths (/sea/...) and relative to mount point
-      let modulePath = id;
-      if (id.startsWith(seaVfsMountPoint) || id.startsWith('/')) {
-        // Absolute path - resolve within VFS
-        if (!id.startsWith(seaVfsMountPoint) && id.startsWith('/')) {
-          // Path like '/modules/foo.js' - prepend mount point
-          modulePath = seaVfsMountPoint + id;
-        }
-
-        // Check if the file exists in VFS
-        if (seaVfs.existsSync(modulePath)) {
-          // Use wrapModuleLoad to load the module with proper tracing/diagnostics
-          return wrapModuleLoad(modulePath, embedderRequire.main, false);
-        }
-      }
-    }
+  // When VFS is active, use wrapModuleLoad which flows through the
+  // registered Module.registerHooks({ resolve, load }) hooks in
+  // module_hooks.js, handling both absolute VFS paths and relative requires.
+  if (isLoadingSea && seaVfsActive) {
+    return wrapModuleLoad(id, embedderRequire.main, false);
   }
 
-  // No VFS or file not in VFS - show warning and throw
+  // No VFS - show warning and throw
   warnNonBuiltinInSEA();
   throw new ERR_UNKNOWN_BUILTIN_MODULE(id);
 }