github/darkfi
1
1
Fork 0
mirror of https://github.com/darkrenaissance/darkfi.git synced 2026-01-06 21:34:00 -05:00
Code Issues Packages Projects Releases Wiki Activity

net/hosts: moved file doc comments before items

Browse Source
This commit is contained in:
skoupidi
2026-01-04 14:31:01 +02:00
parent e641ac09f4
commit f644d8cae0
1 changed files with 38 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

76
src/net/hosts.rs
View File

@@ -16,6 +16,44 @@
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
//! The main interface for interacting with the hostlist. Contains the following:
//!
//! `Hosts`: the main parent class that manages HostRegistry and HostContainer. It is also
//! responsible for filtering addresses before writing to the hostlist.
//!
//! `HostRegistry`: A locked HashMap that maps peer addresses onto mutually exclusive
//! states (`HostState`). Prevents race conditions by dictating a strict flow of logically
//! acceptable states.
//!
//! `HostContainer`: A wrapper for the hostlists. Each hostlist is represented by a `HostColor`,
//! which can be Grey, White, Gold or Black. Exposes a common interface for hostlist queries and
//! utilities.
//!
//! `HostColor`:
//! > `White`: Hosts that have passed the `GreylistRefinery` successfully.
//!
//! > `Gold`: Hosts we have been able to establish a connection to in `OutboundSession`.
//!
//! > `Grey`: Recently received hosts that are checked by the `GreylistRefinery` and
//! > upgraded to the whitelist if valid. If they're inaccessible by the Refinery
//! > they will be deleted.
//!
//! > `Black`: hostile hosts that are strictly avoided for the duration of the program.
//!
//! > `Dark`: hosts that do not match our transports, but that we continue to share with
//! > other peers. We do not keep darklist entries that are older than one day.
//! > This is to avoid peers propagating nodes that may be faulty. We assume that
//! > within the one day period, the nodes will be picked up by peers that accept
//! > the transports and can refine them to remove inactive peers. Dark list hosts
//! > are otherwise ignored.
//!
//! `HostState`: a set of mutually exclusive states that can be Insert, Refine, Connect, Suspend
//! or Connected. The state is `None` when the corresponding host has been removed from the
//! HostRegistry.
//TODO: Use HostState::Free `age` variable to implement a pruning logic that deletes peers from
//the registry once they have bypassed a certain age threshold.
use rand::{prelude::IteratorRandom, rngs::OsRng, Rng};
use smol::lock::RwLock as AsyncRwLock;
use std::{
@@ -49,44 +87,6 @@ use crate::{
Error, Result,
};
/// The main interface for interacting with the hostlist. Contains the following:
///
/// `Hosts`: the main parent class that manages HostRegistry and HostContainer. It is also
/// responsible for filtering addresses before writing to the hostlist.
///
/// `HostRegistry`: A locked HashMap that maps peer addresses onto mutually exclusive
/// states (`HostState`). Prevents race conditions by dictating a strict flow of logically
/// acceptable states.
///
/// `HostContainer`: A wrapper for the hostlists. Each hostlist is represented by a `HostColor`,
/// which can be Grey, White, Gold or Black. Exposes a common interface for hostlist queries and
/// utilities.
///
/// `HostColor`:
/// > `White`: Hosts that have passed the `GreylistRefinery` successfully.
///
/// > `Gold`: Hosts we have been able to establish a connection to in `OutboundSession`.
///
/// > `Grey`: Recently received hosts that are checked by the `GreylistRefinery` and
/// > upgraded to the whitelist if valid. If they're inaccessible by the Refinery
/// > they will be deleted.
///
/// > `Black`: hostile hosts that are strictly avoided for the duration of the program.
///
/// > `Dark`: hosts that do not match our transports, but that we continue to share with
/// > other peers. We do not keep darklist entries that are older than one day.
/// > This is to avoid peers propagating nodes that may be faulty. We assume that
/// > within the one day period, the nodes will be picked up by peers that accept
/// > the transports and can refine them to remove inactive peers. Dark list hosts
/// > are otherwise ignored.
///
/// `HostState`: a set of mutually exclusive states that can be Insert, Refine, Connect, Suspend
/// or Connected. The state is `None` when the corresponding host has been removed from the
/// HostRegistry.
///
//TODO: Use HostState::Free `age` variable to implement a pruning logic that deletes peers from
//the registry once they have bypassed a certain age threshold.
// An array containing all possible local host strings
// TODO: This could perhaps be more exhaustive?
pub const LOCAL_HOST_STRS: [&str; 2] = ["localhost", "localhost.localdomain"];