tributaries 0.1.0

Cross-platform filesystem notification: overlapping watch subscriptions are subsumed into disjoint roots, and every event is attributed back to each subscription covering it.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
//! The umbrella crate's **source-neutral** error vocabulary.
//!
//! The umbrella owns this vocabulary exactly as it owns the event vocabulary
//! ([`EventKind`](crate::EventKind)): every [`Source`](crate::Source) — the fs binding
//! included — maps its own failures into it at its binding, so no source's error enum
//! leaks through the generic seam. A classified failure travels as a [`SourceFault`]
//! (a neutral [`FaultKind`] plus the concrete source error boxed behind the standard
//! error chain), and the concrete error stays recoverable via
//! [`SourceFault::downcast_ref`] — for the default fs source, the
//! [`WatchError::as_fs`] sugar.
//!
//! Note the absence of any overlap variant: subsuming overlapping subscriptions into
//! disjoint roots is precisely this layer's job, so the overlap a source rejects can
//! never reach the caller here (a [`FaultKind::Conflict`] is only ever a genuine live
//! conflict — a source-contract violation, never a subsumed-away overlap). And once a
//! subscription is live, every runtime condition — a vanished root, kernel-side loss, a
//! lagging consumer — arrives in-band as an [`Event`](crate::Event) (a `Removed`, a
//! `Rescan`), never as an error here.

use core::error::Error;

#[cfg(all(test, not(feature = "fs")))]
mod tests;

/// A classified failure reported by a [`Source`](crate::Source): the umbrella-neutral
/// [`FaultKind`] plus, when the source has one, the concrete source error boxed behind
/// the standard error chain (`Send + Sync` payloads only, so errors cross threads).
///
/// A source constructs these at its binding — classify honestly into a [`FaultKind`]
/// and preserve the full concrete error via [`with_source`](Self::with_source) — and
/// the umbrella carries them opaquely inside [`WatchError`] / [`BuildError`]. A caller
/// dispatches on [`kind`](Self::kind) generically, or recovers the concrete error with
/// [`downcast_ref`](Self::downcast_ref) when it knows the source.
///
/// `Display` is the kind; the boxed error is exposed through
/// [`Error::source`](core::error::Error::source), so the standard error-chain walk
/// reaches the concrete failure.
///
/// # Examples
///
/// ```
/// use tributaries::{FaultKind, SourceFault};
///
/// let fault = SourceFault::new(FaultKind::NotFound)
///   .with_source(std::io::Error::from(std::io::ErrorKind::NotFound));
/// assert!(fault.kind().is_not_found());
/// assert!(fault.downcast_ref::<std::io::Error>().is_some());
/// ```
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub struct SourceFault {
  kind: FaultKind,
  #[source]
  source: Option<Box<dyn Error + Send + Sync>>,
}

impl SourceFault {
  /// A fault classified as `kind`, with no concrete source error attached.
  #[inline]
  pub const fn new(kind: FaultKind) -> Self {
    Self { kind, source: None }
  }

  /// Attaches the concrete source error, preserved whole behind the box so
  /// [`get_ref`](Self::get_ref) / [`downcast_ref`](Self::downcast_ref) recover it with
  /// full fidelity.
  #[inline]
  #[must_use]
  pub fn with_source(mut self, source: impl Into<Box<dyn Error + Send + Sync>>) -> Self {
    self.source = Some(source.into());
    self
  }

  /// The umbrella-neutral classification of this fault.
  #[inline]
  pub const fn kind(&self) -> FaultKind {
    self.kind
  }

  /// The boxed concrete source error, if one was attached.
  #[inline]
  pub fn get_ref(&self) -> Option<&(dyn Error + Send + Sync + 'static)> {
    self.source.as_deref()
  }

  /// The concrete source error downcast to `E`, when one is attached and is an `E`.
  #[inline]
  pub fn downcast_ref<E>(&self) -> Option<&E>
  where
    E: Error + 'static,
  {
    self.get_ref()?.downcast_ref()
  }
}

