Expand description
tributary-proto
Pure Sans-I/O state machine — the brain of the tributaries
filesystem-notification stack. no_std-capable, modeled on quinn-proto.
§Introduction
This crate contains no I/O, no syscalls, and no clock reads. It is the
quinn-proto-style core that a driver feeds normalized OsRecords and drains Actions
and Changes from. All the logic the design calls out as easy to get wrong — recursion,
overflow handling, move pairing, watch-limit degradation — lives here as a pure,
testable state machine, written once and shared across every backend.
Most applications want the tributaries umbrella or the tributary-fs source
rather than this core directly. Reach for it when you are writing a driver of your own.
§Shape
The Monitor is the primitive-agnostic top half: it owns the proto-minted handle
registries (WatchId, ReqId, ChangeId), the parent-relative watch tree (so paths
are reconstructed by walking to a root), delivery dedup, move normalization, overflow →
ChangeKind::Rescan, emission, and — given the object Identity the driver supplies —
whether a same-name reappearance is the same object.
Backend-specific behavior enters only as data, never as a trait the engine is generic over:
- the static
Capabilitiesa monitor is built with, whose most load-bearing flag,kernel_recursive, selects whether the core descends per-directory or leans on one kernel-recursive watch per root; - the optional
Identitycarried on each record and entry.
One Monitor can host mixed backends: register_root_with_profile gives a single
scope its own capability profile, so a driver selecting per root registers each with
the profile its backend actually satisfies.
ScopeId — one disjoint watched root — is not proto-minted: the layer above supplies
it and guarantees roots are disjoint. Time is not read either; every time-dependent
input takes a now: Instant, a Duration since an opaque per-process origin the
driver chooses, so the same logic is portable across std, embedded, and test clocks.
§Driver contract
| Direction | Entry points |
|---|---|
| driver → core | on_os_record, on_enumerate, on_watch_result, on_overflow, handle_timeout |
| core → driver | poll_action, poll_event, poll_timeout |
The driver owns the WatchId ↔ raw-handle table; the core never sees a raw OS handle.
use core::num::NonZeroU64;
use tributary_proto::{Capabilities, Interest, Monitor, ScopeId};
// A kernel-recursive profile (FSEvents, fanotify-FILESYSTEM, ReadDirectoryChangesW):
// one native mark covers the whole root, so the core does not descend.
let mut monitor = Monitor::new(Capabilities::new().with_kernel_recursive());
assert!(!monitor.descends());
// The layer above supplies the scope id for each disjoint root; the returned
// `WatchId` is the handle the queued action carries.
let scope = ScopeId::new(NonZeroU64::new(1).unwrap());
let root = monitor.register_root(scope, Interest::all());
assert_eq!(monitor.scope_of(root), Some(scope));
// Drain the work the registration produced. A real driver executes each action
// against the OS and reports the outcome back through `on_watch_result`.
while let Some(_action) = monitor.poll_action() {}§Feature tiers
| Features | Environment |
|---|---|
std (default) | std hosts |
| (none) | no_std with a global allocator |
The crate floor is alloc: every configuration needs collections and strings, so with
std off the crate aliases alloc unconditionally rather than gating it behind a
feature of its own.
§Installation
[dependencies]
tributary-proto = "0.1" # std (default)
# no_std with a global allocator:
tributary-proto = { version = "0.1", default-features = false }The minimum supported Rust version (MSRV) is 1.95 (edition 2024).
§The family
tributaries (the consumer surface — overlapping subscriptions, attribution,
filters, debounce) · tributary-fs (the std async filesystem source, and the
reference driver for this core) · tributary-proto (this crate).
§License
tributary-proto 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.
Re-exports§
pub use action::Action;pub use action::EnumerateCommand;pub use action::StatChild;pub use action::StatCommand;pub use action::StatTarget;pub use action::WatchAck;pub use action::WatchChild;pub use action::WatchCommand;pub use action::WatchTarget;pub use capabilities::Capabilities;pub use change::Change;pub use change::ChangeKind;pub use error::WatchError;pub use id::ChangeId;pub use id::Epoch;pub use id::Identity;pub use id::MoveCookie;pub use id::ReqId;pub use id::ScopeId;pub use id::WatchId;pub use interest::Interest;pub use monitor::Monitor;pub use path::Location;pub use path::Segment;pub use record::DirEntry;pub use record::EnumerateResult;pub use record::FileKind;pub use record::IoClass;pub use record::OsRecord;pub use record::RecordKind;pub use scope::Scope;pub use scope::SubtreeScope;pub use time::Instant;
Modules§
- action
- Commands the core issues to the driver.
- capabilities
- Static, source-wide capabilities of a backend.
- change
- The consumer-facing change vocabulary the core emits.
- error
- Classification of a watch-installation outcome.
- fanotify
- Linux fanotify-FILESYSTEM backend profile (kernel-recursive, privileged).
- fsevents
- macOS FSEvents backend profile (kernel-recursive).
- id
- Opaque, proto-minted handles and the disjoint-root / move-pairing tokens.
- inotify
- Linux inotify backend profile (per-directory, not kernel-recursive).
- interest
- The per-watch subscription mask.
- monitor
- The primitive-agnostic top half: the
Monitorstate machine. - path
- Canonical path segments and reconstructed locations.
- record
- The normalized event vocabulary the driver feeds the core.
- scope
- The blast radius of a notification-queue overflow.
- time
- A portable, clock-agnostic monotonic instant.