Enable polling in file watcher

`inotify` does not work reliably with network file systems
(e.g., NFS, CIFS) commonly used in cloud environments. These
file systems may not propagate file system events correctly,
causing `inotify` to miss changes. To ensure consistent file
monitoring across these environments, polling is enabled by
default in FileWatcher.

Signed-off-by: Daniel Zullo <[email protected]>

Author: daniel-zullo-frequenz

RELEASE_NOTES.md

@@ -14,4 +14,4 @@
 
 ## Bug Fixes
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+- Fixed `FileWatcher` to report events correctly on network file systems like CIFS. File polling is now enabled by default to ensure reliable and consistent file monitoring in these environments.

src/frequenz/channels/file_watcher.py

@@ -22,6 +22,7 @@
 import pathlib
 from collections import abc
 from dataclasses import dataclass
+from datetime import timedelta
 from enum import Enum
 
 from watchfiles import Change, awatch
@@ -127,13 +128,22 @@ def __init__(
         self,
         paths: list[pathlib.Path | str],
         event_types: abc.Iterable[EventType] = frozenset(EventType),
+        *,
+        force_polling: bool = True,
+        polling_interval: timedelta = timedelta(seconds=1),
     ) -> None:
         """Initialize this file watcher.
 
         Args:
             paths: The paths to watch for changes.
             event_types: The types of events to watch for. Defaults to watch for
                 all event types.
+            force_polling: Whether to explicitly force file polling to check for
+                changes. Note that even if set to False, file polling will still
+                be used as a fallback when the underlying file system does not
+                support event-based notifications.
+            polling_interval: The interval to poll for changes. Only relevant if
+                polling is enabled.
         """
         self.event_types: frozenset[EventType] = frozenset(event_types)
         """The types of events to watch for."""
@@ -144,7 +154,11 @@ def __init__(
             for path in paths
         ]
         self._awatch: abc.AsyncGenerator[set[FileChange], None] = awatch(
-            *self._paths, stop_event=self._stop_event, watch_filter=self._filter_events
+            *self._paths,
+            stop_event=self._stop_event,
+            watch_filter=self._filter_events,
+            force_polling=force_polling,
+            poll_delay_ms=int(polling_interval.total_seconds() * 1_000),
         )
         self._awatch_stopped_exc: Exception | None = None
         self._changes: set[FileChange] = set()

tests/test_file_watcher.py

@@ -97,7 +97,11 @@ async def test_file_watcher_filter_events(
 
         assert awatch_mock.mock_calls == [
             mock.call(
-                pathlib.Path(good_path), stop_event=mock.ANY, watch_filter=filter_events
+                pathlib.Path(good_path),
+                stop_event=mock.ANY,
+                watch_filter=filter_events,
+                force_polling=True,
+                poll_delay_ms=1_000,
             )
         ]
         for event_type in EventType:

tests/test_file_watcher_integration.py

@@ -54,7 +54,11 @@ async def test_file_watcher_deletes(tmp_path: pathlib.Path) -> None:
         tmp_path: A tmp directory to run the file watcher on. Created by pytest.
     """
     filename = tmp_path / "test-file"
-    file_watcher = FileWatcher(paths=[str(tmp_path)], event_types={EventType.DELETE})
+    file_watcher = FileWatcher(
+        paths=[str(tmp_path)],
+        event_types={EventType.DELETE},
+        force_polling=False,
+    )
     write_timer = Timer(timedelta(seconds=0.1), SkipMissedAndDrift())
     deletion_timer = Timer(timedelta(seconds=0.25), SkipMissedAndDrift())
 
@@ -113,7 +117,11 @@ async def test_file_watcher_exit_iterator(tmp_path: pathlib.Path) -> None:
     number_of_writes = 0
     expected_number_of_writes = 3
 
-    file_watcher = FileWatcher(paths=[str(tmp_path)])
+    file_watcher = FileWatcher(
+        paths=[str(tmp_path)],
+        force_polling=True,
+        polling_interval=timedelta(seconds=0.05),
+    )
     timer = Timer(timedelta(seconds=0.1), SkipMissedAndDrift())
 
     async for selected in select(file_watcher, timer):