Skip to main content

Crate tributary_fs

Crate tributary_fs 

Source
Expand description

tributary-fs

The filesystem source crate of the tributaries stack: an async, runtime-agnostic watcher over the Sans-I/O tributary-proto Monitor, driving a native backend per platform.

github LoC Build codecov

docs.rs crates.io crates.io license

§Introduction

tributary-fs is the std, async driver layer over the Sans-I/O tributary-proto Monitor: it performs the real OS filesystem watching and lowers raw kernel events into the Monitor’s normalized vocabulary. All the logic that is easy to get wrong lives in testable, sans-I/O layers; the OS callback only decodes.

  • Truth-grounded events. A backend’s flag word is a hint, not a verdict — one FSEvents event can carry created + modified + removed + renamed OR’d together — so records are grounded against lstat before delivery, and renames pair by file id into a bounded window with a safe remove + create degrade.
  • Loss is never silent. Kernel drops, a full buffer, a vanished root: every coverage gap surfaces as a Rescan event whose epoch dominates everything delivered before it.
  • Runtime-agnostic. Watcher<R: RuntimeLite> over agnostic-lite, with TokioWatcher / SmolWatcher aliases behind the tokio / smol features — or bring any other RuntimeLite implementation.
  • Unsafe is quarantined. Every unsafe platform call is confined to an internal, cfg-gated module behind a platform-neutral seam.

tributary-fs watches only disjoint roots and rejects a new root that overlaps a live one; subsuming overlapping trees is the tributaries umbrella’s job.

§Backends

A backend is selected per disjoint root — Backend::Auto by default, or forced, in which case a failing precondition is a typed spawn error rather than a silent fallback. A kernel-recursive backend covers a whole root with one native mark and the core does not descend; the per-directory profile arms a watch before reading each new directory.

BackendKindPlatformProfile
FsEventsmacOSkernel-recursive; flag words are hints
InotifyLinuxper-directory (descending); precise verbs, unprivileged — the universal default
FanotifyLinuxfanotify-FILESYSTEM: kernel-recursive, precise verbs, membership-only admission. Privileged (CAP_SYS_ADMIN)
RdcwWindowsReadDirectoryChangesW: kernel-recursive, unprivileged; the per-volume fallback when the USN journal is unusable
UsnJournalWindowsUSN change journal: kernel-recursive, journal-cursor sourced; volume-handle access effectively requires elevation

Watcher::backend_of reports what a live root actually settled on, and Watcher::backend_stats surfaces the fanotify admission-map counters for a root that keeps one. The crate compiles on every platform; where no backend exists, watching returns SourceError::Unsupported.

§Installation

[dependencies]
tributary-fs = { version = "0.1", features = ["tokio"] }

The minimum supported Rust version (MSRV) is 1.95 (edition 2024).

§Quick start

use tributary_fs::{Interest, TokioWatcher, WatcherOptions};

let mut watcher = TokioWatcher::new(WatcherOptions::new())?;
let root = watcher.watch("/path/to/project", Interest::all()).await?;
println!("watching {:?}", watcher.root_path(root));
while let Some(event) = watcher.next().await {
  println!("{}: {}", event.kind(), event.path().display());
}

WatcherOptions carries the transport knobs: the coalescing latency, the rename pairing window, the event and OS-batch capacities, path exclusions, the root-liveness probe interval, the fanotify admission-map directory cap, and the Backend selection.

§The two contracts

  • Watching means “changes from now on.” No initial inventory is delivered. Consumers that need a snapshot start the watch first, then crawl — changes racing the crawl arrive as events, and grounding makes the overlap idempotent.
  • Loss is never silent. Every coverage gap surfaces as a Rescan event whose epoch dominates everything delivered before it. That epoch is the re-enumeration contract: everything the consumer saw at a lower epoch is superseded, and a Rescan is delivered regardless of the registered interest.

§Feature flags

No feature is on by default; pick a runtime.

