Skip to main content

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}