Merge branch 'explain_into_tor_addr' into 'main'

// ----------------------------------------------------------------------

/// An object that can be converted to a [`TorAddr`] with a minimum

/// of risk.

/// An object that can be converted to a [`TorAddr`] with a minimum of risk.

///

/// Typically, this trait will be implemented for a hostname or service name.

///

/// Don't implement this trait for IP addresses and similar types; instead,

/// implement [`DangerouslyIntoTorAddr`] for those.  (The trouble with accepting

/// IP addresses is that, in order to get an IP address, most programs will do a

/// local hostname lookup, which will leak the target address to the DNS

/// resolver. The `DangerouslyIntoTorAddr` trait provides a contract for careful

/// programs to say, "I have gotten this IP address from somewhere safe."  This

/// trait is for name-based addressing and similar, which _usually_ gets its

/// addresses from a safer source.)

///

/// [*See also: the `TorAddr` documentation.*](TorAddr)

///

/// # Design note

///

/// We use a separate trait here, instead of using `Into<TorAddr>` or

/// `TryInto<TorAddr>`, because `IntoTorAddr` implies additional guarantees

/// relating to privacy risk.  The separate trait alerts users that something

/// tricky is going on here, and encourages them to think twice before

/// implementing `IntoTorAddr` for their own types.

pub trait IntoTorAddr {

    /// Try to make a [`TorAddr`] to represent connecting to this

    /// address.

///

/// [*See also: the `TorAddr` documentation.*](TorAddr)

pub trait DangerouslyIntoTorAddr {

    /// Try to make a [`TorAddr`] to represent connecting to this

    /// address.

    /// Try to make a [`TorAddr`] to represent connecting to `self`.

    ///

    /// By calling this function, the caller asserts that `self` was

    /// obtained from some secure, private mechanism, and **not** from a local

    /// DNS lookup or something similar.

    fn into_tor_addr_dangerously(self) -> Result<TorAddr, TorAddrError>;

}