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 SYN/SYN-ACK timing, QUIC connection-ID coalescing,
8//! and timeout-based cleanup — **without** any UI, capture, or process-lookup
9//! dependency.
10//!
11//! This is the piece that makes headless tools easy: pair a capture source with
12//! a parser, then feed each parsed packet to [`ConnectionTracker::ingest`] and
13//! periodically call [`ConnectionTracker::cleanup`]. A Prometheus exporter, a
14//! pcap post-processor, or a test harness can all reuse the exact connection
15//! semantics of the main application. Offline consumers replaying a saved trace
16//! should use [`ConnectionTracker::ingest_at`] with each packet's capture
17//! timestamp so connection lifetimes and timeouts follow trace time rather than
18//! 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(&parsed);
31//!     }
32//! }
33//! tracker.cleanup(SystemTime::now()); // expire idle/closed connections
34//! for conn in tracker.snapshot() {
35//!     println!("{} {} -> {}", conn.protocol, conn.local_addr, conn.remote_addr);
36//! }
37//! ```
38//!
39//! All methods take `&self` (the internal tables use interior mutability), so a
40//! single tracker can be wrapped in an [`std::sync::Arc`] and shared across a
41//! capture thread, a cleanup thread, and a reader thread.
42
43use crate::network::merge::{create_connection_from_packet, merge_packet_into_connection};
44use crate::network::parser::ParsedPacket;
45use crate::network::types::{ApplicationProtocol, Connection, ConnectionKey, Protocol, RttTracker};
46use dashmap::DashMap;
47use rustc_hash::FxBuildHasher;
48use std::collections::HashMap;
49use std::sync::atomic::{AtomicUsize, Ordering};
50use std::sync::{Mutex, RwLock};
51use std::time::{Duration, SystemTime};
52
53/// Recently archived TCP tuples remain tombstoned briefly so delayed teardown
54/// packets do not create phantom established connections.
55const RECENTLY_CLOSED_TTL: Duration = Duration::from_secs(30);
56
57/// Tombstone capacity floor. `max_historic` sizes the user-facing archive,
58/// but tombstones guard correctness, so a tiny or zero `max_historic` must
59/// not strip them and reopen the phantom-connection window. Entries are a
60/// key and a timestamp; the TTL above bounds how long any of them live.
61const RECENTLY_CLOSED_MIN_ENTRIES: usize = 1024;
62
63/// The active connection table: flow key -> connection.
64///
65/// Keys are compact `Copy` structs, and the map uses FxHash — with a small
66/// fixed-size key, hashing is a handful of multiplies instead of SipHash over
67/// a formatted string. (Hash-flooding resistance isn't needed here: the table
68/// is bounded by `max_connections` and keyed by addresses, not attacker-chosen
69/// bytes of arbitrary length.)
70pub type ConnectionMap = DashMap<ConnectionKey, Connection, FxBuildHasher>;
71
72/// The historic (recently-closed) connection table.
73pub type HistoricMap = DashMap<HistoricKey, Connection, FxBuildHasher>;
74
75/// Identity of an archived (closed) connection: the flow key plus the
76/// connection's creation time, so multiple closed connections that reused the
77/// same 4-tuple don't clobber each other. (Replaces the former
78/// `"<key>:<created_at_nanos>"` string suffix.)
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
80pub struct HistoricKey {
81    pub key: ConnectionKey,
82    pub created_nanos: u128,
83}
84
85impl std::fmt::Display for HistoricKey {
86    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
87        write!(f, "{}:{}", self.key, self.created_nanos)
88    }
89}
90
91/// Tuning knobs for a [`ConnectionTracker`].
92#[derive(Debug, Clone)]
93pub struct TrackerConfig {
94    /// Maximum number of concurrent active connections. New connections beyond
95    /// this limit are dropped (existing ones still update) to bound memory
96    /// under port scans or connection floods.
97    pub max_connections: usize,
98    /// Maximum number of recently-closed ("historic") connections retained.
99    /// Oldest-closed entries are evicted first.
100    pub max_historic: usize,
101    /// Maximum number of QUIC connection-ID -> connection-key mappings kept for
102    /// coalescing migrated QUIC connections. Cleared wholesale when exceeded.
103    pub max_quic_mappings: usize,
104    /// Whether [`ConnectionTracker::cleanup`] archives removed connections into
105    /// the historic table. Headless tools that don't need a closed-connection
106    /// view can set this to `false` to save memory.
107    pub keep_historic: bool,
108}
109
110impl Default for TrackerConfig {
111    fn default() -> Self {
112        Self {
113            max_connections: 50_000,
114            max_historic: 5_000,
115            max_quic_mappings: 10_000,
116            keep_historic: true,
117        }
118    }
119}
120
121/// What happened when a packet was [`ingest`](ConnectionTracker::ingest)ed.
122///
123/// Returned so callers can layer their own concerns — global statistics,
124/// structured logging, DNS enrichment — on top of the core table update without
125/// the tracker needing to know about them.
126#[derive(Debug, Clone)]
127pub struct IngestOutcome {
128    /// The (possibly QUIC-coalesced) key under which the connection is stored.
129    /// `Copy`, and its `Display` form matches the historical string key
130    /// (`"TCP:1.2.3.4:80-TCP:5.6.7.8:443"`).
131    pub key: ConnectionKey,
132    /// `true` if this packet created a new connection entry.
133    pub created: bool,
134    /// `true` if the packet was dropped because `max_connections` was reached
135    /// (the connection did not already exist and was not inserted).
136    pub dropped: bool,
137    /// `true` when a delayed packet matched a recently archived TCP tuple and
138    /// was intentionally not turned into a new active connection.
139    pub ignored_late: bool,
140    /// Previous live generation archived by a strong new-session signal.
141    /// Historic storage receives an immutable snapshot of this connection.
142    pub archived: Option<Connection>,
143    /// New TCP retransmissions detected by this packet.
144    pub retransmits: u64,
145    /// New out-of-order TCP segments detected by this packet.
146    pub out_of_order: u64,
147    /// New TCP fast-retransmits detected by this packet.
148    pub fast_retransmits: u64,
149    /// An RTT sample, if this packet was a TCP SYN-ACK that matched a prior SYN.
150    pub measured_rtt: Option<Duration>,
151}
152
153/// A live, lifecycle-managed table of network connections built from parsed
154/// packets. See the [module docs](self) for the intended usage.
155pub struct ConnectionTracker {
156    connections: ConnectionMap,
157    historic: HistoricMap,
158    /// Coordinates moves between the active and historic maps with readers
159    /// that need one consistent retained-connection view.
160    lifecycle: RwLock<()>,
161    rtt: Mutex<RttTracker>,
162    quic_map: Mutex<HashMap<String, ConnectionKey>>,
163    recently_closed: Mutex<HashMap<ConnectionKey, SystemTime>>,
164    config: TrackerConfig,
165    /// Active-connection count maintained by `ingest_at`/`cleanup`/`clear`.
166    /// Lets the per-packet `max_connections` check be a single atomic load
167    /// instead of a `DashMap::len()` (which read-locks every shard) plus an
168    /// extra `contains_key` lookup. May transiently lag `connections.len()`
169    /// by a few entries under concurrent ingest near the limit — acceptable
170    /// for a flood-protection bound.
171    active_count: AtomicUsize,
172}
173
174impl ConnectionTracker {
175    /// Create a tracker with [default](TrackerConfig::default) configuration.
176    pub fn new() -> Self {
177        Self::with_config(TrackerConfig::default())
178    }
179
180    /// Create a tracker with custom [`TrackerConfig`].
181    pub fn with_config(config: TrackerConfig) -> Self {
182        Self {
183            connections: ConnectionMap::with_hasher(FxBuildHasher),
184            historic: HistoricMap::with_hasher(FxBuildHasher),
185            lifecycle: RwLock::new(()),
186            rtt: Mutex::new(RttTracker::new()),
187            quic_map: Mutex::new(HashMap::new()),
188            recently_closed: Mutex::new(HashMap::new()),
189            config,
190            active_count: AtomicUsize::new(0),
191        }
192    }
193
194    /// Fold a parsed packet into the connection table, creating or updating the
195    /// matching connection, timestamping the update with the current wall clock.
196    ///
197    /// This is the right call for live capture. Offline consumers replaying a
198    /// pcap should use [`ingest_at`](Self::ingest_at) and pass the packet's own
199    /// capture time so connection lifetimes and [`cleanup`](Self::cleanup)
200    /// timeouts reflect the trace rather than the replay wall clock.
201    pub fn ingest(&self, parsed: &ParsedPacket) -> IngestOutcome {
202        self.ingest_at(parsed, SystemTime::now())
203    }
204
205    /// Like [`ingest`](Self::ingest), but stamps the connection update with the
206    /// supplied `now` instead of the wall clock.
207    ///
208    /// Use this for deterministic offline processing (pcap replay, tests): pass
209    /// the packet's capture timestamp so `created_at`/`last_activity` and the
210    /// `cleanup` timeout sweep operate on trace time, not real time.
211    pub fn ingest_at(&self, parsed: &ParsedPacket, now: SystemTime) -> IngestOutcome {
212        // Track RTT for TCP connections using SYN/SYN-ACK timing.
213        let mut measured_rtt: Option<Duration> = None;
214        let base_key = parsed.connection_key();
215        if parsed.protocol == Protocol::Tcp
216            && let Some(tcp_header) = &parsed.tcp_header
217        {
218            if tcp_header.flags.syn && !tcp_header.flags.ack {
219                if let Ok(mut tracker) = self.rtt.lock() {
220                    tracker.record_syn(base_key);
221                }
222            } else if tcp_header.flags.syn
223                && tcp_header.flags.ack
224                && let Ok(mut tracker) = self.rtt.lock()
225            {
226                measured_rtt = tracker.record_syn_ack(&base_key);
227            }
228        }
229
230        // A read guard makes ordinary packet updates atomic with cleanup. The
231        // uncommon generation-split path drops it and reacquires a write guard
232        // so retained-source readers also see one consistent move.
233        let lifecycle = self
234            .lifecycle
235            .read()
236            .unwrap_or_else(std::sync::PoisonError::into_inner);
237        let key = self.resolve_connection_key(parsed);
238
239        if !self.connections.contains_key(&key) && self.is_recent_late_packet(key, parsed, now) {
240            return IngestOutcome {
241                key,
242                created: false,
243                dropped: false,
244                ignored_late: true,
245                archived: None,
246                retransmits: 0,
247                out_of_order: 0,
248                fast_retransmits: 0,
249                measured_rtt,
250            };
251        }
252
253        let starts_new_generation = self
254            .connections
255            .get(&key)
256            .is_some_and(|conn| Self::packet_starts_new_generation(&conn, parsed));
257        if starts_new_generation {
258            drop(lifecycle);
259            return self.ingest_new_generation(parsed, now, key, measured_rtt);
260        }
261
262        self.ingest_into_active(parsed, now, key, measured_rtt)
263    }
264
265    fn ingest_into_active(
266        &self,
267        parsed: &ParsedPacket,
268        now: SystemTime,
269        key: ConnectionKey,
270        measured_rtt: Option<Duration>,
271    ) -> IngestOutcome {
272        // Prevent unbounded growth from port scans or connection floods. Only
273        // limit new connections; existing ones always get updated. The fast
274        // path is a single atomic load; only when at the cap do we pay a
275        // lookup to distinguish update-existing from drop-new. (Never call
276        // `len()` here or while holding an entry guard — it read-locks every
277        // shard.)
278        if self.active_count.load(Ordering::Relaxed) >= self.config.max_connections
279            && !self.connections.contains_key(&key)
280        {
281            return IngestOutcome {
282                key,
283                created: false,
284                dropped: true,
285                ignored_late: false,
286                archived: None,
287                retransmits: 0,
288                out_of_order: 0,
289                fast_retransmits: 0,
290                measured_rtt,
291            };
292        }
293
294        let mut created = false;
295        let mut deltas = (0u64, 0u64, 0u64);
296        self.connections
297            .entry(key)
298            .and_modify(|conn| {
299                deltas = merge_packet_into_connection(conn, parsed, now);
300                if let Some(rtt) = measured_rtt
301                    && conn.initial_rtt.is_none()
302                {
303                    conn.initial_rtt = Some(rtt);
304                }
305            })
306            .or_insert_with(|| {
307                created = true;
308                let mut conn = create_connection_from_packet(parsed, now);
309                if let Some(rtt) = measured_rtt {
310                    conn.initial_rtt = Some(rtt);
311                }
312                conn
313            });
314        if created {
315            self.active_count.fetch_add(1, Ordering::Relaxed);
316        }
317
318        IngestOutcome {
319            key,
320            created,
321            dropped: false,
322            ignored_late: false,
323            archived: None,
324            retransmits: deltas.0,
325            out_of_order: deltas.1,
326            fast_retransmits: deltas.2,
327            measured_rtt,
328        }
329    }
330
331    fn ingest_new_generation(
332        &self,
333        parsed: &ParsedPacket,
334        now: SystemTime,
335        key: ConnectionKey,
336        measured_rtt: Option<Duration>,
337    ) -> IngestOutcome {
338        let _lifecycle = self
339            .lifecycle
340            .write()
341            .unwrap_or_else(std::sync::PoisonError::into_inner);
342        let mut replacement_now = now;
343
344        let still_needs_split = self
345            .connections
346            .get(&key)
347            .is_some_and(|conn| Self::packet_starts_new_generation(&conn, parsed));
348        let archived = if still_needs_split {
349            self.connections.remove(&key).map(|(_, conn)| {
350                // Historic keys include `created_at`, so two generations of
351                // the same tuple must not share a creation timestamp. This is
352                // possible when several captured packets use one batch time.
353                if replacement_now <= conn.created_at {
354                    replacement_now = conn
355                        .created_at
356                        .checked_add(Duration::from_nanos(1))
357                        .unwrap_or(replacement_now);
358                }
359                self.active_count.fetch_sub(1, Ordering::Relaxed);
360                self.archive_snapshot(key, &conn, now);
361                self.record_recently_closed(key, &conn, now);
362                self.remove_quic_mappings_for_key(key);
363                conn
364            })
365        } else {
366            None
367        };
368
369        // Cleanup may have removed the old generation while this packet was
370        // waiting to acquire the write guard. Reassociate any visible QUIC ID
371        // before creating the replacement.
372        self.associate_quic_id(parsed, key);
373        let mut outcome = self.ingest_into_active(parsed, replacement_now, key, measured_rtt);
374        outcome.archived = archived;
375        self.enforce_historic_limit();
376        self.prune_recently_closed(now);
377        outcome
378    }
379
380    fn resolve_connection_key(&self, parsed: &ParsedPacket) -> ConnectionKey {
381        let mut key = parsed.connection_key();
382        let Some(conn_id_hex) = Self::parsed_quic_id(parsed) else {
383            return key;
384        };
385        let Ok(mut mapping) = self.quic_map.lock() else {
386            return key;
387        };
388        if let Some(existing_key) = mapping.get(conn_id_hex) {
389            key = *existing_key;
390        } else {
391            if mapping.len() >= self.config.max_quic_mappings {
392                mapping.clear();
393            }
394            mapping.insert(conn_id_hex.to_string(), key);
395        }
396        key
397    }
398
399    fn parsed_quic_id(parsed: &ParsedPacket) -> Option<&str> {
400        let dpi = parsed.dpi_result.as_ref()?;
401        let ApplicationProtocol::Quic(quic) = &dpi.application else {
402            return None;
403        };
404        quic.connection_id_hex.as_deref()
405    }
406
407    fn associate_quic_id(&self, parsed: &ParsedPacket, key: ConnectionKey) {
408        let Some(conn_id_hex) = Self::parsed_quic_id(parsed) else {
409            return;
410        };
411        if let Ok(mut mapping) = self.quic_map.lock() {
412            if mapping.len() >= self.config.max_quic_mappings {
413                mapping.clear();
414            }
415            mapping.insert(conn_id_hex.to_string(), key);
416        }
417    }
418
419    fn packet_starts_new_generation(conn: &Connection, parsed: &ParsedPacket) -> bool {
420        if !conn.is_closing_or_terminal() {
421            return false;
422        }
423        match parsed.protocol {
424            Protocol::Tcp => parsed
425                .tcp_header
426                .as_ref()
427                .is_some_and(|header| header.flags.syn),
428            Protocol::Udp => {
429                let Some(new_id) = Self::parsed_quic_id(parsed) else {
430                    return false;
431                };
432                let Some(dpi) = conn.dpi_info.as_ref() else {
433                    return false;
434                };
435                let ApplicationProtocol::Quic(old_quic) = &dpi.application else {
436                    return false;
437                };
438                old_quic
439                    .connection_id_hex
440                    .as_deref()
441                    .is_some_and(|old_id| old_id != new_id)
442            }
443            _ => false,
444        }
445    }
446
447    fn is_recent_late_packet(
448        &self,
449        key: ConnectionKey,
450        parsed: &ParsedPacket,
451        now: SystemTime,
452    ) -> bool {
453        if parsed.protocol != Protocol::Tcp {
454            return false;
455        }
456        let Some(header) = parsed.tcp_header.as_ref() else {
457            return false;
458        };
459        let is_teardown_only = !header.flags.syn
460            && (header.flags.fin
461                || header.flags.rst
462                || (header.flags.ack && header.payload_len == 0));
463        if !is_teardown_only {
464            return false;
465        }
466        self.recently_closed
467            .lock()
468            .unwrap_or_else(std::sync::PoisonError::into_inner)
469            .get(&key)
470            .is_some_and(|closed_at| {
471                now.duration_since(*closed_at).unwrap_or_default() <= RECENTLY_CLOSED_TTL
472            })
473    }
474
475    fn archive_snapshot(&self, key: ConnectionKey, conn: &Connection, now: SystemTime) {
476        if !self.config.keep_historic {
477            return;
478        }
479        let mut historic = conn.snapshot_clone();
480        historic.is_historic = true;
481        historic.closed_at = Some(now);
482        let historic_key = HistoricKey {
483            key,
484            created_nanos: conn
485                .created_at
486                .duration_since(SystemTime::UNIX_EPOCH)
487                .unwrap_or_default()
488                .as_nanos(),
489        };
490        self.historic.insert(historic_key, historic);
491    }
492
493    fn enforce_historic_limit(&self) {
494        if self.historic.len() <= self.config.max_historic {
495            return;
496        }
497        let mut entries: Vec<(HistoricKey, SystemTime)> = self
498            .historic
499            .iter()
500            .map(|entry| {
501                let closed = entry.value().closed_at.unwrap_or(entry.value().created_at);
502                (*entry.key(), closed)
503            })
504            .collect();
505        entries.sort_by_key(|(_, closed)| *closed);
506        let to_remove = self.historic.len() - self.config.max_historic;
507        for (key, _) in entries.into_iter().take(to_remove) {
508            self.historic.remove(&key);
509        }
510    }
511
512    fn record_recently_closed(&self, key: ConnectionKey, conn: &Connection, now: SystemTime) {
513        if !conn.is_terminal() {
514            return;
515        }
516        self.recently_closed
517            .lock()
518            .unwrap_or_else(std::sync::PoisonError::into_inner)
519            .insert(key, now);
520    }
521
522    fn prune_recently_closed(&self, now: SystemTime) {
523        let mut recently_closed = self
524            .recently_closed
525            .lock()
526            .unwrap_or_else(std::sync::PoisonError::into_inner);
527        recently_closed.retain(|_, closed_at| {
528            now.duration_since(*closed_at).unwrap_or_default() <= RECENTLY_CLOSED_TTL
529        });
530        let max_entries = self.config.max_historic.max(RECENTLY_CLOSED_MIN_ENTRIES);
531        if recently_closed.len() > max_entries {
532            let mut entries: Vec<(ConnectionKey, SystemTime)> = recently_closed
533                .iter()
534                .map(|(key, closed_at)| (*key, *closed_at))
535                .collect();
536            entries.sort_by_key(|(_, closed_at)| *closed_at);
537            let to_remove = recently_closed.len() - max_entries;
538            for (key, _) in entries.into_iter().take(to_remove) {
539                recently_closed.remove(&key);
540            }
541        }
542    }
543
544    fn remove_quic_mappings_for_key(&self, key: ConnectionKey) {
545        if let Ok(mut mapping) = self.quic_map.lock() {
546            mapping.retain(|_, conn_key| *conn_key != key);
547        }
548    }
549
550    /// Remove connections whose protocol-aware timeout has elapsed as of `now`.
551    ///
552    /// Removed connections are archived into the historic table (when
553    /// [`keep_historic`](TrackerConfig::keep_historic) is set, subject to
554    /// [`max_historic`](TrackerConfig::max_historic) eviction) and their QUIC
555    /// mappings are dropped. Returns the removed connections (in their original,
556    /// pre-archive form) so callers can emit close events or export them.
557    pub fn cleanup(&self, now: SystemTime) -> Vec<Connection> {
558        let _lifecycle = self
559            .lifecycle
560            .write()
561            .unwrap_or_else(std::sync::PoisonError::into_inner);
562        let mut removed: Vec<Connection> = Vec::new();
563        let mut removed_keys: Vec<ConnectionKey> = Vec::new();
564        let mut to_archive: Vec<(HistoricKey, Connection)> = Vec::new();
565        let keep_historic = self.config.keep_historic;
566
567        self.connections.retain(|key, conn| {
568            let should_keep = !conn.should_cleanup(now);
569            if !should_keep {
570                removed_keys.push(*key);
571                removed.push(conn.clone());
572
573                // Archive a historic copy. The historic key includes created_at
574                // so multiple closed connections sharing a 4-tuple don't clobber
575                // each other. snapshot_clone: historic connections never refresh
576                // their rates, so don't pin the (potentially large) sample
577                // buffer in the archive.
578                if keep_historic {
579                    let mut historic = conn.snapshot_clone();
580                    historic.is_historic = true;
581                    historic.closed_at = Some(now);
582                    // Cached rates describe live traffic. Carrying them into a
583                    // closed record makes Overview and Details report traffic
584                    // that can no longer occur, and leaves a moving fallback
585                    // point after the live rate history is retired.
586                    historic.current_incoming_rate_bps = 0.0;
587                    historic.current_outgoing_rate_bps = 0.0;
588                    let historic_key = HistoricKey {
589                        key: *key,
590                        created_nanos: conn
591                            .created_at
592                            .duration_since(SystemTime::UNIX_EPOCH)
593                            .unwrap_or_default()
594                            .as_nanos(),
595                    };
596                    to_archive.push((historic_key, historic));
597                }
598            }
599            should_keep
600        });
601        if !removed.is_empty() {
602            self.active_count
603                .fetch_sub(removed.len(), Ordering::Relaxed);
604            for (key, conn) in removed_keys.iter().zip(&removed) {
605                self.record_recently_closed(*key, conn, now);
606            }
607        }
608
609        if keep_historic {
610            for (key, conn) in to_archive {
611                self.historic.insert(key, conn);
612            }
613
614            self.enforce_historic_limit();
615        }
616
617        // Clean up QUIC connection-ID mappings pointing at removed connections.
618        if !removed_keys.is_empty()
619            && let Ok(mut mapping) = self.quic_map.lock()
620        {
621            mapping.retain(|_, conn_key| !removed_keys.contains(conn_key));
622        }
623        self.prune_recently_closed(now);
624
625        removed
626    }
627
628    /// A point-in-time copy of the active connections.
629    ///
630    /// Note: this is a full clone, including each connection's rate-sample
631    /// buffer — the buffer is shared via `Arc`, so the *next* per-packet
632    /// update on a live connection pays a copy-on-write deep copy. Callers
633    /// that only need the cached `current_*_rate_bps` fields (any read-only
634    /// view) should prefer [`Connection::snapshot_clone`] over the entries of
635    /// [`connections`](Self::connections) to keep the packet path allocation-
636    /// free.
637    pub fn snapshot(&self) -> Vec<Connection> {
638        self.connections
639            .iter()
640            .map(|entry| entry.value().clone())
641            .collect()
642    }
643
644    /// A point-in-time copy of the historic (recently-closed) connections.
645    pub fn historic_snapshot(&self) -> Vec<Connection> {
646        self.historic
647            .iter()
648            .map(|entry| entry.value().clone())
649            .collect()
650    }
651
652    /// Inspect the active and historic maps as one consistent retained view.
653    ///
654    /// Cleanup cannot move a connection between the maps while `inspect` is
655    /// running. Packet updates may still update active rows through DashMap's
656    /// per-entry locking.
657    pub fn with_retained_sources<R>(
658        &self,
659        inspect: impl FnOnce(&ConnectionMap, &HistoricMap) -> R,
660    ) -> R {
661        let _lifecycle = self
662            .lifecycle
663            .read()
664            .unwrap_or_else(std::sync::PoisonError::into_inner);
665        inspect(&self.connections, &self.historic)
666    }
667
668    /// Number of active connections.
669    pub fn len(&self) -> usize {
670        self.connections.len()
671    }
672
673    /// `true` if there are no active connections.
674    pub fn is_empty(&self) -> bool {
675        self.connections.is_empty()
676    }
677
678    /// Number of historic (recently-closed) connections.
679    pub fn historic_len(&self) -> usize {
680        self.historic.len()
681    }
682
683    /// Drop all active and historic connections and reset RTT/QUIC state.
684    pub fn clear(&self) {
685        let _lifecycle = self
686            .lifecycle
687            .write()
688            .unwrap_or_else(std::sync::PoisonError::into_inner);
689        self.connections.clear();
690        self.active_count.store(0, Ordering::Relaxed);
691        self.historic.clear();
692        if let Ok(mut tracker) = self.rtt.lock() {
693            tracker.clear();
694        }
695        if let Ok(mut mapping) = self.quic_map.lock() {
696            mapping.clear();
697        }
698        self.recently_closed
699            .lock()
700            .unwrap_or_else(std::sync::PoisonError::into_inner)
701            .clear();
702    }
703
704    /// The tracker's configuration.
705    pub fn config(&self) -> &TrackerConfig {
706        &self.config
707    }
708
709    /// Direct access to the active connection table.
710    ///
711    /// Use this for in-place enrichment (e.g. attaching process, DNS, or GeoIP
712    /// information via `iter_mut`) or custom reads. Lifecycle changes should go
713    /// through [`ingest`](Self::ingest) and [`cleanup`](Self::cleanup) so the
714    /// connection-count limit, RTT, and QUIC coalescing stay consistent —
715    /// inserting or removing entries directly desyncs the internal counter
716    /// backing the `max_connections` check.
717    pub fn connections(&self) -> &ConnectionMap {
718        &self.connections
719    }
720
721    /// Direct access to the historic (recently-closed) connection table.
722    pub fn historic(&self) -> &HistoricMap {
723        &self.historic
724    }
725
726    /// Average RTT (in milliseconds) over the last `window_secs` seconds of
727    /// SYN/SYN-ACK samples, consuming the samples in that window. `None` if no
728    /// samples are available.
729    pub fn take_average_rtt(&self, window_secs: u64) -> Option<f64> {
730        self.rtt
731            .lock()
732            .ok()
733            .and_then(|mut tracker| tracker.take_average_rtt(window_secs))
734    }
735}
736
737impl Default for ConnectionTracker {
738    fn default() -> Self {
739        Self::new()
740    }
741}
742
743#[cfg(test)]
744mod tests {
745    use super::*;
746    use crate::network::parser::PacketParser;
747
748    /// A minimal Ethernet+IPv4+UDP frame, parsed into a `ParsedPacket` so we can
749    /// exercise the tracker with a realistic input.
750    fn udp_frame(src_port: u16, dst_port: u16) -> Vec<u8> {
751        let mut f = Vec::new();
752        // Ethernet header: dst mac, src mac, ethertype IPv4 (0x0800)
753        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 1]);
754        f.extend_from_slice(&[0x02, 0, 0, 0, 0, 2]);
755        f.extend_from_slice(&[0x08, 0x00]);
756        // IPv4 header (20 bytes)
757        let ip_total_len = (20 + 8u16).to_be_bytes(); // ip header + udp header
758        f.extend_from_slice(&[0x45, 0x00]);
759        f.extend_from_slice(&ip_total_len);
760        f.extend_from_slice(&[0, 0, 0, 0]); // id, flags/frag
761        f.push(64); // ttl
762        f.push(17); // protocol = UDP
763        f.extend_from_slice(&[0, 0]); // checksum
764        f.extend_from_slice(&[192, 168, 0, 1]); // src ip
765        f.extend_from_slice(&[192, 168, 0, 2]); // dst ip
766        // UDP header (8 bytes)
767        f.extend_from_slice(&src_port.to_be_bytes());
768        f.extend_from_slice(&dst_port.to_be_bytes());
769        f.extend_from_slice(&8u16.to_be_bytes()); // length
770        f.extend_from_slice(&[0, 0]); // checksum
771        f
772    }
773
774    fn parse(frame: &[u8]) -> ParsedPacket {
775        PacketParser::new()
776            .parse_packet(frame)
777            .expect("frame should parse")
778    }
779
780    fn tcp_packet(syn: bool, ack: bool, fin: bool, rst: bool, is_outgoing: bool) -> ParsedPacket {
781        use crate::network::protocol::tcp::{TcpFlags, TcpHeaderInfo};
782        use crate::network::types::{ProtocolState, TcpState};
783        use std::net::{IpAddr, Ipv4Addr, SocketAddr};
784
785        ParsedPacket {
786            protocol: Protocol::Tcp,
787            local_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 1)), 40_000),
788            remote_addr: SocketAddr::new(IpAddr::V4(Ipv4Addr::new(192, 168, 0, 2)), 443),
789            protocol_state: ProtocolState::Tcp(TcpState::Unknown),
790            tcp_header: Some(TcpHeaderInfo {
791                seq: 1_000,
792                ack: 2_000,
793                window: 65_535,
794                flags: TcpFlags {
795                    syn,
796                    ack,
797                    fin,
798                    rst,
799                    psh: false,
800                    urg: false,
801                },
802                payload_len: 0,
803            }),
804            is_outgoing,
805            packet_len: 60,
806            dpi_result: None,
807            process_name: None,
808            process_id: None,
809        }
810    }
811
812    #[test]
813    fn ingest_creates_then_updates() {
814        let tracker = ConnectionTracker::new();
815        let p = parse(&udp_frame(40000, 53));
816
817        let first = tracker.ingest(&p);
818        assert!(first.created, "first packet should create a connection");
819        assert!(!first.dropped);
820        assert_eq!(tracker.len(), 1);
821
822        let second = tracker.ingest(&p);
823        assert!(!second.created, "second packet should update, not create");
824        assert_eq!(second.key, first.key);
825        assert_eq!(tracker.len(), 1);
826    }
827
828    #[test]
829    fn distinct_flows_are_separate_connections() {
830        let tracker = ConnectionTracker::new();
831        tracker.ingest(&parse(&udp_frame(40000, 53)));
832        tracker.ingest(&parse(&udp_frame(40001, 53)));
833        assert_eq!(tracker.len(), 2);
834    }
835
836    #[test]
837    fn max_connections_limit_drops_new_only() {
838        let tracker = ConnectionTracker::with_config(TrackerConfig {
839            max_connections: 1,
840            ..TrackerConfig::default()
841        });
842        let a = tracker.ingest(&parse(&udp_frame(40000, 53)));
843        assert!(a.created && !a.dropped);
844
845        // A different flow can't be inserted (limit reached) and is dropped.
846        let b = tracker.ingest(&parse(&udp_frame(40001, 53)));
847        assert!(b.dropped, "new connection beyond the limit must be dropped");
848        assert!(!b.created);
849        assert_eq!(tracker.len(), 1);
850
851        // The existing flow still updates despite the limit.
852        let a2 = tracker.ingest(&parse(&udp_frame(40000, 53)));
853        assert!(!a2.dropped && !a2.created);
854    }
855
856    #[test]
857    fn connection_limit_recovers_after_cleanup() {
858        let tracker = ConnectionTracker::with_config(TrackerConfig {
859            max_connections: 1,
860            ..TrackerConfig::default()
861        });
862        assert!(tracker.ingest(&parse(&udp_frame(40000, 53))).created);
863        assert!(tracker.ingest(&parse(&udp_frame(40001, 53))).dropped);
864
865        // Expire everything; the limit accounting must follow the removals.
866        tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
867        assert_eq!(tracker.len(), 0);
868
869        let c = tracker.ingest(&parse(&udp_frame(40002, 53)));
870        assert!(
871            c.created && !c.dropped,
872            "slot freed by cleanup must be reusable"
873        );
874        assert_eq!(tracker.len(), 1);
875    }
876
877    #[test]
878    fn connection_limit_recovers_after_clear() {
879        let tracker = ConnectionTracker::with_config(TrackerConfig {
880            max_connections: 1,
881            ..TrackerConfig::default()
882        });
883        assert!(tracker.ingest(&parse(&udp_frame(40000, 53))).created);
884        tracker.clear();
885        let b = tracker.ingest(&parse(&udp_frame(40001, 53)));
886        assert!(b.created && !b.dropped, "clear() must reset the limit");
887    }
888
889    #[test]
890    fn cleanup_archives_to_historic() {
891        let tracker = ConnectionTracker::new();
892        tracker.ingest(&parse(&udp_frame(40000, 53)));
893        assert_eq!(tracker.len(), 1);
894
895        for mut entry in tracker.connections().iter_mut() {
896            entry.current_incoming_rate_bps = 2048.0;
897            entry.current_outgoing_rate_bps = 1024.0;
898        }
899
900        // A far-future `now` forces every connection past its timeout.
901        let far_future = SystemTime::now() + Duration::from_secs(86_400);
902        let removed = tracker.cleanup(far_future);
903
904        assert_eq!(removed.len(), 1, "the idle connection should be removed");
905        assert!(!removed[0].is_historic, "returned form is the original");
906        assert_eq!(tracker.len(), 0);
907        assert_eq!(
908            tracker.historic_len(),
909            1,
910            "removed conn archived as historic"
911        );
912        let historic = tracker.historic().iter().next().unwrap();
913        assert_eq!(historic.current_incoming_rate_bps, 0.0);
914        assert_eq!(historic.current_outgoing_rate_bps, 0.0);
915    }
916
917    #[test]
918    fn traffic_refreshes_a_stale_nonterminal_connection() {
919        let tracker = ConnectionTracker::new();
920        let packet = parse(&udp_frame(40000, 9999));
921        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
922        tracker.ingest_at(&packet, started);
923
924        assert!(
925            tracker
926                .cleanup(started + Duration::from_secs(59))
927                .is_empty()
928        );
929        tracker.ingest_at(&packet, started + Duration::from_secs(59));
930        assert!(
931            tracker
932                .cleanup(started + Duration::from_secs(61))
933                .is_empty()
934        );
935        assert_eq!(tracker.len(), 1);
936    }
937
938    #[test]
939    fn terminal_retransmissions_do_not_postpone_archival() {
940        let tracker = ConnectionTracker::new();
941        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
942        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
943        tracker.ingest_at(
944            &tcp_packet(false, true, false, false, false),
945            started + Duration::from_secs(10),
946        );
947
948        let conn = tracker.connections().iter().next().unwrap();
949        assert_eq!(conn.last_activity, started + Duration::from_secs(10));
950        assert_eq!(conn.terminal_since, Some(started));
951        drop(conn);
952
953        let removed = tracker.cleanup(started + Duration::from_secs(16));
954        assert_eq!(removed.len(), 1);
955        assert_eq!(tracker.historic_len(), 1);
956    }
957
958    #[test]
959    fn syn_after_terminal_state_starts_a_new_generation() {
960        use crate::network::types::{ProtocolState, TcpState};
961
962        let tracker = ConnectionTracker::new();
963        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
964        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
965
966        let outcome = tracker.ingest_at(&tcp_packet(true, false, false, false, true), started);
967        assert!(outcome.created);
968        assert!(outcome.archived.is_some());
969        assert_eq!(tracker.len(), 1);
970        assert_eq!(tracker.historic_len(), 1);
971
972        let active = tracker.connections().iter().next().unwrap();
973        assert_eq!(
974            active.created_at,
975            started + Duration::from_nanos(1),
976            "a same-batch replacement needs a distinct historic identity"
977        );
978        assert!(matches!(
979            active.protocol_state,
980            ProtocolState::Tcp(TcpState::SynSent)
981        ));
982        assert!(!active.is_historic);
983        drop(active);
984
985        let historic = tracker.historic().iter().next().unwrap();
986        assert_eq!(historic.created_at, started);
987        assert!(historic.is_historic);
988        assert_eq!(historic.closed_at, Some(started));
989        drop(historic);
990
991        tracker.cleanup(started + Duration::from_secs(61));
992        assert_eq!(
993            tracker.historic_len(),
994            2,
995            "archiving the replacement must not overwrite the old generation"
996        );
997    }
998
999    #[test]
1000    fn delayed_ack_after_archival_is_not_a_phantom_connection() {
1001        let tracker = ConnectionTracker::new();
1002        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1003        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
1004        tracker.cleanup(started + Duration::from_secs(16));
1005
1006        let outcome = tracker.ingest_at(
1007            &tcp_packet(false, true, false, false, false),
1008            started + Duration::from_secs(17),
1009        );
1010        assert!(outcome.ignored_late);
1011        assert!(!outcome.created);
1012        assert!(tracker.is_empty());
1013        assert_eq!(tracker.historic_len(), 1);
1014    }
1015
1016    #[test]
1017    fn payload_after_terminal_archival_starts_a_new_generation() {
1018        let tracker = ConnectionTracker::new();
1019        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1020        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
1021        tracker.cleanup(started + Duration::from_secs(16));
1022
1023        let mut packet = tcp_packet(false, true, false, false, false);
1024        packet.tcp_header.as_mut().unwrap().payload_len = 100;
1025        let outcome = tracker.ingest_at(&packet, started + Duration::from_secs(17));
1026
1027        assert!(!outcome.ignored_late);
1028        assert!(outcome.created);
1029        assert_eq!(tracker.len(), 1);
1030        assert_eq!(tracker.historic_len(), 1);
1031    }
1032
1033    #[test]
1034    fn traffic_after_idle_archival_starts_a_new_generation_immediately() {
1035        let tracker = ConnectionTracker::new();
1036        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1037        tracker.ingest_at(&tcp_packet(false, true, false, false, true), started);
1038        tracker.cleanup(started + Duration::from_secs(301));
1039
1040        let outcome = tracker.ingest_at(
1041            &tcp_packet(false, true, false, false, false),
1042            started + Duration::from_secs(302),
1043        );
1044        assert!(!outcome.ignored_late);
1045        assert!(outcome.created);
1046        assert_eq!(tracker.len(), 1);
1047        assert_eq!(tracker.historic_len(), 1);
1048    }
1049
1050    #[test]
1051    fn midstream_ack_is_allowed_after_recent_tombstone_expires() {
1052        use crate::network::types::{ProtocolState, TcpState};
1053
1054        let tracker = ConnectionTracker::new();
1055        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1056        tracker.ingest_at(&tcp_packet(false, false, false, true, true), started);
1057        tracker.cleanup(started + Duration::from_secs(16));
1058
1059        let outcome = tracker.ingest_at(
1060            &tcp_packet(false, true, false, false, false),
1061            started + Duration::from_secs(47),
1062        );
1063        assert!(!outcome.ignored_late);
1064        assert!(outcome.created);
1065        let active = tracker.connections().iter().next().unwrap();
1066        assert!(matches!(
1067            active.protocol_state,
1068            ProtocolState::Tcp(TcpState::Established)
1069        ));
1070    }
1071
1072    #[test]
1073    fn new_activity_does_not_mutate_a_historic_snapshot() {
1074        let tracker = ConnectionTracker::new();
1075        let packet = parse(&udp_frame(40000, 9999));
1076        let started = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1077        tracker.ingest_at(&packet, started);
1078        tracker.cleanup(started + Duration::from_secs(61));
1079
1080        let historic_before = tracker.historic_snapshot().pop().unwrap();
1081        tracker.ingest_at(&packet, started + Duration::from_secs(62));
1082        tracker.ingest_at(&packet, started + Duration::from_secs(63));
1083        let historic_after = tracker.historic_snapshot().pop().unwrap();
1084
1085        assert_eq!(historic_after.bytes_sent, historic_before.bytes_sent);
1086        assert_eq!(
1087            historic_after.bytes_received,
1088            historic_before.bytes_received
1089        );
1090        assert_eq!(historic_after.last_activity, historic_before.last_activity);
1091        assert_eq!(historic_after.closed_at, historic_before.closed_at);
1092        assert_eq!(tracker.len(), 1);
1093    }
1094
1095    #[test]
1096    fn retained_source_view_is_atomic_across_cleanup() {
1097        let tracker = std::sync::Arc::new(ConnectionTracker::new());
1098        tracker.ingest(&parse(&udp_frame(40000, 53)));
1099
1100        let (active_scanned_tx, active_scanned_rx) = std::sync::mpsc::channel();
1101        let (release_tx, release_rx) = std::sync::mpsc::channel();
1102        let reader_tracker = std::sync::Arc::clone(&tracker);
1103        let reader = std::thread::spawn(move || {
1104            reader_tracker.with_retained_sources(|active, historic| {
1105                let active_count = active.iter().count();
1106                active_scanned_tx.send(()).unwrap();
1107                release_rx.recv().unwrap();
1108                active_count + historic.iter().count()
1109            })
1110        });
1111
1112        active_scanned_rx.recv().unwrap();
1113        let (cleanup_started_tx, cleanup_started_rx) = std::sync::mpsc::channel();
1114        let (cleanup_done_tx, cleanup_done_rx) = std::sync::mpsc::channel();
1115        let cleanup_tracker = std::sync::Arc::clone(&tracker);
1116        let cleanup = std::thread::spawn(move || {
1117            cleanup_started_tx.send(()).unwrap();
1118            let removed = cleanup_tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
1119            cleanup_done_tx.send(removed.len()).unwrap();
1120        });
1121
1122        cleanup_started_rx.recv().unwrap();
1123        assert!(
1124            cleanup_done_rx
1125                .recv_timeout(Duration::from_millis(50))
1126                .is_err(),
1127            "cleanup must wait for the retained source view"
1128        );
1129        release_tx.send(()).unwrap();
1130
1131        assert_eq!(reader.join().unwrap(), 1);
1132        assert_eq!(cleanup_done_rx.recv().unwrap(), 1);
1133        cleanup.join().unwrap();
1134        assert_eq!(tracker.len(), 0);
1135        assert_eq!(tracker.historic_len(), 1);
1136    }
1137
1138    #[test]
1139    fn cleanup_without_keep_historic_skips_archive() {
1140        let tracker = ConnectionTracker::with_config(TrackerConfig {
1141            keep_historic: false,
1142            ..TrackerConfig::default()
1143        });
1144        tracker.ingest(&parse(&udp_frame(40000, 53)));
1145        let far_future = SystemTime::now() + Duration::from_secs(86_400);
1146        let removed = tracker.cleanup(far_future);
1147        assert_eq!(removed.len(), 1);
1148        assert_eq!(tracker.historic_len(), 0, "historic disabled");
1149    }
1150
1151    /// `max_historic` sizes the user-facing archive; it must not shrink the
1152    /// tombstone table below the floor, or closing more flows than the cap
1153    /// lets delayed teardown packets resurrect phantom connections.
1154    #[test]
1155    fn zero_max_historic_keeps_tombstones_for_all_closed_flows() {
1156        let tracker = ConnectionTracker::with_config(TrackerConfig {
1157            keep_historic: false,
1158            max_historic: 0,
1159            ..TrackerConfig::default()
1160        });
1161
1162        let start = SystemTime::now();
1163        for port in [40_000u16, 40_001] {
1164            let mut syn = tcp_packet(true, false, false, false, true);
1165            syn.local_addr.set_port(port);
1166            tracker.ingest_at(&syn, start);
1167            let mut rst = tcp_packet(false, false, false, true, true);
1168            rst.local_addr.set_port(port);
1169            tracker.ingest_at(&rst, start + Duration::from_secs(1));
1170        }
1171        assert_eq!(tracker.len(), 2);
1172
1173        let closed_at = start + Duration::from_secs(86_400);
1174        let removed = tracker.cleanup(closed_at);
1175        assert_eq!(removed.len(), 2);
1176
1177        for port in [40_000u16, 40_001] {
1178            let mut late_fin = tcp_packet(false, true, true, false, true);
1179            late_fin.local_addr.set_port(port);
1180            let outcome = tracker.ingest_at(&late_fin, closed_at + Duration::from_secs(1));
1181            assert!(
1182                outcome.ignored_late,
1183                "delayed teardown for port {port} must hit a tombstone"
1184            );
1185        }
1186        assert!(tracker.is_empty(), "no phantom connections may be created");
1187    }
1188
1189    #[test]
1190    fn ingest_at_uses_supplied_time_for_cleanup() {
1191        // A packet ingested "in the past" must be eligible for cleanup at a
1192        // `now` only slightly later than its supplied capture time — proving the
1193        // tracker stamps the connection with the caller's time, not the wall
1194        // clock. (Wall-clock stamping would make `created_at` ~= real now, so a
1195        // cleanup at trace-time + a few minutes would NOT expire it.)
1196        let tracker = ConnectionTracker::new();
1197        let capture_time = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1198        tracker.ingest_at(&parse(&udp_frame(40000, 53)), capture_time);
1199        assert_eq!(tracker.len(), 1);
1200
1201        // One day after the capture time the UDP flow is well past its timeout.
1202        let removed = tracker.cleanup(capture_time + Duration::from_secs(86_400));
1203        assert_eq!(
1204            removed.len(),
1205            1,
1206            "flow stamped at capture time should expire"
1207        );
1208        assert_eq!(tracker.len(), 0);
1209    }
1210
1211    #[test]
1212    fn clear_empties_everything() {
1213        let tracker = ConnectionTracker::new();
1214        tracker.ingest(&parse(&udp_frame(40000, 53)));
1215        tracker.cleanup(SystemTime::now() + Duration::from_secs(86_400));
1216        assert_eq!(tracker.historic_len(), 1);
1217        tracker.clear();
1218        assert!(tracker.is_empty());
1219        assert_eq!(tracker.historic_len(), 0);
1220    }
1221}