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

Author: alex-courtis

doc/nvim-tree-lua.txt

@@ -2987,6 +2987,7 @@ Following is the default configuration, see |nvim_tree.config| for details. >lua
       filesystem_watchers = {
         enable = true,
         debounce_delay = 50,
+        max_outstanding_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_outstanding_events = 100,
     ignore_dirs = {
       "/.ccls-cache",
       "/build",

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_outstanding_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_outstanding_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?