ffi: load libraries from a mounted VFS

The operating system's dynamic loader cannot open a library that lives
in a mounted virtual file system: the reserved mount path has no real
inode. Native addons already handle this in require(): the loader
hands their bytes to process.dlopen(), which loads them from a
private, self-cleaning image - an anonymous in-memory memfd on Linux.

Make ffi.dlopen() and new DynamicLibrary() do the same transparently.
Mirroring the fs handler integration, the VFS hook installer sets a
library reader into node:ffi while at least one VFS is mounted and
clears it when the last one unmounts; DynamicLibrary consults it
before every load, so the dependency points from the VFS into ffi and
ffi never loads any VFS code. The reader hands the library's bytes to
the native constructor, which loads them from the same kind of image,
released right after the load, while library.path keeps reporting the
virtual path. Libraries on the real file system are unaffected and
load directly, and pay only a null check while no VFS is mounted.

The AddonImage materializer moves from an anonymous namespace in
node_binding.cc to node_binding.h so that node_ffi.cc can reuse it.
On Windows the image is now written and closed before the load,
because the loader shares read alone and a retained writable
delete-on-close handle failed the load with ERROR_SHARING_VIOLATION;
since a mapped image cannot be unlinked there, it is kept with the
module it loaded as and both are released at process exit. On POSIX
the image still never outlives the constructor call, so nothing is
left for dlclose() to clean up.

Also fix the VFS dlopen hook forwarding a missing flags argument as
undefined, which process.dlopen() coerces to 0 - not a valid
dlopen(2) mode - so loading any addon from the real file system
failed with EINVAL while a VFS was mounted.

Co-authored-by: Philipp Dunkel <pipobscure@users.noreply.github.com>
Signed-off-by: Matteo Collina <hello@matteocollina.com>
PR-URL: #65909
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: James M Snell <jasnell@gmail.com>

Author: 2 people

doc/api/ffi.md

@@ -210,6 +210,11 @@ const path = `libsqlite3.${suffix}`;
 
 <!-- YAML
 added: v26.1.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65909
+    description: Library paths inside a mounted virtual file system are now
+                 supported.
 -->
 
 * `path` {string|null} Path to a dynamic library, or `null` to resolve symbols
@@ -221,6 +226,13 @@ Loads a dynamic library and resolves the requested function definitions.
 
 On Windows passing `null` is not supported.
 
+A `path` inside a mounted [virtual file system][] is supported: the
+operating system's dynamic loader cannot open a virtual path, so the
+library's bytes are read from the VFS and loaded from a private,
+self-cleaning temporary image instead, while `lib.path` keeps reporting
+the virtual path. Libraries on the real file system are unaffected and
+load directly.
+
 When `definitions` is omitted, `functions` is returned as an empty object until
 symbols are resolved explicitly.
 
@@ -302,13 +314,24 @@ Represents a loaded dynamic library.
 
 ### `new DynamicLibrary(path)`
 
+<!-- YAML
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/65909
+    description: Library paths inside a mounted virtual file system are now
+                 supported.
+-->
+
 * `path` {string|null} Path to a dynamic library, or `null` to resolve symbols
   from the current process image.
 
 Loads the dynamic library without resolving any functions eagerly.
 
 On Windows passing `null` is not supported.
 
