node:fs: pin the directory fd at opendir time

[robobun]

What

fs.opendir() / fs.opendirSync() now open a real directory descriptor and iterate entries through it, matching Node's uv_fs_opendir / uv_fs_readdir model.

Why

Previously the Dir handle was path-bound: opendir only did a stat check, and the first read() re-opened the path with readdirSync. Consequences verified against Node v26.3.0:

const dh = fs.opendirSync(R + "/d");        // node: openat(O_DIRECTORY); bun: statx only
fs.renameSync(R + "/d", R + "/old");
fs.mkdirSync(R + "/d");
fs.writeFileSync(R + "/d/REPLACEMENT", "");
while ((e = dh.readSync())) names.push(e.name);
// node: ["ORIGINAL"]   (reads the pinned inode)
// bun:  ["REPLACEMENT"] (re-opened the path)

• TOCTOU: rename-swapping the path (or retargeting a symlink) between opendir and read() made Bun iterate the new object; Node iterates the original.
• rm after opendir: Bun's read() threw ENOENT with syscall: 'scandir'; Node returns end-of-stream.
• Open-time errors deferred: opendirSync on an unreadable directory or at RLIMIT_NOFILE succeeded, deferring EACCES/EMFILE to the first read() as a scandir error instead of the opendir error Node throws.
• fd census: 40 held Dir handles pinned 0 fds in Bun, +40 in Node.

How

• New native opendir op (openat(O_DIRECTORY|O_RDONLY) on POSIX, NtCreateFile iterable on Windows) returns the fd with syscall: "opendir" on failure.
• New internal fdreaddir op reads entries from an already-open fd without closing it.
• Dir stores the real fd, reads through fdreaddir, and closes it on close()/closeSync(). Recursive iteration still goes by path (subdirectories must be opened individually), but the root is opened eagerly so open-time errors surface.
• A FinalizationRegistry closes the fd and emits Node's Closing directory handle on garbage collection warning when a Dir is collected without close(), so the newly-held descriptor can't leak (mirrors FileHandle).
• Linux/macOS directory iterators now treat ENOENT from getdents64 / __getdirentries64 on an unlinked but still-open directory as EOF. POSIX requires this and glibc's readdir() does the same, which is where Node gets its behavior. The FreeBSD iterator already handled it.

Verification

# before (system bun)
{"fdHeldByHandle":0,"entriesAfterSwap":["REPLACEMENT"]}
after-rm read threw ENOENT scandir
# after
{"fdHeldByHandle":1,"entriesAfterSwap":["ORIGINAL"]}
after-rm read -> null(end)

test/js/node/fs/dir.test.ts (28 pass), test-fs-opendir.js, and test/js/node/fs/fs.test.ts pass on Linux.

---

no test proof · iteration 2 · Platform-specific test(s) that do not run on this machine. Deferring to CI, which covers all platforms: test/js/node/fs/dir.test.ts

[coderabbitai]

Warning

Review limit reached

@robobun, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 16 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: a7e02c70-4d4b-45ad-86bb-61e74317bcc8

📥 Commits

Reviewing files that changed from the base of the PR and between 44f6469 and b0657d2.

📒 Files selected for processing (10)

• src/event_loop/ConcurrentTask.rs
• src/js/node/fs.promises.ts
• src/js/node/fs.ts
• src/runtime/dispatch.rs
• src/runtime/node/dir_iterator.rs
• src/runtime/node/node.classes.ts
• src/runtime/node/node_fs.rs
• src/runtime/node/node_fs_binding.rs
• src/sys/lib.rs
• test/js/node/fs/dir.test.ts

---

_{Comment @coderabbitai help to get the list of available commands.}

[robobun]

^{Updated 11:27 AM PT - Jul 26th, 2026}

❌ @robobun, your commit b0657d2 has 2 failures in Build #82484 (All Failures):

• 📦 Binary size — 12 over 0.50 MB

target	this build	canary: main #79916
		size	Δ
❌ bun-darwin-aarch64	58.13 MB	57.58 MB	+564.9 KB
❌ bun-darwin-x64	63.48 MB	62.95 MB	+544.5 KB
❌ bun-linux-aarch64	70.98 MB	70.42 MB	+576.0 KB
❌ bun-linux-x64	72.48 MB	71.95 MB	+544.0 KB
❌ bun-linux-aarch64-musl	64.88 MB	64.32 MB	+576.0 KB
❌ bun-linux-x64-musl	66.98 MB	66.45 MB	+544.0 KB
❌ bun-linux-aarch64-android	78.47 MB	77.97 MB	+512.0 KB
❌ bun-linux-x64-android	80.64 MB	80.10 MB	+545.2 KB
❌ bun-freebsd-x64	83.09 MB	82.56 MB	+544.0 KB
❌ bun-freebsd-aarch64	84.84 MB	84.31 MB	+544.0 KB
❌ bun-windows-x64	80.27 MB	79.70 MB	+582.0 KB
❌ bun-windows-aarch64	70.87 MB	70.34 MB	+542.5 KB

Add [skip size check] to the commit message if this increase is intentional.

