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.

Since the load happens inside the constructor, the image never
outlives the call: nothing is left for dlclose() to clean up and no
temporary file lingers on POSIX. The AddonImage materializer moves
from an anonymous namespace in node_binding.cc to node_binding.h so
that node_ffi.cc can reuse it.

Signed-off-by: Matteo Collina <hello@matteocollina.com>

Author: mcollina

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

@@ -976,6 +976,30 @@ function installAddonLoader() {
   };
 }
 
+/**
+ * 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.
  */
@@ -985,6 +1009,8 @@ function installHooks() {
   normalizedVfsRootPrefix = getNormalizedVfsRoot() + sep;
   installModuleLoaderOverrides();
   installAddonLoader();
+  const { setVfsLibraryReader } = require('internal/ffi/vfs');
+  setVfsLibraryReader(readVirtualBinary);
   vfsHandlerObj = createVfsHandlers();
   setVfsHandlers(vfsHandlerObj);
   hooksInstalled = true;
@@ -1002,6 +1028,8 @@ function uninstallHooks() {
   setLoaderOverrides();
   setVfsHandlers(null);
   vfsHandlerObj = undefined;
+  const { setVfsLibraryReader } = require('internal/ffi/vfs');
+  setVfsLibraryReader(null);
   process.dlopen = originalDlopen;
   hooksInstalled = false;
 }

src/node_binding.cc

@@ -9,6 +9,7 @@
 #include "util.h"
 
 #include <string>
+#include <utility>
 #include <vector>
 
 #ifdef _WIN32
@@ -474,64 +475,29 @@ int NodeMemfdCreate(const char* name, unsigned int flags) {
   return static_cast<int>(syscall(SYS_memfd_create, name, flags));
 }
 #endif  // __linux__
+#else  // _WIN32
+
+// Delete-on-close handles kept alive until process exit so their temp files
+// outlive the loaded DLLs and are removed once the process ends.
+Mutex g_retained_addon_handles_mutex;
+std::vector<HANDLE>* g_retained_addon_handles = nullptr;
+
 #endif  // !_WIN32
 
-// Materializes native-addon bytes into a form dlopen()/LoadLibrary() can load,
-// with the smallest, most private on-disk footprint each platform allows:
-//   Linux:        an anonymous in-memory memfd, loaded via /proc/self/fd/N -
-//                 the bytes never touch the filesystem.
-//   other POSIX:  a 0700 mkdtemp() directory plus an O_EXCL|O_NOFOLLOW file,
-//                 unlink()ed right after the load (the mapping keeps it alive).
-//   Windows:      a temp file opened FILE_FLAG_DELETE_ON_CLOSE; its handle is
-//                 retained for the process lifetime so the file is removed
-//                 automatically once the process (and the loaded DLL) exit.
-// Used for an addon that lives somewhere dlopen() cannot open by path, such as
-// a virtual file system.
-class AddonImage {
- public:
-  AddonImage() = default;
-  ~AddonImage();
-  AddonImage(const AddonImage&) = delete;
-  AddonImage& operator=(const AddonImage&) = delete;
-
-  // The directory a temporary image would be written to, with a trailing
-  // separator; empty when it cannot be determined. Names the resource for the
-  // file-system permission check.
-  static std::string TempDir();
-
-  // On success sets path() to a real, loadable path for `data`.
-  bool Materialize(const char* data, size_t len);
-  const std::string& path() const { return path_; }
-  const std::string& errmsg() const { return errmsg_; }
-
-  // Call exactly once, right after DLib::Open(); `opened` says whether the load
-  // succeeded. Releases the transient resources that are no longer needed (a
-  // successful load holds its own mapping): on POSIX closes the memfd or
-  // unlinks the temp file; on Windows retains the delete-on-close handle for
-  // the process lifetime when opened, or closes it (deleting the file) on
-  // failure.
-  void AfterOpen(bool opened);
+}  // namespace
 
- private:
-  std::string path_;
-  std::string errmsg_;
-  bool consumed_ = false;
+// AddonImage is declared in node_binding.h so that the other loader of
+// dynamically shared objects, node_ffi.cc, can reuse it; see the header for
+// the platform-by-platform description.
+
+AddonImage::AddonImage() {
 #ifdef _WIN32
-  HANDLE handle_ = INVALID_HANDLE_VALUE;
-#else
-  bool MaterializeTempFile(const char* data, size_t len);
-  int fd_ = -1;
-  std::string temp_dir_;  // non-empty only for the temp-file (non-memfd) path
+  handle_ = INVALID_HANDLE_VALUE;
 #endif
-};
+}
 
 #ifdef _WIN32
 
