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
//! The per-subscription admission [`Filter`] — a live-swappable predicate over a change's
//! **pre-delivery** attributes (design §7).
//!
//! A `Filter` decides, per subscription, whether an attributed change is delivered to its caller:
//! [`fan_out`](crate::route::fan_out) consults it as an **additional** admission gate, *after* the
//! coverage ancestor test (design §5). It is a predicate over a [`FilterInput`] — the change's
//! located key, its kind, and (for the fs source) its path — the fully-typed `Filter<L>`
//! location-parsing generic is deferred (design §7). The predicate lives behind an
//! [`arc_swap::ArcSwap`] so it can be **hot-swapped** at any time without re-arming the kernel
//! watch (a re-watch): the driver holds each subscription's `Filter` and [`swap`](Filter::swap)s
//! the closure in place, and the next change admitted sees the new predicate.
//!
//! # The contract: a pre-delivery predicate over *what* changed, never *when* or *whose*
//!
//! A filter inspects only the attributes a change carries **before** the umbrella turns it into a
//! delivery: the located [`key`](FilterInput::key), the [`kind`](FilterInput::kind), and the
//! [`location`](FilterInput::location) / [`path`](FilterInput::path). It **cannot** observe the
//! delivered [`Event`](crate::Event)'s [`epoch`](crate::Event::epoch) or its
//! [`value`](crate::Event::value): both are assigned *after* admission — the epoch is the
//! per-subscription monotone dominance stamp the driver rebases on (`stamp` runs only for an
//! admitted delivery, so a filtered-out one never perturbs a subscription's epoch space), and the
//! value is the caller's own attribution, baked on at emit time. At the moment the filter runs, a
//! candidate still carries the *raw* source epoch (which restarts at 0 on every re-point) and an
//! **unbaked** value, so a predicate that read them would mis-evaluate. [`FilterInput`] removes
//! that footgun by construction: those attributes are simply not reachable from a filter.
//!
//! # A `Rescan` always bypasses the filter
//!
//! A [`Rescan`](EventKind::Rescan) is a coverage-loss signal whose
//! [`epoch`](crate::Event::epoch) dominates everything before it, so it must reach every
//! subscriber unconditionally (design §7/§8). The filter is therefore **never** consulted for a
//! `Rescan`: [`fan_out`](crate::route::fan_out) delivers it before it ever reaches
//! [`admits`](Filter::admits). `admits` itself is a pure predicate — it does not special-case the
//! kind — because the bypass is enforced one level up, at the single point where coverage and
//! filter admission are both decided.
use Arc;
use ArcSwap;
use Location;
use crateEventKind;
/// The pre-delivery view a [`Filter`] predicate inspects (design §7): the attributes of a change
/// known **before** the umbrella stamps the delivery's epoch and bakes its owning value.
///
/// It exposes only *what* changed and *where* — the located [`key`](Self::key), the
/// [`kind`](Self::kind), the [`location`](Self::location), and (for the fs source) the
/// [`path`](Self::path) — deliberately **not** the delivered [`Event`](crate::Event)'s
/// [`epoch`](crate::Event::epoch) or [`value`](crate::Event::value), which are assigned only after
/// admission. Because a candidate is still carrying the raw source epoch (restarting at 0 on a
/// re-point) and an unbaked value when the filter runs, hiding both is what keeps a filter from
/// mis-evaluating on a provisional stamp or an absent value (see [`Filter`] for the contract).
///
/// Borrowed from the change under evaluation for the duration of one [`admits`](Filter::admits)
/// call — cheap to `Copy`, holds no owned state.
/// The boxed predicate a [`Filter`] holds: a `Send + Sync` closure over the pre-delivery
/// [`FilterInput`]. `Send + Sync` is mandatory — the driver swaps it across the async boundary and
/// reads it from whatever task polls `next()`.
type Predicate<C> = ;
/// A live-swappable admission predicate for one subscription (design §7), over a change's
/// pre-delivery [`FilterInput`].
///
/// Constructed with [`all`](Filter::all) (admit everything — the default) or [`new`](Filter::new)
/// (a custom predicate), and mutated in place with [`swap`](Filter::swap) — no re-watch, so a
/// caller can re-scope what a live subscription delivers at any time. The driver calls
/// [`admits`](Filter::admits) as the fan-out admission gate for every non-`Rescan` change (a
/// `Rescan` bypasses it unconditionally — coverage loss is never filtered away, design §7/§8).
///
/// The predicate sees only pre-delivery attributes ([`key`](FilterInput::key) /
/// [`kind`](FilterInput::kind) / [`path`](FilterInput::path)), never the delivered event's epoch
/// or value — both are assigned only *after* admission, so a filter cannot observe them.
///
/// Cloning a `Filter` (or sharing one behind an [`Arc`]) shares the same swappable slot: a
/// [`swap`](Filter::swap) through any handle is observed by every holder, which is what lets the
/// driver keep a subscription's filter while the caller keeps a handle to re-scope it live.