Module WatchFile 

WatchFile

File: Indexing/Watch/WatchFile.rs

Role in Air Architecture

Provides file watching functionality for the File Indexer service, handling file system events for incremental index updates.

Primary Responsibility

Handle file system change events and trigger index updates for created, modified, and deleted files.

Secondary Responsibilities

• File creation event handling
• File modification event handling
• File deletion event handling
• Directory change event handling
• Event debouncing for rapid changes

Dependencies

External Crates:

• notify - File system watching
• tokio - Async runtime for event handling

Internal Modules:

• crate::Result - Error handling type
• crate::AirError - Error types
• super::super::FileIndex - Index structure definitions
• super::super::Store::UpdateIndex - Index update operations

Dependents

• Indexing::Background::StartWatcher - Watcher setup and management
• Indexing::mod::FileIndexer - Main file indexer implementation

VSCode Pattern Reference

Inspired by VSCode’s file watching in src/vs/base/node/watcher/

Security Considerations

• Path validation before watching
• Symbolic link following disabled
• Permission checking on watch paths

Performance Considerations

• Event debouncing prevents excessive updates
• Batch processing of multiple events
• Efficient event filtering

Error Handling Strategy

Event operations log warnings for individual errors and continue, ensuring a single event failure doesn’t stop the watcher.

Thread Safety

Event handlers acquire write locks on shared state and process events asynchronously to avoid blocking the watcher loop.

Structs

DebouncedEventHandler

Debounced file change handler

ProcessedChange

Describes a processed file change

Enums

FileChangeType

File change type for debouncing

ProcessedChangeResult

Result of processing a debounced change

Functions

EventKindToChangeType

Convert notify event kind to FileChangeType

GetDefaultIgnoredPatterns

Get default ignored patterns for file watching

HandleFileEvent

Handle file watcher event for incremental indexing

ShouldWatchPath

Check if a path should be watched (not in ignored paths)

ValidateWatchPath

Validate that a watch path exists and is accessible