fs: support abortsignal in writeFile

PR-URL: #35993
Backport-PR-URL: #38386
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

Author: benjamingr

doc/api/fs.md

@@ -4375,6 +4375,10 @@ details.
 <!-- YAML
 added: v0.1.29
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/35993
+ description: The options argument may include an AbortSignal to abort an
+ ongoing writeFile request.
  - version: v14.12.0
  pr-url: https://github.com/nodejs/node/pull/34993
  description: The `data` parameter will stringify an object with an
@@ -4409,6 +4413,7 @@ changes:
 *`encoding` {string|null} **Default:**`'utf8'`
 *`mode` {integer} **Default:**`0o666`
 *`flag` {string} See [support of file system `flags`][]. **Default:**`'w'`.
+*`signal` {AbortSignal} allows aborting an in-progress writeFile
 *`callback` {Function}
 *`err` {Error}
 
@@ -4440,6 +4445,28 @@ It is unsafe to use `fs.writeFile()` multiple times on the same file without
 waiting for the callback. For this scenario, [`fs.createWriteStream()`][] is
 recommended.
 
+Similarly to `fs.readFile` - `fs.writeFile` is a convenience method that
+performs multiple `write` calls internally to write the buffer passed to it.
+For performance sensitive code consider using [`fs.createWriteStream()`][].
+
+It is possible to use an {AbortSignal} to cancel an `fs.writeFile()`.
+Cancelation is "best effort", and some amount of data is likely still
+to be written.
+
+```js
+constcontroller=newAbortController();
+const { signal } = controller;
+constdata=newUint8Array(Buffer.from('Hello Node.js'));
+fs.writeFile('message.txt', data, { signal }, (err) => {
+// When a request is aborted - the callback is called with an AbortError
+});
+// When the request should be aborted
+controller.abort();
+```
+
+Aborting an ongoing request does not abort individual operating
+system requests but rather the internal buffering `fs.writeFile` performs.
+
 ### Using `fs.writeFile()` with file descriptors
 
 When `file` is a file descriptor, the behavior is almost identical to directly
@@ -5684,6 +5711,10 @@ The `atime` and `mtime` arguments follow these rules:
 <!-- YAML
 added: v10.0.0
 changes:
+ - version: REPLACEME
+ pr-url: https://github.com/nodejs/node/pull/35993
+ description: The options argument may include an AbortSignal to abort an
+ ongoing writeFile request.
  - version: v14.12.0
  pr-url: https://github.com/nodejs/node/pull/34993
  description: The `data` parameter will stringify an object with an
@@ -5700,6 +5731,7 @@ changes:
 *`encoding` {string|null} **Default:**`'utf8'`
 *`mode` {integer} **Default:**`0o666`
 *`flag` {string} See [support of file system `flags`][]. **Default:**`'w'`.
+*`signal` {AbortSignal} allows aborting an in-progress writeFile
 * Returns: {Promise}
 
 Asynchronously writes data to a file, replacing the file if it already exists.
@@ -5713,7 +5745,34 @@ If `options` is a string, then it specifies the encoding.
 Any specified `FileHandle` has to support writing.
 
 It is unsafe to use `fsPromises.writeFile()` multiple times on the same file
-without waiting for the `Promise` to be resolved (or rejected).
+without waiting for the `Promise` to be fulfilled (or rejected).
+
+Similarly to `fsPromises.readFile` - `fsPromises.writeFile` is a convenience
+method that performs multiple `write` calls internally to write the buffer
+passed to it. For performance sensitive code consider using
+[`fs.createWriteStream()`][].
+
+It is possible to use an {AbortSignal} to cancel an `fsPromises.writeFile()`.
+Cancelation is "best effort", and some amount of data is likely still
+to be written.
+
+```js
+constcontroller=newAbortController();
+const { signal } = controller;
+constdata=newUint8Array(Buffer.from('Hello Node.js'));
+(async () => {
+try {
+awaitfs.writeFile('message.txt', data, { signal });
+ } catch (err) {
+// When a request is aborted - err is an AbortError
+ }
+})();
+// When the request should be aborted
+controller.abort();
+```
+
+Aborting an ongoing request does not abort individual operating
+system requests but rather the internal buffering `fs.writeFile` performs.
 
 ## FS constants
 

lib/fs.js

@@ -71,6 +71,7 @@ const {
 ERR_INVALID_CALLBACK,
 ERR_FEATURE_UNAVAILABLE_ON_PLATFORM
 },
+ hideStackFrames,
  uvErrmapGet,
  uvException
 }=require('internal/errors');
@@ -134,6 +135,13 @@ let ReadStream;
 letWriteStream;
 letrimraf;
 letrimrafSync;
+letDOMException;
+
+constlazyDOMException=hideStackFrames((message,name)=>{
+if(DOMException===undefined)
+DOMException=internalBinding('messaging').DOMException;
+returnnewDOMException(message,name);
+});
 
 // These have to be separate because of how graceful-fs happens to do it's
 // monkeypatching.
@@ -1425,7 +1433,11 @@ function lutimesSync(path, atime, mtime) {
 handleErrorFromBinding(ctx);
 }
 