• test/bake/deinitialization.test.ts - pid 1993 error: addresssanitizer on 🐧 13 x64-asan

---

🧪   To try this PR locally:

bunx bun-pr 35928

That installs a local version of the PR into your bun-35928 executable, so you can run:

bun-35928 --bun

[github-actions]

This PR may be a duplicate of:

1. Check if path exists before returning from opendirSync #17846 - Also fixes opendirSync not validating the directory at call time; a smaller draft-quality attempt that node:fs: pin the directory fd at opendir time #35928 fully supersedes

🤖 Generated with Claude Code

[robobun]

Heads up from #35931: with the constructor now doing this.#handle = handle unguarded, a userland new fs.Dir(<integer>, path).closeSync() would close that unrelated fd here too (the dirSetHandle path is fine, it's the public constructor that's the hole). The tests added in test/js/node/fs/dir.test.ts (new fs.Dir with a foreign integer handle) cover this and should keep passing after rebasing; easiest guard is probably to only close when the handle arrived via dirSetHandle.

[robobun]

CI status on b0657d2 (build 82484):

• test/js/node/fs/dir.test.ts (the new coverage) passes on every lane.
• binary-size is soft-failed with [skip size check]: the baseline is main build #79916 (ae4b17d), 12 commits behind this branch's base including node:quic on lsquic — Node v26 compat, HTTP/3 #32602 (node:quic), node:repl: replace the stub with Node v26.3.0's REPL — v26 readline stack, acorn recoverable-parse + top-level await, completion, history, --interactive (82 vendored upstream tests) #31827 (node:repl) and node:inspector: implement Profiler precise coverage and inspector.open() with a DevTools-protocol server #31823 (node:inspector). Other PRs branched from current main see the same ~550 KB delta (e.g. build 82225).
• Red lanes unrelated to this diff, reported for triage:
  • test/bake/deinitialization.test.ts on debian 13 x64-asan: ASAN heap-use-after-free on thread T6 in the bake dev server; not reproducible locally over 3 runs.
  • test-worker-message-port-transfer-terminate.js on debian 13 x64-asan (build 82447): JSC ExceptionScope::assertNoException during worker termination; not reproducible locally over 5 runs.
• The remaining [flaky] tests (bun-upgrade, webview-chrome, install security-scanner matrix) pass on retry and are unrelated.

The diff is green; ready for review.

[claude]

All six rounds of prior feedback have been addressed and this pass found nothing new, but I'd still like a human to sign off — this changes Dir from path-bound to owning a real fd, adds two native ops wired through the task-tag dispatch table, and touches the shared dir_iterator.rs ENOENT handling on Linux/macOS. The Windows open_dir_at_windows_a path is unverified locally per the PR description.

Checked this pass: readdir_with_entries does not close the caller-supplied fd (so fdreaddir correctly leaves ownership with Dir); the Windows iterator's RestartScan=TRUE on each fdreaddir is fine because the JS side caches #entries after one call; the ENOENT→EOF mapping in dir_iterator.rs applies to all iterator callers but matches glibc readdir() and the pre-existing FreeBSD branch.

Extended reasoning...

Overview

Reworks fs.opendir/fs.opendirSync from a path-bound stat check to Node's fd-bound model: a new native opendir op (openat(O_DIRECTORY|O_RDONLY|O_CLOEXEC) on POSIX, NtCreateFile iterable on Windows) returns a real fd stored on Dir, and a new internal fdreaddir op reads entries through it. Touches ten files across the event-loop task table (ConcurrentTask.rs, dispatch.rs), the fs binding surface (node_fs.rs, node_fs_binding.rs, node.classes.ts), the shared directory iterator (dir_iterator.rs), the syscall tag table (sys/lib.rs), the built-in JS Dir class (fs.ts, fs.promises.ts), and adds five new tests in dir.test.ts.

Security risks

None identified. The change narrows a TOCTOU window (path swap between opendir and read()) rather than opening one. O_CLOEXEC was added in an earlier round; the new fd is read-only and O_DIRECTORY-gated. No user-controlled data reaches size/index arithmetic.

Level of scrutiny

High. This is the commit where Dir gains ownership of a real OS resource, so every lifecycle exit (close/closeSync, dispose/asyncDispose, async-iterator finally, GC via FinalizationRegistry) had to be audited — and was, across six prior review rounds that landed the registry, the #owned guard, null-before-close ordering, and the > 2 guard removal. The dir_iterator.rs ENOENT→EOF change is a shared-helper edit that affects every directory iteration in the runtime, not just fs.Dir. The Windows branch calls open_dir_at_windows_a and relies on fs.closeSync accepting the resulting HANDLE; the author notes this was deferred to CI.

Other factors

The PR has been iterated extensively in response to review; all prior inline threads are resolved with fix commits, CI on 816de4e was green on every dir.test.ts lane, and the new tests cover the rename-swap TOCTOU, rm-after-open EOF, fd census, and GC-warning paths (the GC test was moved out of the !isPosix gate in b0657d2 so it now runs on Windows too). The remaining reason to defer is scope, not open concerns: cross-platform fd lifecycle changes in node:fs warrant a maintainer's eye even when clean.