tributaries 0.1.0

Cross-platform filesystem notification: overlapping watch subscriptions are subsumed into disjoint roots, and every event is attributed back to each subscription covering it.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
use core::num::NonZeroU64;
use std::{collections::HashMap, ffi::OsString, path::Path};

use tributary_proto::ScopeId;

use super::{RoutableEvent, Subscription, fan_out};

/// A path's `OsString` components — the located-key form the fs source keys on, and
/// the coordinate `fan_out` covers over.
fn key(path: &str) -> Vec<OsString> {
  Path::new(path)
    .components()
    .map(|c| c.as_os_str().to_os_string())
    .collect()
}

/// Which projection a subscriber received for one raw event — the four move
/// decompositions (design §5) plus the whole delivery for a non-move / Rescan. Carried
/// on the fake `Delivered` so a test can assert *which* projection each covering
/// subscriber got, not merely that it was covered.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Projection {
  /// The event as-is: a non-move change, a Rescan, or a both-covering Moved.
  Whole,
  /// The synthesized move-out `Removed(from)` (source-only coverage).
  MoveOut,
  /// The synthesized move-in `Created(to)` (destination-only coverage).
  MoveIn,
}

/// A fake delivery: the subscriber it was routed to and the projection it received.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
struct Delivered {
  sub: Subscription,
  projection: Projection,
}

/// A minimal stand-in for a raw event: routing reads its endpoint keys and whether it
/// is a `Rescan`. Its delivery records the subscriber and which projection it got, so a
/// test asserts the covered set **and** each move decomposition without touching any
/// real source's private event constructor. A `Some(from)` makes it a move whose
/// destination is `key`.
struct FakeEvent {
  key: Vec<OsString>,
  from: Option<Vec<OsString>>,
  rescan: bool,
}

impl FakeEvent {
  fn change(path: &str) -> Self {
    Self {
      key: key(path),
      from: None,
      rescan: false,
    }
  }

  fn rescan(path: &str) -> Self {
    Self {
      key: key(path),
      from: None,
      rescan: true,
    }
  }

  /// A move from `from` to `to` (the destination is `key`).
  fn moved(from: &str, to: &str) -> Self {
    Self {
      key: key(to),
      from: Some(key(from)),
      rescan: false,
    }
  }
}

impl RoutableEvent<OsString> for FakeEvent {
  type Delivered = Delivered;

  fn key(&self) -> &[OsString] {
    self.key.as_slice()
  }

  fn move_from(&self) -> Option<&[OsString]> {
    self.from.as_deref()
  }

  fn is_rescan(&self) -> bool {
    self.rescan
  }

  fn deliver(&self, sub: Subscription) -> Delivered {
    Delivered {
      sub,
      projection: Projection::Whole,
    }
  }

  fn deliver_move_out(&self, sub: Subscription) -> Delivered {
    Delivered {
      sub,
      projection: Projection::MoveOut,
    }
  }

  fn deliver_move_in(&self, sub: Subscription) -> Delivered {
    Delivered {
      sub,
      projection: Projection::MoveIn,
    }
  }
}

/// A test root's subscriber list plus a side table of each subscriber's key — the two
/// inputs `fan_out` needs (the matched root's subscribers and the key resolver).
struct Fixture {
  subscribers: Vec<Subscription>,
  keys: HashMap<Subscription, Vec<OsString>>,
}

impl Fixture {
  /// A root whose subscribers are the given `(id, key path)` pairs, in that
  /// (registration) order. The root path itself is immaterial to `fan_out` (it keys on
  /// the subscribers and their own keys), so only the subscribers are recorded.
  fn new(_root_path: &str, subscribers: &[(u64, &str)]) -> Self {
    let mut subs = Vec::new();
    let mut keys = HashMap::new();
    for &(id, path) in subscribers {
      let sub = Subscription::for_test(ScopeId::new(NonZeroU64::new(id).expect("nonzero id")));
      subs.push(sub);
      keys.insert(sub, key(path));
    }
    Self {
      subscribers: subs,
      keys,
    }
  }

  fn sub(&self, id: u64) -> Subscription {
    Subscription::for_test(ScopeId::new(NonZeroU64::new(id).expect("nonzero id")))
  }

  /// The full deliveries `event` fans out to (subscriber + projection), every
  /// subscriber's gate admitting — the move-decomposition assertions read this.
  fn route_full(&self, event: &FakeEvent) -> Vec<Delivered> {
    fan_out(
      event,
      &self.subscribers,
      |sub| self.keys.get(&sub).map(Vec::as_slice),
      |_sub, _delivered| true,
    )
  }

  /// The subscribers `event` fans out to, with every subscriber's gate admitting (so
  /// this isolates the coverage/Rescan logic from the filter/interest gate).
  fn route(&self, event: &FakeEvent) -> Vec<Subscription> {
    self.route_full(event).into_iter().map(|d| d.sub).collect()
  }

