Skip to main content

Crate tributaries

Crate tributaries 

Source
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.

github LoC Build codecov

docs.rs crates.io crates.io license

§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:

  1. accepts possibly-overlapping watch subscriptions from the caller and subsumes them into the disjoint roots tributary-fs requires — N overlapping subscriptions collapse to one kernel watch of their common ancestor;
  2. attributes each raw event back to every caller subscription that covers its path, retagged with that subscription’s id;
  3. 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 Send source, a !Send app (the common case — the fs source is Send): spawn ONE auxiliary thread running any supported runtime, build there via Tributaries::parts, and poll the returned driver future on it. The whole handle plane is executor-agnostic and thread-mobile — Tributaries is Clone + Send, WatchView is a cheap Clone + Send + Sync read handle, Subscription is Copy — so watch / unwatch / next / close are awaitable from the !Send app directly; only the driver lives on the auxiliary thread. Demux::parts returns a Send routing future that can be hosted on either side.
  • A !Send source (thread-local state, an Rc, a ring handle): implement LocalSource instead of Source and construct via Tributaries::parts_local; the returned driver future is !Send and 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 over tributary-fs. Off, the crate is the generic core over tributary-proto alone, and a custom-Source consumer skips the whole fs stack.
  • tokio / smol — the async runtime, through agnostic-lite. Orthogonal to fs: they gate the driver’s TokioTributaries / SmolTributaries aliases and forward the runtime into tributary-fs only 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.
ChangeId
The identity/coordinate primitives — change id, epoch, location — are owned by tributary-proto and re-exported from there directly (tributary-fs merely re-exports them itself). The per-watch Interest is not among them: the umbrella owns its own source-neutral mask (aligned to EventKind), and the proto/fs Interest stays a purely fs-internal arm mask for consumers driving a raw fs watcher. The dedup / identity key stamped on every emitted Change.
DebounceConfig
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 Tributaries handle as the shared stream’s sole drainer and delivers every event into its subscription’s own bounded Lane — stalling, never shedding, when a lane is full.
Epoch
The identity/coordinate primitives — change id, epoch, location — are owned by tributary-proto and re-exported from there directly (tributary-fs merely re-exports them itself). The per-watch Interest is not among them: the umbrella owns its own source-neutral mask (aligned to EventKind), and the proto/fs Interest stays a purely fs-internal arm mask for consumers driving a raw fs watcher. A per-scope monotonic reconciliation generation, stamped on every Change.
Event
One change, delivered to a caller Subscription, keyed by components of type C and carrying the caller value type V.
Filter
A live-swappable admission predicate for one subscription (design §7), over a change’s pre-delivery FilterInput.
FilterInput
The pre-delivery view a Filter predicate inspects (design §7): the attributes of a change known before the umbrella stamps the delivery’s epoch and bakes its owning value.
FsSourcefs
The default source: the local filesystem, over one tributary_fs::Watcher.
InstanceId
A process-global identity minted once per Tributaries owner and stamped onto every Subscription that 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 Demux routing 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-proto and re-exported from there directly (tributary-fs merely re-exports them itself). The per-watch Interest is not among them: the umbrella owns its own source-neutral mask (aligned to EventKind), and the proto/fs Interest stays a purely fs-internal arm mask for consumers driving a raw fs watcher. A canonical location: the sequence of Segments from a watched root to a target.
RootHandlefs
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 in tributary-fs for fs consumers. Only the two fs-binding types surface here (with the default fs feature): RootHandle is the FsSource armed-root token (Source::Handle), and WatcherOptions configures the underlying filesystem watcher it drives. An opaque handle to one watched root of a Watcher.
Segment
The identity/coordinate primitives — change id, epoch, location — are owned by tributary-proto and re-exported from there directly (tributary-fs merely re-exports them itself). The per-watch Interest is not among them: the umbrella owns its own source-neutral mask (aligned to EventKind), and the proto/fs Interest stays 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).
SourceEvent
One raw change from a Source — a plain owned data carrier of everything the umbrella’s fan-out and attribution consume to build a delivered Event with no information loss.
SourceFault
A classified failure reported by a 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).
Subscription
A caller-facing handle to one watch subscription.
SyncToken
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.
TributariesOptions
Configuration for a Tributaries watcher — purely the umbrella’s own knobs.
WatchOptions
Per-watch options for one watch call: the fan-out Interest gate (design §5), the admission Filter (design §7), and the Debounce posture (design §6).
WatchView
A cheap Clone + Send + Sync wait-free read handle over the last committed watch-set (design §5).
WatcherOptionsfs
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 in tributary-fs for fs consumers. Only the two fs-binding types surface here (with the default fs feature): RootHandle is the FsSource armed-root token (Source::Handle), and WatcherOptions configures the underlying filesystem watcher it drives. Configuration for a Watcher.

Enums§

BuildError
Why a Tributaries watcher could not be built.
CloseError
Why an orderly close could not be confirmed.
Debounce
A subscription’s debounce posture, resolved against the watcher-global default (TributariesOptions::debounce) at delivery time.
EventKind
What kind of change an Event reports — the umbrella’s source-neutral vocabulary, generic over the key component C.
FaultKind
The umbrella-neutral classification of a SourceFault — owned by this crate on the same principle as EventKind: sources map their failures honestly into it at their bindings, degrading only ever toward Other (the boxed concrete error keeps the detail).
SyncError
Why sync could not establish the barrier.
SyncOutcome
How a sync barrier was met.
UnwatchError
Why a subscription could not be dropped.
WatchError
Why a subscription could not be established.

Traits§

LocalSource
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 no Send requirement.
Source
The multithread-spawnable variant of the source seam: the same eight items as LocalSource, with the three async methods (arm, grow, next) promising Send futures.

Type Aliases§

SmolTributariesfs and smol
A Tributaries driven by the smol runtime, over the local filesystem.
TokioTributariesfs and tokio
A Tributaries driven by the tokio runtime, over the local filesystem.