Module api 

High-level API for vanguards-rs.

This module provides the Vanguards struct, which is the main entry point for programmatic use of the vanguards-rs library.

Overview

The Vanguards struct combines all protection components into a single interface that can be used to protect Tor hidden services. It manages:

• Connection to Tor’s control port
• Vanguard state persistence and rotation
• All protection component lifecycles
• Event processing and response

Conceptual Role

The Vanguards struct sits at the top of the vanguards-rs architecture, orchestrating all protection components.

Thread Safety

The Vanguards struct is Send but not Sync. For concurrent access from multiple tasks, wrap in Arc<Mutex<Vanguards>>:

use std::sync::Arc;
use tokio::sync::Mutex;
use vanguards_rs::{Config, Vanguards};

let config = Config::default();
let vanguards = Vanguards::from_config(config).await?;
let shared = Arc::new(Mutex::new(vanguards));

// Clone Arc for each task
let v1 = shared.clone();
tokio::spawn(async move {
    let guard = v1.lock().await;
    println!("State: {}", guard.state().layer2_guardset());
});

Example

Basic Usage

use vanguards_rs::{Config, Vanguards};

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let config = Config::default();
    let mut vanguards = Vanguards::from_config(config).await?;
    vanguards.run().await
}

With Custom Configuration

use vanguards_rs::{Config, Vanguards, LogLevel};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    let mut config = Config::default();
    config.control_port = Some(9051);
    config.state_file = PathBuf::from("/var/lib/tor/vanguards.state");
    config.loglevel = LogLevel::Debug;
     
    let mut vanguards = Vanguards::from_config(config).await?;
    vanguards.run().await
}

Using an Existing Controller

use vanguards_rs::{Config, Vanguards};
use stem_rs::controller::Controller;

#[tokio::main]
async fn main() -> vanguards_rs::Result<()> {
    // Connect and authenticate manually
    let mut controller = Controller::from_port("127.0.0.1:9051".parse().unwrap()).await?;
    controller.authenticate(None).await?;
     
    // Create Vanguards with existing controller
    let config = Config::default();
    let vanguards = Vanguards::new(controller, config)?;
     
    // Access state without running the loop
    println!("Layer2 guards: {}", vanguards.state().layer2_guardset());
    Ok(())
}

Security

• Passwords are cleared from memory after authentication using [zeroize]
• State files are written with 0600 permissions on Unix
• All inputs are validated before use
• The SecurePassword wrapper ensures passwords don’t leak in debug output

See Also

• Config - Configuration options
• VanguardState - Guard state management
• control::run_main - Main event loop
• Python vanguards - Original implementation

Structs

SecurePassword

A wrapper for sensitive password data that clears itself on drop.

Vanguards

Main vanguards manager combining all protection components.