Module error 

Error types for vanguards-rs.

This module defines the Error enum representing all possible error conditions in the vanguards-rs library. Each variant provides specific information about the failure and guidance on recovery.

Overview

The error system is designed to provide:

• Specific error types for different failure categories
• Recovery guidance for each error type
• Seamless integration with stem-rs errors
• Informative messages without leaking sensitive data

Error Categories

  Error
  ├── Io                     ◄── File/network I/O failures
  ├── Config                 ◄── Invalid configuration
  ├── Control                ◄── Tor control protocol errors (from stem-rs)
  ├── State                  ◄── State file corruption/format issues
  ├── Consensus              ◄── Consensus parsing failures
  ├── NoNodesRemain          ◄── All relays filtered out
  ├── Validation             ◄── Invalid input data
  └── DescriptorUnavailable  ◄── Missing descriptors

Recovery Guide

Error	Recoverable	Retry	Recommended Action
Io	Sometimes	Yes (backoff)	Check permissions, disk space
Config	No	No	Fix configuration file
Control	Sometimes	Yes	Reconnect to Tor
State	Sometimes	No	Delete state file, restart
Consensus	Sometimes	Yes	Wait for new consensus
NoNodesRemain	No	No	Adjust ExcludeNodes
Validation	No	No	Fix input data
DescriptorUnavailable	Yes	Yes	Wait for bootstrap

Example

Basic Error Handling

use vanguards_rs::{Config, Error, Result};

fn load_config() -> Result<Config> {
    let config = Config::from_file(std::path::Path::new("vanguards.conf"))?;
    config.validate()?;
    Ok(config)
}

fn main() {
    match load_config() {
        Ok(config) => println!("Config loaded successfully"),
        Err(Error::Io(e)) => eprintln!("File error: {}", e),
        Err(Error::Config(msg)) => eprintln!("Config error: {}", msg),
        Err(e) => eprintln!("Other error: {}", e),
    }
}

Retry Logic

use vanguards_rs::{Error, Result};
use std::time::Duration;

async fn with_retry<F, T>(mut f: F, max_retries: u32) -> Result<T>
where
    F: FnMut() -> Result<T>,
{
    let mut attempts = 0;
    loop {
        match f() {
            Ok(result) => return Ok(result),
            Err(Error::Io(_)) | Err(Error::Control(_)) if attempts < max_retries => {
                attempts += 1;
                tokio::time::sleep(Duration::from_secs(1 << attempts)).await;
            }
            Err(e) => return Err(e),
        }
    }
}

See Also

• Result - Type alias for std::result::Result<T, Error>
• [stem_rs::Error] - Underlying Tor control errors
• Config::validate - Configuration validation

Enums

Error

Errors that can occur during vanguards-rs operations.

Type Aliases

Result

Result type alias for vanguards-rs operations.