Any other agnostic-lite RuntimeLite implementation can drive Watcher<R> without a feature of its own.

§The family

tributaries (the consumer surface — overlapping subscriptions, attribution, filters, debounce) · tributary-fs (this crate — the std async filesystem source) · tributary-proto (the pure no_std Sans-I/O state machine).

Most applications want the tributaries umbrella. Reach for this crate directly when you manage disjoint roots yourself, or when you are binding the fs watcher into your own Source.

§License

tributary-fs is dual-licensed under the terms of both the MIT license and the Apache License (Version 2.0).

See LICENSE-APACHE, LICENSE-MIT for details.

Copyright (c) 2026 Al Liu.

Structs§

BackendStats
A lightweight, pollable snapshot of one backend’s live internals — the observability the operator owes a tripwire on (design §4.9). Surfaced per watched root by Watcher::backend_stats; only the fanotify backend populates it (every other backend has no equivalent state), so a non-fanotify root reports None rather than a zeroed struct.
ChangeId
The dedup / identity key stamped on every emitted Change.
Epoch
A per-scope monotonic reconciliation generation, stamped on every Change.
Event
One filesystem change, delivered by a Watcher.
Interest
What kinds of change a watch subscribes to.
Location
A canonical location: the sequence of Segments from a watched root to a target.
MovedEvent
The payload of a paired rename: where the object moved from.
RootHandle
An opaque handle to one watched root of a Watcher.
ScopeId
Identifies one disjoint watched root (one subtree the consumer asked for).
Segment
One canonical path component (a single name between separators).
SyncAdmission
An opaque, move-only capability admitting exactly one sync_root call, minted by THIS watcher and paired at mint with the SyncTicket that cancels the same sequence.
SyncRootDenied
Why a sync_root call did not place a cookie, plus — for a refusal that provably created nothing — the SyncAdmission handed back for a same-sequence retry.
SyncTicket
An opaque, Copy cancellation/reap key for one sync_root admission, minted by THIS watcher and paired at mint with the move-only SyncAdmission that admits the same sequence.
Watcher
An asynchronous filesystem watcher: the consumer surface of the tributary-fs driver.
WatcherOptions
Configuration for a Watcher.

Enums§

Backend
The watch primitive a Watcher should use for each root, chosen through WatcherOptions::backend.
BackendKind
Which watch primitive a spawned source is backed by — the capability report Watcher::backend_of surfaces for a live root. The core confirms the per-scope lowering profile the registration intended against it, and the Backend::Auto probe records the selection it settled on here.
BuildError
Why a Watcher could not be built.
CloseError
Why an orderly close could not be confirmed.
CoverOutcome
How an awaited coverage reconcile (Watcher::set_cover) completed.
EventKind
What kind of change an Event reports.
ProbeStage
Which Backend::Auto probe stage decided the selection (design §5, rows 2–5). Carried by SourceError::BackendProbeFailed on a forced Backend::Fanotify whose preconditions did not hold, so the caller learns exactly which one failed. A pure enum (no FFI), so it is available on every platform the error type is.
ReplaceRootError
Why Watcher::replace_root failed. The operation is atomic-on-failure: every variant leaves the old root’s coverage untouched.
RequestOutcome
The disposition of a non-blocking, reply-less control request (request_unwatch, request_set_cover).
SkipReason
Why a Watcher::set_cover reconcile was Skipped: the driver refused to run it, and prior coverage is untouched.
SourceError
Why a platform source could not start, or died.
SyncRootError
Why Watcher::sync_root could not place a sync cookie. The barrier’s observation is the caller’s job (the cookie’s event arrives on the stream); this error covers only the placement.
UnwatchError
Why a root could not be unwatched.
WatchRootError
Why a root could not be watched.

Type Aliases§

SmolWatchersmol
A Watcher driven by the smol runtime.
TokioWatchertokio
A Watcher driven by the tokio runtime.