  /// The subscribers `event` fans out to, admitting a delivery only when `admits`
  /// returns `true` for its `(subscription, delivered)` — the filter/interest gate
  /// under test (it sees the *projected* delivery).
  fn route_filtered(
    &self,
    event: &FakeEvent,
    admits: impl Fn(Subscription, &Delivered) -> bool,
  ) -> Vec<Subscription> {
    fan_out(
      event,
      &self.subscribers,
      |sub| self.keys.get(&sub).map(Vec::as_slice),
      admits,
    )
    .into_iter()
    .map(|d| d.sub)
    .collect()
  }
}

#[test]
fn covers_single_subscriber() {
  let fx = Fixture::new("/a", &[(1, "/a")]);
  let delivered = fx.route(&FakeEvent::change("/a/file"));
  assert_eq!(
    delivered,
    vec![fx.sub(1)],
    "the lone covering sub is served"
  );
}

#[test]
fn overlap_fans_to_all_covering() {
  // Root /a carries two subscriptions: /a and /a/b.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b")]);

  // An event under /a/b is covered by both /a and /a/b.
  let both = fx.route(&FakeEvent::change("/a/b/c"));
  assert_eq!(
    both,
    vec![fx.sub(1), fx.sub(2)],
    "an event under /a/b reaches both /a and /a/b"
  );

  // An event under /a/x is covered only by /a — /a/b is a sibling, not an ancestor.
  let only_a = fx.route(&FakeEvent::change("/a/x"));
  assert_eq!(
    only_a,
    vec![fx.sub(1)],
    "an event under /a/x reaches only /a"
  );
}

#[test]
fn coverage_is_component_wise_not_prefix() {
  // /a/b must not "cover" /a/bc — the ancestor test is component-wise.
  let fx = Fixture::new("/a", &[(1, "/a/b")]);
  assert_eq!(
    fx.route(&FakeEvent::change("/a/bc")),
    Vec::<Subscription>::new(),
    "/a/b does not cover the sibling /a/bc"
  );
  assert_eq!(
    fx.route(&FakeEvent::change("/a/b")),
    vec![fx.sub(1)],
    "/a/b covers itself (ancestor-or-equal)"
  );
}

#[test]
fn rescan_reaches_all_subscribers() {
  // Root /a carries /a and the narrower /a/b/deep.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b/deep")]);

  // A non-Rescan at /a/x reaches only /a (coverage narrows out /a/b/deep).
  assert_eq!(
    fx.route(&FakeEvent::change("/a/x")),
    vec![fx.sub(1)],
    "a plain event honors coverage narrowing"
  );

  // A Rescan — even one located at /a/x, which /a/b/deep does not cover — reaches
  // EVERY subscriber of the root: coverage loss is never narrowed away.
  assert_eq!(
    fx.route(&FakeEvent::rescan("/a/x")),
    vec![fx.sub(1), fx.sub(2)],
    "a Rescan bypasses coverage and reaches all subscribers"
  );
}

#[test]
fn filter_narrows_the_covered_set() {
  // Root /a carries two covering subscriptions: /a and /a/b.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b")]);

  // An event under /a/b is COVERED by both, but subscription 2's filter rejects it —
  // the filter is an additional gate that narrows the covered set (§7).
  let admitted = fx.route_filtered(&FakeEvent::change("/a/b/c"), |sub, _| sub != fx.sub(2));
  assert_eq!(
    admitted,
    vec![fx.sub(1)],
    "the filter excludes the covering subscription that does not admit"
  );

  // With every filter admitting, both covering subscriptions receive it — proving the
  // narrowing above was the filter, not coverage.
  let both = fx.route_filtered(&FakeEvent::change("/a/b/c"), |_, _| true);
  assert_eq!(both, vec![fx.sub(1), fx.sub(2)], "both cover it");
}

#[test]
fn filter_only_sees_covered_deliveries() {
  // Root /a carries /a and /a/b. An event at /a/x is covered only by /a; the filter
  // must never be consulted for /a/b (it does not cover the event), so a filter that
  // panics for /a/b proves coverage is checked FIRST.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b")]);
  let admitted = fx.route_filtered(&FakeEvent::change("/a/x"), |sub, _| {
    assert_ne!(
      sub,
      fx.sub(2),
      "the filter is only asked about covering subs"
    );
    true
  });
  assert_eq!(
    admitted,
    vec![fx.sub(1)],
    "only the covering /a is admitted"
  );
}

#[test]
fn rescan_bypasses_the_filter() {
  // Root /a carries /a and /a/b. A Rescan must reach BOTH even when every filter
  // rejects — coverage loss is never filtered away (§7/§8). A filter that would reject
  // everything (and must never even be consulted for a Rescan) proves the bypass.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/b")]);
  let admitted = fx.route_filtered(&FakeEvent::rescan("/a/x"), |_, _| {
    panic!("the filter must not be consulted for a Rescan");
  });
  assert_eq!(
    admitted,
    vec![fx.sub(1), fx.sub(2)],
    "a Rescan bypasses the filter and reaches every subscriber"
  );
}

