fs: add support for AbortSignal in readFile

PR-URL: #35911 Backport-PR-URL: #38386 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Rich Trott <[email protected]> Reviewed-By: Michaël Zasso <[email protected]>

Author: benjamingr

doc/api/fs.md

@@ -3026,6 +3026,10 @@ If `options.withFileTypes` is set to `true`, the result will contain
 <!-- YAML
 added: v0.1.29
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/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://github.com/nodejs/node/pull/12562
  description: The `callback` parameter is no longer optional. Not passing
@@ -3051,6 +3055,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}
@@ -3092,9 +3097,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
+constcontroller=newAbortController();
+constsignal=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.
@@ -4748,6 +4769,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.
@@ -5411,12 +5433,18 @@ print('./').catch(console.error);
 ### `fsPromises.readFile(path[, options])`
 <!-- YAML
 added: v10.0.0
+changes:
+ - version: REPLACEME
+ pr-url: https://github.com/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.
@@ -5432,6 +5460,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
+constcontroller=newAbortController();
+constsignal=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

@@ -316,6 +316,9 @@ function readFile(path, options, callback){
 constcontext=newReadFileContext(callback,options.encoding);
 context.isUserFd=isFd(path);// File descriptor ownership
 
+if(options.signal){
+context.signal=options.signal;
+}
 if(context.isUserFd){
 process.nextTick(functiontick(context){
 readFileAfterOpen.call({ context },null,path);

lib/internal/fs/promises.js

@@ -30,12 +30,14 @@ const{
 }=internalBinding('constants').fs;
 constbinding=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{
@@ -83,6 +85,13 @@ const{
 constgetDirectoryEntriesPromise=promisify(getDirents);
 constvalidateRmOptionsPromise=promisify(validateRmOptions);
 
+letDOMException;
+constlazyDOMException=hideStackFrames((message,name)=>{
+if(DOMException===undefined)
+DOMException=internalBinding('messaging').DOMException;
+returnnewDOMException(message,name);
+});
+
 classFileHandleextendsJSTransferable{
 constructor(filehandle){
 super();
@@ -260,8 +269,17 @@ async function writeFileHandle(filehandle, data){
 }
 
 asyncfunctionreadFileHandle(filehandle,options){
+constsignal=options&&options.signal;
+
+if(signal&&signal.aborted){
+throwlazyDOMException('The operation was aborted','AbortError');
+}
 conststatFields=awaitbinding.fstat(filehandle.fd,false,kUsePromises);
 
+if(signal&&signal.aborted){
+throwlazyDOMException('The operation was aborted','AbortError');
+}
+
 letsize;
 if((statFields[1/* mode */]&S_IFMT)===S_IFREG){
 size=statFields[8/* size */];
@@ -278,6 +296,9 @@ async function readFileHandle(filehandle, options){
 MathMin(size,kReadFileMaxChunkSize);
 letendOfFile=false;
 do{
+if(signal&&signal.aborted){
+throwlazyDOMException('The operation was aborted','AbortError');
+}
 constbuf=Buffer.alloc(chunkSize);
 const{ bytesRead, buffer }=
 awaitread(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');
+
+
+letDOMException;
+constlazyDOMException=hideStackFrames((message,name)=>{
+if(DOMException===undefined)
+DOMException=internalBinding('messaging').DOMException;
+returnnewDOMException(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(){
 letbuffer;
 letoffset;
 letlength;
 
+if(this.signal&&this.signal.aborted){
+returnthis.close(
+lazyDOMException('The operation was aborted','AbortError')
+);
+}
 if(this.size===0){
 buffer=Buffer.allocUnsafeSlow(kReadFileUnknownBufferLength);
 offset=0;

lib/internal/fs/utils.js

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

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

@@ -1,3 +1,4 @@
+// Flags: --experimental-abortcontroller
 'use strict';
 
 constcommon=require('../common');
@@ -10,18 +11,21 @@ tmpdir.refresh();
 
 constfn=path.join(tmpdir.path,'large-file');
 
-asyncfunctionvalidateReadFile(){
-// Creating large buffer with random content
-constbuffer=Buffer.from(
-Array.apply(null,{length: 16834*2})
-.map(Math.random)
-.map((number)=>(number*(1<<8)))
-);
+// Creating large buffer with random content
+constlargeBuffer=Buffer.from(
+Array.apply(null,{length: 16834*2})
+.map(Math.random)
+.map((number)=>(number*(1<<8)))
+);
 
+asyncfunctioncreateLargeFile(){
 // Writing buffer to a file then try to read it
-awaitwriteFile(fn,buffer);
+awaitwriteFile(fn,largeBuffer);
+}
+
+asyncfunctionvalidateReadFile(){
 constreadBuffer=awaitreadFile(fn);
-assert.strictEqual(readBuffer.equals(buffer),true);
+assert.strictEqual(readBuffer.equals(largeBuffer),true);
 }
 
 asyncfunctionvalidateReadFileProc(){
@@ -39,6 +43,28 @@ async function validateReadFileProc(){
 assert.ok(hostname.length>0);
 }
 
-validateReadFile()
-.then(()=>validateReadFileProc())
-.then(common.mustCall());
+functionvalidateReadFileAbortLogicBefore(){
+constcontroller=newAbortController();
+constsignal=controller.signal;
+controller.abort();
+assert.rejects(readFile(fn,{ signal }),{
+name: 'AbortError'
+});
+}
+
+functionvalidateReadFileAbortLogicDuring(){
+constcontroller=newAbortController();
+constsignal=controller.signal;
+process.nextTick(()=>controller.abort());
+assert.rejects(readFile(fn,{ signal }),{
+name: 'AbortError'
+});
+}
+
+(async()=>{
+awaitcreateLargeFile();
+awaitvalidateReadFile();
+awaitvalidateReadFileProc();
+awaitvalidateReadFileAbortLogicBefore();
+awaitvalidateReadFileAbortLogicDuring();
+})().then(common.mustCall());

test/parallel/test-fs-readfile.js

@@ -1,3 +1,4 @@
+// Flags: --experimental-abortcontroller
 'use strict';
 constcommon=require('../common');
 
@@ -57,3 +58,21 @@ for (const e of fileInfo){
 assert.deepStrictEqual(buf,e.contents);
 }));
 }
+{
+// Test cancellation, before
+constcontroller=newAbortController();
+constsignal=controller.signal;
+controller.abort();
+fs.readFile(fileInfo[0].name,{ signal },common.mustCall((err,buf)=>{
+assert.strictEqual(err.name,'AbortError');
+}));
+}
+{
+// Test cancellation, during read
+constcontroller=newAbortController();
+constsignal=controller.signal;
+fs.readFile(fileInfo[0].name,{ signal },common.mustCall((err,buf)=>{
+assert.strictEqual(err.name,'AbortError');
+}));
+process.nextTick(()=>controller.abort());
+}