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}