Struct BwWeightedGenerator 

pub struct BwWeightedGenerator { /* private fields */ }

Bandwidth-weighted node generator.

Implements bandwidth-weighted random selection of relay nodes. Selection probability is proportional to each relay’s bandwidth weight.

Weight Calculation

The weight for each relay is calculated as:

weight = measured_bandwidth × flag_weight_multiplier

Where flag_weight_multiplier depends on the relay’s flags and position:

Flags	Middle Position	Guard Position	Exit Position
Neither Guard nor Exit	Wmm	Wgm	Wem
Guard only	Wmg	Wgg	Weg
Exit only	Wme	Wge	Wee
Guard + Exit	Wmd	Wgd	Wed

Selection Algorithm

1. Filter routers through all restrictions
2. Calculate weighted bandwidth for each remaining router
3. Build cumulative weight distribution
4. Generate random value in [0, total_weight)
5. Select router where cumulative weight exceeds random value

Example

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

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)]);

let generator = BwWeightedGenerator::new(routers, restrictions, weights, Position::Middle)?;
let selected = generator.generate()?;
println!("Selected relay: {}", selected.fingerprint);

See Also

• Position - Circuit position affecting weight calculation
• NodeRestrictionList - Filtering criteria
• crate::error::Error::NoNodesRemain - Error when no nodes pass filters

Implementations

impl BwWeightedGenerator

pub fn new( sorted_routers: Vec<RouterStatusEntry>, restrictions: NodeRestrictionList, bw_weights: HashMap<String, i64>, position: Position, ) -> Result<Self>

Creates a new bandwidth-weighted generator.

Arguments

• sorted_routers - Routers sorted by measured bandwidth (descending)
• restrictions - Restrictions to filter routers
• bw_weights - Consensus bandwidth weights (Wmm, Wmg, Wme, Wmd, etc.)
• position - Circuit position for weight calculation

Errors

Returns Error::NoNodesRemain if all routers are filtered out.

Example

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

pub fn repair_exits(&mut self)

Repairs exit node weights for rendezvous point selection.

Exit nodes got their weights set based on middle position, but they can still be used as rendezvous points in cannibalized circuits. This method recalculates their weights using exit position weights and tracks a separate exit_total.

Note: We deliberately don’t re-normalize weight_total since we don’t want to lower the upper bound of other nodes. But we do want a separate exit_total for use with Exit nodes.

pub fn generate(&self) -> Result<&RouterStatusEntry>

Generates a randomly selected router using bandwidth-weighted selection.

Selection probability is proportional to each router’s bandwidth weight.

Returns

A reference to the selected router.

Errors

Returns Error::NoNodesRemain if the router list is empty or total weight is zero.

pub fn weight_total(&self) -> f64

Returns the total weight of all routers.

pub fn exit_total(&self) -> f64

Returns the total weight of exit-flagged routers.

pub fn router_count(&self) -> usize

Returns the number of routers after restrictions.

pub fn routers(&self) -> &[RouterStatusEntry]

Returns a reference to the filtered routers.

pub fn node_weights(&self) -> &[f64]

Returns a reference to the node weights.