use std::{
collections::{BTreeMap, HashMap, VecDeque},
ffi::OsString,
io,
marker::PhantomData,
num::NonZeroU64,
path::{Path, PathBuf},
time::Duration,
};
use agnostic_lite::tokio::TokioRuntime;
use tributary_proto::{ChangeId, Epoch, Location};
use super::{Owner, epoch::EpochLedger};
use crate::{
coalesce::Coalescer,
error::{FaultKind, SourceFault, UnwatchError, WatchError},
event::{Event, EventKind},
filter::Filter,
interest::Interest,
options::{Debounce, DebounceConfig, TributariesOptions, WatchOptions},
source::{Armed, Source, SourceEvent, SyncToken},
subscription::Subscription,
subsume::Subsumer,
};
fn key(path: &str) -> Vec<OsString> {
components(Path::new(path))
}
fn components(path: &Path) -> Vec<OsString> {
path
.components()
.map(|c| c.as_os_str().to_os_string())
.collect()
}
#[derive(Debug, Clone, PartialEq, Eq)]
enum Call {
Arm(PathBuf),
Disarm(u32),
Replace(u32, PathBuf),
SetCover(u32, Vec<Vec<OsString>>),
Grow(u32, Vec<Vec<OsString>>),
}
enum ScriptStep {
Pending,
PendingThenComplete,
Ready,
}
struct ScriptedBegin<'a> {
script: &'a mut VecDeque<ScriptStep>,
delivered: &'a mut Vec<Vec<OsString>>,
cookie_key: Vec<OsString>,
}
impl std::future::Future for ScriptedBegin<'_> {
type Output = Vec<OsString>;
fn poll(
self: std::pin::Pin<&mut Self>,
_cx: &mut std::task::Context<'_>,
) -> std::task::Poll<Vec<OsString>> {
let this = self.get_mut();
match this.script.pop_front() {
Some(ScriptStep::Ready) => std::task::Poll::Ready(this.cookie_key.clone()),
Some(ScriptStep::PendingThenComplete) => {
this.delivered.push(this.cookie_key.clone());
std::task::Poll::Pending
}
Some(ScriptStep::Pending) | None => std::task::Poll::Pending,
}
}
}
struct FakeSource {
next_handle: u32,
calls: Vec<Call>,
live: HashMap<u32, PathBuf>,
canonical: HashMap<u32, Vec<OsString>>,
supports_replace: bool,
supports_sync: bool,
ended_syncs: Vec<Vec<OsString>>,
cancelled_syncs: Vec<SyncToken>,
begun_token: Option<SyncToken>,
sync_script: VecDeque<ScriptStep>,
fs_delivered: Vec<Vec<OsString>>,
fail_arms: u32,
fail_grows: u32,
dead_on_arrival_arms: u32,
retarget: HashMap<PathBuf, PathBuf>,
canonicalize: HashMap<Vec<OsString>, Option<Vec<OsString>>>,
reuse_next_handle: Option<u32>,
actual_cover: HashMap<u32, Vec<Vec<OsString>>>,
pending_events: VecDeque<SourceEvent<OsString, u32>>,
next_replace_epoch: u64,
}
impl FakeSource {
fn new() -> Self {
Self {
next_handle: 0,
calls: Vec::new(),
live: HashMap::new(),
canonical: HashMap::new(),
supports_replace: false,
supports_sync: false,
ended_syncs: Vec::new(),
cancelled_syncs: Vec::new(),
begun_token: None,
sync_script: VecDeque::new(),
fs_delivered: Vec::new(),
fail_arms: 0,
fail_grows: 0,
dead_on_arrival_arms: 0,
retarget: HashMap::new(),
canonicalize: HashMap::new(),
reuse_next_handle: None,
actual_cover: HashMap::new(),
pending_events: VecDeque::new(),
next_replace_epoch: 1,
}
}
fn actual_covers(&self, handle: u32, key: &[OsString]) -> bool {
match self.actual_cover.get(&handle) {
Some(cover) => cover
.iter()
.any(|prefix| key.starts_with(prefix.as_slice())),
None => self
.canonical
.get(&handle)
.is_some_and(|root| key.starts_with(root.as_slice())),
}
}
fn apply_cover(&mut self, handle: u32, retained: &[Vec<OsString>]) {
let root_is_covered = self.canonical.get(&handle).is_some_and(|root| {
retained
.iter()
.any(|prefix| prefix.as_slice() == root.as_slice())
});
if root_is_covered {
self.actual_cover.remove(&handle);
} else {
self.actual_cover.insert(handle, retained.to_vec());
}
}
fn canonicalizes_to(&mut self, from: &str, to: &str) {
self.canonicalize.insert(key(from), Some(key(to)));
}
fn cannot_canonicalize(&mut self, k: &str) {
self.canonicalize.insert(key(k), None);
}
fn reuse_next_arm_handle(&mut self, handle: u32) {
self.reuse_next_handle = Some(handle);
}
fn fail_next_arm(&mut self) {
self.fail_arms = 1;
}
fn fail_next_grow(&mut self) {
self.fail_grows = 1;
}
fn dead_on_arrival_next_arm(&mut self) {
self.dead_on_arrival_arms = 1;
}
fn fail_next_arms(&mut self, n: u32) {
self.fail_arms = n;
}
fn retarget(&mut self, planned: &str, fs: &str) {
self
.retarget
.insert(PathBuf::from(planned), PathBuf::from(fs));
}
fn kill_root(&mut self, handle: u32) {
self.canonical.remove(&handle);
self.live.remove(&handle);
}
fn calls(&self) -> Vec<Call> {
self.calls.clone()
}
fn arm_count(&self) -> usize {
self
.calls
.iter()
.filter(|c| matches!(c, Call::Arm(_)))
.count()
}
}
impl Source<OsString> for FakeSource {
type Handle = u32;
fn canonicalize_key(&self, k: &[OsString]) -> Result<Vec<OsString>, WatchError> {
match self.canonicalize.get(k) {
Some(Some(canonical)) => Ok(canonical.clone()),
Some(None) => Err(WatchError::canonicalize(
k.iter().collect::<PathBuf>().display().to_string(),
SourceFault::new(FaultKind::NotFound)
.with_source(io::Error::other("injected non-canonicalizable key")),
)),
None => Ok(k.to_vec()),
}
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
let path: PathBuf = key.iter().collect();
self.calls.push(Call::Arm(path.clone()));
if self.fail_arms > 0 {
self.fail_arms -= 1;
return Err(WatchError::source(
SourceFault::new(FaultKind::Other).with_source(io::Error::other("injected arm failure")),
));
}
if let Some(existing) = self
.live
.values()
.find(|live| path.starts_with(live) || live.starts_with(&path))
.cloned()
{
return Err(WatchError::source(
SourceFault::new(FaultKind::Conflict).with_source(io::Error::other(format!(
"fake root {} overlaps the already-armed {}",
path.display(),
existing.display()
))),
));
}
let handle = match self.reuse_next_handle.take() {
Some(forced) => forced,
None => {
self.next_handle += 1;
self.next_handle
}
};
let canonical_path = self
.retarget
.get(&path)
.cloned()
.unwrap_or_else(|| path.clone());
let canonical_key = components(&canonical_path);
if self.dead_on_arrival_arms > 0 {
self.dead_on_arrival_arms -= 1;
return Ok(Armed::new(handle, canonical_key));
}
self.canonical.insert(handle, canonical_key.clone());
self.live.insert(handle, path);
Ok(Armed::new(handle, canonical_key))
}
fn is_sync_artifact(&self, key: &[OsString]) -> bool {
key
.last()
.and_then(|leaf| leaf.to_str())
.is_some_and(|leaf| leaf.starts_with("cookie-"))
}
fn end_sync(&mut self, _handle: u32, cookie_key: &[OsString]) {
self.ended_syncs.push(cookie_key.to_vec());
}
fn cancel_sync(&mut self, _handle: u32, token: SyncToken) {
self.cancelled_syncs.push(token);
}
async fn begin_sync(
&mut self,
_handle: u32,
dir_key: &[OsString],
token: SyncToken,
) -> Result<Vec<OsString>, crate::error::SyncError> {
if !self.supports_sync {
return Err(crate::error::SyncError::Unsupported);
}
self.begun_token = Some(token);
let mut cookie_key = dir_key.to_vec();
cookie_key.push(OsString::from(format!("cookie-{}", token.seq())));
if self.sync_script.is_empty() {
return Ok(cookie_key);
}
let delivered = ScriptedBegin {
script: &mut self.sync_script,
delivered: &mut self.fs_delivered,
cookie_key,
}
.await;
Ok(delivered)
}
async fn replace(
&mut self,
handle: u32,
new_key: &[OsString],
) -> Result<Armed<OsString, u32>, WatchError> {
if !self.supports_replace {
return Err(WatchError::source(SourceFault::new(FaultKind::Unsupported)));
}
let path: PathBuf = new_key.iter().collect();
self.calls.push(Call::Replace(handle, path.clone()));
let canonical_path = self
.retarget
.get(&path)
.cloned()
.unwrap_or_else(|| path.clone());
let canonical: Vec<OsString> = components(&canonical_path);
self.live.insert(handle, canonical_path);
self.canonical.insert(handle, canonical.clone());
let epoch = self.next_replace_epoch;
self.next_replace_epoch += 1;
self.pending_events.push_back(SourceEvent::new(
handle,
canonical.clone(),
EventKind::Rescan,
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
));
Ok(Armed::new(handle, canonical))
}
fn disarm(&mut self, handle: u32) {
self.calls.push(Call::Disarm(handle));
self.canonical.remove(&handle);
self.live.remove(&handle);
}
fn set_cover(&mut self, handle: u32, retained: &[Vec<OsString>]) {
self.calls.push(Call::SetCover(handle, retained.to_vec()));
self.apply_cover(handle, retained);
}
async fn grow(&mut self, handle: u32, retained: &[Vec<OsString>]) -> Result<(), WatchError> {
self.calls.push(Call::Grow(handle, retained.to_vec()));
if self.fail_grows > 0 {
self.fail_grows -= 1;
return Err(WatchError::CoverageIncomplete);
}
self.apply_cover(handle, retained);
Ok(())
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
self.pending_events.pop_front()
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.canonical.get(&handle).cloned()
}
}
fn rescan_event(handle: u32, path: &str, epoch: u64) -> SourceEvent<OsString, u32> {
SourceEvent::new(
handle,
key(path),
EventKind::Rescan,
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
)
}
fn modified_event(sub: Subscription, path: &str, epoch: u64) -> Event<OsString, ()> {
Event::synthetic(
sub,
key(path),
Location::new(),
EventKind::Modified,
Epoch::new(epoch),
)
}
fn source_modified(handle: u32, path: &str, epoch: u64) -> SourceEvent<OsString, u32> {
SourceEvent::new(
handle,
key(path),
EventKind::Modified,
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
)
}
fn source_removed(handle: u32, path: &str, epoch: u64) -> SourceEvent<OsString, u32> {
SourceEvent::new(
handle,
key(path),
EventKind::Removed,
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
)
}
fn source_created(handle: u32, path: &str, epoch: u64) -> SourceEvent<OsString, u32> {
SourceEvent::new(
handle,
key(path),
EventKind::Created,
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
)
}
fn source_moved(handle: u32, from: &str, to: &str, epoch: u64) -> SourceEvent<OsString, u32> {
SourceEvent::new(
handle,
key(to),
EventKind::Moved { from: key(from) },
Location::new(),
Epoch::new(epoch),
Some(ChangeId::new(NonZeroU64::MIN)),
)
}
struct Harness {
owner: Owner<OsString, (), TokioRuntime, FakeSource>,
events: async_channel::Receiver<Event<OsString, ()>>,
_commands: async_channel::Sender<super::Command<OsString, ()>>,
_sync_commands: async_channel::Sender<super::SyncRequest>,
closes: async_channel::Sender<super::CloseReply>,
}
impl Harness {
fn new() -> Self {
Self::with_coalescer(None)
}
fn with_coalescer(coalescer: Option<Coalescer<OsString, ()>>) -> Self {
Self::build(coalescer, None)
}
fn bounded(capacity: usize) -> Self {
Self::build(None, Some(capacity))
}
fn build(coalescer: Option<Coalescer<OsString, ()>>, capacity: Option<usize>) -> Self {
let (event_tx, event_rx) = match capacity {
Some(cap) => async_channel::bounded(cap),
None => async_channel::unbounded(),
};
let (command_tx, command_rx) = async_channel::unbounded();
let (sync_command_tx, sync_command_rx) = async_channel::unbounded::<super::SyncRequest>();
let (close_tx, close_rx) = async_channel::bounded(1);
let (cleanup_tx, cleanup_rx) = async_channel::unbounded();
let owner = Owner {
source: FakeSource::new(),
subsumer: Subsumer::new(),
epochs: EpochLedger::new(),
filters: HashMap::new(),
needs_rescan: BTreeMap::new(),
suppressed_rescan: BTreeMap::new(),
unclaimed: std::collections::HashSet::new(),
flush_cursor: None,
#[cfg(test)]
last_flush_visited: 0,
#[cfg(test)]
test_pre_cut_claims: Vec::new(),
debounce: None,
coalescer,
pending_syncs: Vec::new(),
sync_seq: 0,
sync_nonce_seed: std::collections::hash_map::RandomState::new(),
loss_serial: HashMap::new(),
loss_gen: std::sync::Arc::new(core::sync::atomic::AtomicU64::new(0)),
cleanup_tx,
cleanup_rx,
commands: command_rx,
sync_commands: sync_command_rx,
closes: close_rx,
events: event_tx,
#[cfg(debug_assertions)]
observed_handles: std::collections::HashSet::new(),
_rt: PhantomData::<TokioRuntime>,
};
Self {
owner,
events: event_rx,
_commands: command_tx,
_sync_commands: sync_command_tx,
closes: close_tx,
}
}
async fn watch(&mut self, path: &str, interest: Interest) -> Result<Subscription, WatchError> {
self
.watch_with(path, WatchOptions::new().with_interest(interest))
.await
}
async fn watch_with(
&mut self,
path: &str,
options: WatchOptions<OsString>,
) -> Result<Subscription, WatchError> {
self
.owner
.reconcile_watch(&key(path), (), options)
.await
.map_err(|stop| match stop {
super::ReconcileStop::Failed(err) => err,
super::ReconcileStop::CloseRequested(_) => {
unreachable!("no close is sent to a directly-driven harness owner")
}
})
}
fn unwatch(&mut self, sub: Subscription) -> Result<(), UnwatchError> {
self.owner.release_subscription(sub)
}
fn drain(&self) -> Vec<Event<OsString, ()>> {
let mut out = Vec::new();
while let Ok(event) = self.events.try_recv() {
out.push(event);
}
out
}
}
#[tokio::test]
async fn overlapping_watch_issues_one_arm() {
let mut h = Harness::new();
h.watch("/a", Interest::all()).await.expect("watch /a");
let covered = h.watch("/a/b", Interest::all()).await;
assert!(
covered.is_ok(),
"an overlapping watch never surfaces Overlaps"
);
assert_eq!(
h.owner.source.arm_count(),
1,
"two overlapping subscriptions collapse to exactly one arm"
);
let arms: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Arm(_)))
.collect();
assert_eq!(
arms,
vec![Call::Arm(PathBuf::from("/a"))],
"only the covering root /a is armed"
);
}
#[tokio::test]
async fn a_foreign_subscription_cannot_unwatch_a_local_one_with_a_colliding_scope_id() {
let mut a = Harness::new();
let mut b = Harness::new();
let a_sub = a.watch("/x", Interest::all()).await.expect("watch on A");
let b_sub = b.watch("/x", Interest::all()).await.expect("watch on B");
assert_eq!(
a_sub.id(),
b_sub.id(),
"the two owners minted a colliding ScopeId"
);
assert_ne!(
a_sub, b_sub,
"…but the per-watcher instance brand makes them distinct handles"
);
let err = b
.unwatch(a_sub)
.expect_err("a foreign subscription is rejected");
assert!(
err.is_unknown_subscription(),
"a foreign handle is Unknown, not applied to B's colliding subscription"
);
assert!(
b.owner.subsumer.view().is_watched(&key("/x")),
"B's subscription stays live after rejecting the foreign unwatch"
);
b.unwatch(b_sub)
.expect("B's own subscription is still live and unwatchable");
}
#[tokio::test]
async fn widen_prefers_the_gapless_in_place_replace_when_the_source_offers_it() {
let mut h = Harness::new();
h.owner.source.supports_replace = true;
let s_narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_wide = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Replace(1, PathBuf::from("/a")),
],
"a widen the source can do in place must never release-and-rearm"
);
let roots: Vec<(PathBuf, u32)> = h
.owner
.subsumer
.roots()
.map(|(k, handle)| (PathBuf::from_iter(k), handle))
.collect();
assert_eq!(
roots,
vec![(PathBuf::from("/a"), 1)],
"one root, widened, on the preserved handle"
);
let rescans: Vec<Subscription> = h
.drain()
.into_iter()
.filter(|e| e.kind().is_rescan())
.map(|e| e.subscription())
.collect();
assert!(
rescans.contains(&s_narrow),
"the re-pointed subscription is rebased onto the wider root: {rescans:?}"
);
let _ = s_wide;
}
#[tokio::test]
async fn widen_falls_back_to_release_and_rearm_without_replace_support() {
let mut h = Harness::new();
let _narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
h.watch("/a", Interest::all()).await.expect("watch /a");
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Disarm(1),
Call::Arm(PathBuf::from("/a")),
],
"without in-place support the widen still releases and re-arms"
);
}
#[tokio::test]
async fn widen_disarms_subsumed_before_arming_the_wider_root() {
let mut h = Harness::new();
let s_narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
h.watch("/a", Interest::all())
.await
.expect("watch /a widens (subsumed /a/b disarmed first, so the wider arm is legal)");
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Disarm(1),
Call::Arm(PathBuf::from("/a")),
],
"disarm-subsumed precedes arm-wider on a widen (the only real-executable order)"
);
let roots: Vec<PathBuf> = h
.owner
.subsumer
.roots()
.map(|(k, _)| PathBuf::from_iter(k))
.collect();
assert_eq!(
roots,
vec![PathBuf::from("/a")],
"the widen collapses to /a"
);
let rescans = h.drain();
assert_eq!(rescans.len(), 1, "one dominating Rescan per re-pointed sub");
assert!(rescans[0].is_rescan(), "the re-point signal is a Rescan");
assert_eq!(
rescans[0].subscription(),
s_narrow,
"it is delivered to the re-pointed subscriber"
);
assert_eq!(
rescans[0].path(),
Path::new("/a"),
"the Rescan names the widened root the consumer must re-enumerate"
);
}
#[tokio::test]
async fn arm_failure_abandons_plan_no_pending_leak() {
let mut h = Harness::new();
h.owner.source.fail_next_arm();
let result = h.watch("/a", Interest::all()).await;
assert!(result.is_err(), "a failed arm surfaces the error");
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"a failed arm abandons the plan — no pending reservation leaks"
);
h.watch("/a", Interest::all())
.await
.expect("watch /a after the earlier failure");
assert_eq!(
h.owner.source.arm_count(),
2,
"the retried watch arms again (the failed plan left no live root)"
);
}
#[tokio::test]
async fn disjoint_dead_on_arrival_arm_fails_no_root_committed() {
let mut h = Harness::new();
h.owner.source.dead_on_arrival_next_arm();
let result = h.watch("/a", Interest::all()).await;
let err = result.expect_err("a dead-on-arrival fresh arm fails the watch");
assert!(
err.is_dead_on_arrival(),
"the failure is the dead-on-arrival arm error, got {err:?}"
);
assert_eq!(
h.owner.source.calls(),
vec![Call::Arm(PathBuf::from("/a")), Call::Disarm(1)],
"the dead-on-arrival handle is best-effort disarmed, not committed"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the failed arm abandons the plan — no pending reservation leaks"
);
assert!(
!h.owner.subsumer.view().is_watched(&key("/a")),
"NO root is committed for a dead-on-arrival arm (fail-on-old: is_watched true)"
);
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"no root is recorded (fail-on-old: the dead handle is committed as a root)"
);
h.watch("/a", Interest::all())
.await
.expect("watch /a after the dead-on-arrival failure");
assert_eq!(
h.owner.source.arm_count(),
2,
"the retried watch arms again (the dead-on-arrival plan left no live root)"
);
}
#[tokio::test]
async fn widen_emits_dominating_rescan_per_repointed_sub() {
let mut h = Harness::new();
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.epochs.stamp(sb, Epoch::new(4));
h.owner.epochs.stamp(sc, Epoch::new(2));
h.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let rescans = h.drain();
assert_eq!(rescans.len(), 2, "one Rescan per re-pointed subscription");
for ev in &rescans {
assert!(ev.is_rescan(), "the synthetic event is a Rescan");
assert_eq!(ev.path(), Path::new("/a"), "it names the widened root");
}
let by_sub: HashMap<Subscription, Epoch> = rescans
.iter()
.map(|ev| (ev.subscription(), ev.epoch()))
.collect();
assert_eq!(
by_sub.get(&sb).copied(),
Some(Epoch::new(5)),
"sb's Rescan strictly dominates its high-water of 4"
);
assert_eq!(
by_sub.get(&sc).copied(),
Some(Epoch::new(3)),
"sc's Rescan strictly dominates its high-water of 2"
);
}
#[tokio::test]
async fn over_broad_unwatch_set_covers_root_in_place() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let _s_bc = h
.watch("/a/b/c", Interest::all())
.await
.expect("watch /a/b/c covered");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::SetCover(handle, _) if *handle == wide)),
"no prune of the wide root before the over-broadening unwatch"
);
h.unwatch(s_a).expect("unwatch the widening /a");
let shrinks: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(handle, _) if *handle == wide))
.collect();
assert_eq!(
shrinks,
vec![Call::SetCover(wide, vec![key("/a/b")])],
"exactly one shrink of the wide root to the nested-survivor antichain /a/b (not the raw \
{{/a/b, /a/b/c}})"
);
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::Disarm(handle) if *handle == wide)),
"an over-broad drop shrinks the surviving root, never disarms it"
);
}
#[tokio::test]
async fn narrow_unwatch_does_not_set_cover() {
let mut h = Harness::new();
let _s_a = h.watch("/a", Interest::all()).await.expect("watch /a");
let s_b = h
.watch("/a/b", Interest::all())
.await
.expect("watch /a/b covered");
let shrinks_before: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(..)))
.collect();
h.unwatch(s_b).expect("unwatch /a/b");
let shrinks_after: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(..)))
.collect();
assert_eq!(
shrinks_before, shrinks_after,
"a narrower drop widens no gap — the root stays pinned by its own /a subscriber, so the unwatch \
fires no shrink"
);
}
#[tokio::test]
async fn over_broad_droporphan_also_set_covers() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.owner.apply_cleanup(super::Cleanup::DropOrphan(s_a));
let shrinks: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(..)))
.collect();
assert_eq!(
shrinks,
vec![Call::SetCover(wide, vec![key("/a/b")])],
"the orphan release shrinks the over-broad root too (uniform sync call-site)"
);
}
#[tokio::test]
async fn covered_outside_grows_then_repins_to_full() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::SetCover(handle, _) | Call::Grow(handle, _) if *handle == wide)),
"no cover call on the wide root before any over-broadening drop or covered-outside commit"
);
h.unwatch(s_a).expect("unwatch the widening /a");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"the prune narrowed the record to {{/a/b}}"
);
let _s_c = h
.watch("/a/c", Interest::all())
.await
.expect("watch /a/c covered-outside");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the grow broadened the record EXACTLY to {{/a/b, /a/c}} (broaden-on-return)"
);
let _s_a2 = h
.watch("/a", Interest::all())
.await
.expect("watch /a again covered");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
None,
"re-pinning the root at its own key grows back to FULL and clears the record"
);
let covers: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(handle, _) | Call::Grow(handle, _) if *handle == wide))
.collect();
assert_eq!(
covers,
vec![
Call::SetCover(wide, vec![key("/a/b")]),
Call::Grow(wide, vec![key("/a/b"), key("/a/c")]),
Call::Grow(wide, vec![key("/a")]),
],
"one PRUNE then two GROWs, each carrying the fresh cover: the {{/a/b}} survivor drop, then the \
grow to {{/a/b, /a/c}}, then the cancel-equivalent grow to FULL {{/a}}"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/c")),
"the grow covered /a/c"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/z")),
"the cancel-equivalent grew back to FULL coverage under /a"
);
}
#[tokio::test]
async fn covered_outside_narrowed_root_grows_before_returning() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
assert!(
h.owner.source.actual_covers(wide, &key("/a/b")),
"the retained /a/b survivor stays covered after the prune"
);
assert!(
!h.owner.source.actual_covers(wide, &key("/a/c")),
"the pruned /a/c is NOT covered before the newcomer (the narrowed source state)"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"the record narrowed to {{/a/b}} on the prune issue"
);
let grows_before = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.count();
let s_c = h
.watch("/a/c", Interest::all())
.await
.expect("watch /a/c covered-outside");
assert!(
!h.owner.needs_rescan.contains_key(&s_c),
"no bridge Rescan is parked for the covered-outside newcomer — coverage is live on return (v3)"
);
let grows_after: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.collect();
assert!(
grows_after.len() > grows_before,
"the covered-outside commit issued a Call::Grow (the grow trigger)"
);
assert_eq!(
grows_after,
vec![Call::Grow(wide, vec![key("/a/b"), key("/a/c")])],
"the grow carried the fresh survivor+newcomer cover {{/a/b, /a/c}}"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/c")),
"the source grew its actual coverage to include /a/c before the watch returned"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/b")),
"the retained /a/b never lost coverage across the grow (no gap, no re-crawl)"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the record broadened EXACTLY on grow-return, matching the source's live coverage"
);
}
#[tokio::test]
async fn second_covered_inside_the_grown_cover_does_not_regrow() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
let _s_c = h
.watch("/a/c", Interest::all())
.await
.expect("watch /a/c covered-outside grows");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the first grow broadened the record EXACTLY to {{/a/b, /a/c}}"
);
let grows_before = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.count();
let s_cx = h
.watch("/a/c/x", Interest::all())
.await
.expect("watch /a/c/x covered-INSIDE");
assert!(
!h.owner.needs_rescan.contains_key(&s_cx),
"an inside-cover newcomer parks no bridge — coverage already backs it"
);
let grows_after = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.count();
assert_eq!(
grows_after, grows_before,
"an inside-cover newcomer issues NO grow (the exact broadened record classifies it INSIDE)"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the record is unchanged by an inside-cover newcomer"
);
}
#[tokio::test]
async fn grow_then_unwatch_non_root_reprunes() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
let s_c = h
.watch("/a/c", Interest::all())
.await
.expect("watch /a/c covered-outside grows");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the grow broadened the record to {{/a/b, /a/c}}"
);
let prunes_before = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(handle, _) if *handle == wide))
.count();
h.unwatch(s_c).expect("unwatch the non-root /a/c");
let prunes_after: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::SetCover(handle, _) if *handle == wide))
.collect();
assert_eq!(
prunes_after.len(),
prunes_before + 1,
"the non-root unwatch issued exactly one re-prune of the wide root"
);
assert_eq!(
prunes_after.last(),
Some(&Call::SetCover(wide, vec![key("/a/b")])),
"the re-prune carries the shrunken {{/a/b}} antichain"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"the record narrowed on the F2 re-prune issue"
);
assert!(
!h.owner.source.actual_covers(wide, &key("/a/c")),
"the /a/c coverage was reclaimed by the re-prune"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/b")),
"the retained /a/b survivor keeps coverage"
);
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::Disarm(handle) if *handle == wide)),
"the re-prune reclaims in place, never disarms the surviving root"
);
}
#[tokio::test]
async fn source_rescan_degrades_the_retained_cover_so_newcomers_regrow() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"the prune narrowed the record to {{/a/b}}"
);
let _ = h.drain();
let _s_inside = h
.watch("/a/b/deep", Interest::all())
.await
.expect("a covered-inside newcomer commits");
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::Grow(handle, _) if *handle == wide)),
"inside the retained cover no grow is needed"
);
let loss = rescan_event(wide, "/a/b", 1);
h.owner.consume_source_event(&loss);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![]),
"the narrowed record degraded to the empty cover — it claims nothing below the root"
);
let _ = h.drain();
let _s2 = h
.watch("/a/b/deeper", Interest::all())
.await
.expect("the post-loss newcomer commits through a re-proving grow");
let grows: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.collect();
assert_eq!(
grows.len(),
1,
"the post-loss newcomer drove exactly one grow"
);
let Call::Grow(_, grown) = &grows[0] else {
unreachable!("filtered to grows");
};
assert!(
grown
.iter()
.any(|k| key("/a/b/deeper").starts_with(k.as_slice())),
"the grown antichain covers the newcomer, got {grown:?}"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/b/deeper")),
"the newcomer's subtree is genuinely covered after the grow"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(grown.clone()),
"the record broadened exactly to the grown cover"
);
}
#[tokio::test]
async fn post_degrade_unwatch_keeps_the_record_degraded_until_a_grow_re_proves() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
let s_c = h
.watch("/a/c", Interest::all())
.await
.expect("watch /a/c grows the cover");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the grown record names both survivors"
);
let _ = h.drain();
let loss = rescan_event(wide, "/a", 1);
h.owner.consume_source_event(&loss);
assert_eq!(h.owner.subsumer.retained_cover_of(wide), Some(vec![]));
let calls_before = h.owner.source.calls().len();
h.unwatch(s_c).expect("unwatch the /a/c sibling");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![]),
"the record stays degraded across the unwatch — survivors are not proof of coverage"
);
assert!(
!h.owner.source.calls()[calls_before..]
.iter()
.any(|c| matches!(c, Call::SetCover(handle, _) if *handle == wide)),
"no reclaim prune is issued against a degraded record"
);
let _s2 = h
.watch("/a/b/x", Interest::all())
.await
.expect("the post-unwatch newcomer commits through a re-proving grow");
let grows: Vec<Call> = h.owner.source.calls()[calls_before..]
.iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.cloned()
.collect();
assert_eq!(grows.len(), 1, "the newcomer drove the re-proving grow");
assert!(
h.owner.source.actual_covers(wide, &key("/a/b/x")),
"the newcomer's subtree is genuinely covered after the grow"
);
}
#[tokio::test]
async fn covered_outside_grow_failure_fails_the_watch_and_broadens_nothing() {
let mut h = Harness::new();
let _s_b = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let s_a = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let wide = h
.owner
.subsumer
.roots()
.find(|(k, _)| *k == key("/a").as_slice())
.map(|(_, handle)| handle)
.expect("the wide /a root is live");
h.unwatch(s_a).expect("unwatch the widening /a");
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"the prune narrowed the record to {{/a/b}}"
);
let _ = h.drain();
let filters_before = h.owner.filters.len();
h.owner.source.fail_next_grow();
let err = h
.watch("/a/c", Interest::all())
.await
.expect_err("a failed covered-outside grow fails the watch (grow-before-commit)");
assert!(
err.is_coverage_incomplete(),
"the failure is the retryable CoverageIncomplete, got {err:?}"
);
let grows: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.collect();
assert_eq!(
grows,
vec![Call::Grow(wide, vec![key("/a/b"), key("/a/c")])],
"the failed grow carried the fresh {{/a/b, /a/c}} cover"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b")]),
"no broaden on a failed grow — the record still names the source's true coverage"
);
assert!(
!h.owner.source.actual_covers(wide, &key("/a/c")),
"the newcomer's subtree is NOT covered after the failed grow"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/b")),
"survivor coverage is untouched by the failed grow (never moves)"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the aborted plan leaks no pending reservation"
);
assert!(
!h.owner.subsumer.view().is_watched(&key("/a/c")),
"the failed watch is never published as watched"
);
assert_eq!(
h.owner.filters.len(),
filters_before,
"no filter was registered for the never-committed subscription"
);
assert!(
h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.is_empty(),
"no parked Rescan debt for a never-committed subscription"
);
assert!(
h.drain().is_empty(),
"the failed watch delivered nothing (existing subscribers are covered by the source's own \
in-band Rescan, per the grow error contract — not by the umbrella)"
);
let _s_c = h
.watch("/a/c", Interest::all())
.await
.expect("the identical retry succeeds");
let grows_after: Vec<Call> = h
.owner
.source
.calls()
.into_iter()
.filter(|c| matches!(c, Call::Grow(handle, _) if *handle == wide))
.collect();
assert_eq!(
grows_after,
vec![
Call::Grow(wide, vec![key("/a/b"), key("/a/c")]),
Call::Grow(wide, vec![key("/a/b"), key("/a/c")]),
],
"the retry re-issued the SAME grow — the unbroadened record classified it outside-cover again"
);
assert_eq!(
h.owner.subsumer.retained_cover_of(wide),
Some(vec![key("/a/b"), key("/a/c")]),
"the successful retry broadened the record exactly on grow-Ok"
);
assert!(
h.owner.source.actual_covers(wide, &key("/a/c")),
"the retry's grow applied — the newcomer's subtree is live"
);
assert!(
h.owner.subsumer.view().is_watched(&key("/a/c")),
"the retry committed and published"
);
}
#[tokio::test]
async fn widen_arm_failure_restores_disarmed_roots() {
let mut h = Harness::new();
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.epochs.stamp(sb, Epoch::new(4));
h.owner.epochs.stamp(sc, Epoch::new(2));
h.owner.source.fail_next_arm();
let result = h.watch("/a", Interest::all()).await;
assert!(result.is_err(), "the failed wider arm surfaces the error");
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Arm(PathBuf::from("/a/c")),
Call::Disarm(1),
Call::Disarm(2),
Call::Arm(PathBuf::from("/a")),
Call::Arm(PathBuf::from("/a/b")),
Call::Arm(PathBuf::from("/a/c")),
],
"the failed widen re-arms the disarmed subsumed roots (restore, not strand)"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the aborted widen leaks no pending reservation"
);
let view = h.owner.subsumer.view();
assert!(
view.is_watched(&key("/a/b")) && view.is_watched(&key("/a/c")),
"the restored subscriptions read watched again"
);
let roots: Vec<(PathBuf, u32)> = h
.owner
.subsumer
.roots()
.map(|(k, handle)| (PathBuf::from_iter(k), handle))
.collect();
assert_eq!(
roots.iter().map(|(p, _)| p.clone()).collect::<Vec<_>>(),
vec![PathBuf::from("/a/b"), PathBuf::from("/a/c")],
"the two subsumed roots are back (re-armed), not collapsed and not gone"
);
for (path, handle) in &roots {
assert!(
h.owner.source.root_key(*handle).is_some(),
"the re-armed root {path:?} is on a LIVE handle — never published-watched-but-disarmed"
);
}
let by_sub: HashMap<Subscription, Epoch> = h
.drain()
.iter()
.map(|ev| {
assert!(ev.is_rescan(), "every restore signal is a Rescan");
(ev.subscription(), ev.epoch())
})
.collect();
assert_eq!(
by_sub.get(&sb).copied(),
Some(Epoch::new(5)),
"sb's restore Rescan strictly dominates its high-water of 4"
);
assert_eq!(
by_sub.get(&sc).copied(),
Some(Epoch::new(3)),
"sc's restore Rescan strictly dominates its high-water of 2"
);
}
#[tokio::test]
async fn widen_arm_failure_retires_root_that_cannot_rearm() {
let mut h = Harness::new();
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.epochs.stamp(sb, Epoch::new(4));
h.owner.epochs.stamp(sc, Epoch::new(2));
h.owner.source.fail_next_arms(2);
let result = h.watch("/a", Interest::all()).await;
assert!(result.is_err(), "the failed wider arm surfaces the error");
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the aborted widen leaks no pending reservation"
);
let view = h.owner.subsumer.view();
assert!(
view.is_watched(&key("/a/c")),
"the re-armable subsumed root is restored and watched"
);
assert!(
!view.is_watched(&key("/a/b")),
"the dead subsumed root is RETIRED — not left published-watched-but-disarmed"
);
let roots: Vec<PathBuf> = h
.owner
.subsumer
.roots()
.map(|(k, _)| PathBuf::from_iter(k))
.collect();
assert_eq!(
roots,
vec![PathBuf::from("/a/c")],
"only the re-armed root remains; the un-re-armable one is gone"
);
assert!(
!h.owner.filters.contains_key(&sb),
"the retired root's subscriber filter is freed (I4)"
);
assert!(
h.owner.filters.contains_key(&sc),
"the restored subscriber's filter is kept"
);
h.owner.flush_pending_rescans();
let by_sub: HashMap<Subscription, Epoch> = h
.drain()
.iter()
.map(|ev| {
assert!(ev.is_rescan(), "every loss/restore signal is a Rescan");
(ev.subscription(), ev.epoch())
})
.collect();
assert_eq!(
by_sub.get(&sb).copied(),
Some(Epoch::new(5)),
"the retired sb's terminal Rescan strictly dominates its high-water of 4"
);
assert_eq!(
by_sub.get(&sc).copied(),
Some(Epoch::new(3)),
"the restored sc's Rescan strictly dominates its high-water of 2"
);
}
#[tokio::test]
#[should_panic(expected = "already observed by this owner")]
#[cfg_attr(
not(debug_assertions),
ignore = "the debug_assert tripwire is compiled out in release builds"
)]
async fn failed_widen_restore_reusing_a_recorded_sibling_handle_trips_the_tripwire() {
let mut h = Harness::new();
let _sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b"); let _sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.source.fail_next_arm();
h.owner.source.reuse_next_arm_handle(2);
let _ = h.watch("/a", Interest::all()).await;
}
#[tokio::test]
#[should_panic(expected = "already observed by this owner")]
#[cfg_attr(
not(debug_assertions),
ignore = "the debug_assert tripwire is compiled out in release builds"
)]
async fn failed_widen_restore_reusing_old_handle_trips_the_tripwire() {
let mut h = Harness::new();
let _sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b"); let _sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.source.fail_next_arm();
h.owner.source.reuse_next_arm_handle(1);
let _ = h.watch("/a", Interest::all()).await;
}
#[tokio::test]
#[should_panic(expected = "already observed by this owner")]
#[cfg_attr(
not(debug_assertions),
ignore = "the debug_assert tripwire is compiled out in release builds"
)]
async fn rearm_reusing_a_retired_handle_trips_the_tripwire() {
let mut h = Harness::new();
let sa = h.watch("/a", Interest::all()).await.expect("watch /a"); h.unwatch(sa).expect("unwatch /a");
h.owner.source.reuse_next_arm_handle(1);
let _ = h.watch("/b", Interest::all()).await;
}
#[tokio::test]
async fn widen_dead_on_arrival_wider_arm_restores_disarmed_roots() {
let mut h = Harness::new();
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.owner.epochs.stamp(sb, Epoch::new(4));
h.owner.epochs.stamp(sc, Epoch::new(2));
h.owner.source.dead_on_arrival_next_arm();
let result = h.watch("/a", Interest::all()).await;
let err = result.expect_err("the dead-on-arrival wider arm fails the widen");
assert!(
err.is_dead_on_arrival(),
"the widen fails with the dead-on-arrival arm error, got {err:?}"
);
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Arm(PathBuf::from("/a/c")),
Call::Disarm(1),
Call::Disarm(2),
Call::Arm(PathBuf::from("/a")),
Call::Disarm(3),
Call::Arm(PathBuf::from("/a/b")),
Call::Arm(PathBuf::from("/a/c")),
],
"the dead-on-arrival wider handle is disarmed, then the subsumed roots restored (not stranded)"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the aborted widen leaks no pending reservation"
);
let view = h.owner.subsumer.view();
assert!(
view.is_watched(&key("/a/b")) && view.is_watched(&key("/a/c")),
"the restored subscriptions read watched again"
);
assert!(
!view.is_watched(&key("/a")),
"the dead-on-arrival wider root was NEVER committed (fail-on-old: /a is watched)"
);
let roots: Vec<(PathBuf, u32)> = h
.owner
.subsumer
.roots()
.map(|(k, handle)| (PathBuf::from_iter(k), handle))
.collect();
assert_eq!(
roots.iter().map(|(p, _)| p.clone()).collect::<Vec<_>>(),
vec![PathBuf::from("/a/b"), PathBuf::from("/a/c")],
"the two subsumed roots are back (re-armed), not collapsed onto the dead wider handle"
);
for (path, handle) in &roots {
assert!(
h.owner.source.root_key(*handle).is_some(),
"the re-armed root {path:?} is on a LIVE handle — never published-watched-but-disarmed"
);
}
let by_sub: HashMap<Subscription, Epoch> = h
.drain()
.iter()
.map(|ev| {
assert!(ev.is_rescan(), "every restore signal is a Rescan");
(ev.subscription(), ev.epoch())
})
.collect();
assert_eq!(
by_sub.get(&sb).copied(),
Some(Epoch::new(5)),
"sb's restore Rescan strictly dominates its high-water of 4"
);
assert_eq!(
by_sub.get(&sc).copied(),
Some(Epoch::new(3)),
"sc's restore Rescan strictly dominates its high-water of 2"
);
}
#[tokio::test]
async fn covered_sub_with_wider_interest_still_delivered() {
let mut h = Harness::new();
let created_only = Interest::none().with_created();
h.watch("/a", created_only).await.expect("watch /a");
let removed_only = Interest::none().with_removed();
let sb = h
.watch("/a/b", removed_only)
.await
.expect("watch /a/b covered");
assert_eq!(
h.owner.source.arm_count(),
1,
"the covered watch issues no second arm"
);
assert_eq!(
h.owner.subsumer.subscription_interest(sb),
Some(removed_only),
"the covered sub's own removed-only interest is its fan-out gate"
);
assert!(
removed_only.admits(&EventKind::<OsString>::Removed),
"a removal under /a/b is admitted by the covered sub's gate — not silently lost"
);
assert!(
!created_only.admits(&EventKind::<OsString>::Removed),
"…and the gate is genuinely narrowing (a created-only gate would drop it)"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn watch_admission_backpressures_when_the_mailbox_is_full() {
struct GatedArmSource {
inner: FakeSource,
gate: async_channel::Receiver<()>,
}
impl Source<OsString> for GatedArmSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
self.inner.canonicalize_key(key)
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
let _ = self.gate.recv().await;
self.inner.arm(key).await
}
fn disarm(&mut self, handle: u32) {
self.inner.disarm(handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
core::future::pending().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.inner.root_key(handle)
}
}
let (gate_tx, gate_rx) = async_channel::unbounded::<()>();
let w: super::Tributaries<OsString, (), TokioRuntime, u32> = super::Tributaries::with_source(
GatedArmSource {
inner: FakeSource::new(),
gate: gate_rx,
},
TributariesOptions::new().with_command_capacity(std::num::NonZeroUsize::new(1).unwrap()),
);
let w1 = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/one"), (), WatchOptions::new()).await })
};
let w2 = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/two"), (), WatchOptions::new()).await })
};
tokio::time::sleep(std::time::Duration::from_millis(200)).await;
let w3 = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/three"), (), WatchOptions::new()).await })
};
tokio::time::sleep(std::time::Duration::from_millis(300)).await;
assert!(
!w3.is_finished(),
"the third watch awaits mailbox ADMISSION while the owner is parked and the \
capacity-1 mailbox is full — it must not resolve, and nothing queues"
);
for _ in 0..3 {
gate_tx.send(()).await.expect("feed the arm gate");
}
for handle in [w1, w2, w3] {
tokio::time::timeout(std::time::Duration::from_secs(20), handle)
.await
.expect("watch resolves once the owner unparks")
.expect("task")
.expect("watch succeeds");
}
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn parts_future_drives_the_watcher_when_caller_spawned() {
struct AliveSource(FakeSource);
impl Source<OsString> for AliveSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
self.0.canonicalize_key(key)
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.0.arm(key).await
}
fn disarm(&mut self, handle: u32) {
self.0.disarm(handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
core::future::pending().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.0.root_key(handle)
}
}
let (w, driver): (super::Tributaries<OsString, (), TokioRuntime, u32>, _) =
super::Tributaries::parts(AliveSource(FakeSource::new()), TributariesOptions::new());
let driver = tokio::spawn(driver);
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch through the caller-spawned driver");
assert!(w.view().is_watched(&key("/a")), "the read plane published");
w.unwatch(sub).await.expect("unwatch");
w.close()
.await
.expect("close resolves — the caller-spawned driver serviced it");
tokio::time::timeout(Duration::from_secs(5), driver)
.await
.expect("the driver future completes after close")
.expect("driver task");
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn dropping_the_parts_future_is_hard_teardown() {
let (mut w, driver): (super::Tributaries<OsString, (), TokioRuntime, u32>, _) =
super::Tributaries::parts(FakeSource::new(), TributariesOptions::new());
drop(driver);
let err = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect_err("watch against a dropped driver surfaces Closed");
assert!(matches!(err, WatchError::Closed), "got {err:?}");
assert!(
!w.view().is_watched(&key("/a")),
"the read plane is empty-and-honest after the hard teardown"
);
assert!(w.next().await.is_none(), "the event stream is ended");
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn dropping_the_parts_future_mid_arm_drops_the_source_for_reclamation() {
struct InstrumentedSource {
inner: FakeSource,
arm_entered: Option<futures_channel::oneshot::Sender<()>>,
gate: async_channel::Receiver<()>,
dropped: std::sync::Arc<std::sync::atomic::AtomicBool>,
}
impl Drop for InstrumentedSource {
fn drop(&mut self) {
self
.dropped
.store(true, std::sync::atomic::Ordering::Release);
}
}
impl Source<OsString> for InstrumentedSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
self.inner.canonicalize_key(key)
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
if let Some(entered) = self.arm_entered.take() {
let _ = entered.send(());
}
let _ = self.gate.recv().await;
self.inner.arm(key).await
}
fn disarm(&mut self, handle: u32) {
self.inner.disarm(handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
core::future::pending().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.inner.root_key(handle)
}
}
let dropped = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let (entered_tx, entered_rx) = futures_channel::oneshot::channel();
let (_gate_tx, gate_rx) = async_channel::unbounded::<()>();
let (w, driver): (super::Tributaries<OsString, (), TokioRuntime, u32>, _) =
super::Tributaries::parts(
InstrumentedSource {
inner: FakeSource::new(),
arm_entered: Some(entered_tx),
gate: gate_rx,
dropped: std::sync::Arc::clone(&dropped),
},
TributariesOptions::new(),
);
let driver = tokio::spawn(driver);
let watching = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/a"), (), WatchOptions::new()).await })
};
entered_rx
.await
.expect("the arm was entered — reconcile in flight");
driver.abort();
let _ = driver.await;
assert!(
dropped.load(std::sync::atomic::Ordering::Acquire),
"the source's Drop ran when the mid-arm driver was cancelled"
);
let err = tokio::time::timeout(Duration::from_secs(5), watching)
.await
.expect("the watch settles")
.expect("task")
.expect_err("a cancelled owner surfaces Closed to the in-flight watch");
assert!(matches!(err, WatchError::Closed), "got {err:?}");
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn dropping_the_parts_future_mid_grow_drops_the_source_for_reclamation() {
struct GrowGatedSource {
inner: FakeSource,
grow_entered: Option<futures_channel::oneshot::Sender<()>>,
gate: async_channel::Receiver<()>,
dropped: std::sync::Arc<std::sync::atomic::AtomicBool>,
}
impl Drop for GrowGatedSource {
fn drop(&mut self) {
self
.dropped
.store(true, std::sync::atomic::Ordering::Release);
}
}
impl Source<OsString> for GrowGatedSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
self.inner.canonicalize_key(key)
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.inner.arm(key).await
}
fn disarm(&mut self, handle: u32) {
self.inner.disarm(handle);
}
fn set_cover(&mut self, handle: u32, retained: &[Vec<OsString>]) {
self.inner.set_cover(handle, retained);
}
async fn grow(&mut self, handle: u32, retained: &[Vec<OsString>]) -> Result<(), WatchError> {
if let Some(entered) = self.grow_entered.take() {
let _ = entered.send(());
}
let _ = self.gate.recv().await;
self.inner.grow(handle, retained).await
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
core::future::pending().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.inner.root_key(handle)
}
}
let dropped = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false));
let (entered_tx, entered_rx) = futures_channel::oneshot::channel();
let (_gate_tx, gate_rx) = async_channel::unbounded::<()>();
let (w, driver): (super::Tributaries<OsString, (), TokioRuntime, u32>, _) =
super::Tributaries::parts(
GrowGatedSource {
inner: FakeSource::new(),
grow_entered: Some(entered_tx),
gate: gate_rx,
dropped: std::sync::Arc::clone(&dropped),
},
TributariesOptions::new(),
);
let driver = tokio::spawn(driver);
let _s_b = w
.watch(key("/a/b"), (), WatchOptions::new())
.await
.expect("watch /a/b");
let s_a = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a widens");
w.unwatch(s_a).await.expect("unwatch the widening /a");
let watching = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/a/c"), (), WatchOptions::new()).await })
};
entered_rx
.await
.expect("the grow was entered — the covered-outside reconcile is parked pre-commit");
driver.abort();
let _ = driver.await;
assert!(
dropped.load(std::sync::atomic::Ordering::Acquire),
"the source's Drop ran when the mid-grow driver was cancelled"
);
let err = tokio::time::timeout(Duration::from_secs(5), watching)
.await
.expect("the watch settles")
.expect("task")
.expect_err("a cancelled owner surfaces Closed to the in-flight watch");
assert!(matches!(err, WatchError::Closed), "got {err:?}");
assert!(
!w.view().is_watched(&key("/a/c")),
"the cancelled covered-outside watch was never published"
);
}
#[tokio::test]
async fn parts_local_drives_a_thread_local_source_end_to_end() {
use std::{
cell::{Cell, RefCell},
rc::Rc,
};
use crate::source::LocalSource;
struct RcSource {
next_handle: Rc<Cell<u32>>,
live: Rc<RefCell<HashMap<u32, Vec<OsString>>>>,
events: async_channel::Receiver<SourceEvent<OsString, u32>>,
}
impl LocalSource<OsString> for RcSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
let handle = self.next_handle.get() + 1;
self.next_handle.set(handle);
self.live.borrow_mut().insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.borrow_mut().remove(&handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
self.events.recv().await.ok()
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.borrow().get(&handle).cloned()
}
}
let (event_tx, event_rx) = async_channel::unbounded();
let source = RcSource {
next_handle: Rc::new(Cell::new(0)),
live: Rc::new(RefCell::new(HashMap::new())),
events: event_rx,
};
let (mut w, driver): (super::Tributaries<OsString, (), TokioRuntime, u32>, _) =
super::Tributaries::parts_local(source, TributariesOptions::new());
let local = tokio::task::LocalSet::new();
local
.run_until(async move {
let driver = tokio::task::spawn_local(driver);
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch through the locally-polled driver");
assert!(w.view().is_watched(&key("/a")), "the read plane published");
event_tx
.send(source_modified(1, "/a/file.txt", 1))
.await
.expect("feed the thread-local source");
let event = tokio::time::timeout(Duration::from_secs(10), w.next())
.await
.expect("delivery is prompt")
.expect("the change is delivered");
assert_eq!(
event.subscription(),
sub,
"attributed to the covering subscription"
);
assert!(event.kind().is_modified(), "the kind survives the fan-out");
w.close().await.expect("close resolves on the local driver");
tokio::time::timeout(Duration::from_secs(5), driver)
.await
.expect("the driver future completes after close")
.expect("driver task");
})
.await;
}
#[tokio::test]
async fn coalescer_overflow_sheds_to_a_dominating_parked_rescan() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200))
.with_max_buffered(2);
let mut h = Harness::with_coalescer(Some(Coalescer::new(Some(cfg))));
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.epochs.stamp(sub, Epoch::new(3));
h.owner.fan_out_and_push(&source_modified(1, "/a/k0", 4));
h.owner.fan_out_and_push(&source_modified(1, "/a/k1", 5));
assert!(
h.owner.needs_rescan.is_empty(),
"under the cap nothing is shed"
);
h.owner.fan_out_and_push(&source_modified(1, "/a/k2", 6));
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the overflowed subscription is owed a dominating parked Rescan"
);
let parked_epoch = h.owner.needs_rescan.get(&sub).expect("parked").epoch;
assert!(
parked_epoch >= Epoch::new(6),
"the shed Rescan dominates the purged buffered epochs (got {parked_epoch:?})"
);
h.owner.flush_pending_rescans();
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == sub && e.kind().is_rescan()),
"the parked Rescan flushes to the consumer"
);
}
#[tokio::test]
async fn per_sub_off_delivers_raw_while_inherit_sibling_settles() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let mut h = Harness::with_coalescer(Some(Coalescer::new(Some(cfg))));
let settled = h.watch("/a", Interest::all()).await.expect("watch /a");
let raw = h
.watch_with("/a", WatchOptions::new().with_debounce(Debounce::Off))
.await
.expect("watch /a raw");
for epoch in 1..=3 {
h.owner.fan_out_and_push(&source_modified(1, "/a/f", epoch));
}
let delivered = h.drain();
let raw_events: Vec<_> = delivered
.iter()
.filter(|e| e.subscription() == raw)
.collect();
assert_eq!(
raw_events.len(),
3,
"the Off subscription sees every raw event, undelayed and uncollapsed"
);
assert!(
raw_events.windows(2).all(|w| w[0].epoch() < w[1].epoch()),
"…in admission (= epoch) order"
);
assert!(
!delivered.iter().any(|e| e.subscription() == settled),
"the inheriting sibling's burst is still settling — nothing delivered yet"
);
h.owner.drain_owed_once();
let tail = h.drain();
assert_eq!(
tail.len(),
1,
"the settled sibling collapsed the burst to one"
);
assert_eq!(tail[0].subscription(), settled);
assert_eq!(
tail[0].epoch(),
Epoch::new(3),
"the newest observation's stamp"
);
}
#[tokio::test]
async fn off_with_global_none_never_instantiates_the_coalescer() {
let mut h = Harness::new();
let sub = h
.watch_with("/a", WatchOptions::new().with_debounce(Debounce::Off))
.await
.expect("watch /a");
assert!(
h.owner.coalescer.is_none(),
"Off atop a disabled global debounce instantiates nothing"
);
h.owner.fan_out_and_push(&source_modified(1, "/a/f", 0));
let delivered = h.drain();
assert_eq!(delivered.len(), 1, "events pass straight through");
assert_eq!(delivered[0].subscription(), sub);
}
#[tokio::test]
async fn custom_with_global_none_lazily_instantiates_the_coalescer() {
let mut h = Harness::new();
assert!(h.owner.coalescer.is_none(), "nothing opted in yet");
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let custom = h
.watch_with(
"/a",
WatchOptions::new().with_debounce(Debounce::Custom(cfg)),
)
.await
.expect("watch /a"); assert!(
h.owner.coalescer.is_some(),
"the first Custom commit lazily instantiated the coalescer"
);
let inherit = h.watch("/b", Interest::all()).await.expect("watch /b");
h.owner.fan_out_and_push(&source_modified(1, "/a/f", 0)); h.owner.fan_out_and_push(&source_modified(2, "/b/g", 0));
let delivered = h.drain();
assert_eq!(
delivered.len(),
1,
"only the inheriting sibling's event passes through"
);
assert_eq!(delivered[0].subscription(), inherit);
assert!(
delivered[0].kind().is_modified(),
"…as the raw delivery itself, not a Rescan"
);
let _ = custom;
assert!(
h.owner
.coalescer
.as_ref()
.and_then(Coalescer::next_deadline)
.is_some(),
"the Custom subscription's delta is held settling"
);
}
#[tokio::test]
async fn widen_repoint_keeps_the_custom_policy_release_forgets_it() {
let mut h = Harness::new();
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let sb = h
.watch_with(
"/a/b",
WatchOptions::new().with_debounce(Debounce::Custom(cfg)),
)
.await
.expect("watch /a/b");
h.owner.fan_out_and_push(&source_modified(1, "/a/b/f", 0));
assert!(h.drain().is_empty(), "the pre-widen delta is settling");
let sa = h.watch("/a", Interest::all()).await.expect("widen to /a"); let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == sb && e.is_rescan()),
"the re-pointed subscription received its dominating widen Rescan"
);
assert!(
!delivered
.iter()
.any(|e| e.subscription() == sb && !e.is_rescan()),
"the purged pre-widen delta never delivers (dominated by the Rescan)"
);
let coalescer = h.owner.coalescer.as_ref().expect("coalescer live");
assert!(
coalescer.has_policy(sb),
"the widen re-point KEPT the Custom policy — the subscription is still live"
);
h.owner.fan_out_and_push(&source_modified(2, "/a/b/g", 0));
let delivered = h.drain();
assert!(
!delivered.iter().any(|e| e.subscription() == sb),
"sb's post-widen delta is buffered under the retained Custom policy, not raw"
);
assert!(
delivered.iter().any(|e| e.subscription() == sa),
"…while the inheriting widener's copy passes through raw (per-sub isolation)"
);
h.owner.park_rescan(sb);
let coalescer = h.owner.coalescer.as_ref().expect("coalescer live");
assert!(
coalescer.has_policy(sb),
"an overflow park purges buffers but keeps the policy"
);
h.unwatch(sb).expect("unwatch");
let coalescer = h.owner.coalescer.as_ref().expect("coalescer live");
assert!(
!coalescer.has_policy(sb),
"release_subscription forgets the retired subscription's policy"
);
}
#[tokio::test]
async fn terminal_retirement_forgets_the_policy() {
let mut h = Harness::new();
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let sub = h
.watch_with(
"/a",
WatchOptions::new().with_debounce(Debounce::Custom(cfg)),
)
.await
.expect("watch /a"); assert!(
h.owner
.coalescer
.as_ref()
.expect("coalescer")
.has_policy(sub),
"the Custom policy is registered at commit"
);
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
assert!(
!h.owner
.coalescer
.as_ref()
.expect("coalescer")
.has_policy(sub),
"terminal retirement forgets the dead subscription's policy"
);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"…while its owed terminal Rescan is still parked (unaffected by the forget)"
);
}
#[tokio::test]
async fn retire_rewatch_cycle_is_bounded_by_the_retired_debt_gate() {
let mut h = Harness::bounded(1);
let plug = h.watch("/plug", Interest::all()).await.expect("watch plug");
h.owner.epochs.stamp(plug, Epoch::new(1));
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
h.owner.flush_pending_rescans();
let mut cycles = 0usize;
loop {
match h.watch(&format!("/cycle{cycles}"), Interest::all()).await {
Ok(_) => {
let handle = u32::try_from(cycles).expect("small") + 2;
h.owner.source.kill_root(handle);
h.owner.retire_root_with_terminal_rescan(handle);
cycles += 1;
assert!(
cycles
<= super::Owner::<OsString, (), TokioRuntime, FakeSource>::RETIRED_RESCAN_DEBT_LIMIT
+ 1,
"the gate must refuse before the debt exceeds its cap"
);
}
Err(WatchError::RescanBacklog) => break,
Err(other) => panic!("unexpected watch error: {other:?}"),
}
}
let retired = h
.owner
.needs_rescan
.keys()
.filter(|&&sub| h.owner.subsumer.subscription_key(sub).is_none())
.count();
assert!(
retired <= super::Owner::<OsString, (), TokioRuntime, FakeSource>::RETIRED_RESCAN_DEBT_LIMIT,
"retired debt is capped (got {retired})"
);
loop {
h.owner.flush_pending_rescans();
if h.drain().is_empty() {
break;
}
}
h.watch("/after-drain", Interest::all())
.await
.expect("admission restored once the retired debt drained");
}
#[tokio::test]
async fn batch_retirement_stands_above_the_threshold_but_cannot_replenish() {
const COHORT: usize = 1200; let mut h = Harness::bounded(1);
for _ in 0..COHORT {
h.watch("/batch", Interest::all())
.await
.expect("cohort watch admitted under a zero retired count");
}
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
let retired = h
.owner
.needs_rescan
.keys()
.filter(|&&sub| h.owner.subsumer.subscription_key(sub).is_none())
.count();
assert_eq!(
retired, COHORT,
"the batch stands above the threshold — bounded by the caller's own peak cohort"
);
let refused = h.watch("/fresh", Interest::all()).await;
assert!(
matches!(refused, Err(WatchError::RescanBacklog)),
"admission refused while retired debt sits at/above the threshold (got {refused:?})"
);
loop {
h.owner.flush_pending_rescans();
if h.drain().is_empty() {
break;
}
}
h.watch("/fresh", Interest::all())
.await
.expect("admission restored once the retired debt drained");
}
#[tokio::test]
async fn flush_pass_work_is_room_proportional_not_map_proportional() {
const COHORT: usize = 64;
let mut h = Harness::bounded(1);
for _ in 0..COHORT {
h.watch("/cohort", Interest::all())
.await
.expect("cohort watch");
}
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
let mut delivered = 0usize;
while delivered < COHORT {
h.owner.flush_pending_rescans();
assert!(
h.owner.last_flush_visited <= 2,
"a capacity-1 pass visits at most the delivered offer plus one probe \
(visited {} with {} entries left)",
h.owner.last_flush_visited,
COHORT - delivered
);
let batch = h.drain();
if batch.is_empty() {
break;
}
delivered += batch.len();
}
assert_eq!(delivered, COHORT, "every owed terminal Rescan drained");
assert!(h.owner.needs_rescan.is_empty(), "no residue");
}
#[tokio::test]
async fn unclaimed_retired_cohort_costs_the_flush_nothing() {
const COHORT: usize = 64;
let mut h = Harness::new();
let mut subs = Vec::new();
for _ in 0..COHORT {
let sub = h.watch("/cohort", Interest::all()).await.expect("watch");
h.owner.unclaimed.insert(sub); subs.push(sub);
}
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
assert!(
h.owner.needs_rescan.is_empty(),
"no offerable debt — the retry timer has nothing to arm for"
);
assert_eq!(
h.owner.suppressed_rescan.len(),
COHORT,
"the whole cohort's terminal debt is suppressed apart"
);
h.owner.flush_pending_rescans();
assert_eq!(
h.owner.last_flush_visited, 0,
"a flush pass over an all-unclaimed cohort visits ZERO candidates"
);
assert!(h.drain().is_empty(), "nothing delivered while unclaimed");
let claimed = subs[COHORT / 2];
h.owner.apply_cleanup(super::Cleanup::Claim(claimed));
assert_eq!(h.owner.needs_rescan.len(), 1, "the claim moved its entry");
h.owner.flush_pending_rescans();
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == claimed && e.is_rescan()),
"the claimed sub's terminal Rescan is delivered — suppression never became loss"
);
assert_eq!(
h.owner.suppressed_rescan.len(),
COHORT - 1,
"the other suppressed entries remain, still costing nothing"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn raced_pre_cut_claim_is_delivered_not_stranded() {
let mut h = Harness::bounded(1);
let plug = h.watch("/plug", Interest::all()).await.expect("watch plug");
h.owner.epochs.stamp(plug, Epoch::new(1));
h.owner.source.kill_root(1);
h.owner.retire_root_with_terminal_rescan(1);
h.owner.flush_pending_rescans();
let racer = h
.watch("/racer", Interest::all())
.await
.expect("watch racer");
h.owner.unclaimed.insert(racer);
h.owner.source.kill_root(2);
h.owner.retire_root_with_terminal_rescan(2);
assert!(h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.contains_key(&racer));
h.owner
.test_pre_cut_claims
.push(super::Cleanup::Claim(racer));
let events = h.events.clone();
let drain = tokio::spawn(async move {
h.owner.drain_owed_before_shutdown().await;
h
});
tokio::time::sleep(Duration::from_millis(300)).await;
assert!(
!drain.is_finished(),
"the drain stays in the retry loop while the raced claim's Rescan cannot be \
delivered — returning here would strand a live Ok subscription"
);
let first = tokio::time::timeout(Duration::from_secs(5), events.recv())
.await
.expect("recv settles")
.expect("plug Rescan");
assert_eq!(first.subscription(), plug);
let second = tokio::time::timeout(Duration::from_secs(10), events.recv())
.await
.expect("recv settles")
.expect("racer Rescan");
assert!(
second.subscription() == racer && second.is_rescan(),
"the raced claim's terminal Rescan IS delivered"
);
let h = tokio::time::timeout(Duration::from_secs(5), drain)
.await
.expect("the drain returns once the raced debt delivered")
.expect("drain task");
assert!(h.owner.needs_rescan.is_empty(), "nothing stranded");
}
#[test]
fn interest_gates_a_whole_moved_by_the_moved_bit() {
let moved = EventKind::Moved {
from: key("/a/src/f"),
};
assert!(
Interest::none().with_moved().admits(&moved),
"a moved-interested gate admits the whole Moved"
);
assert!(
Interest::all().admits(&moved),
"the widest gate admits it too"
);
assert!(
!Interest::none()
.with_created()
.with_removed()
.admits(&moved),
"a gate without the moved bit rejects the whole Moved — it is gated by moved(), \
not by its endpoints' created/removed projections"
);
}
#[tokio::test]
async fn created_only_subscription_receives_created_and_move_in_only() {
let mut h = Harness::new();
let sub = h
.watch("/a", Interest::none().with_created())
.await
.expect("watch /a");
h.owner.fan_out_and_push(&source_created(1, "/a/f", 0));
h.owner.fan_out_and_push(&source_modified(1, "/a/f", 1));
h.owner
.fan_out_and_push(&source_moved(1, "/a/src", "/a/dst", 2));
h.owner
.fan_out_and_push(&source_moved(1, "/outside/g", "/a/arrived", 3));
let delivered = h.drain();
assert_eq!(
delivered.len(),
2,
"exactly the plain Created and the move-in projection are delivered, got {delivered:?}"
);
assert!(delivered.iter().all(|ev| ev.subscription() == sub));
assert!(
delivered[0].kind().is_created() && delivered[0].key() == key("/a/f").as_slice(),
"the plain Created is admitted by the created bit"
);
assert!(
delivered[1].kind().is_created() && delivered[1].key() == key("/a/arrived").as_slice(),
"the move-in projection is a plain Created at the destination — admitted by the \
created bit, not the moved bit"
);
assert!(
delivered[1].move_from().is_none(),
"the projection carries no move source — it is not a whole Moved"
);
}
#[tokio::test]
async fn equal_path_heterogeneous_interest() {
let mut h = Harness::new();
let created_only = Interest::none().with_created();
let removed_only = Interest::none().with_removed();
let s1 = h.watch("/a", created_only).await.expect("watch /a created");
let s2 = h.watch("/a", removed_only).await.expect("watch /a removed");
assert_eq!(
h.owner.source.arm_count(),
1,
"equal paths share one kernel watch"
);
assert_eq!(
h.owner.subsumer.subscription_interest(s1),
Some(created_only)
);
assert_eq!(
h.owner.subsumer.subscription_interest(s2),
Some(removed_only)
);
}
#[tokio::test]
async fn canonical_key_uses_source_key_not_the_planned_one() {
let mut h = Harness::new();
h.owner.source.retarget("/a/link", "/a/real");
let sub = h
.watch("/a/link", Interest::all())
.await
.expect("watch /a/link");
let roots: Vec<PathBuf> = h
.owner
.subsumer
.roots()
.map(|(k, _)| PathBuf::from_iter(k))
.collect();
assert_eq!(
roots,
vec![PathBuf::from("/a/real")],
"the root is keyed on the source's canonical key, not the planned /a/link"
);
assert_eq!(
h.owner.subsumer.subscription_key(sub),
Some(key("/a/real").as_slice()),
"the subscription's coverage key is in the source's coordinate"
);
assert!(
key("/a/real/child").starts_with(h.owner.subsumer.subscription_key(sub).unwrap()),
"a canonical event routes to the creating subscription (no silent drop)"
);
}
#[tokio::test]
async fn canonical_race_that_changes_subsumption_aborts_cleanly() {
let mut h = Harness::new();
h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.source.retarget("/b", "/a/inside");
let err = h
.watch("/b", Interest::all())
.await
.expect_err("a subsumption-changing canonical race aborts");
assert!(
err.is_canonical_race(),
"the abort is the retryable canonical-race error, got {err:?}"
);
let roots: Vec<PathBuf> = h
.owner
.subsumer
.roots()
.map(|(k, _)| PathBuf::from_iter(k))
.collect();
assert_eq!(
roots,
vec![PathBuf::from("/a")],
"no mis-keyed entry lingers"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the aborted plan leaks no pending reservation"
);
assert!(
matches!(h.owner.source.calls().last(), Some(Call::Disarm(_))),
"the just-armed root was disarmed on abort"
);
}
#[tokio::test]
async fn noncanonical_covered_watch_is_canonicalized_then_receives_events() {
let mut h = Harness::new();
let s_root = h
.watch("/root", Interest::all())
.await
.expect("watch /root");
h.owner.source.canonicalizes_to("/root/link", "/root/b");
let s_link = h
.watch("/root/link", Interest::all())
.await
.expect("the covered non-canonical watch is accepted (canonicalized, not rejected)");
assert_eq!(
h.owner.source.arm_count(),
1,
"the covered watch arms nothing (subsumed under /root)"
);
assert_eq!(
h.owner.subsumer.subscription_key(s_link),
Some(key("/root/b").as_slice()),
"the covered subscription is keyed on the source's canonical coordinate, not the raw \
/root/link (fail-on-old: committed verbatim as /root/link)"
);
h.owner
.fan_out_and_push(&source_modified(1, "/root/b/file", 0));
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|ev| ev.subscription() == s_link && !ev.is_rescan()),
"a canonical event under /root/b reaches the covered subscription (fail-on-old: keyed on \
/root/link, the canonical event fails its ancestor match → silently misses)"
);
assert!(
delivered
.iter()
.any(|ev| ev.subscription() == s_root && !ev.is_rescan()),
"…and its covering root's own subscription still receives it too"
);
}
#[tokio::test]
async fn watch_whose_key_cannot_be_canonicalized_is_rejected() {
let mut h = Harness::new();
h.owner.source.cannot_canonicalize("/ghost");
let err = h
.watch("/ghost", Interest::all())
.await
.expect_err("a non-canonicalizable key is rejected, not committed");
assert!(
err.is_canonicalize(),
"the rejection is a Canonicalize error, got {err:?}"
);
assert_eq!(
h.owner.source.arm_count(),
0,
"a rejected watch arms nothing"
);
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"no root is recorded for a rejected watch"
);
assert_eq!(
h.owner.subsumer.pending_len(),
0,
"the rejected watch leaks no pending reservation (canonicalize fails before plan_watch)"
);
assert!(
!h.owner.subsumer.view().is_watched(&key("/ghost")),
"the rejected key is never published watched"
);
}
#[tokio::test]
async fn unwatch_reclaims_epoch_ledger_across_churn() {
let mut h = Harness::new();
for _ in 0..50 {
let a = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
h.owner.epochs.stamp(a, Epoch::new(7));
let wide = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
let _ = h.drain(); assert!(h.unwatch(a).is_ok(), "a was live");
assert!(h.unwatch(wide).is_ok(), "wide was live");
}
assert_eq!(
h.owner.epochs.tracked_len(),
(0, 0),
"unwatch reclaims epoch base + high_water on every outcome (no unbounded leak)"
);
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"all roots released after the churn"
);
}
#[tokio::test]
async fn terminal_rescan_retires_root_overflow_keeps_it() {
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.epochs.stamp(sub, Epoch::new(3));
h.owner.retire_if_dead(&rescan_event(1, "/a", 0));
assert_eq!(
h.owner.subsumer.roots().count(),
1,
"an overflow Rescan on a still-live root keeps it"
);
assert!(
h.owner.filters.contains_key(&sub),
"the live root's subscriber state is untouched"
);
h.owner.source.kill_root(1);
h.owner.retire_if_dead(&rescan_event(1, "/a", 0));
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"a terminal Rescan retires the dead root (I4)"
);
assert!(
!h.owner.filters.contains_key(&sub),
"retirement frees the filter (I4)"
);
assert_eq!(
h.owner.epochs.tracked_len(),
(0, 0),
"retirement frees the epoch state (I4)"
);
}
#[tokio::test]
async fn dead_root_removed_before_terminal_rescan_retires_so_rewatch_rearms() {
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.epochs.stamp(sub, Epoch::new(3));
assert_eq!(
h.owner.source.arm_count(),
1,
"the initial watch armed once"
);
h.owner.source.kill_root(1);
let retired = h.owner.retire_if_dead(&source_removed(1, "/a", 0));
assert!(
retired,
"a dead root retires on the non-`Rescan` terminal event too (run loop skips its own fan-out)"
);
assert!(
h.drain().is_empty(),
"no ordinary terminal event is fanned out — the parked Rescan carries the coverage loss"
);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the retired subscription is owed a dominating terminal Rescan (no silent loss)"
);
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"the dead root is retired on the `Removed`, not left recorded until the `Rescan`"
);
let resub = h.watch("/a", Interest::all()).await.expect("re-watch /a");
assert_ne!(resub, sub, "the re-watch mints a fresh subscription");
assert_eq!(
h.owner.source.arm_count(),
2,
"the re-watch triggers a FRESH arm — NOT `Covered` by the dead root (fail-on-old: stays 1)"
);
h.owner.fan_out_and_push(&source_modified(2, "/a/f", 0));
let delivered = h.drain();
assert_eq!(
delivered.len(),
1,
"a change under the recreated root is delivered to the re-watch (not silently missed)"
);
assert_eq!(
delivered[0].subscription(),
resub,
"…to the fresh subscription riding the live re-armed handle"
);
}
#[tokio::test]
async fn covered_rewatch_validates_liveness_retires_dead_root_and_rearms() {
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.epochs.stamp(sub, Epoch::new(3));
assert_eq!(
h.owner.source.arm_count(),
1,
"the initial watch armed once"
);
h.owner.source.kill_root(1);
assert_eq!(
h.owner.subsumer.roots().count(),
1,
"the dead root is still RECORDED (its terminal event has not yet retired it)"
);
let resub = h
.watch("/a/b", Interest::all())
.await
.expect("re-watch /a/b");
assert_ne!(resub, sub, "the re-watch mints a fresh subscription");
assert_eq!(
h.owner.source.arm_count(),
2,
"the re-watch validates liveness, retires the dead root, and arms a FRESH live root \
(fail-on-old: binds `Covered` to the dead handle → stays 1)"
);
let roots: Vec<Vec<OsString>> = h.owner.subsumer.roots().map(|(k, _)| k.to_vec()).collect();
assert_eq!(
roots,
vec![key("/a/b")],
"the dead /a root is retired and replaced by the fresh /a/b root (fail-on-old: /a survives)"
);
assert!(
!h.owner.filters.contains_key(&sub),
"the dead root's subscriber state is freed on retirement (I4)"
);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"…and it is owed a dominating terminal Rescan (no silent loss)"
);
h.owner.fan_out_and_push(&source_modified(2, "/a/b/f", 0));
let delivered = h.drain();
assert_eq!(
delivered.len(),
1,
"a change under the recreated root reaches the re-watch (fail-on-old: bound to the dead handle → 0)"
);
assert_eq!(
delivered[0].subscription(),
resub,
"…to the fresh subscription riding the live re-armed handle"
);
}
#[tokio::test]
async fn dead_root_terminal_removed_under_debounce_signals_via_parked_rescan_only() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_millis(0))
.with_max_hold(Duration::from_millis(0));
let mut h = Harness::with_coalescer(Some(Coalescer::new(Some(cfg))));
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.epochs.stamp(sub, Epoch::new(3));
h.owner.source.kill_root(1);
let retired = h.owner.retire_if_dead(&source_removed(1, "/a", 0));
assert!(retired, "the dead root retires on the terminal `Removed`");
assert!(
h.drain().is_empty(),
"the dead-root terminal event is NOT fanned through the coalescer (fail-on-old: a redundant \
`Removed` drains)"
);
assert!(
h.owner
.coalescer
.as_ref()
.and_then(Coalescer::next_deadline)
.is_none(),
"no coalescer entry dangles for the retired subscription"
);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the coverage loss is owed as a parked dominating terminal Rescan"
);
h.owner.flush_pending_rescans();
let delivered = h.drain();
assert_eq!(
delivered.len(),
1,
"exactly the terminal Rescan reaches the consumer"
);
assert!(
delivered[0].is_rescan(),
"…and it is the coverage-loss Rescan"
);
assert_eq!(
delivered[0].subscription(),
sub,
"…for the subscription whose root died"
);
assert_eq!(
delivered[0].path(),
Path::new("/a"),
"…naming its covered key, which the consumer re-enumerates to discover the root is gone"
);
}
#[tokio::test]
async fn caller_vanished_after_commit_releases_the_orphan_synchronously() {
let mut h = Harness::new();
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
h.owner
.on_watch(key("/a"), (), WatchOptions::new(), reply)
.await;
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"the orphaned subscription's owner-local state was purged"
);
assert!(h.owner.filters.is_empty(), "its filter state was reclaimed");
assert_eq!(
h.owner.source.arm_count(),
1,
"the watch armed once (it committed) before being orphaned"
);
assert!(
h.owner.source.calls().contains(&Call::Disarm(1)),
"the committed root's last-subscriber disarm was requested synchronously at cleanup"
);
assert_eq!(
h.owner.source.root_key(1),
None,
"the released handle is logically dead immediately"
);
}
#[tokio::test]
async fn watch_wait_dropped_after_commit_reconciles_the_orphan_away() {
let mut h = Harness::new();
let (reply, response) = futures_channel::oneshot::channel();
h.owner
.on_watch(key("/a"), (), WatchOptions::new(), reply)
.await;
assert_eq!(
h.owner.source.arm_count(),
1,
"the watch armed once — it committed before the wait was dropped"
);
assert!(
h.owner.subsumer.view().is_watched(&key("/a")),
"the committed subscription reads watched while the grant is still in flight"
);
drop(response);
let cleanup = h
.owner
.cleanup_rx
.try_recv()
.expect("the dropped grant enqueued a DropOrphan cleanup notice");
assert!(
matches!(cleanup, super::Cleanup::DropOrphan(_)),
"the dropped grant must enqueue exactly a Cleanup::DropOrphan"
);
h.owner.apply_cleanup(cleanup);
assert!(
!h.owner.subsumer.view().is_watched(&key("/a")),
"the orphaned subscription is no longer watched (reconciled away)"
);
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"its subsumer root/record is released"
);
assert!(h.owner.filters.is_empty(), "its filter entry is purged");
assert_eq!(
h.owner.epochs.tracked_len(),
(0, 0),
"its epoch state is purged"
);
assert!(
h.owner.source.calls().contains(&Call::Disarm(1)),
"the committed root's last-subscriber disarm was requested synchronously at cleanup"
);
assert_eq!(
h.owner.source.root_key(1),
None,
"the released handle is logically dead immediately"
);
}
#[tokio::test]
async fn stalled_consumer_parks_dominating_rescan_and_resumes() {
let mut h = Harness::bounded(2);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..3 {
h.owner.epochs.stamp(sub, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
h.owner.try_emit(modified_event(sub, "/a/f2", 2));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(3)),
"overflow parked a Rescan minted one past the high-water (strictly dominating)"
);
h.owner.try_emit(modified_event(sub, "/a/f3", 3));
assert_eq!(
h.owner.needs_rescan.len(),
1,
"repeated overflow collapses to one parked Rescan"
);
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(3)),
"the parked epoch is idempotent under repeated overflow"
);
let buffered = h.drain();
assert_eq!(
buffered.len(),
2,
"the pre-overflow events buffered in-order, not lost"
);
assert!(
buffered.iter().all(|e| !e.is_rescan()),
"the buffered events are the ordinary deliveries"
);
h.owner.flush_pending_rescans();
assert!(
h.owner.needs_rescan.is_empty(),
"the parked Rescan was delivered on resume"
);
let resumed = h.drain();
assert_eq!(
resumed.len(),
1,
"exactly the dominating Rescan is delivered on resume"
);
let rescan = &resumed[0];
assert!(rescan.is_rescan(), "the shed signal is a Rescan");
assert_eq!(rescan.subscription(), sub, "…for the affected subscription");
assert_eq!(
rescan.path(),
Path::new("/a"),
"…naming its covered key to re-enumerate"
);
let max_delivered = buffered
.iter()
.map(Event::epoch)
.max()
.expect("two buffered events");
assert!(
rescan.epoch() > max_delivered,
"the shed Rescan strictly dominates every event delivered before it (no silent loss)"
);
}
#[tokio::test]
async fn parked_rescan_does_not_block_other_subscriptions() {
let mut h = Harness::bounded(1);
let sa = h.watch("/a", Interest::all()).await.expect("watch /a");
let sb = h.watch("/b", Interest::all()).await.expect("watch /b");
h.owner.try_emit(modified_event(sa, "/a/f0", 0));
h.owner.try_emit(modified_event(sa, "/a/f1", 1));
assert!(
h.owner.needs_rescan.contains_key(&sa),
"A overflowed and parked a Rescan"
);
assert!(
!h.owner.needs_rescan.contains_key(&sb),
"B is unaffected by A's overflow"
);
assert_eq!(h.drain().len(), 1, "the pre-overflow A delivery drains");
h.owner.try_emit(modified_event(sb, "/b/f0", 0));
h.owner.try_emit(modified_event(sa, "/a/f2", 2));
let after = h.drain();
assert_eq!(after.len(), 1, "only B's delivery flows; A's is suppressed");
assert_eq!(
after[0].subscription(),
sb,
"the delivered event belongs to the unparked B"
);
assert!(
h.owner.needs_rescan.contains_key(&sa),
"A stays parked until its Rescan is flushed"
);
}
#[tokio::test]
async fn root_death_while_channel_full_keeps_owed_rescan() {
let mut h = Harness::bounded(2);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..3 {
h.owner.epochs.stamp(sub, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
h.owner.source.kill_root(1);
h.owner.fan_out_and_push(&rescan_event(1, "/a", 3));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(3)),
"the overflowed terminal Rescan parked at its own dominating epoch (base + raw = 3)"
);
h.owner.retire_if_dead(&rescan_event(1, "/a", 0));
assert_eq!(
h.owner.subsumer.roots().count(),
0,
"the dead root is retired"
);
assert!(
!h.owner.filters.contains_key(&sub),
"retirement frees the dead root's filter (I4)"
);
assert_eq!(
h.owner.epochs.tracked_len(),
(0, 0),
"retirement frees the dead root's epoch state (I4)"
);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"retirement KEEPS the owed terminal Rescan (no silent loss on root death)"
);
let buffered = h.drain();
assert_eq!(
buffered.len(),
2,
"the pre-death events buffered in-order, not lost"
);
h.owner.flush_pending_rescans();
assert!(
h.owner.needs_rescan.is_empty(),
"the parked terminal Rescan self-drained on resume"
);
let resumed = h.drain();
assert_eq!(
resumed.len(),
1,
"exactly the terminal Rescan is delivered on resume — the consumer is not left stale"
);
let rescan = &resumed[0];
assert!(rescan.is_rescan(), "the coverage-loss signal is a Rescan");
assert_eq!(
rescan.subscription(),
sub,
"…for the subscription whose root died"
);
assert_eq!(
rescan.path(),
Path::new("/a"),
"…naming its covered key, which the consumer re-enumerates to discover the root is gone"
);
let max_delivered = buffered
.iter()
.map(Event::epoch)
.max()
.expect("two buffered events");
assert!(
rescan.epoch() > max_delivered,
"the terminal Rescan strictly dominates every event delivered before it (no silent loss)"
);
}
#[tokio::test]
async fn widen_repoint_rescan_parks_at_own_epoch_not_shed_when_channel_full() {
let mut h = Harness::bounded(2);
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b"); for raw in 0..5 {
h.owner.epochs.stamp(sb, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sb, "/a/b/f0", 0));
h.owner.try_emit(modified_event(sb, "/a/b/f1", 1));
assert!(
h.owner.needs_rescan.is_empty(),
"the fillers took both slots without overflowing yet"
);
h.watch("/a", Interest::all())
.await
.expect("watch /a widens");
assert_eq!(
h.owner.needs_rescan.get(&sb).map(|p| p.epoch),
Some(Epoch::new(5)),
"the re-point Rescan parked at the repoint base (5), not shed_rescan (6)"
);
assert_eq!(h.drain().len(), 2, "the two pre-widen fillers drained");
h.owner.flush_pending_rescans();
assert!(
h.owner.needs_rescan.is_empty(),
"the parked re-point Rescan was delivered on resume"
);
let rescan = h
.drain()
.into_iter()
.find(|e| e.subscription() == sb && e.is_rescan())
.expect("the re-point Rescan was delivered");
assert_eq!(rescan.path(), Path::new("/a"), "it names the widened root");
let rescan_epoch = rescan.epoch();
assert_eq!(
rescan_epoch,
Epoch::new(5),
"the delivered re-point Rescan carries the repoint base (5), not shed_rescan (6)"
);
h.owner.fan_out_and_push(&source_modified(2, "/a/b/g0", 0));
let raw0 = h
.drain()
.into_iter()
.find(|e| e.subscription() == sb)
.expect("sb's new-root raw-0 event was delivered, not suppressed");
h.owner.fan_out_and_push(&source_modified(2, "/a/b/g1", 1));
let raw1 = h
.drain()
.into_iter()
.find(|e| e.subscription() == sb)
.expect("sb's new-root raw-1 event was delivered");
assert_eq!(raw0.epoch(), Epoch::new(5), "raw-0 stamps the repoint base");
assert_eq!(raw1.epoch(), Epoch::new(6), "raw-1 stamps base + 1");
assert!(
raw0.epoch() >= rescan_epoch,
"the new root's raw-0 genuine event is not dominated by the re-point Rescan (no silent loss)"
);
assert!(
raw1.epoch() >= rescan_epoch,
"…and raw-1 is not dominated either"
);
}
#[tokio::test]
async fn widen_drops_buffered_coalescer_delta_so_repoint_rescan_parks_at_own_epoch() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let mut h = Harness::build(Some(Coalescer::new(Some(cfg))), Some(2));
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b"); for raw in 0..5 {
h.owner.epochs.stamp(sb, Epoch::new(raw)); }
h.owner
.push_all(vec![modified_event(sb, "/a/b/buffered", 3)]);
assert!(
h.owner.needs_rescan.is_empty(),
"the buffered delta is held in the coalescer, not overflowed"
);
h.owner.try_emit(modified_event(sb, "/a/b/f0", 0));
h.owner.try_emit(modified_event(sb, "/a/b/f1", 1));
h.watch("/a", Interest::all())
.await
.expect("watch /a widens");
assert_eq!(
h.owner.needs_rescan.get(&sb).map(|p| p.epoch),
Some(Epoch::new(5)),
"the buffered delta was dropped, so the re-point Rescan parked at the repoint base (5), \
not a fresh shed_rescan (6) minted by a buffered delta flushing ahead of it"
);
}
#[tokio::test]
async fn a_source_rescan_while_parked_merges_coverage_instead_of_being_dropped() {
let mut h = Harness::bounded(2);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a"); for raw in 0..3 {
h.owner.epochs.stamp(sub, Epoch::new(raw)); }
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
h.owner.fan_out_and_push(&rescan_event(1, "/a/x", 5));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.key.clone()),
Some(key("/a/x")),
"the first source Rescan parked at its own key /a/x"
);
h.owner.fan_out_and_push(&rescan_event(1, "/a/y", 6));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.key.clone()),
Some(key("/a")),
"the second source Rescan merged into the parked debt, widening the key to the common \
ancestor /a that covers both losses (not dropped, not left at /a/x)"
);
}
#[tokio::test]
async fn source_drain_delivers_owed_parked_rescan_no_silent_loss() {
let mut h = Harness::bounded(1);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..2 {
h.owner.epochs.stamp(sub, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(2)),
"overflow parked a dominating Rescan while the channel is full"
);
let events = h.events.clone();
let owner = &mut h.owner;
let consumer = async {
let buffered = events
.recv()
.await
.expect("the buffered pre-overflow event drains first");
let owed = events
.recv()
.await
.expect("then the owed Rescan is delivered (not dropped)");
(buffered, owed)
};
let (_, (buffered, owed)) = tokio::time::timeout(Duration::from_secs(10), async {
tokio::join!(owner.drain_owed_before_shutdown(), consumer)
})
.await
.expect("source-drain teardown delivered the owed Rescan before the deadline (no silent loss)");
assert!(
!buffered.is_rescan(),
"the first delivered event is the buffered ordinary one, in order"
);
assert!(owed.is_rescan(), "the owed shed signal is a Rescan");
assert_eq!(owed.subscription(), sub, "…for the overflowed subscription");
assert_eq!(
owed.path(),
Path::new("/a"),
"…naming its covered key to re-enumerate"
);
assert!(
owed.epoch() > buffered.epoch(),
"the owed Rescan strictly dominates every event delivered before it (no silent loss)"
);
assert!(
owner.needs_rescan.is_empty(),
"source-drain teardown delivered the owed Rescan — nothing left parked"
);
}
#[tokio::test]
async fn source_next_cancellation_is_lossless_only_when_cancel_safe() {
use futures_util::FutureExt;
struct CancelSafe {
queue: VecDeque<SourceEvent<OsString, u32>>,
consumed: u32,
}
impl Source<OsString> for CancelSafe {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
Ok(Armed::new(1, key.to_vec()))
}
fn disarm(&mut self, _handle: u32) {}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
tokio::task::yield_now().await; self.consumed += 1;
self.queue.pop_front()
}
fn root_key(&self, _handle: u32) -> Option<Vec<OsString>> {
Some(key("/w"))
}
}
struct CancelUnsafe {
queue: VecDeque<SourceEvent<OsString, u32>>,
lost: u32,
}
impl Source<OsString> for CancelUnsafe {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
Ok(Armed::new(1, key.to_vec()))
}
fn disarm(&mut self, _handle: u32) {}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
let popped = self.queue.pop_front(); if popped.is_some() {
self.lost += 1; }
tokio::task::yield_now().await; if popped.is_some() {
self.lost -= 1; }
popped
}
fn root_key(&self, _handle: u32) -> Option<Vec<OsString>> {
Some(key("/w"))
}
}
const N: u64 = 6;
const CANCELS: u32 = 2;
async fn drive<S>(source: &mut S) -> (Vec<SourceEvent<OsString, u32>>, u32)
where
S: Source<OsString, Handle = u32>,
{
let mut delivered = Vec::new();
let mut cancels = 0u32;
loop {
for _ in 0..CANCELS {
futures_util::select_biased! {
ev = source.next().fuse() => if let Some(event) = ev { delivered.push(event); },
_ = std::future::ready(()).fuse() => cancels += 1,
}
}
match source.next().await {
Some(event) => delivered.push(event),
None => break,
}
}
(delivered, cancels)
}
let queued = || -> VecDeque<_> {
(0..N)
.map(|i| source_modified(1, &format!("/w/f{i}"), i))
.collect()
};
let expected: Vec<Vec<OsString>> = (0..N).map(|i| key(&format!("/w/f{i}"))).collect();
let mut safe = CancelSafe {
queue: queued(),
consumed: 0,
};
let (delivered, cancels) = drive(&mut safe).await;
assert!(
cancels > 0,
"the select actually cancelled in-flight next() futures"
);
assert_eq!(
delivered
.iter()
.map(|e| e.key().to_vec())
.collect::<Vec<_>>(),
expected,
"a cancel-safe source delivers every event, in order — no loss across cancellation"
);
let mut bad = CancelUnsafe {
queue: queued(),
lost: 0,
};
let (delivered_bad, _) = drive(&mut bad).await;
assert!(
delivered_bad.len() < usize::try_from(N).unwrap(),
"a cancel-unsafe source loses events to cancellation (delivered {} of {N})",
delivered_bad.len()
);
assert!(
bad.lost > 0,
"the cancel-unsafe source dropped popped-but-unreturned events (silent loss, no Rescan)"
);
}
#[tokio::test]
async fn failed_widen_retire_parks_owed_terminal_rescan_when_channel_full() {
let mut h = Harness::bounded(1);
let sb = h.watch("/a/b", Interest::all()).await.expect("watch /a/b"); let _sc = h.watch("/a/c", Interest::all()).await.expect("watch /a/c"); for raw in 0..3 {
h.owner.epochs.stamp(sb, Epoch::new(raw)); }
h.owner.try_emit(modified_event(sb, "/a/b/f0", 0));
assert!(
h.owner.needs_rescan.is_empty(),
"the pre-widen delivery filled the slot without overflowing yet"
);
h.owner.source.fail_next_arms(2);
let result = h.watch("/a", Interest::all()).await;
assert!(result.is_err(), "the failed wider arm surfaces the error");
assert!(
!h.owner.subsumer.view().is_watched(&key("/a/b")),
"the un-re-armable subsumed root is retired"
);
assert!(
h.owner.needs_rescan.contains_key(&sb),
"the retired root's owed terminal Rescan is parked despite the full channel (not dropped)"
);
let buffered = h.drain();
assert!(
buffered
.iter()
.any(|e| e.subscription() == sb && !e.is_rescan()),
"the pre-widen sb delivery drained in order"
);
let mut resumed = Vec::new();
for _ in 0..2 {
h.owner.flush_pending_rescans();
resumed.extend(h.drain());
}
let sb_rescan = resumed
.iter()
.find(|e| e.subscription() == sb && e.is_rescan())
.expect("sb receives its owed terminal dominating Rescan after resume (no silent loss)");
assert_eq!(
sb_rescan.path(),
Path::new("/a/b"),
"the terminal Rescan names the retired root the consumer re-enumerates"
);
let sb_max = buffered
.iter()
.filter(|e| e.subscription() == sb)
.map(Event::epoch)
.max()
.expect("sb had a buffered delivery");
assert!(
sb_rescan.epoch() > sb_max,
"sb's terminal Rescan strictly dominates every event delivered to it before it"
);
}
#[tokio::test]
async fn source_drain_orders_parked_rescan_before_its_buffered_tail() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let mut h = Harness::build(Some(Coalescer::new(Some(cfg))), Some(1));
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..2 {
h.owner.epochs.stamp(sub, Epoch::new(raw)); }
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(2)),
"overflow parked a dominating Rescan while the channel is full"
);
h.owner.push_all(vec![modified_event(sub, "/a/g0", 9)]);
let events = h.events.clone();
let owner = &mut h.owner;
let consumer = async {
let mut seen: Vec<Event<OsString, ()>> = Vec::new();
while let Ok(event) = events.recv().await {
if event.subscription() == sub {
let is_rescan = event.is_rescan();
seen.push(event);
if is_rescan {
break;
}
}
}
seen
};
let (_, seen) = tokio::time::timeout(Duration::from_secs(10), async {
tokio::join!(owner.drain_owed_before_shutdown(), consumer)
})
.await
.expect("the source-drain teardown delivered the owed Rescan before the deadline");
let rescan_pos = seen
.iter()
.position(|e| e.is_rescan())
.expect("the owed Rescan was delivered");
let rescan_epoch = seen[rescan_pos].epoch();
assert_eq!(rescan_epoch, Epoch::new(2), "the owed dominating Rescan");
for earlier in &seen[..rescan_pos] {
assert!(
earlier.epoch() < rescan_epoch,
"no delta with epoch >= the Rescan's is delivered before it (dominance preserved)"
);
}
assert!(
!seen.iter().any(|e| e.key() == key("/a/g0").as_slice()),
"the parked sub's buffered tail delta was purged (dominated by its Rescan), not delivered"
);
assert!(
owner.needs_rescan.is_empty(),
"the owed Rescan was delivered — nothing left parked"
);
}
#[tokio::test]
async fn source_drain_retry_stays_responsive_to_close() {
let mut h = Harness::bounded(1);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..2 {
h.owner.epochs.stamp(sub, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
assert!(
h.owner.needs_rescan.contains_key(&sub),
"overflow parked a Rescan; the channel is full"
);
let _held = h.events.clone();
let (reply, response) = futures_channel::oneshot::channel();
h.closes
.try_send(reply)
.expect("send the close on the dedicated signal");
let returned = tokio::time::timeout(
Duration::from_secs(10),
h.owner.drain_owed_before_shutdown(),
)
.await
.expect(
"the source-drain retry stayed responsive to Close (did not hang behind the full channel)",
);
let close_reply = returned.expect("the mid-drain Close is surfaced to the caller to be acked");
close_reply.send(Ok(())).expect("ack the Close");
assert!(
matches!(response.await, Ok(Ok(()))),
"close() completes once the drain surfaced and acked its Close"
);
}
#[tokio::test]
async fn source_drain_close_interrupt_still_runs_a_final_owed_pass() {
let mut h = Harness::bounded(1);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
for raw in 0..2 {
h.owner.epochs.stamp(sub, Epoch::new(raw)); }
h.owner.try_emit(modified_event(sub, "/a/f0", 0));
h.owner.try_emit(modified_event(sub, "/a/f1", 1));
assert_eq!(
h.owner.needs_rescan.get(&sub).map(|p| p.epoch),
Some(Epoch::new(2)),
"overflow parked a dominating Rescan while the channel is full"
);
let buffered = h
.events
.try_recv()
.expect("the buffered ordinary event drains, freeing a slot");
assert!(!buffered.is_rescan(), "the freed event is the ordinary one");
let (reply, response) = futures_channel::oneshot::channel();
h.closes
.try_send(reply)
.expect("send the close on the dedicated signal");
let interrupted = h.owner.drain_owed_before_shutdown().await;
let close_reply = interrupted.expect("the queued close interrupted the drain and is surfaced");
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the interrupted drain returned before delivering the owed Rescan (the freed slot is unused)"
);
h.owner.drain_owed_once();
close_reply.send(Ok(())).expect("ack the close");
assert!(
matches!(response.await, Ok(Ok(()))),
"close() completes once the drain surfaced and acked its close"
);
let owed = h
.events
.try_recv()
.expect("the final owed pass delivered the parked Rescan onto the freed slot");
assert!(owed.is_rescan(), "the delivered owed signal is a Rescan");
assert_eq!(owed.subscription(), sub, "…for the overflowed subscription");
assert_eq!(
owed.path(),
Path::new("/a"),
"…naming its covered key to re-enumerate"
);
assert!(
owed.epoch() > buffered.epoch(),
"the owed Rescan strictly dominates the ordinary event delivered before it (no silent loss)"
);
assert!(
h.owner.needs_rescan.is_empty(),
"the final pass delivered the owed Rescan — nothing left parked"
);
}
#[tokio::test]
async fn close_tail_drains_cleanup_not_public_backlog() {
let mut h = Harness::new(); let sub = h.watch("/a", Interest::all()).await.expect("watch /a"); h.owner.unclaimed.insert(sub);
for raw in 0..2 {
h.owner.epochs.stamp(sub, Epoch::new(raw));
}
h.owner.park_rescan(sub);
assert!(
h.owner.suppressed_rescan.contains_key(&sub),
"the unclaimed sub's overflow Rescan is parked into the suppressed partition"
);
const BACKLOG: usize = 2000;
for i in 0..BACKLOG {
let (reply, resp) = futures_channel::oneshot::channel();
drop(resp);
h._commands
.try_send(super::Command::Watch {
key: key(&format!("/flood{i}")),
value: (),
options: WatchOptions::new(),
reply,
})
.expect("prefill a public backlog command");
}
h.owner
.cleanup_tx
.try_send(super::Cleanup::Claim(sub))
.expect("enqueue the claim on the dedicated cleanup channel");
let (reply, response) = futures_channel::oneshot::channel();
h.closes
.try_send(reply)
.expect("send the close on the dedicated signal");
let interrupted =
tokio::time::timeout(Duration::from_secs(5), h.owner.drain_owed_before_shutdown())
.await
.expect("the drain returns promptly (close queued first), not O(public backlog)");
let close_reply = interrupted.expect("the queued close interrupted the drain and is surfaced");
assert!(
h.owner.unclaimed.contains(&sub) && h.owner.suppressed_rescan.contains_key(&sub),
"the drain returned before draining the queued Cleanup::Claim — the debt is still suppressed"
);
assert!(
h.drain().is_empty(),
"…and nothing was delivered yet (a bare final pass here would suppress the unclaimed debt)"
);
h.owner.drain_pending_cleanup();
assert!(
!h.owner.unclaimed.contains(&sub),
"the cleanup drain processed the Claim — suppression lifted"
);
h.owner.drain_owed_once();
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == sub && e.is_rescan()),
"the claimed sub's parked Rescan is delivered by the final pass, before the ack"
);
assert!(
h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.is_empty(),
"the owed debt is resolved, not stranded by stale suppression state"
);
assert_eq!(
h.owner.commands.len(),
BACKLOG,
"the public backlog is never walked by the cleanup drain"
);
close_reply.send(Ok(())).expect("ack the close");
assert!(
matches!(response.await, Ok(Ok(()))),
"close() completes once the interrupted drain acked its close"
);
}
#[tokio::test]
async fn source_drain_dropped_orphan_is_purged_without_blocking_close_on_disarm() {
let mut h = Harness::bounded(1);
let live = h.watch("/a", Interest::all()).await.expect("watch /a");
let orphan = h.watch("/b", Interest::all()).await.expect("watch /b");
for raw in 0..2 {
h.owner.epochs.stamp(live, Epoch::new(raw));
}
h.owner.try_emit(modified_event(live, "/a/f0", 0));
h.owner.try_emit(modified_event(live, "/a/f1", 1));
assert!(
h.owner.needs_rescan.contains_key(&live),
"overflow parked the live sub's Rescan; the channel is full"
);
let _held = h.events.clone();
h.owner
.cleanup_tx
.try_send(super::Cleanup::DropOrphan(orphan))
.expect("enqueue the DropOrphan cleanup notice");
let (reply, response) = futures_channel::oneshot::channel();
let closes = h.closes.clone();
let (returned, ()) = tokio::time::timeout(Duration::from_secs(5), async {
tokio::join!(h.owner.drain_owed_before_shutdown(), async move {
tokio::task::yield_now().await;
closes
.try_send(reply)
.expect("send the close on the dedicated signal");
})
})
.await
.expect("the drain serviced the queued DropOrphan and then surfaced the close");
let close_reply = returned.expect("the mid-drain close is surfaced to the caller to be acked");
close_reply.send(Ok(())).expect("ack the close");
assert!(
matches!(response.await, Ok(Ok(()))),
"close() completes once the drain surfaced and acked its close"
);
assert!(
h.owner.source.calls().contains(&Call::Disarm(2)),
"the teardown released the orphan's last-subscriber root via the synchronous disarm request"
);
assert!(
!h.owner.subsumer.view().is_watched(&key("/b")),
"the orphan is reconciled away (its per-sub state purged)"
);
assert!(
h.owner.needs_rescan.contains_key(&live),
"the live sub's owed parked Rescan survived the orphan purge"
);
}
struct DrainableSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
drain: async_channel::Receiver<std::convert::Infallible>,
}
impl Source<OsString> for DrainableSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
match self.drain.recv().await {
Ok(never) => match never {},
Err(_) => None,
}
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.get(&handle).cloned()
}
}
#[tokio::test]
async fn teardown_publishes_empty_read_plane_so_view_stops_advertising_dead_subs() {
let (drain_tx, drain_rx) = async_channel::bounded::<std::convert::Infallible>(1);
let source = DrainableSource {
next_handle: 0,
live: HashMap::new(),
drain: drain_rx,
};
let mut w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let view = w.view();
let watched = key("/a");
let _sub = w
.watch(watched.clone(), (), WatchOptions::new())
.await
.expect("watch /a");
assert!(view.is_watched(&watched), "the live watch is advertised");
assert!(
view.covering(&watched).is_some(),
"…and attribution resolves it while live"
);
drop(drain_tx);
let ended = tokio::time::timeout(Duration::from_secs(10), w.next()).await;
assert!(
matches!(ended, Ok(None)),
"the event stream ends after the source drains + teardown"
);
assert!(
!view.is_watched(&watched),
"the retained view stops advertising the dead subscription after teardown (empty read plane)"
);
assert!(
view.covering(&watched).is_none(),
"…and attribution resolves to nothing (the owner + source are gone)"
);
}
struct OwnerU64 {
owner: Owner<OsString, u64, TokioRuntime, FakeSource>,
events: async_channel::Receiver<Event<OsString, u64>>,
_commands: async_channel::Sender<super::Command<OsString, u64>>,
_sync_commands: async_channel::Sender<super::SyncRequest>,
_closes: async_channel::Sender<super::CloseReply>,
}
impl OwnerU64 {
fn new(capacity: usize, coalescer: Option<Coalescer<OsString, u64>>) -> Self {
let (event_tx, event_rx) = async_channel::bounded(capacity);
let (command_tx, command_rx) = async_channel::unbounded();
let (sync_command_tx, sync_command_rx) = async_channel::unbounded::<super::SyncRequest>();
let (close_tx, close_rx) = async_channel::bounded(1);
let (cleanup_tx, cleanup_rx) = async_channel::unbounded();
let owner = Owner {
source: FakeSource::new(),
subsumer: Subsumer::new(),
epochs: EpochLedger::new(),
filters: HashMap::new(),
needs_rescan: BTreeMap::new(),
suppressed_rescan: BTreeMap::new(),
unclaimed: std::collections::HashSet::new(),
flush_cursor: None,
#[cfg(test)]
last_flush_visited: 0,
#[cfg(test)]
test_pre_cut_claims: Vec::new(),
debounce: None,
coalescer,
pending_syncs: Vec::new(),
sync_seq: 0,
sync_nonce_seed: std::collections::hash_map::RandomState::new(),
loss_serial: HashMap::new(),
loss_gen: std::sync::Arc::new(core::sync::atomic::AtomicU64::new(0)),
cleanup_tx,
cleanup_rx,
commands: command_rx,
sync_commands: sync_command_rx,
closes: close_rx,
events: event_tx,
#[cfg(debug_assertions)]
observed_handles: std::collections::HashSet::new(),
_rt: PhantomData::<TokioRuntime>,
};
Self {
owner,
events: event_rx,
_commands: command_tx,
_sync_commands: sync_command_tx,
_closes: close_tx,
}
}
fn drain(&self) -> Vec<Event<OsString, u64>> {
let mut out = Vec::new();
while let Ok(event) = self.events.try_recv() {
out.push(event);
}
out
}
}
#[tokio::test]
async fn delivered_delta_carries_owning_subscription_value() {
let mut rig = OwnerU64::new(8, None);
let sub = rig
.owner
.reconcile_watch(&key("/a"), 42, WatchOptions::new())
.await
.expect("watch /a");
rig.owner.fan_out_and_push(&source_modified(1, "/a/f", 0));
let drained = rig.drain();
assert_eq!(drained.len(), 1, "one delivery for the single covering sub");
assert_eq!(
drained[0].subscription(),
sub,
"…retagged with its subscription"
);
assert_eq!(
drained[0].value().copied(),
Some(42),
"a normal delivered delta carries its owning subscription's value (baked at emit time)"
);
}
#[tokio::test]
async fn baked_value_attributes_queued_events_after_teardown_empties_view() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let mut rig = OwnerU64::new(8, Some(Coalescer::new(Some(cfg))));
let a = rig
.owner
.reconcile_watch(&key("/a"), 7, WatchOptions::new())
.await
.expect("watch /a"); let b = rig
.owner
.reconcile_watch(&key("/b"), 9, WatchOptions::new())
.await
.expect("watch /b");
let view = rig.owner.subsumer.view();
assert_eq!(
view.resolve(&key("/b")).map(|s| *s.get()),
Some(9),
"the live view attributes /b while its sub is live"
);
rig.owner.fan_out_and_push(&source_modified(2, "/b/g0", 5));
rig.owner.retire_root_with_terminal_rescan(1);
assert!(
rig.owner.needs_rescan.contains_key(&a),
"subA owes a parked terminal Rescan"
);
assert_eq!(
rig.owner.subsumer.subscription_value(a),
None,
"subA's subsumer state is gone post-retire — its value HAD to be captured at park time"
);
rig.owner.drain_owed_once();
assert_eq!(
view.resolve(&key("/b")).map(|s| *s.get()),
Some(9),
"subB still resolves through the live view just before the empty publish"
);
rig.owner.subsumer.publish_empty();
assert!(
view.resolve(&key("/b")).is_none(),
"teardown emptied the view — resolve now attributes NOTHING for the queued tail delta"
);
assert!(
view.resolve(&key("/a")).is_none(),
"…and nothing for the retired root"
);
let drained = rig.drain();
let rescan = drained
.iter()
.find(|e| e.subscription() == a && e.is_rescan())
.expect("subA's owed terminal Rescan was delivered");
assert_eq!(
rescan.value().copied(),
Some(7),
"the owed terminal Rescan carries subA's value baked at park time — attribution survives \
teardown (the emptied view resolves to None)"
);
let tail = drained
.iter()
.find(|e| e.subscription() == b && !e.is_rescan())
.expect("subB's coalescer tail delta was delivered");
assert_eq!(
tail.value().copied(),
Some(9),
"the coalesced tail delta preserved subB's baked value through buffering"
);
assert!(
drained.iter().all(|e| e.value().is_some()),
"every delivered event carries a baked owning-subscription value (none slips through as None)"
);
}
#[tokio::test]
async fn consumer_unwatch_purges_buffered_coalescer_delta() {
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_secs(3600))
.with_max_hold(Duration::from_secs(7200));
let mut h = Harness::with_coalescer(Some(Coalescer::new(Some(cfg))));
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner.push_all(vec![modified_event(sub, "/a/f", 0)]);
assert!(
h.drain().is_empty(),
"the delta is held under the long quiet window, not yet emitted"
);
h.unwatch(sub).expect("sub was live");
h.owner.drain_coalescer_due();
h.owner.drain_owed_once();
assert!(
h.drain().is_empty(),
"no buffered coalescer event drains for a subscription whose unwatch already resolved"
);
}
#[tokio::test]
async fn owner_drop_publishes_empty_read_plane_on_a_panicking_caller_callback() {
let mut h = Harness::new();
let sub = h
.owner
.reconcile_watch(
&key("/a"),
(),
WatchOptions::new().with_filter(Filter::new(|_| -> bool {
panic!("caller filter predicate panics inside fan-out")
})),
)
.await
.expect("watch /a");
let view = h.owner.subsumer.view();
assert!(
view.is_watched(&key("/a")),
"the live watch is advertised while the sub is live"
);
let panicked = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
h.owner.fan_out_and_push(&source_modified(1, "/a/f", 0));
}));
assert!(
panicked.is_err(),
"the caller filter panicked, unwinding the owner"
);
assert!(
view.is_watched(&key("/a")),
"the caught panic left the owner alive — the plane is unchanged until the owner drops"
);
let _ = sub;
drop(h);
assert!(
!view.is_watched(&key("/a")),
"the Owner Drop guard emptied the read plane on unwind — no stale coverage for a dead owner"
);
assert!(
view.covering(&key("/a")).is_none(),
"…and attribution resolves to nothing after the guard empties the plane"
);
}
#[tokio::test]
async fn drop_orphan_after_terminal_retire_clears_the_orphans_parked_rescan_no_false_debt() {
let mut h = Harness::bounded(1);
let sibling = h.watch("/a", Interest::all()).await.expect("watch /a");
let orphan = h.watch("/b", Interest::all()).await.expect("watch /b");
for raw in 0..2 {
h.owner.epochs.stamp(sibling, Epoch::new(raw));
}
h.owner.try_emit(modified_event(sibling, "/a/f0", 0));
h.owner.try_emit(modified_event(sibling, "/a/f1", 1));
assert!(
h.owner.needs_rescan.contains_key(&sibling),
"the sibling's overflow parked a dominating Rescan"
);
h.owner.retire_root_with_terminal_rescan(2);
assert!(
h.owner.needs_rescan.contains_key(&orphan),
"terminal retirement parked the orphan's owed terminal Rescan"
);
assert!(
!h.owner.subsumer.view().is_watched(&key("/b")),
"the orphan's root is retired from the subsumer"
);
let outcome = h.owner.release_subscription(orphan);
assert!(
outcome.is_err_and(|err| err.is_unknown_subscription()),
"a terminal-retired sub is Unknown to the subsumer"
);
assert!(
!h.owner.needs_rescan.contains_key(&orphan),
"the orphan's parked Rescan was cleared despite the subsumer reporting Unknown (no false debt)"
);
assert!(
h.owner.needs_rescan.contains_key(&sibling),
"the live sibling's owed parked Rescan survived the orphan purge untouched"
);
}
#[tokio::test]
async fn rewatch_of_a_just_orphaned_key_succeeds_no_overlaps() {
let mut h = Harness::new();
let orphan = h.watch("/a", Interest::all()).await.expect("watch /a");
h.owner
.release_subscription(orphan)
.expect("the orphan (its root's last subscriber) is released");
assert_eq!(
h.owner.source.root_key(1),
None,
"the orphaned root is logically dead immediately (its disarm was a synchronous request)"
);
let rewatched = h
.watch("/a", Interest::all())
.await
.expect("the re-watch never surfaces Overlaps (the prior release was already applied)");
assert_ne!(
orphan, rewatched,
"the re-watch minted a fresh subscription"
);
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a")),
Call::Disarm(1),
Call::Arm(PathBuf::from("/a")),
],
"release recorded before the re-watch's (single) arm — no Overlaps"
);
assert_eq!(
h.owner.source.root_key(1),
None,
"the OLD handle stays released — it cannot touch the new root"
);
assert!(
h.owner.subsumer.view().is_watched(&key("/a")),
"the re-watch is live and covered on a fresh root"
);
}
#[tokio::test]
async fn widen_records_releases_before_wider_arm_and_applies_them() {
let mut h = Harness::new();
h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
h.watch("/a/c", Interest::all()).await.expect("watch /a/c");
h.watch("/a", Interest::all())
.await
.expect("watch /a widens over the narrow roots");
assert_eq!(
h.owner.source.calls(),
vec![
Call::Arm(PathBuf::from("/a/b")),
Call::Arm(PathBuf::from("/a/c")),
Call::Disarm(1),
Call::Disarm(2),
Call::Arm(PathBuf::from("/a")),
],
"the narrow roots are released before the wider root is armed"
);
assert_eq!(h.owner.source.root_key(1), None, "narrow /a/b released");
assert_eq!(h.owner.source.root_key(2), None, "narrow /a/c released");
assert_eq!(
h.owner.source.root_key(3),
Some(key("/a")),
"the wider root is armed and live"
);
assert!(
h.owner.subsumer.view().is_watched(&key("/a/b")),
"the widened root covers the old narrow keys"
);
}
#[tokio::test]
async fn release_marks_handle_logically_dead_immediately_even_with_transport_pending() {
struct PendingReleaseSource {
next_handle: u32,
transport_live: std::collections::HashSet<u32>,
pending: VecDeque<u32>,
pending_set: std::collections::HashSet<u32>,
keys: HashMap<u32, Vec<OsString>>,
}
impl Source<OsString> for PendingReleaseSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
while let Some(released) = self.pending.pop_front() {
self.transport_live.remove(&released);
self.pending_set.remove(&released);
self.keys.remove(&released);
}
self.next_handle += 1;
let handle = self.next_handle;
self.transport_live.insert(handle);
self.keys.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
if self.pending_set.insert(handle) {
self.pending.push_back(handle);
}
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
None
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
if self.pending_set.contains(&handle) {
return None;
}
self.keys.get(&handle).cloned()
}
}
let (event_tx, _event_rx) = async_channel::unbounded::<Event<OsString, ()>>();
let (command_tx, command_rx) = async_channel::unbounded::<super::Command<OsString, ()>>();
let (_sync_command_tx, sync_command_rx) = async_channel::unbounded::<super::SyncRequest>();
let (_close_tx, close_rx) = async_channel::bounded::<super::CloseReply>(1);
let (cleanup_tx, cleanup_rx) = async_channel::unbounded::<super::Cleanup>();
let mut owner = Owner {
source: PendingReleaseSource {
next_handle: 0,
transport_live: std::collections::HashSet::new(),
pending: VecDeque::new(),
pending_set: std::collections::HashSet::new(),
keys: HashMap::new(),
},
subsumer: Subsumer::new(),
epochs: EpochLedger::new(),
filters: HashMap::new(),
needs_rescan: BTreeMap::new(),
suppressed_rescan: BTreeMap::new(),
unclaimed: std::collections::HashSet::new(),
flush_cursor: None,
#[cfg(test)]
last_flush_visited: 0,
#[cfg(test)]
test_pre_cut_claims: Vec::new(),
debounce: None,
coalescer: None,
pending_syncs: Vec::new(),
sync_seq: 0,
sync_nonce_seed: std::collections::hash_map::RandomState::new(),
loss_serial: HashMap::new(),
loss_gen: std::sync::Arc::new(core::sync::atomic::AtomicU64::new(0)),
cleanup_tx,
cleanup_rx,
commands: command_rx,
sync_commands: sync_command_rx,
closes: close_rx,
events: event_tx,
#[cfg(debug_assertions)]
observed_handles: std::collections::HashSet::new(),
_rt: PhantomData::<TokioRuntime>,
};
let _commands = command_tx;
let sub = owner
.reconcile_watch(&key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
assert_eq!(
owner.source.root_key(1),
Some(key("/a")),
"the armed root is live before release"
);
owner
.release_subscription(sub)
.expect("the subscription is released");
assert_eq!(
owner.source.root_key(1),
None,
"root_key answers None the instant the release is requested"
);
assert!(
owner.source.transport_live.contains(&1),
"the transport teardown is still pending — an FsSource-shaped deferred release"
);
}
#[tokio::test]
async fn unclaimed_orphans_parked_rescan_is_suppressed_by_state_in_the_run_loop() {
type ReplyRx = futures_channel::oneshot::Receiver<Result<super::WatchGrant, WatchError>>;
struct TerminalRetireSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
trigger: async_channel::Receiver<ReplyRx>,
held_reply: std::sync::Mutex<Option<ReplyRx>>,
delivered_terminal: bool,
}
impl Source<OsString> for TerminalRetireSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
if self.delivered_terminal {
std::future::pending::<Option<SourceEvent<OsString, u32>>>().await
} else {
let reply_rx = match self.trigger.recv().await {
Ok(rx) => rx,
Err(_) => return None,
};
*self.held_reply.lock().unwrap() = Some(reply_rx);
self.live.clear();
self.delivered_terminal = true;
Some(rescan_event(1, "/a", 0))
}
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
match self.live.get(&handle) {
Some(k) => Some(k.clone()),
None => {
drop(self.held_reply.lock().unwrap().take());
None
}
}
}
}
let (event_tx, event_rx) = async_channel::unbounded::<Event<OsString, ()>>();
let (command_tx, command_rx) = async_channel::unbounded::<super::Command<OsString, ()>>();
let (_sync_command_tx, sync_command_rx) = async_channel::unbounded::<super::SyncRequest>();
let (close_tx, close_rx) = async_channel::bounded::<super::CloseReply>(1);
let (cleanup_tx, cleanup_rx) = async_channel::unbounded::<super::Cleanup>();
let (trigger_tx, trigger_rx) = async_channel::unbounded::<ReplyRx>();
let owner = Owner {
source: TerminalRetireSource {
next_handle: 0,
live: HashMap::new(),
trigger: trigger_rx,
held_reply: std::sync::Mutex::new(None),
delivered_terminal: false,
},
subsumer: Subsumer::new(),
epochs: EpochLedger::new(),
filters: HashMap::new(),
needs_rescan: BTreeMap::new(),
suppressed_rescan: BTreeMap::new(),
unclaimed: std::collections::HashSet::new(),
flush_cursor: None,
#[cfg(test)]
last_flush_visited: 0,
#[cfg(test)]
test_pre_cut_claims: Vec::new(),
debounce: None,
coalescer: None,
pending_syncs: Vec::new(),
sync_seq: 0,
sync_nonce_seed: std::collections::hash_map::RandomState::new(),
loss_serial: HashMap::new(),
loss_gen: std::sync::Arc::new(core::sync::atomic::AtomicU64::new(0)),
cleanup_tx,
cleanup_rx,
commands: command_rx,
sync_commands: sync_command_rx,
closes: close_rx,
events: event_tx,
#[cfg(debug_assertions)]
observed_handles: std::collections::HashSet::new(),
_rt: PhantomData::<TokioRuntime>,
};
let run = tokio::spawn(super::run(owner));
let (reply, reply_rx) = futures_channel::oneshot::channel();
command_tx
.try_send(super::Command::Watch {
key: key("/a"),
value: (),
options: WatchOptions::new(),
reply,
})
.expect("enqueue the Watch");
trigger_tx
.try_send(reply_rx)
.expect("hand the reply receiver to the source");
tokio::time::sleep(Duration::from_millis(250)).await;
let (close_reply, close_response) = futures_channel::oneshot::channel();
close_tx
.try_send(close_reply)
.expect("send the close on the dedicated signal");
let acked = tokio::time::timeout(Duration::from_secs(5), close_response)
.await
.expect("close() completes within the deadline")
.expect("the close reply channel stays open");
assert!(matches!(acked, Ok(())), "close() succeeds");
let mut delivered = Vec::new();
while let Ok(event) = event_rx.try_recv() {
delivered.push(event);
}
assert!(
delivered.is_empty(),
"the orphan's parked terminal Rescan was suppressed by state — no event for a subscription the \
caller never obtained (got {} event(s))",
delivered.len()
);
tokio::time::timeout(Duration::from_secs(5), run)
.await
.expect("the run task joins after Close")
.expect("the run task did not panic");
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn unpolled_grant_across_source_drain_teardown_is_poisoned() {
let (drain_tx, drain_rx) = async_channel::bounded::<std::convert::Infallible>(1);
let source = DrainableSource {
next_handle: 0,
live: HashMap::new(),
drain: drain_rx,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let (reply, response) = futures_channel::oneshot::channel();
w.commands
.try_send(super::Command::Watch {
key: key("/a"),
value: (),
options: WatchOptions::new(),
reply,
})
.expect("enqueue the Watch");
tokio::time::sleep(Duration::from_millis(100)).await;
drop(drain_tx);
tokio::time::sleep(Duration::from_millis(200)).await;
let grant = tokio::time::timeout(Duration::from_secs(5), response)
.await
.expect("the reply was sent before teardown")
.expect("the grant sits in the slot")
.expect("the watch committed successfully");
assert!(
grant.defuse().is_err(),
"a grant polled after the owner tore down is POISONED — watch() surfaces Closed, never a dead Ok"
);
}
#[tokio::test]
async fn claim_after_the_source_drain_cut_is_poisoned_even_before_owner_drop() {
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a"); h.owner.unclaimed.insert(sub);
let grant = super::WatchGrant::new(sub, h.owner.cleanup_tx.clone());
h.owner.retire_root_with_terminal_rescan(1);
let returned = tokio::time::timeout(Duration::from_secs(5), h.owner.drain_owed_before_shutdown())
.await
.expect("the drain exits promptly");
assert!(returned.is_none(), "no close interrupted the drain");
assert!(
grant.defuse().is_err(),
"a claim after the source-drain cut is poisoned even while the owner is still alive"
);
assert!(
h.drain().iter().all(|e| e.subscription() != sub),
"the suppressed debt was never delivered for the never-claimed subscription"
);
}
#[tokio::test]
async fn source_drain_suppresses_unclaimed_orphan_debt_and_exits_without_spinning() {
let mut h = Harness::new(); let live = h.watch("/a", Interest::all()).await.expect("watch /a"); let orphan = h.watch("/b", Interest::all()).await.expect("watch /b"); h.owner.unclaimed.insert(orphan);
for raw in 0..2 {
h.owner.epochs.stamp(live, Epoch::new(raw));
}
h.owner.park_rescan(live);
h.owner.retire_root_with_terminal_rescan(2);
assert!(
h.owner.needs_rescan.contains_key(&live) && h.owner.suppressed_rescan.contains_key(&orphan),
"both parked: the live sub's overflow Rescan offerable, the unclaimed orphan's terminal \
Rescan in the suppressed partition"
);
let returned = tokio::time::timeout(Duration::from_secs(5), h.owner.drain_owed_before_shutdown())
.await
.expect("the drain exits promptly instead of spinning on unclaimed-only debt");
assert!(returned.is_none(), "no Close interrupted the drain");
let delivered = h.drain();
assert!(
!delivered.iter().any(|e| e.subscription() == orphan),
"the unclaimed orphan's parked terminal Rescan is suppressed by state — never delivered"
);
assert!(
delivered
.iter()
.any(|e| e.subscription() == live && e.is_rescan()),
"the claimed live sub's owed Rescan IS delivered (no-silent-loss for claimed subs)"
);
assert!(
h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.contains_key(&orphan),
"only suppressed (owed-to-nobody) debt remains at exit — the offerable map drained"
);
}
#[tokio::test]
async fn final_drain_suppresses_unclaimed_orphan_debt_after_close() {
let mut h = Harness::new(); let live = h.watch("/a", Interest::all()).await.expect("watch /a"); let orphan = h.watch("/b", Interest::all()).await.expect("watch /b"); h.owner.unclaimed.insert(orphan);
for raw in 0..2 {
h.owner.epochs.stamp(live, Epoch::new(raw));
}
h.owner.park_rescan(live);
h.owner.retire_root_with_terminal_rescan(2);
assert!(
h.owner.needs_rescan.contains_key(&live) && h.owner.suppressed_rescan.contains_key(&orphan),
"both parked: the live sub's overflow Rescan offerable, the unclaimed orphan's terminal \
Rescan in the suppressed partition"
);
h.owner
.cleanup_tx
.try_send(super::Cleanup::DropOrphan(orphan))
.expect("enqueue the residual DropOrphan cleanup notice");
h.owner.drain_owed_once();
let delivered = h.drain();
assert!(
!delivered.iter().any(|e| e.subscription() == orphan),
"the unclaimed orphan's parked Rescan is suppressed by state in the final pass"
);
assert!(
delivered
.iter()
.any(|e| e.subscription() == live && e.is_rescan()),
"the claimed live sub's owed Rescan IS delivered by the best-effort pass"
);
}
#[tokio::test]
async fn claimed_grant_lifts_suppression_and_its_parked_rescan_is_delivered() {
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a"); h.owner.unclaimed.insert(sub);
h.owner.retire_root_with_terminal_rescan(1);
assert!(
h.owner.suppressed_rescan.contains_key(&sub),
"the terminal Rescan is parked, suppressed"
);
h.owner.flush_pending_rescans();
assert!(
h.drain().is_empty(),
"unclaimed: the parked Rescan is suppressed, not offered"
);
assert_eq!(
h.owner.last_flush_visited, 0,
"…at zero flush cost — suppressed debt lives outside the offerable map"
);
assert!(
h.owner.suppressed_rescan.contains_key(&sub),
"…and retained (deferred), not dropped"
);
h.owner.apply_cleanup(super::Cleanup::Claim(sub));
h.owner.flush_pending_rescans();
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == sub && e.is_rescan()),
"claimed: the parked terminal Rescan is delivered — suppression never became loss"
);
assert!(
h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.is_empty(),
"the owed debt is resolved once claimed"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn parked_rescan_delivers_under_sustained_command_load() {
let (_drain_tx, drain_rx) = async_channel::bounded::<std::convert::Infallible>(1);
let source = DrainableSource {
next_handle: 0,
live: HashMap::new(),
drain: drain_rx,
};
let mut w: super::Tributaries<OsString, (), TokioRuntime, u32> = super::Tributaries::with_source(
source,
TributariesOptions::new().with_event_capacity(std::num::NonZeroUsize::new(1).expect("nonzero")),
);
let narrow_b = w
.watch(key("/a/b"), (), WatchOptions::new())
.await
.expect("watch /a/b");
let narrow_c = w
.watch(key("/a/c"), (), WatchOptions::new())
.await
.expect("watch /a/c");
let _wide = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("widen to /a");
let flood_commands = w.commands.clone();
let flood = tokio::spawn(async move {
loop {
for _ in 0..8 {
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
if flood_commands
.try_send(super::Command::Watch {
key: key("/flood"),
value: (),
options: WatchOptions::new(),
reply,
})
.is_err()
{
return;
}
}
tokio::task::yield_now().await;
}
});
let mut seen = std::collections::HashSet::new();
for _ in 0..2 {
let event = tokio::time::timeout(Duration::from_secs(5), w.next())
.await
.expect("a re-point Rescan is delivered within the deadline despite sustained command load")
.expect("the stream is open");
assert!(event.is_rescan(), "the widen minted re-point Rescans");
seen.insert(event.subscription());
}
assert!(
seen.contains(&narrow_b) && seen.contains(&narrow_c),
"both re-pointed subscriptions received their Rescan — the parked one was never starved"
);
flood.abort();
}
fn spawn_command_flood(
commands: async_channel::Sender<super::Command<OsString, ()>>,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
loop {
for _ in 0..8 {
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
if commands
.try_send(super::Command::Watch {
key: key("/flood"),
value: (),
options: WatchOptions::new(),
reply,
})
.is_err()
{
return;
}
}
tokio::task::yield_now().await;
}
})
}
struct TriggeredSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
events: std::collections::VecDeque<SourceEvent<OsString, u32>>,
trigger: async_channel::Receiver<()>,
grows: std::sync::Arc<std::sync::atomic::AtomicU32>,
}
impl Source<OsString> for TriggeredSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
async fn grow(&mut self, _handle: u32, _retained: &[Vec<OsString>]) -> Result<(), WatchError> {
self.grows.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
Ok(())
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
match self.trigger.recv().await {
Ok(()) => self.events.pop_front(),
Err(_) => None,
}
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.get(&handle).cloned()
}
}
#[tokio::test]
async fn queued_claim_grant_is_serviced_before_the_source_drain_exit() {
let mut h = Harness::new(); let sub = h.watch("/a", Interest::all()).await.expect("watch /a"); h.owner.unclaimed.insert(sub);
h.owner.retire_root_with_terminal_rescan(1);
assert!(
h.owner.suppressed_rescan.contains_key(&sub),
"the terminal Rescan is parked, suppressed"
);
h.owner
.cleanup_tx
.try_send(super::Cleanup::Claim(sub))
.expect("enqueue the Claim on the cleanup channel");
let returned = tokio::time::timeout(Duration::from_secs(5), h.owner.drain_owed_before_shutdown())
.await
.expect("the drain exits promptly after delivering the claimed debt");
assert!(returned.is_none(), "no Close interrupted the drain");
let delivered = h.drain();
assert!(
delivered
.iter()
.any(|e| e.subscription() == sub && e.is_rescan()),
"the claimed sub's parked Rescan is delivered before the source-drain exit"
);
assert!(
h.owner.needs_rescan.is_empty() && h.owner.suppressed_rescan.is_empty(),
"the owed debt is resolved, not stranded"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn raw_source_event_delivers_under_sustained_command_load() {
let (trigger_tx, trigger_rx) = async_channel::unbounded::<()>();
let source = TriggeredSource {
next_handle: 0,
live: HashMap::new(),
events: std::collections::VecDeque::from([SourceEvent::new(
1,
key("/a/f"),
EventKind::Created,
Location::new(),
Epoch::new(0),
Some(ChangeId::new(NonZeroU64::MIN)),
)]),
trigger: trigger_rx,
grows: std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0)),
};
let mut w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let flood = spawn_command_flood(w.commands.clone());
trigger_tx.try_send(()).expect("release the queued event");
let event = tokio::time::timeout(Duration::from_secs(5), w.next())
.await
.expect("the raw source event is delivered despite the sustained command flood (the valve)")
.expect("the stream is open");
assert_eq!(event.subscription(), sub, "routed to the covering sub");
flood.abort();
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn valve_pumped_rescan_still_degrades_the_retained_cover() {
let (trigger_tx, trigger_rx) = async_channel::unbounded::<()>();
let grows = std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0));
let source = TriggeredSource {
next_handle: 0,
live: HashMap::new(),
events: std::collections::VecDeque::from([SourceEvent::new(
2,
key("/a"),
EventKind::Rescan,
Location::new(),
Epoch::new(1),
None,
)]),
trigger: trigger_rx,
grows: grows.clone(),
};
let mut w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let s_b = w
.watch(key("/a/b"), (), WatchOptions::new())
.await
.expect("watch /a/b");
let s_a = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a widens");
w.unwatch(s_a).await.expect("unwatch the widening /a");
let repoint = tokio::time::timeout(Duration::from_secs(5), w.next())
.await
.expect("the re-point Rescan arrives")
.expect("stream open");
assert!(repoint.is_rescan() && repoint.subscription() == s_b);
let flood = spawn_command_flood(w.commands.clone());
trigger_tx.try_send(()).expect("release the queued Rescan");
let event = tokio::time::timeout(Duration::from_secs(5), w.next())
.await
.expect("the loss Rescan is delivered through the valve despite the flood")
.expect("stream open");
assert!(
event.is_rescan() && event.subscription() == s_b,
"the coverage-loss Rescan fanned to the covering sub"
);
flood.abort();
assert_eq!(grows.load(std::sync::atomic::Ordering::SeqCst), 0);
let _s2 = w
.watch(key("/a/b/x"), (), WatchOptions::new())
.await
.expect("the post-loss newcomer commits through a re-proving grow");
assert_eq!(
grows.load(std::sync::atomic::Ordering::SeqCst),
1,
"the newcomer classified covered-OUTSIDE against the degraded record and grew"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn source_drain_delivers_claimed_debt_under_sustained_command_flood() {
let mut h = Harness::new(); let live = h.watch("/a", Interest::all()).await.expect("watch /a"); for raw in 0..2 {
h.owner.epochs.stamp(live, Epoch::new(raw));
}
h.owner.park_rescan(live);
let flood = spawn_command_flood(h._commands.clone());
let _ = tokio::time::timeout(Duration::from_secs(2), h.owner.drain_owed_before_shutdown()).await;
flood.abort();
assert!(
h.drain()
.iter()
.any(|e| e.subscription() == live && e.is_rescan()),
"the claimed sub's parked Rescan is delivered despite the sustained command flood"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn due_debounced_event_drains_under_sustained_command_load() {
let (trigger_tx, trigger_rx) = async_channel::unbounded::<()>();
let source = TriggeredSource {
next_handle: 0,
live: HashMap::new(),
events: std::collections::VecDeque::from([SourceEvent::new(
1,
key("/a/f"),
EventKind::Modified,
Location::new(),
Epoch::new(0),
Some(ChangeId::new(NonZeroU64::MIN)),
)]),
trigger: trigger_rx,
grows: std::sync::Arc::new(std::sync::atomic::AtomicU32::new(0)),
};
let cfg = DebounceConfig::new()
.with_quiet_window(Duration::from_millis(20))
.with_max_hold(Duration::from_millis(100));
let mut w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new().debounce(cfg));
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let flood = spawn_command_flood(w.commands.clone());
trigger_tx.try_send(()).expect("release the queued event");
let event = tokio::time::timeout(Duration::from_secs(5), w.next())
.await
.expect("the due debounced event drains despite the flood (the valve's due-coalescer drain)")
.expect("the stream is open");
assert_eq!(event.subscription(), sub, "routed to the covering sub");
flood.abort();
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn close_is_not_starved_by_a_prefilled_command_backlog_and_flood() {
let (_drain_tx, drain_rx) = async_channel::bounded::<std::convert::Infallible>(1);
let source = DrainableSource {
next_handle: 0,
live: HashMap::new(),
drain: drain_rx, };
let w: super::Tributaries<OsString, (), TokioRuntime, u32> = super::Tributaries::with_source(
source,
TributariesOptions::new().with_command_capacity(std::num::NonZeroUsize::new(500).unwrap()),
);
w.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
for _ in 0..500 {
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
w.commands
.try_send(super::Command::Watch {
key: key("/backlog"),
value: (),
options: WatchOptions::new(),
reply,
})
.expect("prefill the command backlog");
}
let flood = spawn_command_flood(w.commands.clone());
let closed = tokio::time::timeout(Duration::from_secs(5), w.close())
.await
.expect("close() completes within the deadline despite the command backlog + flood");
assert!(matches!(closed, Ok(())), "close() succeeds");
flood.abort();
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn source_drain_close_is_surfaced_under_sustained_command_flood() {
let mut h = Harness::bounded(1);
let live = h.watch("/a", Interest::all()).await.expect("watch /a"); for raw in 0..2 {
h.owner.epochs.stamp(live, Epoch::new(raw));
}
h.owner.try_emit(modified_event(live, "/a/f0", 0));
h.owner.try_emit(modified_event(live, "/a/f1", 1));
assert!(
h.owner.needs_rescan.contains_key(&live),
"overflow parked the claimed sub's Rescan; the channel is full"
);
let _held = h.events.clone();
let flood = spawn_command_flood(h._commands.clone());
let (reply, response) = futures_channel::oneshot::channel();
h.closes
.try_send(reply)
.expect("send the close on the dedicated signal");
let returned = tokio::time::timeout(Duration::from_secs(5), h.owner.drain_owed_before_shutdown())
.await
.expect("the source-drain teardown surfaced the close despite the sustained command flood");
let close_reply = returned.expect("the mid-drain close is surfaced to the caller to be acked");
close_reply.send(Ok(())).expect("ack the close");
assert!(
matches!(response.await, Ok(Ok(()))),
"close() completes once the drain surfaced and acked its close, under the flood"
);
flood.abort();
}
#[tokio::test]
async fn a_rescan_dominates_a_pending_sync_and_the_rescan_is_published() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/cookie-1"),
sub,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner.consume_source_event(&rescan_event(handle, "/a", 5));
let events = h.drain();
assert!(
events.iter().any(|e| e.kind().is_rescan()),
"the covering Rescan is on the stream: {events:?}"
);
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"the barrier resolved Dominated, not Delivered"
);
}
#[tokio::test]
async fn a_cookie_delivered_over_existing_rescan_debt_resolves_dominated() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::bounded(1);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
h.owner.try_emit(modified_event(sub, "/a/x", 1));
h.owner.consume_source_event(&rescan_event(handle, "/a", 2));
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the sub carries parked Rescan debt"
);
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/cookie-1"),
sub,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 3));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a cookie delivered over Rescan debt is Dominated"
);
}
#[tokio::test]
async fn a_covering_rescan_dominates_a_modified_only_sync_a_removed_cannot() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
let sub = h
.watch("/a", Interest::none().with_modified())
.await
.expect("watch /a modified-only");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/cookie-1"),
sub,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner
.consume_source_event(&source_removed(handle, "/a/child", 5));
assert!(
h.drain().iter().all(|e| !e.kind().is_removed()),
"the Removed is filtered from the Modified-only sub"
);
assert!(
(&mut reply_rx).now_or_never().is_none(),
"a Removed the sub never sees does not resolve the barrier"
);
h.owner.consume_source_event(&rescan_event(handle, "/a", 6));
assert!(
h.drain().iter().any(|e| e.kind().is_rescan()),
"the covering Rescan reaches the Modified-only sub"
);
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"the barrier resolved Dominated via the covering Rescan, not a false Delivered"
);
}
#[tokio::test]
async fn an_unwatched_subscription_reaps_its_pending_cookie() {
use futures_util::FutureExt;
use crate::error::SyncError;
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/cookie-1"),
sub,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner.release_subscription(sub).expect("unwatch");
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Err(SyncError::Retired)))
),
"the caller-unwatched barrier fails Retired"
);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/cookie-1")],
"the cookie is reaped, not leaked"
);
}
#[tokio::test]
async fn a_diverging_in_place_widen_rolls_back_and_keeps_old_coverage() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
h.owner.source.supports_replace = true;
let s_narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let handle = h
.owner
.subsumer
.subscription_root(s_narrow)
.expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/b/cookie-1"),
sub: s_narrow,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner
.source
.retarget
.insert(PathBuf::from("/a"), PathBuf::from("/z"));
let err = h
.watch("/a", Interest::all())
.await
.expect_err("the diverging widen is refused");
assert!(matches!(err, WatchError::CanonicalRace), "{err:?}");
assert!(
!h.owner
.source
.calls()
.iter()
.any(|c| matches!(c, Call::Disarm(_))),
"the preserved handle must not be disarmed while old subscribers remain: {:?}",
h.owner.source.calls()
);
let roots: Vec<PathBuf> = h
.owner
.subsumer
.roots()
.map(|(k, _)| PathBuf::from_iter(k))
.collect();
assert_eq!(
roots,
vec![PathBuf::from("/a/b")],
"the sole root is rolled back to its original coverage"
);
assert!(
h.owner.subsumer.subscription_root(s_narrow).is_some(),
"the old subscription is still live on the restored root"
);
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"the sole root's pending sync resolves Dominated after the exact rollback"
);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/b/cookie-1")],
"the dominated barrier's cookie is reaped"
);
assert!(
h.owner.needs_rescan.contains_key(&s_narrow),
"s_narrow owes a dominating Rescan for the silently-missed retarget window"
);
h.owner.flush_pending_rescans();
let events = h.drain();
assert!(
events
.iter()
.any(|e| e.subscription() == s_narrow && e.kind().is_rescan()),
"s_narrow receives the dominating Rescan: {events:?}"
);
}
#[tokio::test]
async fn a_loss_published_before_the_cookie_still_resolves_dominated() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::bounded(4);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/cookie-1"),
sub,
root: handle,
loss_serial_at_install: h.owner.loss_serial.get(&sub).copied().unwrap_or(0),
dominated_at_install: false,
reply: reply_tx,
});
for i in 0..4 {
h.owner.try_emit(modified_event(sub, "/a/fill", i));
}
h.owner.try_emit(modified_event(sub, "/a/lost", 9)); assert!(h.owner.needs_rescan.contains_key(&sub));
let _ = h.drain(); h.owner.flush_pending_rescans(); assert!(
!h.owner.needs_rescan.contains_key(&sub),
"the parked Rescan was published and cleared"
);
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 20));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a loss published before the cookie must still yield Dominated"
);
}
#[tokio::test]
async fn a_widen_resolves_the_repointed_subscriptions_pending_sync() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
let s_narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let handle = h.owner.subsumer.subscription_root(s_narrow).expect("live");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/a/b/cookie-1"),
sub: s_narrow,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
let _wide = h
.watch("/a", Interest::all())
.await
.expect("watch /a widens");
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"the re-pointed subscription's barrier resolves Dominated at the widen"
);
}
#[tokio::test]
async fn a_barrier_installed_over_existing_debt_resolves_dominated() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
h.owner.source.supports_sync = true;
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
h.owner.park_rescan(sub);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the sub owes a parked Rescan before the barrier is installed"
);
let loss_gen_at_call = h.owner.loss_gen.load(core::sync::atomic::Ordering::SeqCst);
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.on_sync(sub, loss_gen_at_call, reply_tx).await;
assert!(
!h.owner.source.ended_syncs.contains(&key("/a/cookie-1")),
"the cookie is still pending — not yet reaped"
);
h.owner.flush_pending_rescans();
assert!(
!h.owner.needs_rescan.contains_key(&sub),
"the pre-install Rescan published and cleared"
);
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 20));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a barrier installed over pre-existing debt resolves Dominated, not a false Delivered"
);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/cookie-1")],
"the resolved barrier's cookie is reaped"
);
}
#[tokio::test]
async fn a_completed_cookie_for_a_gone_caller_is_reaped_not_installed() {
use crate::{error::SyncError, source::SyncOutcome};
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, reply_rx) = futures_channel::oneshot::channel::<Result<SyncOutcome, SyncError>>();
drop(reply_rx);
let loss_gen_at_call = h.owner.loss_gen.load(core::sync::atomic::Ordering::SeqCst);
h.owner
.admit_begun_cookie(key("/a/cookie-1"), sub, handle, loss_gen_at_call, reply_tx);
assert!(
h.owner.pending_syncs.is_empty(),
"a completed cookie for a gone caller parks no barrier"
);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/cookie-1")],
"the completed cookie is reaped inline, never orphaned"
);
}
#[tokio::test]
async fn a_completed_cookie_for_a_live_caller_is_parked_not_reaped() {
use crate::{error::SyncError, source::SyncOutcome};
let mut h = Harness::new();
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, _reply_rx) = futures_channel::oneshot::channel::<Result<SyncOutcome, SyncError>>();
let loss_gen_at_call = h.owner.loss_gen.load(core::sync::atomic::Ordering::SeqCst);
h.owner
.admit_begun_cookie(key("/a/cookie-1"), sub, handle, loss_gen_at_call, reply_tx);
assert_eq!(
h.owner.pending_syncs.len(),
1,
"a live caller's barrier is parked to await its cookie"
);
assert!(
h.owner.source.ended_syncs.is_empty(),
"and its cookie is not reaped while the caller still waits"
);
}
#[tokio::test]
async fn a_delivered_rescan_between_the_call_and_the_install_resolves_dominated() {
use core::sync::atomic::Ordering;
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
h.owner.source.supports_sync = true;
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let loss_gen_at_call = h.owner.loss_gen.load(Ordering::SeqCst);
h.owner
.consume_source_event(&rescan_event(handle, "/a", 10));
assert!(
!h.owner.needs_rescan.contains_key(&sub) && !h.owner.suppressed_rescan.contains_key(&sub),
"the Rescan was delivered, not parked — no standing debt for the install to snapshot"
);
assert_eq!(
h.owner.loss_serial.get(&sub).copied().unwrap_or(0),
0,
"a delivered Rescan never moves the per-subscription serial — the long-window probe is blind too"
);
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.on_sync(sub, loss_gen_at_call, reply_tx).await;
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 20));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a Rescan delivered between the caller's sync() call and the install resolves Dominated"
);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/cookie-1")],
"the dominated barrier's cookie is reaped"
);
}
#[tokio::test]
async fn a_loss_between_the_call_and_the_install_resolves_dominated() {
use core::sync::atomic::Ordering;
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
h.owner.source.supports_sync = true;
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let loss_gen_at_call = h.owner.loss_gen.load(Ordering::SeqCst);
h.owner.park_rescan(sub);
h.owner.flush_pending_rescans();
assert!(
!h.owner.needs_rescan.contains_key(&sub) && !h.owner.suppressed_rescan.contains_key(&sub),
"the loss published and cleared before the barrier is installed — no standing debt to snapshot"
);
assert_ne!(
h.owner.loss_serial.get(&sub).copied().unwrap_or(0),
0,
"the loss serial ALREADY advanced, so the install-to-resolve comparison cannot see this loss"
);
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.on_sync(sub, loss_gen_at_call, reply_tx).await;
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 20));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a loss processed between the caller's sync() call and the barrier's install resolves \
Dominated, never a false Delivered"
);
}
#[tokio::test]
async fn a_parked_rescan_published_in_the_call_window_resolves_dominated() {
use core::sync::atomic::Ordering;
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
h.owner.source.supports_sync = true;
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
h.owner.park_rescan(sub);
assert!(
h.owner.needs_rescan.contains_key(&sub),
"the pre-call loss parked debt"
);
let loss_gen_at_call = h.owner.loss_gen.load(Ordering::SeqCst);
h.owner.flush_pending_rescans();
assert!(
!h.owner.needs_rescan.contains_key(&sub),
"the parked Rescan published and cleared before the barrier installs"
);
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.on_sync(sub, loss_gen_at_call, reply_tx).await;
h.owner
.consume_source_event(&source_created(handle, "/a/cookie-1", 20));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a parked Rescan published in the call-to-install window resolves Dominated, not a false Delivered"
);
}
#[tokio::test]
async fn an_installed_barrier_is_dominated_by_a_descendant_rescan() {
use futures_util::FutureExt;
use crate::source::SyncOutcome;
let mut h = Harness::new();
let sub = h.watch("/r", Interest::all()).await.expect("watch /r");
let handle = h.owner.subsumer.subscription_root(sub).expect("live root");
let (reply_tx, mut reply_rx) = futures_channel::oneshot::channel();
h.owner.pending_syncs.push(super::PendingSync {
cookie_key: key("/r/.cookie"),
sub,
root: handle,
loss_serial_at_install: 0,
dominated_at_install: false,
reply: reply_tx,
});
h.owner
.consume_source_event(&rescan_event(handle, "/r/x", 5));
assert!(
matches!(
(&mut reply_rx).now_or_never(),
Some(Ok(Ok(SyncOutcome::Dominated)))
),
"a descendant-loss Rescan dominates the /r barrier by subscription, not by cookie ancestry"
);
}
#[tokio::test]
async fn a_transient_root_rescan_after_a_widen_rollback_is_clamped_to_the_live_root() {
let mut h = Harness::new();
h.owner.source.supports_replace = true;
let s_narrow = h.watch("/a/b", Interest::all()).await.expect("watch /a/b");
let handle = h
.owner
.subsumer
.subscription_root(s_narrow)
.expect("live root");
h.owner
.source
.retarget
.insert(PathBuf::from("/a"), PathBuf::from("/z"));
let err = h
.watch("/a", Interest::all())
.await
.expect_err("the diverging widen is refused");
assert!(matches!(err, WatchError::CanonicalRace), "{err:?}");
assert_eq!(
h.owner.needs_rescan.get(&s_narrow).map(|p| p.key.clone()),
Some(key("/a/b")),
"the rollback owes s_narrow a Rescan at its exact /a/b coverage"
);
assert_eq!(h.owner.source.root_key(handle), Some(key("/a/b")));
let mut pumped = Vec::new();
while let Some(ev) = h.owner.source.next().await {
pumped.push(ev);
}
assert_eq!(
pumped.len(),
2,
"each replace enqueued one full-root Rescan: {pumped:?}"
);
for ev in &pumped {
h.owner.consume_source_event(ev);
}
assert_eq!(
h.owner.needs_rescan.get(&s_narrow).map(|p| p.key.clone()),
Some(key("/a/b")),
"the stale /z Rescan was clamped to the live root; the debt never widened to a common ancestor"
);
}
#[tokio::test]
async fn on_sync_skips_an_already_canceled_barrier() {
use crate::{error::SyncError, source::SyncOutcome};
let mut h = Harness::new();
h.owner.source.supports_sync = true;
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let (reply_tx, reply_rx) = futures_channel::oneshot::channel::<Result<SyncOutcome, SyncError>>();
drop(reply_rx);
assert!(
reply_tx.is_canceled(),
"the reply is canceled before on_sync runs"
);
h.owner.on_sync(sub, 0, reply_tx).await;
assert!(
h.owner.pending_syncs.is_empty(),
"no PendingSync is parked for an already-canceled reply"
);
assert_eq!(
h.owner.sync_seq, 0,
"no token was minted — the skip precedes begin_sync"
);
assert!(
h.owner.source.ended_syncs.is_empty(),
"no cookie was written, so none is reaped"
);
}
#[tokio::test]
async fn a_write_completing_between_its_poll_and_the_cancel_poll_is_cancelled_by_token() {
use core::sync::atomic::Ordering;
use std::task::{Context, Poll, Waker};
let mut h = Harness::new();
h.owner.source.supports_sync = true;
h.owner.source.sync_script =
VecDeque::from([ScriptStep::Pending, ScriptStep::PendingThenComplete]);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let loss_gen = h.owner.loss_gen.load(Ordering::SeqCst);
let (reply_tx, reply_rx) = futures_channel::oneshot::channel();
let mut cx = Context::from_waker(Waker::noop());
let mut fut = Box::pin(h.owner.on_sync(sub, loss_gen, reply_tx));
assert!(
fut.as_mut().poll(&mut cx).is_pending(),
"the write is in flight and the caller still waits — the pass parks"
);
drop(reply_rx);
let admit = fut.as_mut().poll(&mut cx);
assert!(
matches!(admit, Poll::Ready(super::SyncAdmit::Done)),
"the cancellation arm resolves the abandoned barrier in the same pass"
);
drop(fut);
let token = h
.owner
.source
.begun_token
.expect("begin_sync minted the token");
assert_eq!(
h.owner.source.fs_delivered,
vec![key("/a/cookie-1")],
"the write DID complete and deliver its cookie between the two arm polls"
);
assert!(
h.owner.source.ended_syncs.is_empty(),
"no path-precise reap was possible — the owner never learned the cookie key"
);
assert_eq!(
h.owner.source.cancelled_syncs,
vec![token],
"the token cancel is the ONLY thing that frees the delivered-but-unread cookie"
);
assert!(
h.owner.pending_syncs.is_empty(),
"the abandoned barrier parked nothing (leak oracle)"
);
}
#[tokio::test]
async fn a_write_completing_between_its_poll_and_the_cancel_poll_is_cancelled_by_token_close_arm() {
use core::sync::atomic::Ordering;
use std::task::{Context, Poll, Waker};
let mut h = Harness::new();
h.owner.source.supports_sync = true;
h.owner.source.sync_script =
VecDeque::from([ScriptStep::Pending, ScriptStep::PendingThenComplete]);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let loss_gen = h.owner.loss_gen.load(Ordering::SeqCst);
let (reply_tx, _reply_rx) = futures_channel::oneshot::channel();
let mut cx = Context::from_waker(Waker::noop());
let mut fut = Box::pin(h.owner.on_sync(sub, loss_gen, reply_tx));
assert!(
fut.as_mut().poll(&mut cx).is_pending(),
"the write is in flight and no close is queued — the pass parks"
);
let (close_reply, _close_resp) =
futures_channel::oneshot::channel::<Result<(), super::CloseError>>();
h.closes
.try_send(close_reply)
.expect("queue the close on the dedicated signal");
let admit = fut.as_mut().poll(&mut cx);
assert!(
matches!(admit, Poll::Ready(super::SyncAdmit::CloseRequested(_))),
"the close arm consumes its reply and abandons the in-flight write"
);
drop(fut);
let token = h
.owner
.source
.begun_token
.expect("begin_sync minted the token");
assert_eq!(
h.owner.source.fs_delivered,
vec![key("/a/cookie-1")],
"the write delivered its cookie between the two arm polls"
);
assert!(
h.owner.source.ended_syncs.is_empty(),
"the owner never learned the cookie key — no path-precise reap"
);
assert_eq!(
h.owner.source.cancelled_syncs,
vec![token],
"the close abandon token-cancels the delivered-but-unread cookie"
);
assert!(
h.owner.pending_syncs.is_empty(),
"the abandoned barrier parked nothing (leak oracle)"
);
}
#[tokio::test]
async fn a_ready_write_still_wins_the_tie_and_is_not_token_cancelled() {
use core::sync::atomic::Ordering;
use std::task::{Context, Poll, Waker};
let mut h = Harness::new();
h.owner.source.supports_sync = true;
h.owner.source.sync_script = VecDeque::from([ScriptStep::Pending, ScriptStep::Ready]);
let sub = h.watch("/a", Interest::all()).await.expect("watch /a");
let loss_gen = h.owner.loss_gen.load(Ordering::SeqCst);
let (reply_tx, reply_rx) = futures_channel::oneshot::channel();
let mut cx = Context::from_waker(Waker::noop());
let mut fut = Box::pin(h.owner.on_sync(sub, loss_gen, reply_tx));
assert!(
fut.as_mut().poll(&mut cx).is_pending(),
"the write is in flight; the caller still waits — the pass parks"
);
drop(reply_rx);
let admit = fut.as_mut().poll(&mut cx);
assert!(
matches!(admit, Poll::Ready(super::SyncAdmit::Done)),
"the ready write wins the tie and admits"
);
drop(fut);
assert_eq!(
h.owner.source.ended_syncs,
vec![key("/a/cookie-1")],
"the completed cookie is reaped by PATH — the R7-1 write-first outcome"
);
assert!(
h.owner.source.cancelled_syncs.is_empty(),
"a completed write is NOT token-cancelled — the cancel fires only on abandon"
);
assert!(
h.owner.source.fs_delivered.is_empty(),
"the Ready step resolves the write; it does not side-effect-deliver"
);
assert!(
h.owner.pending_syncs.is_empty(),
"the gone caller's cookie is reaped inline, not parked (leak oracle)"
);
}
struct SyncSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
pending: VecDeque<SourceEvent<OsString, u32>>,
observe: bool,
}
impl Source<OsString> for SyncSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
fn is_sync_artifact(&self, key: &[OsString]) -> bool {
key
.last()
.and_then(|leaf| leaf.to_str())
.is_some_and(|leaf| leaf.starts_with("cookie-"))
}
async fn begin_sync(
&mut self,
handle: u32,
dir_key: &[OsString],
token: SyncToken,
) -> Result<Vec<OsString>, crate::error::SyncError> {
let mut cookie_key = dir_key.to_vec();
cookie_key.push(OsString::from(format!("cookie-{}", token.seq())));
if self.observe {
self.pending.push_back(SourceEvent::new(
handle,
cookie_key.clone(),
EventKind::Created,
Location::new(),
Epoch::new(1),
Some(ChangeId::new(NonZeroU64::MIN)),
));
}
Ok(cookie_key)
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
if let Some(event) = self.pending.pop_front() {
Some(event)
} else {
std::future::pending::<Option<SourceEvent<OsString, u32>>>().await
}
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.get(&handle).cloned()
}
}
#[tokio::test]
async fn a_sync_admitted_through_the_dedicated_mailbox_still_resolves() {
use crate::source::SyncOutcome;
let source = SyncSource {
next_handle: 0,
live: HashMap::new(),
pending: VecDeque::new(),
observe: true,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let outcome = tokio::time::timeout(Duration::from_secs(5), w.sync(sub, Duration::from_secs(5)))
.await
.expect("the sync resolves within the test deadline")
.expect("the sync succeeds");
assert!(
matches!(outcome, SyncOutcome::Delivered),
"a clean end-to-end sync via the dedicated mailbox resolves Delivered: {outcome:?}"
);
}
#[tokio::test]
async fn a_sync_times_out_when_never_observed() {
use crate::error::SyncError;
let source = SyncSource {
next_handle: 0,
live: HashMap::new(),
pending: VecDeque::new(),
observe: false,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let result = tokio::time::timeout(
Duration::from_secs(5),
w.sync(sub, Duration::from_millis(100)),
)
.await
.expect("the outer test deadline is not hit — the inner sync timeout fires first");
assert!(
matches!(result, Err(SyncError::Timeout)),
"a barrier whose cookie is never observed times out: {result:?}"
);
}
fn spawn_saturating_command_flood(
commands: async_channel::Sender<super::Command<OsString, ()>>,
retired: Subscription,
) -> tokio::task::JoinHandle<()> {
tokio::spawn(async move {
loop {
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
match commands.try_send(super::Command::Unwatch {
sub: retired,
reply,
}) {
Ok(()) => {}
Err(async_channel::TrySendError::Full(_)) => tokio::task::yield_now().await,
Err(async_channel::TrySendError::Closed(_)) => return,
}
}
})
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn a_command_flood_does_not_starve_the_sync_mailbox() {
use crate::source::SyncOutcome;
let source = SyncSource {
next_handle: 0,
live: HashMap::new(),
pending: VecDeque::new(),
observe: true,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> = super::Tributaries::with_source(
source,
TributariesOptions::new().with_command_capacity(std::num::NonZeroUsize::new(500).unwrap()),
);
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let retired = w
.watch(key("/doomed"), (), WatchOptions::new())
.await
.expect("watch /doomed");
w.unwatch(retired).await.expect("retire /doomed");
for _ in 0..500 {
let (reply, response) = futures_channel::oneshot::channel();
drop(response);
w.commands
.try_send(super::Command::Unwatch {
sub: retired,
reply,
})
.expect("prefill the command backlog");
}
let flood = spawn_saturating_command_flood(w.commands.clone(), retired);
let outcome = tokio::time::timeout(Duration::from_secs(10), w.sync(sub, Duration::from_secs(5)))
.await
.expect("the outer test deadline is not hit — the sync resolves or its own timeout fires");
flood.abort();
let outcome = outcome.expect("the sync resolves rather than starving behind the command flood");
assert!(
matches!(outcome, SyncOutcome::Delivered),
"the barrier resolves cleanly under the flood — no loss occurred, so the deliberately GLOBAL \
loss generation must not fire spuriously on unrelated control-plane traffic: {outcome:?}"
);
}
struct HeldBeginSyncSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
begin_gate: async_channel::Receiver<()>,
}
impl Source<OsString> for HeldBeginSyncSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
fn is_sync_artifact(&self, key: &[OsString]) -> bool {
key
.last()
.and_then(|leaf| leaf.to_str())
.is_some_and(|leaf| leaf.starts_with("cookie-"))
}
async fn begin_sync(
&mut self,
_handle: u32,
dir_key: &[OsString],
token: SyncToken,
) -> Result<Vec<OsString>, crate::error::SyncError> {
let _ = self.begin_gate.recv().await;
let mut cookie_key = dir_key.to_vec();
cookie_key.push(OsString::from(format!("cookie-{}", token.seq())));
Ok(cookie_key)
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
std::future::pending::<Option<SourceEvent<OsString, u32>>>().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.get(&handle).cloned()
}
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn a_timed_out_sync_frees_the_owner_when_the_caller_drops() {
use crate::error::SyncError;
let (_begin_tx, begin_rx) = async_channel::unbounded::<()>();
let source = HeldBeginSyncSource {
next_handle: 0,
live: HashMap::new(),
begin_gate: begin_rx,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let result = tokio::time::timeout(
Duration::from_secs(10),
w.sync(sub, Duration::from_millis(300)),
)
.await
.expect("the outer bound is not hit — the inner sync timeout returns");
assert!(
matches!(result, Err(SyncError::Timeout)),
"the held sync times out: {result:?}"
);
tokio::time::timeout(
Duration::from_secs(5),
w.watch(key("/b"), (), WatchOptions::new()),
)
.await
.expect(
"the owner services a command after the timed-out sync — it is not wedged in the held write",
)
.expect("the follow-up watch succeeds");
assert!(
w.view().is_watched(&key("/b")),
"the follow-up watch committed — the owner resumed servicing the mailbox after freeing itself"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn a_close_during_a_held_sync_tears_down_promptly() {
use crate::error::SyncError;
let (_begin_tx, begin_rx) = async_channel::unbounded::<()>();
let source = HeldBeginSyncSource {
next_handle: 0,
live: HashMap::new(),
begin_gate: begin_rx,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
let sub = w
.watch(key("/a"), (), WatchOptions::new())
.await
.expect("watch /a");
let syncer = {
let w = w.clone();
tokio::spawn(async move { w.sync(sub, Duration::from_secs(30)).await })
};
tokio::time::sleep(Duration::from_millis(200)).await;
tokio::time::timeout(Duration::from_secs(5), w.close())
.await
.expect("close tears down promptly while the write is held — it does not wait the write out")
.expect("close acknowledges");
let sync_result = tokio::time::timeout(Duration::from_secs(5), syncer)
.await
.expect("the held sync resolves once the owner tore down")
.expect("sync task");
assert!(
matches!(sync_result, Err(SyncError::Closed)),
"the abandoned held sync resolves Closed after the close-driven teardown: {sync_result:?}"
);
}
struct HeldReplaceSource {
next_handle: u32,
live: HashMap<u32, Vec<OsString>>,
replace_gate: async_channel::Receiver<()>,
first_replace_diverges_to: Option<Vec<OsString>>,
replace_calls: u32,
}
impl Source<OsString> for HeldReplaceSource {
type Handle = u32;
fn canonicalize_key(&self, key: &[OsString]) -> Result<Vec<OsString>, WatchError> {
Ok(key.to_vec())
}
async fn arm(&mut self, key: &[OsString]) -> Result<Armed<OsString, u32>, WatchError> {
self.next_handle += 1;
let handle = self.next_handle;
self.live.insert(handle, key.to_vec());
Ok(Armed::new(handle, key.to_vec()))
}
fn disarm(&mut self, handle: u32) {
self.live.remove(&handle);
}
async fn replace(
&mut self,
handle: u32,
new_key: &[OsString],
) -> Result<Armed<OsString, u32>, WatchError> {
self.replace_calls += 1;
if self.replace_calls == 1
&& let Some(divergent) = self.first_replace_diverges_to.clone()
{
self.live.insert(handle, divergent.clone());
return Ok(Armed::new(handle, divergent));
}
let _ = self.replace_gate.recv().await;
self.live.insert(handle, new_key.to_vec());
Ok(Armed::new(handle, new_key.to_vec()))
}
async fn next(&mut self) -> Option<SourceEvent<OsString, u32>> {
std::future::pending::<Option<SourceEvent<OsString, u32>>>().await
}
fn root_key(&self, handle: u32) -> Option<Vec<OsString>> {
self.live.get(&handle).cloned()
}
}
async fn assert_a_held_retarget_does_not_wedge_close(
first_replace_diverges_to: Option<Vec<OsString>>,
) {
let (_replace_tx, replace_rx) = async_channel::unbounded::<()>();
let source = HeldReplaceSource {
next_handle: 0,
live: HashMap::new(),
replace_gate: replace_rx,
first_replace_diverges_to,
replace_calls: 0,
};
let w: super::Tributaries<OsString, (), TokioRuntime, u32> =
super::Tributaries::with_source(source, TributariesOptions::new());
w.watch(key("/a/b"), (), WatchOptions::new())
.await
.expect("watch /a/b");
let widener = {
let w = w.clone();
tokio::spawn(async move { w.watch(key("/a"), (), WatchOptions::new()).await })
};
tokio::time::sleep(Duration::from_millis(200)).await;
tokio::time::timeout(Duration::from_secs(5), w.close())
.await
.expect("close tears down promptly while the retarget is held — it does not wait it out")
.expect("close acknowledges");
let watch_result = tokio::time::timeout(Duration::from_secs(5), widener)
.await
.expect("the held widen resolves once the owner tore down")
.expect("widen task");
assert!(
matches!(watch_result, Err(WatchError::Closed)),
"the abandoned held widen resolves Closed after the close-driven teardown: {watch_result:?}"
);
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn a_hung_in_place_replace_does_not_wedge_close() {
assert_a_held_retarget_does_not_wedge_close(None).await;
}
#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
async fn a_hung_in_place_replace_rollback_does_not_wedge_close() {
assert_a_held_retarget_does_not_wedge_close(Some(key("/z"))).await;
}