Struct BandwidthStats 

pub struct BandwidthStats {
    pub circs: HashMap<String, BwCircuitStat>,
    pub live_guard_conns: HashMap<String, BwGuardStat>,
    pub guards: HashMap<String, BwGuardStat>,
    pub circs_destroyed_total: u64,
    pub no_conns_since: Option<f64>,
    pub no_circs_since: Option<f64>,
    pub network_down_since: Option<f64>,
    pub max_fake_id: i32,
    pub disconnected_circs: bool,
    pub disconnected_conns: bool,
}

Main bandwidth monitoring state for attack detection.

Tracks all circuit and guard connection statistics for bandwidth monitoring. This is the primary interface for the bandguards protection system.

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         BandwidthStats                                   │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Circuit Tracking (circs: HashMap<String, BwCircuitStat>)        │    │
│  │ • Per-circuit bandwidth statistics                              │    │
│  │ • Dropped cell detection                                        │    │
│  │ • Purpose and state tracking                                    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Guard Tracking (guards: HashMap<String, BwGuardStat>)           │    │
│  │ • Connection state per guard                                    │    │
│  │ • Killed connection correlation                                 │    │
│  │ • Close reason tracking                                         │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Connectivity Tracking                                           │    │
│  │ • no_conns_since: When all guard connections were lost          │    │
│  │ • no_circs_since: When all circuits started failing             │    │
│  │ • network_down_since: When network liveness went down           │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

Event Handling

This struct processes several Tor event types:

Event	Method	Purpose
ORCONN	orconn_event	Guard connection state changes
CIRC	circ_event	Circuit state changes
CIRC_MINOR	circ_minor_event	Purpose changes
CIRC_BW	circbw_event	Bandwidth updates
BW	check_connectivity	Periodic connectivity checks
NETWORK_LIVENESS	network_liveness_event	Network state changes

Example

use vanguards_rs::bandguards::BandwidthStats;
use vanguards_rs::config::BandguardsConfig;

let mut stats = BandwidthStats::new();
let config = BandguardsConfig::default();

// Track a guard connection
stats.orconn_event("1", &"A".repeat(40), "CONNECTED", None, 1000.0);

// Track a circuit
stats.circ_event("123", "LAUNCHED", "GENERAL", None, &[], None, 1000.0);
stats.circ_event("123", "BUILT", "GENERAL", None, &["A".repeat(40)], None, 1001.0);

// Check connectivity
let status = stats.check_connectivity(1002.0, &config);

See Also

• BwCircuitStat - Per-circuit statistics
• BwGuardStat - Per-guard statistics
• CircuitLimitResult - Limit check results
• ConnectivityStatus - Connectivity check results

Fields

circs: HashMap<String, BwCircuitStat>

Circuit statistics by circuit ID.

live_guard_conns: HashMap<String, BwGuardStat>

Live guard connections by connection ID.

guards: HashMap<String, BwGuardStat>

All guard statistics by fingerprint.

circs_destroyed_total: u64

Total circuits destroyed.

no_conns_since: Option<f64>

Timestamp when all connections were lost (None if connected).

no_circs_since: Option<f64>

Timestamp when circuits started failing (None if working).

network_down_since: Option<f64>

Timestamp when network went down (None if up).

max_fake_id: i32

Maximum fake ID used for initial orconn-status entries.

disconnected_circs: bool

Whether we’re currently disconnected (circuits failing).

disconnected_conns: bool

Whether we’re currently disconnected (no connections).

Implementations

impl BandwidthStats

pub fn new() -> Self

Creates a new bandwidth stats tracker.

pub fn orconn_event( &mut self, conn_id: &str, guard_fp: &str, status: &str, reason: Option<&str>, arrived_at: f64, )

Handles an ORCONN event.

Tracks guard connection state changes. When a connection closes, marks any circuits using that guard as possibly destroyed.

Arguments

• conn_id - Connection ID
• guard_fp - Guard fingerprint
• status - Connection status (CONNECTED, CLOSED, FAILED)
• reason - Close reason (for CLOSED status)
• arrived_at - Event timestamp

pub fn circ_event( &mut self, circ_id: &str, status: &str, purpose: &str, hs_state: Option<&str>, path: &[String], remote_reason: Option<&str>, arrived_at: f64, ) -> Option<bool>

Handles a CIRC event.

Tracks circuit state changes including creation, building, and closure.

Arguments

• circ_id - Circuit ID
• status - Circuit status (LAUNCHED, BUILT, EXTENDED, FAILED, CLOSED)
• purpose - Circuit purpose
• hs_state - Hidden service state
• path - Circuit path (list of relay fingerprints)
• remote_reason - Remote close reason
• arrived_at - Event timestamp

Returns

Some(true) if circuit was destroyed due to guard connection closure, Some(false) if circuit was closed normally, None otherwise.

pub fn circ_minor_event( &mut self, circ_id: &str, event_type: &str, purpose: &str, hs_state: Option<&str>, old_purpose: Option<&str>, old_hs_state: Option<&str>, path: &[String], )

Handles a CIRC_MINOR event (purpose changes).

Tracks circuit purpose changes, particularly from HS_VANGUARDS to actual HS purposes.

Arguments

• circ_id - Circuit ID
• event_type - Event type (PURPOSE_CHANGED, etc.)
• purpose - New circuit purpose
• hs_state - New hidden service state
• old_purpose - Previous circuit purpose
• old_hs_state - Previous hidden service state
• path - Circuit path

pub fn circbw_event( &mut self, circ_id: &str, read: u64, written: u64, delivered_read: u64, delivered_written: u64, overhead_read: u64, overhead_written: u64, _arrived_at: f64, )

Handles a CIRC_BW event (bandwidth update).

Updates circuit bandwidth statistics and checks limits.

Arguments

• circ_id - Circuit ID
• read - Bytes read
• written - Bytes written
• delivered_read - Delivered read bytes
• delivered_written - Delivered written bytes
• overhead_read - Overhead read bytes
• overhead_written - Overhead written bytes
• arrived_at - Event timestamp

pub fn check_circuit_limits( &self, circ_id: &str, config: &BandguardsConfig, ) -> CircuitLimitResult

Checks circuit limits and returns circuits that should be closed.

Checks for:

• Dropped cells (potential attack)
• Maximum bytes exceeded
• Maximum HSDIR bytes exceeded
• Maximum service intro bytes exceeded

Arguments

• circ_id - Circuit ID to check
• config - Bandguards configuration

Returns

A CircuitLimitResult indicating whether the circuit should be closed and why.

pub fn get_aged_circuits(&self, config: &BandguardsConfig) -> Vec<String>

Returns circuits that have exceeded the maximum age.

Arguments

• config - Bandguards configuration

Returns

A list of circuit IDs that should be closed due to age.

pub fn check_connectivity( &mut self, now: f64, config: &BandguardsConfig, ) -> ConnectivityStatus

Checks connectivity status and returns warnings if disconnected.

Arguments

• now - Current timestamp
• config - Bandguards configuration

Returns

A ConnectivityStatus indicating the current connectivity state.

pub fn network_liveness_event(&mut self, status: &str, arrived_at: f64)

Handles a NETWORK_LIVENESS event.

Arguments

• status - Network status (“UP” or “DOWN”)
• arrived_at - Event timestamp

pub fn circuit_count(&self) -> usize

Returns the number of tracked circuits.

pub fn live_connection_count(&self) -> usize

Returns the number of live guard connections.

Trait Implementations

impl Clone for BandwidthStats

fn clone(&self) -> BandwidthStats

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BandwidthStats

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for BandwidthStats

fn default() -> Self

Returns the “default value” for a type.