/// The umbrella-neutral classification of a [`SourceFault`] — owned by this crate on
/// the same principle as [`EventKind`](crate::EventKind): sources map their failures
/// honestly into it at their bindings, degrading only ever toward
/// [`Other`](Self::Other) (the boxed concrete error keeps the detail).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FaultKind {
  /// The keyed object does not exist at the source.
  NotFound,
  /// The keyed object exists but cannot anchor a watch (for the fs source, the path is
  /// not a directory).
  NotADirectory,
  /// The source was not permitted to inspect or watch the keyed object.
  PermissionDenied,
  /// A source resource budget is exhausted (for the fs source, the per-user
  /// watch-instance limit).
  Capacity,
  /// The source rejected the watch as conflicting with one it already holds. Never an
  /// overlap between this watcher's own subscriptions — those are subsumed away before
  /// any arm — so a genuine conflict indicates a source-contract violation or a watch
  /// held outside this watcher.
  Conflict,
  /// The source cannot watch at all on this platform or configuration.
  Unsupported,
  /// A failure outside the classified kinds; the boxed concrete error carries the
  /// detail.
  Other,
}

impl FaultKind {
  /// The stable snake_case name of this kind.
  #[inline]
  pub const fn as_str(&self) -> &'static str {
    match self {
      Self::NotFound => "not_found",
      Self::NotADirectory => "not_a_directory",
      Self::PermissionDenied => "permission_denied",
      Self::Capacity => "capacity",
      Self::Conflict => "conflict",
      Self::Unsupported => "unsupported",
      Self::Other => "other",
    }
  }

  /// Whether this is [`NotFound`](Self::NotFound).
  #[inline]
  pub const fn is_not_found(&self) -> bool {
    matches!(self, Self::NotFound)
  }

  /// Whether this is [`NotADirectory`](Self::NotADirectory).
  #[inline]
  pub const fn is_not_a_directory(&self) -> bool {
    matches!(self, Self::NotADirectory)
  }

  /// Whether this is [`PermissionDenied`](Self::PermissionDenied).
  #[inline]
  pub const fn is_permission_denied(&self) -> bool {
    matches!(self, Self::PermissionDenied)
  }

  /// Whether this is [`Capacity`](Self::Capacity).
  #[inline]
  pub const fn is_capacity(&self) -> bool {
    matches!(self, Self::Capacity)
  }

  /// Whether this is [`Conflict`](Self::Conflict).
  #[inline]
  pub const fn is_conflict(&self) -> bool {
    matches!(self, Self::Conflict)
  }

  /// Whether this is [`Unsupported`](Self::Unsupported).
  #[inline]
  pub const fn is_unsupported(&self) -> bool {
    matches!(self, Self::Unsupported)
  }

  /// Whether this is [`Other`](Self::Other).
  #[inline]
  pub const fn is_other(&self) -> bool {
    matches!(self, Self::Other)
  }
}

impl core::fmt::Display for FaultKind {
  #[inline]
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.write_str(self.as_str())
  }
}

/// Why a [`Tributaries`](crate::Tributaries) watcher could not be built.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum BuildError {
  /// The source could not be built; the classified fault carries the source's concrete
  /// error.
  #[error("the source could not be built")]
  Source(#[source] SourceFault),
}

impl BuildError {
  /// Whether this is [`Source`](Self::Source).
  #[inline]
  pub const fn is_source(&self) -> bool {
    matches!(self, Self::Source(_))
  }

  /// The classified fault this error carries.
  #[inline]
  pub const fn fault(&self) -> Option<&SourceFault> {
    match self {
      Self::Source(fault) => Some(fault),
    }
  }

  /// The underlying `tributary-fs` build error, when this error's fault carries one —
  /// downcast sugar over [`fault`](Self::fault) + [`SourceFault::downcast_ref`] for the
  /// default fs source, riding its `fs` feature (on by default).
  #[cfg(feature = "fs")]
  #[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
  #[inline]
  pub fn as_fs(&self) -> Option<&tributary_fs::BuildError> {
    self.fault()?.downcast_ref()
  }
}

