ailloli_ui_fs/
watch.rs

1//! Normalized native filesystem watch events and correlation metadata.
2
3use crate::{FileIdentity, FileUri};
4
5/// Kind of change reported by a provider watch stream.
6///
7/// The enum is non-exhaustive so downstream matches need a wildcard arm.
8///
9/// # Examples
10///
11/// ```
12/// use ailloli_ui_fs::WatchEventKind;
13/// assert_ne!(WatchEventKind::Created, WatchEventKind::Removed);
14/// ```
15#[non_exhaustive]
16#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
17pub enum WatchEventKind {
18    /// A new entry appeared at the event URI.
19    Created,
20    /// Content or metadata changed at the event URI.
21    Modified,
22    /// The entry at the event URI disappeared.
23    Removed,
24    /// An entry changed name, normally within one directory.
25    Renamed,
26    /// An entry changed parent or provider location.
27    Moved,
28    /// The provider lost one or more events; consumers must invalidate/reload.
29    Overflow,
30}
31
32/// One normalized provider watch event.
33///
34/// Sequence numbers are interpreted within a provider generation; this type
35/// stores but does not validate monotonicity. Rename/move events can carry a
36/// previous URI, and any event can carry a stable identity. The struct is
37/// non-exhaustive so it can gain correlation fields compatibly.
38///
39/// # Examples
40///
41/// ```
42/// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
43/// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///new")?, 1, 4);
44/// assert_eq!((event.sequence(), event.generation()), (1, 4));
45/// # Ok::<(), ailloli_ui_fs::FileError>(())
46/// ```
47#[non_exhaustive]
48#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
49pub struct WatchEvent {
50    /// Normalized event category.
51    kind: WatchEventKind,
52    /// Current or affected URI.
53    uri: FileUri,
54    /// Former URI for a paired rename/move when supplied.
55    previous_uri: Option<FileUri>,
56    /// Provider sequence number within `generation`.
57    sequence: u64,
58    /// Provider watch-stream generation.
59    generation: u64,
60    /// Optional provider-stable entry identity.
61    identity: Option<FileIdentity>,
62}
63
64impl WatchEvent {
65    /// Creates an event without previous URI or stable identity.
66    ///
67    /// Zero and non-monotone sequence/generation values are accepted verbatim.
68    ///
69    /// # Examples
70    ///
71    /// ```
72    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
73    /// let event = WatchEvent::new(WatchEventKind::Modified, FileUri::parse("file:///a")?, 0, 0);
74    /// assert_eq!(event.previous_uri(), None);
75    /// # Ok::<(), ailloli_ui_fs::FileError>(())
76    /// ```
77    pub fn new(kind: WatchEventKind, uri: FileUri, sequence: u64, generation: u64) -> Self {
78        Self {
79            kind,
80            uri,
81            previous_uri: None,
82            sequence,
83            generation,
84            identity: None,
85        }
86    }
87
88    /// Attaches the entry's former URI.
89    ///
90    /// The value is accepted for every event kind and replaces an earlier one.
91    ///
92    /// # Examples
93    ///
94    /// ```
95    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
96    /// let event = WatchEvent::new(WatchEventKind::Renamed, FileUri::parse("file:///new")?, 1, 1)
97    ///     .with_previous_uri(FileUri::parse("file:///old")?);
98    /// assert_eq!(event.previous_uri().unwrap().path(), "/old");
99    /// # Ok::<(), ailloli_ui_fs::FileError>(())
100    /// ```
101    pub fn with_previous_uri(mut self, previous_uri: FileUri) -> Self {
102        self.previous_uri = Some(previous_uri);
103        self
104    }
105
106    /// Attaches a provider-stable identity, replacing any previous identity.
107    ///
108    /// # Examples
109    ///
110    /// ```
111    /// use ailloli_ui_fs::{FileIdentity, FileUri, WatchEvent, WatchEventKind};
112    /// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///a")?, 1, 1)
113    ///     .with_identity(FileIdentity::new("local", [1]));
114    /// assert_eq!(event.identity().unwrap().value(), &[1]);
115    /// # Ok::<(), ailloli_ui_fs::FileError>(())
116    /// ```
117    pub fn with_identity(mut self, identity: FileIdentity) -> Self {
118        self.identity = Some(identity);
119        self
120    }
121
122    /// Returns the normalized event category.
123    ///
124    /// # Examples
125    ///
126    /// ```
127    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
128    /// let event = WatchEvent::new(WatchEventKind::Overflow, FileUri::parse("file:///")?, 1, 1);
129    /// assert_eq!(event.kind(), WatchEventKind::Overflow);
130    /// # Ok::<(), ailloli_ui_fs::FileError>(())
131    /// ```
132    pub const fn kind(&self) -> WatchEventKind {
133        self.kind
134    }
135
136    /// Borrows the entry's current/event URI.
137    ///
138    /// # Examples
139    ///
140    /// ```
141    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
142    /// let event = WatchEvent::new(WatchEventKind::Removed, FileUri::parse("file:///a")?, 1, 1);
143    /// assert_eq!(event.uri().path(), "/a");
144    /// # Ok::<(), ailloli_ui_fs::FileError>(())
145    /// ```
146    pub const fn uri(&self) -> &FileUri {
147        &self.uri
148    }
149
150    /// Borrows the former URI, or returns `None` when it was not supplied.
151    ///
152    /// # Examples
153    ///
154    /// ```
155    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
156    /// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///a")?, 1, 1);
157    /// assert!(event.previous_uri().is_none());
158    /// # Ok::<(), ailloli_ui_fs::FileError>(())
159    /// ```
160    pub const fn previous_uri(&self) -> Option<&FileUri> {
161        self.previous_uri.as_ref()
162    }
163
164    /// Returns the provider sequence number within its generation.
165    ///
166    /// # Examples
167    ///
168    /// ```
169    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
170    /// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///a")?, 7, 2);
171    /// assert_eq!(event.sequence(), 7);
172    /// # Ok::<(), ailloli_ui_fs::FileError>(())
173    /// ```
174    pub const fn sequence(&self) -> u64 {
175        self.sequence
176    }
177
178    /// Returns the provider watch-generation identifier.
179    ///
180    /// # Examples
181    ///
182    /// ```
183    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
184    /// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///a")?, 7, 2);
185    /// assert_eq!(event.generation(), 2);
186    /// # Ok::<(), ailloli_ui_fs::FileError>(())
187    /// ```
188    pub const fn generation(&self) -> u64 {
189        self.generation
190    }
191
192    /// Borrows the stable identity, or returns `None` when unavailable.
193    ///
194    /// # Examples
195    ///
196    /// ```
197    /// use ailloli_ui_fs::{FileUri, WatchEvent, WatchEventKind};
198    /// let event = WatchEvent::new(WatchEventKind::Created, FileUri::parse("file:///a")?, 1, 1);
199    /// assert!(event.identity().is_none());
200    /// # Ok::<(), ailloli_ui_fs::FileError>(())
201    /// ```
202    pub const fn identity(&self) -> Option<&FileIdentity> {
203        self.identity.as_ref()
204    }
205}