Skip to main content

hopr_protocol_session/socket/
loss_report.rs

1//! Summarises dropped frames and duplicate segments received by a
2//! [`SessionSocket`](super::SessionSocket).
3//!
4//! Some frames arrive too late or have missing segments. Retried packets can also arrive twice.
5//! Simply logging every drop or duplicate can hide other problems. This module counts these
6//! events and logs an INFO summary only when frames were dropped or could not be reassembled.
7//!
8//! A "window" is the time covered by one summary. Each counted event checks whether enough time
9//! has passed to finish the window. There is no background timer, so an idle socket waits until
10//! the next event or until this report is dropped before logging its remaining counts.
11
12use std::{
13    sync::{
14        Arc,
15        atomic::{AtomicU64, Ordering},
16    },
17    time::{Duration, Instant},
18};
19
20use super::loss_signal::FrameLossSignal;
21
22/// Minimum time between summaries, except for the final summary when the report is dropped.
23pub(crate) const FRAME_LOSS_REPORT_INTERVAL: Duration = Duration::from_secs(30);
24
25/// Counts collected during one reporting period.
26///
27/// These counts measure different events. They are not mutually exclusive.
28/// A failed reassembly and a later discard can refer to
29/// the same frame, and duplicates count segments, not frames. Do not add them to calculate loss.
30#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
31pub(crate) struct FrameLossSummary {
32    /// Complete frames passed to the reader.
33    pub emitted: u64,
34    /// Frames skipped while putting received frames in order.
35    /// E.g. Frame 10 is missing or too late, so delivery continues with frame 11.
36    pub discarded: u64,
37    /// Frames that could not be built from the received segments.
38    /// E.g. A frame needs 3 segments but only 2 were arrived before timeout.
39    pub not_reassembled: u64,
40    /// Ignored segments whose frame ID is at or below the last frame passed to the reader.
41    pub duplicates: u64,
42    /// Time covered by these counts.
43    pub window: Duration,
44}
45
46impl FrameLossSummary {
47    /// Whether any frames were dropped or could not be reassembled.
48    pub fn has_loss(&self) -> bool {
49        self.discarded > 0 || self.not_reassembled > 0
50    }
51
52    fn log(&self, session_id: &str) {
53        tracing::info!(
54            session_id,
55            emitted = self.emitted,
56            discarded = self.discarded,
57            not_reassembled = self.not_reassembled,
58            duplicates = self.duplicates,
59            window_s = self.window.as_secs(),
60            "session frames dropped in the last window"
61        );
62    }
63}
64
65/// Counts received frames and duplicate segments, and logs summaries when there is frame loss.
66///
67/// The receive stages share this report. When its last owner drops it, it logs any remaining
68/// counts if frames were dropped or could not be reassembled. Duplicate segments alone do not
69/// indicate frame loss, but their counts are included as context in loss summaries.
70#[derive(Debug)]
71pub(crate) struct FrameLossReport {
72    session_id: String,
73    interval: Duration,
74    emitted: AtomicU64,
75    discarded: AtomicU64,
76    not_reassembled: AtomicU64,
77    duplicates: AtomicU64,
78    window_start: parking_lot::Mutex<Instant>,
79    /// Live loss, for a reader that has to react within seconds rather than within a window.
80    ///
81    /// `None` for a socket nobody observes, which is every socket but an Exit Session's.
82    loss_signal: Option<Arc<FrameLossSignal>>,
83}
84
85impl FrameLossReport {
86    #[cfg(test)]
87    pub fn new(session_id: impl std::fmt::Display, interval: Duration) -> Self {
88        Self::with_signal(session_id, interval, None)
89    }
90
91    /// As `new`, also recording every loss into `loss_signal` as it happens.
92    pub fn with_signal(
93        session_id: impl std::fmt::Display,
94        interval: Duration,
95        loss_signal: Option<Arc<FrameLossSignal>>,
96    ) -> Self {
97        Self {
98            session_id: session_id.to_string(),
99            interval,
100            emitted: AtomicU64::new(0),
101            discarded: AtomicU64::new(0),
102            not_reassembled: AtomicU64::new(0),
103            duplicates: AtomicU64::new(0),
104            window_start: parking_lot::Mutex::new(Instant::now()),
105            loss_signal,
106        }
107    }
108
109    pub fn frame_emitted(&self) {
110        self.emitted.fetch_add(1, Ordering::Relaxed);
111        self.report_if_due();
112    }
113
114    pub fn frame_discarded(&self) {
115        self.discarded.fetch_add(1, Ordering::Relaxed);
116        self.record_loss();
117        self.report_if_due();
118    }
119
120    pub fn frame_not_reassembled(&self) {
121        self.not_reassembled.fetch_add(1, Ordering::Relaxed);
122        self.record_loss();
123        self.report_if_due();
124    }
125
126    /// A segment of `frame_id` arrived and was not a duplicate: the live signal's stall detection
127    /// follows it, if there is a signal.
128    pub fn segment_received(&self, frame_id: u32) {
129        if let Some(signal) = &self.loss_signal {
130            signal.segment_received(frame_id);
131        }
132    }
133
134    /// A frame completed its reassembly, which ends a stall of the live signal, if there is one.
135    pub fn frame_reassembled(&self) {
136        if let Some(signal) = &self.loss_signal {
137            signal.frame_completed();
138        }
139    }
140
141    /// Records a loss into the live signal, if there is one.
142    ///
143    /// Only the two loss events call this: a duplicate segment is delivery, not loss.
144    fn record_loss(&self) {
145        if let Some(signal) = &self.loss_signal {
146            signal.record();
147        }
148    }
149
150    pub fn duplicate_segment(&self) {
151        self.duplicates.fetch_add(1, Ordering::Relaxed);
152        self.report_if_due();
153    }
154
155    fn report_if_due(&self) {
156        if let Some(summary) = self.close_window_if_due(Instant::now())
157            && summary.has_loss()
158        {
159            summary.log(&self.session_id);
160        }
161    }
162
163    /// Returns the counts and starts a new period if enough time has passed.
164    ///
165    /// If another call holds the lock, return without waiting. The counts stay available for
166    /// this summary or the next one.
167    fn close_window_if_due(&self, now: Instant) -> Option<FrameLossSummary> {
168        let mut window_start = self.window_start.try_lock()?;
169        let window = now.saturating_duration_since(*window_start);
170        if window < self.interval {
171            return None;
172        }
173        *window_start = now;
174        Some(self.take_counts(window))
175    }
176
177    fn take_counts(&self, window: Duration) -> FrameLossSummary {
178        FrameLossSummary {
179            emitted: self.emitted.swap(0, Ordering::Relaxed),
180            discarded: self.discarded.swap(0, Ordering::Relaxed),
181            not_reassembled: self.not_reassembled.swap(0, Ordering::Relaxed),
182            duplicates: self.duplicates.swap(0, Ordering::Relaxed),
183            window,
184        }
185    }
186}
187
188impl Drop for FrameLossReport {
189    fn drop(&mut self) {
190        let window = self.window_start.get_mut().elapsed();
191        let summary = self.take_counts(window);
192        if summary.has_loss() {
193            summary.log(&self.session_id);
194        }
195    }
196}
197
198#[cfg(test)]
199mod tests {
200    use anyhow::Context;
201
202    use super::*;
203
204    const INTERVAL: Duration = Duration::from_secs(30);
205
206    #[test]
207    fn window_is_not_closed_before_the_interval() {
208        let report = FrameLossReport::new("test", INTERVAL);
209        report.discarded.fetch_add(3, Ordering::Relaxed);
210
211        let start = *report.window_start.lock();
212        assert_eq!(report.close_window_if_due(start + INTERVAL / 2), None);
213        assert_eq!(report.discarded.load(Ordering::Relaxed), 3, "counts must be kept");
214    }
215
216    #[test]
217    fn closing_a_window_returns_and_resets_its_counts() -> anyhow::Result<()> {
218        let report = FrameLossReport::new("test", INTERVAL);
219        report.emitted.fetch_add(10, Ordering::Relaxed);
220        report.discarded.fetch_add(2, Ordering::Relaxed);
221        report.not_reassembled.fetch_add(1, Ordering::Relaxed);
222        report.duplicates.fetch_add(4, Ordering::Relaxed);
223
224        let start = *report.window_start.lock();
225        let summary = report
226            .close_window_if_due(start + INTERVAL)
227            .context("window must close at the interval")?;
228
229        assert_eq!(
230            summary,
231            FrameLossSummary {
232                emitted: 10,
233                discarded: 2,
234                not_reassembled: 1,
235                duplicates: 4,
236                window: INTERVAL,
237            }
238        );
239        assert!(summary.has_loss());
240
241        // Reset the counts and start the next period where this one ended.
242        assert_eq!(*report.window_start.lock(), start + INTERVAL);
243        let next = report
244            .close_window_if_due(start + 2 * INTERVAL)
245            .context("second window must close")?;
246        assert_eq!(
247            next.emitted + next.discarded + next.not_reassembled + next.duplicates,
248            0
249        );
250        Ok(())
251    }
252
253    #[test]
254    fn a_window_with_only_delivered_frames_has_no_loss() {
255        let summary = FrameLossSummary {
256            emitted: 100,
257            window: INTERVAL,
258            ..Default::default()
259        };
260        assert!(!summary.has_loss());
261    }
262
263    #[test]
264    fn duplicate_segments_do_not_indicate_frame_loss() {
265        let summary = FrameLossSummary {
266            emitted: 100,
267            duplicates: 4,
268            window: INTERVAL,
269            ..Default::default()
270        };
271        assert!(!summary.has_loss());
272    }
273
274    #[test]
275    fn discarded_or_unreassembled_frames_indicate_loss() {
276        for (discarded, not_reassembled) in [(1, 0), (0, 1)] {
277            let summary = FrameLossSummary {
278                discarded,
279                not_reassembled,
280                window: INTERVAL,
281                ..Default::default()
282            };
283            assert!(summary.has_loss());
284        }
285    }
286
287    #[test]
288    fn loss_is_recorded_into_the_signal_while_the_window_goes_on() {
289        let signal = Arc::new(FrameLossSignal::new());
290        let report = FrameLossReport::with_signal("test", INTERVAL, Some(signal.clone()));
291
292        report.frame_discarded();
293        report.frame_not_reassembled();
294        assert_eq!(2, signal.lost_total(), "both loss events are loss");
295
296        // A duplicate segment is delivery, not loss, and the window closing does not reset the signal.
297        report.duplicate_segment();
298        assert_eq!(2, signal.lost_total());
299        let start = *report.window_start.lock();
300        assert!(report.close_window_if_due(start + INTERVAL).is_some());
301        assert_eq!(
302            2,
303            signal.lost_total(),
304            "the signal outlives the window that the log summary resets"
305        );
306        assert!(signal.lost_within(Duration::from_secs(1)));
307    }
308
309    #[test]
310    fn a_report_without_a_signal_counts_as_before() {
311        let report = FrameLossReport::new("test", INTERVAL);
312        report.frame_discarded();
313        report.frame_not_reassembled();
314        report.duplicate_segment();
315
316        let summary = report.take_counts(Duration::ZERO);
317        assert_eq!(
318            (1, 1, 1),
319            (summary.discarded, summary.not_reassembled, summary.duplicates)
320        );
321    }
322
323    #[test]
324    fn counting_methods_update_their_own_counter() {
325        let report = FrameLossReport::new("test", INTERVAL);
326        report.frame_emitted();
327        report.frame_discarded();
328        report.frame_discarded();
329        report.frame_not_reassembled();
330        report.duplicate_segment();
331
332        let summary = report.take_counts(Duration::ZERO);
333        assert_eq!(summary.emitted, 1);
334        assert_eq!(summary.discarded, 2);
335        assert_eq!(summary.not_reassembled, 1);
336        assert_eq!(summary.duplicates, 1);
337    }
338}