fs: extend signal option to lstat, fstat and promises API

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

Author: mertcanaltin

doc/api/fs.md

@@ -1478,6 +1478,10 @@ link(2) documentation for more detail.
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v10.5.0
     pr-url: https://github.com/nodejs/node/pull/20220
     description: Accepts an additional `options` object to specify whether
@@ -1488,6 +1492,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the given
   symbolic link `path`.
 
@@ -1982,6 +1988,10 @@ Removes files and directories (modeled on the standard POSIX `rm` utility).
 <!-- YAML
 added: v10.0.0
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v25.7.0
     pr-url: https://github.com/nodejs/node/pull/61178
     description: Accepts a `throwIfNoEntry` option to specify whether
@@ -1999,6 +2009,8 @@ changes:
   * `throwIfNoEntry` {boolean} Whether an exception will be thrown
     if no file system entry exists, rather than returning `undefined`.
     **Default:** `true`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * Returns: {Promise}  Fulfills with the {fs.Stats} object for the
   given `path`.
 
@@ -3309,6 +3321,10 @@ exception are given to the completion callback.
 <!-- YAML
 added: v0.1.95
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3332,6 +3348,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * `callback` {Function}
   * `err` {Error}
   * `stats` {fs.Stats}
@@ -3673,6 +3691,10 @@ exception are given to the completion callback.
 <!-- YAML
 added: v0.1.30
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/57775
+    description: Accepts an additional `signal` option to allow aborting the
+                 operation.
   - version: v18.0.0
     pr-url: https://github.com/nodejs/node/pull/41678
     description: Passing an invalid callback to the `callback` argument
@@ -3700,6 +3722,8 @@ changes:
 * `options` {Object}
   * `bigint` {boolean} Whether the numeric values in the returned
     {fs.Stats} object should be `bigint`. **Default:** `false`.
+  * `signal` {AbortSignal} An AbortSignal to cancel the operation.
+    **Default:** `undefined`.
 * `callback` {Function}
   * `err` {Error}
   * `stats` {fs.Stats}

lib/fs.js

