Skip to main content

rustnet_core/network/
tracker.rs

1//! Live connection tracking.
2//!
3//! [`ConnectionTracker`] folds parsed packets into a long-lived, lifecycle-
4//! managed table of [`Connection`]s. It owns everything needed to turn a stream
5//! of [`ParsedPacket`]s into the same connection view the `rustnet` TUI shows:
6//! the active table, an archive of recently-closed ("historic") connections,
7//! RTT estimation from TCP, QUIC handshakes, and ICMP echo, plus DNS-shaped
8//! response timing, QUIC connection-ID coalescing, and timeout-based cleanup,
9//! all without any UI, capture, or process-lookup
10//! dependency.
11//!
12//! This is the piece that makes headless tools easy: pair a capture source with
13//! a parser, then feed each parsed packet to [`ConnectionTracker::ingest_at`]
14//! and periodically call [`ConnectionTracker::cleanup`]. A Prometheus exporter,
15//! a pcap post-processor, or a test harness can all reuse the exact connection
16//! semantics of the main application. Offline consumers replaying a saved trace
17//! should pass each packet's capture timestamp so connection lifetimes and
18//! timeouts follow trace time rather than the replay wall clock.
19//!
20//! ```no_run
21//! use rustnet_core::network::parser::PacketParser;
22//! use rustnet_core::network::tracker::ConnectionTracker;
23//! use std::time::SystemTime;
24//!
25//! let parser = PacketParser::new();
26//! let tracker = ConnectionTracker::new();
27//! # let frames: Vec<Vec<u8>> = Vec::new();
28//! for frame in frames {
29//!     if let Some(parsed) = parser.parse_packet(&frame) {
30//!         tracker.ingest_at(&parsed, SystemTime::now());
31//!     }
32//! }
33//! tracker.cleanup(SystemTime::now()); // expire idle/closed connections
34//! for entry in tracker.connections().iter() {
35//!     let conn = entry.value();
36//!     println!("{} {} -> {}", conn.protocol, conn.local_addr, conn.remote_addr);
37//! }
38//! ```
39//!
40//! All methods take `&self` (the internal tables use interior mutability), so a
41//! single tracker can be wrapped in an [`std::sync::Arc`] and shared across a
42//! capture thread, a cleanup thread, and a reader thread.
43
44use crate::network::dns_analytics::{DnsAnalyticsSnapshot, DnsAnalyticsTracker};
45use crate::network::dns_attribution::DnsAttributionCache;
46use crate::network::merge::{
47    TcpMergeEvents, create_connection_from_packet, merge_packet_into_connection,
48};
49use crate::network::neighbors::{NeighborCache, NeighborEntry};
50use crate::network::parser::ParsedPacket;
51use crate::network::types::{
52    ApplicationProtocol, AttributionSource, Connection, ConnectionKey, Protocol, ProtocolState,
53    QuicPacketType, RequestHealthEvents, RttTracker,
54};
55use dashmap::DashMap;
56use rustc_hash::FxBuildHasher;
57use std::collections::HashMap;
58use std::sync::atomic::{AtomicUsize, Ordering};
59use std::sync::{Mutex, RwLock};
60use std::time::{Duration, SystemTime};
61
62/// Recently archived TCP tuples remain tombstoned briefly so delayed teardown
63/// packets do not create phantom established connections.
64const RECENTLY_CLOSED_TTL: Duration = Duration::from_secs(30);
65
66/// Tombstone capacity floor. `max_historic` sizes the user-facing archive,
67/// but tombstones guard correctness, so a tiny or zero `max_historic` must
68/// not strip them and reopen the phantom-connection window. Entries are a
69/// key and a timestamp; the TTL above bounds how long any of them live.
70const RECENTLY_CLOSED_MIN_ENTRIES: usize = 1024;
71
72/// Whether a QUIC packet belongs to the handshake exchange that RTT timing
73/// pairs up.
74///
75/// 0-RTT is deliberately excluded: it is client-only application data sent
76/// alongside the Initial, so treating it as a fresh send would restart the
77/// timer and report a fraction of the real round trip. 1-RTT packets carry a
78/// short header and reveal nothing to time against.
79fn is_quic_handshake_packet(packet_type: QuicPacketType) -> bool {
80    matches!(
81        packet_type,
82        QuicPacketType::Initial
83            | QuicPacketType::Handshake
84            | QuicPacketType::Retry
85            | QuicPacketType::VersionNegotiation
86    )
87}
88
89/// Whether a UDP packet's DPI classification is one the RTT tracker times.
90/// Gates the RTT lock in `measure_timings` so untimed UDP traffic (QUIC 1-RTT
91/// bulk data, SSDP, mDNS, ...) never touches the mutex on the packet path.
92fn udp_application_is_timed(application: &ApplicationProtocol) -> bool {
93    match application {
94        ApplicationProtocol::Quic(quic) => is_quic_handshake_packet(quic.packet_type),
95        ApplicationProtocol::Dns(_)
96        | ApplicationProtocol::Llmnr(_)
97        | ApplicationProtocol::NetBios(_)
98        | ApplicationProtocol::Stun(_)
99        | ApplicationProtocol::Ntp(_) => true,
100        _ => false,
101    }
102}
103
104/// The active connection table: flow key -> connection.
105///
106/// Keys are compact `Copy` structs, and the map uses FxHash; with a small
107/// fixed-size key, hashing is a handful of multiplies instead of SipHash over
108/// a formatted string. (Hash-flooding resistance isn't needed here: the table
109/// is bounded by `max_connections` and keyed by addresses, not attacker-chosen
110/// bytes of arbitrary length.)
111pub type ConnectionMap = DashMap<ConnectionKey, Connection, FxBuildHasher>;
112
113/// The historic (recently-closed) connection table.
114pub type HistoricMap = DashMap<HistoricKey, Connection, FxBuildHasher>;
115
116/// Identity of an archived (closed) connection: the flow key plus the
117/// connection's creation time, so multiple closed connections that reused the
118/// same 4-tuple don't clobber each other. (Replaces the former
119/// `"<key>:<created_at_nanos>"` string suffix.)
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
121pub struct HistoricKey {
122    pub key: ConnectionKey,
123    pub created_nanos: u128,
124}
125
126impl HistoricKey {
127    /// The identity `conn` has (or will have) in the historic table.
128    pub fn for_connection(key: ConnectionKey, conn: &Connection) -> Self {
129        Self {
130            key,
131            created_nanos: conn
132                .created_at
133                .duration_since(SystemTime::UNIX_EPOCH)
134                .unwrap_or_default()
135                .as_nanos(),
136        }
137    }
138}
139
140impl std::fmt::Display for HistoricKey {
141    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
142        write!(f, "{}:{}", self.key, self.created_nanos)
143    }
144}
145
146/// Tuning knobs for a [`ConnectionTracker`].
147#[derive(Debug, Clone)]
148pub struct TrackerConfig {
149    /// Maximum number of concurrent active connections. New connections beyond
150    /// this limit are dropped (existing ones still update) to bound memory
151    /// under port scans or connection floods.
152    pub max_connections: usize,
153    /// Maximum number of recently-closed ("historic") connections retained.
154    /// Oldest-closed entries are evicted first.
155    pub max_historic: usize,
156    /// Maximum number of QUIC connection-ID -> connection-key mappings kept for
157    /// coalescing migrated QUIC connections. Cleared wholesale when exceeded.
158    pub max_quic_mappings: usize,
159    /// Whether [`ConnectionTracker::cleanup`] archives removed connections into
160    /// the historic table. Headless tools that don't need a closed-connection
161    /// view can set this to `false` to save memory.
162    pub keep_historic: bool,
163    /// Whether connections without an authoritative hostname (TLS SNI or HTTP
164    /// `Host:`) are tagged with the name from a DNS response observed on the
165    /// wire shortly before the connection appeared. Purely passive; consumers
166    /// that don't display hostnames can set this to `false`.
167    pub dns_attribution: bool,
168}
169
170impl Default for TrackerConfig {
171    fn default() -> Self {
172        Self {
173            max_connections: 50_000,
174            max_historic: 5_000,
175            max_quic_mappings: 10_000,
176            keep_historic: true,
177            dns_attribution: true,
178        }
179    }
180}
181
182/// What happened when a packet was ingested via
183/// [`ingest_at`](ConnectionTracker::ingest_at).
184///
185/// Returned so callers can layer their own concerns (global statistics,
186/// structured logging, DNS enrichment) on top of the core table update without
187/// the tracker needing to know about them.
188#[derive(Debug, Clone)]
189pub struct IngestOutcome {
190    /// The (possibly QUIC-coalesced) key under which the connection is stored.
191    /// `Copy`, and its `Display` form matches the historical string key
192    /// (`"TCP:1.2.3.4:80-TCP:5.6.7.8:443"`).
193    pub key: ConnectionKey,
194    /// `true` if this packet created a new connection entry.
195    pub created: bool,
196    /// `true` if the packet was dropped because `max_connections` was reached
197    /// (the connection did not already exist and was not inserted).
198    pub dropped: bool,
199    /// `true` when a delayed packet matched a recently archived TCP tuple and
200    /// was intentionally not turned into a new active connection.
201    pub ignored_late: bool,
202    /// Previous live generation archived by a strong new-session signal.
203    /// Historic storage receives an immutable snapshot of this connection.
204    pub archived: Option<Connection>,
205    /// New TCP retransmissions detected by this packet.
206    pub retransmits: u64,
207    /// New out-of-order TCP segments detected by this packet.
208    pub out_of_order: u64,
209    /// New TCP fast-retransmits detected by this packet.
210    pub fast_retransmits: u64,
211    /// An RTT sample, if this packet completed a handshake round trip: a TCP
212    /// SYN-ACK matching a prior SYN, or a QUIC handshake packet answering one
213    /// sent the other way.
214    pub measured_rtt: Option<Duration>,
215    /// The latest completed DNS query→response round trip, if this packet was
216    /// a response matching a pending query by transaction ID.
217    pub dns_response_time: Option<Duration>,
218    /// The first completed LLMNR query-to-response round trip, if this packet
219    /// was a response matching a pending multicast query by transaction ID.
220    pub llmnr_response_time: Option<Duration>,
221    /// The latest completed NetBIOS request-to-response round trip, if this
222    /// packet matched a pending request by transaction ID.
223    pub netbios_response_time: Option<Duration>,
224    /// The latest completed ICMP echo round trip, if this packet was a reply
225    /// matching an outgoing request by identifier and sequence number.
226    pub icmp_echo_rtt: Option<Duration>,
227    /// The latest completed STUN request→response round trip, if this packet
228    /// was a response matching a pending request by transaction ID.
229    pub stun_rtt: Option<Duration>,
230    /// The latest completed NTP request→response round trip, if this packet
231    /// was a server response echoing a pending client transmit timestamp.
232    pub ntp_rtt: Option<Duration>,
233}
234
235/// Timing measurements extracted from one packet, carried together through
236/// the connection-table update into the resulting [`IngestOutcome`].
237#[derive(Clone, Copy, Default)]
238struct PacketTimings {
239    measured_rtt: Option<Duration>,
240    dns_response_time: Option<Duration>,
241    llmnr_response_time: Option<Duration>,
242    netbios_response_time: Option<Duration>,
243    icmp_echo_rtt: Option<Duration>,
244    stun_rtt: Option<Duration>,
245    ntp_rtt: Option<Duration>,
246}
247
248impl PacketTimings {
249    /// An [`IngestOutcome`] carrying these timings, with every other field at
250    /// its quiescent value for the caller to override via struct update.
251    fn outcome(self, key: ConnectionKey) -> IngestOutcome {
252        IngestOutcome {
253            key,
254            created: false,
255            dropped: false,
256            ignored_late: false,
257            archived: None,
258            retransmits: 0,
259            out_of_order: 0,
260            fast_retransmits: 0,
261            measured_rtt: self.measured_rtt,
262            dns_response_time: self.dns_response_time,
263            llmnr_response_time: self.llmnr_response_time,
264            netbios_response_time: self.netbios_response_time,
265            icmp_echo_rtt: self.icmp_echo_rtt,
266            stun_rtt: self.stun_rtt,
267            ntp_rtt: self.ntp_rtt,
268        }
269    }
270}
271
272/// Stamp any round trips this packet completed onto its connection.
273fn apply_timings(conn: &mut Connection, timings: &PacketTimings) {
274    if let Some(rtt) = timings.measured_rtt
275        && conn.initial_rtt.is_none()
276    {
277        conn.initial_rtt = Some(rtt);
278    }
279    // Last-wins, unlike `initial_rtt`: each completed query refreshes the
280    // displayed response time.
281    if let Some(rtt) = timings.dns_response_time {
282        conn.dns_response_time = Some(rtt);
283    }
284    if let Some(rtt) = timings.llmnr_response_time {
285        conn.llmnr_response_time = Some(rtt);
286    }
287    if let Some(rtt) = timings.netbios_response_time {
288        conn.netbios_response_time = Some(rtt);
289    }
290    if let Some(rtt) = timings.icmp_echo_rtt {
291        conn.icmp_echo_rtt = Some(rtt);
292    }
293    if let Some(rtt) = timings.stun_rtt {
294        conn.stun_rtt = Some(rtt);
295    }
296    if let Some(rtt) = timings.ntp_rtt {
297        conn.ntp_rtt = Some(rtt);
298    }
299}
300
301/// Count explicit QUIC health signals and mark outgoing timed requests.
302fn apply_observed_protocol_health(conn: &mut Connection, parsed: &ParsedPacket) {
303    let Some(dpi) = parsed.dpi_result.as_ref() else {
304        return;
305    };
306    match &dpi.application {
307        ApplicationProtocol::Quic(quic) => match quic.packet_type {
308            QuicPacketType::Retry => {
309                conn.protocol_health.quic_retry_count =
310                    conn.protocol_health.quic_retry_count.saturating_add(1);
311            }
312            QuicPacketType::VersionNegotiation => {
313                conn.protocol_health.quic_version_negotiation_count = conn
314                    .protocol_health
315                    .quic_version_negotiation_count
316                    .saturating_add(1);
317            }
318            _ => {}
319        },
320        ApplicationProtocol::Dns(info) if parsed.is_outgoing && !info.is_response => {
321            conn.protocol_health.request_observed = true;
322        }
323        ApplicationProtocol::Llmnr(info) if parsed.is_outgoing && !info.is_response => {
324            conn.protocol_health.request_observed = true;
325        }
326        ApplicationProtocol::NetBios(info) if parsed.is_outgoing && info.is_request() => {
327            conn.protocol_health.request_observed = true;
328        }
329        ApplicationProtocol::Stun(info)
330            if parsed.is_outgoing
331                && info.message_class == crate::network::types::StunMessageClass::Request =>
332        {
333            conn.protocol_health.request_observed = true;
334        }
335        ApplicationProtocol::Ntp(info)
336            if parsed.is_outgoing && info.mode == crate::network::types::NtpMode::Client =>
337        {
338            conn.protocol_health.request_observed = true;
339        }
340        _ => {}
341    }
342}
343
344/// A live, lifecycle-managed table of network connections built from parsed
345/// packets. See the [module docs](self) for the intended usage.
346pub struct ConnectionTracker {
347    connections: ConnectionMap,
348    historic: HistoricMap,
349    /// Coordinates moves between the active and historic maps with readers
350    /// that need one consistent retained-connection view.
351    lifecycle: RwLock<()>,
352    rtt: Mutex<RttTracker>,
353    dns_analytics: Mutex<DnsAnalyticsTracker>,
354    quic_map: Mutex<HashMap<String, ConnectionKey>>,
355    recently_closed: Mutex<HashMap<ConnectionKey, SystemTime>>,
356    config: TrackerConfig,
357    /// Active-connection count maintained by `ingest_at`/`cleanup`/`clear`.
358    /// Lets the per-packet `max_connections` check be a single atomic load
359    /// instead of a `DashMap::len()` (which read-locks every shard) plus an
360    /// extra `contains_key` lookup. May transiently lag `connections.len()`
361    /// by a few entries under concurrent ingest near the limit, acceptable
362    /// for a flood-protection bound.
363    active_count: AtomicUsize,
364    /// IP -> MAC/vendor mappings learned passively from ingested ARP (IPv4)
365    /// and NDP (IPv6) packets. Outlives the connections themselves, so LAN
366    /// peers stay identified after their ARP/NDP rows are cleaned up.
367    neighbors: NeighborCache,
368    /// IP -> domain mappings learned passively from ingested DNS responses,
369    /// used to tag SNI-less connections with a hostname. Fed and drained by
370    /// `ingest_at`, pruned by `cleanup`.
371    dns_attribution: DnsAttributionCache,
372}
373
374impl ConnectionTracker {
375    /// Create a tracker with default configuration.
376    pub fn new() -> Self {
377        Self::with_config(TrackerConfig::default())
378    }
379
380    /// Create a tracker with custom [`TrackerConfig`].
381    pub fn with_config(config: TrackerConfig) -> Self {
382        Self {
383            connections: ConnectionMap::with_hasher(FxBuildHasher),
384            historic: HistoricMap::with_hasher(FxBuildHasher),
385            lifecycle: RwLock::new(()),
386            rtt: Mutex::new(RttTracker::new()),
387            dns_analytics: Mutex::new(DnsAnalyticsTracker::default()),
388            quic_map: Mutex::new(HashMap::new()),
389            recently_closed: Mutex::new(HashMap::new()),
390            config,
391            active_count: AtomicUsize::new(0),
392            neighbors: NeighborCache::default(),
393            dns_attribution: DnsAttributionCache::default(),
394        }
395    }
396
397    /// Fold a parsed packet into the connection table, creating or updating the
398    /// matching connection, stamping the update with the supplied `now`.
399    ///
400    /// Pass the packet's own capture timestamp: for offline processing (pcap
401    /// replay, tests) this keeps `created_at`/`last_activity` and the
402    /// [`cleanup`](Self::cleanup) timeout sweep on trace time rather than the
403    /// replay wall clock. Live callers should also pass each packet's own
404    /// capture timestamp, not one clock read shared across a batch of packets.
405    /// Handshake RTT is the difference between two packets' `now` values, so a
406    /// shared timestamp collapses every round trip that completes within one
407    /// batch to zero.
408    pub fn ingest_at(&self, parsed: &ParsedPacket, now: SystemTime) -> IngestOutcome {
409        // Harvest IP -> MAC mappings from ARP and NDP packets; only they pay
410        // this cost.
411        match &parsed.protocol_state {
412            ProtocolState::Arp(arp_info) => self.neighbors.learn_from_arp(arp_info, now),
413            ProtocolState::Icmp {
414                ndp_neighbor: Some(neighbor),
415                ..
416            } => self.neighbors.learn_from_ndp(neighbor, now),
417            _ => {}
418        }
419
420        let timings = self.measure_timings(parsed, now);
421
422        if parsed.protocol == Protocol::Udp
423            && let Some(dpi) = &parsed.dpi_result
424            && let ApplicationProtocol::Dns(dns) = &dpi.application
425            && let Ok(mut analytics) = self.dns_analytics.lock()
426        {
427            analytics.record_packet(
428                parsed.connection_key(),
429                dns,
430                parsed.is_outgoing,
431                now,
432                timings.dns_response_time,
433            );
434        }
435
436        // Passive DNS attribution: record answered A/AAAA mappings and collect
437        // the connections that were waiting on one of the answered IPs.
438        let waiters = if self.config.dns_attribution
439            && let Some(dpi) = &parsed.dpi_result
440            && let ApplicationProtocol::Dns(dns) = &dpi.application
441            && dns.is_response
442            && !dns.response_ips.is_empty()
443            && let Some(query_name) = &dns.query_name
444        {
445            self.dns_attribution.record_and_drain_pending(
446                query_name,
447                &dns.response_ips,
448                AttributionSource::CapturedDns,
449            )
450        } else {
451            Vec::new()
452        };
453
454        let outcome = self.ingest_update(parsed, now, timings);
455
456        // Tag drained waiters after the table update so the DNS packet's own
457        // row never holds an entry lock while a waiter's row is taken.
458        for waiter_key in waiters {
459            if let Some(mut conn) = self.connections.get_mut(&waiter_key) {
460                self.dns_attribution.attribute(&mut conn, waiter_key);
461            }
462        }
463
464        outcome
465    }
466
467    /// The connection-table update half of [`ingest_at`](Self::ingest_at):
468    /// resolve the key and fold the packet into the active table, splitting
469    /// off a new generation or ignoring a late teardown packet as needed.
470    fn ingest_update(
471        &self,
472        parsed: &ParsedPacket,
473        now: SystemTime,
474        timings: PacketTimings,
475    ) -> IngestOutcome {
476        // A read guard makes ordinary packet updates atomic with cleanup. The
477        // uncommon generation-split path drops it and reacquires a write guard
478        // so retained-source readers also see one consistent move.
479        let lifecycle = self
480            .lifecycle
481            .read()
482            .unwrap_or_else(std::sync::PoisonError::into_inner);
483        let key = self.resolve_connection_key(parsed);
484
485        // Existing flows need one shard lookup and lock, not separate
486        // presence, generation and update lookups. Keep the lifecycle guard
487        // until the update finishes so cleanup cannot archive this generation.
488        if let Some(mut conn) = self.connections.get_mut(&key) {
489            if Self::packet_starts_new_generation(&conn, parsed) {
490                // The split takes the lifecycle write lock and rechecks the
491                // generation. Never retain a shard guard while upgrading.
492                drop(conn);
493                drop(lifecycle);
494                return self.ingest_new_generation(parsed, now, key, timings);
495            }
496
497            let deltas = merge_packet_into_connection(&mut conn, parsed, now);
498            apply_timings(&mut conn, &timings);
499            apply_observed_protocol_health(&mut conn, parsed);
500            drop(conn);
501            return self.finish_ingest(key, timings, false, deltas);
502        }
503
504        if self.is_recent_late_packet(key, parsed, now) {
505            return IngestOutcome {
506                ignored_late: true,
507                ..timings.outcome(key)
508            };
509        }
510
511        // Another ingestion caller can insert after the initial miss. Keep
512        // the slow path's generation check before its entry-based update.
513        let starts_new_generation = self
514            .connections
515            .get(&key)
516            .is_some_and(|conn| Self::packet_starts_new_generation(&conn, parsed));
517        if starts_new_generation {
518            drop(lifecycle);
519            return self.ingest_new_generation(parsed, now, key, timings);
520        }
521
522        self.ingest_into_active(parsed, now, key, timings)
523    }
524
525    /// Run this packet through the RTT tracker and collect any round trips it
526    /// completed.
527    fn measure_timings(&self, parsed: &ParsedPacket, now: SystemTime) -> PacketTimings {
528        // Track RTT for TCP connections using SYN/SYN-ACK timing, and for QUIC
529        // using the long-header handshake exchange. Everything QUIC sends after
530        // the handshake is behind header protection, so this initial flight is
531        // the only round trip an on-path observer can time.
532        let mut measured_rtt: Option<Duration> = None;
533        let mut dns_response_time: Option<Duration> = None;
534        let mut llmnr_response_time: Option<Duration> = None;
535        let mut netbios_response_time: Option<Duration> = None;
536        let mut stun_rtt: Option<Duration> = None;
537        let mut ntp_rtt: Option<Duration> = None;
538        let mut request_health_events = RequestHealthEvents::default();
539        let base_key = parsed.connection_key();
540        if parsed.protocol == Protocol::Tcp
541            && let Some(tcp_header) = &parsed.tcp_header
542        {
543            if tcp_header.flags.syn && !tcp_header.flags.ack {
544                if let Ok(mut tracker) = self.rtt.lock() {
545                    tracker.record_syn(base_key, now);
546                }
547            } else if tcp_header.flags.syn
548                && tcp_header.flags.ack
549                && let Ok(mut tracker) = self.rtt.lock()
550            {
551                measured_rtt = tracker.record_syn_ack(&base_key, now);
552            }
553        } else if parsed.protocol == Protocol::Udp
554            && let Some(dpi) = &parsed.dpi_result
555            && udp_application_is_timed(&dpi.application)
556            && let Ok(mut tracker) = self.rtt.lock()
557        {
558            // One lock acquisition covers every timed UDP application; a
559            // packet carries one DPI result, so at most one arm runs.
560            match &dpi.application {
561                ApplicationProtocol::Quic(_) => {
562                    measured_rtt = tracker.record_quic_handshake(base_key, parsed.is_outgoing, now);
563                }
564                // Time DNS query→response pairs by transaction ID. Port-53
565                // gating already happened in DPI dispatch, so any DNS result
566                // here is unicast DNS (mDNS/LLMNR map to their own variants).
567                ApplicationProtocol::Dns(dns) => {
568                    dns_response_time = tracker.record_dns_packet(
569                        base_key,
570                        dns.txid,
571                        parsed.is_outgoing,
572                        dns.is_response,
573                        now,
574                    );
575                }
576                // LLMNR uses the DNS transaction ID, but sends the query to a
577                // multicast address and receives each response from a unicast
578                // address. The RTT tracker returns the multicast request row
579                // so both views can carry the first response time.
580                ApplicationProtocol::Llmnr(llmnr) => {
581                    let completed =
582                        tracker.record_llmnr_packet(base_key, llmnr, parsed.is_outgoing, now);
583                    if let Some((rtt, request_key)) = completed {
584                        llmnr_response_time = Some(rtt);
585                        self.stamp_request_row_timing(request_key, base_key, |conn| {
586                            conn.llmnr_response_time = Some(rtt);
587                        });
588                    }
589                }
590                // NetBIOS Name Service broadcasts are answered from a host's
591                // unicast address, so the RTT tracker pairs on local socket,
592                // service, and transaction ID rather than the full connection
593                // key.
594                ApplicationProtocol::NetBios(netbios) => {
595                    let completed =
596                        tracker.record_netbios_packet(base_key, netbios, parsed.is_outgoing, now);
597                    if let Some((rtt, request_key)) = completed {
598                        netbios_response_time = Some(rtt);
599                        self.stamp_request_row_timing(request_key, base_key, |conn| {
600                            conn.netbios_response_time = Some(rtt);
601                        });
602                    }
603                }
604                // STUN requests and responses share a 96-bit transaction ID
605                // that retransmits reuse, so request→response pairing is
606                // exact.
607                ApplicationProtocol::Stun(stun) => {
608                    stun_rtt = tracker.record_stun(
609                        base_key,
610                        stun.transaction_id,
611                        parsed.is_outgoing,
612                        stun.message_class,
613                        now,
614                    );
615                }
616                // NTP servers echo the client's transmit timestamp as the
617                // originate timestamp, pairing each poll with its response.
618                ApplicationProtocol::Ntp(ntp) => {
619                    ntp_rtt = tracker.record_ntp(base_key, ntp, parsed.is_outgoing, now);
620                }
621                _ => {}
622            }
623            request_health_events = tracker.take_request_health_events();
624        }
625
626        self.apply_request_health_events(request_health_events);
627
628        // ICMP echo requests reuse one identifier for the life of a ping
629        // process, so sequence number is part of the key. That allows several
630        // subsecond requests to be pending at once and replies to arrive out of
631        // order without cross-pairing samples.
632        let echo_metadata = match &parsed.protocol_state {
633            ProtocolState::Icmp {
634                icmp_type,
635                icmp_id: Some(identifier),
636                icmp_sequence: Some(sequence),
637                ..
638            } => match icmp_type {
639                8 | 128 => Some((*identifier, *sequence, false)),
640                0 | 129 => Some((*identifier, *sequence, true)),
641                _ => None,
642            },
643            _ => None,
644        };
645        let mut icmp_echo_rtt: Option<Duration> = None;
646        if let Some((identifier, sequence, is_reply)) = echo_metadata
647            && let Ok(mut tracker) = self.rtt.lock()
648        {
649            // Loopback captures classify the reply as outgoing too (both
650            // endpoints are local), so reclassify it as incoming to let it
651            // match the pending request.
652            let is_outgoing = parsed.is_outgoing
653                && !(is_reply && parsed.local_addr.ip() == parsed.remote_addr.ip());
654            icmp_echo_rtt = tracker.record_icmp_echo(
655                base_key,
656                (identifier, sequence),
657                is_outgoing,
658                is_reply,
659                now,
660            );
661        }
662
663        PacketTimings {
664            measured_rtt,
665            dns_response_time,
666            llmnr_response_time,
667            netbios_response_time,
668            icmp_echo_rtt,
669            stun_rtt,
670            ntp_rtt,
671        }
672    }
673
674    /// Stamp a completed broadcast or multicast exchange on its request row.
675    /// The response packet's own row is updated later through `PacketTimings`.
676    fn stamp_request_row_timing(
677        &self,
678        request_key: ConnectionKey,
679        response_key: ConnectionKey,
680        stamp: impl FnOnce(&mut Connection),
681    ) {
682        if request_key != response_key
683            && let Some(mut conn) = self.connections.get_mut(&request_key)
684        {
685            stamp(&mut conn);
686        }
687    }
688
689    fn apply_request_health_events(&self, events: RequestHealthEvents) {
690        for key in events.retries {
691            if let Some(mut conn) = self.connections.get_mut(&key) {
692                conn.protocol_health.request_retry_count =
693                    conn.protocol_health.request_retry_count.saturating_add(1);
694            }
695        }
696        for key in events.timeouts {
697            if let Some(mut conn) = self.connections.get_mut(&key) {
698                conn.protocol_health.request_timeout_count =
699                    conn.protocol_health.request_timeout_count.saturating_add(1);
700            }
701        }
702    }
703
704    fn ingest_into_active(
705        &self,
706        parsed: &ParsedPacket,
707        now: SystemTime,
708        key: ConnectionKey,
709        timings: PacketTimings,
710    ) -> IngestOutcome {
711        // Prevent unbounded growth from port scans or connection floods. Only
712        // limit new connections; existing ones always get updated. The fast
713        // path is a single atomic load; only when at the cap do we pay a
714        // lookup to distinguish update-existing from drop-new. (Never call
715        // `len()` here or while holding an entry guard; it read-locks every
716        // shard.)
717        if self.active_count.load(Ordering::Relaxed) >= self.config.max_connections
718            && !self.connections.contains_key(&key)
719        {
720            return IngestOutcome {
721                dropped: true,
722                ..timings.outcome(key)
723            };
724        }
725
726        let mut created = false;
727        let mut deltas = TcpMergeEvents::default();
728        self.connections
729            .entry(key)
730            .and_modify(|conn| {
731                deltas = merge_packet_into_connection(conn, parsed, now);
732                apply_timings(conn, &timings);
733                apply_observed_protocol_health(conn, parsed);
734            })
735            .or_insert_with(|| {
736                created = true;
737                let mut conn = create_connection_from_packet(parsed, now);
738                apply_timings(&mut conn, &timings);
739                apply_observed_protocol_health(&mut conn, parsed);
740                // Attribute a hostname (or enroll for a later DNS response)
741                // at creation. The cache only touches its own maps, so this
742                // is safe under the entry's shard lock.
743                if self.config.dns_attribution {
744                    self.dns_attribution.attribute(&mut conn, key);
745                }
746                conn
747            });
748        if created {
749            self.active_count.fetch_add(1, Ordering::Relaxed);
750        }
751
752        self.finish_ingest(key, timings, created, deltas)
753    }
754
755    /// Finish an update after releasing the connection's shard guard. RTT
756    /// aggregation must not acquire its mutex while a shard is still locked.
757    fn finish_ingest(
758        &self,
759        key: ConnectionKey,
760        timings: PacketTimings,
761        created: bool,
762        deltas: TcpMergeEvents,
763    ) -> IngestOutcome {
764        // Feed completed data round trips into the aggregate view, so the
765        // average RTT reflects established connections rather than only the
766        // handshakes of freshly opened ones.
767        if let Some(rtt) = deltas.rtt_sample
768            && let Ok(mut tracker) = self.rtt.lock()
769        {
770            tracker.record_data_rtt(rtt);
771        }
772
773        IngestOutcome {
774            created,
775            retransmits: deltas.retransmits,
776            out_of_order: deltas.out_of_order,
777            fast_retransmits: deltas.fast_retransmits,
778            ..timings.outcome(key)
779        }
780    }
781
782    fn ingest_new_generation(
783        &self,
784        parsed: &ParsedPacket,
785        now: SystemTime,
786        key: ConnectionKey,
787        timings: PacketTimings,
788    ) -> IngestOutcome {
789        let _lifecycle = self
790            .lifecycle
791            .write()
792            .unwrap_or_else(std::sync::PoisonError::into_inner);
793        let mut replacement_now = now;
794
795        let still_needs_split = self
796            .connections
797            .get(&key)
798            .is_some_and(|conn| Self::packet_starts_new_generation(&conn, parsed));
799        let archived = if still_needs_split {
800            self.connections.remove(&key).map(|(_, conn)| {
801                // Historic keys include `created_at`, so two generations of
802                // the same tuple must not share a creation timestamp. This is
803                // possible when several captured packets use one batch time.
804                // Windows SystemTime stores 100 ns ticks, so a smaller step
805                // would be rounded away instead of producing a distinct key.
806                if replacement_now <= conn.created_at {
807                    replacement_now = conn
808                        .created_at
809                        .checked_add(Duration::from_nanos(100))
810                        .unwrap_or(replacement_now);
811                }
812                self.archive_snapshot(key, &conn, now);
813                self.retire(key, &conn, now);
814                conn
815            })
816        } else {
817            None
818        };
819
820        // Cleanup may have removed the old generation while this packet was
821        // waiting to acquire the write guard. Reassociate any visible QUIC ID
822        // before creating the replacement.
823        self.associate_quic_id(parsed, key);
824        let mut outcome = self.ingest_into_active(parsed, replacement_now, key, timings);
825        outcome.archived = archived;
826        self.enforce_historic_limit();
827        self.prune_recently_closed(now);
828        outcome
829    }
830
831    fn resolve_connection_key(&self, parsed: &ParsedPacket) -> ConnectionKey {
832        let mut key = parsed.connection_key();
833        let Some(conn_id_hex) = Self::parsed_quic_id(parsed) else {
834            return key;
835        };
836        let Ok(mut mapping) = self.quic_map.lock() else {
837            return key;
838        };
839        if let Some(existing_key) = mapping.get(conn_id_hex) {
840            key = *existing_key;
841        } else {
842            if mapping.len() >= self.config.max_quic_mappings {
843                mapping.clear();
844            }
845            mapping.insert(conn_id_hex.to_string(), key);
846        }
847        key
848    }
849
850    fn parsed_quic_id(parsed: &ParsedPacket) -> Option<&str> {
851        let dpi = parsed.dpi_result.as_ref()?;
852        let ApplicationProtocol::Quic(quic) = &dpi.application else {
853            return None;
854        };
855        quic.connection_id_hex.as_deref()
856    }
857
858    fn associate_quic_id(&self, parsed: &ParsedPacket, key: ConnectionKey) {
859        let Some(conn_id_hex) = Self::parsed_quic_id(parsed) else {
860            return;
861        };
862        if let Ok(mut mapping) = self.quic_map.lock() {
863            if mapping.len() >= self.config.max_quic_mappings {
864                mapping.clear();
865            }
866            mapping.insert(conn_id_hex.to_string(), key);
867        }
868    }
869
870    fn packet_starts_new_generation(conn: &Connection, parsed: &ParsedPacket) -> bool {
871        if !conn.is_closing_or_terminal() {
872            return false;
873        }
874        match parsed.protocol {
875            Protocol::Tcp => parsed
876                .tcp_header
877                .as_ref()
878                .is_some_and(|header| header.flags.syn),
879            Protocol::Udp => {
880                let Some(new_id) = Self::parsed_quic_id(parsed) else {
881                    return false;
882                };
883                let Some(dpi) = conn.dpi_info.as_ref() else {
884                    return false;
885                };
886                let ApplicationProtocol::Quic(old_quic) = &dpi.application else {
887                    return false;
888                };
889                old_quic
890                    .connection_id_hex
891                    .as_deref()
892                    .is_some_and(|old_id| old_id != new_id)
893            }
894            _ => false,
895        }
896    }
897
898    fn is_recent_late_packet(
899        &self,
900        key: ConnectionKey,
901        parsed: &ParsedPacket,
902        now: SystemTime,
903    ) -> bool {
904        if parsed.protocol != Protocol::Tcp {
905            return false;
906        }
907        let Some(header) = parsed.tcp_header.as_ref() else {
908            return false;
909        };
910        let is_teardown_only = !header.flags.syn
911            && (header.flags.fin
912                || header.flags.rst
913                || (header.flags.ack && header.payload_len == 0));
914        if !is_teardown_only {
915            return false;
916        }
917        self.recently_closed
918            .lock()
919            .unwrap_or_else(std::sync::PoisonError::into_inner)
920            .get(&key)
921            .is_some_and(|closed_at| {
922                now.duration_since(*closed_at).unwrap_or_default() <= RECENTLY_CLOSED_TTL
923            })
924    }
925
926    /// Archive a historic copy of `conn`, closed at `now`, when
927    /// `keep_historic` is set. The historic key includes created_at so
928    /// multiple closed connections sharing a 4-tuple don't clobber each
929    /// other. snapshot_clone: historic connections never refresh their rates,
930    /// so don't pin the (potentially large) sample buffer in the archive.
931    fn archive_snapshot(&self, key: ConnectionKey, conn: &Connection, now: SystemTime) {
932        if !self.config.keep_historic {
933            return;
934        }
935        let mut historic = conn.snapshot_clone();
936        historic.is_historic = true;
937        historic.closed_at = Some(now);
938        // Cached rates describe live traffic. Carrying them into a closed
939        // record makes Overview and Details report traffic that can no longer
940        // occur, and leaves a moving fallback point after the live rate
941        // history is retired.
942        historic.current_incoming_rate_bps = 0.0;
943        historic.current_outgoing_rate_bps = 0.0;
944        self.historic
945            .insert(HistoricKey::for_connection(key, conn), historic);
946    }
947
948    /// Bookkeeping for a connection that has left the active table: the
949    /// active count, the recently-closed tombstone, its pending
950    /// DNS-attribution enrollment (so a later response cannot surface a dead
951    /// key, and a replacement generation enrolls with a fresh timestamp) and
952    /// any QUIC connection-ID mappings still pointing at it.
953    ///
954    /// Must not be called from inside a `connections` shard lock.
955    fn retire(&self, key: ConnectionKey, conn: &Connection, now: SystemTime) {
956        self.active_count.fetch_sub(1, Ordering::Relaxed);
957        self.record_recently_closed(key, conn, now);
958        self.dns_attribution
959            .forget_pending(conn.remote_addr.ip(), key);
960        self.remove_quic_mappings_for_key(key);
961    }
962
963    fn enforce_historic_limit(&self) {
964        if self.historic.len() <= self.config.max_historic {
965            return;
966        }
967        let mut entries: Vec<(HistoricKey, SystemTime)> = self
968            .historic
969            .iter()
970            .map(|entry| {
971                let closed = entry.value().closed_at.unwrap_or(entry.value().created_at);
972                (*entry.key(), closed)
973            })
974            .collect();
975        entries.sort_by_key(|(_, closed)| *closed);
976        let to_remove = self.historic.len() - self.config.max_historic;
977        for (key, _) in entries.into_iter().take(to_remove) {
978            self.historic.remove(&key);
979        }
980    }
981
982    fn record_recently_closed(&self, key: ConnectionKey, conn: &Connection, now: SystemTime) {
983        if !conn.is_terminal() {
984            return;
985        }
986        self.recently_closed
987            .lock()
988            .unwrap_or_else(std::sync::PoisonError::into_inner)
989            .insert(key, now);
990    }
991
992    fn prune_recently_closed(&self, now: SystemTime) {
993        let mut recently_closed = self
994            .recently_closed
995            .lock()
996            .unwrap_or_else(std::sync::PoisonError::into_inner);
997        recently_closed.retain(|_, closed_at| {
998            now.duration_since(*closed_at).unwrap_or_default() <= RECENTLY_CLOSED_TTL
999        });
1000        let max_entries = self.config.max_historic.max(RECENTLY_CLOSED_MIN_ENTRIES);
1001        if recently_closed.len() > max_entries {
1002            let mut entries: Vec<(ConnectionKey, SystemTime)> = recently_closed
1003                .iter()
1004                .map(|(key, closed_at)| (*key, *closed_at))
1005                .collect();
1006            entries.sort_by_key(|(_, closed_at)| *closed_at);
1007            let to_remove = recently_closed.len() - max_entries;
1008            for (key, _) in entries.into_iter().take(to_remove) {
1009                recently_closed.remove(&key);
1010            }
1011        }
1012    }
1013
1014    fn remove_quic_mappings_for_key(&self, key: ConnectionKey) {
1015        if let Ok(mut mapping) = self.quic_map.lock() {
1016            mapping.retain(|_, conn_key| *conn_key != key);
1017        }
1018    }
1019
1020    /// Remove connections whose protocol-aware timeout has elapsed as of `now`.
1021    ///
1022    /// Removed connections are archived into the historic table (when
1023    /// `keep_historic` is set, subject to `max_historic` eviction) and their
1024    /// QUIC
1025    /// mappings are dropped. Returns the removed connections (in their original,
1026    /// pre-archive form) so callers can emit close events or export them.
1027    pub fn cleanup(&self, now: SystemTime) -> Vec<Connection> {
1028        let _lifecycle = self
1029            .lifecycle
1030            .write()
1031            .unwrap_or_else(std::sync::PoisonError::into_inner);
1032        let request_health_events = self
1033            .rtt
1034            .lock()
1035            .unwrap_or_else(std::sync::PoisonError::into_inner)
1036            .expire_requests(now);
1037        self.apply_request_health_events(request_health_events);
1038        let mut removed: Vec<Connection> = Vec::new();
1039        let mut removed_keys: Vec<ConnectionKey> = Vec::new();
1040
1041        self.connections.retain(|key, conn| {
1042            let should_keep = !conn.should_cleanup(now);
1043            if !should_keep {
1044                removed_keys.push(*key);
1045                removed.push(conn.clone());
1046            }
1047            should_keep
1048        });
1049        // Archive and retire outside the retain closure so no shard lock is
1050        // held while the tracker's other locks are taken.
1051        for (key, conn) in removed_keys.iter().zip(&removed) {
1052            self.archive_snapshot(*key, conn, now);
1053            self.retire(*key, conn, now);
1054        }
1055        self.enforce_historic_limit();
1056        self.prune_recently_closed(now);
1057        self.dns_attribution.cleanup_tick(std::time::Instant::now());
1058
1059        removed
1060    }
1061
1062    /// Inspect the active and historic maps as one consistent retained view.
1063    ///
1064    /// Cleanup cannot move a connection between the maps while `inspect` is
1065    /// running. Packet updates may still update active rows through DashMap's
1066    /// per-entry locking.
1067    pub fn with_retained_sources<R>(
1068        &self,
1069        inspect: impl FnOnce(&ConnectionMap, &HistoricMap) -> R,
1070    ) -> R {
1071        let _lifecycle = self
1072            .lifecycle
1073            .read()
1074            .unwrap_or_else(std::sync::PoisonError::into_inner);
1075        inspect(&self.connections, &self.historic)
1076    }
1077
1078    /// Number of historic (recently-closed) connections.
1079    pub fn historic_len(&self) -> usize {
1080        self.historic.len()
1081    }
1082
1083    /// Return passive DNS analytics for the latest rolling 60-second window.
1084    pub fn dns_analytics_snapshot(&self) -> DnsAnalyticsSnapshot {
1085        self.dns_analytics_snapshot_at(SystemTime::now())
1086    }
1087
1088    /// Return passive DNS analytics relative to a supplied capture time.
1089    /// Offline consumers can use this to keep the window aligned with a
1090    /// replayed trace instead of wall-clock time.
1091    pub fn dns_analytics_snapshot_at(&self, now: SystemTime) -> DnsAnalyticsSnapshot {
1092        self.dns_analytics
1093            .lock()
1094            .unwrap_or_else(std::sync::PoisonError::into_inner)
1095            .snapshot(now)
1096    }
1097
1098    /// Drop all active and historic connections and reset RTT, DNS, QUIC,
1099    /// and learned-neighbor state.
1100    pub fn clear(&self) {
1101        let _lifecycle = self
1102            .lifecycle
1103            .write()
1104            .unwrap_or_else(std::sync::PoisonError::into_inner);
1105        self.connections.clear();
1106        self.active_count.store(0, Ordering::Relaxed);
1107        self.historic.clear();
1108        if let Ok(mut tracker) = self.rtt.lock() {
1109            tracker.clear();
1110        }
1111        if let Ok(mut analytics) = self.dns_analytics.lock() {
1112            analytics.clear();
1113        }
1114        if let Ok(mut mapping) = self.quic_map.lock() {
1115            mapping.clear();
1116        }
1117        self.recently_closed
1118            .lock()
1119            .unwrap_or_else(std::sync::PoisonError::into_inner)
1120            .clear();
1121        self.neighbors.clear();
1122        self.dns_attribution.clear();
1123    }
1124
1125    /// Direct access to the active connection table.
1126    ///
1127    /// Use this for in-place enrichment (e.g. attaching process, DNS, or GeoIP
1128    /// information via `iter_mut`) or custom reads. Lifecycle changes should go
1129    /// through [`ingest_at`](Self::ingest_at) and [`cleanup`](Self::cleanup) so the
1130    /// connection-count limit, RTT, and QUIC coalescing stay consistent;
1131    /// inserting or removing entries directly desyncs the internal counter
1132    /// backing the `max_connections` check.
1133    pub fn connections(&self) -> &ConnectionMap {
1134        &self.connections
1135    }
1136
1137    /// Direct access to the historic (recently-closed) connection table.
1138    pub fn historic(&self) -> &HistoricMap {
1139        &self.historic
1140    }
1141
1142    /// The ARP/NDP-learned MAC/vendor mapping for `ip`, if one has been
1143    /// observed.
1144    pub fn neighbor(&self, ip: &std::net::IpAddr) -> Option<NeighborEntry> {
1145        self.neighbors.get(ip)
1146    }
1147
1148    /// Average network RTT (in milliseconds) over the last `window_secs`
1149    /// seconds of handshake, TCP data, and ICMP echo samples. `None` if no
1150    /// samples are available.
1151    pub fn take_average_rtt(&self, window_secs: u64) -> Option<f64> {
1152        self.rtt
1153            .lock()
1154            .ok()
1155            .and_then(|mut tracker| tracker.take_average_rtt(window_secs))
1156    }
1157}
1158
1159impl Default for ConnectionTracker {
1160    fn default() -> Self {
1161        Self::new()
1162    }
1163}
1164
1165#[cfg(test)]
1166mod tests {
1167    use super::*;
1168    use crate::network::parser::PacketParser;
1169    use crate::network::types::NetBiosOpcode;
1170
1171    impl ConnectionTracker {
1172        /// Wall-clock `ingest_at` shorthand for tests that don't exercise
1173        /// packet timing.
1174        fn ingest(&self, parsed: &ParsedPacket) -> IngestOutcome {
1175            self.ingest_at(parsed, SystemTime::now())
1176        }
1177    }
1178
1179    /// A minimal Ethernet+IPv4+UDP frame, parsed into a `ParsedPacket` so we can
1180    /// exercise the tracker with a realistic input.
1181    fn udp_frame(src_port: u16, dst_port: u16) -> Vec<u8> {
1182        let mut f = Vec::new();
1183        // Ethernet header: dst mac, src mac, ethertype IPv4 (0x0800)
1184        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 1]);
1185        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 2]);
1186        f.extend_from_slice(&[0x08, 0x00]);
1187        // IPv4 header (20 bytes)
1188        let ip_total_len = (20 + 8u16).to_be_bytes(); // IP header + UDP header
1189        f.extend_from_slice(&[0x45, 0x00]);
1190        f.extend_from_slice(&ip_total_len);
1191        f.extend_from_slice(&[0, 0, 0, 0]); // id, flags/frag
1192        f.push(64); // ttl
1193        f.push(17); // protocol = UDP
1194        f.extend_from_slice(&[0, 0]); // checksum
1195        f.extend_from_slice(&[192, 168, 0, 1]); // src ip
1196        f.extend_from_slice(&[192, 168, 0, 2]); // dst ip
1197        // UDP header (8 bytes)
1198        f.extend_from_slice(&src_port.to_be_bytes());
1199        f.extend_from_slice(&dst_port.to_be_bytes());
1200        f.extend_from_slice(&8u16.to_be_bytes()); // length
1201        f.extend_from_slice(&[0, 0]); // checksum
1202        f
1203    }
1204
1205    fn parse(frame: &[u8]) -> ParsedPacket {
1206        PacketParser::new()
1207            .parse_packet(frame)
1208            .expect("frame should parse")
1209    }
1210
1211    fn tcp_packet(syn: bool, ack: bool, fin: bool, rst: bool, is_outgoing: bool) -> ParsedPacket {
1212        use crate::network::protocol::tcp::{TcpFlags, TcpHeaderInfo};
1213        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1214
1215        let mut packet = ParsedPacket::test_tcp(
1216            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1217            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 2)), 443),
1218            TcpHeaderInfo {
1219                seq: 1_000,
1220                ack: 2_000,
1221                window: 65_535,
1222                flags: TcpFlags { syn, ack, fin, rst },
1223                payload_len: 0,
1224                window_scale: None,
1225            },
1226        );
1227        packet.is_outgoing = is_outgoing;
1228        packet.packet_len = 60;
1229        packet
1230    }
1231
1232    fn quic_packet(packet_type: QuicPacketType, is_outgoing: bool) -> ParsedPacket {
1233        use crate::network::types::QuicInfo;
1234        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1235
1236        let mut quic = QuicInfo::new(1);
1237        quic.packet_type = packet_type;
1238
1239        let mut packet = ParsedPacket::test_udp(
1240            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1241            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 2)), 443),
1242            ApplicationProtocol::Quic(Box::new(quic)),
1243        );
1244        packet.is_outgoing = is_outgoing;
1245        packet.packet_len = 1_200;
1246        packet
1247    }
1248
1249    fn dns_packet(txid: u16, is_outgoing: bool, is_response: bool, rcode: u8) -> ParsedPacket {
1250        use crate::network::types::{DnsInfo, DnsQueryType};
1251        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1252
1253        let mut packet = ParsedPacket::test_udp(
1254            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1255            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 2)), 53),
1256            ApplicationProtocol::Dns(DnsInfo {
1257                query_name: Some("example.com".to_string()),
1258                query_type: Some(DnsQueryType::A),
1259                response_ips: Vec::new(),
1260                is_response,
1261                txid,
1262                rcode: is_response.then_some(rcode),
1263                nodata: None,
1264            }),
1265        );
1266        packet.is_outgoing = is_outgoing;
1267        packet.packet_len = 80;
1268        packet
1269    }
1270
1271    fn llmnr_packet(
1272        txid: u16,
1273        is_outgoing: bool,
1274        is_response: bool,
1275        remote_ip: [u8; 4],
1276    ) -> ParsedPacket {
1277        use crate::network::types::{AddrKind, DnsQueryType, LlmnrInfo};
1278        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1279
1280        let mut packet = ParsedPacket::test_udp(
1281            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1282            SocketAddr::new(IpAddr::V4(Ipv4Addr::from(remote_ip)), 5355),
1283            ApplicationProtocol::Llmnr(LlmnrInfo {
1284                query_name: Some("workstation".to_string()),
1285                query_type: Some(DnsQueryType::A),
1286                is_response,
1287                response_ips: Vec::new(),
1288                txid,
1289            }),
1290        );
1291        if remote_ip == [224, 0, 0, 252] {
1292            packet.remote_addr_kind = AddrKind::Multicast;
1293        }
1294        packet.is_outgoing = is_outgoing;
1295        packet.packet_len = 80;
1296        packet
1297    }
1298
1299    /// An outgoing plain UDP packet (no DPI classification) to
1300    /// 203.0.113.80:9999, the flow the attribution tests try to name.
1301    fn plain_udp_packet() -> ParsedPacket {
1302        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1303
1304        let mut packet = ParsedPacket::test_base(
1305            Protocol::Udp,
1306            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1307            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 80)), 9_999),
1308            ProtocolState::Udp,
1309        );
1310        packet.is_outgoing = true;
1311        packet.packet_len = 60;
1312        packet
1313    }
1314
1315    /// An incoming DNS response answering `query_name` with `response_ips`,
1316    /// as the passive attribution path sees it.
1317    fn dns_answer_packet(
1318        txid: u16,
1319        query_name: &str,
1320        response_ips: &[std::net::IpAddr],
1321    ) -> ParsedPacket {
1322        use crate::network::types::{DnsInfo, DnsQueryType};
1323        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1324
1325        let mut packet = ParsedPacket::test_udp(
1326            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
1327            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 2)), 53),
1328            ApplicationProtocol::Dns(DnsInfo {
1329                query_name: Some(query_name.to_string()),
1330                query_type: Some(DnsQueryType::A),
1331                response_ips: response_ips.to_vec(),
1332                is_response: true,
1333                txid,
1334                rcode: Some(0),
1335                nodata: Some(false),
1336            }),
1337        );
1338        packet.is_outgoing = false;
1339        packet.packet_len = 120;
1340        packet
1341    }
1342
1343    fn netbios_packet(
1344        transaction_id: u16,
1345        is_outgoing: bool,
1346        opcode: NetBiosOpcode,
1347        is_response: bool,
1348        remote_ip: [u8; 4],
1349    ) -> ParsedPacket {
1350        use crate::network::types::{AddrKind, NetBiosInfo, NetBiosResponseStatus, NetBiosService};
1351        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1352
1353        let mut packet = ParsedPacket::test_udp(
1354            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 137),
1355            SocketAddr::new(IpAddr::V4(Ipv4Addr::from(remote_ip)), 137),
1356            ApplicationProtocol::NetBios(NetBiosInfo {
1357                service: NetBiosService::NameService,
1358                opcode,
1359                name: Some("FILESERVER".to_string()),
1360                transaction_id,
1361                is_response,
1362                response_status: is_response.then_some(NetBiosResponseStatus::NameService(0)),
1363            }),
1364        );
1365        if remote_ip == [255, 255, 255, 255] {
1366            packet.remote_addr_kind = AddrKind::Broadcast;
1367        }
1368        packet.is_outgoing = is_outgoing;
1369        packet.packet_len = 80;
1370        packet
1371    }
1372
1373    fn icmp_echo_packet(
1374        identifier: u16,
1375        sequence: u16,
1376        is_outgoing: bool,
1377        is_reply: bool,
1378    ) -> ParsedPacket {
1379        use crate::network::types::ProtocolState;
1380        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1381
1382        let mut packet = ParsedPacket::test_base(
1383            Protocol::Icmp,
1384            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 0),
1385            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(8, 8, 8, 8)), 0),
1386            ProtocolState::Icmp {
1387                icmp_type: if is_reply { 0 } else { 8 },
1388                icmp_id: Some(identifier),
1389                icmp_sequence: Some(sequence),
1390                ndp_neighbor: None,
1391            },
1392        );
1393        packet.is_outgoing = is_outgoing;
1394        packet.packet_len = 84;
1395        packet
1396    }
1397
1398    /// Capture time for a packet `millis` into a synthetic trace. Tests drive
1399    /// `ingest_at` with these rather than the wall clock so an RTT assertion
1400    /// pins a real duration instead of however long the test loop took.
1401    fn capture_time(millis: u64) -> SystemTime {
1402        SystemTime::UNIX_EPOCH + Duration::from_secs(1_700_000_000) + Duration::from_millis(millis)
1403    }
1404
1405    fn arp_packet(operation: crate::network::types::ArpOperation) -> ParsedPacket {
1406        use crate::network::types::{ArpInfo, ProtocolState};
1407        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1408
1409        let mut packet = ParsedPacket::test_base(
1410            Protocol::Arp,
1411            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 132)), 0),
1412            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 0),
1413            ProtocolState::Arp(ArpInfo {
1414                operation,
1415                sender_mac: "04:d9:f5:c5:ed:e8".to_string(),
1416                sender_ip: IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)),
1417                target_mac: "68:5e:dd:09:15:5e".to_string(),
1418                target_ip: IpAddr::V4(Ipv4Addr::new(192, 168, 0, 132)),
1419                sender_vendor: Some("ASUSTek COMPUTER INC.".to_string()),
1420                target_vendor: Some("Apple, Inc.".to_string()),
1421            }),
1422        );
1423        packet.packet_len = 42;
1424        packet
1425    }
1426
1427    /// Ingesting an ARP reply must populate the neighbor cache for both the
1428    /// answering host and the requester, and the mapping must outlive the ARP
1429    /// connection row itself.
1430    #[test]
1431    fn arp_ingest_learns_neighbors() {
1432        use crate::network::types::ArpOperation;
1433        use std::net::{IpAddr, Ipv4Addr};
1434
1435        let tracker = ConnectionTracker::new();
1436        let gateway = IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1));
1437        let laptop = IpAddr::V4(Ipv4Addr::new(192, 168, 0, 132));
1438        assert!(tracker.neighbor(&gateway).is_none());
1439
1440        let outcome = tracker.ingest_at(&arp_packet(ArpOperation::Reply), capture_time(0));
1441
1442        let entry = tracker.neighbor(&gateway).expect("gateway learned");
1443        assert_eq!(entry.mac, "04:d9:f5:c5:ed:e8");
1444        assert_eq!(entry.vendor.as_deref(), Some("ASUSTek COMPUTER INC."));
1445        assert_eq!(
1446            tracker.neighbor(&laptop).expect("requester learned").mac,
1447            "68:5e:dd:09:15:5e"
1448        );
1449
1450        // The mapping survives removal of the ARP connection entry.
1451        tracker.connections().remove(&outcome.key);
1452        assert!(tracker.neighbor(&gateway).is_some());
1453    }
1454
1455    /// A full Ethernet+IPv6 frame carrying an NDP neighbor advertisement,
1456    /// so the test exercises the parser's hop-limit gate end to end.
1457    fn ndp_advertisement_frame(hop_limit: u8) -> Vec<u8> {
1458        let mut f = Vec::new();
1459        // Ethernet header: dst mac, src mac, ethertype IPv6 (0x86dd)
1460        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 1]);
1461        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 2]);
1462        f.extend_from_slice(&[0x86, 0xdd]);
1463        // IPv6 header (40 bytes)
1464        f.extend_from_slice(&[0x60, 0, 0, 0]); // version/tc/flow
1465        f.extend_from_slice(&32u16.to_be_bytes()); // payload length
1466        f.push(58); // next header = ICMPv6
1467        f.push(hop_limit);
1468        let src: std::net::Ipv6Addr = "fe80::cafe".parse().unwrap();
1469        let dst: std::net::Ipv6Addr = "ff02::1".parse().unwrap();
1470        f.extend_from_slice(&src.octets());
1471        f.extend_from_slice(&dst.octets());
1472        // ICMPv6 neighbor advertisement: header, target address, then the
1473        // target link-layer address option.
1474        f.extend_from_slice(&[136, 0, 0, 0, 0x20, 0, 0, 0]); // override flag
1475        let target: std::net::Ipv6Addr = "2001:db8::10".parse().unwrap();
1476        f.extend_from_slice(&target.octets());
1477        f.extend_from_slice(&[2, 1, 0x68, 0x5e, 0xdd, 0x09, 0x15, 0x5e]);
1478        f
1479    }
1480
1481    /// Ingesting an NDP neighbor advertisement must populate the neighbor
1482    /// cache for the advertised target address, but only when the frame
1483    /// arrived with hop limit 255, which proves it was not routed (RFC 4861).
1484    #[test]
1485    fn ndp_ingest_learns_advertised_target_at_hop_limit_255_only() {
1486        let target: std::net::IpAddr = "2001:db8::10".parse().unwrap();
1487
1488        let tracker = ConnectionTracker::new();
1489        tracker.ingest_at(&parse(&ndp_advertisement_frame(255)), capture_time(0));
1490        assert_eq!(
1491            tracker.neighbor(&target).expect("target learned").mac,
1492            "68:5e:dd:09:15:5e"
1493        );
1494
1495        let routed = ConnectionTracker::new();
1496        routed.ingest_at(&parse(&ndp_advertisement_frame(64)), capture_time(0));
1497        assert!(routed.neighbor(&target).is_none());
1498    }
1499
1500    /// QUIC's handshake is the only round trip an on-path observer can time,
1501    /// so the client Initial and the server's reply must pair up into the
1502    /// connection's initial RTT the way SYN/SYN-ACK does for TCP.
1503    ///
1504    /// The RTT must come from the packets' capture timestamps. Capture hands
1505    /// packets to processing in batches spanning up to 100 packets or 100ms, so
1506    /// a handshake this quick is processed as one microseconds-wide burst; a
1507    /// tracker that read its own clock would report 0.0ms here.
1508    #[test]
1509    fn quic_handshake_exchange_measures_initial_rtt() {
1510        let tracker = ConnectionTracker::new();
1511
1512        let client_initial =
1513            tracker.ingest_at(&quic_packet(QuicPacketType::Initial, true), capture_time(0));
1514        assert!(
1515            client_initial.measured_rtt.is_none(),
1516            "the opening Initial has nothing to pair with yet"
1517        );
1518
1519        let server_initial = tracker.ingest_at(
1520            &quic_packet(QuicPacketType::Initial, false),
1521            capture_time(18),
1522        );
1523        assert_eq!(
1524            server_initial.measured_rtt,
1525            Some(Duration::from_millis(18)),
1526            "the RTT is the gap between the two capture timestamps"
1527        );
1528        assert_eq!(
1529            tracker
1530                .connections()
1531                .get(&server_initial.key)
1532                .and_then(|conn| conn.initial_rtt),
1533            Some(Duration::from_millis(18)),
1534            "the measured RTT should land on the connection"
1535        );
1536    }
1537
1538    /// A repeated client Initial is a retransmission, not a reply, so it must
1539    /// not be read as a completed round trip.
1540    #[test]
1541    fn repeated_quic_initial_in_one_direction_measures_nothing() {
1542        let tracker = ConnectionTracker::new();
1543        tracker.ingest_at(&quic_packet(QuicPacketType::Initial, true), capture_time(0));
1544        let retransmit = tracker.ingest_at(
1545            &quic_packet(QuicPacketType::Initial, true),
1546            capture_time(250),
1547        );
1548        assert!(retransmit.measured_rtt.is_none());
1549        assert!(
1550            tracker
1551                .connections()
1552                .get(&retransmit.key)
1553                .and_then(|conn| conn.initial_rtt)
1554                .is_none()
1555        );
1556    }
1557
1558    #[test]
1559    fn quic_retry_and_version_negotiation_packets_are_counted() {
1560        let tracker = ConnectionTracker::new();
1561        let retry = tracker.ingest_at(&quic_packet(QuicPacketType::Retry, false), capture_time(0));
1562        tracker.ingest_at(
1563            &quic_packet(QuicPacketType::VersionNegotiation, false),
1564            capture_time(1),
1565        );
1566
1567        let conn = tracker.connections().get(&retry.key).unwrap().clone();
1568        assert_eq!(conn.protocol_health.quic_retry_count, 1);
1569        assert_eq!(conn.protocol_health.quic_version_negotiation_count, 1);
1570    }
1571
1572    /// rustnet watches from an endpoint, so an arriving packet followed by this
1573    /// host's own answer spans no network at all; it times the local stack's
1574    /// turnaround. Only an outbound packet may start the clock.
1575    ///
1576    /// A server's first flight is several datagrams, so this ordering shows up
1577    /// on ordinary connections once the first datagram has been paired off.
1578    #[test]
1579    fn inbound_quic_handshake_packet_does_not_start_the_clock() {
1580        let tracker = ConnectionTracker::new();
1581
1582        tracker.ingest_at(
1583            &quic_packet(QuicPacketType::Handshake, false),
1584            capture_time(0),
1585        );
1586        let local_reply = tracker.ingest_at(
1587            &quic_packet(QuicPacketType::Handshake, true),
1588            capture_time(1),
1589        );
1590        assert!(
1591            local_reply.measured_rtt.is_none(),
1592            "this host's own turnaround is not a round trip"
1593        );
1594        assert!(
1595            tracker
1596                .connections()
1597                .get(&local_reply.key)
1598                .and_then(|conn| conn.initial_rtt)
1599                .is_none()
1600        );
1601    }
1602
1603    /// Once the client Initial has been paired with the server's first
1604    /// datagram, the rest of the server's flight must not overwrite the real
1605    /// measurement with a local-turnaround one.
1606    #[test]
1607    fn later_server_flight_does_not_replace_the_handshake_rtt() {
1608        let tracker = ConnectionTracker::new();
1609
1610        tracker.ingest_at(&quic_packet(QuicPacketType::Initial, true), capture_time(0));
1611        tracker.ingest_at(
1612            &quic_packet(QuicPacketType::Initial, false),
1613            capture_time(18),
1614        );
1615
1616        // Remainder of the server's first flight, then this host's ACK.
1617        tracker.ingest_at(
1618            &quic_packet(QuicPacketType::Handshake, false),
1619            capture_time(19),
1620        );
1621        let ack = tracker.ingest_at(
1622            &quic_packet(QuicPacketType::Handshake, true),
1623            capture_time(19),
1624        );
1625        assert!(ack.measured_rtt.is_none());
1626
1627        assert_eq!(
1628            tracker
1629                .connections()
1630                .get(&ack.key)
1631                .and_then(|conn| conn.initial_rtt),
1632            Some(Duration::from_millis(18))
1633        );
1634    }
1635
1636    /// A DNS response pairs with its query by transaction ID, and the delta
1637    /// between the two capture timestamps lands on the connection. The
1638    /// transport-level `initial_rtt` must stay untouched: DNS time includes
1639    /// resolver processing.
1640    #[test]
1641    fn dns_query_response_measures_response_time() {
1642        let tracker = ConnectionTracker::new();
1643
1644        let query = tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(0));
1645        assert!(query.dns_response_time.is_none());
1646
1647        let response = tracker.ingest_at(&dns_packet(0x1234, false, true, 0), capture_time(35));
1648        assert_eq!(
1649            response.dns_response_time,
1650            Some(Duration::from_millis(35)),
1651            "the response time is the gap between the two capture timestamps"
1652        );
1653        let conn = tracker.connections().get(&response.key).unwrap().clone();
1654        assert_eq!(conn.dns_response_time, Some(Duration::from_millis(35)));
1655        let analytics = tracker.dns_analytics_snapshot_at(capture_time(35));
1656        assert_eq!(analytics.lookups, 1);
1657        assert_eq!(analytics.answered, 1);
1658        assert_eq!(analytics.noerror, 1);
1659        assert_eq!(analytics.latency_p95, Some(Duration::from_millis(35)));
1660        assert!(
1661            conn.initial_rtt.is_none(),
1662            "DNS timing must not pollute the transport RTT"
1663        );
1664    }
1665
1666    /// A response whose transaction ID matches no pending query (spoofed,
1667    /// expired, or captured mid-exchange) measures nothing.
1668    #[test]
1669    fn dns_response_with_unknown_txid_measures_nothing() {
1670        let tracker = ConnectionTracker::new();
1671        tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(0));
1672        let response = tracker.ingest_at(&dns_packet(0x9999, false, true, 0), capture_time(20));
1673        assert!(response.dns_response_time.is_none());
1674        assert!(
1675            tracker
1676                .connections()
1677                .get(&response.key)
1678                .and_then(|conn| conn.dns_response_time)
1679                .is_none()
1680        );
1681    }
1682
1683    /// Stub resolvers reuse one socket for many queries, so each completed
1684    /// exchange refreshes the connection's response time (last wins, unlike
1685    /// the one-shot `initial_rtt`).
1686    #[test]
1687    fn later_dns_exchange_updates_the_response_time() {
1688        let tracker = ConnectionTracker::new();
1689        tracker.ingest_at(&dns_packet(1, true, false, 0), capture_time(0));
1690        tracker.ingest_at(&dns_packet(1, false, true, 0), capture_time(35));
1691        tracker.ingest_at(&dns_packet(2, true, false, 0), capture_time(1_000));
1692        let second = tracker.ingest_at(&dns_packet(2, false, true, 0), capture_time(1_012));
1693        assert_eq!(second.dns_response_time, Some(Duration::from_millis(12)));
1694        assert_eq!(
1695            tracker
1696                .connections()
1697                .get(&second.key)
1698                .and_then(|conn| conn.dns_response_time),
1699            Some(Duration::from_millis(12))
1700        );
1701    }
1702
1703    /// When the local host is the DNS server, the inbound query followed by
1704    /// our own answer times the local resolver's turnaround, not the network,
1705    /// so it must measure nothing (mirrors the QUIC direction rule).
1706    #[test]
1707    fn local_dns_server_role_measures_nothing() {
1708        let tracker = ConnectionTracker::new();
1709        tracker.ingest_at(&dns_packet(0x1234, false, false, 0), capture_time(0));
1710        let reply = tracker.ingest_at(&dns_packet(0x1234, true, true, 0), capture_time(1));
1711        assert!(reply.dns_response_time.is_none());
1712    }
1713
1714    /// A re-sent query restarts the timer from the most recent send, so the
1715    /// measurement reflects the answered attempt, not the retry wait.
1716    #[test]
1717    fn retransmitted_dns_query_measures_from_the_last_send() {
1718        let tracker = ConnectionTracker::new();
1719        let query = tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(0));
1720        tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(1_000));
1721        let response = tracker.ingest_at(&dns_packet(0x1234, false, true, 0), capture_time(1_018));
1722        assert_eq!(response.dns_response_time, Some(Duration::from_millis(18)));
1723
1724        let conn = tracker.connections().get(&query.key).unwrap().clone();
1725        assert!(conn.protocol_health.request_observed);
1726        assert_eq!(conn.protocol_health.request_retry_count, 1);
1727        assert_eq!(conn.protocol_health.request_timeout_count, 0);
1728    }
1729
1730    #[test]
1731    fn unanswered_dns_query_is_counted_as_a_timeout() {
1732        let tracker = ConnectionTracker::new();
1733        let query = tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(0));
1734
1735        tracker.cleanup(capture_time(10_001));
1736
1737        let conn = tracker.connections().get(&query.key).unwrap().clone();
1738        assert!(conn.protocol_health.request_observed);
1739        assert_eq!(conn.protocol_health.request_retry_count, 0);
1740        assert_eq!(conn.protocol_health.request_timeout_count, 1);
1741    }
1742
1743    /// SERVFAIL is still an answer: the round trip completed, so it is a valid
1744    /// timing sample. The response code is surfaced separately in the UI.
1745    #[test]
1746    fn dns_servfail_response_still_measures_response_time() {
1747        let tracker = ConnectionTracker::new();
1748        tracker.ingest_at(&dns_packet(0x1234, true, false, 0), capture_time(0));
1749        let response = tracker.ingest_at(&dns_packet(0x1234, false, true, 2), capture_time(40));
1750        assert_eq!(response.dns_response_time, Some(Duration::from_millis(40)));
1751    }
1752
1753    /// LLMNR sends a query to the link-local multicast group, then each
1754    /// responder replies via unicast. The first reply should time the lookup
1755    /// even though it belongs to a different connection-table key, and that
1756    /// timing should be visible from both rows.
1757    #[test]
1758    fn llmnr_multicast_query_measures_first_unicast_response_time() {
1759        let tracker = ConnectionTracker::new();
1760        let query = tracker.ingest_at(
1761            &llmnr_packet(0x1234, true, false, [224, 0, 0, 252]),
1762            capture_time(0),
1763        );
1764        assert!(query.llmnr_response_time.is_none());
1765
1766        let response = tracker.ingest_at(
1767            &llmnr_packet(0x1234, false, true, [192, 168, 0, 20]),
1768            capture_time(27),
1769        );
1770        assert_ne!(query.key, response.key);
1771        assert_eq!(
1772            response.llmnr_response_time,
1773            Some(Duration::from_millis(27))
1774        );
1775
1776        let response_conn = tracker.connections().get(&response.key).unwrap().clone();
1777        assert_eq!(
1778            response_conn.llmnr_response_time,
1779            Some(Duration::from_millis(27))
1780        );
1781        assert!(response_conn.initial_rtt.is_none());
1782
1783        let query_conn = tracker.connections().get(&query.key).unwrap().clone();
1784        assert_eq!(
1785            query_conn.llmnr_response_time,
1786            Some(Duration::from_millis(27))
1787        );
1788
1789        let second_response = tracker.ingest_at(
1790            &llmnr_packet(0x1234, false, true, [192, 168, 0, 21]),
1791            capture_time(35),
1792        );
1793        assert!(second_response.llmnr_response_time.is_none());
1794        assert!(
1795            tracker
1796                .connections()
1797                .get(&second_response.key)
1798                .and_then(|conn| conn.llmnr_response_time)
1799                .is_none()
1800        );
1801    }
1802
1803    #[test]
1804    fn llmnr_response_with_unknown_transaction_id_measures_nothing() {
1805        let tracker = ConnectionTracker::new();
1806        tracker.ingest_at(
1807            &llmnr_packet(0x1234, true, false, [224, 0, 0, 252]),
1808            capture_time(0),
1809        );
1810        let response = tracker.ingest_at(
1811            &llmnr_packet(0x9999, false, true, [192, 168, 0, 20]),
1812            capture_time(27),
1813        );
1814        assert!(response.llmnr_response_time.is_none());
1815    }
1816
1817    /// Name Service requests are normally broadcast, then answered from a
1818    /// host's unicast address. The transaction still pairs even though the
1819    /// request and response belong to different connection-table keys.
1820    #[test]
1821    fn netbios_broadcast_request_measures_unicast_response_time() {
1822        let tracker = ConnectionTracker::new();
1823        let query = tracker.ingest_at(
1824            &netbios_packet(
1825                0x1234,
1826                true,
1827                NetBiosOpcode::Query,
1828                false,
1829                [255, 255, 255, 255],
1830            ),
1831            capture_time(0),
1832        );
1833        assert!(query.netbios_response_time.is_none());
1834
1835        let response = tracker.ingest_at(
1836            &netbios_packet(
1837                0x1234,
1838                false,
1839                NetBiosOpcode::Response,
1840                true,
1841                [192, 168, 0, 20],
1842            ),
1843            capture_time(27),
1844        );
1845        assert_ne!(query.key, response.key);
1846        assert_eq!(
1847            response.netbios_response_time,
1848            Some(Duration::from_millis(27))
1849        );
1850        let conn = tracker.connections().get(&response.key).unwrap().clone();
1851        assert_eq!(conn.netbios_response_time, Some(Duration::from_millis(27)));
1852        assert!(conn.initial_rtt.is_none());
1853
1854        // The broadcast row is the one a user naturally inspects, so the
1855        // round trip must land there as well, not only on the responder.
1856        let query_conn = tracker.connections().get(&query.key).unwrap().clone();
1857        assert_eq!(
1858            query_conn.netbios_response_time,
1859            Some(Duration::from_millis(27))
1860        );
1861    }
1862
1863    #[test]
1864    fn netbios_response_with_unknown_transaction_id_measures_nothing() {
1865        let tracker = ConnectionTracker::new();
1866        tracker.ingest_at(
1867            &netbios_packet(
1868                0x1234,
1869                true,
1870                NetBiosOpcode::Query,
1871                false,
1872                [255, 255, 255, 255],
1873            ),
1874            capture_time(0),
1875        );
1876        let response = tracker.ingest_at(
1877            &netbios_packet(
1878                0x9999,
1879                false,
1880                NetBiosOpcode::Response,
1881                true,
1882                [192, 168, 0, 20],
1883            ),
1884            capture_time(27),
1885        );
1886        assert!(response.netbios_response_time.is_none());
1887    }
1888
1889    /// A WACK extends an NBNS transaction and must not consume its pending
1890    /// request. The eventual final response completes the original timing.
1891    #[test]
1892    fn netbios_wack_keeps_request_pending() {
1893        let tracker = ConnectionTracker::new();
1894        tracker.ingest_at(
1895            &netbios_packet(
1896                0x1234,
1897                true,
1898                NetBiosOpcode::Registration,
1899                false,
1900                [192, 168, 0, 2],
1901            ),
1902            capture_time(0),
1903        );
1904        let wack = tracker.ingest_at(
1905            &netbios_packet(0x1234, false, NetBiosOpcode::Wack, false, [192, 168, 0, 2]),
1906            capture_time(10),
1907        );
1908        assert!(wack.netbios_response_time.is_none());
1909
1910        let response = tracker.ingest_at(
1911            &netbios_packet(
1912                0x1234,
1913                false,
1914                NetBiosOpcode::Response,
1915                true,
1916                [192, 168, 0, 2],
1917            ),
1918            capture_time(40),
1919        );
1920        assert_eq!(
1921            response.netbios_response_time,
1922            Some(Duration::from_millis(40))
1923        );
1924    }
1925
1926    /// Subsecond ping intervals can leave several requests outstanding. The
1927    /// sequence number keeps each reply attached to its own send timestamp,
1928    /// even when replies complete out of order.
1929    #[test]
1930    fn fast_ping_pairs_each_echo_by_identifier_and_sequence() {
1931        let tracker = ConnectionTracker::new();
1932
1933        tracker.ingest_at(&icmp_echo_packet(0x1234, 1, true, false), capture_time(0));
1934        tracker.ingest_at(&icmp_echo_packet(0x1234, 2, true, false), capture_time(200));
1935        let second_reply =
1936            tracker.ingest_at(&icmp_echo_packet(0x1234, 2, false, true), capture_time(225));
1937        let first_reply =
1938            tracker.ingest_at(&icmp_echo_packet(0x1234, 1, false, true), capture_time(350));
1939
1940        assert_eq!(second_reply.icmp_echo_rtt, Some(Duration::from_millis(25)));
1941        assert_eq!(first_reply.icmp_echo_rtt, Some(Duration::from_millis(350)));
1942
1943        tracker.ingest_at(&icmp_echo_packet(0x1234, 3, true, false), capture_time(400));
1944        let third_reply =
1945            tracker.ingest_at(&icmp_echo_packet(0x1234, 3, false, true), capture_time(418));
1946        let conn = tracker
1947            .connections()
1948            .get(&third_reply.key)
1949            .expect("ping connection should exist")
1950            .clone();
1951        assert_eq!(third_reply.icmp_echo_rtt, Some(Duration::from_millis(18)));
1952        assert_eq!(conn.icmp_echo_rtt, Some(Duration::from_millis(18)));
1953        assert_eq!(conn.current_rtt(), Some(Duration::from_millis(18)));
1954    }
1955
1956    #[test]
1957    fn echo_reply_with_unknown_sequence_measures_nothing() {
1958        let tracker = ConnectionTracker::new();
1959        tracker.ingest_at(&icmp_echo_packet(7, 10, true, false), capture_time(0));
1960        let reply = tracker.ingest_at(&icmp_echo_packet(7, 11, false, true), capture_time(12));
1961
1962        assert!(reply.icmp_echo_rtt.is_none());
1963        assert!(
1964            tracker
1965                .connections()
1966                .get(&reply.key)
1967                .and_then(|conn| conn.icmp_echo_rtt)
1968                .is_none()
1969        );
1970    }
1971
1972    #[test]
1973    fn local_echo_responder_turnaround_measures_nothing() {
1974        let tracker = ConnectionTracker::new();
1975        tracker.ingest_at(&icmp_echo_packet(7, 1, false, false), capture_time(0));
1976        let reply = tracker.ingest_at(&icmp_echo_packet(7, 1, true, true), capture_time(1));
1977
1978        assert!(reply.icmp_echo_rtt.is_none());
1979    }
1980
1981    fn loopback_echo_packet(identifier: u16, sequence: u16, is_reply: bool) -> ParsedPacket {
1982        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
1983
1984        let mut packet = icmp_echo_packet(identifier, sequence, true, is_reply);
1985        let loopback = SocketAddr::new(IpAddr::V4(Ipv4Addr::LOCALHOST), 0);
1986        packet.local_addr = loopback;
1987        packet.remote_addr = loopback;
1988        packet
1989    }
1990
1991    /// Loopback captures classify both the request and its reply as outgoing
1992    /// because both endpoints are local. The reply must still pair up.
1993    #[test]
1994    fn loopback_ping_measures_rtt() {
1995        let tracker = ConnectionTracker::new();
1996        tracker.ingest_at(&loopback_echo_packet(9, 1, false), capture_time(0));
1997        let reply = tracker.ingest_at(&loopback_echo_packet(9, 1, true), capture_time(1));
1998
1999        assert_eq!(reply.icmp_echo_rtt, Some(Duration::from_millis(1)));
2000    }
2001
2002    /// Echo requests reveal who initiated the flow; the Details tab uses the
2003    /// direction to hide the RTT row on flows this host only answers.
2004    #[test]
2005    fn echo_request_sets_connection_direction() {
2006        let tracker = ConnectionTracker::new();
2007        let outgoing = tracker.ingest_at(&icmp_echo_packet(7, 1, true, false), capture_time(0));
2008        let direction = tracker
2009            .connections()
2010            .get(&outgoing.key)
2011            .and_then(|conn| conn.connection_direction);
2012        assert_eq!(direction, Some(true));
2013
2014        let tracker = ConnectionTracker::new();
2015        let inbound = tracker.ingest_at(&icmp_echo_packet(7, 1, false, false), capture_time(0));
2016        tracker.ingest_at(&icmp_echo_packet(7, 1, true, true), capture_time(1));
2017        let direction = tracker
2018            .connections()
2019            .get(&inbound.key)
2020            .and_then(|conn| conn.connection_direction);
2021        assert_eq!(direction, Some(false), "our reply must not flip it");
2022    }
2023
2024    fn stun_packet(
2025        transaction_id: [u8; 12],
2026        is_outgoing: bool,
2027        class: crate::network::types::StunMessageClass,
2028    ) -> ParsedPacket {
2029        use crate::network::types::{StunInfo, StunMethod};
2030        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
2031
2032        let mut packet = ParsedPacket::test_udp(
2033            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 54_000),
2034            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 5)), 3478),
2035            ApplicationProtocol::Stun(StunInfo {
2036                message_class: class,
2037                method: StunMethod::Binding,
2038                transaction_id,
2039                software: None,
2040            }),
2041        );
2042        packet.is_outgoing = is_outgoing;
2043        packet.packet_len = 48;
2044        packet
2045    }
2046
2047    /// STUN binding requests and responses pair by transaction ID, giving a
2048    /// UDP flow with no handshake a real request→response time.
2049    #[test]
2050    fn stun_binding_response_measures_rtt() {
2051        use crate::network::types::StunMessageClass;
2052
2053        let tracker = ConnectionTracker::new();
2054        let txid = [3u8; 12];
2055        tracker.ingest_at(
2056            &stun_packet(txid, true, StunMessageClass::Request),
2057            capture_time(0),
2058        );
2059        let response = tracker.ingest_at(
2060            &stun_packet(txid, false, StunMessageClass::SuccessResponse),
2061            capture_time(31),
2062        );
2063
2064        assert_eq!(response.stun_rtt, Some(Duration::from_millis(31)));
2065        let conn = tracker
2066            .connections()
2067            .get(&response.key)
2068            .expect("STUN connection should exist")
2069            .clone();
2070        assert_eq!(conn.stun_rtt, Some(Duration::from_millis(31)));
2071    }
2072
2073    fn ntp_packet(
2074        mode: crate::network::types::NtpMode,
2075        is_outgoing: bool,
2076        origin_timestamp: u64,
2077        transmit_timestamp: u64,
2078    ) -> ParsedPacket {
2079        use crate::network::types::NtpInfo;
2080        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
2081
2082        let mut packet = ParsedPacket::test_udp(
2083            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 47_000),
2084            SocketAddr::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 9)), 123),
2085            ApplicationProtocol::Ntp(NtpInfo {
2086                version: 4,
2087                mode,
2088                stratum: 2,
2089                origin_timestamp,
2090                transmit_timestamp,
2091            }),
2092        );
2093        packet.is_outgoing = is_outgoing;
2094        packet.packet_len = 90;
2095        packet
2096    }
2097
2098    /// An NTP poll pairs with its response through the originate timestamp
2099    /// echo, giving the UDP flow a request→response time.
2100    #[test]
2101    fn ntp_server_response_measures_rtt() {
2102        use crate::network::types::NtpMode;
2103
2104        let tracker = ConnectionTracker::new();
2105        tracker.ingest_at(
2106            &ntp_packet(NtpMode::Client, true, 0, 0xAABB),
2107            capture_time(0),
2108        );
2109        let response = tracker.ingest_at(
2110            &ntp_packet(NtpMode::Server, false, 0xAABB, 0xCCDD),
2111            capture_time(21),
2112        );
2113
2114        assert_eq!(response.ntp_rtt, Some(Duration::from_millis(21)));
2115        let conn = tracker
2116            .connections()
2117            .get(&response.key)
2118            .expect("NTP connection should exist")
2119            .clone();
2120        assert_eq!(conn.ntp_rtt, Some(Duration::from_millis(21)));
2121    }
2122
2123    #[test]
2124    fn stun_response_with_unknown_transaction_measures_nothing() {
2125        use crate::network::types::StunMessageClass;
2126
2127        let tracker = ConnectionTracker::new();
2128        tracker.ingest_at(
2129            &stun_packet([3u8; 12], true, StunMessageClass::Request),
2130            capture_time(0),
2131        );
2132        let response = tracker.ingest_at(
2133            &stun_packet([4u8; 12], false, StunMessageClass::SuccessResponse),
2134            capture_time(31),
2135        );
2136
2137        assert!(response.stun_rtt.is_none());
2138    }
2139
2140    /// 1-RTT packets carry a short header with nothing timeable in the clear.
2141    #[test]
2142    fn quic_one_rtt_packets_do_not_measure_rtt() {
2143        let tracker = ConnectionTracker::new();
2144        tracker.ingest_at(&quic_packet(QuicPacketType::OneRtt, true), capture_time(0));
2145        let inbound = tracker.ingest_at(
2146            &quic_packet(QuicPacketType::OneRtt, false),
2147            capture_time(18),
2148        );
2149        assert!(inbound.measured_rtt.is_none());
2150    }
2151
2152    /// The TCP handshake is timed from capture timestamps for the same reason
2153    /// the QUIC one is: SYN and SYN-ACK routinely land in a single batch.
2154    #[test]
2155    fn tcp_handshake_rtt_comes_from_capture_timestamps() {
2156        let tracker = ConnectionTracker::new();
2157
2158        tracker.ingest_at(
2159            &tcp_packet(true, false, false, false, true),
2160            capture_time(0),
2161        );
2162        let syn_ack = tracker.ingest_at(
2163            &tcp_packet(true, true, false, false, false),
2164            capture_time(12),
2165        );
2166        assert_eq!(syn_ack.measured_rtt, Some(Duration::from_millis(12)));
2167    }
2168
2169    #[test]
2170    fn ingest_creates_then_updates() {
2171        let tracker = ConnectionTracker::new();
2172        let p = parse(&udp_frame(40000, 53));
2173
2174        let first = tracker.ingest(&p);
2175        assert!(first.created, "first packet should create a connection");
2176        assert!(!first.dropped);
2177        assert_eq!(tracker.connections().len(), 1);
2178
2179        let second = tracker.ingest(&p);
2180        assert!(!second.created, "second packet should update, not create");
2181        assert_eq!(second.key, first.key);
2182        assert_eq!(tracker.connections().len(), 1);
2183    }
2184
2185    #[test]
2186    fn distinct_flows_are_separate_connections() {
2187        let tracker = ConnectionTracker::new();
2188        tracker.ingest(&parse(&udp_frame(40000, 53)));
2189        tracker.ingest(&parse(&udp_frame(40001, 53)));
2190        assert_eq!(tracker.connections().len(), 2);
2191    }
2192
2193    #[test]
2194    fn concurrent_existing_flow_updates_preserve_counters_at_connection_limit() {
2195        let tracker = ConnectionTracker::with_config(TrackerConfig {
2196            max_connections: 1,
2197            ..TrackerConfig::default()
2198        });
2199        let packet = parse(&udp_frame(40000, 9999));
2200        let first = tracker.ingest_at(&packet, capture_time(0));
2201        let barrier = std::sync::Barrier::new(4);
2202
2203        std::thread::scope(|scope| {
2204            for _ in 0..4 {
2205                scope.spawn(|| {
2206                    barrier.wait();
2207                    for _ in 0..1_000 {
2208                        let outcome = tracker.ingest_at(&packet, capture_time(1));
2209                        assert!(!outcome.created);
2210                        assert!(!outcome.dropped);
2211                        assert!(!outcome.ignored_late);
2212                        assert!(outcome.archived.is_none());
2213                        assert_eq!(outcome.key, first.key);
2214                    }
2215                });
2216            }
2217        });
2218
2219        let conn = tracker.connections.get(&first.key).unwrap();
2220        assert_eq!(conn.packets_sent + conn.packets_received, 4_001);
2221        assert_eq!(
2222            conn.bytes_sent + conn.bytes_received,
2223            4_001 * packet.packet_len as u64
2224        );
2225        drop(conn);
2226        assert_eq!(tracker.active_count.load(Ordering::Relaxed), 1);
2227        assert!(tracker.ingest(&parse(&udp_frame(40001, 9999))).dropped);
2228    }
2229
2230    #[test]
2231    fn existing_terminal_generation_can_be_replaced_at_connection_limit() {
2232        let tracker = ConnectionTracker::with_config(TrackerConfig {
2233            max_connections: 1,
2234            ..TrackerConfig::default()
2235        });
2236        let first = tracker.ingest_at(
2237            &tcp_packet(false, false, false, true, true),
2238            capture_time(0),
2239        );
2240        let replacement = tracker.ingest_at(
2241            &tcp_packet(true, false, false, false, true),
2242            capture_time(1),
2243        );
2244        assert_eq!(replacement.key, first.key);
2245        assert!(replacement.created);
2246        assert!(!replacement.dropped);
2247        assert!(replacement.archived.is_some());
2248        assert_eq!(tracker.active_count.load(Ordering::Relaxed), 1);
2249        assert_eq!(tracker.connections().len(), 1);
2250        assert_eq!(tracker.historic_len(), 1);
2251
2252        let update = tracker.ingest_at(
2253            &tcp_packet(false, true, false, false, true),
2254            capture_time(2),
2255        );
2256        assert!(!update.created);
2257        assert!(!update.dropped);
2258        assert!(!update.ignored_late);
2259        assert!(update.archived.is_none());
2260        let conn = tracker.connections.get(&first.key).unwrap();
2261        assert_eq!(conn.packets_sent + conn.packets_received, 2);
2262    }
2263
2264    #[test]
2265    fn existing_flow_updates_publish_tcp_deltas_and_data_rtt() {
2266        let tracker = ConnectionTracker::new();
2267        tracker.ingest_at(
2268            &tcp_packet(false, true, false, false, true),
2269            capture_time(0),
2270        );
2271        let mut data = tcp_packet(false, true, false, false, true);
2272        data.tcp_header.as_mut().unwrap().payload_len = 100;
2273        let sent = tracker.ingest_at(&data, capture_time(10));
2274        assert!(!sent.created);
2275        assert_eq!(sent.retransmits, 0);
2276
2277        let mut ack = tcp_packet(false, true, false, false, false);
2278        ack.tcp_header.as_mut().unwrap().ack = 1_100;
2279        tracker.ingest_at(&ack, capture_time(35));
2280        assert_eq!(tracker.take_average_rtt(60), Some(25.0));
2281
2282        let retransmit = tracker.ingest_at(&data, capture_time(40));
2283        assert!(!retransmit.created);
2284        assert_eq!(retransmit.retransmits, 1);
2285        let conn = tracker.connections.get(&sent.key).unwrap();
2286        assert_eq!(conn.packets_sent + conn.packets_received, 4);
2287    }
2288
2289    #[test]
2290    fn max_connections_limit_drops_new_only() {
2291        let tracker = ConnectionTracker::with_config(TrackerConfig {
2292            max_connections: 1,
2293            ..TrackerConfig::default()
2294        });
2295        let a = tracker.ingest(&parse(&udp_frame(40000, 53)));
2296        assert!(a.created && !a.dropped);
2297
2298        // A different flow can't be inserted (limit reached) and is dropped.
2299        let b = tracker.ingest(&parse(&udp_frame(40001, 53)));
2300        assert!(b.dropped, "new connection beyond the limit must be dropped");
2301        assert!(!b.created);
2302        assert_eq!(tracker.connections().len(), 1);
2303
2304        // The existing flow still updates despite the limit.
2305        let a2 = tracker.ingest(&parse(&udp_frame(40000, 53)));
2306        assert!(!a2.dropped && !a2.created);
2307    }
2308
2309    #[test]
2310    fn connection_limit_recovers_after_cleanup() {
2311        let tracker = ConnectionTracker::with_config(TrackerConfig {
2312            max_connections: 1,
2313            ..TrackerConfig::default()
2314        });
2315        assert!(tracker.ingest(&parse(&udp_frame(40000, 53))).created);
2316        assert!(tracker.ingest(&parse(&udp_frame(40001, 53))).dropped);
2317
2318        // Expire everything; the limit accounting must follow the removals.
2319        tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
2320        assert_eq!(tracker.connections().len(), 0);
2321
2322        let c = tracker.ingest(&parse(&udp_frame(40002, 53)));
2323        assert!(
2324            c.created && !c.dropped,
2325            "slot freed by cleanup must be reusable"
2326        );
2327        assert_eq!(tracker.connections().len(), 1);
2328    }
2329
2330    #[test]
2331    fn connection_limit_recovers_after_clear() {
2332        let tracker = ConnectionTracker::with_config(TrackerConfig {
2333            max_connections: 1,
2334            ..TrackerConfig::default()
2335        });
2336        assert!(tracker.ingest(&parse(&udp_frame(40000, 53))).created);
2337        tracker.clear();
2338        let b = tracker.ingest(&parse(&udp_frame(40001, 53)));
2339        assert!(b.created && !b.dropped, "clear() must reset the limit");
2340    }
2341
2342    #[test]
2343    fn cleanup_archives_to_historic() {
2344        let tracker = ConnectionTracker::new();
2345        tracker.ingest(&parse(&udp_frame(40000, 53)));
2346        assert_eq!(tracker.connections().len(), 1);
2347
2348        for mut entry in tracker.connections().iter_mut() {
2349            entry.current_incoming_rate_bps = 2048.0;
2350            entry.current_outgoing_rate_bps = 1024.0;
2351        }
2352
2353        // A far-future `now` forces every connection past its timeout.
2354        let far_future = SystemTime::now() + Duration::from_secs(86_400);
2355        let removed = tracker.cleanup(far_future);
2356
2357        assert_eq!(removed.len(), 1, "the idle connection should be removed");
2358        assert!(!removed[0].is_historic, "returned form is the original");
2359        assert_eq!(tracker.connections().len(), 0);
2360        assert_eq!(
2361            tracker.historic_len(),
2362            1,
2363            "removed conn archived as historic"
2364        );
2365        let historic = tracker.historic().iter().next().unwrap();
2366        assert_eq!(historic.current_incoming_rate_bps, 0.0);
2367        assert_eq!(historic.current_outgoing_rate_bps, 0.0);
2368    }
2369
2370    #[test]
2371    fn traffic_refreshes_a_stale_nonterminal_connection() {
2372        let tracker = ConnectionTracker::new();
2373        let packet = parse(&udp_frame(40000, 9999));
2374        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2375        tracker.ingest_at(&packet, started);
2376
2377        assert!(
2378            tracker
2379                .cleanup(started + Duration::from_secs(59))
2380                .is_empty()
2381        );
2382        tracker.ingest_at(&packet, started + Duration::from_secs(59));
2383        assert!(
2384            tracker
2385                .cleanup(started + Duration::from_secs(61))
2386                .is_empty()
2387        );
2388        assert_eq!(tracker.connections().len(), 1);
2389    }
2390
2391    #[test]
2392    fn terminal_retransmissions_do_not_postpone_archival() {
2393        let tracker = ConnectionTracker::new();
2394        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2395        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
2396        tracker.ingest_at(
2397            &tcp_packet(false, true, false, false, false),
2398            started + Duration::from_secs(10),
2399        );
2400
2401        let conn = tracker.connections().iter().next().unwrap();
2402        assert_eq!(conn.last_activity, started + Duration::from_secs(10));
2403        assert_eq!(conn.terminal_since, Some(started));
2404        drop(conn);
2405
2406        let removed = tracker.cleanup(started + Duration::from_secs(16));
2407        assert_eq!(removed.len(), 1);
2408        assert_eq!(tracker.historic_len(), 1);
2409    }
2410
2411    #[test]
2412    fn syn_after_terminal_state_starts_a_new_generation() {
2413        use crate::network::types::{ProtocolState, TcpState};
2414
2415        let tracker = ConnectionTracker::new();
2416        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2417        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
2418        for mut entry in tracker.connections().iter_mut() {
2419            entry.current_incoming_rate_bps = 2048.0;
2420            entry.current_outgoing_rate_bps = 1024.0;
2421        }
2422
2423        let outcome = tracker.ingest_at(&tcp_packet(true, false, false, false, true), started);
2424        assert!(outcome.created);
2425        assert!(outcome.archived.is_some());
2426        assert_eq!(tracker.connections().len(), 1);
2427        assert_eq!(tracker.historic_len(), 1);
2428
2429        let active = tracker.connections().iter().next().unwrap();
2430        assert!(
2431            active.created_at > started,
2432            "a same-batch replacement needs a distinct historic identity"
2433        );
2434        assert!(matches!(
2435            active.protocol_state,
2436            ProtocolState::Tcp(TcpState::SynSent)
2437        ));
2438        assert!(!active.is_historic);
2439        drop(active);
2440
2441        let historic = tracker.historic().iter().next().unwrap();
2442        assert_eq!(historic.created_at, started);
2443        assert!(historic.is_historic);
2444        assert_eq!(historic.closed_at, Some(started));
2445        assert_eq!(
2446            historic.current_incoming_rate_bps, 0.0,
2447            "a superseded generation is archived with its rates zeroed, like cleanup"
2448        );
2449        assert_eq!(historic.current_outgoing_rate_bps, 0.0);
2450        drop(historic);
2451
2452        tracker.cleanup(started + Duration::from_secs(61));
2453        assert_eq!(
2454            tracker.historic_len(),
2455            2,
2456            "archiving the replacement must not overwrite the old generation"
2457        );
2458    }
2459
2460    #[test]
2461    fn delayed_ack_after_archival_is_not_a_phantom_connection() {
2462        let tracker = ConnectionTracker::new();
2463        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2464        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
2465        tracker.cleanup(started + Duration::from_secs(16));
2466
2467        let outcome = tracker.ingest_at(
2468            &tcp_packet(false, true, false, false, false),
2469            started + Duration::from_secs(17),
2470        );
2471        assert!(outcome.ignored_late);
2472        assert!(!outcome.created);
2473        assert!(tracker.connections().is_empty());
2474        assert_eq!(tracker.historic_len(), 1);
2475    }
2476
2477    #[test]
2478    fn payload_after_terminal_archival_starts_a_new_generation() {
2479        let tracker = ConnectionTracker::new();
2480        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2481        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
2482        tracker.cleanup(started + Duration::from_secs(16));
2483
2484        let mut packet = tcp_packet(false, true, false, false, false);
2485        packet.tcp_header.as_mut().unwrap().payload_len = 100;
2486        let outcome = tracker.ingest_at(&packet, started + Duration::from_secs(17));
2487
2488        assert!(!outcome.ignored_late);
2489        assert!(outcome.created);
2490        assert_eq!(tracker.connections().len(), 1);
2491        assert_eq!(tracker.historic_len(), 1);
2492    }
2493
2494    #[test]
2495    fn traffic_after_idle_archival_starts_a_new_generation_immediately() {
2496        let tracker = ConnectionTracker::new();
2497        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2498        tracker.ingest_at(&tcp_packet(false, true, false, false, true), started);
2499        tracker.cleanup(started + Duration::from_secs(301));
2500
2501        let outcome = tracker.ingest_at(
2502            &tcp_packet(false, true, false, false, false),
2503            started + Duration::from_secs(302),
2504        );
2505        assert!(!outcome.ignored_late);
2506        assert!(outcome.created);
2507        assert_eq!(tracker.connections().len(), 1);
2508        assert_eq!(tracker.historic_len(), 1);
2509    }
2510
2511    #[test]
2512    fn midstream_ack_is_allowed_after_recent_tombstone_expires() {
2513        use crate::network::types::{ProtocolState, TcpState};
2514
2515        let tracker = ConnectionTracker::new();
2516        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2517        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
2518        tracker.cleanup(started + Duration::from_secs(16));
2519
2520        let outcome = tracker.ingest_at(
2521            &tcp_packet(false, true, false, false, false),
2522            started + Duration::from_secs(47),
2523        );
2524        assert!(!outcome.ignored_late);
2525        assert!(outcome.created);
2526        let active = tracker.connections().iter().next().unwrap();
2527        assert!(matches!(
2528            active.protocol_state,
2529            ProtocolState::Tcp(TcpState::Established)
2530        ));
2531    }
2532
2533    #[test]
2534    fn new_activity_does_not_mutate_a_historic_snapshot() {
2535        let tracker = ConnectionTracker::new();
2536        let packet = parse(&udp_frame(40000, 9999));
2537        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2538        tracker.ingest_at(&packet, started);
2539        tracker.cleanup(started + Duration::from_secs(61));
2540
2541        let historic_before = tracker.historic.iter().next().unwrap().value().clone();
2542        tracker.ingest_at(&packet, started + Duration::from_secs(62));
2543        tracker.ingest_at(&packet, started + Duration::from_secs(63));
2544        let historic_after = tracker.historic.iter().next().unwrap().value().clone();
2545
2546        assert_eq!(historic_after.bytes_sent, historic_before.bytes_sent);
2547        assert_eq!(
2548            historic_after.bytes_received,
2549            historic_before.bytes_received
2550        );
2551        assert_eq!(historic_after.last_activity, historic_before.last_activity);
2552        assert_eq!(historic_after.closed_at, historic_before.closed_at);
2553        assert_eq!(tracker.connections().len(), 1);
2554    }
2555
2556    #[test]
2557    fn retained_source_view_is_atomic_across_cleanup() {
2558        let tracker = std::sync::Arc::new(ConnectionTracker::new());
2559        tracker.ingest(&parse(&udp_frame(40000, 53)));
2560
2561        let (active_scanned_tx, active_scanned_rx) = std::sync::mpsc::channel();
2562        let (release_tx, release_rx) = std::sync::mpsc::channel();
2563        let reader_tracker = std::sync::Arc::clone(&tracker);
2564        let reader = std::thread::spawn(move || {
2565            reader_tracker.with_retained_sources(|active, historic| {
2566                let active_count = active.iter().count();
2567                active_scanned_tx.send(()).unwrap();
2568                release_rx.recv().unwrap();
2569                active_count + historic.iter().count()
2570            })
2571        });
2572
2573        active_scanned_rx.recv().unwrap();
2574        let (cleanup_started_tx, cleanup_started_rx) = std::sync::mpsc::channel();
2575        let (cleanup_done_tx, cleanup_done_rx) = std::sync::mpsc::channel();
2576        let cleanup_tracker = std::sync::Arc::clone(&tracker);
2577        let cleanup = std::thread::spawn(move || {
2578            cleanup_started_tx.send(()).unwrap();
2579            let removed = cleanup_tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
2580            cleanup_done_tx.send(removed.len()).unwrap();
2581        });
2582
2583        cleanup_started_rx.recv().unwrap();
2584        assert!(
2585            cleanup_done_rx
2586                .recv_timeout(Duration::from_millis(50))
2587                .is_err(),
2588            "cleanup must wait for the retained source view"
2589        );
2590        release_tx.send(()).unwrap();
2591
2592        assert_eq!(reader.join().unwrap(), 1);
2593        assert_eq!(cleanup_done_rx.recv().unwrap(), 1);
2594        cleanup.join().unwrap();
2595        assert_eq!(tracker.connections().len(), 0);
2596        assert_eq!(tracker.historic_len(), 1);
2597    }
2598
2599    #[test]
2600    fn cleanup_without_keep_historic_skips_archive() {
2601        let tracker = ConnectionTracker::with_config(TrackerConfig {
2602            keep_historic: false,
2603            ..TrackerConfig::default()
2604        });
2605        tracker.ingest(&parse(&udp_frame(40000, 53)));
2606        let far_future = SystemTime::now() + Duration::from_secs(86_400);
2607        let removed = tracker.cleanup(far_future);
2608        assert_eq!(removed.len(), 1);
2609        assert_eq!(tracker.historic_len(), 0, "historic disabled");
2610    }
2611
2612    /// `max_historic` sizes the user-facing archive; it must not shrink the
2613    /// tombstone table below the floor, or closing more flows than the cap
2614    /// lets delayed teardown packets resurrect phantom connections.
2615    #[test]
2616    fn zero_max_historic_keeps_tombstones_for_all_closed_flows() {
2617        let tracker = ConnectionTracker::with_config(TrackerConfig {
2618            keep_historic: false,
2619            max_historic: 0,
2620            ..TrackerConfig::default()
2621        });
2622
2623        let start = SystemTime::now();
2624        for port in [40_000u16, 40_001] {
2625            let mut syn = tcp_packet(true, false, false, false, true);
2626            syn.local_addr.set_port(port);
2627            tracker.ingest_at(&syn, start);
2628            let mut rst = tcp_packet(false, false, false, true, true);
2629            rst.local_addr.set_port(port);
2630            tracker.ingest_at(&rst, start + Duration::from_secs(1));
2631        }
2632        assert_eq!(tracker.connections().len(), 2);
2633
2634        let closed_at = start + Duration::from_secs(86_400);
2635        let removed = tracker.cleanup(closed_at);
2636        assert_eq!(removed.len(), 2);
2637
2638        for port in [40_000u16, 40_001] {
2639            let mut late_fin = tcp_packet(false, true, true, false, true);
2640            late_fin.local_addr.set_port(port);
2641            let outcome = tracker.ingest_at(&late_fin, closed_at + Duration::from_secs(1));
2642            assert!(
2643                outcome.ignored_late,
2644                "delayed teardown for port {port} must hit a tombstone"
2645            );
2646        }
2647        assert!(
2648            tracker.connections().is_empty(),
2649            "no phantom connections may be created"
2650        );
2651    }
2652
2653    #[test]
2654    fn ingest_at_uses_supplied_time_for_cleanup() {
2655        // A packet ingested "in the past" must be eligible for cleanup at a
2656        // `now` only slightly later than its supplied capture time, proving the
2657        // tracker stamps the connection with the caller's time, not the wall
2658        // clock. (Wall-clock stamping would make `created_at` ~= real now, so a
2659        // cleanup at trace-time + a few minutes would NOT expire it.)
2660        let tracker = ConnectionTracker::new();
2661        let capture_time = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
2662        tracker.ingest_at(&parse(&udp_frame(40000, 53)), capture_time);
2663        assert_eq!(tracker.connections().len(), 1);
2664
2665        // One day after the capture time the UDP flow is well past its timeout.
2666        let removed = tracker.cleanup(capture_time + Duration::from_secs(86_400));
2667        assert_eq!(
2668            removed.len(),
2669            1,
2670            "flow stamped at capture time should expire"
2671        );
2672        assert_eq!(tracker.connections().len(), 0);
2673    }
2674
2675    /// A connection opened right after a captured DNS response to one of the
2676    /// answered IPs must be tagged with the query name at creation. With
2677    /// `dns_attribution` disabled, the same traffic must stay untagged.
2678    #[test]
2679    fn dns_response_attributes_a_following_connection() {
2680        let answered_ip: std::net::IpAddr = "203.0.113.80".parse().unwrap();
2681
2682        let tracker = ConnectionTracker::new();
2683        tracker.ingest_at(
2684            &dns_answer_packet(1, "cdn.example", &[answered_ip]),
2685            capture_time(0),
2686        );
2687        let outcome = tracker.ingest_at(&plain_udp_packet(), capture_time(50));
2688        assert_eq!(
2689            tracker
2690                .connections()
2691                .get(&outcome.key)
2692                .and_then(|conn| conn.attributed_hostname.as_ref().map(|a| a.name.clone())),
2693            Some("cdn.example".to_string())
2694        );
2695
2696        let disabled = ConnectionTracker::with_config(TrackerConfig {
2697            dns_attribution: false,
2698            ..TrackerConfig::default()
2699        });
2700        disabled.ingest_at(
2701            &dns_answer_packet(1, "cdn.example", &[answered_ip]),
2702            capture_time(0),
2703        );
2704        let outcome = disabled.ingest_at(&plain_udp_packet(), capture_time(50));
2705        assert!(
2706            disabled
2707                .connections()
2708                .get(&outcome.key)
2709                .unwrap()
2710                .attributed_hostname
2711                .is_none(),
2712            "the config flag must disable attribution"
2713        );
2714    }
2715
2716    /// A connection observed before any matching DNS waits in the pending
2717    /// index; the DNS response that later answers its remote IP tags it.
2718    #[test]
2719    fn late_dns_response_attributes_a_pending_connection() {
2720        let tracker = ConnectionTracker::new();
2721        let outcome = tracker.ingest_at(&plain_udp_packet(), capture_time(0));
2722        assert!(
2723            tracker
2724                .connections()
2725                .get(&outcome.key)
2726                .unwrap()
2727                .attributed_hostname
2728                .is_none()
2729        );
2730
2731        let answered_ip: std::net::IpAddr = "203.0.113.80".parse().unwrap();
2732        tracker.ingest_at(
2733            &dns_answer_packet(1, "late.example", &[answered_ip]),
2734            capture_time(200),
2735        );
2736        assert_eq!(
2737            tracker
2738                .connections()
2739                .get(&outcome.key)
2740                .and_then(|conn| conn.attributed_hostname.as_ref().map(|a| a.name.clone())),
2741            Some("late.example".to_string())
2742        );
2743    }
2744
2745    /// Cleaning up a still-pending connection must drop its enrollment, so a
2746    /// DNS response arriving after its death finds no waiter and the archived
2747    /// record stays unattributed.
2748    #[test]
2749    fn cleanup_forgets_pending_attribution_enrollments() {
2750        let tracker = ConnectionTracker::new();
2751        tracker.ingest(&plain_udp_packet());
2752        let removed = tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
2753        assert_eq!(removed.len(), 1);
2754
2755        let answered_ip: std::net::IpAddr = "203.0.113.80".parse().unwrap();
2756        tracker.ingest(&dns_answer_packet(1, "posthumous.example", &[answered_ip]));
2757        assert!(
2758            tracker
2759                .historic
2760                .iter()
2761                .all(|conn| conn.attributed_hostname.is_none()),
2762            "a response after death must not label the archived record"
2763        );
2764    }
2765
2766    #[test]
2767    fn clear_empties_everything() {
2768        let tracker = ConnectionTracker::new();
2769        tracker.ingest(&parse(&udp_frame(40000, 53)));
2770        tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
2771        assert_eq!(tracker.historic_len(), 1);
2772
2773        let dns_at = SystemTime::now();
2774        tracker.ingest_at(&dns_packet(7, true, false, 0), dns_at);
2775        tracker.ingest_at(
2776            &dns_packet(7, false, true, 0),
2777            dns_at + Duration::from_millis(15),
2778        );
2779        assert_eq!(
2780            tracker
2781                .dns_analytics_snapshot_at(dns_at + Duration::from_millis(15))
2782                .lookups,
2783            1
2784        );
2785
2786        tracker.clear();
2787        assert!(tracker.connections().is_empty());
2788        assert_eq!(tracker.historic_len(), 0);
2789        assert_eq!(
2790            tracker.dns_analytics_snapshot_at(dns_at + Duration::from_millis(15)),
2791            DnsAnalyticsSnapshot::default()
2792        );
2793    }
2794}