/// Why a subscription could not be established.
///
/// Note the absence of an `Overlaps` variant: overlapping subscriptions are subsumed
/// onto a shared source watch (design §4), so the overlap a source rejects can never
/// reach the caller here (see [`FaultKind::Conflict`] for the never-expected genuine
/// live conflict).
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum WatchError {
  /// `key` — the source-rendered display form of the caller's key — could not be
  /// canonicalized into the source's canonical coordinate: it does not exist, or its
  /// metadata could not be read. Canonicalization runs at the top of every watch so the
  /// subsumption index keys off the same canonical coordinate space the source reports
  /// events in; the umbrella refuses to commit a key that would receive no events.
  #[error("watch key {key} could not be canonicalized")]
  Canonicalize {
    /// The caller's key in the source's own display rendering (the fs source renders
    /// the supplied path) — diagnostic only; the typed key is in the caller's hand at
    /// the `watch` call site.
    key: Box<str>,
    /// The classified canonicalization failure.
    #[source]
    source: SourceFault,
  },
  /// The source reported a classified fault establishing the watch — arming it failed,
  /// or (for a covered newcomer) its awaited coverage
  /// [`grow`](crate::Source::grow) hit a fault such as the covering root dying
  /// concurrently. Never an overlap caused by subsumed roots (see the enum docs).
  #[error("the source could not establish the watch")]
  Source(#[source] SourceFault),
  /// The source reported the arm as succeeded, but the armed root was **already
  /// gone** — a *dead-on-arrival* handle: the root was removed between the arm
  /// request and its completion, so the source has already forgotten it
  /// ([`Source::root_key`](crate::Source::root_key) answers `None`). The umbrella
  /// refuses to commit a root no live source watch backs — it would publish the
  /// key as watched yet stream no change under it — so it fails the watch at the
  /// arm choke point (design §4, invariant I2); retry it. Distinct from
  /// [`Source`](Self::Source) (the arm itself failed) and
  /// [`CanonicalRace`](Self::CanonicalRace) (the arm succeeded, but at a divergent
  /// coordinate).
  #[error("the watched root was removed before its watch could be armed; retry the watch")]
  DeadOnArrival,
  /// The source's committed canonical key diverged from the planned one in a way that
  /// changes subsumption (design §4, invariant I2): the just-armed root was released and
  /// the reconcile aborted cleanly rather than commit a mis-keyed or overlapping entry.
  /// A retryable race, like [`DeadOnArrival`](Self::DeadOnArrival) — retry the watch.
  #[error("the source's committed canonical key diverged from the planned one; retry the watch")]
  CanonicalRace,
  /// The owner is holding the maximum RETIRED parked-`Rescan` debt — terminal
  /// [`Rescan`](crate::EventKind::Rescan)s owed to subscriptions whose roots died,
  /// parked because the event channel was full, and retained past the subscriptions'
  /// retirement so the deaths are never silently lost. New watch admission
  /// is refused at that cap: each retire-and-rewatch cycle mints another retired entry,
  /// so gating the ONE step the cycle needs — a fresh watch — is what keeps the debt
  /// (each entry retains a key and a cloned value) structurally bounded. Drain
  /// [`next`](crate::Tributaries::next) — delivering the owed terminal `Rescan`s — and
  /// retry; `close` is never gated (it rides its own channel).
  #[error("retired parked-Rescan debt is at its cap; drain the event stream, then retry the watch")]
  RescanBacklog,
  /// The watcher is closed: the owner is gone (closed, torn down, or every handle
  /// dropped), so no watch can be established.
  #[error("the watcher is closed")]
  Closed,
  /// The key is covered by an existing root whose coverage was narrowed below it, and
  /// the awaited [`Source::grow`](crate::Source::grow) could not restore coverage for
  /// the key's subtree (for the fs source, the grow's effect-completion fence settled
  /// degraded). The umbrella refuses to commit a subscription whose subtree has no
  /// live backing and no retry owner (ratified R1, grow-before-commit), so the watch
  /// fails instead — **record-exact**: the coverage record was NOT broadened, so a
  /// later watch under the pruned region classifies outside-cover again and re-issues
  /// the grow (self-healing). Nothing is silently lost meanwhile: the source has
  /// already emitted an in-band dominating [`Rescan`](crate::EventKind::Rescan) to the
  /// root's current subscribers wherever one is owed. Retryable — retry the watch.
  #[error(
    "the source could not restore coverage for the watch; the covering Rescan dominates the gap; \
     retry the watch"
  )]
  CoverageIncomplete,
}

impl WatchError {
  /// The [`Canonicalize`](Self::Canonicalize) constructor a [`Source`](crate::Source)
  /// uses: the source renders its own coordinate's display form (the fs source renders
  /// the supplied path) and classifies the failure.
  #[inline]
  pub fn canonicalize(key: impl Into<Box<str>>, fault: SourceFault) -> Self {
    Self::Canonicalize {
      key: key.into(),
      source: fault,
    }
  }

