windows-file-watcher 0.2.6

Memory-safe, queue-mediated Windows path-change watching over ReadDirectoryChangesW, with a coarse fallback.
Documentation
// Copyright (c) 2026 Mike Grier
//! Per-subscription routing within one coalesced directory watcher (D-6/D-7).
//!
//! A directory is watched once regardless of how many subscriptions target
//! entries within it (D-6). What a [`Route`] decides is which of a decoded
//! batch's records belong to *this* subscription. Two things vary:
//!
//! - **Reach**: a recursive directory subscription matches a record at any
//!   depth; a shallow one, or a file subscription, matches only a record with
//!   no path separator in its relative name -- a direct child of the directory
//!   actually opened.
//! - **Name**: a directory subscription matches every name within its reach; a
//!   file subscription (D-7) matches only its own leaf name. The comparison
//!   is on raw UTF-16 units via `win-text-sys`'s `compare_string_ordinal`,
//!   which is `CompareStringOrdinal`, folding case only when
//!   the directory itself is case-insensitive: the default Windows filesystem
//!   is case-insensitive but case-preserving, so `CreateFileW` accepts a
//!   target whose casing differs from the stored name, while a decoded
//!   notification always carries the name as actually stored -- an exact
//!   match would silently drop every one of those events, and an ASCII-only
//!   fold would still drop one whenever the differing case falls outside
//!   ASCII. On the rare directory that opts into per-directory case
//!   sensitivity (`fsutil file setCaseSensitiveInfo`), folding at all would be
//!   wrong the other way -- `A.txt` and `a.txt` genuinely name different
//!   files there, so the comparison is exact instead (PR #20 review
//!   response).
//!
//! A desync is never filtered by scope: it means "you may have missed something
//! in this directory," which is equally true for every subscription within it.

use std::cmp::Ordering;

use win_text_sys::{Case, CompareStringOrdinalError, compare_string_ordinal};
use wtf_string::Wtf16String;

use crate::notify::Change;
use crate::queue::{Sender, StandingSlot, WatchId};
use crate::watch::{RetryMode, VolumeChangePolicy};

/// The backslash that separates path components in a relative name.
const SEPARATOR: u16 = b'\\' as u16;

/// What part of a directory one subscription wants.
#[derive(Clone, Debug, PartialEq, Eq)]
pub(crate) enum RouteScope {
    /// The directory itself. `subtree` reaches every depth; otherwise only
    /// direct children.
    Directory {
        /// Whether nested changes are reported as well.
        subtree: bool,
    },
    /// One file within the directory (D-7): always a direct child, matched by
    /// its exact leaf name. Never recursive -- a file has no subtree.
    File {
        /// The file's name within the directory that was actually opened.
        leaf: Wtf16String,
    },
}

impl RouteScope {
    /// Whether this scope needs the kernel's own `bWatchSubtree` reach.
    ///
    /// Only a recursive directory subscription does. A file subscription is
    /// always a direct child of the directory that is opened, regardless of
    /// whether some *other* subscription on the same directory needs subtree
    /// reach for its own purposes.
    pub(crate) fn needs_kernel_subtree(&self) -> bool {
        matches!(self, RouteScope::Directory { subtree: true })
    }

    /// Whether `name` -- raw UTF-16 units, exactly as the kernel reported them --
    /// belongs to this scope. `case_sensitive` is this directory's own
    /// case-sensitivity (PR #20 review response, [`crate::directory::DirectoryHandle::is_case_sensitive`]):
    /// a leaf-name match must fold case only when the directory itself is
    /// case-insensitive, or a genuinely distinct file on a case-sensitive
    /// directory would be matched to the wrong route.
    fn matches(&self, name: &[u16], case_sensitive: bool) -> bool {
        match self {
            RouteScope::Directory { subtree: true } => true,
            RouteScope::Directory { subtree: false } => is_direct_child(name),
            RouteScope::File { leaf } => {
                is_direct_child(name) && names_match(name, leaf.as_units(), case_sensitive)
            }
        }
    }
}

/// Whether `name` names something directly within the watched directory, rather
/// than nested inside a subdirectory of it.
fn is_direct_child(name: &[u16]) -> bool {
    !name.contains(&SEPARATOR)
}

