ffi: load libraries from a mounted VFS

[mcollina]

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.

This makes ffi.dlopen() and new ffi.DynamicLibrary() do the same, transparently:

const ffi = require('node:ffi');
const path = require('node:path');

// mountPoint is a mounted VFS (or a SEA useVfs mount).
const { lib, functions } = ffi.dlopen(
  path.join(mountPoint, `mylib.${ffi.suffix}`),
  { add: { arguments: ['i32', 'i32'], return: 'i32' } },
);

• Mirroring the fs handler integration (setVfsHandlers), 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, 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 private image (AddonImage, moved from an anonymous namespace in node_binding.cc to node_binding.h so node_ffi.cc can reuse it). library.path keeps reporting the virtual path.
• Because the load happens inside the constructor, the image never outlives the call: it is unlinked right after uv_dlopen() on POSIX (in-memory memfd on Linux, so nothing touches the file system at all), and there is nothing left for dlclose() to clean up or reference-count. Windows retains the delete-on-close handle for the process lifetime, exactly as for addons.
• Libraries on the real file system are unaffected and load directly; while no VFS is mounted the cost is a null check.
• Loading from bytes requires file-system write permission for the temp directory on top of the FFI permission, mirroring dlopenBinary().

Bug fix included

Writing the test exposed a pre-existing bug, fixed in the first commit: the dlopen hook installed while a VFS is mounted always forwarded its flags parameter, so a two-argument process.dlopen() call for a real file-system path reached the original implementation with undefined as the flags. That coerces to 0, which is not a valid dlopen(2) mode, and loading any addon from the real file system failed with EINVAL while a VFS was mounted.

[pipobscure]

LETM (Looks Excellent To Me 😃 )

[pipobscure]

The only question I have is whether we want to hide the detail that the path may need materializing inside ffi.load like we did for process.dlopen. There are pro & cons for both. And maybe someone that is using FFI is the kind of person good with handling this manually. However this is also the kind of thing that's easy to forget to do (especially if you don't think of VFS as an option). So hiding it inside ffi.load would eliminate this fault category.

And since node:ffi has both dlopen and dlclose we even have a good place to put it and do reference counting. Making a library Symbol.disposable can call dlclose which would decrement the counter on the path and on the last close we can delete the file. And then just cleanup leftovers atexit.

[mcollina]

@pipobscure updated, PTAL

[codecov]

Codecov Report

❌ Patch coverage is 88.03419% with 14 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.16%. Comparing base (2987a59) to head (17f29b3).
⚠️ Report is 94 commits behind head on main.

Files with missing lines	Patch %	Lines
src/node_ffi.cc	50.00%	6 Missing and 3 partials ⚠️
lib/internal/vfs/setup.js	87.50%	2 Missing and 2 partials ⚠️
src/node_binding.h	80.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65909      +/-   ##
==========================================
- Coverage   90.16%   90.16%   -0.01%     
==========================================
  Files         771      773       +2     
  Lines      265097   265578     +481     
  Branches    50358    50488     +130     
==========================================
+ Hits       239026   239453     +427     
- Misses      17011    17070      +59     
+ Partials     9060     9055       -5     

Files with missing lines	Coverage Δ
lib/ffi.js	96.37% <100.00%> (+0.30%)	⬆️
lib/internal/ffi/vfs.js	100.00% <100.00%> (ø)
src/node_binding.cc	70.63% <100.00%> (-0.13%)	⬇️
src/node_binding.h	80.00% <80.00%> (ø)
lib/internal/vfs/setup.js	87.88% <87.50%> (+0.08%)	⬆️
src/node_ffi.cc	71.47% <50.00%> (-0.39%)	⬇️

... and 69 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pipobscure]

Awesome stuff! => LGTM

[github-actions]

Failed to start CI

- Validating Jenkins credentials
✔  Jenkins credentials valid
- Querying data for job/node-test-pull-request/77322/
SyntaxError: Unexpected token '<', ..."    
  https://github.com/nodejs/node/actions/runs/34634996295

[github-actions]

Failed to start CI

- Validating Jenkins credentials
✔  Jenkins credentials valid
- Querying data for job/node-test-pull-request/77322/
SyntaxError: Unexpected token '<', ..."    
  https://github.com/nodejs/node/actions/runs/34647251003

[github-actions]

Failed to start CI

- Validating Jenkins credentials
✔  Jenkins credentials valid
- Querying data for job/node-test-pull-request/77322/
SyntaxError: Unexpected token '<', ..."    
  https://github.com/nodejs/node/actions/runs/34648712529

[github-actions]

Failed to start CI

- Validating Jenkins credentials
✔  Jenkins credentials valid
- Querying data for job/node-test-pull-request/77322/
SyntaxError: Unexpected token '<', ..."    
  https://github.com/nodejs/node/actions/runs/34683737619

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/77407/

[saitanallensantiago26-beep]

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.

This makes ffi.dlopen() and new ffi.DynamicLibrary() do the same, transparently:

const ffi = require('node:ffi');
const path = require('node:path');

// mountPoint is a mounted VFS (or a SEA useVfs mount).
const { lib, functions } = ffi.dlopen(
  path.join(mountPoint, `mylib.${ffi.suffix}`),
  { add: { arguments: ['i32', 'i32'], return: 'i32' } },
);

• Mirroring the fs handler integration (setVfsHandlers), 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, 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 private image (AddonImage, moved from an anonymous namespace in node_binding.cc to node_binding.h so node_ffi.cc can reuse it). library.path keeps reporting the virtual path.
• Because the load happens inside the constructor, the image never outlives the call: it is unlinked right after uv_dlopen() on POSIX (in-memory memfd on Linux, so nothing touches the file system at all), and there is nothing left for dlclose() to clean up or reference-count. Windows retains the delete-on-close handle for the process lifetime, exactly as for addons.
• Libraries on the real file system are unaffected and load directly; while no VFS is mounted the cost is a null check.
• Loading from bytes requires file-system write permission for the temp directory on top of the FFI permission, mirroring dlopenBinary().

Bug fix included

Writing the test exposed a pre-existing bug, fixed in the first commit: the dlopen hook installed while a VFS is mounted always forwarded its flags parameter, so a two-argument process.dlopen() call for a real file-system path reached the original implementation with undefined as the flags. That coerces to 0, which is not a valid dlopen(2) mode, and loading any addon from the real file system failed with EINVAL while a VFS was mounted.

[saitanallensantiago26-beep]

CI: https://ci.nodejs.org/job/node-test-pull-request/77309/