Module file_watcher 

Common file watching utilities for configuration hot-reloading.

This module provides a generic file watcher that can be used to watch files for changes and trigger callbacks when changes occur.

The watcher monitors the parent directory of each file rather than the file itself. This ensures that file deletions and recreations are properly tracked, which is common with editors that use atomic saves or when configuration files are replaced.

If the path goes through symlinks (the file itself or any ancestor directory), the directory holding each symlink is watched as well, so that swapping a symlink anywhere in the chain (e.g. ln -sfn secrets.2 secrets, as done by secret managers like sops-nix or Kubernetes volume mounts) is detected. The chain is re-resolved after every relevant event and the set of watched directories is updated accordingly.

Structs

FileWatcherBuilder

A builder for creating file watchers with flexible configuration.

FileWatcherConfig

Configuration for the file watcher behavior.

WatchTargets 🔒

Directories to watch and the directory entries whose events are relevant.

Constants

MAX_SYMLINK_HOPS 🔒

Maximum number of symlinks followed while resolving a single path. This mirrors Linux’s MAXSYMLINKS and guards against symlink loops.

Functions

entry_key 🔒

Key used to compare an event path with WatchTargets::entries.

is_relevant_event 🔒

Check if an event kind is relevant based on the configuration.

rearm_watches 🔒

Re-resolves file_paths and updates the watched directories, returning the new targets. Failures are logged and retried on the next event that matches a chain entry.

resolve_one 🔒

resolve_watch_targets 🔒

Resolves every path component by component, following symlinks, and collects what has to be watched to notice any change of what the path points to.

warn_if_root 🔒

Warns when the root directory is watched, which happens when a path goes through a symlink directly under it (e.g. /tmp, /var or /etc on macOS). On macOS the FSEvents backend then receives every event on the volume and filters them in user space.