Struct VanguardMgr

pub struct VanguardMgr<R: Runtime> {
    inner: RwLock<Inner>,
    runtime: R,
    storage: DynStorageHandle<VanguardSets>,
}

Available on crate feature vanguards only.

The vanguard manager.

Fields

inner: RwLock<Inner>

The mutable state.

runtime: R

The runtime.

storage: DynStorageHandle<VanguardSets>

The persistent storage handle, used for writing the vanguard sets to disk if full vanguards are enabled.

Implementations

impl<R: Runtime> VanguardMgr<R>

pub fn new<S>( config: &VanguardConfig, runtime: R, state_mgr: S, has_onion_svc: bool, ) -> Result<Self, VanguardMgrError>

where S: StateMgr + Send + Sync + 'static,

Create a new VanguardMgr.

The state_mgr handle is used for persisting the “vanguards-full” guard pools to disk.

pub fn launch_background_tasks( self: &Arc<Self>, netdir_provider: &Arc<dyn NetDirProvider>, ) -> Result<(), VanguardMgrError>

where R: Runtime,

Launch the vanguard pool management tasks.

These run until the VanguardMgr is dropped.

pub fn reconfigure( &self, config: &VanguardConfig, ) -> Result<RetireCircuits, ReconfigureError>

Replace the configuration in this VanguardMgr with the specified config.

pub fn select_vanguard<'a, Rng: RngCore>( &self, rng: &mut Rng, netdir: &'a NetDir, layer: Layer, relay_selector: &RelaySelector<'a>, ) -> Result<Vanguard<'a>, VanguardMgrError>

Return a Vanguard relay for use in the specified layer.

The relay_selector must exclude the relays that would neighbor this vanguard in the path.

Specifically, it should exclude

• the last relay in the path (the one immediately preceding the vanguard): the same relay cannot be used in consecutive positions in the path (a relay won’t let you extend the circuit to itself).
• the penultimate relay of the path, if there is one: relays don’t allow extending the circuit to their previous hop

If Full vanguards are in use, this function can be used for selecting both Layer2 and Layer3 vanguards.

If Lite vanguards are in use, this function can only be used for selecting Layer2 vanguards. It will return an error if a Layer3 is requested.

Returns an error if vanguards are disabled.

Returns a NoSuitableRelay error if none of our vanguards satisfy the layer and neighbor_exlusion requirements.

Returns a BootstrapRequired error if called before the vanguard manager has finished bootstrapping, or if all the vanguards have become unusable (by expiring or no longer being listed in the consensus) and we are unable to replenish them.

Example

If the partially built path is of the form G - L2 and we are selecting the L3 vanguard, the RelayExclusion should contain G and L2 (to prevent building a path of the form G - L2 - G, or G - L2 - L2).

If the path only contains the L1 guard (G), then the RelayExclusion should only exclude G.

async fn maintain_vanguard_sets( mgr: Weak<Self>, netdir_provider: Weak<dyn NetDirProvider>, config_rx: Receiver<VanguardConfig>, )

The vanguard set management task.

This is a background task that:

• removes vanguards from the L2 and L3 vanguard sets when they expire
• ensures the vanguard sets are repopulated with new vanguards when the number of vanguards drops below a certain threshold
• handles NetDir changes, updating the vanguard set sizes as needed

async fn run_once( mgr: Weak<Self>, netdir_provider: Weak<dyn NetDirProvider>, netdir_events: &mut BoxStream<'static, DirEvent>, config_rx: &mut Receiver<VanguardConfig>, ) -> Result<ShutdownStatus, VanguardMgrError>

Wait until a vanguard expires or until there is a new NetDir.

This populates the L2 and L3 vanguard sets, and rotates the vanguards when their lifetime expires.

Note: the L3 set is only populated with vanguards if Full vanguards are enabled.

fn timely_netdir( netdir_provider: &Arc<dyn NetDirProvider>, ) -> Result<Option<Arc<NetDir>>, VanguardMgrError>

Return a timely NetDir, if one is available.

Returns None if no directory information is available.

fn rotate_expired( &self, netdir_provider: &Arc<dyn NetDirProvider>, now: SystemTime, ) -> Result<Option<Duration>, VanguardMgrError>

Rotate the vanguards that have expired, returning how long until the next vanguard will expire, or None if there are no vanguards in any of our sets.

pub fn mode(&self) -> VanguardMode

Get the current VanguardMode.

impl VanguardMgr<MockRuntime>

Helpers for tests involving vanguards

pub fn new_testing( rt: &MockRuntime, mode: VanguardMode, ) -> Result<Arc<VanguardMgr<MockRuntime>>, VanguardMgrError>

Available on crate feature testing only.

Create a new VanguardMgr for testing.

pub async fn init_vanguard_sets( self: &Arc<VanguardMgr<MockRuntime>>, netdir: &NetDir, ) -> Result<Arc<TestNetDirProvider>, VanguardMgrError>

Available on crate feature testing only.

Wait until the vanguardmgr has populated its vanguard sets.

Returns a TestNetDirProvider that can be used to notify the VanguardMgr of netdir changes.