tor_netdoc/doc.rs
1//! Individual document types that we can parse in Tor's meta-format.
2//!
3//! Right now, we recognize four kinds of documents.
4//!
5//! A [netstatus::MdConsensus] is a multi-signed document that the
6//! directory authorities use to tell clients and relays who is on the
7//! network. It contains information about each relay, and it links to
8//! additional microdescriptors ([microdesc::Microdesc]) that have
9//! more information about each relay.
10//!
11//! In order to validate a [netstatus::MdConsensus], you need to have
12//! the authority certificate ([authcert::AuthCert]) for the directory
13//! authorities that signed it.
14//!
15//! Finally, in order to use relays not listed in the consensus (such
16//! as bridges), clients use those relays' self-signed router
17//! descriptors ([routerdesc::RouterDesc]). These router descriptors
18//! are also uploaded to the authorities in order to tell them about
19//! relays and their status.
20//!
21//! All of these formats are described in
22//! [dir-spec.txt](https://spec.torproject.org/dir-spec).
23//!
24//! # Limitations
25//!
26//! Tor recognizes other kinds of documents that this crate doesn't
27//! parse yet. There are "ExtraInfo documents" that encode
28//! information about relays that almost nobody needs.
29//! Finally, there are the voting documents themselves that authorities
30//! use in order to calculate the consensus.
31
32use crate::util::intern::InternCache;
33
34#[macro_use]
35mod ns_variety_definition_macros;
36
37pub mod authcert;
38#[cfg(feature = "hs-common")]
39pub mod hsdesc;
40pub mod microdesc;
41pub mod netstatus;
42
43#[cfg(any(doc, feature = "routerdesc"))]
44pub mod routerdesc;
45
46#[allow(missing_docs, clippy::missing_docs_in_private_items)]
47#[cfg(not(any(doc, feature = "routerdesc")))]
48pub mod routerdesc {
49 /// The digest of a RouterDesc document, as reported in a NS consensus.
50 pub type RdDigest = [u8; 20];
51}
52
53/// Cache of Protocols objects, for saving memory.
54//
55/// This only holds weak references to the objects, so we don't
56/// need to worry about running out of space because of stale entries.
57static PROTOVERS_CACHE: InternCache<tor_protover::Protocols> = InternCache::new();