+A `path` inside a mounted [virtual file system][] loads the same way as
+with [`ffi.dlopen()`][].
+
 ```cjs
 const { DynamicLibrary, suffix } = require('node:ffi');
 
@@ -798,7 +821,9 @@ and keep callback and pointer lifetimes explicit on the native side.
 
 [Permission Model]: permissions.md#permission-model
 [`--allow-ffi`]: cli.md#--allow-ffi
+[`ffi.dlopen()`]: #ffidlopenpath-definitions
 [`ffi.toBuffer(pointer, length, copy)`]: #ffitobufferpointer-length-copy
 [`library.functions`]: #libraryfunctions
 [`using`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/using
 [type names]: #type-names
+[virtual file system]: vfs.md

doc/api/vfs.md

@@ -425,6 +425,12 @@ addon's bytes are read from the VFS and loaded from a private, self-cleaning
 temporary image instead. Addons on the real file system are unaffected and
 load directly.
 
+Shared libraries opened through [`ffi.dlopen()`][] (or
+[`new ffi.DynamicLibrary()`][]) work the same way: a library path inside a
+mounted VFS is detected, its bytes are read from the VFS, and the library is
+loaded from a private, self-cleaning image while `library.path` keeps
+reporting the virtual path. Libraries on the real file system load directly.
+
 ## Use with Single Executable Applications
 
 When running as a [Single Executable Application][] built with
@@ -634,9 +640,11 @@ fields use synthetic but stable values:
 [`VirtualFileSystem`]: #class-virtualfilesystem
 [`VirtualProvider`]: #class-virtualprovider
 [`ZipProvider`]: #class-zipprovider
+[`ffi.dlopen()`]: ffi.md#ffidlopenpath-definitions
 [`fs.BigIntStats`]: fs.md#class-fsstats
 [`fs.Stats`]: fs.md#class-fsstats
 [`import.meta.resolve()`]: esm.md#importmetaresolvespecifier
+[`new ffi.DynamicLibrary()`]: ffi.md#new-dynamiclibrarypath
 [`node:fs`]: fs.md
 [`require()`]: modules.md#requireid
 [`require.resolve()`]: modules.md#requireresolverequest-options

lib/ffi.js

@@ -9,6 +9,7 @@ const {
   ObjectGetOwnPropertyDescriptor,
   ObjectKeys,
   ObjectPrototypeToString,
+  ReflectConstruct,
   SafeWeakMap,
   SafeWeakRef,
   SymbolDispose,
@@ -38,7 +39,7 @@ const {
 emitExperimentalWarning('FFI');
 
 const {
-  DynamicLibrary,
+  DynamicLibrary: NativeDynamicLibrary,
   getInt8,
   getUint8,
   getInt16,
@@ -119,6 +120,37 @@ function wrapFFIFunction(rawFn, owner) {
   return wrapped;
 }
 
+const { getVfsLibraryReader } = require('internal/ffi/vfs');
+
+// A thin constructor in front of the native class so that a library inside
+// a mounted virtual file system loads transparently: its bytes are read
+// from the VFS and handed to the native constructor, which loads them from
+// a private, self-cleaning image - the same way require() handles a native
+// addon in a VFS. The reader is installed by the VFS while it is mounted
+// (see internal/ffi/vfs), so no VFS code is ever loaded from here. The
+// wrapper shares the native prototype, so instances and instanceof behave
+// as if the native class were exposed directly.
+function DynamicLibrary(path) {
+  if (new.target === undefined) {
+    // Let the native constructor produce its usual error.
+    return FunctionPrototypeCall(NativeDynamicLibrary, this, path);
+  }
+  const readVirtualLibrary = getVfsLibraryReader();
+  const binary =
+    readVirtualLibrary === null || typeof path !== 'string' ?
+      undefined : readVirtualLibrary(path);
+  return ReflectConstruct(NativeDynamicLibrary,
+                          binary === undefined ? [path] : [path, binary],
+                          new.target);
+}
+DynamicLibrary.prototype = NativeDynamicLibrary.prototype;
+ObjectDefineProperty(DynamicLibrary.prototype, 'constructor', {
+  __proto__: null,
+  configurable: true,
+  value: DynamicLibrary,
+  writable: true,
+});
+
 const rawGetFunction = DynamicLibrary.prototype.getFunction;
 const rawGetFunctions = DynamicLibrary.prototype.getFunctions;
 const rawClose = DynamicLibrary.prototype.close;

lib/internal/ffi/vfs.js

@@ -0,0 +1,27 @@
+'use strict';
+
+// Seam between node:ffi and the virtual file system, mirroring the fs
+// handler integration in internal/fs/utils: the VFS hook installer sets a
+// library reader while at least one VFS is mounted and clears it when the
+// last one unmounts, and DynamicLibrary consults it before every load. The
+// dependency points from the VFS into ffi: ffi never loads any VFS code,
+// and pays only a null check while no VFS is mounted.
+
+// When reader is null, no VFS is active (zero overhead). Otherwise it is
+// (path) => Buffer|undefined: the library's bytes for a path inside a
+// mounted VFS, or undefined for a path the dynamic loader should open
+// itself.
+let vfsLibraryReader = null;
+
+function setVfsLibraryReader(reader) {
+  vfsLibraryReader = reader;
+}
+
+function getVfsLibraryReader() {
+  return vfsLibraryReader;
+}
+
+module.exports = {
+  getVfsLibraryReader,
+  setVfsLibraryReader,
+};

lib/internal/vfs/setup.js

@@ -968,10 +968,38 @@ function installAddonLoader() {
       const { dlopenBinary } = internalBinding('process_methods');
       return dlopenBinary(module, filename, flags, readFileSync(filename));
     }
+    // Do not forward a missing flags argument as `undefined`:
+    // process.dlopen() coerces it to 0, which is not a valid dlopen(2)
+    // mode, instead of applying the default flags.
+    if (flags === undefined) return originalDlopen(module, filename);
     return originalDlopen(module, filename, flags);
   };
 }
 
+/**
+ * Reads the bytes of a file that lives in a mounted VFS. Returns undefined
+ * for a path outside the reserved VFS root - the caller should open the
+ * path itself - and throws ENOENT for a path under the root that no
+ * mounted VFS serves, since no real file can exist there. Installed into
+ * node:ffi while hooks are installed, so DynamicLibrary can load a
+ * VFS-resident library from a private image, the same way the module
+ * loader handles a native addon in a VFS.
+ * @param {string} pathStr The path of the library
+ * @returns {Buffer|undefined} The library's bytes, or undefined
+ */
+function readVirtualBinary(pathStr) {
+  const normalized = normalizeMountedPath(pathStr);
+  if (!StringPrototypeStartsWith(normalized, normalizedVfsRootPrefix)) {
+    return undefined;
+  }
+  const layerId = getLayerIdFromPath(normalized);
+  const vfs = layerId === -1 ? undefined : activeVFSLayers.get(layerId);
+  if (vfs === undefined || !vfs.shouldHandleNormalized(normalized)) {
+    throw createENOENT('open', pathStr);
+  }
+  return vfs.readFileSync(normalized);
+}
+
 /**
  * Install all VFS hooks: module loader overrides and fs handlers.
  */
@@ -981,6 +1009,8 @@ function installHooks() {
   normalizedVfsRootPrefix = getNormalizedVfsRoot() + sep;
   installModuleLoaderOverrides();
   installAddonLoader();
+  const { setVfsLibraryReader } = require('internal/ffi/vfs');
+  setVfsLibraryReader(readVirtualBinary);
   vfsHandlerObj = createVfsHandlers();
   setVfsHandlers(vfsHandlerObj);
   hooksInstalled = true;
@@ -998,6 +1028,8 @@ function uninstallHooks() {
   setLoaderOverrides();
   setVfsHandlers(null);
   vfsHandlerObj = undefined;
+  const { setVfsLibraryReader } = require('internal/ffi/vfs');
+  setVfsLibraryReader(null);
   process.dlopen = originalDlopen;
   hooksInstalled = false;
 }