Module remote 

Remote descriptor downloading from directory authorities and mirrors.

This module provides functionality to download Tor descriptors from directory authorities and fallback mirrors. It enables fetching various types of network data including consensus documents, server descriptors, microdescriptors, and key certificates.

Overview

The Tor network publishes its state through a distributed directory system. Directory authorities are trusted servers that vote on the network consensus, while directory mirrors cache and serve this data to reduce load on authorities.

This module provides:

• A list of known directory authorities
• Functions to download specific descriptor types
• Support for compression (gzip, zstd, lzma)
• Configurable timeouts and retry logic

Descriptor Types

Type	Function	Description
Consensus	download_consensus()	Network status document
Server Descriptors	download_server_descriptors()	Full relay metadata
Extra-Info	download_extrainfo_descriptors()	Bandwidth statistics
Microdescriptors	download_microdescriptors()	Compact client descriptors
Key Certificates	download_key_certificates()	Authority signing keys
Bandwidth File	download_bandwidth_file()	Bandwidth measurements

Example

use stem_rs::descriptor::remote::{download_consensus, DirPort};
use std::time::Duration;

// Download the current consensus with a 30-second timeout
let result = download_consensus(
    false,  // full consensus, not microdescriptor
    None,   // use default authorities
    Some(Duration::from_secs(30)),
).await?;

println!("Downloaded {} bytes from {:?}", result.content.len(), result.source);
println!("Download took {:?}", result.runtime);

Rate Limits

The Tor directory protocol has limits on how many descriptors can be requested at once:

• Maximum 96 fingerprints per request for server/extra-info descriptors
• Maximum 90 hashes per request for microdescriptors

These limits exist due to URL length restrictions in proxy servers.

Compression

Downloads support multiple compression formats to reduce bandwidth:

• gzip: Widely supported, good compression
• zstd: Better compression ratio, faster decompression
• lzma: Best compression, slower
• identity: No compression (plaintext)

The server will use the best mutually supported format.

Error Handling

Download functions try multiple endpoints and return the first successful result. If all endpoints fail, the last error is returned.

See Also

• consensus: Parsing downloaded consensus documents
• server: Parsing server descriptors
• micro: Parsing microdescriptors
• key_cert: Parsing key certificates

Structs

DirPort

A directory port endpoint for downloading descriptors.

DirectoryAuthority

Information about a Tor directory authority.

DownloadResult

Result of a successful descriptor download.

Enums

Compression

Compression formats supported for descriptor downloads.

Functions

download_bandwidth_file

Downloads the bandwidth file for the next consensus.

download_consensus

Downloads the current network consensus.

download_detached_signatures

Downloads detached signatures for the next consensus.

download_extrainfo_descriptors

Downloads extra-info descriptors.

download_from_dirport

Downloads a resource from a directory port.

download_key_certificates

Downloads authority key certificates.

download_microdescriptors

Downloads microdescriptors by their hashes.

download_server_descriptors

Downloads server descriptors.

get_authorities

Returns the list of known directory authorities.