Add EventKindMask for filtering filesystem events by withzombies · Pull Request #736 · notify-rs/notify

withzombies · 2025-12-14T15:37:51Z

Adds EventKindMask, a bitflags-based type that allows users to configure which event kinds they want to receive. This is configured via Config::with_event_kinds().

This feature allows filtering at the source. On Linux (inotify), filtering happens at the kernel level via WatchMask translation, so unwanted events never reach userspace. On other backends, filtering is applied early in the event pipeline.

Existing users shouldn't see any breaking changes. The default (EventKindMask::ALL) should preserve existing behavior.

Usage

use notify::{Config, EventKindMask, RecommendedWatcher, Watcher};

// Exclude access events (OPEN/CLOSE) - kernel-level on Linux
let config = Config::default().with_event_kinds(EventKindMask::CORE);

// Or be more selective
let config = Config::default()
    .with_event_kinds(EventKindMask::CREATE | EventKindMask::REMOVE);

let mut watcher = RecommendedWatcher::new(tx, config)?;

Changes

New EventKindMask type in notify-types with flags: CREATE, REMOVE, MODIFY_DATA, MODIFY_META, MODIFY_NAME, ACCESS_OPEN, ACCESS_CLOSE, ACCESS_CLOSE_NOWRITE
Composite masks: CORE (excludes access), ALL (everything)
Default is ALL for backward compatibility
Implemented in all backends: inotify (kernel), kqueue, FSEvents, Windows, PollWatcher (userspace)
Includes examples and tests for each backend

greged93 · 2025-12-17T15:26:59Z

Would really love this feature to be merged. Should this be on the Config or on the Watcher::watch?

withzombies · 2025-12-17T16:03:00Z

Would really love this feature to be merged. Should this be on the Config or on the Watcher::watch?

I went with Config because it better fit my use case. I wasn't trying to have a mix of event levels. I think if we want different event levels we could start a few watchers?

riberk · 2025-12-23T11:11:00Z

notify/src/inotify.rs

