zond_engine/journal/settle.rs
1// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
2//
3// This file is part of Zond Engine, licensed under the GNU Affero General
4// Public License, version 3 or later. See the LICENSE file for details, or
5// <https://www.gnu.org/licenses/agpl-3.0.html>.
6//
7// SPDX-License-Identifier: AGPL-3.0-or-later
8
9//! # What became of a target, and whether a resume may skip it
10//!
11//! A raw port scan gives the same verdict to a target whose retry budget ran out and to
12//! one still mid-schedule when the scan stopped: both were asked and neither answered. A
13//! target no probe was sent to is recorded
14//! [`PortState::Unasked`](crate::model::port::PortState::Unasked), since that is a fact about
15//! the scan.
16//!
17//! A resume has to tell these apart. A cursor advanced over a target nobody probed produces
18//! a second sitting that skips it and a merged report claiming coverage it never had.
19//! [`Outcome`] makes the distinction unforgeable: only the settled variants carry a
20//! position, and a position is the only thing a cursor can advance over.
21//!
22//! | Outcome | Decided at | Position |
23//! |---|---|---|
24//! | [`Answered`](Outcome::Answered) | `ledger.resolve(..) -> Some` | yes |
25//! | [`Exhausted`](Outcome::Exhausted) | `Due::Exhausted` | yes |
26//! | [`Skipped`](Outcome::Skipped) | the liveness pass heard silence | yes |
27//! | [`Withheld`](Outcome::Withheld) | the exclusion policy names its machine | yes |
28//! | [`Unreachable`](Outcome::Unreachable) | its address was filed as one no route leads to | yes |
29//! | [`Interrupted`](Outcome::Interrupted) | `ledger.drain_unresolved()` | no |
30//! | [`Unasked`](Outcome::Unasked) | no probe was sent | no |
31//! | [`Undecided`](Outcome::Undecided) | the liveness pass reached no verdict | no |
32//! | [`Unroutable`](Outcome::Unroutable) | no scanner for the protocol, or a send refused | no |
33//!
34//! Unsettled outcomes are counted, not stored. Every one is re-probed, so only their
35//! total is worth reporting.
36
37use std::sync::Mutex;
38use std::sync::atomic::{AtomicU64, Ordering};
39
40use super::cursor::{Checkpoint, Cursor};
41use crate::model::order::Permutation;
42
43/// The two outcomes a probe earns, before the position is attached.
44///
45/// A caller that earned a verdict says which, and something that knows the plan
46/// attaches the position; see
47/// [`ScanContext::settle_address`](crate::scanner::session::ScanContext::settle_address),
48/// which is how a sweep settles an address it does not know the number of.
49///
50/// [`Skipped`](Outcome::Skipped) is not here because no probe earns it, and whatever decides
51/// it already knows the position. The unsettled outcomes carry no position and go straight
52/// through [`Settlements::record`].
53#[non_exhaustive]
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
55pub enum Settled {
56 /// The target answered.
57 Answered,
58 /// Its retry budget was spent without an answer.
59 Exhausted,
60}
61
62impl Settled {
63 /// The outcome this settlement is, at `position`.
64 pub fn at(self, position: u64) -> Outcome {
65 match self {
66 Settled::Answered => Outcome::Answered { position },
67 Settled::Exhausted => Outcome::Exhausted { position },
68 }
69 }
70}
71
72/// What became of one target in one sitting.
73///
74/// Settled variants carry the target's position in the plan's enumeration; see
75/// [`PlannedTarget`](crate::model::target::PlannedTarget).
76#[non_exhaustive]
77#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
78pub enum Outcome {
79 /// The target answered. Settled.
80 Answered {
81 /// Its position in the plan.
82 position: u64,
83 },
84
85 /// The retry budget was spent without an answer. Settled, since waiting longer could
86 /// not have changed it.
87 Exhausted {
88 /// Its position in the plan.
89 position: u64,
90 },
91
92 /// Its host answered nothing in the liveness pass, so no probe was owed.
93 ///
94 /// Settled, and the one settled outcome no probe was sent for. The scan asked
95 /// whether the host was there as many times as its policy allows and heard nothing, which
96 /// is what separates this from [`Undecided`](Outcome::Undecided).
97 ///
98 /// A resumed scan does not revisit these ports even if the host answers next time: the job
99 /// found the host down, and asking again is a new scan, as
100 /// [`JournalManifest`](crate::journal::manifest::JournalManifest) says about a plan that has
101 /// moved. [`ZondConfig::assume_up`](crate::config::ZondConfig::assume_up) opts out.
102 Skipped {
103 /// Its position in the plan.
104 position: u64,
105 },
106
107 /// Its address answers from the hardware of a machine the exclusion policy names,
108 /// so no probe was allowed.
109 ///
110 /// Settled, and like [`Skipped`](Outcome::Skipped) sent nothing. This host's neighbour
111 /// tables tied the address to that machine before anything was sent; see
112 /// [the machine an address names](crate::model::exclusion#an-address-names-a-machine).
113 /// A resume does not ask it either, whatever the tables say by then, since an exclusion may
114 /// only err towards withholding more.
115 Withheld {
116 /// Its position in the plan.
117 position: u64,
118 },
119
120 /// Its address was filed as one this machine cannot reach: no route or source
121 /// address led there, a route was refused by its type, or the neighbour never answered
122 /// address resolution.
123 ///
124 /// Settled, though nothing was sent. Asking again within the job would draw the same answer
125 /// from this machine's routing, and left unsettled every target at such an address would
126 /// keep a finished job resumable. A route that appears later is a reason for a new scan.
127 ///
128 /// Recorded when the address is filed, over every target the plan numbers at it. That is
129 /// what separates it from [`Unroutable`](Outcome::Unroutable), the one target a scanner
130 /// could not send, counted as it happens. See
131 /// [`ScanContext::record_unroutable`](crate::scanner::session::ScanContext::record_unroutable).
132 Unreachable {
133 /// Its position in the plan.
134 position: u64,
135 },
136
137 /// Outstanding mid-retry-schedule when the scan stopped.
138 Interrupted,
139
140 /// No probe was sent: the target was still queued when the scan stopped, its
141 /// host had already spent its own budget, or this machine's sender refused
142 /// the send.
143 Unasked,
144
145 /// No scanner spoke its protocol, or this machine refused to send the probe.
146 /// Usually a missing privilege or a local fault, which can differ between sittings. A target
147 /// whose address the scan then files as unreachable is settled over this, as
148 /// [`Unreachable`](Outcome::Unreachable).
149 Unroutable,
150
151 /// The liveness pass reached no verdict on its host, so it was neither probed nor
152 /// written off.
153 ///
154 /// The pass stopped before or while asking, had no strategy that could ask, or was refused
155 /// the range. None of those is silence, so it stays unsettled and the next sitting's
156 /// liveness pass asks about the host again.
157 Undecided,
158}
159
160impl Outcome {
161 /// The position a resume may skip, or `None` where the scan did not earn one.
162 pub fn settled_position(self) -> Option<u64> {
163 match self {
164 Outcome::Answered { position }
165 | Outcome::Exhausted { position }
166 | Outcome::Skipped { position }
167 | Outcome::Withheld { position }
168 | Outcome::Unreachable { position } => Some(position),
169 Outcome::Interrupted | Outcome::Unasked | Outcome::Unroutable | Outcome::Undecided => {
170 None
171 }
172 }
173 }
174
175 /// Whether a resume may skip this target.
176 pub fn is_settled(self) -> bool {
177 self.settled_position().is_some()
178 }
179
180 /// The wire name, for diagnostics and for reporting a sitting's shape.
181 pub fn name(self) -> &'static str {
182 match self {
183 Outcome::Answered { .. } => "answered",
184 Outcome::Exhausted { .. } => "exhausted",
185 Outcome::Skipped { .. } => "skipped",
186 Outcome::Withheld { .. } => "withheld",
187 Outcome::Unreachable { .. } => "unreachable",
188 Outcome::Interrupted => "interrupted",
189 Outcome::Unasked => "unasked",
190 Outcome::Unroutable => "unroutable",
191 Outcome::Undecided => "undecided",
192 }
193 }
194}
195
196/// How a sitting ended for each of its targets: a cursor over what settled, and
197/// counts of what did not.
198///
199/// Memory follows how far out of order the scan settled, not how many targets it
200/// had. See [`cursor`](super::cursor).
201#[derive(Debug, Default)]
202pub struct Settlements {
203 cursor: Mutex<Cursor>,
204 answered: AtomicU64,
205 exhausted: AtomicU64,
206 skipped: AtomicU64,
207 withheld: AtomicU64,
208 unreachable: AtomicU64,
209 interrupted: AtomicU64,
210 unasked: AtomicU64,
211 unroutable: AtomicU64,
212 undecided: AtomicU64,
213}
214
215impl Settlements {
216 /// Begins from a checkpoint, keeping what earlier sittings settled.
217 pub fn resuming(checkpoint: &Checkpoint) -> Self {
218 Self {
219 cursor: Mutex::new(Cursor::from_checkpoint(checkpoint)),
220 ..Self::default()
221 }
222 }
223
224 /// Begins from a checkpoint, also counting along `order` when the scan asks its
225 /// targets in one. See [`Cursor::walking`] for what that saves.
226 pub(crate) fn walking(checkpoint: &Checkpoint, order: Option<Permutation>) -> Self {
227 let cursor = Cursor::from_checkpoint(checkpoint);
228 Self {
229 cursor: Mutex::new(match order {
230 Some(order) => cursor.along(order),
231 None => cursor,
232 }),
233 ..Self::default()
234 }
235 }
236
237 /// Counts along `order` as well from here on, unless this count already has a walk
238 /// (see [`Cursor::along`]).
239 ///
240 /// For the stream that takes the walk. A session built without a plan cannot know its
241 /// dispatcher's walk, and counting a walked scan in plan order alone holds nearly every
242 /// settled position above the watermark: half the plan at the halfway mark.
243 pub(crate) fn walk_along(&self, order: Permutation) {
244 self.with_cursor(|cursor| *cursor = std::mem::take(cursor).along(order));
245 }
246
247 /// Records what became of one target.
248 pub fn record(&self, outcome: Outcome) {
249 self.counter(outcome).fetch_add(1, Ordering::Relaxed);
250
251 if let Some(position) = outcome.settled_position() {
252 self.with_cursor(|cursor| cursor.settle(position));
253 }
254 }
255
256 /// Whether the target at `position` is settled, by this sitting or an earlier one.
257 pub(crate) fn is_settled(&self, position: u64) -> bool {
258 self.with_cursor(|cursor| cursor.is_settled(position))
259 }
260
261 /// Records `outcome`, a settled one, unless its target is settled already.
262 ///
263 /// For an account given after the fact over every target at an address: targets that
264 /// earned a verdict of their own first keep it and are not counted twice.
265 pub(crate) fn record_unsettled(&self, outcome: Outcome) {
266 let Some(position) = outcome.settled_position() else {
267 return;
268 };
269 let fresh = self.with_cursor(|cursor| {
270 let fresh = !cursor.is_settled(position);
271 cursor.settle(position);
272 fresh
273 });
274 if fresh {
275 self.counter(outcome).fetch_add(1, Ordering::Relaxed);
276 }
277 }
278
279 /// Records `count` targets ending the same way.
280 ///
281 /// For the unsettled outcomes, which are counted, not stored: a sweep cut short can
282 /// leave millions of addresses unasked. A settled outcome names one position, so it goes
283 /// through [`record`](Self::record).
284 pub fn record_many(&self, outcome: Outcome, count: u64) {
285 debug_assert!(
286 !outcome.is_settled(),
287 "a settled outcome names one position and cannot stand for many"
288 );
289 self.counter(outcome).fetch_add(count, Ordering::Relaxed);
290 }
291
292 /// A snapshot to write down.
293 pub fn checkpoint(&self) -> Checkpoint {
294 self.with_cursor(|cursor| cursor.checkpoint())
295 }
296
297 /// How many targets are settled in total, this sitting and any it resumed.
298 pub fn settled_count(&self) -> u64 {
299 self.with_cursor(|cursor| cursor.settled_count())
300 }
301
302 /// How many targets ended in `outcome`'s variant this sitting. The position of a
303 /// settled variant is ignored.
304 pub fn count(&self, outcome: Outcome) -> u64 {
305 self.counter(outcome).load(Ordering::Relaxed)
306 }
307
308 fn counter(&self, outcome: Outcome) -> &AtomicU64 {
309 match outcome {
310 Outcome::Answered { .. } => &self.answered,
311 Outcome::Exhausted { .. } => &self.exhausted,
312 Outcome::Skipped { .. } => &self.skipped,
313 Outcome::Withheld { .. } => &self.withheld,
314 Outcome::Unreachable { .. } => &self.unreachable,
315 Outcome::Interrupted => &self.interrupted,
316 Outcome::Unasked => &self.unasked,
317 Outcome::Unroutable => &self.unroutable,
318 Outcome::Undecided => &self.undecided,
319 }
320 }
321
322 fn with_cursor<R>(&self, read: impl FnOnce(&mut Cursor) -> R) -> R {
323 let mut cursor = self.cursor.lock().unwrap_or_else(|e| e.into_inner());
324 read(&mut cursor)
325 }
326}
327
328// ╔════════════════════════════════════════════╗
329// ║ ████████╗███████╗███████╗████████╗███████╗ ║
330// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
331// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
332// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
333// ║ ██║ ███████╗███████║ ██║ ███████║ ║
334// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
335// ╚════════════════════════════════════════════╝
336
337#[cfg(test)]
338mod tests {
339 use super::*;
340
341 /// The rule the type exists to enforce.
342 #[test]
343 fn only_an_earned_outcome_carries_a_position() {
344 assert_eq!(
345 Outcome::Answered { position: 7 }.settled_position(),
346 Some(7)
347 );
348 assert_eq!(
349 Outcome::Exhausted { position: 7 }.settled_position(),
350 Some(7)
351 );
352
353 assert_eq!(Outcome::Skipped { position: 7 }.settled_position(), Some(7));
354 assert_eq!(
355 Outcome::Withheld { position: 7 }.settled_position(),
356 Some(7)
357 );
358 assert_eq!(
359 Outcome::Unreachable { position: 7 }.settled_position(),
360 Some(7)
361 );
362
363 for assigned in [
364 Outcome::Interrupted,
365 Outcome::Unasked,
366 Outcome::Unroutable,
367 Outcome::Undecided,
368 ] {
369 assert_eq!(assigned.settled_position(), None, "{}", assigned.name());
370 assert!(!assigned.is_settled());
371 }
372 }
373
374 /// A sitting cut short advances the cursor over no outstanding or unasked target.
375 #[test]
376 fn a_cut_short_sitting_settles_only_what_it_earned() {
377 let settlements = Settlements::default();
378
379 settlements.record(Outcome::Answered { position: 0 });
380 settlements.record(Outcome::Exhausted { position: 1 });
381 for _ in 0..500 {
382 settlements.record(Outcome::Interrupted);
383 settlements.record(Outcome::Unasked);
384 }
385
386 let checkpoint = settlements.checkpoint();
387 assert_eq!(checkpoint.watermark, 2);
388 assert!(checkpoint.settled_above.is_empty());
389 assert_eq!(settlements.settled_count(), 2);
390 assert_eq!(settlements.count(Outcome::Interrupted), 500);
391 }
392
393 /// Unsettled outcomes cost a counter each, whatever their number.
394 #[test]
395 fn unsettled_outcomes_are_counted_rather_than_stored() {
396 let settlements = Settlements::default();
397 for _ in 0..100_000 {
398 settlements.record(Outcome::Unasked);
399 }
400
401 assert_eq!(settlements.count(Outcome::Unasked), 100_000);
402 assert_eq!(settlements.settled_count(), 0);
403 assert_eq!(settlements.checkpoint(), Checkpoint::default());
404 }
405
406 /// One unearned position holds the watermark however much settles above it.
407 #[test]
408 fn one_unearned_position_stalls_the_watermark() {
409 let settlements = Settlements::default();
410
411 settlements.record(Outcome::Answered { position: 0 });
412 // Position 1 was interrupted, so it carries no position and is re-probed.
413 settlements.record(Outcome::Interrupted);
414 for position in 2..1_000 {
415 settlements.record(Outcome::Answered { position });
416 }
417
418 assert_eq!(settlements.checkpoint().watermark, 1);
419 assert_eq!(settlements.settled_count(), 999);
420 }
421
422 /// A resumed sitting starts from what the first settled and counts only its own
423 /// work.
424 #[test]
425 fn resuming_keeps_the_earlier_sittings_progress() {
426 let first = Settlements::default();
427 for position in 0..10 {
428 first.record(Outcome::Answered { position });
429 }
430
431 let second = Settlements::resuming(&first.checkpoint());
432 assert_eq!(second.settled_count(), 10);
433 assert_eq!(second.count(Outcome::Answered { position: 0 }), 0);
434
435 second.record(Outcome::Exhausted { position: 10 });
436 assert_eq!(second.checkpoint().watermark, 11);
437 }
438}