vfs: drop --vfs-mount, keep --vfs-load alone by pipobscure · Pull Request #66162 · nodejs/node

pipobscure · 2026-09-20T14:46:31Z

vfs: drop --vfs-mount, pin the load mount point
--vfs-mount mounted a source without running it, and shared one ordered
list of sources with --vfs-load, so neither option could say which entry
it had contributed: the entry point was recovered from the position of
--vfs-load among the mounts, in a list NODE_OPTIONS could prepend to.
Nothing needs more than one mount from the command line: a program that
wants more can mount them itself through node:vfs, where it also gets
the instance.

Remove --vfs-mount, leaving --vfs-load with the single source it mounts
and runs, and reserve layer 0 for that source, numbering the file
systems a program mounts itself from 1. The source is then at the same
mount point in every thread, whatever else that thread mounts -
including a thread where a --require preload mounted a file system of
its own first - so a path into it stays valid in a worker.

A worker still does not run that entry point: it inherits the source but
not the decision to load from it. A worker created with its own execArgv
inherits neither, so the documentation now says that such a worker must
be given --experimental-vfs and --vfs-load again to run a script from
the mount, and that --experimental-vfs is also what makes node:vfs
available to the worker's own code.

ERR_VFS_INVALID_TARGET now names --vfs-load as the source's origin, and
the startup test moves to test-vfs-load.js, with the cases that covered
mounting without loading removed and cases for the reserved mount point
added.

nodejs-github-bot · 2026-09-20T14:46:36Z

Review requested:

@nodejs/config
@nodejs/startup

pipobscure · 2026-09-20T14:50:51Z

This is the alternate to #66119 so we can either have names for mounts, in which case --vfs-mount makes sense, or we go with this PR, which drops the idea of --vfs-mount entirely and just allows for --vfs-load.

@mcollina @jasnell @bakkot since you have been the most actively engaged on the topic and much more in tune with the philosophy of what should go into node-core, I'm asking for your guidance. I'm fine with either.

bakkot

Great, thanks, I think this ends up being a lot simpler/clearer.

pipobscure · 2026-09-21T10:35:06Z

I'm refactoring the reservation of layerId=0 into this branch and out of #66140. This way the two PRs are entirely independent of each other.

pipobscure · 2026-09-21T11:16:09Z

I'm refactoring the reservation of layerId=0 into this branch and out of #66140. This way the two PRs are entirely independent of each other. Plus I rebased on main and squashed.

pipobscure · 2026-09-21T11:27:03Z

Note: this refactor makes #66162 and #66140 are now entirel independent of each other

nodejs-github-bot · 2026-09-21T11:51:57Z

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

codecov · 2026-09-21T13:18:46Z

Codecov Report

❌ Patch coverage is 91.52542% with 5 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.27%. Comparing base (36dd044) to head (e86cbc1).
⚠️ Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/process/pre_execution.js	93.02%	3 Missing ⚠️
src/node.cc	0.00%	1 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #66162      +/-   ##
==========================================
- Coverage   90.29%   90.27%   -0.02%     
==========================================
  Files         790      790              
  Lines      272529   272495      -34     
  Branches    52031    52018      -13     
==========================================
- Hits       246083   246006      -77     
- Misses      16909    16954      +45     
+ Partials     9537     9535       -2

Files with missing lines	Coverage Δ
lib/internal/errors.js	`98.81% <100.00%> (ø)`
lib/internal/main/worker_thread.js	`95.02% <100.00%> (ø)`
lib/internal/vfs/file_system.js	`99.62% <100.00%> (+<0.01%)`	⬆️
lib/internal/vfs/provider_registry.js	`93.68% <100.00%> (ø)`
src/node_options.cc	`80.68% <ø> (-0.27%)`	⬇️
src/node_options.h	`95.63% <ø> (ø)`
src/node_worker.cc	`81.77% <ø> (ø)`
src/node.cc	`77.36% <0.00%> (+0.22%)`	⬆️
lib/internal/process/pre_execution.js	`96.67% <93.02%> (+0.91%)`	⬆️

... and 30 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 · 2026-09-21T17:23:04Z

I’m seeing the same three jobs fail on #66127, #66140 and #66162 and given I ran test on Linux, Mac and Windows, I’m assuming it’s not related to these PRs. Could someone have a look.

pipobscure · 2026-09-22T07:56:45Z

I have rebased on latest main in order to include:

Ref: 20b3a69
Ref: 3f76564
Ref: 194eb69

Which were merged last night and hopefully deflake tests.

If someone can verify them and retrigger CI, I'd appreciate it.

