From 6747721962bb6e1a1e0372f90737cb308d06d99f Mon Sep 17 00:00:00 2001
From: Moshe Atlow <moshe@atlow.co.il>
Date: Sun, 25 Jun 2023 14:18:54 +0300
Subject: [PATCH] fs, stream: initial `Symbol.dispose` and
 `Symbol.asyncDispose` support

Co-authored-by: Benjamin Gruenbaum <benjamingr@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/48518
Backport-PR-URL: https://github.com/nodejs/node/pull/49598
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Erick Wendel <erick.workspace@gmail.com>
Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
---
 doc/api/fs.md                                 | 10 ++++++++
 doc/api/stream.md                             | 11 +++++++++
 lib/internal/fs/promises.js                   |  5 ++++
 lib/internal/per_context/primordials.js       |  6 +++++
 lib/internal/process/pre_execution.js         | 13 +++++++++++
 lib/internal/streams/readable.js              | 11 +++++++++
 .../test-fs-promises-file-handle-dispose.js   | 12 ++++++++++
 test/parallel/test-stream-readable-dispose.js | 23 +++++++++++++++++++
 typings/primordials.d.ts                      |  2 ++
 9 files changed, 93 insertions(+)
 create mode 100644 test/parallel/test-fs-promises-file-handle-dispose.js
 create mode 100644 test/parallel/test-stream-readable-dispose.js

diff --git a/doc/api/fs.md b/doc/api/fs.md
index 261d6c532eb952..e5056a35d32089 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -813,6 +813,16 @@ On Linux, positional writes don't work when the file is opened in append mode.
 The kernel ignores the position argument and always appends the data to
 the end of the file.
 
+#### `filehandle[Symbol.asyncDispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+An alias for `filehandle.close()`.
+
 ### `fsPromises.access(path[, mode])`
 
 <!-- YAML
diff --git a/doc/api/stream.md b/doc/api/stream.md
index b698cb6cfe634a..93632b5798b80a 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -1902,6 +1902,17 @@ option. In the code example above, data will be in a single chunk if the file
 has less then 64 KiB of data because no `highWaterMark` option is provided to
 [`fs.createReadStream()`][].
 
+##### `readable[Symbol.asyncDispose]()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+Calls [`readable.destroy()`][readable-destroy] with an `AbortError` and returns
+a promise that fulfills when the stream is finished.
+
 ##### `readable.compose(stream[, options])`
 
 <!-- YAML
diff --git a/lib/internal/fs/promises.js b/lib/internal/fs/promises.js
index bd3e15e4db83fb..4cf97f2253aa7d 100644
--- a/lib/internal/fs/promises.js
+++ b/lib/internal/fs/promises.js
@@ -14,6 +14,7 @@ const {
   SafeArrayIterator,
   SafePromisePrototypeFinally,
   Symbol,
+  SymbolAsyncDispose,
   Uint8Array,
   FunctionPrototypeBind,
 } = primordials;
@@ -241,6 +242,10 @@ class FileHandle extends EventEmitterMixin(JSTransferable) {
     return this[kClosePromise];
   };
 