/// Whether `a` and `b` are the same name (`is_direct_child` above establishes
/// reach; this decides identity within it, for [`RouteScope::File`]).
///
/// `case_sensitive` selects exact ordinal comparison (a case-sensitive
/// directory, a per-directory NTFS opt-in feature, e.g. via `fsutil file
/// setCaseSensitiveInfo`, where `A.txt` and `a.txt` genuinely name different
/// files) or `win-text-sys`'s `compare_string_ordinal` with `Case::Insensitive` -- the OS's own
/// ordinal (per-UTF-16-unit) case folding -- for the overwhelmingly common
/// case-insensitive-but-case-preserving directory. Either way this is never
/// an ASCII-only fold: that silently drops a match whenever a subscription's
/// leaf name and the kernel's stored spelling differ only in a non-ASCII
/// letter's case (e.g. a stored `E9.txt` opened through a subscription
/// spelling `C9.txt`), which is exactly the kind of event this crate's
/// completeness contract (D-77) promises never to drop.
fn names_match(a: &[u16], b: &[u16], case_sensitive: bool) -> bool {
    let case = if case_sensitive {
        Case::Sensitive
    } else {
        Case::Insensitive
    };
    equal_from(compare_string_ordinal(a, b, case), a, b)
}

/// What a comparison's result says about whether `a` and `b` are the same name.
///
/// Only an `Equal` is a match, and a failure the call reports is not one. A name
/// too long for the call's count, which no name is (that is more than 2^31 UTF-16
/// units), is compared exactly: truncating the count would compare a prefix, and
/// two names that share one would match. Reaching that arm takes a slice that
/// long, so it is tested through the result.
fn equal_from(result: Result<Ordering, CompareStringOrdinalError>, a: &[u16], b: &[u16]) -> bool {
    match result {
        Ok(ordering) => ordering == Ordering::Equal,
        Err(CompareStringOrdinalError::TooLong { .. }) => a == b,
        Err(CompareStringOrdinalError::Call(_)) => false,
    }
}

/// One subscription's place within a coalesced directory watcher: what it wants
/// and where its notifications go.
pub(crate) struct Route {
    /// The identifier every notification delivered through this route carries.
    pub(crate) watch: WatchId,
    /// What within the directory this subscription wants.
    pub(crate) scope: RouteScope,
    /// This subscription's session sink (D-11).
    pub(crate) sink: Sender,
    /// How this subscription wants faults recovered (D-27).
    pub(crate) retry: RetryMode,
    /// Whether this subscription wants `Suspended`/`Resumed`/`Established`
    /// (D-13).
    pub(crate) report_liveness: bool,
    /// Whether this subscription wants to confirm a volume change on reopen
    /// (D-78/M12).
    pub(crate) on_volume_change: VolumeChangePolicy,
    /// The standing reservation for this subscription's fault question or
    /// volume-change question (D-27/D-28/M12), present iff it can ever need
    /// one (`retry == Interactive` or `on_volume_change == Confirm`).
    /// `report_liveness` alone never creates one: `Suspended`/`Resumed`/
    /// `Established` all ride the ordinary best-effort queue like any other
    /// observation (D-57).
    pub(crate) fault_slot: Option<StandingSlot>,
}

impl Route {
    /// The subset of `changes` this route should see, in the order they arrived.
    ///
    /// Cloned rather than referenced: more than one route can match an
    /// overlapping subset (a subtree route and a file route both watching the
    /// same directory, say), so no single route may claim exclusive ownership of
    /// the decoded batch. `case_sensitive` is the directory's own
    /// case-sensitivity (PR #20 review response); see
    /// [`RouteScope::matches`].
    pub(crate) fn select(&self, changes: &[Change], case_sensitive: bool) -> Vec<Change> {
        changes
            .iter()
            .filter(|change| self.scope.matches(change.name.as_wide(), case_sensitive))
            .cloned()
            .collect()
    }
}

impl std::fmt::Debug for Route {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Route")
            .field("watch", &self.watch)
            .field("scope", &self.scope)
            .field("retry", &self.retry)
            .field("report_liveness", &self.report_liveness)
            .finish_non_exhaustive()
    }
}

#[cfg(test)]
mod tests;