tributary_fs/error.rs
1//! The watcher's error vocabulary.
2//!
3//! Errors cover construction and root registration only: once a root is live,
4//! every condition — a vanished root, kernel-side loss, a lagging consumer —
5//! arrives as an in-band [`Event`](crate::Event) (a `Removed`, a `Rescan`),
6//! never as a stream error.
7
8use std::path::PathBuf;
9
10use crate::os::SourceError;
11
12/// Why a [`Watcher`](crate::Watcher) could not be built.
13#[derive(Debug, thiserror::Error)]
14#[non_exhaustive]
15pub enum BuildError {
16 /// More exclusion paths than the OS honors were configured (the FSEvents
17 /// limit is [`WatcherOptions::MAX_EXCLUSIONS`](crate::WatcherOptions::MAX_EXCLUSIONS)).
18 #[error(
19 "{supplied} exclusion paths exceed the OS limit of {}",
20 crate::os::MAX_EXCLUSIONS
21 )]
22 TooManyExclusions {
23 /// How many exclusion paths the options carried.
24 supplied: usize,
25 },
26}
27
28impl BuildError {
29 /// Whether this is [`TooManyExclusions`](Self::TooManyExclusions).
30 #[inline]
31 pub const fn is_too_many_exclusions(&self) -> bool {
32 matches!(self, Self::TooManyExclusions { .. })
33 }
34}
35
36/// Why a root could not be watched.
37#[derive(Debug, thiserror::Error)]
38#[non_exhaustive]
39pub enum WatchRootError {
40 /// The root does not exist.
41 #[error("watch root {} does not exist", path.display())]
42 NotFound {
43 /// The root as the caller supplied it.
44 path: PathBuf,
45 },
46 /// The root exists but is not a directory.
47 #[error("watch root {} is not a directory", path.display())]
48 NotADirectory {
49 /// The canonicalized root.
50 path: PathBuf,
51 },
52 /// The root overlaps a root this watcher already covers. Roots must be
53 /// disjoint; subsuming overlapping trees is the layer above's job.
54 #[error("watch root {} overlaps the already-watched {}", path.display(), existing.display())]
55 Overlaps {
56 /// The canonicalized root that was rejected.
57 path: PathBuf,
58 /// The already-watched root it overlaps.
59 existing: PathBuf,
60 },
61 /// The platform source could not start.
62 #[error("the platform source could not start")]
63 Source(#[source] SourceError),
64 /// The watcher's driver has already stopped.
65 #[error("the watcher is closed")]
66 Closed,
67}
68
69impl WatchRootError {
70 /// Whether this is [`NotFound`](Self::NotFound).
71 #[inline]
72 pub const fn is_not_found(&self) -> bool {
73 matches!(self, Self::NotFound { .. })
74 }
75
76 /// Whether this is [`NotADirectory`](Self::NotADirectory).
77 #[inline]
78 pub const fn is_not_a_directory(&self) -> bool {
79 matches!(self, Self::NotADirectory { .. })
80 }
81
82 /// Whether this is [`Overlaps`](Self::Overlaps).
83 #[inline]
84 pub const fn is_overlaps(&self) -> bool {
85 matches!(self, Self::Overlaps { .. })
86 }
87
88 /// Whether this is [`Source`](Self::Source).
89 #[inline]
90 pub const fn is_source(&self) -> bool {
91 matches!(self, Self::Source(_))
92 }
93
94 /// Whether this is [`Closed`](Self::Closed).
95 #[inline]
96 pub const fn is_closed(&self) -> bool {
97 matches!(self, Self::Closed)
98 }
99}
100
101/// Why a root could not be unwatched.
102#[derive(Debug, thiserror::Error)]
103#[non_exhaustive]
104pub enum UnwatchError {
105 /// The handle does not name a live root of this watcher (never watched,
106 /// already unwatched, or torn down by a root-death event).
107 #[error("the root handle is not watched")]
108 UnknownRoot,
109 /// The watcher's driver has already stopped.
110 #[error("the watcher is closed")]
111 Closed,
112}
113
114impl UnwatchError {
115 /// Whether this is [`UnknownRoot`](Self::UnknownRoot).
116 #[inline]
117 pub const fn is_unknown_root(&self) -> bool {
118 matches!(self, Self::UnknownRoot)
119 }
120
121 /// Whether this is [`Closed`](Self::Closed).
122 #[inline]
123 pub const fn is_closed(&self) -> bool {
124 matches!(self, Self::Closed)
125 }
126}
127
128/// Why an orderly [`close`](crate::Watcher::close) could not be confirmed.
129#[derive(Debug, thiserror::Error)]
130#[non_exhaustive]
131pub enum CloseError {
132 /// The driver stopped before confirming the shutdown (it panicked or was
133 /// torn down externally); streams are still reclaimed at process exit.
134 #[error("the driver stopped before confirming the shutdown")]
135 Stopped,
136 /// The close grace expired with work still OUTSTANDING: teardowns still inside
137 /// their `shutdown` calls, spawns that may already own a live stream (the
138 /// backend starts the stream and then performs post-live metadata reads inside
139 /// the same call), or a sync cookie the driver wrote but could not CONFIRM
140 /// removed within the grace — an unlink still in flight, or one whose retries
141 /// the grace outran (a parked record awaiting the terminal sweep is counted
142 /// too: it is owned-and-unremoved, not merely executing). None proves
143 /// quiescence at reply time. Their reclamation stories differ: a wedged
144 /// teardown's stream is unreachable until the call returns (the OS reclaims at
145 /// process exit), a wedged spawn's stream is reclaimed by its undeliverable
146 /// result dropping the handle once the wedge clears, and an unremoved cookie
147 /// leaves its file until the mount unwedges (the registry's best-effort
148 /// terminal sweep retries it) — but close reports the outstanding count
149 /// honestly rather than hanging on any of them.
150 #[error("{pending} operation(s) still outstanding when the close grace expired")]
151 NotQuiesced {
152 /// How many stream spawns/teardowns and owned-but-unconfirmed cookies were
153 /// still outstanding at grace expiry.
154 pending: usize,
155 },
156}
157
158impl CloseError {
159 /// Whether this is [`Stopped`](Self::Stopped).
160 #[inline]
161 pub const fn is_stopped(&self) -> bool {
162 matches!(self, Self::Stopped)
163 }
164
165 /// Whether this is [`NotQuiesced`](Self::NotQuiesced).
166 #[inline]
167 pub const fn is_not_quiesced(&self) -> bool {
168 matches!(self, Self::NotQuiesced { .. })
169 }
170}
171
172/// Why [`Watcher::sync_root`](crate::Watcher::sync_root) could not place a
173/// sync cookie. The barrier's *observation* is the caller's job (the cookie's
174/// event arrives on the stream); this error covers only the placement.
175#[derive(Debug, thiserror::Error)]
176#[non_exhaustive]
177pub enum SyncRootError {
178 /// The handle does not name a live root of this watcher.
179 #[error("the handle does not name a live root of this watcher")]
180 UnknownRoot,
181 /// The [`SyncTicket`](crate::SyncTicket) was minted by a DIFFERENT watcher.
182 /// Refused synchronously, before any write: a ticket's sequence numbering is
183 /// per-watcher, so honoring a foreign one would let it alias one of this
184 /// watcher's incarnations. Mint the ticket from the same watcher the sync runs
185 /// on ([`Watcher::mint_sync_ticket`](crate::Watcher::mint_sync_ticket)).
186 #[error("the sync ticket was minted by a different watcher")]
187 ForeignTicket,
188 /// The cookie directory is not inside the root's coverage — a cookie
189 /// written there could never be reported on this root's stream. Also raised
190 /// when the directory only *appears* inside the root through `..` traversal
191 /// (`<root>/../outside`), which a lexical `starts_with` would accept.
192 #[error("cookie directory {} is outside root {}", dir.display(), root.display())]
193 DirOutsideRoot {
194 /// The requested cookie directory.
195 dir: PathBuf,
196 /// The root it must be inside.
197 root: PathBuf,
198 },
199 /// The cookie name is not a single normal filename component — it holds a
200 /// path separator, a `.`/`..`, or is absolute or empty. A name like this
201 /// would escape the directory the barrier was validated for, so it is refused
202 /// before any write. The umbrella mints names that never trip this; a caller
203 /// that hits it violated the reserved-namespace contract.
204 #[error("cookie name {name:?} is not a single normal filename component")]
205 BadCookieName {
206 /// The offending name as supplied.
207 name: String,
208 },
209 /// The cookie could not be written. A read-only tree surfaces here as
210 /// [`std::io::ErrorKind::PermissionDenied`] — the honest refusal: a tree
211 /// with no writable covered location cannot support a kernel-mediated
212 /// barrier at all.
213 #[error("could not write sync cookie {}: {source}", path.display())]
214 Write {
215 /// The cookie path the write was attempted at.
216 path: PathBuf,
217 /// The underlying failure.
218 #[source]
219 source: std::io::Error,
220 },
221 /// A physical cookie write for this root is already in flight. The barrier is
222 /// single-flighted per root: at most one physical write may be outstanding at
223 /// a time, so a caller that times out and retries cannot pile unbounded
224 /// blocking writes against a hung mount. Retry once the outstanding write
225 /// resolves.
226 #[error("a sync cookie write is already in flight for this root")]
227 WriteInFlight,
228 /// A live sync obligation of this watcher already holds this cookie name —
229 /// admitting a second would make cancel-by-name ambiguous and could target
230 /// another root's sync. The name is freed when the holding obligation reaches
231 /// its terminal (its cookie confirmed removed, or the sync retired), so
232 /// sequential reuse of a name admits; concurrent syncs need distinct names
233 /// (the umbrella's minted names are always distinct).
234 #[error("cookie name {name:?} is already held by a live sync of this watcher")]
235 NameInUse {
236 /// The contested name as supplied.
237 name: String,
238 },
239 /// A LIVE sync obligation of this watcher already holds this admission's mint
240 /// sequence. From the safe [`sync_root`](crate::Watcher::sync_root) API this is
241 /// now unreachable — the move-only [`SyncAdmission`](crate::SyncAdmission) makes
242 /// presenting one sequence to two syncs a compile error — so it is retained as a
243 /// driver-internal invariant. The refusal is pre-birth and creates nothing, so
244 /// [`sync_root`](crate::Watcher::sync_root) hands the admission back in
245 /// [`SyncRootDenied`](crate::SyncRootDenied) for a same-sequence retry; the
246 /// paired [`SyncTicket`](crate::SyncTicket) remains the forever cancel key.
247 #[error("the sync ticket is already held by a live sync of this watcher")]
248 TicketInUse {},
249 /// This root has too many unremoved cookies: its cleanup owner is retrying
250 /// failing unlinks (a pathological filesystem where writes succeed but unlinks
251 /// keep failing), and the per-root backlog cap has been reached. Retryable —
252 /// once the backlog drains, syncs resume with no operator action.
253 #[error("the root's sync cookie cleanup is backlogged; retry later")]
254 CleanupBacklog,
255 /// The barrier outlived the coverage it was to be written under: the root died (or was
256 /// unwatched) while the write was parked on the coverage-settle fence, or the scope retired —
257 /// or the driver itself shut down — while the write was already in flight. In the latter cases
258 /// the cookie file is unlinked again before this is reported, so a refused barrier never leaves
259 /// a marker behind.
260 #[error("the root died while the sync cookie was pending")]
261 Retired,
262 /// The watcher is closed.
263 #[error("the watcher is closed")]
264 Closed,
265}
266
267/// Why [`Watcher::replace_root`](crate::Watcher::replace_root) failed. The
268/// operation is atomic-on-failure: every variant leaves the old root's
269/// coverage untouched.
270#[derive(Debug, thiserror::Error)]
271#[non_exhaustive]
272pub enum ReplaceRootError {
273 /// The new root does not exist.
274 #[error("replacement root {} does not exist", path.display())]
275 NotFound {
276 /// The path as the caller supplied it.
277 path: PathBuf,
278 },
279 /// The new root exists but is not a directory.
280 #[error("replacement root {} is not a directory", path.display())]
281 NotADirectory {
282 /// The canonicalized path.
283 path: PathBuf,
284 },
285 /// The new root overlaps a DIFFERENT live (or reserved) root. The root
286 /// being replaced is exempt — overlapping it is the operation's point.
287 #[error("replacement root {} overlaps live root {}", path.display(), existing.display())]
288 Overlaps {
289 /// The canonicalized new root.
290 path: PathBuf,
291 /// The conflicting coverage.
292 existing: PathBuf,
293 },
294 /// The handle does not name a live root of this watcher.
295 #[error("the handle does not name a live root of this watcher")]
296 UnknownRoot,
297 /// A replace is already in flight on this root.
298 #[error("a replace is already in flight on this root")]
299 ReplaceInFlight,
300 /// The new root resolved to a different lowering profile than the live
301 /// scope runs (a descending↔kernel-recursive flip, e.g. a Linux
302 /// `Backend::Auto` landing on fanotify for one volume and inotify for the
303 /// other). A live scope never swaps lowering profiles; unwatch + watch is
304 /// the sanctioned transition.
305 #[error("the replacement resolved to a different lowering profile")]
306 BackendDiverged,
307 /// The root died (or was unwatched) while the replacement was starting —
308 /// death wins, and the scope ended through its normal lifecycle. The new
309 /// stream was torn down; retry against a fresh `watch`.
310 #[error("the root died while the replacement was starting")]
311 Retired,
312 /// The watcher is closed.
313 #[error("the watcher is closed")]
314 Closed,
315 /// The replacement stream could not start.
316 #[error(transparent)]
317 Source(#[from] SourceError),
318}