Merge branch 'explain_into_tor_addr' into 'main'

More docs for IntoTorAddr

Closes #253

See merge request tpo/core/arti!305

crates/arti-client/src/address.rs

@@ -8,10 +8,28 @@ use thiserror::Error;
 
 // ----------------------------------------------------------------------
 
-/// 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.
@@ -30,8 +48,11 @@ pub trait IntoTorAddr {
 ///
 /// [*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>;
 }