Skip to main content

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}