Skip to main content

Crate tributary_proto

Crate tributary_proto 

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

github LoC Build codecov

docs.rs crates.io crates.io license

§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 Capabilities a 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 Identity carried 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

DirectionEntry points
driver → coreon_os_record, on_enumerate, on_watch_result, on_overflow, handle_timeout
core → driverpoll_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

FeaturesEnvironment
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 Monitor state 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.