Module events 

Event types and handling for Tor control protocol async notifications.

This module provides comprehensive event types for all Tor control protocol asynchronous events, as described in section 4.1 of the control-spec.

Overview

Tor emits asynchronous events to notify controllers about state changes, bandwidth usage, circuit activity, and other important occurrences. Events are received after subscribing via the SETEVENTS command through the Controller.

Event Categories

Events are organized into several categories:

• Bandwidth Events: BandwidthEvent, CircuitBandwidthEvent, ConnectionBandwidthEvent - Track data transfer rates
• Circuit Events: CircuitEvent - Monitor circuit lifecycle
• Stream Events: StreamEvent - Track stream connections
• Connection Events: OrConnEvent - Monitor OR connections
• Log Events: LogEvent - Receive Tor log messages
• Status Events: StatusEvent - Bootstrap progress and status changes
• Guard Events: GuardEvent - Guard relay changes
• Hidden Service Events: HsDescEvent - Hidden service descriptor activity
• Configuration Events: ConfChangedEvent - Configuration changes
• Network Events: NetworkLivenessEvent - Network connectivity status

Event Subscription

To receive events, subscribe using the controller’s set_events method:

use stem_rs::{controller::Controller, EventType};

let mut controller = Controller::from_port("127.0.0.1:9051".parse()?).await?;
controller.authenticate(None).await?;

// Subscribe to bandwidth and circuit events
controller.set_events(&[EventType::Bw, EventType::Circ]).await?;

// Events will now be delivered asynchronously

Event Parsing

Raw event data from Tor is parsed into strongly-typed event structs using ParsedEvent::parse. Each event type provides access to its specific fields while also preserving the raw content for debugging.

Thread Safety

All event types implement Send and Sync, allowing them to be safely shared across threads. The Event trait requires these bounds.

See Also

• crate::controller - High-level controller API for event subscription
• crate::protocol - Low-level protocol message handling

Structs

AddrMapEvent

Event indicating a new address mapping has been created.

BandwidthEvent

Event emitted every second with the bytes sent and received by Tor.

BuildTimeoutSetEvent

Event indicating that the circuit build timeout has changed.

CircuitBandwidthEvent

Event providing bandwidth information for a specific circuit.

CircuitEvent

Event indicating that a circuit’s status has changed.

ConfChangedEvent

Event indicating that Tor’s configuration has changed.

ConnectionBandwidthEvent

Event providing bandwidth information for a specific connection.

GuardEvent

Event indicating that guard relay status has changed.

HsDescEvent

Event triggered when fetching or uploading hidden service descriptors.

LogEvent

Tor logging event for receiving log messages from the Tor process.

NetworkLivenessEvent

Event indicating network connectivity status.

NewDescEvent

Event indicating that new relay descriptors are available.

OrConnEvent

Event indicating that an OR (Onion Router) connection status has changed.

SignalEvent

Event indicating that Tor received a signal.

StatusEvent

Event providing status information about Tor’s operation.

StreamEvent

Event indicating that a stream’s status has changed.

Enums

ParsedEvent

Enumeration of all parsed event types.

Traits

Event

Trait implemented by all Tor control protocol events.