+  async [SymbolAsyncDispose]() {
+    return this.close();
+  }
+
   /**
    * @typedef {import('../webstreams/readablestream').ReadableStream
    * } ReadableStream
diff --git a/lib/internal/per_context/primordials.js b/lib/internal/per_context/primordials.js
index cd23e8aa804989..98e9a0754a8a76 100644
--- a/lib/internal/per_context/primordials.js
+++ b/lib/internal/per_context/primordials.js
@@ -228,6 +228,12 @@ function copyPrototype(src, dest, prefix) {
   copyPrototype(original.prototype, primordials, `${name}Prototype`);
 });
 
+// Define Symbol.Dispose and Symbol.AsyncDispose
+// Until these are defined by the environment.
+// TODO(MoLow): Remove this polyfill once Symbol.dispose and Symbol.asyncDispose are available in V8.
+primordials.SymbolDispose ??= primordials.SymbolFor('nodejs.dispose');
+primordials.SymbolAsyncDispose ??= primordials.SymbolFor('nodejs.asyncDispose');
+
 // Create copies of intrinsic objects that require a valid `this` to call
 // static methods.
 // Refs: https://www.ecma-international.org/ecma-262/#sec-promise.all
diff --git a/lib/internal/process/pre_execution.js b/lib/internal/process/pre_execution.js
index 250a43c5455b4f..b4a24bbffb6c43 100644
--- a/lib/internal/process/pre_execution.js
+++ b/lib/internal/process/pre_execution.js
@@ -8,6 +8,9 @@ const {
   SafeMap,
   SafeWeakMap,
   StringPrototypeStartsWith,
+  Symbol,
+  SymbolDispose,
+  SymbolAsyncDispose,
   globalThis,
 } = primordials;
 
@@ -72,6 +75,8 @@ function prepareExecution(options) {
   initializeDeprecations();
   require('internal/dns/utils').initializeDns();
 
+  setupSymbolDisposePolyfill();
+
   if (isMainThread) {
     assert(internalBinding('worker').isMainThread);
     // Worker threads will get the manifest in the message handler.
@@ -109,6 +114,14 @@ function prepareExecution(options) {
   }
 }
 
+function setupSymbolDisposePolyfill() {
+  // TODO(MoLow): Remove this polyfill once Symbol.dispose and Symbol.asyncDispose are available in V8.
+  // eslint-disable-next-line node-core/prefer-primordials
+  Symbol.dispose ??= SymbolDispose;
+  // eslint-disable-next-line node-core/prefer-primordials
+  Symbol.asyncDispose ??= SymbolAsyncDispose;
+}
+
 function setupUserModules() {
   initializeCJSLoader();
   initializeESMLoader();
diff --git a/lib/internal/streams/readable.js b/lib/internal/streams/readable.js
index 3b91ff9852baca..a32dbaee167fcc 100644
--- a/lib/internal/streams/readable.js
+++ b/lib/internal/streams/readable.js
@@ -31,6 +31,7 @@ const {
   ObjectSetPrototypeOf,
   Promise,
   SafeSet,
+  SymbolAsyncDispose,
   SymbolAsyncIterator,
   Symbol,
 } = primordials;
@@ -66,6 +67,7 @@ const {
     ERR_STREAM_PUSH_AFTER_EOF,
     ERR_STREAM_UNSHIFT_AFTER_END_EVENT,
   },
+  AbortError,
 } = require('internal/errors');
 const { validateObject } = require('internal/validators');
 
@@ -226,6 +228,15 @@ Readable.prototype[EE.captureRejectionSymbol] = function(err) {
   this.destroy(err);
 };
 
+Readable.prototype[SymbolAsyncDispose] = function() {
+  let error;
+  if (!this.destroyed) {
+    error = this.readableEnded ? null : new AbortError();
+    this.destroy(error);
+  }
+  return new Promise((resolve, reject) => eos(this, (err) => (err && err !== error ? reject(err) : resolve(null))));
+};
+
 // Manually shove something into the read() buffer.
 // This returns true if the highWaterMark has not been hit yet,
 // similar to how Writable.write() returns true if you should
diff --git a/test/parallel/test-fs-promises-file-handle-dispose.js b/test/parallel/test-fs-promises-file-handle-dispose.js
new file mode 100644
index 00000000000000..406430eef4a204
--- /dev/null
+++ b/test/parallel/test-fs-promises-file-handle-dispose.js
@@ -0,0 +1,12 @@
+'use strict';
+
+const common = require('../common');
+const { promises: fs } = require('fs');
+
+async function doOpen() {
+  const fh = await fs.open(__filename);
+  fh.on('close', common.mustCall());
+  await fh[Symbol.asyncDispose]();
+}
+
+doOpen().then(common.mustCall());
diff --git a/test/parallel/test-stream-readable-dispose.js b/test/parallel/test-stream-readable-dispose.js
new file mode 100644
index 00000000000000..e940bf1688f2bf
--- /dev/null
+++ b/test/parallel/test-stream-readable-dispose.js
@@ -0,0 +1,23 @@
+'use strict';
+
+const common = require('../common');
+const { Readable } = require('stream');
+const assert = require('assert');
+
+{
+  const read = new Readable({
+    read() {}
+  });
+  read.resume();
+
+  read.on('end', common.mustNotCall('no end event'));
+  read.on('close', common.mustCall());
+  read.on('error', common.mustCall((err) => {
+    assert.strictEqual(err.name, 'AbortError');
+  }));
+
+  read[Symbol.asyncDispose]().then(common.mustCall(() => {
+    assert.strictEqual(read.errored.name, 'AbortError');
+    assert.strictEqual(read.destroyed, true);
+  }));
+}
diff --git a/typings/primordials.d.ts b/typings/primordials.d.ts
index a216ac801f7f47..8590812f4155e4 100644
--- a/typings/primordials.d.ts
+++ b/typings/primordials.d.ts
@@ -434,6 +434,8 @@ declare namespace primordials {
   export const SymbolFor: typeof Symbol.for
   export const SymbolKeyFor: typeof Symbol.keyFor
   export const SymbolAsyncIterator: typeof Symbol.asyncIterator
+  export const SymbolDispose: typeof Symbol // TODO(MoLow): use typeof Symbol.dispose when it's available
+  export const SymbolAsyncDispose: typeof Symbol // TODO(MoLow): use typeof Symbol.asyncDispose when it's available
   export const SymbolHasInstance: typeof Symbol.hasInstance
   export const SymbolIsConcatSpreadable: typeof Symbol.isConcatSpreadable
   export const SymbolIterator: typeof Symbol.iterator