Skip to main content

kizz_core/
check.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The cache check: comparing a step's recorded observations with the file system.
6//!
7//! [`check`] compares every recorded observation with the current state of its
8//! path, concurrently, and lists every [`Difference`]. The step is a cache hit only
9//! when there is none. The rules of "Cache check":
10//!
11//! * A regular file or a directory whose type, permission bits, or owner differ has
12//!   changed, found without hashing, whatever its content: a command may check them. The
13//!   permission bits are the low twelve bits of the mode, the set-user-ID, set-group-ID,
14//!   and sticky bits included.
15//! * A regular file that was read has a hash. A different size is a change, found without
16//!   hashing. The same size and the same metadata (modification and change times, inode,
17//!   device, mode, and owner) is unchanged. The same size, mode, and owner with different
18//!   times, inode, or device is hashed: an equal hash means unchanged, and the check
19//!   returns the new metadata so the record can store it.
20//! * When the recorded modification time is within two seconds of when the record was
21//!   written, or later, metadata cannot prove the file unchanged, so it is hashed even
22//!   when the metadata matches, as git does for racily clean files.
23//! * A regular file that was not read has no hash: any difference in size or metadata,
24//!   the owner included, is a change.
25//! * A directory's mode and owner are always compared. A listed directory is listed again
26//!   and compared by its entries, in the order the file system returns them: an equal
27//!   listing hash is unchanged; otherwise an equal hash of the sorted entries means only
28//!   the order changed, and a different one that the entries changed, naming those that
29//!   appeared, disappeared, or changed type when both listings kept their entries.
30//! * For a step run with `timestamps`, a regular file that was read or run, or a
31//!   directory that was read, listed, or checked, whose modification or change time
32//!   differs has changed, found without hashing, after its permission bits and owner and,
33//!   for a file, its size. A file that was only checked or written already compares its
34//!   times with the rest of its metadata. Access times are never compared, and neither
35//!   are the times of a symbolic link itself: its pointee follows the rule. Without
36//!   `timestamps`, the bytes decide for a file that was read, and directory times are
37//!   never compared.
38//! * A symbolic link is compared by its target, then by the state of what it points to.
39//! * Devices, FIFOs, and sockets are compared by type.
40//! * A path whose extended attributes were recorded is compared by them too, once the
41//!   rest of its state matches: they are read again through the attribute query of the
42//!   tracer interface (see [`record_attributes`]), and an attribute that appeared,
43//!   disappeared, or changed value, of the path itself or, for a symbolic link, of what
44//!   it points to, is a change.
45//! * Untracked paths under `/proc` and `/sys` are never compared. Tracked ones are read
46//!   and hashed again, without the cache of file states, because their metadata says
47//!   nothing about their content. A symbolic link that leads into `/proc` or `/sys` is
48//!   compared by its target, and its untracked pointee is not compared.
49//!
50//! Hashes of files that were not tracked go through the build's [`FileStates`], so a
51//! file is hashed once per build.
52
53use std::{
54    collections::BTreeMap,
55    fs::{self, Metadata},
56    os::unix::fs::MetadataExt as _,
57    path::Path,
58};
59
60use kizz_store::{
61    AccessBits, Attribute, Attributes, Change, ContentHash, Difference, DirEntry, EntryKind,
62    FileMeta, Listing, Observation, Owner, PathState, Times, permission_bits,
63};
64use kizz_trace::Tracer;
65use rayon::iter::{IntoParallelRefIterator as _, ParallelIterator as _};
66
67use crate::{
68    observe::{self, failed, file_meta, list, record_attributes, special_kind},
69    states::FileStates,
70};
71
72/// How close to when a record was written a recorded modification time must be,
73/// in nanoseconds, for metadata not to prove a file unchanged: two seconds.
74pub const RACY_WINDOW_NANOS: i64 = 2_000_000_000;
75
76/// The result of comparing a step's recorded observations with the file system.
77#[derive(Debug, Clone, PartialEq, Eq, Default)]
78pub struct Checked {
79    /// Every recorded path that changed, sorted by path. The step is a cache hit
80    /// only when this is empty.
81    pub differences: Vec<Difference>,
82    /// The recorded observations, with the new metadata of every file whose metadata
83    /// changed while its content did not.
84    pub observations: Vec<Observation>,
85    /// Whether the record should be written again: a file's metadata changed while
86    /// its content did not, or a racily clean file was hashed and found unchanged.
87    pub refresh: bool,
88}
89
90impl Checked {
91    /// Whether nothing changed, so the step is a cache hit.
92    #[must_use]
93    pub fn is_hit(&self) -> bool {
94        self.differences.is_empty()
95    }
96}
97
98/// How one recorded path compares with the file system.
99#[derive(Debug, Clone, PartialEq, Eq)]
100enum Compared {
101    /// Unchanged, proved by metadata or without needing a hash.
102    Same,
103    /// Unchanged, proved by hashing a racily clean file whose metadata matched.
104    Verified,
105    /// Unchanged content with new metadata, which this state holds.
106    Refreshed(PathState),
107    /// Changed.
108    Changed(Change),
109}
110
111/// What every comparison of one check shares.
112#[derive(Debug, Clone, Copy)]
113struct Context<'a> {
114    /// Recorded modification times at or after this time, in nanoseconds since the
115    /// Unix epoch, cannot prove a file unchanged.
116    racy_from: i64,
117    /// Whether the step was run with `timestamps`.
118    timestamps: bool,
119    /// The build's file states and hashes.
120    states: &'a FileStates,
121}
122
123/// Whether a step run with `timestamps` compares the times of a path it touched
124/// with `access`: one it read, ran, listed, or checked, and not one it only wrote.
125const fn uses(access: AccessBits) -> bool {
126    (access.0 & !AccessBits::WRITE) != 0
127}
128
129/// The timestamp change from `old` to `new`, or `None` when they match.
130fn times_change(
131    old: Times,
132    new: Times,
133) -> Option<Change> {
134    (old != new).then_some(Change::Timestamps { old, new })
135}
136
137/// Compare every observation in `observations`, recorded with the record written at
138/// `recorded_at_nanos`, with the file system, concurrently on the worker pool of
139/// `states`, hashing through `states`. With `timestamps`, the times of what the step
140/// read, ran, listed, or checked are compared too. Recorded extended attributes are
141/// read again through the attribute query of `tracer`.
142#[must_use]
143pub fn check(
144    observations: &[Observation],
145    recorded_at_nanos: u64,
146    timestamps: bool,
147    states: &FileStates,
148    tracer: &dyn Tracer,
149) -> Checked {
150    let context = Context {
151        racy_from: i64::try_from(recorded_at_nanos)
152            .unwrap_or(i64::MAX)
153            .saturating_sub(RACY_WINDOW_NANOS),
154        timestamps,
155        states,
156    };
157    let compared: Vec<Compared> = states.pool().install(|| {
158        observations
159            .par_iter()
160            .map(|observation| {
161                let compared = compare(
162                    &observation.path,
163                    &observation.state,
164                    false,
165                    observation.tracked,
166                    Context {
167                        timestamps: context.timestamps && uses(observation.access),
168                        ..context
169                    },
170                );
171                match (&compared, &observation.attributes) {
172                    (Compared::Changed(_), _) | (_, None) => compared,
173                    (_, Some(recorded)) => {
174                        let current = record_attributes(&observation.path, tracer);
175                        attributes_change(recorded, &current).map_or(compared, Compared::Changed)
176                    },
177                }
178            })
179            .collect()
180    });
181    let mut checked = Checked {
182        observations: Vec::with_capacity(observations.len()),
183        ..Checked::default()
184    };
185    for (observation, compared) in observations.iter().zip(compared) {
186        let mut observation = observation.clone();
187        match compared {
188            Compared::Same => {},
189            Compared::Verified => checked.refresh = true,
190            Compared::Refreshed(state) => {
191                observation.state = state;
192                checked.refresh = true;
193            },
194            Compared::Changed(change) => {
195                checked.differences.push(Difference {
196                    path: observation.path.clone(),
197                    change,
198                });
199            },
200        }
201        checked.observations.push(observation);
202    }
203    checked
204}
205
206/// The change from the recorded extended attributes `old` of a path to its
207/// `current` ones, or `None` when they match: the attributes that appeared,
208/// disappeared, or changed value, of the path itself and, for a symbolic link, of
209/// what it points to, each sorted by name. Attributes that could not be read count
210/// as none, so a change only in whether they could be read lists no attribute.
211fn attributes_change(
212    old: &Attributes,
213    current: &Attributes,
214) -> Option<Change> {
215    if old == current {
216        return None;
217    }
218    let mut appeared = Vec::new();
219    let mut disappeared = Vec::new();
220    let mut changed = Vec::new();
221    let pairs = [
222        (old.own.as_deref(), current.own.as_deref()),
223        (old.pointee.as_deref(), current.pointee.as_deref()),
224    ];
225    for (old, current) in pairs {
226        let hashes = |attributes: Option<&[Attribute]>| -> BTreeMap<Vec<u8>, ContentHash> {
227            attributes
228                .into_iter()
229                .flatten()
230                .map(|attribute| (attribute.name.clone(), attribute.hash))
231                .collect()
232        };
233        let old = hashes(old);
234        let current = hashes(current);
235        for (name, &hash) in &current {
236            let attribute = Attribute {
237                name: name.clone(),
238                hash,
239            };
240            match old.get(name) {
241                None => appeared.push(attribute),
242                Some(recorded) if *recorded != hash => changed.push(attribute),
243                Some(_) => {},
244            }
245        }
246        for (name, &hash) in &old {
247            if !current.contains_key(name) {
248                disappeared.push(Attribute {
249                    name: name.clone(),
250                    hash,
251                });
252            }
253        }
254    }
255    for list in [&mut appeared, &mut disappeared, &mut changed] {
256        list.sort();
257    }
258    Some(Change::Attributes {
259        appeared,
260        disappeared,
261        changed,
262    })
263}
264
265/// Compare the recorded state `recorded` of `path` with its current state,
266/// following a final symbolic link when `follow` is set. `tracked` marks a `/proc`
267/// or `/sys` path that a `track` pattern matched.
268fn compare(
269    path: &Path,
270    recorded: &PathState,
271    follow: bool,
272    tracked: bool,
273    context: Context<'_>,
274) -> Compared {
275    if matches!(recorded, PathState::Untracked) {
276        return Compared::Same;
277    }
278    let metadata = if follow {
279        fs::metadata(path)
280    } else {
281        fs::symlink_metadata(path)
282    };
283    let metadata = match metadata {
284        Ok(metadata) => metadata,
285        Err(error) => return compare_missing(recorded, &failed(&error)),
286    };
287    let file_type = metadata.file_type();
288    match recorded {
289        PathState::Absent => Compared::Changed(Change::Appeared),
290        PathState::File { meta, hash } if file_type.is_file() => {
291            compare_file(path, meta, hash.as_ref(), &metadata, tracked, context)
292        },
293        PathState::Directory {
294            mode,
295            owner,
296            listing,
297            times,
298        } if file_type.is_dir() => {
299            if let Some(change) =
300                access_change(*mode, *owner, metadata.mode(), observe::owner(&metadata))
301            {
302                return Compared::Changed(change);
303            }
304            if context.timestamps
305                && let Some(change) = times_change(*times, observe::times(&metadata))
306            {
307                return Compared::Changed(change);
308            }
309            let Some(listing) = listing else {
310                return Compared::Same;
311            };
312            match list(path) {
313                Ok(current) => {
314                    listing_change(listing, &current).map_or(Compared::Same, Compared::Changed)
315                },
316                Err(_) => Compared::Changed(Change::Type),
317            }
318        },
319        PathState::Symlink { target, pointee } if file_type.is_symlink() => {
320            match fs::read_link(path) {
321                Ok(current) if current == *target => {
322                    match compare(path, pointee, true, tracked, context) {
323                        Compared::Refreshed(state) => {
324                            Compared::Refreshed(PathState::Symlink {
325                                target: target.clone(),
326                                pointee: Box::new(state),
327                            })
328                        },
329                        other => other,
330                    }
331                },
332                Ok(current) => {
333                    Compared::Changed(Change::LinkTarget {
334                        old: target.clone(),
335                        new: current,
336                    })
337                },
338                Err(_) => Compared::Changed(Change::Type),
339            }
340        },
341        PathState::Special { kind }
342            if !file_type.is_file()
343                && !file_type.is_dir()
344                && !file_type.is_symlink()
345                && special_kind(file_type) == *kind =>
346        {
347            Compared::Same
348        },
349        _ => Compared::Changed(Change::Type),
350    }
351}
352
353/// Compare the recorded state `recorded` with `current`, the state of a path whose
354/// metadata could not be read: absent, or inaccessible.
355fn compare_missing(
356    recorded: &PathState,
357    current: &PathState,
358) -> Compared {
359    match (recorded, current) {
360        (PathState::Absent, PathState::Absent) => Compared::Same,
361        (PathState::Absent, _) => Compared::Changed(Change::Appeared),
362        (_, PathState::Absent) => Compared::Changed(Change::Disappeared),
363        (PathState::Inaccessible { errno }, PathState::Inaccessible { errno: now })
364            if errno == now =>
365        {
366            Compared::Same
367        },
368        _ => Compared::Changed(Change::Type),
369    }
370}
371
372/// The change between a recorded mode `old_mode` and owner `old_owner` of a regular
373/// file or a directory and its current mode `new_mode` and owner `new_owner`, when
374/// its type is the same: different permission bits, then a different owner, or
375/// `None` when both match.
376fn access_change(
377    old_mode: u32,
378    old_owner: Owner,
379    new_mode: u32,
380    new_owner: Owner,
381) -> Option<Change> {
382    let (old, new) = (permission_bits(old_mode), permission_bits(new_mode));
383    if old != new {
384        return Some(Change::Permissions { old, new });
385    }
386    (old_owner != new_owner).then_some(Change::Owner {
387        old: old_owner,
388        new: new_owner,
389    })
390}
391
392/// The change from the recorded listing `old` of a directory to its `current`
393/// listing, or `None` when the entries and their order match: an equal listing hash
394/// is unchanged; otherwise an equal sorted hash is an order change, and a different
395/// one is an entries change.
396fn listing_change(
397    old: &Listing,
398    current: &Listing,
399) -> Option<Change> {
400    if current.hash == old.hash {
401        None
402    } else if current.sorted_hash == old.sorted_hash {
403        Some(Change::Order)
404    } else {
405        Some(entries_change(
406            old.entries.as_deref(),
407            current.entries.as_deref(),
408        ))
409    }
410}
411
412/// The entries change from the recorded entries `old` to the `current` ones: the
413/// entries that appeared, that disappeared, and whose type changed, each sorted by
414/// name, or none of them when either listing kept no entries.
415fn entries_change(
416    old: Option<&[DirEntry]>,
417    current: Option<&[DirEntry]>,
418) -> Change {
419    let mut appeared = Vec::new();
420    let mut disappeared = Vec::new();
421    let mut retyped = Vec::new();
422    if let (Some(old), Some(current)) = (old, current) {
423        let kinds = |entries: &[DirEntry]| -> BTreeMap<Vec<u8>, EntryKind> {
424            entries
425                .iter()
426                .map(|entry| (entry.name.clone(), entry.kind))
427                .collect()
428        };
429        let old = kinds(old);
430        let current = kinds(current);
431        for (name, &kind) in &current {
432            let entry = DirEntry {
433                name: name.clone(),
434                kind,
435            };
436            match old.get(name) {
437                None => appeared.push(entry),
438                Some(&recorded) if recorded != kind => retyped.push(entry),
439                Some(_) => {},
440            }
441        }
442        for (name, &kind) in &old {
443            if !current.contains_key(name) {
444                disappeared.push(DirEntry {
445                    name: name.clone(),
446                    kind,
447                });
448            }
449        }
450    }
451    Change::Entries {
452        appeared,
453        disappeared,
454        retyped,
455    }
456}
457
458/// Compare a regular file at `path`, recorded with `meta` and, when it was read,
459/// `hash`, with its current `metadata`. Its permission bits and owner come first,
460/// so a refresh of its metadata never hides a change of either; with `timestamps`,
461/// the times of a file that was read come next, after its size, and before any hash.
462fn compare_file(
463    path: &Path,
464    meta: &FileMeta,
465    hash: Option<&ContentHash>,
466    metadata: &Metadata,
467    tracked: bool,
468    context: Context<'_>,
469) -> Compared {
470    let current = file_meta(metadata);
471    if let Some(change) = access_change(meta.mode, meta.owner, current.mode, current.owner) {
472        return Compared::Changed(change);
473    }
474    if tracked {
475        if hash.is_some()
476            && context.timestamps
477            && let Some(change) = times_change(meta.times(), current.times())
478        {
479            return Compared::Changed(change);
480        }
481        return match context.states.hash_uncached(path) {
482            Ok(now) if Some(&now) == hash => Compared::Same,
483            Ok(_) => Compared::Changed(Change::Content),
484            Err(_) => Compared::Changed(Change::Type),
485        };
486    }
487    if current.size != meta.size {
488        return Compared::Changed(Change::Size {
489            old: meta.size,
490            new: current.size,
491        });
492    }
493    let Some(hash) = hash else {
494        return if current == *meta {
495            Compared::Same
496        } else {
497            Compared::Changed(Change::Metadata)
498        };
499    };
500    if context.timestamps
501        && let Some(change) = times_change(meta.times(), current.times())
502    {
503        return Compared::Changed(change);
504    }
505    let racy = meta.mtime_nanos >= context.racy_from;
506    if current == *meta && !racy {
507        return Compared::Same;
508    }
509    match context.states.hash(path, &current) {
510        Ok(now) if now == *hash => {
511            if current == *meta {
512                Compared::Verified
513            } else {
514                Compared::Refreshed(PathState::File {
515                    meta: current,
516                    hash: Some(now),
517                })
518            }
519        },
520        Ok(_) => Compared::Changed(Change::Content),
521        Err(_) => Compared::Changed(Change::Type),
522    }
523}
524
525/// Unit tests for the comparison rules.
526#[cfg(test)]
527#[allow(
528    clippy::disallowed_macros,
529    clippy::disallowed_methods,
530    reason = "test code: the tests assert and lock"
531)]
532mod tests {
533    use std::{
534        fs::{File, FileTimes},
535        io,
536        os::unix::fs::{PermissionsExt as _, symlink},
537        path::PathBuf,
538        sync::{Mutex, PoisonError},
539        time::{Duration, SystemTime, UNIX_EPOCH},
540    };
541
542    use kizz_store::{AccessBits, MAX_LISTED_NAMES, SpecialKind};
543    use kizz_trace::{
544        AccessKind, AccessKinds, Cancellation, EchoSink, ExtendedAttributes, MachineState,
545        RunRequest, RunResult, TraceError,
546    };
547
548    use super::*;
549    use crate::{
550        observe::{access_bits, path_state},
551        pool::WorkerPool,
552    };
553
554    /// An empty cache of file states, on a worker pool of its own.
555    fn fresh_states() -> FileStates {
556        FileStates::new(WorkerPool::new().unwrap())
557    }
558
559    /// A fake tracer that runs nothing, whose attribute query finds no attributes
560    /// anywhere, for the tests that record none, and whose machine query knows no
561    /// part, because the cache check reads no machine state.
562    struct NoAttributes;
563
564    impl Tracer for NoAttributes {
565        fn run(
566            &self,
567            _request: &RunRequest,
568            _echo: &dyn EchoSink,
569            _cancel: &Cancellation,
570        ) -> Result<RunResult, TraceError> {
571            Err(TraceError::Tracer {
572                message: "the fake runs nothing".to_owned(),
573                source: None,
574            })
575        }
576
577        fn extended_attributes(
578            &self,
579            _path: &Path,
580            _follow: bool,
581        ) -> io::Result<ExtendedAttributes> {
582            Ok(ExtendedAttributes::new())
583        }
584
585        fn machine_state(
586            &self,
587            _cwd: &Path,
588        ) -> MachineState {
589            MachineState::default()
590        }
591    }
592
593    /// A fake tracer that runs nothing, and whose attribute query answers with the
594    /// attributes that a test sets for each path, with and without following a
595    /// final link, and fails with `NotFound` for a path that it knows nothing of.
596    #[derive(Default)]
597    struct FakeAttributes {
598        /// The attributes of each path, by the path and whether a final link is
599        /// followed.
600        attributes: Mutex<BTreeMap<(PathBuf, bool), ExtendedAttributes>>,
601    }
602
603    impl FakeAttributes {
604        /// Set the attributes of `path`, with or without following a final link, to
605        /// `pairs` of a name and a value.
606        fn set(
607            &self,
608            path: &Path,
609            follow: bool,
610            pairs: &[(&str, &str)],
611        ) {
612            let attributes = pairs
613                .iter()
614                .map(|(name, value)| (name.as_bytes().to_vec(), value.as_bytes().to_vec()))
615                .collect();
616            self.attributes
617                .lock()
618                .unwrap_or_else(PoisonError::into_inner)
619                .insert((path.to_path_buf(), follow), attributes);
620        }
621    }
622
623    impl Tracer for FakeAttributes {
624        fn run(
625            &self,
626            request: &RunRequest,
627            echo: &dyn EchoSink,
628            cancel: &Cancellation,
629        ) -> Result<RunResult, TraceError> {
630            NoAttributes.run(request, echo, cancel)
631        }
632
633        fn extended_attributes(
634            &self,
635            path: &Path,
636            follow: bool,
637        ) -> io::Result<ExtendedAttributes> {
638            self.attributes
639                .lock()
640                .unwrap_or_else(PoisonError::into_inner)
641                .get(&(path.to_path_buf(), follow))
642                .cloned()
643                .ok_or_else(|| io::Error::from(io::ErrorKind::NotFound))
644        }
645
646        fn machine_state(
647            &self,
648            cwd: &Path,
649        ) -> MachineState {
650            NoAttributes.machine_state(cwd)
651        }
652    }
653
654    /// A temporary directory with helpers to record and check observations.
655    struct Dir {
656        /// The directory.
657        dir: tempfile::TempDir,
658        /// The cache of file states and hashes.
659        states: FileStates,
660    }
661
662    impl Dir {
663        /// A new empty directory.
664        fn new() -> Self {
665            Self {
666                dir: tempfile::tempdir().unwrap(),
667                states: fresh_states(),
668            }
669        }
670
671        /// The path of `name` in the directory.
672        fn path(
673            &self,
674            name: &str,
675        ) -> PathBuf {
676            self.dir.path().join(name)
677        }
678
679        /// Write `content` to `name` with a modification time an hour ago.
680        fn write_old(
681            &self,
682            name: &str,
683            content: &str,
684        ) {
685            let path = self.path(name);
686            fs::write(&path, content).unwrap();
687            age(&path);
688        }
689
690        /// The observation of `name`, touched with `kind`.
691        fn observe(
692            &self,
693            name: &str,
694            kind: AccessKind,
695        ) -> Observation {
696            let path = self.path(name);
697            Observation {
698                state: path_state(&path, AccessKinds::only(kind), false, &self.states),
699                path,
700                access: access_bits(AccessKinds::only(kind)),
701                tracked: false,
702                attributes: None,
703            }
704        }
705    }
706
707    /// Set the modification time of `path` to an hour ago.
708    fn age(path: &Path) {
709        let hour_ago = SystemTime::now()
710            .checked_sub(Duration::from_secs(3_600))
711            .unwrap();
712        File::options()
713            .write(true)
714            .open(path)
715            .unwrap()
716            .set_times(FileTimes::new().set_modified(hour_ago))
717            .unwrap();
718    }
719
720    /// Now, in nanoseconds since the Unix epoch.
721    fn now() -> u64 {
722        u64::try_from(
723            SystemTime::now()
724                .duration_since(UNIX_EPOCH)
725                .unwrap()
726                .as_nanos(),
727        )
728        .unwrap()
729    }
730
731    /// The changes `check` finds.
732    fn changes(checked: &Checked) -> Vec<Change> {
733        checked
734            .differences
735            .iter()
736            .map(|difference| difference.change.clone())
737            .collect()
738    }
739
740    #[test]
741    fn unchanged_paths_match_without_hashing() {
742        let dir = Dir::new();
743        dir.write_old("read", "content");
744        dir.write_old("checked", "content");
745        fs::create_dir(dir.path("listed")).unwrap();
746        let observations = vec![
747            dir.observe("read", AccessKind::Read),
748            dir.observe("checked", AccessKind::Probe),
749            dir.observe("listed", AccessKind::List),
750            dir.observe("missing", AccessKind::Probe),
751        ];
752        assert_eq!(dir.states.files_hashed(), 1);
753        let states = fresh_states();
754        let checked = check(&observations, now(), false, &states, &NoAttributes);
755        assert!(checked.is_hit(), "{checked:?}");
756        assert!(!checked.refresh);
757        assert_eq!(checked.observations, observations);
758        assert_eq!(states.files_hashed(), 0);
759    }
760
761    #[test]
762    fn sizes_are_compared_before_hashes() {
763        let dir = Dir::new();
764        dir.write_old("read", "content");
765        let observations = vec![dir.observe("read", AccessKind::Read)];
766        fs::write(dir.path("read"), "longer content").unwrap();
767        let states = fresh_states();
768        let checked = check(&observations, now(), false, &states, &NoAttributes);
769        assert_eq!(changes(&checked), [Change::Size { old: 7, new: 14 }]);
770        assert_eq!(states.files_hashed(), 0);
771
772        fs::write(dir.path("read"), "CONTENT").unwrap();
773        let checked = check(&observations, now(), false, &states, &NoAttributes);
774        assert_eq!(changes(&checked), [Change::Content]);
775        assert_eq!(states.files_hashed(), 1);
776    }
777
778    #[test]
779    fn new_metadata_with_the_same_content_is_refreshed() {
780        let dir = Dir::new();
781        dir.write_old("read", "content");
782        let observations = vec![dir.observe("read", AccessKind::Read)];
783        fs::write(dir.path("read"), "content").unwrap();
784        let states = fresh_states();
785        let checked = check(&observations, now(), false, &states, &NoAttributes);
786        assert!(checked.is_hit());
787        assert!(checked.refresh);
788        assert_eq!(states.files_hashed(), 1);
789        let current = path_state(
790            &dir.path("read"),
791            AccessKinds::only(AccessKind::Read),
792            false,
793            &states,
794        );
795        assert_eq!(checked.observations[0].state, current);
796        assert_ne!(checked.observations[0].state, observations[0].state);
797    }
798
799    #[test]
800    fn racily_clean_files_are_hashed() {
801        let dir = Dir::new();
802        fs::write(dir.path("fresh"), "content").unwrap();
803        let observations = vec![dir.observe("fresh", AccessKind::Read)];
804        let states = fresh_states();
805        let checked = check(&observations, now(), false, &states, &NoAttributes);
806        assert!(checked.is_hit());
807        assert!(checked.refresh);
808        assert_eq!(checked.observations, observations);
809        assert_eq!(states.files_hashed(), 1);
810    }
811
812    #[test]
813    fn files_that_were_not_read_compare_by_metadata() {
814        let dir = Dir::new();
815        dir.write_old("checked", "content");
816        fs::set_permissions(dir.path("checked"), fs::Permissions::from_mode(0o644)).unwrap();
817        let observations = vec![dir.observe("checked", AccessKind::Probe)];
818        set_modified(&dir.path("checked"), 7_200);
819        let states = fresh_states();
820        let checked = check(&observations, now(), false, &states, &NoAttributes);
821        assert_eq!(changes(&checked), [Change::Metadata]);
822        fs::write(dir.path("checked"), "longer content").unwrap();
823        let checked = check(&observations, now(), false, &states, &NoAttributes);
824        assert_eq!(changes(&checked), [Change::Size { old: 7, new: 14 }]);
825        fs::set_permissions(dir.path("checked"), fs::Permissions::from_mode(0o600)).unwrap();
826        let checked = check(&observations, now(), false, &states, &NoAttributes);
827        assert_eq!(changes(&checked), [Change::Permissions {
828            old: 0o644,
829            new: 0o600,
830        }]);
831        assert_eq!(states.files_hashed(), 0);
832    }
833
834    /// Set the modification time of `path`, a file or a directory, to `seconds`
835    /// seconds ago.
836    fn set_modified(
837        path: &Path,
838        seconds: u64,
839    ) {
840        let then = SystemTime::now()
841            .checked_sub(Duration::from_secs(seconds))
842            .unwrap();
843        File::open(path)
844            .unwrap()
845            .set_times(FileTimes::new().set_modified(then))
846            .unwrap();
847    }
848
849    /// The recorded times of `observation`, a regular file, a directory, or a link to
850    /// either.
851    fn recorded_times(observation: &Observation) -> Times {
852        match &observation.state {
853            PathState::File { meta, .. } => meta.times(),
854            PathState::Directory { times, .. } => *times,
855            PathState::Symlink { pointee, .. } => {
856                recorded_times(&Observation {
857                    state: (**pointee).clone(),
858                    ..observation.clone()
859                })
860            },
861            other => panic!("no times in {other:?}"),
862        }
863    }
864
865    /// The timestamp change from what `observation` recorded to the current times of
866    /// `path`, following symbolic links.
867    fn timestamps_change(
868        observation: &Observation,
869        path: &Path,
870    ) -> Change {
871        Change::Timestamps {
872            old: recorded_times(observation),
873            new: observe::times(&fs::metadata(path).unwrap()),
874        }
875    }
876
877    #[test]
878    fn timestamps_are_compared_without_hashing_only_with_the_option() {
879        let dir = Dir::new();
880        dir.write_old("read", "content");
881        dir.write_old("checked", "content");
882        fs::create_dir(dir.path("listed")).unwrap();
883        fs::create_dir(dir.path("opened")).unwrap();
884        fs::create_dir(dir.path("written")).unwrap();
885        symlink("read", dir.path("link")).unwrap();
886        let observations = vec![
887            dir.observe("checked", AccessKind::Probe),
888            dir.observe("link", AccessKind::Read),
889            dir.observe("listed", AccessKind::List),
890            dir.observe("opened", AccessKind::Probe),
891            dir.observe("read", AccessKind::Read),
892            dir.observe("written", AccessKind::Write),
893        ];
894        for name in ["read", "checked", "listed", "opened", "written"] {
895            set_modified(&dir.path(name), 7_200);
896        }
897
898        // Without the option, the bytes decide for a read file, which is hashed, once
899        // through the link and once by its own path, and refreshed; directory times are
900        // never compared; a checked file compares all of its metadata, as before.
901        let states = fresh_states();
902        let checked = check(&observations, now(), false, &states, &NoAttributes);
903        assert_eq!(changes(&checked), [Change::Metadata]);
904        assert!(checked.refresh);
905        assert_eq!(states.files_hashed(), 2);
906
907        // With it, every time that changed is the change, found without hashing; a
908        // directory that was only written is not compared by its times.
909        let states = fresh_states();
910        let checked = check(&observations, now(), true, &states, &NoAttributes);
911        assert_eq!(changes(&checked), [
912            Change::Metadata,
913            timestamps_change(&observations[1], &dir.path("read")),
914            timestamps_change(&observations[2], &dir.path("listed")),
915            timestamps_change(&observations[3], &dir.path("opened")),
916            timestamps_change(&observations[4], &dir.path("read")),
917        ]);
918        assert!(!checked.refresh);
919        assert_eq!(states.files_hashed(), 0);
920    }
921
922    #[test]
923    fn with_the_option_unchanged_times_and_a_new_link_are_a_hit() {
924        let dir = Dir::new();
925        dir.write_old("read", "content");
926        fs::create_dir(dir.path("listed")).unwrap();
927        symlink("read", dir.path("link")).unwrap();
928        let observations = vec![
929            dir.observe("link", AccessKind::Read),
930            dir.observe("listed", AccessKind::List),
931            dir.observe("read", AccessKind::Read),
932        ];
933        // A link made again has new times of its own, which are never compared.
934        fs::remove_file(dir.path("link")).unwrap();
935        symlink("read", dir.path("link")).unwrap();
936        let states = fresh_states();
937        let checked = check(&observations, now(), true, &states, &NoAttributes);
938        assert!(checked.is_hit(), "{checked:?}");
939        assert!(!checked.refresh);
940        assert_eq!(states.files_hashed(), 0);
941    }
942
943    #[test]
944    fn with_the_option_a_size_or_permission_change_comes_before_the_times() {
945        let dir = Dir::new();
946        dir.write_old("read", "content");
947        fs::set_permissions(dir.path("read"), fs::Permissions::from_mode(0o644)).unwrap();
948        let observations = vec![dir.observe("read", AccessKind::Read)];
949        fs::write(dir.path("read"), "longer content").unwrap();
950        let states = fresh_states();
951        let checked = check(&observations, now(), true, &states, &NoAttributes);
952        assert_eq!(changes(&checked), [Change::Size { old: 7, new: 14 }]);
953        fs::set_permissions(dir.path("read"), fs::Permissions::from_mode(0o600)).unwrap();
954        let checked = check(&observations, now(), true, &states, &NoAttributes);
955        assert_eq!(changes(&checked), [Change::Permissions {
956            old: 0o644,
957            new: 0o600,
958        }]);
959        assert_eq!(states.files_hashed(), 0);
960    }
961
962    /// The owner every observation of `observations` records, replaced by one that
963    /// no file has: one more than the current user and group numbers.
964    fn other_owner(observations: &mut [Observation]) -> Owner {
965        let mut replaced = None;
966        for observation in observations {
967            let owner = match &mut observation.state {
968                PathState::File { meta, .. } => &mut meta.owner,
969                PathState::Directory { owner, .. } => owner,
970                other => panic!("no owner in {other:?}"),
971            };
972            *owner = Owner {
973                uid: owner.uid.wrapping_add(1),
974                gid: owner.gid.wrapping_add(1),
975            };
976            replaced = Some(*owner);
977        }
978        replaced.unwrap()
979    }
980
981    #[test]
982    fn permission_changes_are_found_without_hashing_whatever_the_content() {
983        let dir = Dir::new();
984        dir.write_old("read", "content");
985        fs::set_permissions(dir.path("read"), fs::Permissions::from_mode(0o644)).unwrap();
986        fs::create_dir(dir.path("listed")).unwrap();
987        fs::set_permissions(dir.path("listed"), fs::Permissions::from_mode(0o755)).unwrap();
988        fs::create_dir(dir.path("opened")).unwrap();
989        fs::set_permissions(dir.path("opened"), fs::Permissions::from_mode(0o755)).unwrap();
990        let observations = vec![
991            dir.observe("listed", AccessKind::List),
992            dir.observe("opened", AccessKind::Probe),
993            dir.observe("read", AccessKind::Read),
994        ];
995        for name in ["read", "listed", "opened"] {
996            fs::set_permissions(dir.path(name), fs::Permissions::from_mode(0o700)).unwrap();
997        }
998        let states = fresh_states();
999        let checked = check(&observations, now(), false, &states, &NoAttributes);
1000        assert_eq!(changes(&checked), [
1001            Change::Permissions {
1002                old: 0o755,
1003                new: 0o700,
1004            },
1005            Change::Permissions {
1006                old: 0o755,
1007                new: 0o700,
1008            },
1009            Change::Permissions {
1010                old: 0o644,
1011                new: 0o700,
1012            },
1013        ]);
1014        assert!(!checked.refresh);
1015        assert_eq!(states.files_hashed(), 0);
1016    }
1017
1018    #[test]
1019    fn a_file_whose_times_and_mode_changed_reports_the_mode_and_is_not_refreshed() {
1020        let dir = Dir::new();
1021        dir.write_old("read", "content");
1022        fs::set_permissions(dir.path("read"), fs::Permissions::from_mode(0o644)).unwrap();
1023        let observations = vec![dir.observe("read", AccessKind::Read)];
1024        set_modified(&dir.path("read"), 7_200);
1025        fs::set_permissions(dir.path("read"), fs::Permissions::from_mode(0o600)).unwrap();
1026        let states = fresh_states();
1027        let checked = check(&observations, now(), false, &states, &NoAttributes);
1028        assert_eq!(changes(&checked), [Change::Permissions {
1029            old: 0o644,
1030            new: 0o600,
1031        }]);
1032        assert!(!checked.refresh);
1033        assert_eq!(checked.observations, observations);
1034        assert_eq!(states.files_hashed(), 0);
1035    }
1036
1037    #[test]
1038    fn a_recorded_owner_that_differs_is_a_change_found_without_hashing() {
1039        let dir = Dir::new();
1040        dir.write_old("read", "content");
1041        dir.write_old("checked", "content");
1042        fs::create_dir(dir.path("listed")).unwrap();
1043        fs::create_dir(dir.path("opened")).unwrap();
1044        let mut observations = vec![
1045            dir.observe("checked", AccessKind::Probe),
1046            dir.observe("listed", AccessKind::List),
1047            dir.observe("opened", AccessKind::Probe),
1048            dir.observe("read", AccessKind::Read),
1049        ];
1050        let current = fs::metadata(dir.path("read")).unwrap();
1051        let current = Owner {
1052            uid: current.uid(),
1053            gid: current.gid(),
1054        };
1055        let recorded = other_owner(&mut observations);
1056        let states = fresh_states();
1057        let checked = check(&observations, now(), false, &states, &NoAttributes);
1058        let owner = Change::Owner {
1059            old: recorded,
1060            new: current,
1061        };
1062        assert_eq!(changes(&checked), [
1063            owner.clone(),
1064            owner.clone(),
1065            owner.clone(),
1066            owner
1067        ]);
1068        assert_eq!(states.files_hashed(), 0);
1069    }
1070
1071    #[test]
1072    fn special_bits_count_as_permission_bits_and_the_type_does_not() {
1073        let owner = Owner { uid: 1, gid: 2 };
1074        for special in [0o4000, 0o2000, 0o1000] {
1075            assert_eq!(
1076                access_change(0o100_755, owner, 0o100_755 | special, owner),
1077                Some(Change::Permissions {
1078                    old: 0o755,
1079                    new: 0o755 | special,
1080                }),
1081                "{special:o}"
1082            );
1083            assert_eq!(
1084                access_change(0o040_755 | special, owner, 0o040_755, owner),
1085                Some(Change::Permissions {
1086                    old: 0o755 | special,
1087                    new: 0o755,
1088                }),
1089                "{special:o}"
1090            );
1091        }
1092        // The type bits are compared as the type, never as permissions.
1093        assert_eq!(access_change(0o100_644, owner, 0o040_644, owner), None);
1094        assert_eq!(access_change(0o100_644, owner, 0o100_644, owner), None);
1095        // A permission change is reported before an owner change.
1096        let root = Owner { uid: 0, gid: 0 };
1097        assert_eq!(
1098            access_change(0o100_644, owner, 0o100_600, root),
1099            Some(Change::Permissions {
1100                old: 0o644,
1101                new: 0o600,
1102            })
1103        );
1104        assert_eq!(
1105            access_change(0o100_644, owner, 0o100_644, root),
1106            Some(Change::Owner {
1107                old: owner,
1108                new: root,
1109            })
1110        );
1111    }
1112
1113    #[test]
1114    fn appearing_disappearing_and_retyped_paths_change() {
1115        let dir = Dir::new();
1116        dir.write_old("gone", "content");
1117        dir.write_old("retyped", "content");
1118        fs::create_dir(dir.path("listed")).unwrap();
1119        symlink("gone", dir.path("link")).unwrap();
1120        let observations = vec![
1121            dir.observe("appears", AccessKind::Probe),
1122            dir.observe("gone", AccessKind::Read),
1123            dir.observe("link", AccessKind::Read),
1124            dir.observe("listed", AccessKind::List),
1125            dir.observe("retyped", AccessKind::Probe),
1126        ];
1127        fs::write(dir.path("appears"), "").unwrap();
1128        fs::write(dir.path("listed/entry"), "").unwrap();
1129        fs::remove_file(dir.path("gone")).unwrap();
1130        fs::remove_file(dir.path("retyped")).unwrap();
1131        fs::create_dir(dir.path("retyped")).unwrap();
1132        let checked = check(&observations, now(), false, &fresh_states(), &NoAttributes);
1133        assert_eq!(changes(&checked), [
1134            Change::Appeared,
1135            Change::Disappeared,
1136            Change::Disappeared,
1137            Change::Entries {
1138                appeared: vec![DirEntry {
1139                    name: b"entry".to_vec(),
1140                    kind: EntryKind::File,
1141                }],
1142                disappeared: Vec::new(),
1143                retyped: Vec::new(),
1144            },
1145            Change::Type,
1146        ]);
1147
1148        fs::remove_file(dir.path("link")).unwrap();
1149        symlink("appears", dir.path("link")).unwrap();
1150        let checked = check(
1151            &observations[2..3],
1152            now(),
1153            false,
1154            &fresh_states(),
1155            &NoAttributes,
1156        );
1157        assert_eq!(changes(&checked), [Change::LinkTarget {
1158            old: PathBuf::from("gone"),
1159            new: PathBuf::from("appears"),
1160        }]);
1161    }
1162
1163    /// The recorded listing of `observation`, a listed directory.
1164    fn recorded_listing(observation: &Observation) -> &Listing {
1165        match &observation.state {
1166            PathState::Directory {
1167                listing: Some(listing),
1168                ..
1169            } => listing,
1170            other => panic!("no listing in {other:?}"),
1171        }
1172    }
1173
1174    /// `observation`, a listed directory, recorded with `listing` instead.
1175    fn with_listing(
1176        observation: &Observation,
1177        listing: Listing,
1178    ) -> Observation {
1179        let mut observation = observation.clone();
1180        if let PathState::Directory {
1181            listing: recorded, ..
1182        } = &mut observation.state
1183        {
1184            *recorded = Some(listing);
1185        }
1186        observation
1187    }
1188
1189    /// A regular-file entry named `name`.
1190    fn file_entry(name: &str) -> DirEntry {
1191        DirEntry {
1192            name: name.as_bytes().to_vec(),
1193            kind: EntryKind::File,
1194        }
1195    }
1196
1197    #[test]
1198    fn an_order_change_is_told_apart_from_an_entries_change() {
1199        let dir = Dir::new();
1200        fs::create_dir(dir.path("listed")).unwrap();
1201        for name in ["a", "b", "c"] {
1202            fs::write(dir.path(&format!("listed/{name}")), "").unwrap();
1203        }
1204        let observed = dir.observe("listed", AccessKind::List);
1205        let current = recorded_listing(&observed).entries.clone().unwrap();
1206        let check_with = |entries: Vec<DirEntry>, keep: bool| {
1207            let mut listing = observe::listing(entries);
1208            if !keep {
1209                listing.entries = None;
1210            }
1211            changes(&check(
1212                &[with_listing(&observed, listing)],
1213                now(),
1214                false,
1215                &fresh_states(),
1216                &NoAttributes,
1217            ))
1218        };
1219        assert_eq!(check_with(current.clone(), true), []);
1220
1221        // The current entries recorded in reverse order: only the order changed.
1222        let reversed: Vec<DirEntry> = current.iter().rev().cloned().collect();
1223        assert_eq!(check_with(reversed, true), [Change::Order]);
1224
1225        // A recorded listing that lacks `b`, and has a `gone` directory and a `c`
1226        // directory, names what appeared, disappeared, and changed type.
1227        let mut other: Vec<DirEntry> = current
1228            .iter()
1229            .filter(|entry| entry.name != b"b")
1230            .cloned()
1231            .collect();
1232        for entry in &mut other {
1233            if entry.name == b"c" {
1234                entry.kind = EntryKind::Directory;
1235            }
1236        }
1237        other.push(DirEntry {
1238            name: b"gone".to_vec(),
1239            kind: EntryKind::Directory,
1240        });
1241        assert_eq!(check_with(other.clone(), true), [Change::Entries {
1242            appeared: vec![file_entry("b")],
1243            disappeared: vec![DirEntry {
1244                name: b"gone".to_vec(),
1245                kind: EntryKind::Directory,
1246            }],
1247            retyped: vec![file_entry("c")],
1248        }]);
1249
1250        // Without recorded entries, an entries change names none.
1251        assert_eq!(check_with(other, false), [Change::Entries {
1252            appeared: Vec::new(),
1253            disappeared: Vec::new(),
1254            retyped: Vec::new(),
1255        }]);
1256    }
1257
1258    #[test]
1259    fn above_the_limit_a_matching_sorted_hash_is_an_order_change() {
1260        let dir = Dir::new();
1261        fs::create_dir(dir.path("listed")).unwrap();
1262        for index in 0..=MAX_LISTED_NAMES {
1263            fs::write(dir.path(&format!("listed/{index}")), "").unwrap();
1264        }
1265        let observed = dir.observe("listed", AccessKind::List);
1266        let listing = recorded_listing(&observed).clone();
1267        assert_eq!(listing.entries, None);
1268        let check_with = |listing: Listing| {
1269            changes(&check(
1270                &[with_listing(&observed, listing)],
1271                now(),
1272                false,
1273                &fresh_states(),
1274                &NoAttributes,
1275            ))
1276        };
1277        assert_eq!(check_with(listing.clone()), []);
1278
1279        // An ordered hash that differs with a sorted hash that matches.
1280        let reordered = Listing {
1281            hash: ContentHash([0; 32]),
1282            ..listing.clone()
1283        };
1284        assert_eq!(check_with(reordered), [Change::Order]);
1285
1286        // Both hashes differ: the entries changed, and no names are known.
1287        let different = Listing {
1288            hash: ContentHash([0; 32]),
1289            sorted_hash: ContentHash([0; 32]),
1290            entries: None,
1291        };
1292        assert_eq!(check_with(different), [Change::Entries {
1293            appeared: Vec::new(),
1294            disappeared: Vec::new(),
1295            retyped: Vec::new(),
1296        }]);
1297    }
1298
1299    #[test]
1300    fn untracked_kernel_paths_are_never_compared() {
1301        let observation = Observation {
1302            path: PathBuf::from("/proc/kizz-test-never-there"),
1303            access: AccessBits(AccessBits::READ),
1304            tracked: false,
1305            state: PathState::Untracked,
1306            attributes: None,
1307        };
1308        let special = Observation {
1309            path: PathBuf::from("/dev/null"),
1310            access: AccessBits(AccessBits::WRITE),
1311            tracked: false,
1312            state: PathState::Special {
1313                kind: SpecialKind::CharDevice,
1314            },
1315            attributes: None,
1316        };
1317        let checked = check(
1318            &[observation, special],
1319            now(),
1320            false,
1321            &fresh_states(),
1322            &NoAttributes,
1323        );
1324        assert!(checked.is_hit(), "{checked:?}");
1325    }
1326
1327    /// The observation of `name`, whose extended attributes the step read, with
1328    /// its attributes recorded through `query`.
1329    fn observe_attributes(
1330        dir: &Dir,
1331        name: &str,
1332        query: &FakeAttributes,
1333    ) -> Observation {
1334        let mut observation = dir.observe(name, AccessKind::Xattr);
1335        observation.attributes = Some(record_attributes(&observation.path, query));
1336        observation
1337    }
1338
1339    /// The recorded attribute `name` with the hash of `value`.
1340    fn hashed(
1341        name: &str,
1342        value: &str,
1343    ) -> Attribute {
1344        Attribute {
1345            name: name.as_bytes().to_vec(),
1346            hash: ContentHash(*blake3::hash(value.as_bytes()).as_bytes()),
1347        }
1348    }
1349
1350    /// A file, a directory, and a symbolic link whose attributes were read record
1351    /// them with their state: each name with a hash of its value, sorted by name,
1352    /// and for the link also those of what it points to; a missing path records
1353    /// none it could read, and a file system without attributes records none.
1354    #[test]
1355    fn extended_attributes_are_recorded_with_the_state() {
1356        let dir = Dir::new();
1357        dir.write_old("file", "content");
1358        fs::create_dir(dir.path("dir")).unwrap();
1359        dir.write_old("target", "pointee");
1360        symlink("target", dir.path("link")).unwrap();
1361        let query = FakeAttributes::default();
1362        query.set(&dir.path("file"), false, &[
1363            ("user.b", "2"),
1364            ("user.a", "1"),
1365        ]);
1366        query.set(&dir.path("link"), false, &[]);
1367        query.set(&dir.path("link"), true, &[("user.origin", "x")]);
1368
1369        let file = observe_attributes(&dir, "file", &query);
1370        assert!(file.access.contains(AccessBits::XATTR));
1371        assert_eq!(
1372            file.attributes,
1373            Some(Attributes {
1374                own: Some(vec![hashed("user.a", "1"), hashed("user.b", "2")]),
1375                pointee: None,
1376            })
1377        );
1378        assert!(matches!(file.state, PathState::File { hash: None, .. }));
1379        let link = observe_attributes(&dir, "link", &query);
1380        assert_eq!(
1381            link.attributes,
1382            Some(Attributes {
1383                own: Some(Vec::new()),
1384                pointee: Some(vec![hashed("user.origin", "x")]),
1385            })
1386        );
1387        let missing = observe_attributes(&dir, "missing", &query);
1388        assert_eq!(
1389            missing.attributes,
1390            Some(Attributes {
1391                own: None,
1392                pointee: None,
1393            })
1394        );
1395        assert_eq!(
1396            record_attributes(&dir.path("dir"), &NoAttributes),
1397            Attributes {
1398                own: Some(Vec::new()),
1399                pointee: None,
1400            }
1401        );
1402    }
1403
1404    /// Recorded attributes that did not change are a hit; an attribute that
1405    /// appeared on a file, one that disappeared from a directory, and one whose
1406    /// value changed on what a link points to are changes that name them, and
1407    /// attributes that can no longer be read count as none, so they disappeared.
1408    #[test]
1409    fn extended_attributes_that_appear_disappear_or_change_are_changes() {
1410        let dir = Dir::new();
1411        dir.write_old("file", "content");
1412        fs::create_dir(dir.path("dir")).unwrap();
1413        dir.write_old("target", "pointee");
1414        symlink("target", dir.path("link")).unwrap();
1415        let query = FakeAttributes::default();
1416        query.set(&dir.path("file"), false, &[("user.a", "1")]);
1417        query.set(&dir.path("dir"), false, &[
1418            ("user.kept", "k"),
1419            ("user.gone", "g"),
1420        ]);
1421        query.set(&dir.path("link"), false, &[]);
1422        query.set(&dir.path("link"), true, &[("user.origin", "x")]);
1423        let observations: Vec<Observation> = ["dir", "file", "link"]
1424            .into_iter()
1425            .map(|name| observe_attributes(&dir, name, &query))
1426            .collect();
1427        let states = fresh_states();
1428        let checked = check(&observations, now(), false, &states, &query);
1429        assert!(checked.is_hit(), "{checked:?}");
1430        assert!(!checked.refresh);
1431
1432        query.set(&dir.path("file"), false, &[
1433            ("user.a", "1"),
1434            ("user.new", "n"),
1435        ]);
1436        query.set(&dir.path("dir"), false, &[("user.kept", "k")]);
1437        query.set(&dir.path("link"), true, &[("user.origin", "y")]);
1438        let checked = check(&observations, now(), false, &states, &query);
1439        assert_eq!(changes(&checked), [
1440            Change::Attributes {
1441                appeared: Vec::new(),
1442                disappeared: vec![hashed("user.gone", "g")],
1443                changed: Vec::new(),
1444            },
1445            Change::Attributes {
1446                appeared: vec![hashed("user.new", "n")],
1447                disappeared: Vec::new(),
1448                changed: Vec::new(),
1449            },
1450            Change::Attributes {
1451                appeared: Vec::new(),
1452                disappeared: Vec::new(),
1453                changed: vec![hashed("user.origin", "y")],
1454            },
1455        ]);
1456        let shown: Vec<String> = changes(&checked).iter().map(ToString::to_string).collect();
1457        assert_eq!(shown, [
1458            "extended attributes changed: `user.gone` disappeared",
1459            "extended attributes changed: `user.new` appeared",
1460            "extended attributes changed: `user.origin` changed",
1461        ]);
1462
1463        // Attributes that the query can no longer read count as none, and an
1464        // observation without recorded attributes never queries.
1465        let unreadable = FakeAttributes::default();
1466        let checked = check(&observations[1..2], now(), false, &states, &unreadable);
1467        assert_eq!(changes(&checked), [Change::Attributes {
1468            appeared: Vec::new(),
1469            disappeared: vec![hashed("user.a", "1")],
1470            changed: Vec::new(),
1471        }]);
1472        let plain = dir.observe("file", AccessKind::Read);
1473        let checked = check(&[plain], now(), false, &states, &unreadable);
1474        assert!(checked.is_hit(), "{checked:?}");
1475    }
1476
1477    /// A change of the rest of the state is found before the attributes, which are
1478    /// then not compared.
1479    #[test]
1480    fn state_changes_come_before_attribute_changes() {
1481        let dir = Dir::new();
1482        dir.write_old("file", "content");
1483        fs::set_permissions(dir.path("file"), fs::Permissions::from_mode(0o644)).unwrap();
1484        let query = FakeAttributes::default();
1485        query.set(&dir.path("file"), false, &[("user.a", "1")]);
1486        let observations = vec![observe_attributes(&dir, "file", &query)];
1487        fs::set_permissions(dir.path("file"), fs::Permissions::from_mode(0o600)).unwrap();
1488        query.set(&dir.path("file"), false, &[("user.a", "2")]);
1489        let checked = check(&observations, now(), false, &fresh_states(), &query);
1490        assert_eq!(changes(&checked), [Change::Permissions {
1491            old: 0o644,
1492            new: 0o600,
1493        }]);
1494    }
1495}