--vfs-mount mounted a source without running it, and shared one ordered list of sources with --vfs-load, so neither option could say which entry it had contributed: the entry point was recovered from the position of --vfs-load among the mounts, in a list NODE_OPTIONS could prepend to. Nothing needs more than one mount from the command line: a program that wants more can mount them itself through node:vfs, where it also gets the instance. Remove --vfs-mount, leaving --vfs-load with the single source it mounts and runs, and reserve layer 0 for that source, numbering the file systems a program mounts itself from 1. The source is then at the same mount point in every thread, whatever else that thread mounts - including a thread where a --require preload mounted a file system of its own first - so a path into it stays valid in a worker. A worker still does not run that entry point: it inherits the source but not the decision to load from it. A worker created with its own execArgv inherits neither, so the documentation now says that such a worker must be given --experimental-vfs and --vfs-load again to run a script from the mount, and that --experimental-vfs is also what makes node:vfs available to the worker's own code. ERR_VFS_INVALID_TARGET now names --vfs-load as the source's origin, and the startup test moves to test-vfs-load.js, with the cases that covered mounting without loading removed and cases for the reserved mount point added. Signed-off-by: Philipp Dunkel <pip@pipobscure.com>

pipobscure · 2026-09-22T09:45:42Z

Rebased on latest main as there was a conflict that wanted resolving.

--vfs-load shipped in v26.10.0 (nodejs/node#65748), so that is now the floor: `engines` said >=26.0.0, which no version before 26.10 could satisfy for anything that mounts. Two things are also on their way out, and the code stops leaning on them now rather than when they go: * --vfs-mount is removed in the next patch release (nodejs/node#66162), which leaves --vfs-load as the one flag that mounts anything and reserves layer 0 for its source. Nothing here ran --vfs-mount any more; eleven comments still described it as the mechanism, and now describe --vfs-load instead. The recorder's note about several command-line mounts merging into one list goes with it — the command line mounts exactly one source now. * Named mounts are not going to happen (nodejs/node#66119, closed), and a mount point was never a caller's to choose either. The declaration said `mount(path?: PathLike)`; it is `mount(): string`, so the type stops offering an argument node will not take. Nothing here passed one. And a test the recorder was missing: the README's recipe end to end, a preload plus one real --vfs-load run, asserting that what the program read is listed and what it never touched is not. Every other recorder test mounts by hand, which checks the provider but never the flag and the preload meeting. Against the released v26.10.0: typecheck clean, 127 of 128 pass. The one that does not is sea.test.ts, which needs vfsArchive (#65810, not in 26.10) and says so from its build-time self-test.

… its way out README, HISTORY, the example's README, the slides and their checklist now say 26.10 rather than 'the next 26.x', drop --vfs-mount from everything but the note that explains its removal (nodejs/node#66162), record that layer 0 is the --vfs-load source's and that named mounts (#66119) were closed. The release workflow's header says what actually keeps it off now: it publishes.

mcollina

lgtm

nodejs-github-bot · 2026-09-22T14:57:27Z

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

nodejs-github-bot added lib / src Issues and PRs involving general changes in the lib/ or src/ directories. needs-ci PRs that need a full CI run. labels Sep 20, 2026

pipobscure mentioned this pull request Sep 20, 2026

vfs: make the reserved root readable through fs #66140

Open

pipobscure force-pushed the vfs-load-only branch from 1e49322 to 0abd2c8 Compare September 20, 2026 15:31

jasnell approved these changes Sep 20, 2026

View reviewed changes

bakkot reviewed Sep 20, 2026

View reviewed changes

Comment thread doc/api/cli.md Outdated

pipobscure marked this pull request as ready for review September 21, 2026 09:15

pipobscure mentioned this pull request Sep 21, 2026

vfs: add mount names #66119

Closed

pipobscure marked this pull request as draft September 21, 2026 10:33

pipobscure force-pushed the vfs-load-only branch from 1831297 to bd8627c Compare September 21, 2026 11:13

pipobscure marked this pull request as ready for review September 21, 2026 11:15

jasnell approved these changes Sep 21, 2026

View reviewed changes

jasnell added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Sep 21, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Sep 21, 2026

pipobscure mentioned this pull request Sep 21, 2026

vfs: support recursive readdir in ZipProvider #66127

Open

pipobscure force-pushed the vfs-load-only branch from bd8627c to 49f2d1f Compare September 22, 2026 07:56

pipobscure force-pushed the vfs-load-only branch from 49f2d1f to e86cbc1 Compare September 22, 2026 09:44

pipobscure requested a review from jasnell September 22, 2026 11:17

mcollina approved these changes Sep 22, 2026

View reviewed changes

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Sep 22, 2026

github-actions Bot removed the request-ci Add this label to start a Jenkins CI on a PR. Only starts once the PR has an approving review. label Sep 22, 2026

Uh oh!

Conversation

pipobscure commented Sep 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

nodejs-github-bot commented Sep 20, 2026

Uh oh!

pipobscure commented Sep 20, 2026

Uh oh!

bakkot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pipobscure commented Sep 21, 2026

Uh oh!

pipobscure commented Sep 21, 2026

Uh oh!

pipobscure commented Sep 21, 2026

Uh oh!

nodejs-github-bot commented Sep 21, 2026

Uh oh!

codecov Bot commented Sep 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pipobscure commented Sep 21, 2026

Uh oh!

pipobscure commented Sep 22, 2026

Uh oh!

pipobscure commented Sep 22, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

Uh oh!

nodejs-github-bot commented Sep 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

pipobscure commented Sep 20, 2026 •

edited

Loading

codecov Bot commented Sep 21, 2026 •

edited

Loading