+    let mut watch_mask = WatchMask::empty();
+
+    if mask.intersects(EventKindMask::CREATE) {
+        watch_mask |= WatchMask::CREATE | WatchMask::MOVED_TO;


I think it maybe rally confusing, if user requested recursive watch with ignored create events. In that case subdirectories created after a watch call will not be watched

Got it.

Recursive watches now always register for CREATE/MOVED_TO at the kernel level, then filter in userspace before delivery. This ensures subdirectory tracking works regardless of the user's EventKindMask.

JohnTitor · 2026-01-15T12:24:01Z

notify/src/windows.rs

 impl ReadDirectoryChangesWatcher {
    pub fn create(
        event_handler: Arc<Mutex<dyn EventHandler>>,
+        event_kinds: EventKindMask,


Note: this is a technically breaking change. It doesn't mean we should change it but it would require a major release.

JohnTitor

Needs to resolve the conflict but otherwise LGTM

JohnTitor · 2026-01-15T12:26:03Z

notify/src/inotify.rs

-        follow_links: bool,
+        config: &Config,


- Change EventKindMask::default() from CORE to ALL to match Config::default().event_kinds() - Add userspace event filtering to PollWatcher via EventEmitter - Filter events in emit_ok() using EventKindMask::matches() - Error events always pass through (not filtered) - Add test verifying CREATE-only mask filters MODIFY events - Add cross-crate consistency test for defaults This is part of the EventKindMask cross-platform filtering feature. PollWatcher now respects the event_kinds config, filtering events before delivery to the user's handler.

Adds userspace event filtering to the kqueue backend by storing the EventKindMask from Config and checking events against it before delivering to the handler. This follows the same pattern established in PollWatcher. - Store event_kinds in EventLoop struct - Pass event_kinds from Config through the constructor chain - Filter OK events before calling handle_event(), errors pass through - Add test for filtering behavior (requires BSD/macOS to run)

Add event filtering to the FSEvents (macOS) backend by calling EventKindMask::matches() before delivering events to the handler. This follows the same pattern established in kqueue and PollWatcher. Changes: - Add event_kinds field to FsEventWatcher and StreamContextInfo - Pass event_kinds from Config through to the callback context - Filter events in callback_impl based on the mask - Add test for filtering behavior

Thread EventKindMask through ReadDirectoryChangesServer and start_read to filter events before delivery. Events that don't match the mask are silently dropped, while errors always pass through.

Change test infrastructure ChannelConfig::default() to use Config::default() which includes EventKindMask::ALL instead of CORE. This ensures tests cover all event types including Access events. Updated inotify tests to use wait_ordered() instead of wait_ordered_exact() where appropriate, since with ALL events we may get directory access events that are timing-dependent. Tests that check for absence of specific events now filter out Access events to focus on the behavior being tested.

kqueue uses userspace filtering via EventKindMask::matches(), only inotify has kernel-level support via WatchMask translation. Updated documentation in: - notify-types/src/event.rs: EventKindMask doc comment - notify/src/config.rs: with_event_kinds() doc comment

Use blocking recv_timeout instead of try_iter to avoid race condition between poll thread processing the message and test collecting events.

Recursive watches now always register for CREATE/MOVED_TO at the kernel level, then filter in userspace before delivery. This ensures subdirectory tracking works regardless of the user's EventKindMask.

JohnTitor · 2026-01-21T22:16:24Z

CI fails: https://github.com/notify-rs/notify/actions/runs/21216461719/job/61077502532?pr=736

withzombies · 2026-01-21T22:20:54Z

Sorry, I'm used to my git hooks enforcing that one but I don't have any setup on this repo. I fixed it.

JohnTitor

Thank you!

chris-morgan · 2026-02-18T18:08:22Z

notify-types/src/event.rs

+        const ALL_ACCESS = Self::ACCESS_OPEN.bits() | Self::ACCESS_CLOSE.bits() | Self::ACCESS_CLOSE_NOWRITE.bits();
+
+        /// Core events: create, remove, and all modify events.
+        /// This is the default and matches the current notify behavior (no access events).


This is the default

Fairly sure that’s an error, EventKindMask::default() returns ALL and Config::default() uses ALL.

I also don’t know what “current notify behavior” means in this context. But I don’t imagine most users want access events.

Good catch, fixed in #819.

But I don’t imagine most users want access events.

Yeah, likely. But I'd like to change it carefully as it's behavior change. Maybe we can consider changing if someone files a request (and receives positive reactions).

riberk reviewed Dec 23, 2025

View reviewed changes

withzombies requested a review from riberk December 23, 2025 20:36

JohnTitor reviewed Jan 15, 2026

View reviewed changes

JohnTitor reviewed Jan 16, 2026

View reviewed changes

notify/src/inotify.rs

Comment on lines -93 to +144

follow_links: bool,

config: &Config,

Copy link

Member

JohnTitor Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ditto

withzombies added 10 commits January 21, 2026 10:54

feat: add configurable EventKindMask for event filtering

5ae7a9f

docs: add EventKindMask filtering examples

80ad7ad

feat: add userspace EventKindMask filtering to Windows backend

bdbf8aa

Thread EventKindMask through ReadDirectoryChangesServer and start_read to filter events before delivery. Events that don't match the mask are silently dropped, while errors always pass through.

test: fix flaky poll_watcher_respects_event_kind_mask test

31d34ab

Use blocking recv_timeout instead of try_iter to avoid race condition between poll thread processing the message and test collecting events.

Enables recursive directory watching

133cc3b

Recursive watches now always register for CREATE/MOVED_TO at the kernel level, then filter in userspace before delivery. This ensures subdirectory tracking works regardless of the user's EventKindMask.

withzombies force-pushed the filter-access-events branch from a706125 to 133cc3b Compare January 21, 2026 16:00

withzombies requested a review from JohnTitor January 21, 2026 16:01

Fix formatting

37de409

JohnTitor approved these changes Jan 22, 2026

View reviewed changes

JohnTitor merged commit 47c3761 into notify-rs:main Jan 22, 2026
17 checks passed

chris-morgan reviewed Feb 18, 2026

View reviewed changes

Uh oh!

Comments

Conversation

withzombies commented Dec 14, 2025

Usage

Changes

Uh oh!

greged93 commented Dec 17, 2025

Uh oh!

withzombies commented Dec 17, 2025

Uh oh!

riberk Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

withzombies Dec 23, 2025

Choose a reason for hiding this comment

Uh oh!

JohnTitor Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

JohnTitor left a comment

Choose a reason for hiding this comment

Uh oh!

JohnTitor Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

JohnTitor commented Jan 21, 2026

Uh oh!

withzombies commented Jan 21, 2026

Uh oh!

JohnTitor left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chris-morgan Feb 18, 2026

Choose a reason for hiding this comment

Uh oh!

JohnTitor Feb 21, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants