Module control 

Control module for Tor controller interaction and main application loop.

This module provides the core functionality for connecting to Tor’s control port, authenticating, handling events, and managing the vanguard protection lifecycle.

Overview

The control module handles:

• Connection Management: Connect via TCP or Unix socket with auto-detection
• Authentication: Password, cookie, and interactive authentication
• Consensus Processing: Parse consensus weights and update vanguard state
• Event Handling: Register and dispatch events to protection components
• Circuit Management: Close circuits when attacks are detected
• Signal Handling: Handle SIGHUP for configuration reload

Architecture

The control module orchestrates all protection components through a central event loop:

┌──────────────────────────────────────────────────────────────────────────┐
│                         Main Event Loop                                  │
│                                                                          │
│  ┌──────────────┐     ┌──────────────┐     ┌──────────────────────────┐  │
│  │  Tor Control │───▶│   Event      │───▶│   Protection Components  │  │
│  │    Socket    │    │  Dispatcher  │      │                          │  │
│  └──────────────┘    └──────────────┘      │  ┌────────────────────┐  │  │
│         │                   │              │  │ VanguardState      │  │  │
│         │                   │              │  │ (guard management) │  │  │
│         ▼                   │              │  └────────────────────┘  │  │
│  ┌──────────────┐           │              │  ┌────────────────────┐  │  │
│  │ Authenticate │           │              │  │ BandwidthStats     │  │  │
│  │ (password/   │           │              │  │ (attack detection) │  │  │
│  │  cookie)     │           │              │  └────────────────────┘  │  │
│  └──────────────┘           │              │  ┌────────────────────┐  │  │
│                             │              │  │ RendGuard          │  │  │
│                             │              │  │ (RP monitoring)    │  │  │
│                             │              │  └────────────────────┘  │  │
│                             │              │  ┌────────────────────┐  │  │
│                             │              │  │ PathVerify         │  │  │
│                             │              │  │ (path validation)  │  │  │
│                             │              │  └────────────────────┘  │  │
│                             │              └──────────────────────────┘  │
│                             │                                            │
│                             ▼                                            │
│                    ┌──────────────────┐                                  │
│                    │ Circuit Actions  │                                  │
│                    │ (close on attack)│                                  │
│                    └──────────────────┘                                  │
└─────────────────────────────────────────────────────────────────────────┘

Main Loop Flow

The main application loop follows this sequence:

                   ┌─────────────────┐
                   │     Start       │
                   └────────┬────────┘
                            │
                            ▼
                   ┌─────────────────┐
                   │ Connect to Tor  │◀──────────────────┐
                   │ (socket/port)   │                   │
                   └────────┬────────┘                   │
                            │                            │
                            ▼                            │
                   ┌─────────────────┐                   │
                   │  Authenticate   │                   │
                   │ (auto-detect)   │                   │
                   └────────┬────────┘                   │
                            │                            │
                            ▼                            │
                   ┌─────────────────┐                   │
                   │ Load/Create     │                   │
                   │ Vanguard State  │                   │
                   └────────┬────────┘                   │
                            │                            │
                            ▼                            │
                   ┌─────────────────┐                   │
                   │ Subscribe to    │                   │
                   │ Tor Events      │                   │
                   └────────┬────────┘                   │
                            │                            │
                            ▼                            │
             ┌──────────────────────────────┐            │
             │      Event Processing Loop   │            │
             │  ┌────────────────────────┐  │            │
             │  │ Receive Event          │  │            │
             │  └───────────┬────────────┘  │            │
             │              │               │            │
             │              ▼               │            │
             │  ┌────────────────────────┐  │            │
             │  │ Dispatch to Handlers   │  │            │
             │  │ (CIRC, CIRC_BW, etc.)  │  │            │
             │  └───────────┬────────────┘  │            │
             │              │               │            │
             │              ▼               │            │
             │  ┌────────────────────────┐  │            │
             │  │ Check Circuit Limits   │  │            │
             │  │ (close if attack)      │  │            │
             │  └───────────┬────────────┘  │            │
             │              │               │            │
             │              ▼               │            │
             │         [Continue]           │            │
             └──────────────┬───────────────┘            │
                            │                            │
                   [Connection Lost]                     │
                            │                            │
                            ▼                            │
                   ┌─────────────────┐                   │
                   │ Reconnect?      │───────────────────┘
                   │ (retry limit)   │
                   └────────┬────────┘
                            │ [Limit Reached]
                            ▼
                   ┌─────────────────┐
                   │      Exit       │
                   └─────────────────┘

