fix(#3198): add filesystem_watchers.max_events to handle runaway filesystem events on PowerShell (#3232)

* fix(#3198): add filesystem_watchers.max_outstanding_events which disables filesystem watchers on a directory when runaway events are received

* fix(#3198): document filesystem_watchers.max_events

* fix(#3198): document filesystem_watchers.max_events

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -1707,6 +1707,10 @@ Windows WSL and PowerShell
   freeze Nvim
 - Some filesystem watcher error related to permissions will not be reported
 
+Powershell
+- Observed Nvim hanging after a runaway (infinite) number of events on a
+  single directory. See |nvim_tree.config.filesystem_watchers| {max_events}
+
 ==============================================================================
 netrw                                                        *nvim-tree-netrw*
 
@@ -2511,12 +2515,21 @@ Config: filesystem_watchers             *nvim-tree-config-filesystem-watchers*
       This may be useful when a path is not in `.gitignore` or git integration
       is disabled.
 
+    After {max_events} consecutive filesystem events on a single directory
+    with an interval < {debounce_delay}:
+    • The filesystem watcher will be disabled for that directory.
+    • A warning notification will be shown.
+    • Consider adding this directory to {ignore_dirs}
+
     Fields: ~
       • {enable}?          (`boolean`) (default: `true`)
       • {debounce_delay}?  (`integer`, default: `50`) Idle milliseconds
                            between filesystem change and tree update.
       • {ignore_dirs}?     (`string[]|(fun(path: string): boolean)`, default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`)
-                           Disable for directories.
+                           Disable for specific directories.
+      • {max_events}?      (`integer`, default: `100`) Disable for a single
+                           directory after {max_events} consecutive events
+                           with an interval < {debounce_delay}.
 
 
 
@@ -2987,6 +3000,7 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
       filesystem_watchers = {
         enable = true,
         debounce_delay = 50,
+        max_events = 100,
         ignore_dirs = {
           "/.ccls-cache",
           "/build",

lua/nvim-tree.lua

@@ -462,6 +462,7 @@ local DEFAULT_OPTS = { -- default-config-start
   filesystem_watchers = {
     enable = true,
     debounce_delay = 50,
+    max_events = 100,
     ignore_dirs = {
       "/.ccls-cache",
       "/build",

lua/nvim-tree/_meta/config/filesystem_watchers.lua

@@ -12,6 +12,11 @@ error("Cannot require a meta file")
 --- - A function that is passed an absolute path and returns `true` to disable
 ---This may be useful when a path is not in `.gitignore` or git integration is disabled.
 ---
+---After {max_events} consecutive filesystem events on a single directory with an interval < {debounce_delay}:
+---- The filesystem watcher will be disabled for that directory.
+---- A warning notification will be shown.
+---- Consider adding this directory to {ignore_dirs}
+---
 ---@class nvim_tree.config.filesystem_watchers
 ---
 ---(default: `true`)
@@ -21,6 +26,10 @@ error("Cannot require a meta file")
 ---(default: `50`)
 ---@field debounce_delay? integer
 ---
----Disable for directories.
+---Disable for specific directories.
 ---(default: `{ "/.ccls-cache", "/build", "/node_modules", "/target", }`)
 ---@field ignore_dirs? string[]|(fun(path: string): boolean)
+---
+---Disable for a single directory after {max_events} consecutive events with an interval < {debounce_delay}.
+---(default: `100`)
+---@field max_events? integer

lua/nvim-tree/explorer/watch.lua

@@ -1,6 +1,7 @@
 local log = require("nvim-tree.log")
 local git = require("nvim-tree.git")
 local utils = require("nvim-tree.utils")
+local notify = require("nvim-tree.notify")
 local Watcher = require("nvim-tree.watcher").Watcher
 
 local M = {
@@ -69,10 +70,30 @@ function M.create_watcher(node)
   ---@param watcher Watcher
   local function callback(watcher)
     log.line("watcher", "node event scheduled refresh %s", watcher.data.context)
+
+    -- event is awaiting debouncing and handling
+    watcher.data.outstanding_events = watcher.data.outstanding_events + 1
+
+    -- disable watcher when outstanding exceeds max
+    if watcher.data.outstanding_events > M.config.filesystem_watchers.max_events then
+      notify.error(string.format(
+        "Observed %d consecutive file system events with interval < %dms, exceeding filesystem_watchers.max_events=%s. Disabling watcher for directory '%s'. Consider adding this directory to filesystem_watchers.ignore_dirs",
+        watcher.data.outstanding_events,
+        M.config.filesystem_watchers.max_events,
+        M.config.filesystem_watchers.debounce_delay,
+        node.absolute_path
+      ))
+      node:destroy_watcher()
+    end
+
     utils.debounce(watcher.data.context, M.config.filesystem_watchers.debounce_delay, function()
       if watcher.destroyed then
         return
       end
+
+      -- event has been handled
+      watcher.data.outstanding_events = 0
+
       if node.link_to then
         log.line("watcher", "node event executing refresh '%s' -> '%s'", node.link_to, node.absolute_path)
       else
@@ -87,7 +108,8 @@ function M.create_watcher(node)
     path = path,
     callback = callback,
     data = {
-      context = "explorer:watch:" .. path .. ":" .. M.uid
+      context = "explorer:watch:" .. path .. ":" .. M.uid,
+      outstanding_events = 0, -- unprocessed events that have not been debounced
     }
   })
 end

lua/nvim-tree/node/directory.lua

@@ -37,10 +37,7 @@ function DirectoryNode:new(args)
 end
 
 function DirectoryNode:destroy()
-  if self.watcher then
-    self.watcher:destroy()
-    self.watcher = nil
-  end
+  self:destroy_watcher()
 
   if self.nodes then
     for _, node in pairs(self.nodes) do
@@ -51,6 +48,14 @@ function DirectoryNode:destroy()
   Node.destroy(self)
 end
 
+---Halt and remove the watcher for this node
+function DirectoryNode:destroy_watcher()
+  if self.watcher then
+    self.watcher:destroy()
+    self.watcher = nil
+  end
+end
+
 ---Update the git_status of the directory
 ---@param parent_ignored boolean
 ---@param project GitProject?