-functionwriteAll(fd,isUserFd,buffer,offset,length,callback){
+functionwriteAll(fd,isUserFd,buffer,offset,length,signal,callback){
+if(signal?.aborted){
+callback(lazyDOMException('The operation was aborted','AbortError'));
+return;
+}
 // write(fd, buffer, offset, length, position, callback)
 fs.write(fd,buffer,offset,length,null,(writeErr,written)=>{
 if(writeErr){
@@ -1445,7 +1457,7 @@ function writeAll(fd, isUserFd, buffer, offset, length, callback) {
 }else{
 offset+=written;
 length-=written;
-writeAll(fd,isUserFd,buffer,offset,length,callback);
+writeAll(fd,isUserFd,buffer,offset,length,signal,callback);
 }
 });
 }
@@ -1462,16 +1474,22 @@ function writeFile(path, data, options, callback) {
 
 if(isFd(path)){
 constisUserFd=true;
-writeAll(path,isUserFd,data,0,data.byteLength,callback);
+constsignal=options.signal;
+writeAll(path,isUserFd,data,0,data.byteLength,signal,callback);
 return;
 }
 
+if(options.signal?.aborted){
+callback(lazyDOMException('The operation was aborted','AbortError'));
+return;
+}
 fs.open(path,flag,options.mode,(openErr,fd)=>{
 if(openErr){
 callback(openErr);
 }else{
 constisUserFd=false;
-writeAll(fd,isUserFd,data,0,data.byteLength,callback);
+constsignal=options.signal;
+writeAll(fd,isUserFd,data,0,data.byteLength,signal,callback);
 }
 });
 }

lib/internal/fs/promises.js

@@ -250,12 +250,15 @@ async function fsCall(fn, handle, ...args) {
 }
 }
 
-asyncfunctionwriteFileHandle(filehandle,data){
+asyncfunctionwriteFileHandle(filehandle,data,signal){
 // `data` could be any kind of typed array.
 data=newUint8Array(data.buffer,data.byteOffset,data.byteLength);
 letremaining=data.length;
 if(remaining===0)return;
 do{
+if(signal?.aborted){
+thrownewlazyDOMException('The operation was aborted','AbortError');
+}
 const{ bytesWritten }=
 awaitwrite(filehandle,data,0,
 MathMin(kWriteFileMaxChunkSize,data.length));
@@ -644,9 +647,12 @@ async function writeFile(path, data, options) {
 }
 
 if(pathinstanceofFileHandle)
-returnwriteFileHandle(path,data);
+returnwriteFileHandle(path,data,options.signal);
 
 constfd=awaitopen(path,flag,options.mode);
+if(options.signal?.aborted){
+thrownewlazyDOMException('The operation was aborted','AbortError');
+}
 returnPromisePrototypeFinally(writeFileHandle(fd,data),fd.close);
 }
 

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

@@ -1,3 +1,4 @@
+// Flags: --experimental-abortcontroller
 'use strict';
 
 constcommon=require('../common');
@@ -11,6 +12,7 @@ const tmpDir = tmpdir.path;
 tmpdir.refresh();
 
 constdest=path.resolve(tmpDir,'tmp.txt');
+constotherDest=path.resolve(tmpDir,'tmp-2.txt');
 constbuffer=Buffer.from('abc'.repeat(1000));
 constbuffer2=Buffer.from('xyz'.repeat(1000));
 
@@ -20,6 +22,15 @@ async function doWrite() {
 assert.deepStrictEqual(data,buffer);
 }
 
+asyncfunctiondoWriteWithCancel(){
+constcontroller=newAbortController();
+const{ signal }=controller;
+process.nextTick(()=>controller.abort());
+assert.rejects(fsPromises.writeFile(otherDest,buffer,{ signal }),{
+name: 'AbortError'
+});
+}
+
 asyncfunctiondoAppend(){
 awaitfsPromises.appendFile(dest,buffer2);
 constdata=fs.readFileSync(dest);
@@ -41,6 +52,7 @@ async function doReadWithEncoding() {
 }
 
 doWrite()
+.then(doWriteWithCancel)
 .then(doAppend)
 .then(doRead)
 .then(doReadWithEncoding)

test/parallel/test-fs-write-file.js

@@ -19,6 +19,7 @@
 // OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
 // USE OR OTHER DEALINGS IN THE SOFTWARE.
 
+// Flags: --experimental-abortcontroller
 'use strict';
 constcommon=require('../common');
 constassert=require('assert');
@@ -66,3 +67,32 @@ fs.open(filename4, 'w+', common.mustSucceed((fd) => {
 }));
 }));
 }));
+
+
+{
+// Test that writeFile is cancellable with an AbortSignal.
+// Before the operation has started
+constcontroller=newAbortController();
+constsignal=controller.signal;
+constfilename3=join(tmpdir.path,'test3.txt');
+
+fs.writeFile(filename3,s,{ signal },common.mustCall((err)=>{
+assert.strictEqual(err.name,'AbortError');
+}));
+
+controller.abort();
+}
+
+{
+// Test that writeFile is cancellable with an AbortSignal.
+// After the operation has started
+constcontroller=newAbortController();
+constsignal=controller.signal;
+constfilename4=join(tmpdir.path,'test4.txt');
+
+fs.writeFile(filename4,s,{ signal },common.mustCall((err)=>{
+assert.strictEqual(err.name,'AbortError');
+}));
+
+process.nextTick(()=>controller.abort());
+}