fs: add recursive option to rmdir()

This commit adds a recursive option to fs.rmdir(),
fs.rmdirSync(), and fs.promises.rmdir(). The implementation
is a port of the npm module rimraf.

PR-URL: #29168
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Roman Reiss <me@silverwind.io>
Reviewed-By: Ben Coe <bencoe@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>

LICENSE

@@ -1507,3 +1507,22 @@ The externally maintained libraries used by Node.js are:
     ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
     OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
   """
+
+- rimraf, located at lib/internal/fs/rimraf.js, is licensed as follows:
+  """
+    The ISC License
+
+    Copyright (c) Isaac Z. Schlueter and Contributors
+
+    Permission to use, copy, modify, and/or distribute this software for any
+    purpose with or without fee is hereby granted, provided that the above
+    copyright notice and this permission notice appear in all copies.
+
+    THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+    WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+    ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+    ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
+    IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+  """

doc/api/fs.md

@@ -3017,10 +3017,14 @@ changes:
 
 Synchronous rename(2). Returns `undefined`.
 
-## fs.rmdir(path, callback)
+## fs.rmdir(path[, options], callback)
 <!-- YAML
 added: v0.0.2
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive`, `maxBusyTries`, and `emfileWait` options are
+                 now supported.
   - version: v10.0.0
     pr-url: https://github.com/nodejs/node/pull/12562
     description: The `callback` parameter is no longer optional. Not passing
@@ -3035,7 +3039,21 @@ changes:
                  it will emit a deprecation warning with id DEP0013.
 -->
 
+> Stability: 1 - Recursive removal is experimental.
+
 * `path` {string|Buffer|URL}
+* `options` {Object}
+  * `emfileWait` {integer} If an `EMFILE` error is encountered, Node.js will
+  retry the operation with a linear backoff of 1ms longer on each try until the
+  timeout duration passes this limit. This option is ignored if the `recursive`
+  option is not `true`. **Default:** `1000`.
+  * `maxBusyTries` {integer} If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error is
+  encountered, Node.js will retry the operation with a linear backoff wait of
+  100ms longer on each try. This option represents the number of retries. This
+  option is ignored if the `recursive` option is not `true`. **Default:** `3`.
+  * `recursive` {boolean} If `true`, perform a recursive directory removal. In
+  recursive mode, errors are not reported if `path` does not exist, and
+  operations are retried on failure. **Default:** `false`.
 * `callback` {Function}
   * `err` {Error}
 
@@ -3045,17 +3063,27 @@ to the completion callback.
 Using `fs.rmdir()` on a file (not a directory) results in an `ENOENT` error on
 Windows and an `ENOTDIR` error on POSIX.
 
-## fs.rmdirSync(path)
+## fs.rmdirSync(path[, options])
 <!-- YAML
 added: v0.1.21
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive`, `maxBusyTries`, and `emfileWait` options are
+                 now supported.
   - version: v7.6.0
     pr-url: https://github.com/nodejs/node/pull/10739
     description: The `path` parameters can be a WHATWG `URL` object using
                  `file:` protocol. Support is currently still *experimental*.
 -->
 
+> Stability: 1 - Recursive removal is experimental.
+
 * `path` {string|Buffer|URL}
+* `options` {Object}
+  * `recursive` {boolean} If `true`, perform a recursive directory removal. In
+  recursive mode, errors are not reported if `path` does not exist, and
+  operations are retried on failure. **Default:** `false`.
 
 Synchronous rmdir(2). Returns `undefined`.
 
@@ -4694,12 +4722,31 @@ added: v10.0.0
 Renames `oldPath` to `newPath` and resolves the `Promise` with no arguments
 upon success.
 
-### fsPromises.rmdir(path)
+### fsPromises.rmdir(path[, options])
 <!-- YAML
 added: v10.0.0
+changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/29168
+    description: The `recursive`, `maxBusyTries`, and `emfileWait` options are
+                  now supported.
 -->
 
+> Stability: 1 - Recursive removal is experimental.
+
 * `path` {string|Buffer|URL}
+* `options` {Object}
+  * `emfileWait` {integer} If an `EMFILE` error is encountered, Node.js will
+  retry the operation with a linear backoff of 1ms longer on each try until the
+  timeout duration passes this limit. This option is ignored if the `recursive`
+  option is not `true`. **Default:** `1000`.
+  * `maxBusyTries` {integer} If an `EBUSY`, `ENOTEMPTY`, or `EPERM` error is
+  encountered, Node.js will retry the operation with a linear backoff wait of
+  100ms longer on each try. This option represents the number of retries. This
+  option is ignored if the `recursive` option is not `true`. **Default:** `3`.
+  * `recursive` {boolean} If `true`, perform a recursive directory removal. In
+  recursive mode, errors are not reported if `path` does not exist, and
+  operations are retried on failure. **Default:** `false`.
 * Returns: {Promise}
 
 Removes the directory identified by `path` then resolves the `Promise` with
@@ -5193,7 +5240,7 @@ the file contents.
 [`fs.readdir()`]: #fs_fs_readdir_path_options_callback
 [`fs.readdirSync()`]: #fs_fs_readdirsync_path_options
 [`fs.realpath()`]: #fs_fs_realpath_path_options_callback
-[`fs.rmdir()`]: #fs_fs_rmdir_path_callback
+[`fs.rmdir()`]: #fs_fs_rmdir_path_options_callback
 [`fs.stat()`]: #fs_fs_stat_path_options_callback
 [`fs.symlink()`]: #fs_fs_symlink_target_path_type_callback
 [`fs.utimes()`]: #fs_fs_utimes_path_atime_mtime_callback

lib/fs.js

@@ -76,6 +76,7 @@ const {
   validateOffsetLengthRead,
   validateOffsetLengthWrite,
   validatePath,
+  validateRmdirOptions,
   warnOnNonPortableTemplate
 } = require('internal/fs/utils');
 const {
@@ -100,6 +101,8 @@ let watchers;
 let ReadFileContext;
 let ReadStream;
 let WriteStream;
+let rimraf;
+let rimrafSync;
 
 // These have to be separate because of how graceful-fs happens to do it's
 // monkeypatching.
@@ -720,16 +723,41 @@ function ftruncateSync(fd, len = 0) {
   handleErrorFromBinding(ctx);
 }
 
-function rmdir(path, callback) {
+
+function lazyLoadRimraf() {
+  if (rimraf === undefined)
+    ({ rimraf, rimrafSync } = require('internal/fs/rimraf'));
+}
+
+function rmdir(path, options, callback) {
+  if (typeof options === 'function') {
+    callback = options;
+    options = undefined;
+  }
+
   callback = makeCallback(callback);
-  path = getValidatedPath(path);
+  path = pathModule.toNamespacedPath(getValidatedPath(path));
+  options = validateRmdirOptions(options);
+
+  if (options.recursive) {
+    lazyLoadRimraf();
+    return rimraf(path, options, callback);
+  }
+
   const req = new FSReqCallback();
   req.oncomplete = callback;
-  binding.rmdir(pathModule.toNamespacedPath(path), req);
+  binding.rmdir(path, req);
 }
 
-function rmdirSync(path) {
+function rmdirSync(path, options) {
   path = getValidatedPath(path);
+  options = validateRmdirOptions(options);
+
+  if (options.recursive) {
+    lazyLoadRimraf();
+    return rimrafSync(pathModule.toNamespacedPath(path), options);
+  }
+
   const ctx = { path };
   binding.rmdir(pathModule.toNamespacedPath(path), undefined, ctx);
   handleErrorFromBinding(ctx);

lib/internal/fs/promises.js

@@ -18,6 +18,7 @@ const {
   ERR_METHOD_NOT_IMPLEMENTED
 } = require('internal/errors').codes;
 const { isUint8Array } = require('internal/util/types');
+const { rimrafPromises } = require('internal/fs/rimraf');
 const {
   copyObject,
   getDirents,
@@ -32,6 +33,7 @@ const {
   validateBufferArray,
   validateOffsetLengthRead,
   validateOffsetLengthWrite,
+  validateRmdirOptions,
   warnOnNonPortableTemplate
 } = require('internal/fs/utils');
 const {
@@ -291,9 +293,15 @@ async function ftruncate(handle, len = 0) {
   return binding.ftruncate(handle.fd, len, kUsePromises);
 }
 
-async function rmdir(path) {
-  path = getValidatedPath(path);
-  return binding.rmdir(pathModule.toNamespacedPath(path), kUsePromises);
+async function rmdir(path, options) {
+  path = pathModule.toNamespacedPath(getValidatedPath(path));
+  options = validateRmdirOptions(options);
+
+  if (options.recursive) {
+    return rimrafPromises(path, options);
+  }
+
+  return binding.rmdir(path, kUsePromises);
 }
 
 async function fdatasync(handle) {