Module node_selection 

Node selection and input validation for vanguards-rs.

This module provides bandwidth-weighted node selection for vanguard relay selection, along with input validation functions for fingerprints, IP addresses, and country codes.

Overview

The node selection system implements:

• Input Validation: Functions to validate relay fingerprints, IP addresses, and country codes
• Node Restrictions: Trait-based system for filtering relays by flags and other criteria
• Bandwidth-Weighted Selection: Random selection proportional to relay bandwidth

Bandwidth-Weighted Selection Algorithm

The selection algorithm ensures relays are chosen proportionally to their bandwidth, which helps distribute load across the network while respecting Tor’s consensus weights.

Validation Functions

• is_valid_fingerprint: Validates 40-character hexadecimal relay fingerprints
• is_valid_ip_or_network: Validates IPv4/IPv6 addresses and CIDR networks
• is_valid_country_code: Validates 2-character country codes

Node Selection

The BwWeightedGenerator implements bandwidth-weighted random selection:

use vanguards_rs::node_selection::{BwWeightedGenerator, FlagsRestriction, NodeRestrictionList, Position};

// Create restrictions requiring Fast, Stable, Valid flags
let restriction = FlagsRestriction::new(
    vec!["Fast".to_string(), "Stable".to_string(), "Valid".to_string()],
    vec!["Authority".to_string()],
);
let restrictions = NodeRestrictionList::new(vec![Box::new(restriction)]);

// Create generator with consensus weights
let generator = BwWeightedGenerator::new(routers, restrictions, weights, Position::Middle)?;

// Generate nodes
let node = generator.generate()?;

What This Module Does NOT Do

• Consensus fetching: Use [stem_rs::descriptor::remote] to fetch consensus data
• Guard persistence: Use crate::vanguards::VanguardState for state management
• Circuit building: This module only selects nodes; circuit construction is handled elsewhere

Security Considerations

• Bandwidth weighting prevents attackers from easily positioning malicious relays
• Flag restrictions ensure only qualified relays are selected for sensitive positions
• The random selection uses a cryptographically secure random number generator

See Also

• crate::error::Error::NoNodesRemain - Error when all nodes are filtered
• crate::vanguards - Vanguard state management using selected nodes
• crate::config - Configuration for node selection parameters
• Python vanguards NodeSelection

Structs

BwWeightedGenerator

Bandwidth-weighted node generator.

FlagsRestriction

Restriction for mandatory and forbidden router flags.

NodeRestrictionList

A list of node restrictions to apply.

Enums

Position

Position in circuit for weight calculation.

Traits

NodeRestriction

Interface for node restriction policies.

Functions

is_valid_country_code

Validates that a string is a valid 2-character country code.

is_valid_fingerprint

Validates that a string is a valid relay fingerprint.

is_valid_ip_or_network

Validates that a string is a valid IP address or CIDR network.