fs: add support for AbortSignal in readFile

doc/api/fs.md

@@ -3031,6 +3031,10 @@ If `options.withFileTypes` is set to `true`, the result will contain
 <!-- YAML
 added: v0.1.29
 changes:
+ - version: REPLACEME
+ pr-url: https:/nodejs/node/pull/35911
+ description: The options argument may include an AbortSignal to abort an
+ ongoing readFile request.
  - version: v10.0.0
  pr-url: https:/nodejs/node/pull/12562
  description: The `callback` parameter is no longer optional. Not passing
@@ -3056,6 +3060,7 @@ changes:
 * `options` {Object|string}
  * `encoding` {string|null} **Default:** `null`
  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
+ * `signal` {AbortSignal} allows aborting an in-progress readFile
 * `callback` {Function}
  * `err` {Error}
  * `data` {string|Buffer}
@@ -3097,9 +3102,25 @@ fs.readFile('<directory>', (err, data) => {
 });
 ```
 
+It is possible to abort an ongoing request using an `AbortSignal`. If a
+request is aborted the callback is called with an `AbortError`:
+
+```js
+const controller = new AbortController();
+const signal = controller.signal;
+fs.readFile(fileInfo[0].name, { signal }, (err, buf) => {
+ // ...
+});
+// When you want to abort the request
+controller.abort();
+```
+
 The `fs.readFile()` function buffers the entire file. To minimize memory costs,
 when possible prefer streaming via `fs.createReadStream()`.
 
+Aborting an ongoing request does not abort individual operating
+system requests but rather the internal buffering `fs.readFile` performs.
+
 ### File descriptors
 
 1. Any specified file descriptor has to support reading.
@@ -4771,6 +4792,7 @@ added: v10.0.0
 
 * `options` {Object|string}
  * `encoding` {string|null} **Default:** `null`
+ * `signal` {AbortSignal} allows aborting an in-progress readFile
 * Returns: {Promise}
 
 Asynchronously reads the entire contents of a file.
@@ -5438,12 +5460,18 @@ print('./').catch(console.error);
 ### `fsPromises.readFile(path[, options])`
 <!-- YAML
 added: v10.0.0
+changes:
+ - version: REPLACEME
+ pr-url: https:/nodejs/node/pull/35911
+ description: The options argument may include an AbortSignal to abort an
+ ongoing readFile request.
 -->
 
 * `path` {string|Buffer|URL|FileHandle} filename or `FileHandle`
 * `options` {Object|string}
  * `encoding` {string|null} **Default:** `null`
  * `flag` {string} See [support of file system `flags`][]. **Default:** `'r'`.
+ * `signal` {AbortSignal} allows aborting an in-progress readFile
 * Returns: {Promise}
 
 Asynchronously reads the entire contents of a file.
@@ -5459,6 +5487,20 @@ platform-specific. On macOS, Linux, and Windows, the promise will be rejected
 with an error. On FreeBSD, a representation of the directory's contents will be
 returned.
 
+It is possible to abort an ongoing `readFile` using an `AbortSignal`. If a
+request is aborted the promise returned is rejected with an `AbortError`:
+
+```js
+const controller = new AbortController();
+const signal = controller.signal;
+readFile(fileName, { signal }).then((file) => { /* ... */ });
+// Abort the request
+controller.abort();
+```
+
+Aborting an ongoing request does not abort individual operating
+system requests but rather the internal buffering `fs.readFile` performs.
+
 Any specified `FileHandle` has to support reading.
 
 ### `fsPromises.readlink(path[, options])`

lib/fs.js

@@ -315,6 +315,9 @@ function readFile(path, options, callback) {
  const context = new ReadFileContext(callback, options.encoding);
  context.isUserFd = isFd(path); // File descriptor ownership
 
+ if (options.signal) {
+ context.signal = options.signal;
+ }
  if (context.isUserFd) {
  process.nextTick(function tick(context) {
  readFileAfterOpen.call({ context }, null, path);

lib/internal/fs/promises.js

@@ -29,12 +29,14 @@ const {
 } = internalBinding('constants').fs;
 const binding = internalBinding('fs');
 const { Buffer } = require('buffer');
+
+const { codes, hideStackFrames } = require('internal/errors');
 const {
  ERR_FS_FILE_TOO_LARGE,
  ERR_INVALID_ARG_TYPE,
  ERR_INVALID_ARG_VALUE,
- ERR_METHOD_NOT_IMPLEMENTED
-} = require('internal/errors').codes;
+ ERR_METHOD_NOT_IMPLEMENTED,
+} = codes;
 const { isArrayBufferView } = require('internal/util/types');
 const { rimrafPromises } = require('internal/fs/rimraf');
 const {
@@ -82,6 +84,13 @@ const {
 const getDirectoryEntriesPromise = promisify(getDirents);
 const validateRmOptionsPromise = promisify(validateRmOptions);
 
+let DOMException;
+const lazyDOMException = hideStackFrames((message, name) => {
+ if (DOMException === undefined)
+ DOMException = internalBinding('messaging').DOMException;
+ return new DOMException(message, name);
+});
+
 class FileHandle extends JSTransferable {
  constructor(filehandle) {
  super();
@@ -259,8 +268,17 @@ async function writeFileHandle(filehandle, data) {
 }
 
 async function readFileHandle(filehandle, options) {
+ const signal = options && options.signal;
+
+ if (signal && signal.aborted) {
+ throw lazyDOMException('The operation was aborted', 'AbortError');
+ }
  const statFields = await binding.fstat(filehandle.fd, false, kUsePromises);
 
+ if (signal && signal.aborted) {
+ throw lazyDOMException('The operation was aborted', 'AbortError');
+ }
+
  let size;
  if ((statFields[1/* mode */] & S_IFMT) === S_IFREG) {
  size = statFields[8/* size */];
@@ -277,6 +295,9 @@ async function readFileHandle(filehandle, options) {
  MathMin(size, kReadFileMaxChunkSize);
  let endOfFile = false;
  do {
+ if (signal && signal.aborted) {
+ throw lazyDOMException('The operation was aborted', 'AbortError');
+ }
  const buf = Buffer.alloc(chunkSize);
  const { bytesRead, buffer } =
  await read(filehandle, buf, 0, chunkSize, -1);

lib/internal/fs/read_file_context.js

@@ -8,6 +8,16 @@ const { Buffer } = require('buffer');
 
 const { FSReqCallback, close, read } = internalBinding('fs');
 
+const { hideStackFrames } = require('internal/errors');
+
+
+let DOMException;
+const lazyDOMException = hideStackFrames((message, name) => {
+ if (DOMException === undefined)
+ DOMException = internalBinding('messaging').DOMException;
+ return new DOMException(message, name);
+});
+
 // Use 64kb in case the file type is not a regular file and thus do not know the
 // actual file size. Increasing the value further results in more frequent over
 // allocation for small files and consumes CPU time and memory that should be
@@ -74,13 +84,19 @@ class ReadFileContext {
  this.pos = 0;
  this.encoding = encoding;
  this.err = null;
+ this.signal = undefined;
  }
 
  read() {
  let buffer;
  let offset;
  let length;
 
+ if (this.signal && this.signal.aborted) {
+ return this.close(
+ lazyDOMException('The operation was aborted', 'AbortError')
+ );
+ }
  if (this.size === 0) {
  buffer = Buffer.allocUnsafeSlow(kReadFileUnknownBufferLength);
  offset = 0;

lib/internal/fs/utils.js

@@ -35,6 +35,7 @@ const {
 const { once } = require('internal/util');
 const { toPathIfFileURL } = require('internal/url');
 const {
+ validateAbortSignal,
  validateBoolean,
  validateInt32,
  validateUint32
@@ -296,6 +297,10 @@ function getOptions(options, defaultOptions) {
 
  if (options.encoding !== 'buffer')
  assertEncoding(options.encoding);
+
+ if (options.signal !== undefined) {
+ validateAbortSignal(options.signal, 'options.signal');
+ }
  return options;
 }
 

test/parallel/test-fs-promises-readfile.js

@@ -10,18 +10,21 @@ tmpdir.refresh();
 
 const fn = path.join(tmpdir.path, 'large-file');
 
-async function validateReadFile() {
- // Creating large buffer with random content
- const buffer = Buffer.from(
- Array.apply(null, { length: 16834 * 2 })
- .map(Math.random)
- .map((number) => (number * (1 << 8)))
- );
+// Creating large buffer with random content
+const largeBuffer = Buffer.from(
+ Array.apply(null, { length: 16834 * 2 })
+ .map(Math.random)
+ .map((number) => (number * (1 << 8)))
+);
 
+async function createLargeFile() {
  // Writing buffer to a file then try to read it
- await writeFile(fn, buffer);
+ await writeFile(fn, largeBuffer);
+}
+
+async function validateReadFile() {
  const readBuffer = await readFile(fn);
- assert.strictEqual(readBuffer.equals(buffer), true);
+ assert.strictEqual(readBuffer.equals(largeBuffer), true);
 }
 
 async function validateReadFileProc() {
@@ -39,6 +42,28 @@ async function validateReadFileProc() {
  assert.ok(hostname.length > 0);
 }
 
-validateReadFile()
- .then(() => validateReadFileProc())
- .then(common.mustCall());
+function validateReadFileAbortLogicBefore() {
+ const controller = new AbortController();
+ const signal = controller.signal;
+ controller.abort();
+ assert.rejects(readFile(fn, { signal }), {
+ name: 'AbortError'
+ });
+}
+
+function validateReadFileAbortLogicDuring() {
+ const controller = new AbortController();
+ const signal = controller.signal;
+ process.nextTick(() => controller.abort());
+ assert.rejects(readFile(fn, { signal }), {
+ name: 'AbortError'
+ });
+}
+
+(async () => {
+ await createLargeFile();
+ await validateReadFile();
+ await validateReadFileProc();
+ await validateReadFileAbortLogicBefore();
+ await validateReadFileAbortLogicDuring();
+})().then(common.mustCall());

test/parallel/test-fs-readfile.js

@@ -57,3 +57,21 @@ for (const e of fileInfo) {
  assert.deepStrictEqual(buf, e.contents);
  }));
 }
+{
+ // Test cancellation, before
+ const controller = new AbortController();
+ const signal = controller.signal;
+ controller.abort();
+ fs.readFile(fileInfo[0].name, { signal }, common.mustCall((err, buf) => {
+ assert.strictEqual(err.name, 'AbortError');
+ }));
+}
+{
+ // Test cancellation, during read
+ const controller = new AbortController();
+ const signal = controller.signal;
+ fs.readFile(fileInfo[0].name, { signal }, common.mustCall((err, buf) => {
+ assert.strictEqual(err.name, 'AbortError');
+ }));
+ process.nextTick(() => controller.abort());
+}