Event Handling State Diagram

Events are dispatched to different handlers based on type:

                        ┌─────────────┐
                        │ Tor Event   │
                        └──────┬──────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
   ┌───────────┐        ┌───────────┐        ┌───────────┐
   │   CIRC    │        │  CIRC_BW  │        │ NEWCONSENS│
   └─────┬─────┘        └─────┬─────┘        └─────┬─────┘
         │                    │                    │
         ▼                    ▼                    ▼
   ┌───────────┐        ┌───────────┐        ┌───────────┐
   │RendGuard  │        │BandGuards │        │ Update    │
   │BandGuards │        │(bandwidth │        │ Vanguard  │
   │CBTVerify  │        │ tracking) │        │ State     │
   │PathVerify │        └───────────┘        └───────────┘
   │LogGuard   │
   └───────────┘

         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
   ┌───────────┐        ┌───────────┐        ┌───────────┐
   │  ORCONN   │        │   GUARD   │        │  SIGNAL   │
   └─────┬─────┘        └─────┬─────┘        └─────┬─────┘
         │                    │                    │
         ▼                    ▼                    ▼
   ┌───────────┐        ┌───────────┐        ┌───────────┐
   │BandGuards │        │PathVerify │        │ Reapply   │
   │PathVerify │        │(guard     │        │ Vanguards │
   │(conn      │        │ tracking) │        │ (SIGHUP)  │
   │ tracking) │        └───────────┘        └───────────┘
   └───────────┘

What This Module Does NOT Do

• Direct relay communication: Use stem-rs client module for ORPort connections
• Descriptor parsing: Consensus parsing is limited to bandwidth weights
• Guard selection: Use crate::node_selection for bandwidth-weighted selection
• State persistence: Use crate::vanguards::VanguardState for state file I/O

Example

Running the main application loop:

use vanguards_rs::config::Config;
use vanguards_rs::control::run_main;

// Load configuration
let config = Config::default();

// Run the main loop (blocks until shutdown)
run_main(config).await?;

Security Considerations

• Passwords are prompted interactively if not provided (never logged)
• Circuit closure decisions are logged for audit purposes
• State files contain guard fingerprints (protect accordingly)
• Reconnection attempts are rate-limited to prevent DoS

See Also

• crate::config - Configuration management
• crate::vanguards - Vanguard state management
• crate::bandguards - Bandwidth-based attack detection
• crate::rendguard - Rendezvous point monitoring
• crate::pathverify - Circuit path verification
• Python vanguards control - Original implementation
• Tor Control Protocol - Protocol specification

Structs

AppState

Application state shared across event handlers.

Constants

VERSION

Library version string.

Functions

authenticate_any

Authenticates with Tor using any available method.

configure_tor

Configures Tor with the current vanguard settings.

control_loop

Main control loop for event processing.

get_close_circuits

Gets the global close circuits flag.

get_consensus_weights

Parses consensus bandwidth weights from a cached-microdesc-consensus file.

new_consensus_event

Handles a new consensus event by updating vanguard state.

run_main

Runs the main application loop with reconnection support.

set_close_circuits

Sets the global close circuits flag.

signal_event

Handles a signal event from Tor.

try_close_circuit

Attempts to close a circuit, optionally dumping logs first.