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.
§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
lstatbefore 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
Rescanevent whose epoch dominates everything delivered before it. - Runtime-agnostic.
Watcher<R: RuntimeLite>overagnostic-lite, withTokioWatcher/SmolWatcheraliases behind thetokio/smolfeatures — or bring any otherRuntimeLiteimplementation. - 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.
BackendKind | Platform | Profile |
|---|---|---|
FsEvents | macOS | kernel-recursive; flag words are hints |
Inotify | Linux | per-directory (descending); precise verbs, unprivileged — the universal default |
Fanotify | Linux | fanotify-FILESYSTEM: kernel-recursive, precise verbs, membership-only admission. Privileged (CAP_SYS_ADMIN) |
Rdcw | Windows | ReadDirectoryChangesW: kernel-recursive, unprivileged; the per-volume fallback when the USN journal is unusable |
UsnJournal | Windows | USN 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
Rescanevent 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 aRescanis delivered regardless of the registered interest.
§Feature flags
No feature is on by default; pick a runtime.
tokio— theTokioWatcheralias, throughagnostic-lite.smol— theSmolWatcheralias, throughagnostic-lite.
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§
- Backend
Stats - 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 reportsNonerather than a zeroed struct. - Change
Id - 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. - Moved
Event - The payload of a paired rename: where the object moved from.
- Root
Handle - 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).
- Sync
Admission - An opaque, move-only capability admitting exactly one
sync_rootcall, minted by THIS watcher and paired at mint with theSyncTicketthat cancels the same sequence. - Sync
Root Denied - Why a
sync_rootcall did not place a cookie, plus — for a refusal that provably created nothing — theSyncAdmissionhanded back for a same-sequence retry. - Sync
Ticket - An opaque,
Copycancellation/reap key for onesync_rootadmission, minted by THIS watcher and paired at mint with the move-onlySyncAdmissionthat admits the same sequence. - Watcher
- An asynchronous filesystem watcher: the consumer surface of the
tributary-fsdriver. - Watcher
Options - Configuration for a
Watcher.
Enums§
- Backend
- The watch primitive a
Watchershould use for each root, chosen throughWatcherOptions::backend. - Backend
Kind - Which watch primitive a spawned source is backed by — the capability
report
Watcher::backend_ofsurfaces for a live root. The core confirms the per-scope lowering profile the registration intended against it, and theBackend::Autoprobe records the selection it settled on here. - Build
Error - Why a
Watchercould not be built. - Close
Error - Why an orderly
closecould not be confirmed. - Cover
Outcome - How an awaited coverage reconcile (
Watcher::set_cover) completed. - Event
Kind - What kind of change an
Eventreports. - Probe
Stage - Which
Backend::Autoprobe stage decided the selection (design §5, rows 2–5). Carried bySourceError::BackendProbeFailedon a forcedBackend::Fanotifywhose 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. - Replace
Root Error - Why
Watcher::replace_rootfailed. The operation is atomic-on-failure: every variant leaves the old root’s coverage untouched. - Request
Outcome - The disposition of a non-blocking, reply-less control request
(
request_unwatch,request_set_cover). - Skip
Reason - Why a
Watcher::set_coverreconcile wasSkipped: the driver refused to run it, and prior coverage is untouched. - Source
Error - Why a platform source could not start, or died.
- Sync
Root Error - Why
Watcher::sync_rootcould 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. - Unwatch
Error - Why a root could not be unwatched.
- Watch
Root Error - Why a root could not be watched.
Type Aliases§
- Smol
Watcher smol - A
Watcherdriven by the smol runtime. - Tokio
Watcher tokio - A
Watcherdriven by the tokio runtime.