Skip to main content

rustnet_core/network/
dns_analytics.rs

1//! Bounded passive DNS transaction analytics.
2
3use std::collections::{HashMap, VecDeque};
4use std::time::{Duration, SystemTime};
5
6use super::types::{ConnectionKey, DnsInfo, DnsQueryType};
7
8const DNS_ANALYTICS_WINDOW: Duration = Duration::from_secs(60);
9const DNS_TRANSACTION_TIMEOUT: Duration = Duration::from_secs(10);
10const MAX_PENDING_DNS_TRANSACTIONS: usize = 4096;
11const MAX_RETAINED_DNS_TRANSACTIONS: usize = 8192;
12/// Operational-failure share of finalized lookups that degrades DNS health.
13pub const DEGRADED_FAILURE_PERCENT: usize = 20;
14const DEGRADED_P95: Duration = Duration::from_millis(500);
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
17pub enum DnsHealth {
18    #[default]
19    NotObserved,
20    Checking,
21    Responsive,
22    Degraded,
23    Failing,
24    NoReplies,
25}
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct DnsQuestionStats {
29    pub name: String,
30    pub query_type: Option<DnsQueryType>,
31    pub lookups: usize,
32    pub nxdomain: usize,
33    pub failures: usize,
34    pub latency_p95: Option<Duration>,
35}
36
37#[derive(Debug, Clone, PartialEq, Eq, Default)]
38pub struct DnsAnalyticsSnapshot {
39    pub health: DnsHealth,
40    pub lookups: usize,
41    pub answered: usize,
42    pub pending: usize,
43    pub timeouts: usize,
44    pub noerror: usize,
45    pub nxdomain: usize,
46    pub servfail: usize,
47    pub refused: usize,
48    pub other_rcodes: usize,
49    pub nodata: usize,
50    /// Operational failures among finalized lookups: timeouts plus every
51    /// response other than NOERROR or NXDOMAIN.
52    pub failures: usize,
53    pub latency_samples: usize,
54    pub latency_p50: Option<Duration>,
55    pub latency_p95: Option<Duration>,
56    pub latency_max: Option<Duration>,
57    /// Latency buckets: below 10ms, 10ms to below 50ms, 50ms to below
58    /// 100ms, and 100ms or slower.
59    pub latency_buckets: [usize; 4],
60    pub questions: Vec<DnsQuestionStats>,
61    /// True when capacity pressure within the rolling window caused at least
62    /// one transaction sample to be omitted or evicted.
63    pub truncated: bool,
64}
65
66#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
67struct TransactionKey {
68    connection: ConnectionKey,
69    txid: u16,
70}
71
72#[derive(Debug)]
73struct PendingTransaction {
74    sent_at: SystemTime,
75    query_name: Option<String>,
76    query_type: Option<DnsQueryType>,
77}
78
79#[derive(Debug)]
80struct CompletedTransaction {
81    completed_at: SystemTime,
82    query_name: Option<String>,
83    query_type: Option<DnsQueryType>,
84    rcode: Option<u8>,
85    nodata: bool,
86    latency: Option<Duration>,
87    timed_out: bool,
88}
89
90impl CompletedTransaction {
91    fn is_normal_response(&self) -> bool {
92        !self.timed_out && matches!(self.rcode, Some(0 | 3))
93    }
94
95    fn is_failure(&self) -> bool {
96        !self.is_normal_response()
97    }
98}
99
100#[derive(Debug, Default)]
101struct QuestionAggregate {
102    lookups: usize,
103    nxdomain: usize,
104    failures: usize,
105    latencies: Vec<Duration>,
106}
107
108#[derive(Debug, Default)]
109pub(crate) struct DnsAnalyticsTracker {
110    pending: HashMap<TransactionKey, PendingTransaction>,
111    completed: VecDeque<CompletedTransaction>,
112    truncated_at: Option<SystemTime>,
113}
114
115impl DnsAnalyticsTracker {
116    pub(crate) fn record_packet(
117        &mut self,
118        connection: ConnectionKey,
119        info: &DnsInfo,
120        is_outgoing: bool,
121        at: SystemTime,
122        latency: Option<Duration>,
123    ) {
124        self.advance(at);
125        let key = TransactionKey {
126            connection,
127            txid: info.txid,
128        };
129
130        if is_outgoing && !info.is_response {
131            let pending = PendingTransaction {
132                sent_at: at,
133                query_name: normalize_query_name(info.query_name.as_deref()),
134                query_type: info.query_type,
135            };
136            if self.pending.len() < MAX_PENDING_DNS_TRANSACTIONS || self.pending.contains_key(&key)
137            {
138                self.pending.insert(key, pending);
139            } else {
140                self.mark_truncated(at);
141            }
142            return;
143        }
144
145        if is_outgoing || !info.is_response {
146            return;
147        }
148
149        let Some(mut pending) = self.pending.remove(&key) else {
150            return;
151        };
152        if pending.query_name.is_none() {
153            pending.query_name = normalize_query_name(info.query_name.as_deref());
154        }
155        if pending.query_type.is_none() {
156            pending.query_type = info.query_type;
157        }
158        self.push_completed(CompletedTransaction {
159            completed_at: at,
160            query_name: pending.query_name,
161            query_type: pending.query_type,
162            rcode: info.rcode,
163            nodata: info.nodata == Some(true),
164            latency,
165            timed_out: false,
166        });
167    }
168
169    pub(crate) fn snapshot(&mut self, now: SystemTime) -> DnsAnalyticsSnapshot {
170        self.advance(now);
171
172        let mut snapshot = DnsAnalyticsSnapshot {
173            pending: self.pending.len(),
174            truncated: self.truncated_at.is_some(),
175            ..DnsAnalyticsSnapshot::default()
176        };
177        let mut latencies = Vec::new();
178        let mut questions: HashMap<(String, Option<DnsQueryType>), QuestionAggregate> =
179            HashMap::new();
180        let mut normal_responses = 0usize;
181        let mut failures = 0usize;
182
183        for transaction in &self.completed {
184            if transaction.timed_out {
185                snapshot.timeouts += 1;
186            } else {
187                snapshot.answered += 1;
188                match transaction.rcode {
189                    Some(0) => snapshot.noerror += 1,
190                    Some(2) => snapshot.servfail += 1,
191                    Some(3) => snapshot.nxdomain += 1,
192                    Some(5) => snapshot.refused += 1,
193                    _ => snapshot.other_rcodes += 1,
194                }
195                if transaction.nodata {
196                    snapshot.nodata += 1;
197                }
198            }
199
200            if transaction.is_normal_response() {
201                normal_responses += 1;
202            } else {
203                failures += 1;
204            }
205
206            if let Some(latency) = transaction.latency {
207                latencies.push(latency);
208                let bucket = if latency < Duration::from_millis(10) {
209                    0
210                } else if latency < Duration::from_millis(50) {
211                    1
212                } else if latency < Duration::from_millis(100) {
213                    2
214                } else {
215                    3
216                };
217                snapshot.latency_buckets[bucket] += 1;
218            }
219
220            if let Some(name) = &transaction.query_name {
221                let aggregate = questions
222                    .entry((name.clone(), transaction.query_type))
223                    .or_default();
224                aggregate.lookups += 1;
225                if transaction.rcode == Some(3) {
226                    aggregate.nxdomain += 1;
227                }
228                if transaction.is_failure() {
229                    aggregate.failures += 1;
230                }
231                if let Some(latency) = transaction.latency {
232                    aggregate.latencies.push(latency);
233                }
234            }
235        }
236
237        snapshot.lookups = self.completed.len() + snapshot.pending;
238        snapshot.failures = failures;
239        latencies.sort_unstable();
240        snapshot.latency_samples = latencies.len();
241        snapshot.latency_p50 = percentile(&latencies, 50);
242        snapshot.latency_p95 = percentile(&latencies, 95);
243        snapshot.latency_max = latencies.last().copied();
244
245        snapshot.questions = questions
246            .into_iter()
247            .map(|((name, query_type), mut aggregate)| {
248                aggregate.latencies.sort_unstable();
249                DnsQuestionStats {
250                    name,
251                    query_type,
252                    lookups: aggregate.lookups,
253                    nxdomain: aggregate.nxdomain,
254                    failures: aggregate.failures,
255                    latency_p95: percentile(&aggregate.latencies, 95),
256                }
257            })
258            .collect();
259        snapshot.questions.sort_unstable_by(|a, b| {
260            b.lookups
261                .cmp(&a.lookups)
262                .then_with(|| a.name.cmp(&b.name))
263                .then_with(|| {
264                    a.query_type
265                        .map(|value| value.to_string())
266                        .cmp(&b.query_type.map(|value| value.to_string()))
267                })
268        });
269
270        snapshot.health = classify_health(HealthInputs {
271            lookups: snapshot.lookups,
272            pending: snapshot.pending,
273            finalized: self.completed.len(),
274            answered: snapshot.answered,
275            timeouts: snapshot.timeouts,
276            normal_responses,
277            failures,
278            latency_samples: snapshot.latency_samples,
279            latency_p95: snapshot.latency_p95,
280        });
281        snapshot
282    }
283
284    pub(crate) fn clear(&mut self) {
285        self.pending.clear();
286        self.completed.clear();
287        self.truncated_at = None;
288    }
289
290    fn advance(&mut self, now: SystemTime) {
291        let pending_cutoff = now.checked_sub(DNS_TRANSACTION_TIMEOUT);
292        let expired: Vec<TransactionKey> = pending_cutoff.map_or_else(Vec::new, |cutoff| {
293            self.pending
294                .iter()
295                .filter_map(|(key, pending)| (pending.sent_at <= cutoff).then_some(*key))
296                .collect()
297        });
298        for key in expired {
299            if let Some(pending) = self.pending.remove(&key) {
300                let completed_at = pending
301                    .sent_at
302                    .checked_add(DNS_TRANSACTION_TIMEOUT)
303                    .unwrap_or(now);
304                self.push_completed(CompletedTransaction {
305                    completed_at,
306                    query_name: pending.query_name,
307                    query_type: pending.query_type,
308                    rcode: None,
309                    nodata: false,
310                    latency: None,
311                    timed_out: true,
312                });
313            }
314        }
315
316        let transaction_cutoff = now.checked_sub(DNS_ANALYTICS_WINDOW);
317        if let Some(cutoff) = transaction_cutoff {
318            self.completed
319                .retain(|transaction| transaction.completed_at > cutoff);
320            if self.truncated_at.is_some_and(|at| at <= cutoff) {
321                self.truncated_at = None;
322            }
323        }
324    }
325
326    fn push_completed(&mut self, transaction: CompletedTransaction) {
327        if self.completed.len() >= MAX_RETAINED_DNS_TRANSACTIONS {
328            self.completed.pop_front();
329            self.mark_truncated(transaction.completed_at);
330        }
331        self.completed.push_back(transaction);
332    }
333
334    fn mark_truncated(&mut self, at: SystemTime) {
335        if self.truncated_at.is_none_or(|previous| at > previous) {
336            self.truncated_at = Some(at);
337        }
338    }
339}
340
341fn normalize_query_name(name: Option<&str>) -> Option<String> {
342    let name = name?.trim_end_matches('.');
343    (!name.is_empty()).then(|| name.to_ascii_lowercase())
344}
345
346fn percentile(sorted: &[Duration], percent: usize) -> Option<Duration> {
347    if sorted.is_empty() {
348        return None;
349    }
350    let rank = sorted
351        .len()
352        .saturating_mul(percent)
353        .div_ceil(100)
354        .saturating_sub(1)
355        .min(sorted.len() - 1);
356    sorted.get(rank).copied()
357}
358
359struct HealthInputs {
360    lookups: usize,
361    pending: usize,
362    finalized: usize,
363    answered: usize,
364    timeouts: usize,
365    normal_responses: usize,
366    failures: usize,
367    latency_samples: usize,
368    latency_p95: Option<Duration>,
369}
370
371fn classify_health(inputs: HealthInputs) -> DnsHealth {
372    if inputs.lookups == 0 {
373        return DnsHealth::NotObserved;
374    }
375    if inputs.answered == 0 && inputs.timeouts >= 3 {
376        return DnsHealth::NoReplies;
377    }
378    if inputs.finalized >= 3 && inputs.normal_responses == 0 {
379        return DnsHealth::Failing;
380    }
381    let failure_degraded = inputs.finalized >= 5
382        && inputs.failures.saturating_mul(100)
383            >= inputs.finalized.saturating_mul(DEGRADED_FAILURE_PERCENT);
384    let latency_degraded =
385        inputs.latency_samples >= 5 && inputs.latency_p95.is_some_and(|p95| p95 >= DEGRADED_P95);
386    if inputs.normal_responses > 0 && (failure_degraded || latency_degraded) {
387        return DnsHealth::Degraded;
388    }
389    if inputs.normal_responses > 0 {
390        return DnsHealth::Responsive;
391    }
392    if inputs.pending > 0 || inputs.finalized < 3 {
393        return DnsHealth::Checking;
394    }
395    DnsHealth::Failing
396}
397
398#[cfg(test)]
399mod tests {
400    use super::*;
401    use crate::network::types::Protocol;
402    use std::net::{IpAddr, Ipv4Addr, SocketAddr};
403
404    fn time(ms: u64) -> SystemTime {
405        SystemTime::UNIX_EPOCH + Duration::from_millis(ms)
406    }
407
408    fn connection() -> ConnectionKey {
409        ConnectionKey::new(
410            Protocol::Udp,
411            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 10)), 53000),
412            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(1, 1, 1, 1)), 53),
413        )
414    }
415
416    fn dns(
417        name: &str,
418        query_type: DnsQueryType,
419        txid: u16,
420        is_response: bool,
421        rcode: Option<u8>,
422    ) -> DnsInfo {
423        DnsInfo {
424            query_name: Some(name.to_string()),
425            query_type: Some(query_type),
426            response_ips: Vec::new(),
427            is_response,
428            txid,
429            rcode,
430            nodata: (is_response && rcode == Some(0)).then_some(false),
431        }
432    }
433
434    fn complete(
435        tracker: &mut DnsAnalyticsTracker,
436        txid: u16,
437        name: &str,
438        rcode: u8,
439        sent_ms: u64,
440        latency_ms: u64,
441    ) {
442        let query = dns(name, DnsQueryType::A, txid, false, None);
443        tracker.record_packet(connection(), &query, true, time(sent_ms), None);
444        let response = dns(name, DnsQueryType::A, txid, true, Some(rcode));
445        tracker.record_packet(
446            connection(),
447            &response,
448            false,
449            time(sent_ms + latency_ms),
450            Some(Duration::from_millis(latency_ms)),
451        );
452    }
453
454    #[test]
455    fn repeated_socket_transactions_remain_distinct() {
456        let mut tracker = DnsAnalyticsTracker::default();
457        complete(&mut tracker, 1, "Example.COM.", 0, 0, 12);
458        complete(&mut tracker, 2, "example.com", 3, 100, 25);
459
460        let snapshot = tracker.snapshot(time(200));
461        assert_eq!(snapshot.lookups, 2);
462        assert_eq!(snapshot.answered, 2);
463        assert_eq!(snapshot.noerror, 1);
464        assert_eq!(snapshot.nxdomain, 1);
465        assert_eq!(snapshot.latency_p50, Some(Duration::from_millis(12)));
466        assert_eq!(snapshot.latency_p95, Some(Duration::from_millis(25)));
467        assert_eq!(snapshot.questions.len(), 1);
468        assert_eq!(snapshot.questions[0].name, "example.com");
469        assert_eq!(snapshot.questions[0].lookups, 2);
470        assert_eq!(snapshot.questions[0].nxdomain, 1);
471        assert_eq!(snapshot.health, DnsHealth::Responsive);
472    }
473
474    #[test]
475    fn retransmission_refreshes_one_logical_lookup() {
476        let mut tracker = DnsAnalyticsTracker::default();
477        let query = dns("example.com", DnsQueryType::AAAA, 7, false, None);
478        tracker.record_packet(connection(), &query, true, time(0), None);
479        tracker.record_packet(connection(), &query, true, time(1_000), None);
480        let response = dns("example.com", DnsQueryType::AAAA, 7, true, Some(0));
481        tracker.record_packet(
482            connection(),
483            &response,
484            false,
485            time(1_020),
486            Some(Duration::from_millis(20)),
487        );
488
489        let snapshot = tracker.snapshot(time(1_100));
490        assert_eq!(snapshot.lookups, 1);
491        assert_eq!(snapshot.answered, 1);
492        assert_eq!(snapshot.pending, 0);
493    }
494
495    #[test]
496    fn three_expired_queries_report_no_replies() {
497        let mut tracker = DnsAnalyticsTracker::default();
498        for txid in 1..=3 {
499            let query = dns(
500                &format!("name{txid}.example"),
501                DnsQueryType::A,
502                txid,
503                false,
504                None,
505            );
506            tracker.record_packet(connection(), &query, true, time(0), None);
507        }
508
509        let snapshot = tracker.snapshot(time(10_001));
510        assert_eq!(snapshot.timeouts, 3);
511        assert_eq!(snapshot.health, DnsHealth::NoReplies);
512    }
513
514    #[test]
515    fn operational_failures_degrade_but_nxdomain_does_not() {
516        let mut degraded = DnsAnalyticsTracker::default();
517        for txid in 1..=4 {
518            complete(&mut degraded, txid, "ok.example", 0, u64::from(txid), 10);
519        }
520        complete(&mut degraded, 5, "bad.example", 2, 10, 10);
521        assert_eq!(degraded.snapshot(time(100)).health, DnsHealth::Degraded);
522
523        let mut negative = DnsAnalyticsTracker::default();
524        for txid in 1..=5 {
525            complete(
526                &mut negative,
527                txid,
528                "missing.example",
529                3,
530                u64::from(txid),
531                10,
532            );
533        }
534        assert_eq!(negative.snapshot(time(100)).health, DnsHealth::Responsive);
535    }
536
537    #[test]
538    fn completed_transactions_leave_the_rolling_window() {
539        let mut tracker = DnsAnalyticsTracker::default();
540        complete(&mut tracker, 1, "old.example", 0, 0, 10);
541        assert_eq!(tracker.snapshot(time(1_000)).lookups, 1);
542        assert_eq!(tracker.snapshot(time(60_011)).lookups, 0);
543    }
544
545    #[test]
546    fn sampled_indicator_leaves_the_rolling_window() {
547        let mut tracker = DnsAnalyticsTracker::default();
548        tracker.mark_truncated(time(0));
549        assert!(tracker.snapshot(time(1_000)).truncated);
550        assert!(!tracker.snapshot(time(60_001)).truncated);
551    }
552}