vfs: close the fs hook gaps for mounted paths

Several `node:fs` entry points behave differently for a mounted path
than for a real one, because of how the call reaches the VFS hooks.
Make them behave as they do for a real path:

* Add the `watchFile`, `unwatchFile` and `promisesWatch` handlers,
  backed by the provider's stat watcher and async watcher; those calls
  threw a TypeError before. Have `watch` refuse a path that does not
  exist with ENOENT instead of handing back a watcher that polls
  forever and keeps the process alive.
* Convert timestamps and validate arguments before the hook runs in
  `utimes`, `lutimes` and `readdir` (sync, callback and promise forms),
  so a mounted path gets the same ERR_INVALID_ARG_* errors and the same
  seconds-since-epoch numbers as a real one.
* Pass the mode and times through to the `fchmod` and `futimes` hooks
  and route them to the handle's entry, so descriptor operations take
  effect like their path forms instead of being no-ops; the memory
  handle validates the way a FileHandle would since one calls it
  directly.
* Treat a `mkdtemp` prefix as text rather than a path when it ends in a
  separator, so the directory is created inside the intended parent.
* Map the first directory a recursive `mkdir` created back under the
  mount point instead of returning the provider-relative path.
* Make disposing an already closed virtual `Dir` a no-op, as on the
  native `Dir`, instead of rejecting with ERR_DIR_CLOSED.

test-vfs-fs-hook-gaps adds a test per gap, stating the real-fs outcome
as the expectation. The existing file handle test asserted that
`chmod()` and `utimes()` without arguments were no-ops; they now
validate and apply, so it exercises that instead.

Signed-off-by: Philipp Dunkel <pip@pipobscure.com>
PR-URL: #65852
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>

Author: pipobscure

lib/fs.js

@@ -1864,16 +1864,16 @@ function readdir(path, options, callback) {
     options = undefined;
   }
 
-  const h = vfsState.handlers;
-  if (h !== null && vfsResult(h.readdir(path, options), callback)) return;
-
   callback = makeCallback(callback);
   options = getOptions(options);
   path = getValidatedPath(path);
   if (options.recursive != null) {
     validateBoolean(options.recursive, 'options.recursive');
   }
 