// -------------------------------------------------------------------------------
// Moved decomposition (design §5): a move has two endpoints; each subscriber gets
// exactly one projection from its two-endpoint coverage.
// -------------------------------------------------------------------------------

/// The projection each subscriber received, as `(id, Projection)` pairs, so a move
/// test asserts the per-subscriber decomposition directly.
fn projections(fx: &Fixture, event: &FakeEvent) -> Vec<(u64, Projection)> {
  fx.route_full(event)
    .into_iter()
    .map(|d| (d.sub.id().as_u64(), d.projection))
    .collect()
}

/// A subscription covering only the move SOURCE gets a move-out `Removed(from)` — it
/// must learn the file left its tree, even though the destination is outside its watch.
/// (The pre-fix bug tested only the destination path, so a source-only sub silently
/// missed the move entirely.)
#[test]
fn move_out_delivers_removed_to_source_only_sub() {
  // Root /a; the sub watches only /a/src. A move /a/src/f -> /a/dst/f: it covers the
  // source, not the destination.
  let fx = Fixture::new("/a", &[(1, "/a/src")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert_eq!(
    out,
    vec![(1, Projection::MoveOut)],
    "a source-only sub gets the move-out Removed(from) — never silently skipped"
  );
}

/// A subscription covering only the move DESTINATION gets a move-in `Created(to)` — the
/// file arrived from outside its watch.
#[test]
fn move_in_delivers_created_to_dest_only_sub() {
  let fx = Fixture::new("/a", &[(1, "/a/dst")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert_eq!(
    out,
    vec![(1, Projection::MoveIn)],
    "a destination-only sub gets the move-in Created(to)"
  );
}

/// A subscription covering BOTH endpoints gets exactly one whole `Moved` — never also a
/// Removed/Created (structural dedup).
#[test]
fn move_within_one_sub_delivers_one_moved() {
  // The sub watches all of /a, covering both /a/src/f and /a/dst/f.
  let fx = Fixture::new("/a", &[(1, "/a")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert_eq!(
    out,
    vec![(1, Projection::Whole)],
    "a both-covering sub gets exactly one whole Moved — dedup, no extra Removed/Created"
  );
}

/// A move between two SIBLING subscriptions decomposes per subscriber: the source-sub
/// gets a Removed, the dest-sub gets a Created — each sees its own side of the move.
#[test]
fn move_between_sibling_subs() {
  // Root /a carries two sibling subs: /a/src and /a/dst.
  let fx = Fixture::new("/a", &[(1, "/a/src"), (2, "/a/dst")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert_eq!(
    out,
    vec![(1, Projection::MoveOut), (2, Projection::MoveIn)],
    "the source-sub gets a Removed, the dest-sub a Created"
  );
}

/// A subscription covering NEITHER endpoint of a move gets nothing.
#[test]
fn move_covering_neither_endpoint_delivers_nothing() {
  let fx = Fixture::new("/a", &[(1, "/a/other")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert!(
    out.is_empty(),
    "a sub covering neither endpoint gets nothing"
  );
}

/// Dedup across a mixed subscriber set: one both-covering sub gets exactly one Moved,
/// while narrower siblings get their single-endpoint projection — no duplicate for the
/// both-coverer.
#[test]
fn move_dedup_both_covering_sub_gets_exactly_one_moved() {
  // /a covers both endpoints; /a/src covers only the source; /a/dst only the dest.
  let fx = Fixture::new("/a", &[(1, "/a"), (2, "/a/src"), (3, "/a/dst")]);
  let out = projections(&fx, &FakeEvent::moved("/a/src/f", "/a/dst/f"));
  assert_eq!(
    out,
    vec![
      (1, Projection::Whole), // both endpoints → one Moved, never also Removed/Created
      (2, Projection::MoveOut), // source only → Removed
      (3, Projection::MoveIn), // dest only → Created
    ],
    "the both-covering sub gets exactly one Moved; siblings get their one-sided projection"
  );
}

/// The filter/interest gate sees the *projected* delivery, so it can gate a move-out
/// and a move-in independently by their projected kind (a sub with `removed` interest
/// keeps a move-out but a `created`-only one would drop it). Here the gate rejects the
/// move-out projection specifically, proving the projection is minted before the gate.
#[test]
fn move_projection_is_gated_by_the_projected_kind() {
  let fx = Fixture::new("/a", &[(1, "/a/src"), (2, "/a/dst")]);
  // Admit everything EXCEPT the move-out projection (as a `created`-only interest would).
  let admitted = fx.route_filtered(&FakeEvent::moved("/a/src/f", "/a/dst/f"), |_sub, d| {
    d.projection != Projection::MoveOut
  });
  assert_eq!(
    admitted,
    vec![fx.sub(2)],
    "the gate drops the move-out projection; the move-in still reaches the dest-sub"
  );
}