-// Delete-on-close handles kept alive until process exit so their temp files
-// outlive the loaded DLLs and are removed once the process ends.
-Mutex g_retained_addon_handles_mutex;
-std::vector<HANDLE>* g_retained_addon_handles = nullptr;
-
 // static
 std::string AddonImage::TempDir() {
   wchar_t dir[MAX_PATH + 1];
@@ -730,8 +696,6 @@ AddonImage::~AddonImage() {
 
 #endif  // _WIN32
 
-}  // namespace
-
 // Shared by process.dlopen() and the internal dlopenBinary(). `allow_binary`
 // says whether args[3] may carry the addon's bytes; it is false for
 // process.dlopen(), whose signature stays (module, filename[, flags]).
@@ -928,6 +892,7 @@ void DLOpenBinary(const FunctionCallbackInfo<Value>& args) {
   DLOpenImpl(args, true);
 }
 
+
 inline struct node_module* FindModule(struct node_module* list,
                                       const char* name,
                                       int flag) {

src/node_binding.h

@@ -7,6 +7,8 @@
 #include <dlfcn.h>
 #endif
 
+#include <string>
+
 #include "node.h"
 #include "node_api.h"
 #include "quic/guard.h"
@@ -170,6 +172,58 @@ void GetLinkedBinding(const v8::FunctionCallbackInfo<v8::Value>& args);
 void DLOpen(const v8::FunctionCallbackInfo<v8::Value>& args);
 void DLOpenBinary(const v8::FunctionCallbackInfo<v8::Value>& args);
 
+// Materializes the bytes of a dynamically shared object into a form
+// dlopen()/LoadLibrary() can load, with the smallest, most private on-disk
+// footprint each platform allows:
+//   Linux:        an anonymous in-memory memfd, loaded via /proc/self/fd/N -
+//                 the bytes never touch the filesystem.
+//   other POSIX:  a 0700 mkdtemp() directory plus an O_EXCL|O_NOFOLLOW file,
+//                 unlink()ed right after the load (the mapping keeps it alive).
+//   Windows:      a temp file opened FILE_FLAG_DELETE_ON_CLOSE; its handle is
+//                 retained for the process lifetime so the file is removed
+//                 automatically once the process (and the loaded DLL) exit.
+// Used for a native addon or an FFI library that lives somewhere the dynamic
+// loader cannot open by path, such as a virtual file system. Call exactly one
+// of Materialize()+AfterOpen() around the load; a destroyed image that never
+// reached AfterOpen() cleans up after itself.
+class AddonImage {
+ public:
+  AddonImage();
+  ~AddonImage();
+  AddonImage(const AddonImage&) = delete;
+  AddonImage& operator=(const AddonImage&) = delete;
+
+  // The directory a temporary image would be written to, with a trailing
+  // separator; empty when it cannot be determined. Names the resource for the
+  // file-system permission check.
+  static std::string TempDir();
+
+  // On success sets path() to a real, loadable path for `data`.
+  bool Materialize(const char* data, size_t len);
+  const std::string& path() const { return path_; }
+  const std::string& errmsg() const { return errmsg_; }
+
+  // Call exactly once, right after the load; `opened` says whether the load
+  // succeeded. Releases the transient resources that are no longer needed (a
+  // successful load holds its own mapping): on POSIX closes the memfd or
+  // unlinks the temp file; on Windows retains the delete-on-close handle for
+  // the process lifetime when opened, or closes it (deleting the file) on
+  // failure.
+  void AfterOpen(bool opened);
+
+ private:
+  std::string path_;
+  std::string errmsg_;
+  bool consumed_ = false;
+#ifdef _WIN32
+  void* handle_;  // HANDLE; void* keeps windows.h out of this header
+#else
+  bool MaterializeTempFile(const char* data, size_t len);
+  int fd_ = -1;
+  std::string temp_dir_;
+#endif
+};
+
 }  // namespace binding
 
 }  // namespace node