+  const h = vfsState.handlers;
+  if (h !== null && vfsResult(h.readdir(path, options), callback)) return;
+
   if (options.recursive) {
     readdirRecursive(path, options, callback);
     return;
@@ -1910,17 +1910,18 @@ function readdir(path, options, callback) {
  * @returns {string | Buffer[] | Dirent[]}
  */
 function readdirSync(path, options) {
-  const h = vfsState.handlers;
-  if (h !== null) {
-    const result = h.readdirSync(path, options);
-    if (result !== undefined) return result;
-  }
   options = getOptions(options);
   path = getValidatedPath(path);
   if (options.recursive != null) {
     validateBoolean(options.recursive, 'options.recursive');
   }
 
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const result = h.readdirSync(path, options);
+    if (result !== undefined) return result;
+  }
+
   if (options.recursive) {
     return readdirSyncRecursive(path, options);
   }
@@ -2423,7 +2424,7 @@ function fchmod(fd, mode, callback) {
   callback = makeCallback(callback);
 
   const h = vfsState.handlers;
-  if (h !== null && vfsVoid(h.fchmod(fd), callback)) return;
+  if (h !== null && vfsVoid(h.fchmod(fd, mode), callback)) return;
 
   if (permission.isEnabled()) {
     callback(new ERR_ACCESS_DENIED('fchmod API is disabled when Permission Model is enabled.'));
@@ -2442,19 +2443,18 @@ function fchmod(fd, mode, callback) {
  * @returns {void}
  */
 function fchmodSync(fd, mode) {
+  mode = parseFileMode(mode, 'mode');
+
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.fchmodSync(fd);
+    const result = h.fchmodSync(fd, mode);
     if (result !== undefined) return;
   }
 
   if (permission.isEnabled()) {
     throw new ERR_ACCESS_DENIED('fchmod API is disabled when Permission Model is enabled.');
   }
-  binding.fchmod(
-    fd,
-    parseFileMode(mode, 'mode'),
-  );
+  binding.fchmod(fd, mode);
 }
 
 /**
@@ -2693,18 +2693,15 @@ function chownSync(path, uid, gid) {
 function utimes(path, atime, mtime, callback) {
   callback = makeCallback(callback);
   path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
 
   const h = vfsState.handlers;
   if (h !== null && vfsVoid(h.utimes(path, atime, mtime), callback)) return;
 
   const req = new FSReqCallback();
   req.oncomplete = callback;
-  binding.utimes(
-    path,
-    toUnixTimestamp(atime),
-    toUnixTimestamp(mtime),
-    req,
-  );
+  binding.utimes(path, atime, mtime, req);
 }
 
 /**
@@ -2717,18 +2714,16 @@ function utimes(path, atime, mtime, callback) {
  */
 function utimesSync(path, atime, mtime) {
   path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
 
   const h = vfsState.handlers;
   if (h !== null) {
     const result = h.utimesSync(path, atime, mtime);
     if (result !== undefined) return;
   }
 
-  binding.utimes(
-    path,
-    toUnixTimestamp(atime),
-    toUnixTimestamp(mtime),
-  );
+  binding.utimes(path, atime, mtime);
 }
 
 /**
@@ -2746,7 +2741,7 @@ function futimes(fd, atime, mtime, callback) {
   callback = makeCallback(callback);
 
   const h = vfsState.handlers;
-  if (h !== null && vfsVoid(h.futimes(fd), callback)) return;
+  if (h !== null && vfsVoid(h.futimes(fd, atime, mtime), callback)) return;
 
   if (permission.isEnabled()) {
     callback(new ERR_ACCESS_DENIED('futimes API is disabled when Permission Model is enabled.'));
@@ -2768,21 +2763,20 @@ function futimes(fd, atime, mtime, callback) {
  * @returns {void}
  */
 function futimesSync(fd, atime, mtime) {
+  atime = toUnixTimestamp(atime, 'atime');
+  mtime = toUnixTimestamp(mtime, 'mtime');
+
   const h = vfsState.handlers;
   if (h !== null) {
-    const result = h.futimesSync(fd);
+    const result = h.futimesSync(fd, atime, mtime);
     if (result !== undefined) return;
   }
 
   if (permission.isEnabled()) {
     throw new ERR_ACCESS_DENIED('futimes API is disabled when Permission Model is enabled.');
   }
 
-  binding.futimes(
-    fd,
-    toUnixTimestamp(atime, 'atime'),
-    toUnixTimestamp(mtime, 'mtime'),
-  );
+  binding.futimes(fd, atime, mtime);
 }
 
 /**
@@ -2797,18 +2791,15 @@ function futimesSync(fd, atime, mtime) {
 function lutimes(path, atime, mtime, callback) {
   callback = makeCallback(callback);
   path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
 
   const h = vfsState.handlers;
   if (h !== null && vfsVoid(h.lutimes(path, atime, mtime), callback)) return;
 
   const req = new FSReqCallback();
   req.oncomplete = callback;
-  binding.lutimes(
-    path,
-    toUnixTimestamp(atime),
-    toUnixTimestamp(mtime),
-    req,
-  );
+  binding.lutimes(path, atime, mtime, req);
 }
 
 /**
@@ -2821,18 +2812,16 @@ function lutimes(path, atime, mtime, callback) {
  */
 function lutimesSync(path, atime, mtime) {
   path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
 
   const h = vfsState.handlers;
   if (h !== null) {
     const result = h.lutimesSync(path, atime, mtime);
     if (result !== undefined) return;
   }
 
-  binding.lutimes(
-    path,
-    toUnixTimestamp(atime),
-    toUnixTimestamp(mtime),
-  );
+  binding.lutimes(path, atime, mtime);
 }
 
 function writeAll(fd, isUserFd, buffer, offset, length, signal, flush, callback) {

lib/internal/fs/promises.js

@@ -1725,17 +1725,18 @@ async function readdirRecursiveWithPermissionModel(basePath, options) {
 }
 
 async function readdir(path, options) {
-  const h = vfsState.handlers;
-  if (h !== null) {
-    const promise = h.readdir(path, options);
-    if (promise !== undefined) return await promise;
-  }
   options = getOptions(options);
 
   // Make shallow copy to prevent mutating options from affecting results
   options = copyObject(options);
 
   path = getValidatedPath(path);
+
+  const h = vfsState.handlers;
+  if (h !== null) {
+    const promise = h.readdir(path, options);
+    if (promise !== undefined) return await promise;
+  }
   if (options.recursive) {
     return readdirRecursive(path, options);
   }
@@ -2011,6 +2012,8 @@ async function chown(path, uid, gid) {
 
 async function utimes(path, atime, mtime) {
   path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
 
   const h = vfsState.handlers;
   if (h !== null) {
@@ -2019,12 +2022,7 @@ async function utimes(path, atime, mtime) {
   }
 
   return await PromisePrototypeThen(
-    binding.utimes(
-      path,
-      toUnixTimestamp(atime),
-      toUnixTimestamp(mtime),
-      kUsePromises,
-    ),
+    binding.utimes(path, atime, mtime, kUsePromises),
     undefined,
     handleErrorFromBinding,
   );
@@ -2044,19 +2042,18 @@ async function futimes(handle, atime, mtime) {
 }
 
 async function lutimes(path, atime, mtime) {
+  path = getValidatedPath(path);
+  atime = toUnixTimestamp(atime);
+  mtime = toUnixTimestamp(mtime);
+
   const h = vfsState.handlers;
   if (h !== null) {
     const promise = h.lutimes(path, atime, mtime);
     if (promise !== undefined) { await promise; return; }
   }
 
   return await PromisePrototypeThen(
-    binding.lutimes(
-      getValidatedPath(path),
-      toUnixTimestamp(atime),
-      toUnixTimestamp(mtime),
-      kUsePromises,
-    ),
+    binding.lutimes(path, atime, mtime, kUsePromises),
     undefined,
     handleErrorFromBinding,
   );

lib/internal/vfs/dir.js

@@ -94,10 +94,15 @@ class VirtualDir {
       this.closeSync();
     }
   }
+
+  async [SymbolAsyncDispose]() {
+    if (!this.#closed) {
+      this.closeSync();
+    }
+  }
 }
 
 VirtualDir.prototype[SymbolAsyncIterator] = VirtualDir.prototype.entries;
-VirtualDir.prototype[SymbolAsyncDispose] = VirtualDir.prototype.close;
 
 module.exports = {
   VirtualDir,

lib/internal/vfs/file_handle.js

@@ -20,6 +20,8 @@ const {
 const {
   createEBADF,
 } = require('internal/vfs/errors');
+const { stringToFlags, toUnixTimestamp } = require('internal/fs/utils');
+const { parseFileMode } = require('internal/validators');
 
 // Private symbols
 const kPath = Symbol('kPath');
@@ -29,7 +31,6 @@ const kPosition = Symbol('kPosition');
 const kClosed = Symbol('kClosed');
 const kAccess = Symbol('kAccess');
 
-const { stringToFlags } = require('internal/fs/utils');
 const {
   fs: { O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY },
 } = internalBinding('constants');
@@ -288,10 +289,17 @@ class VirtualFileHandle {
   }
 
   /**
-   * No-op chmod - VFS files don't have real permissions.
+   * @param {number} mode The new permission bits
+   */
+  chmodSync(mode) {}
+
+  /**
+   * @param {number} mode The new permission bits
    * @returns {Promise<void>}
    */
-  async chmod() {}
+  async chmod(mode) {
+    this.chmodSync(mode);
+  }
 
   /**
    * No-op chown - VFS files don't have real ownership.
@@ -300,10 +308,19 @@ class VirtualFileHandle {
   async chown() {}
 
   /**
-   * No-op utimes - timestamps are handled by the provider.
+   * @param {Date|number|string} atime The new access time
+   * @param {Date|number|string} mtime The new modification time
+   */
+  utimesSync(atime, mtime) {}
+
+  /**
+   * @param {Date|number|string} atime The new access time
+   * @param {Date|number|string} mtime The new modification time
    * @returns {Promise<void>}
    */
-  async utimes() {}
+  async utimes(atime, mtime) {
+    this.utimesSync(atime, mtime);
+  }
 
   /**
    * No-op datasync - VFS is in-memory.
@@ -681,6 +698,33 @@ class MemoryFileHandle extends VirtualFileHandle {
     throw new ERR_INVALID_STATE('stats not available');
   }
 
+  /**
+   * @param {number} mode The new permission bits
+   */
+  chmodSync(mode) {
+    this.#checkClosed('fchmod');
+    mode = parseFileMode(mode, 'mode');
+    if (this.#entry) {
+      this.#entry.mode = (this.#entry.mode & ~0o7777) | (mode & 0o7777);
+      this.#entry.ctime = DateNow();
+    }
+  }
+
+  /**
+   * @param {Date|number|string} atime The new access time
+   * @param {Date|number|string} mtime The new modification time
+   */
+  utimesSync(atime, mtime) {
+    this.#checkClosed('futimes');
+    const atimeMs = toUnixTimestamp(atime, 'atime') * 1000;
+    const mtimeMs = toUnixTimestamp(mtime, 'mtime') * 1000;
+    if (this.#entry) {
+      this.#entry.atime = atimeMs;
+      this.#entry.mtime = mtimeMs;
+      this.#entry.ctime = DateNow();
+    }
+  }
+
   /**
    * Gets file stats.
    * @param {object} [options] Options