  /// The [`Source`](Self::Source) constructor a [`Source`](crate::Source) uses to
  /// report a classified arm failure.
  #[inline]
  pub const fn source(fault: SourceFault) -> Self {
    Self::Source(fault)
  }

  /// Whether this is [`Canonicalize`](Self::Canonicalize).
  #[inline]
  pub const fn is_canonicalize(&self) -> bool {
    matches!(self, Self::Canonicalize { .. })
  }

  /// Whether this is [`Source`](Self::Source).
  #[inline]
  pub const fn is_source(&self) -> bool {
    matches!(self, Self::Source(_))
  }

  /// Whether this is [`DeadOnArrival`](Self::DeadOnArrival).
  #[inline]
  pub const fn is_dead_on_arrival(&self) -> bool {
    matches!(self, Self::DeadOnArrival)
  }

  /// Whether this is [`CanonicalRace`](Self::CanonicalRace).
  #[inline]
  pub const fn is_canonical_race(&self) -> bool {
    matches!(self, Self::CanonicalRace)
  }

  /// Whether this is [`RescanBacklog`](Self::RescanBacklog).
  #[inline]
  pub const fn is_rescan_backlog(&self) -> bool {
    matches!(self, Self::RescanBacklog)
  }

  /// Whether this is [`Closed`](Self::Closed).
  #[inline]
  pub const fn is_closed(&self) -> bool {
    matches!(self, Self::Closed)
  }

  /// Whether this is [`CoverageIncomplete`](Self::CoverageIncomplete) — the retryable,
  /// record-exact refusal to commit a covered newcomer whose awaited coverage grow
  /// could not be applied (no broaden happened; retry the watch).
  #[inline]
  pub const fn is_coverage_incomplete(&self) -> bool {
    matches!(self, Self::CoverageIncomplete)
  }

  /// The classified fault this error carries, for the two fault-carrying variants
  /// ([`Canonicalize`](Self::Canonicalize) and [`Source`](Self::Source)).
  #[inline]
  pub const fn fault(&self) -> Option<&SourceFault> {
    match self {
      Self::Canonicalize { source, .. } | Self::Source(source) => Some(source),
      Self::DeadOnArrival
      | Self::CanonicalRace
      | Self::RescanBacklog
      | Self::Closed
      | Self::CoverageIncomplete => None,
    }
  }

  /// The underlying [`tributary_fs::WatchRootError`], when this error's fault carries
  /// one — downcast sugar over [`fault`](Self::fault) + [`SourceFault::downcast_ref`]
  /// for the default fs source, riding its `fs` feature (on by default).
  #[cfg(feature = "fs")]
  #[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
  #[inline]
  pub fn as_fs(&self) -> Option<&tributary_fs::WatchRootError> {
    self.fault()?.downcast_ref()
  }
}

/// Why a subscription could not be dropped.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum UnwatchError {
  /// The handle does not name a live subscription of this watcher: never registered,
  /// already dropped, or minted by a **different** watcher instance (its per-owner
  /// brand does not match, so it can never name a subscription here — even if its
  /// [`ScopeId`](crate::Subscription::id) collides with a live local one).
  #[error("the subscription is not live")]
  UnknownSubscription,
  /// The watcher is closed: the owner is gone (closed, torn down, or every handle
  /// dropped), so there is nothing left to drop from.
  #[error("the watcher is closed")]
  Closed,
}

impl UnwatchError {
  /// Whether this is [`UnknownSubscription`](Self::UnknownSubscription).
  #[inline]
  pub const fn is_unknown_subscription(&self) -> bool {
    matches!(self, Self::UnknownSubscription)
  }

  /// Whether this is [`Closed`](Self::Closed).
  #[inline]
  pub const fn is_closed(&self) -> bool {
    matches!(self, Self::Closed)
  }
}

