Struct CircuitEvent 

pub struct CircuitEvent {
    pub id: CircuitId,
    pub status: CircStatus,
    pub path: Vec<(String, Option<String>)>,
    pub build_flags: Option<Vec<CircBuildFlag>>,
    pub purpose: Option<CircPurpose>,
    pub hs_state: Option<HiddenServiceState>,
    pub rend_query: Option<String>,
    pub created: Option<DateTime<Utc>>,
    pub reason: Option<CircClosureReason>,
    pub remote_reason: Option<CircClosureReason>,
    pub socks_username: Option<String>,
    pub socks_password: Option<String>,
    /* private fields */
}

Event indicating that a circuit’s status has changed.

Circuit events are fundamental to understanding Tor’s operation. They track the lifecycle of circuits from creation through closure, including the relays involved and the purpose of each circuit.

Circuit Lifecycle

Circuits progress through these states:

1. CircStatus::Launched - Circuit creation initiated
2. CircStatus::Extended - Circuit extended to additional hops
3. CircStatus::Built - Circuit fully constructed and ready
4. CircStatus::Failed or CircStatus::Closed - Circuit terminated

Path Information

The path field contains the relays in the circuit as (fingerprint, nickname) tuples. The fingerprint is always present; the nickname may be None if the VERBOSE_NAMES feature isn’t enabled (on by default since Tor 0.2.2.1).

Hidden Service Circuits

For hidden service circuits, additional fields provide context:

• hs_state - Current state in the hidden service protocol
• rend_query - The rendezvous point address
• purpose - Indicates the circuit’s role (intro, rend, etc.)

Example

use stem_rs::events::CircuitEvent;
use stem_rs::CircStatus;

fn handle_circuit(event: &CircuitEvent) {
    match event.status {
        CircStatus::Built => {
            println!("Circuit {} built with {} hops", event.id, event.path.len());
            for (fingerprint, nickname) in &event.path {
                println!("  - {} ({:?})", fingerprint, nickname);
            }
        }
        CircStatus::Failed => {
            println!("Circuit {} failed: {:?}", event.id, event.reason);
        }
        _ => {}
    }
}

See Also

• CircStatus - Circuit status values
• CircPurpose - Circuit purpose types
• CircClosureReason - Closure reasons

Fields

id: CircuitId

Unique identifier for this circuit.

status: CircStatus

Current status of the circuit.

path: Vec<(String, Option<String>)>

Relays in the circuit path as (fingerprint, nickname) tuples.

build_flags: Option<Vec<CircBuildFlag>>

Flags governing how the circuit was built.

purpose: Option<CircPurpose>

Purpose that the circuit is intended for.

hs_state: Option<HiddenServiceState>

Hidden service state if this is an HS circuit.

rend_query: Option<String>

Rendezvous query if this is a hidden service circuit.

created: Option<DateTime<Utc>>

Time when the circuit was created or cannibalized.

reason: Option<CircClosureReason>

Reason for circuit closure (local).

remote_reason: Option<CircClosureReason>

Reason for circuit closure (from remote side).

socks_username: Option<String>

SOCKS username for stream isolation.

socks_password: Option<String>

SOCKS password for stream isolation.

Implementations

impl CircuitEvent

pub fn parse(content: &str) -> Result<Self, Error>

Parses a circuit event from raw control protocol content.

Arguments

• content - The event content after the event type

Event Format

CircuitID CircStatus [Path] [BUILD_FLAGS=...] [PURPOSE=...] [HS_STATE=...]
[REND_QUERY=...] [TIME_CREATED=...] [REASON=...] [REMOTE_REASON=...]
[SOCKS_USERNAME="..."] [SOCKS_PASSWORD="..."]

Errors

Returns Error::Protocol if:

• The circuit ID or status is missing
• The status is not a recognized value

Trait Implementations

impl Clone for CircuitEvent

fn clone(&self) -> CircuitEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CircuitEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Event for CircuitEvent

fn event_type(&self) -> EventType

Returns the type of this event.

fn raw_content(&self) -> &str

Returns the raw, unparsed content of the event.

fn arrived_at(&self) -> Instant

Returns the instant when this event was received.