use core::error::Error;
#[cfg(all(test, not(feature = "fs")))]
mod tests;
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub struct SourceFault {
kind: FaultKind,
#[source]
source: Option<Box<dyn Error + Send + Sync>>,
}
impl SourceFault {
#[inline]
pub const fn new(kind: FaultKind) -> Self {
Self { kind, source: None }
}
#[inline]
#[must_use]
pub fn with_source(mut self, source: impl Into<Box<dyn Error + Send + Sync>>) -> Self {
self.source = Some(source.into());
self
}
#[inline]
pub const fn kind(&self) -> FaultKind {
self.kind
}
#[inline]
pub fn get_ref(&self) -> Option<&(dyn Error + Send + Sync + 'static)> {
self.source.as_deref()
}
#[inline]
pub fn downcast_ref<E>(&self) -> Option<&E>
where
E: Error + 'static,
{
self.get_ref()?.downcast_ref()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum FaultKind {
NotFound,
NotADirectory,
PermissionDenied,
Capacity,
Conflict,
Unsupported,
Other,
}
impl FaultKind {
#[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",
}
}
#[inline]
pub const fn is_not_found(&self) -> bool {
matches!(self, Self::NotFound)
}
#[inline]
pub const fn is_not_a_directory(&self) -> bool {
matches!(self, Self::NotADirectory)
}
#[inline]
pub const fn is_permission_denied(&self) -> bool {
matches!(self, Self::PermissionDenied)
}
#[inline]
pub const fn is_capacity(&self) -> bool {
matches!(self, Self::Capacity)
}
#[inline]
pub const fn is_conflict(&self) -> bool {
matches!(self, Self::Conflict)
}
#[inline]
pub const fn is_unsupported(&self) -> bool {
matches!(self, Self::Unsupported)
}
#[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())
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum BuildError {
#[error("the source could not be built")]
Source(#[source] SourceFault),
}
impl BuildError {
#[inline]
pub const fn is_source(&self) -> bool {
matches!(self, Self::Source(_))
}
#[inline]
pub const fn fault(&self) -> Option<&SourceFault> {
match self {
Self::Source(fault) => Some(fault),
}
}
#[cfg(feature = "fs")]
#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
#[inline]
pub fn as_fs(&self) -> Option<&tributary_fs::BuildError> {
self.fault()?.downcast_ref()
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum WatchError {
#[error("watch key {key} could not be canonicalized")]
Canonicalize {
key: Box<str>,
#[source]
source: SourceFault,
},
#[error("the source could not establish the watch")]
Source(#[source] SourceFault),
#[error("the watched root was removed before its watch could be armed; retry the watch")]
DeadOnArrival,
#[error("the source's committed canonical key diverged from the planned one; retry the watch")]
CanonicalRace,
#[error("retired parked-Rescan debt is at its cap; drain the event stream, then retry the watch")]
RescanBacklog,
#[error("the watcher is closed")]
Closed,
#[error(
"the source could not restore coverage for the watch; the covering Rescan dominates the gap; \
retry the watch"
)]
CoverageIncomplete,
}
impl WatchError {
#[inline]
pub fn canonicalize(key: impl Into<Box<str>>, fault: SourceFault) -> Self {
Self::Canonicalize {
key: key.into(),
source: fault,
}
}
#[inline]
pub const fn source(fault: SourceFault) -> Self {
Self::Source(fault)
}
#[inline]
pub const fn is_canonicalize(&self) -> bool {
matches!(self, Self::Canonicalize { .. })
}
#[inline]
pub const fn is_source(&self) -> bool {
matches!(self, Self::Source(_))
}
#[inline]
pub const fn is_dead_on_arrival(&self) -> bool {
matches!(self, Self::DeadOnArrival)
}
#[inline]
pub const fn is_canonical_race(&self) -> bool {
matches!(self, Self::CanonicalRace)
}
#[inline]
pub const fn is_rescan_backlog(&self) -> bool {
matches!(self, Self::RescanBacklog)
}
#[inline]
pub const fn is_closed(&self) -> bool {
matches!(self, Self::Closed)
}
#[inline]
pub const fn is_coverage_incomplete(&self) -> bool {
matches!(self, Self::CoverageIncomplete)
}
#[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,
}
}
#[cfg(feature = "fs")]
#[cfg_attr(docsrs, doc(cfg(feature = "fs")))]
#[inline]
pub fn as_fs(&self) -> Option<&tributary_fs::WatchRootError> {
self.fault()?.downcast_ref()
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum UnwatchError {
#[error("the subscription is not live")]
UnknownSubscription,
#[error("the watcher is closed")]
Closed,
}
impl UnwatchError {
#[inline]
pub const fn is_unknown_subscription(&self) -> bool {
matches!(self, Self::UnknownSubscription)
}
#[inline]
pub const fn is_closed(&self) -> bool {
matches!(self, Self::Closed)
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum SyncError {
#[error("the subscription is not live")]
UnknownSubscription,
#[error("this source does not support a sync barrier")]
Unsupported,
#[error("could not write the sync cookie: {0}")]
CookieWrite(#[source] SourceFault),
#[error("the sync cookie directory is not inside the subscription's coverage")]
CookieDirUncovered,
#[error("the subscription was unwatched while the sync was pending")]
Retired,
#[error("the sync barrier timed out")]
Timeout,
#[error(
"the subscription's root is busy (a barrier is in flight or its cookie cleanup is backlogged)"
)]
Busy,
#[error("the watcher is closed")]
Closed,
}
impl SyncError {
#[inline]
pub const fn is_unknown_subscription(&self) -> bool {
matches!(self, Self::UnknownSubscription)
}
#[inline]
pub const fn is_unsupported(&self) -> bool {
matches!(self, Self::Unsupported)
}
#[inline]
pub const fn is_cookie_write(&self) -> bool {
matches!(self, Self::CookieWrite(_))
}
#[inline]
pub const fn is_cookie_dir_uncovered(&self) -> bool {
matches!(self, Self::CookieDirUncovered)
}
#[inline]
pub const fn is_retired(&self) -> bool {
matches!(self, Self::Retired)
}
#[inline]
pub const fn is_timeout(&self) -> bool {
matches!(self, Self::Timeout)
}
#[inline]
pub const fn is_busy(&self) -> bool {
matches!(self, Self::Busy)
}
#[inline]
pub const fn is_closed(&self) -> bool {
matches!(self, Self::Closed)
}
}
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum CloseError {
#[error("the watcher stopped before confirming the shutdown")]
Stopped,
}
impl CloseError {
#[inline]
pub const fn is_stopped(&self) -> bool {
matches!(self, Self::Stopped)
}
}