/// Why [`sync`](crate::Tributaries::sync) could not establish the barrier.
///
/// The barrier is kernel-mediated: a cookie file is written under the
/// subscription's coverage, and its own event — riding the root's ordered
/// queue behind every change the backend reported before it — is what proves
/// those changes have exited the pipeline. Every variant here is a failure to
/// establish that proof, never a silent half-barrier.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SyncError {
  /// The handle does not name a live subscription of this watcher.
  #[error("the subscription is not live")]
  UnknownSubscription,
  /// The source does not implement the barrier capability. A source with no
  /// writable in-band marker cannot offer a kernel-mediated barrier, and this
  /// says so rather than pretending an owner-side drain is one.
  #[error("this source does not support a sync barrier")]
  Unsupported,
  /// The cookie could not be written. A read-only tree surfaces as
  /// [`FaultKind::PermissionDenied`] — honest: a tree with no writable covered
  /// location cannot support a kernel-mediated barrier at all.
  #[error("could not write the sync cookie: {0}")]
  CookieWrite(#[source] SourceFault),
  /// The resolved cookie directory lies outside the subscription's root, or
  /// outside the coverage its root actually retains — a cookie written there
  /// could never be reported on this subscription's stream.
  #[error("the sync cookie directory is not inside the subscription's coverage")]
  CookieDirUncovered,
  /// The subscription was unwatched by its caller while the sync was pending.
  /// A caller-unwatch owes no `Rescan`, so the barrier cannot be met honestly
  /// (a ROOT DEATH is different: its terminal `Rescan` dominates, and the sync
  /// resolves [`Dominated`](crate::SyncOutcome::Dominated)).
  #[error("the subscription was unwatched while the sync was pending")]
  Retired,
  /// The deadline elapsed before the cookie was observed.
  #[error("the sync barrier timed out")]
  Timeout,
  /// The barrier could not start because the subscription's root is momentarily
  /// busy: another barrier is already in flight for it (at most one physical
  /// cookie write per root may be outstanding, so a hung backend cannot
  /// accumulate blocking writes), OR the root's cookie cleanup is backlogged (a
  /// failing unlink the driver is retrying has filled the per-root cookie
  /// budget). Both are transient and RETRYABLE — retry once the outstanding
  /// work resolves.
  #[error(
    "the subscription's root is busy (a barrier is in flight or its cookie cleanup is backlogged)"
  )]
  Busy,
  /// The watcher is closed.
  #[error("the watcher is closed")]
  Closed,
}

impl SyncError {
  /// Whether this is [`UnknownSubscription`](Self::UnknownSubscription).
  #[inline]
  pub const fn is_unknown_subscription(&self) -> bool {
    matches!(self, Self::UnknownSubscription)
  }

  /// Whether this is [`Unsupported`](Self::Unsupported).
  #[inline]
  pub const fn is_unsupported(&self) -> bool {
    matches!(self, Self::Unsupported)
  }

  /// Whether this is [`CookieWrite`](Self::CookieWrite).
  #[inline]
  pub const fn is_cookie_write(&self) -> bool {
    matches!(self, Self::CookieWrite(_))
  }

  /// Whether this is [`CookieDirUncovered`](Self::CookieDirUncovered).
  #[inline]
  pub const fn is_cookie_dir_uncovered(&self) -> bool {
    matches!(self, Self::CookieDirUncovered)
  }

  /// Whether this is [`Retired`](Self::Retired).
  #[inline]
  pub const fn is_retired(&self) -> bool {
    matches!(self, Self::Retired)
  }

  /// Whether this is [`Timeout`](Self::Timeout).
  #[inline]
  pub const fn is_timeout(&self) -> bool {
    matches!(self, Self::Timeout)
  }

  /// Whether this is [`Busy`](Self::Busy) — the retryable "another barrier is in flight" refusal.
  #[inline]
  pub const fn is_busy(&self) -> bool {
    matches!(self, Self::Busy)
  }

  /// Whether this is [`Closed`](Self::Closed).
  #[inline]
  pub const fn is_closed(&self) -> bool {
    matches!(self, Self::Closed)
  }
}

/// Why an orderly [`close`](crate::Tributaries::close) could not be confirmed.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum CloseError {
  /// The owner had already stopped before confirming the shutdown: a dropped last
  /// handle, a source that closed itself, or another racing `close` already won and
  /// tore the owner down.
  #[error("the watcher stopped before confirming the shutdown")]
  Stopped,
}

impl CloseError {
  /// Whether this is [`Stopped`](Self::Stopped).
  #[inline]
  pub const fn is_stopped(&self) -> bool {
    matches!(self, Self::Stopped)
  }
}