@@ -1584,7 +1584,7 @@ function readdirSync(path, options) {
  * Invokes the callback with the `fs.Stats`
  * for the file descriptor.
  * @param {number} fd
- * @param {{ bigint?: boolean; }} [options]
+ * @param {{ bigint?: boolean, signal?: AbortSignal }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
@@ -1595,19 +1595,24 @@ function fstat(fd, options = { bigint: false }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
+  } else if (options === null || typeof options !== 'object') {
+    options = kEmptyObject;
   }
   callback = makeStatsCallback(callback);
 
+  if (options.signal !== undefined) validateAbortSignal(options.signal, 'options.signal');
+  if (checkAborted(options.signal, callback)) return;
+
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
+  bindSignalToReq(req, options.signal, callback);
   binding.fstat(fd, options.bigint, req);
 }
 
 /**
  * Retrieves the `fs.Stats` for the symbolic link
  * referred to by the `path`.
  * @param {string | Buffer | URL} path
- * @param {{ bigint?: boolean; }} [options]
+ * @param {{ bigint?: boolean, signal?: AbortSignal }} [options]
  * @param {(
  *   err?: Error,
  *   stats?: Stats
@@ -1618,6 +1623,10 @@ function lstat(path, options = { bigint: false }, callback) {
   if (typeof options === 'function') {
     callback = options;
     options = kEmptyObject;
+  } else if (options === null || typeof options !== 'object') {
+    options = kEmptyObject;
+  } else {
+    options = getOptions(options, { bigint: false });
   }
   callback = makeStatsCallback(callback);
   path = getValidatedPath(path);
@@ -1627,8 +1636,11 @@ function lstat(path, options = { bigint: false }, callback) {
     return;
   }
 
+  if (options.signal !== undefined) validateAbortSignal(options.signal, 'options.signal');
+  if (checkAborted(options.signal, callback)) return;
+
   const req = new FSReqCallback(options.bigint);
-  req.oncomplete = callback;
+  bindSignalToReq(req, options.signal, callback);
   binding.lstat(path, options.bigint, req);
 }
 

lib/internal/fs/promises.js

@@ -14,6 +14,7 @@ const {
   PromiseResolve,
   SafeArrayIterator,
   SafePromisePrototypeFinally,
+  SafePromiseRace,
   Symbol,
   SymbolAsyncDispose,
   SymbolAsyncIterator,
@@ -125,6 +126,7 @@ const kLocked = Symbol('kLocked');
 const kCloseSync = Symbol('kCloseSync');
 
 const { kUsePromises } = binding;
+let kResistStopPropagation;
 const { Interface } = require('internal/readline/interface');
 const {
   kDeserialize, kTransfer, kTransferList, markTransferMode,
@@ -1116,6 +1118,25 @@ function checkAborted(signal) {
     throw new AbortError(undefined, { cause: signal.reason });
 }
 
+async function raceWithSignal(opPromise, signal) {
+  if (!signal) return opPromise;
+  kResistStopPropagation ??= require('internal/event_target').kResistStopPropagation;
+  let onAbort;
+  const abortPromise = new Promise((_, reject) => {
+    onAbort = () => reject(new AbortError(undefined, { cause: signal.reason }));
+    signal.addEventListener('abort', onAbort, {
+      __proto__: null,
+      once: true,
+      [kResistStopPropagation]: true,
+    });
+  });
+  try {
+    return await SafePromiseRace([opPromise, abortPromise]);
+  } finally {
+    signal.removeEventListener('abort', onAbort);
+  }
+}
+
 async function writeFileHandle(filehandle, data, signal, encoding) {
   checkAborted(signal);
   if (isCustomIterable(data)) {
@@ -1654,33 +1675,51 @@ async function symlink(target, path, type) {
 }
 
 async function fstat(handle, options = { bigint: false }) {
-  const result = await PromisePrototypeThen(
-    binding.fstat(handle.fd, options.bigint, kUsePromises),
-    undefined,
-    handleErrorFromBinding,
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.fstat(handle.fd, options.bigint, kUsePromises),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
   return getStatsFromBinding(result);
 }
 
 async function lstat(path, options = { bigint: false }) {
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
   path = getValidatedPath(path);
   if (permission.isEnabled() && !permission.has('fs.read', path)) {
     const resource = pathModule.toNamespacedPath(BufferIsBuffer(path) ? BufferToString(path) : path);
     throw new ERR_ACCESS_DENIED('Access to this API has been restricted', 'FileSystemRead', resource);
   }
-  const result = await PromisePrototypeThen(
-    binding.lstat(path, options.bigint, kUsePromises),
-    undefined,
-    handleErrorFromBinding,
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.lstat(path, options.bigint, kUsePromises),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
   return getStatsFromBinding(result);
 }
 
 async function stat(path, options = { bigint: false, throwIfNoEntry: true }) {
-  const result = await PromisePrototypeThen(
-    binding.stat(getValidatedPath(path), options.bigint, kUsePromises, options.throwIfNoEntry),
-    undefined,
-    handleErrorFromBinding,
+  const signal = options?.signal;
+  if (signal !== undefined) validateAbortSignal(signal, 'options.signal');
+  checkAborted(signal);
+  const result = await raceWithSignal(
+    PromisePrototypeThen(
+      binding.stat(getValidatedPath(path), options.bigint, kUsePromises, options.throwIfNoEntry),
+      undefined,
+      handleErrorFromBinding,
+    ),
+    signal,
   );
 
   // Binding will resolve undefined if UV_ENOENT or UV_ENOTDIR and throwIfNoEntry is false

test/parallel/test-fs-stat-abort-test.js

@@ -4,6 +4,7 @@ require('../common');
 const test = require('node:test');
 const assert = require('node:assert');
 const fs = require('node:fs');
+const fsPromises = require('node:fs/promises');
 const tmpdir = require('../common/tmpdir');
 
 tmpdir.refresh();
@@ -37,3 +38,68 @@ test('fs.stat throws ERR_INVALID_ARG_TYPE for invalid signal', () => {
     { code: 'ERR_INVALID_ARG_TYPE' },
   );
 });
+
+test('fs.lstat aborts in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const { promise, resolve, reject } = Promise.withResolvers();
+  fs.lstat(filePath, { signal: controller.signal }, (err, stats) => {
+    if (err) return reject(err);
+    resolve(stats);
+  });
+  controller.abort();
+  await assert.rejects(promise, { name: 'AbortError' });
+});
+
+test('fs.fstat aborts in-flight when signal aborts after the call', async () => {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const controller = new AbortController();
+    const { promise, resolve, reject } = Promise.withResolvers();
+    fs.fstat(fd, { signal: controller.signal }, (err, stats) => {
+      if (err) return reject(err);
+      resolve(stats);
+    });
+    controller.abort();
+    await assert.rejects(promise, { name: 'AbortError' });
+  } finally {
+    fs.closeSync(fd);
+  }
+});
+
+test('fsPromises.stat rejects when signal is already aborted', async () => {
+  const signal = AbortSignal.abort();
+  await assert.rejects(fsPromises.stat(filePath, { signal }), { name: 'AbortError' });
+});
+
+test('fsPromises.stat rejects in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const p = fsPromises.stat(filePath, { signal: controller.signal });
+  controller.abort();
+  await assert.rejects(p, { name: 'AbortError' });
+});
+
+test('fsPromises.stat rejects with ERR_INVALID_ARG_TYPE for invalid signal', async () => {
+  await assert.rejects(
+    fsPromises.stat(filePath, { signal: 'not-a-signal' }),
+    { code: 'ERR_INVALID_ARG_TYPE' },
+  );
+});
+
+test('fsPromises.lstat rejects in-flight when signal aborts after the call', async () => {
+  const controller = new AbortController();
+  const p = fsPromises.lstat(filePath, { signal: controller.signal });
+  controller.abort();
+  await assert.rejects(p, { name: 'AbortError' });
+});
+
+test('filehandle.stat rejects in-flight when signal aborts after the call', async () => {
+  const fh = await fsPromises.open(filePath, 'r');
+  try {
+    const controller = new AbortController();
+    const p = fh.stat({ signal: controller.signal });
+    controller.abort();
+    await assert.rejects(p, { name: 'AbortError' });
+  } finally {
+    await fh.close();
+  }
+});