fs: add recursive watch to linux

PR-URL: #45098
Reviewed-By: Matteo Collina <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: James M Snell <[email protected]>

Author: anonrig

doc/api/fs.md

@@ -4301,6 +4301,9 @@ The `atime` and `mtime` arguments follow these rules:
 <!-- YAML
 added: v0.5.10
 changes:
+  - version: REPLACEME
+    pr-url: https://github.com/nodejs/node/pull/45098
+    description: Added recursive support for Linux, AIX and IBMi.
   - version:
       - v15.9.0
       - v14.17.0
@@ -4358,10 +4361,6 @@ the returned {fs.FSWatcher}.
 The `fs.watch` API is not 100% consistent across platforms, and is
 unavailable in some situations.
 
-The recursive option is only supported on macOS and Windows.
-An `ERR_FEATURE_UNAVAILABLE_ON_PLATFORM` exception will be thrown
-when the option is used on a platform that does not support it.
-
 On Windows, no events will be emitted if the watched directory is moved or
 renamed. An `EPERM` error is reported when the watched directory is deleted.
 

lib/fs.js

@@ -58,6 +58,7 @@ const {
 
 const pathModule = require('path');
 const { isArrayBufferView } = require('internal/util/types');
+const nonNativeWatcher = require('internal/fs/recursive_watch');
 
 // We need to get the statValues from the binding at the callsite since
 // it's re-initialized after deserialization.
@@ -69,7 +70,6 @@ const {
   codes: {
     ERR_FS_FILE_TOO_LARGE,
     ERR_INVALID_ARG_VALUE,
-    ERR_FEATURE_UNAVAILABLE_ON_PLATFORM,
   },
   AbortError,
   uvErrmapGet,
@@ -166,7 +166,6 @@ let FileWriteStream;
 const isWindows = process.platform === 'win32';
 const isOSX = process.platform === 'darwin';
 
-
 const showStringCoercionDeprecation = deprecate(
   () => {},
   'Implicit coercion of objects with own toString property is deprecated.',
@@ -2309,13 +2308,22 @@ function watch(filename, options, listener) {
 
   if (options.persistent === undefined) options.persistent = true;
   if (options.recursive === undefined) options.recursive = false;
-  if (options.recursive && !(isOSX || isWindows))
-    throw new ERR_FEATURE_UNAVAILABLE_ON_PLATFORM('watch recursively');
-  const watcher = new watchers.FSWatcher();
-  watcher[watchers.kFSWatchStart](filename,
-                                  options.persistent,
-                                  options.recursive,
-                                  options.encoding);
+
+  let watcher;
+
+  // TODO(anonrig): Remove this when/if libuv supports it.
+  // As of November 2022, libuv does not support recursive file watch on all platforms,
+  // e.g. Linux due to the limitations of inotify.
+  if (options.recursive && !isOSX && !isWindows) {
+    watcher = new nonNativeWatcher.FSWatcher(options);
+    watcher[watchers.kFSWatchStart](filename);
+  } else {
+    watcher = new watchers.FSWatcher();
+    watcher[watchers.kFSWatchStart](filename,
+                                    options.persistent,
+                                    options.recursive,
+                                    options.encoding);
+  }
 
   if (listener) {
     watcher.addListener('change', listener);

lib/internal/fs/promises.js

@@ -87,7 +87,8 @@ const {
 } = require('internal/util');
 const { EventEmitterMixin } = require('internal/event_target');
 const { StringDecoder } = require('string_decoder');
-const { watch } = require('internal/fs/watchers');
+const { kFSWatchStart, watch } = require('internal/fs/watchers');
+const nonNativeWatcher = require('internal/fs/recursive_watch');
 const { isIterable } = require('internal/streams/utils');
 const assert = require('internal/assert');
 
@@ -118,6 +119,8 @@ const {
 const getDirectoryEntriesPromise = promisify(getDirents);
 const validateRmOptionsPromise = promisify(validateRmOptions);
 
+const isOSX = process.platform === 'darwin';
+
 let cpPromises;
 function lazyLoadCpPromises() {
   return cpPromises ??= require('internal/fs/cp/cp').cpFn;
@@ -902,6 +905,26 @@ async function readFile(path, options) {
   return handleFdClose(readFileHandle(fd, options), fd.close);
 }
 
+async function* _watch(filename, options = kEmptyObject) {
+  validateObject(options, 'options');
+
+  if (options.recursive != null) {
+    validateBoolean(options.recursive, 'options.recursive');
+
+    // TODO(anonrig): Remove this when/if libuv supports it.
+    // As of November 2022, libuv does not support recursive file watch on all platforms,
+    // e.g. Linux due to the limitations of inotify.
+    if (options.recursive && !isOSX && !isWindows) {
+      const watcher = new nonNativeWatcher.FSWatcher(options);
+      await watcher[kFSWatchStart](filename);
+      yield* watcher;
+      return;
+    }
+  }
+
+  yield* watch(filename, options);
+}
+
 module.exports = {
   exports: {
     access,
@@ -932,7 +955,7 @@ module.exports = {
     writeFile,
     appendFile,
     readFile,
-    watch,
+    watch: !isOSX && !isWindows ? _watch : watch,
     constants,
   },