Expand description
tributaries
The public top-level crate of the tributaries filesystem-notification stack:
overlapping watch subscriptions, subsumed onto disjoint kernel roots and attributed
back to every covering subscriber.
§Introduction
tributary-fs deliberately watches only disjoint roots (it rejects a new root
that overlaps an existing one) because subsuming overlapping trees is the layer
above’s job. tributaries is that layer. It:
- accepts possibly-overlapping watch subscriptions from the caller and
subsumes them into the disjoint roots
tributary-fsrequires — N overlapping subscriptions collapse to one kernel watch of their common ancestor; - attributes each raw event back to every caller subscription that covers its path, retagged with that subscription’s id;
- offers optional consumer conveniences — a filter and an opt-in settle/debounce coalescer — without touching the hardened core.
Everything hard (identity, move-pairing, loss-is-a-Rescan, epoch dominance) already
lives in the tributary-proto Monitor and ships through tributary-fs’s own
event type; tributaries adds routing and consumer ergonomics, not new correctness
logic.
The local-filesystem binding — FsSource, the RootHandle / WatcherOptions
re-exports, the pure-fs constructor and runtime aliases — rides the fs feature, on
by default. With it off, the crate is the generic core over tributary-proto alone:
bring your own Source (or LocalSource) and construct through
Tributaries::with_source / Tributaries::parts / Tributaries::parts_local.
§Installation
[dependencies]
tributaries = { version = "0.1", features = ["tokio"] }The minimum supported Rust version (MSRV) is 1.95 (edition 2024).
§Quick start
Watch possibly-overlapping paths — each under its own per-watch WatchOptions
(interest, Filter, Debounce posture) — optionally settle bursts with a
DebounceConfig, and pull the merged, attributed stream. Each event is retagged with
the Subscription it belongs to, so one change under an overlap is delivered to every
covering subscription under its own id.
use std::{ffi::OsString, path::Path};
use tributaries::{
Debounce, DebounceConfig, Filter, TokioTributaries, TributariesOptions, WatchOptions,
WatcherOptions,
};
// The local-fs source keys on a path's components (the caller supplies canonical paths).
fn key(path: &str) -> Vec<OsString> {
Path::new(path)
.components()
.map(|c| c.as_os_str().to_os_string())
.collect()
}
// The fs watcher's own transport options ride separately from the umbrella's knobs.
// Opt into the settle coalescer (omit `.debounce(..)` for raw pass-through).
let options = TributariesOptions::new().debounce(DebounceConfig::new());
let mut tributaries = TokioTributaries::new(WatcherOptions::new(), options)?;
// A subscription that only reports Rust sources — the filter is live-swappable.
let sources = Filter::new(|event| event.path().extension().is_some_and(|x| x == "rs"));
let handle = sources.clone(); // shares the swappable slot with the one `watch` holds
let project = tributaries
.watch(
key("/path/to/project"),
(),
WatchOptions::new().with_filter(sources),
)
.await?;
// An OVERLAPPING watch of a subtree — accepted, never `Overlaps`: it is subsumed
// onto the same kernel watch, and a change under it fans out to both subscriptions.
// Its per-watch Debounce::Off overrides the global debounce: raw pass-through for
// this subscription while `project` keeps settling.
let logs = tributaries
.watch(
key("/path/to/project/logs"),
(),
WatchOptions::new().with_debounce(Debounce::Off),
)
.await?;
// Re-scope what `project` delivers at any time — no re-watch:
handle.swap(|_| true);
// A SYNC BARRIER: after this resolves, every change made under `project`
// BEFORE the call is deliverable — read the stream and you will see it.
// Kernel-mediated (a cookie file whose own event rides the ordered queue
// behind those changes), never a hopeful sleep; the cookie is suppressed
// from the stream. `SyncOutcome` says whether the barrier was met by
// delivery or by a covering `Rescan` (re-enumerate then).
let outcome = tributaries
.sync(project, std::time::Duration::from_secs(5))
.await?;
if outcome.is_dominated() {
// A loss stood a Rescan in for the cookie: re-read rather than replay.
}
while let Some(event) = tributaries.next().await {
// `event.subscription()` is `project` or `logs`; a `Rescan` reaches every
// subscriber of the affected root regardless of filter (coverage loss).
println!(
"{} [{}]: {}",
event.kind(),
event.subscription(),
event.path().display()
);
let _ = (project, logs);
}§Subsumption
The subsumption engine is the control plane: a sans-I/O state machine over an
iradix radix keyed by canonical root paths. It plans each watch into one of three
cases — the subtree is already covered, the new path widens over existing roots
(which are drained and re-pointed onto it), or it is disjoint — keeping the live root
set pairwise disjoint at all times. It is pure logic over paths and an abstract
root-id, so it is exhaustively property-tested with no real filesystem, clock, or
runtime.
§Settle / debounce (opt-in)
A caller that only cares about the settled state of a file — not every intermediate
write of an editor-save or a cp — can opt into the coalescer by setting a
DebounceConfig on TributariesOptions. It is a second sans-I/O state machine: it
buffers attributed events per (subscription, path) and collapses a burst to a single
emission on a settle timer, while treating a Moved atomically and flushing on a
Rescan so coverage loss is never held back or lost.
The global config is a per-subscription default: each watch can override its own
posture with a Debounce on its WatchOptions — Debounce::Off for raw pass-through
while siblings settle, Debounce::Custom for its own windows (which also enables
settling when the global debounce is off). Absent a DebounceConfig and absent any
Custom override, events pass through untouched at zero cost.
§Hosting on a !Send runtime
The umbrella runs on thread-per-core / completion-based apps (compio, a pinned
LocalSet) in either of two shapes:
- A
Sendsource, a!Sendapp (the common case — the fs source isSend): spawn ONE auxiliary thread running any supported runtime, build there viaTributaries::parts, and poll the returned driver future on it. The whole handle plane is executor-agnostic and thread-mobile —TributariesisClone + Send,WatchViewis a cheapClone + Send + Syncread handle,SubscriptionisCopy— sowatch/unwatch/next/closeare awaitable from the!Sendapp directly; only the driver lives on the auxiliary thread.Demux::partsreturns aSendrouting future that can be hosted on either side. - A
!Sendsource (thread-local state, anRc, a ring handle): implementLocalSourceinstead ofSourceand construct viaTributaries::parts_local; the returned driver future is!Sendand must be polled on the thread that owns the source (block_on,LocalSet::run_until, or the executor’s own local API).
Do not reach for agnostic-lite’s spawn_local* for either shape: its smol
local spawner panics (smol has no ambient thread-local executor to target) and its
tokio one panics outside a LocalSet. Poll the future directly, or use the host
executor’s own local-spawn API.
§Feature flags
fs(default) — the local-filesystem binding overtributary-fs. Off, the crate is the generic core overtributary-protoalone, and a custom-Sourceconsumer skips the whole fs stack.tokio/smol— the async runtime, throughagnostic-lite. Orthogonal tofs: they gate the driver’sTokioTributaries/SmolTributariesaliases and forward the runtime intotributary-fsonly when the fs binding is enabled too. The sans-I/O engines need no runtime.
§The family
tributaries (this crate — the consumer surface) · tributary-fs (the std
async filesystem source) · tributary-proto (the pure no_std Sans-I/O state
machine).
The identity and coordinate primitives — ChangeId, Epoch, Location, Segment —
are owned by tributary-proto and re-exported from here directly. The per-watch
Interest is not among them: the umbrella owns its own source-neutral mask
(aligned to its EventKind), and the proto/fs Interest stays a purely fs-internal
arm mask for consumers driving a raw fs watcher.
§License
tributaries 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§
- Armed
- The outcome of a successful
Source::arm: the armed-root token plus the canonical key the source committed to. - Change
Id - The identity/coordinate primitives — change id, epoch, location — are owned by
tributary-protoand re-exported from there directly (tributary-fsmerely re-exports them itself). The per-watchInterestis not among them: the umbrella owns its own source-neutral mask (aligned toEventKind), and the proto/fsIntereststays a purely fs-internal arm mask for consumers driving a raw fs watcher. The dedup / identity key stamped on every emittedChange. - Debounce
Config - Settle/debounce policy for the opt-in coalescer (design §6).
- Demux
- The per-subscription fan-out layer outside the actor: a routing task that
consumes one
Tributarieshandle as the shared stream’s sole drainer and delivers every event into its subscription’s own boundedLane— stalling, never shedding, when a lane is full. - Epoch
- The identity/coordinate primitives — change id, epoch, location — are owned by
tributary-protoand re-exported from there directly (tributary-fsmerely re-exports them itself). The per-watchInterestis not among them: the umbrella owns its own source-neutral mask (aligned toEventKind), and the proto/fsIntereststays a purely fs-internal arm mask for consumers driving a raw fs watcher. A per-scope monotonic reconciliation generation, stamped on everyChange. - Event
- One change, delivered to a caller
Subscription, keyed by components of typeCand carrying the caller value typeV. - Filter
- A live-swappable admission predicate for one subscription (design §7), over a change’s
pre-delivery
FilterInput. - Filter
Input - The pre-delivery view a
Filterpredicate inspects (design §7): the attributes of a change known before the umbrella stamps the delivery’s epoch and bakes its owning value. - FsSource
fs - The default source: the local filesystem, over one
tributary_fs::Watcher. - Instance
Id - A process-global identity minted once per
Tributariesowner and stamped onto everySubscriptionthat owner hands out. - Interest
- Which delivered
EventKinds a subscription wants — the umbrella’s own per-subscription fan-out gate (design §5), one bit per maskable kind. - Lane
- One bounded per-subscription event stream fed by a
Demuxrouting task — either a claimed subscription’s own lane (Demux::lane) or the rest lane (Demux::spawn). - Location
- The identity/coordinate primitives — change id, epoch, location — are owned by
tributary-protoand re-exported from there directly (tributary-fsmerely re-exports them itself). The per-watchInterestis not among them: the umbrella owns its own source-neutral mask (aligned toEventKind), and the proto/fsIntereststays a purely fs-internal arm mask for consumers driving a raw fs watcher. A canonical location: the sequence ofSegments from a watched root to a target. - Root
Handle fs - The umbrella owns the source-neutral event vocabulary (
EventKind, with the move endpoint carried in-kind): each source — the fs binding included — maps into it at its binding, so the fs-only event types (tributary_fs::EventKind,tributary_fs::MovedEvent) stay intributary-fsfor fs consumers. Only the two fs-binding types surface here (with the defaultfsfeature):RootHandleis theFsSourcearmed-root token (Source::Handle), andWatcherOptionsconfigures the underlying filesystem watcher it drives. An opaque handle to one watched root of aWatcher. - Segment
- The identity/coordinate primitives — change id, epoch, location — are owned by
tributary-protoand re-exported from there directly (tributary-fsmerely re-exports them itself). The per-watchInterestis not among them: the umbrella owns its own source-neutral mask (aligned toEventKind), and the proto/fsIntereststays a purely fs-internal arm mask for consumers driving a raw fs watcher. One canonical path component (a single name between separators). - Snapshot
- An owned snapshot of a caller value
V, returned by attribution (WatchView::covering/resolve). - Source
Event - One raw change from a
Source— a plain owned data carrier of everything the umbrella’s fan-out and attribution consume to build a deliveredEventwith no information loss. - Source
Fault - A classified failure reported by a
Source: the umbrella-neutralFaultKindplus, when the source has one, the concrete source error boxed behind the standard error chain (Send + Syncpayloads only, so errors cross threads). - Subscription
- A caller-facing handle to one watch subscription.
- Sync
Token - The identity of one sync barrier, minted by the owner: unique across
concurrent syncs (
seq), across watcher instances in one process (instance), and across processes (pid). - Tributaries
- The public top-level watcher: overlapping subscriptions in, attributed events out.
- Tributaries
Options - Configuration for a
Tributarieswatcher — purely the umbrella’s own knobs. - Watch
Options - Per-watch options for one
watchcall: the fan-outInterestgate (design §5), the admissionFilter(design §7), and theDebounceposture (design §6). - Watch
View - A cheap
Clone + Send + Syncwait-free read handle over the last committed watch-set (design §5). - Watcher
Options fs - The umbrella owns the source-neutral event vocabulary (
EventKind, with the move endpoint carried in-kind): each source — the fs binding included — maps into it at its binding, so the fs-only event types (tributary_fs::EventKind,tributary_fs::MovedEvent) stay intributary-fsfor fs consumers. Only the two fs-binding types surface here (with the defaultfsfeature):RootHandleis theFsSourcearmed-root token (Source::Handle), andWatcherOptionsconfigures the underlying filesystem watcher it drives. Configuration for aWatcher.
Enums§
- Build
Error - Why a
Tributarieswatcher could not be built. - Close
Error - Why an orderly
closecould not be confirmed. - Debounce
- A subscription’s debounce posture, resolved against the watcher-global default
(
TributariesOptions::debounce) at delivery time. - Event
Kind - What kind of change an
Eventreports — the umbrella’s source-neutral vocabulary, generic over the key componentC. - Fault
Kind - The umbrella-neutral classification of a
SourceFault— owned by this crate on the same principle asEventKind: sources map their failures honestly into it at their bindings, degrading only ever towardOther(the boxed concrete error keeps the detail). - Sync
Error - Why
synccould not establish the barrier. - Sync
Outcome - How a
syncbarrier was met. - Unwatch
Error - Why a subscription could not be dropped.
- Watch
Error - Why a subscription could not be established.
Traits§
- Local
Source - The binding between the umbrella’s generic
Vec<C>key space and a concrete watcher (design §4) — the base seam, whose async methods return futures with noSendrequirement. - Source
- The multithread-spawnable variant of the source seam: the same eight items as
LocalSource, with the three async methods (arm,grow,next) promisingSendfutures.
Type Aliases§
- Smol
Tributaries fsandsmol - A
Tributariesdriven by the smol runtime, over the local filesystem. - Tokio
Tributaries fsandtokio - A
Tributariesdriven by the tokio runtime, over the local filesystem.