~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
1046 lines · 39.5 KB Raw History
//! The one way out to the network. Every URL the server fetches comes, in
//! the end, from a DID document or a DNS record anyone can write, so each is
//! treated as untrusted: only `https`, and only public addresses. Hostnames
//! are resolved by public DNS servers (Cloudflare's and Google's, never the
//! system's configuration), and the addresses that are not public are
//! dropped before a connection is made, so a name pointing at the server's
//! own network cannot be used to reach it; an IP-literal host is checked
//! the same way before any request, and again at every redirect. With
//! `HUD_ALLOW_PRIVATE`, both rules are lifted and the system's resolver is
//! used, for development against local servers.
//!
//! The same DNS servers answer the TXT lookups of handles (`_atproto.`) and
//! lexicon authorities (`_lexicon.`).
//!
//! What a lookup finds is kept, by the caches above this, and so is an
//! answer that there is nothing to find (a `404`, a name with no record).
//! No answer is never kept: none in time, a connection that failed
//! (`Failure::answered`), or a server saying only that it cannot answer
//! now (`Fetched::unavailable`). That says nothing of what was asked for,
//! and kept, one moment's failure (a cold DNS lookup, a busy server) would
//! answer every caller after it for as long as it was kept.
//!
//! Every request goes out through `execute`, which hands on the trace it
//! is sent in as a `traceparent` and logs it, `outgoing`, by host and path,
//! never its query, a header or a body (`telemetry::called`). The one
//! server reached past the filter is the operator's own web app (`Web`).

use hickory_resolver::TokioResolver;
use hickory_resolver::config::{
    CLOUDFLARE, ConnectionConfig, GOOGLE, NameServerConfig, ResolverConfig,
};
use hickory_resolver::net::runtime::TokioRuntimeProvider;
use reqwest::dns::{Addrs, Name, Resolve, Resolving};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr};
use std::sync::Arc;
use std::time::Duration;
use url::{Host, Url};

/// How long one try of a DNS lookup has, in milliseconds: two servers asked
/// at once, each asked again every third of a second while neither answers.
const DNS_TRY_MS: u64 = 1500;
/// How many tries a DNS lookup has: one more after a try with no answer,
/// to the other servers, so lost packets or a slow first answer (a cold
/// cache, at first) do not fail it.
const DNS_TRIES: u64 = 2;
/// How long a DNS lookup has: its tries, and a quarter second for the last
/// one's answer or failure to come back. A name no server answers for fails
/// in about three seconds, as in Monolith and knotless.
pub const DNS_WAIT: Duration = Duration::from_millis(DNS_TRY_MS * DNS_TRIES + 250);
/// The most redirects a request follows.
const REDIRECTS: usize = 3;

/// What a request answered: its status, its headers, as much of its body
/// as was asked for, and whether a redirect took it elsewhere.
pub struct Fetched {
    pub status: u16,
    pub headers: reqwest::header::HeaderMap,
    pub body: Vec<u8>,
    /// Whether it answered from another URL than the one asked, after a
    /// redirect: what must answer at its own URL (a client's metadata, an
    /// authorization server's endpoints) is refused so.
    pub redirected: bool,
}

impl Fetched {
    /// A header's value, if it is text.
    pub fn header(&self, name: &str) -> Option<&str> {
        self.headers.get(name).and_then(|v| v.to_str().ok())
    }

    /// Whether it says only that its server cannot answer now (`408`,
    /// `425`, `429`, `5xx`), nothing of what was asked for: asked again,
    /// it may answer.
    pub fn unavailable(&self) -> bool {
        matches!(self.status, 408 | 425 | 429) || self.status >= 500
    }
}

/// Why a request has nothing to read, in a few words, and whether that was
/// an answer: a server answering more than may be read, or redirecting
/// where no request may go, or DNS answering that its host has no public
/// address, or none at all; or the lack of one: none in time, a connection
/// that failed.
#[derive(Debug)]
pub struct Failure {
    pub why: String,
    pub answered: bool,
}

impl Failure {
    /// No answer, for `why`.
    fn none(why: String) -> Failure {
        Failure {
            why,
            answered: false,
        }
    }

    /// A request's failure: an answer if it was refused on one.
    fn of(e: &reqwest::Error) -> Failure {
        Failure {
            why: describe(e),
            answered: refusal(e).is_some_and(|r| r.answered),
        }
    }
}

impl std::fmt::Display for Failure {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.why)
    }
}

impl From<Failure> for String {
    fn from(f: Failure) -> String {
        f.why
    }
}

/// The outbound client and the DNS resolver behind it.
pub struct Net {
    client: reqwest::Client,
    dns: Arc<TokioResolver>,
    allow_private: bool,
}

/// Whether `ip` is an address on the public internet: not private, loopback,
/// link-local, unique-local, shared (CGNAT), multicast, unspecified or
/// otherwise reserved. An IPv4 address mapped into IPv6 is judged as itself.
pub fn is_public(ip: IpAddr) -> bool {
    match ip {
        IpAddr::V4(v4) => is_public_v4(v4),
        IpAddr::V6(v6) => match v6.to_ipv4_mapped() {
            Some(v4) => is_public_v4(v4),
            None => is_public_v6(v6),
        },
    }
}

fn is_public_v4(ip: Ipv4Addr) -> bool {
    let [a, b, ..] = ip.octets();
    !(ip.is_private()
        || ip.is_loopback()
        || ip.is_link_local()
        || ip.is_multicast()
        || ip.is_broadcast()
        // 0.0.0.0/8, "this network", the unspecified address among them.
        || a == 0
        // 100.64.0.0/10, shared address space (CGNAT).
        || (a == 100 && (b & 0xc0) == 64)
        // 240.0.0.0/4, reserved.
        || a >= 240)
}

fn is_public_v6(ip: Ipv6Addr) -> bool {
    let first = ip.segments()[0];
    !(ip.is_unspecified()
        || ip.is_loopback()
        || ip.is_multicast()
        // fc00::/7, unique local.
        || (first & 0xfe00) == 0xfc00
        // fe80::/10, link local; fec0::/10, the old site local.
        || (first & 0xffc0) == 0xfe80
        || (first & 0xffc0) == 0xfec0)
}

/// Whether a URL may be fetched: `https` (or `http` when private addresses
/// are allowed), with a host, and, if that host is an IP address, a public
/// one unless allowed otherwise. Hostnames are checked as they resolve.
pub fn check_url(url: &Url, allow_private: bool) -> Result<(), String> {
    let scheme_ok = url.scheme() == "https" || (allow_private && url.scheme() == "http");
    if !scheme_ok {
        return Err(format!("{} is not https", origin(url)));
    }
    let public = match url.host() {
        Some(Host::Ipv4(ip)) => is_public(IpAddr::V4(ip)),
        Some(Host::Ipv6(ip)) => is_public(IpAddr::V6(ip)),
        // A domain, checked as it resolves: an http(s) URL always has one.
        _ => true,
    };
    if !public && !allow_private {
        return Err(format!("{} is not a public address", origin(url)));
    }
    Ok(())
}

/// A URL's origin, to name it in a message without its path or query.
fn origin(url: &Url) -> String {
    url.origin().ascii_serialization()
}

/// Why a request was refused before it reached a server, or at a redirect,
/// and whether on an answer (a host with no public address, or none at
/// all; a redirect where no request may go) or for want of one (a host
/// whose name had no answer in time).
#[derive(Debug)]
struct Refused {
    why: String,
    answered: bool,
}

impl std::fmt::Display for Refused {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(&self.why)
    }
}

impl std::error::Error for Refused {}

/// The resolver reqwest connects through: public DNS, public addresses only,
/// each lookup within `wait` (`DNS_WAIT`).
struct PublicOnly {
    dns: Arc<TokioResolver>,
    wait: Duration,
}

impl Resolve for PublicOnly {
    fn resolve(&self, name: Name) -> Resolving {
        let (dns, wait) = (self.dns.clone(), self.wait);
        Box::pin(async move {
            let host = name.as_str().to_string();
            let refused = |why: String, answered: bool| Refused { why, answered };
            let found = match tokio::time::timeout(wait, dns.lookup_ip(format!("{host}."))).await {
                Ok(Ok(found)) => found,
                Ok(Err(e)) => {
                    let answered = e.is_no_records_found();
                    return Err(refused(format!("{host} does not resolve"), answered).into());
                }
                Err(_) => {
                    return Err(refused(format!("{host} did not resolve in time"), false).into());
                }
            };
            let public: Vec<SocketAddr> = found
                .iter()
                .filter(|ip| is_public(*ip))
                .map(|ip| SocketAddr::new(ip, 0))
                .collect();
            if public.is_empty() {
                let why = format!("{host} resolves to no public address");
                return Err(refused(why, true).into());
            }
            let addrs: Addrs = Box::new(public.into_iter());
            Ok(addrs)
        })
    }
}

/// A resolver asking `servers`, each lookup tried `DNS_TRIES` times at most,
/// each try `DNS_TRY_MS`, so all fit in `DNS_WAIT`.
fn resolver(servers: Vec<NameServerConfig>) -> TokioResolver {
    let mut builder = TokioResolver::builder_with_config(
        ResolverConfig::from_name_servers(servers),
        TokioRuntimeProvider::default(),
    );
    let opts = builder.options_mut();
    opts.timeout = Duration::from_millis(DNS_TRY_MS);
    // Its retries, after the first try.
    opts.attempts = DNS_TRIES as usize - 1;
    // Without hickory's TLS, which HUD does not build it with, its builder
    // has nothing that can fail.
    builder.build().expect("a resolver without TLS builds")
}

impl Net {
    /// The client and resolver, as `allow_private` says.
    pub fn new(allow_private: bool) -> Net {
        let servers = CLOUDFLARE
            .ips
            .iter()
            .chain(GOOGLE.ips)
            // IPv4 alone: a container often has no IPv6 route, and every
            // lookup would wait on the servers it cannot reach first.
            .filter(|ip| ip.is_ipv4())
            .map(|&ip| {
                NameServerConfig::new(
                    ip,
                    true,
                    vec![ConnectionConfig::udp(), ConnectionConfig::tcp()],
                )
            })
            .collect();
        Net::over(resolver(servers), allow_private, DNS_WAIT)
    }

    /// The client over `dns`, its connections' lookups each within `wait`.
    fn over(dns: TokioResolver, allow_private: bool, wait: Duration) -> Net {
        let dns = Arc::new(dns);
        let redirects = reqwest::redirect::Policy::custom(move |attempt| {
            let refused = |why: String| Refused {
                why,
                answered: true,
            };
            if attempt.previous().len() >= REDIRECTS {
                return attempt.error(refused("too many redirects".into()));
            }
            match check_url(attempt.url(), allow_private) {
                Ok(()) => attempt.follow(),
                Err(why) => attempt.error(refused(why)),
            }
        });
        let mut client = reqwest::Client::builder()
            .user_agent(concat!("hud/", env!("CARGO_PKG_VERSION")))
            .redirect(redirects)
            .connect_timeout(Duration::from_secs(5))
            .https_only(!allow_private);
        if !allow_private {
            let dns = dns.clone();
            client = client.dns_resolver(Arc::new(PublicOnly { dns, wait }));
        }
        // rustls with webpki's roots, no proxy or identity given: its
        // builder has nothing that can fail.
        let client = client
            .build()
            .expect("an HTTP client of these options builds");
        Net {
            client,
            dns,
            allow_private,
        }
    }

    /// Whether private addresses and `http` are allowed.
    pub fn allow_private(&self) -> bool {
        self.allow_private
    }

    /// A GET of `url`, once it is checked: to send as it is (`execute`),
    /// and stream.
    pub fn get(&self, url: &Url) -> Result<reqwest::RequestBuilder, String> {
        check_url(url, self.allow_private)?;
        Ok(self.client.get(url.clone()))
    }

    /// A POST to `url`, once it is checked, to send with `send`.
    pub fn post(&self, url: &Url) -> Result<reqwest::RequestBuilder, String> {
        check_url(url, self.allow_private)?;
        Ok(self.client.post(url.clone()))
    }

    /// GET `url` within `wait`, reading at most `max` bytes of its body:
    /// past that, it is refused.
    pub async fn fetch(&self, url: &Url, wait: Duration, max: usize) -> Result<Fetched, Failure> {
        self.send(self.get(url).map_err(Failure::none)?, wait, max)
            .await
    }

    /// As `fetch`, asking for JSON (`Accept: application/json`), as a
    /// service answering several types needs.
    pub async fn fetch_json(
        &self,
        url: &Url,
        wait: Duration,
        max: usize,
    ) -> Result<Fetched, Failure> {
        let req = self
            .get(url)
            .map_err(Failure::none)?
            .header(reqwest::header::ACCEPT, "application/json");
        self.send(req, wait, max).await
    }

    /// Sends a request made by `get` or `post` as it is, to stream its
    /// answer, as every request is sent (`execute`).
    pub async fn execute(
        &self,
        req: reqwest::RequestBuilder,
    ) -> reqwest::Result<reqwest::Response> {
        let (client, req) = req.build_split();
        execute(&client, req?, None).await
    }

    /// Send a request made by `get` or `post` and read its answer, within
    /// `wait` and `max` bytes.
    pub async fn send(
        &self,
        req: reqwest::RequestBuilder,
        wait: Duration,
        max: usize,
    ) -> Result<Fetched, Failure> {
        let too_large = || Failure {
            why: "its answer is too large".into(),
            answered: true,
        };
        // The wait's end, so a call it cuts off is logged as timed out, not
        // abandoned by its caller.
        let deadline = std::time::Instant::now() + wait;
        let read = async {
            let (client, req) = req.build_split();
            let req = req.map_err(|e| Failure::of(&e))?;
            let asked = req.url().clone();
            let mut res = execute(&client, req, Some(deadline))
                .await
                .map_err(|e| Failure::of(&e))?;
            let status = res.status().as_u16();
            let redirected = res.url() != &asked;
            let headers = res.headers().clone();
            if res.content_length().is_some_and(|n| n > max as u64) {
                return Err(too_large());
            }
            let mut body = Vec::new();
            while let Some(chunk) = res.chunk().await.map_err(|e| Failure::of(&e))? {
                if body.len() + chunk.len() > max {
                    return Err(too_large());
                }
                body.extend_from_slice(&chunk);
            }
            Ok(Fetched {
                status,
                headers,
                body,
                redirected,
            })
        };
        tokio::time::timeout(wait, read)
            .await
            .map_err(|_| Failure::none("it did not answer in time".into()))?
    }

    /// The TXT records of `name`, each its strings joined: none if it has
    /// none; or, if no server answered within `DNS_WAIT`, why.
    pub async fn txt(&self, name: &str) -> Result<Vec<Vec<u8>>, String> {
        use hickory_resolver::proto::rr::RData;
        let fqdn = format!("{name}.");
        match tokio::time::timeout(DNS_WAIT, self.dns.txt_lookup(fqdn.as_str())).await {
            Ok(Ok(found)) => Ok(found
                .answers()
                .iter()
                .filter_map(|r| match &r.data {
                    RData::TXT(t) => Some(t.txt_data.concat()),
                    _ => None,
                })
                .collect()),
            Ok(Err(e)) if e.is_no_records_found() => Ok(Vec::new()),
            _ => Err(format!("{name} had no DNS answer")),
        }
    }
}

/// How long an idle connection to the web app is kept: less than the 5
/// seconds Node keeps one, so HUD never sends on one just as Node closes it.
const WEB_IDLE: Duration = Duration::from_secs(4);

/// The operator's own web app (`HUD_WEB`), handed the requests HUD doesn't
/// answer itself. It's the one server reached past `Net`'s filter: its
/// origin is the operator's, never one a DID document or anyone else
/// wrote, and it's on a private network on purpose (a container's beside
/// HUD's). So it has a client of its own, for its origin alone, which
/// follows no redirect (the browser does) and decodes no body (HUD hands
/// each on as it comes). Its host is looked up as each request is sent, so
/// HUD starts while it's not up yet.
pub struct Web {
    client: reqwest::Client,
    origin: String,
}

impl Web {
    /// The app at `origin`, as `http://grain-web:3000`, no trailing `/`.
    pub fn new(origin: String) -> Web {
        let client = reqwest::Client::builder()
            .redirect(reqwest::redirect::Policy::none())
            .connect_timeout(Duration::from_secs(5))
            .pool_idle_timeout(WEB_IDLE)
            .no_gzip()
            .no_brotli()
            .no_deflate()
            .no_zstd()
            .build()
            .expect("an HTTP client of these options builds");
        Web { client, origin }
    }

    /// A `method` request of `at`, a path and query, at the app.
    pub fn request(&self, method: reqwest::Method, at: &str) -> reqwest::RequestBuilder {
        self.client.request(method, format!("{}{at}", self.origin))
    }

    /// Sends a request made by `request` as it is, to stream its answer,
    /// logged as every request is (`execute`).
    pub async fn execute(
        &self,
        req: reqwest::RequestBuilder,
    ) -> reqwest::Result<reqwest::Response> {
        let (client, req) = req.build_split();
        execute(&client, req?, None).await
    }
}

/// Sends `req` on `client`, in the trace the task is in (`traceparent`),
/// and logs it once answered, failed, or given up on before either: by
/// `deadline`, its wait's end, if it has one, or else by what asked for it.
async fn execute(
    client: &reqwest::Client,
    mut req: reqwest::Request,
    deadline: Option<std::time::Instant>,
) -> reqwest::Result<reqwest::Response> {
    if let Some(id) = crate::telemetry::trace_id() {
        let parent = crate::telemetry::traceparent(&id);
        let parent = reqwest::header::HeaderValue::try_from(parent).expect("hex is a header value");
        req.headers_mut().insert("traceparent", parent);
    }
    let mut sent = Sent {
        host: req.url().host_str().unwrap_or_default().to_string(),
        method: req.method().to_string(),
        path: crate::telemetry::short(req.url().path()),
        started: std::time::Instant::now(),
        deadline,
        done: false,
    };
    let res = client.execute(req).await;
    let status = res.as_ref().ok().map(|r| r.status().as_u16());
    let error = res.as_ref().err().map(crate::telemetry::error_type);
    sent.done = true;
    sent.log(status, error.as_deref());
    res
}

/// A request sent, to log once it is done with.
struct Sent {
    host: String,
    method: String,
    path: String,
    started: std::time::Instant,
    /// When its wait ends, where it has one.
    deadline: Option<std::time::Instant>,
    done: bool,
}

impl Sent {
    fn log(&self, status: Option<u16>, error: Option<&str>) {
        crate::telemetry::called(&crate::telemetry::Call {
            host: &self.host,
            method: &self.method,
            path: &self.path,
            status,
            error,
            took: self.started.elapsed(),
        });
    }
}

impl Drop for Sent {
    /// One given up on before it was answered is logged as `timeout` where
    /// its wait ran out, and as `abandoned` where what asked for it went
    /// away first, as a search typed past or a race's loser.
    fn drop(&mut self) {
        if !self.done {
            let ran_out = self
                .deadline
                .is_some_and(|d| std::time::Instant::now() >= d);
            let why = if ran_out {
                "timeout"
            } else {
                crate::telemetry::ABANDONED
            };
            self.log(None, Some(why));
        }
    }
}

/// Where a request was refused (`Refused`), why.
fn refusal(e: &reqwest::Error) -> Option<&Refused> {
    let mut source = std::error::Error::source(e);
    while let Some(s) = source {
        if let Some(r) = s.downcast_ref::<Refused>() {
            return Some(r);
        }
        source = s.source();
    }
    None
}

/// A request's failure in a few words, naming the refusal of a non-public
/// address or a redirect where that is what it was. (Every redirect that
/// fails fails on the policy's refusal: `check_url` is stricter than
/// reqwest's own `https_only`, and refuses first.)
pub fn describe(e: &reqwest::Error) -> String {
    if let Some(r) = refusal(e) {
        return r.why.clone();
    }
    if e.is_timeout() {
        "it did not answer in time".into()
    } else if e.is_connect() {
        "could not connect".into()
    } else {
        "the request failed".into()
    }
}

/// The one `did=` TXT record's DID, of records each its strings joined:
/// none if none starts so, or more than one does, or it is not a DID.
pub fn did_of_txt(records: &[Vec<u8>]) -> Option<String> {
    let mut dids = records.iter().filter_map(|r| r.strip_prefix(b"did="));
    let did = dids.next()?;
    if dids.next().is_some() {
        return None;
    }
    let did = std::str::from_utf8(did).ok()?.trim();
    atproto::syntax::is_did(did).then(|| did.to_string())
}

#[cfg(test)]
pub(crate) mod tests {
    use super::*;
    use hickory_resolver::proto::op::{Message, ResponseCode};
    use hickory_resolver::proto::rr::rdata::{A, CNAME, TXT};
    use hickory_resolver::proto::rr::{Name as DnsName, RData, Record, RecordType};

    #[test]
    fn public_addresses() {
        for public in [
            "1.1.1.1",
            "8.8.8.8",
            "100.63.255.255",
            "100.128.0.1",
            "172.32.0.1",
            "2606:4700:4700::1111",
            "::ffff:1.1.1.1",
        ] {
            assert!(is_public(public.parse().unwrap()), "{public}");
        }
        for private in [
            "10.0.0.1",
            "172.16.0.1",
            "192.168.1.1",
            "127.0.0.1",
            "169.254.169.254",
            "100.64.0.1",
            "100.127.255.255",
            "224.0.0.1",
            "0.0.0.0",
            "0.1.2.3",
            "255.255.255.255",
            "240.0.0.1",
            "::",
            "::1",
            "fe80::1",
            "fc00::1",
            "fd12:3456::1",
            "ff02::1",
            "fec0::1",
            "::ffff:127.0.0.1",
            "::ffff:10.1.2.3",
        ] {
            assert!(!is_public(private.parse().unwrap()), "{private}");
        }
    }

    #[test]
    fn urls() {
        let ok = |u: &str, allow| check_url(&Url::parse(u).unwrap(), allow).is_ok();
        assert!(ok("https://example.com/x", false));
        assert!(ok("https://1.1.1.1/", false));
        assert!(!ok("http://example.com/", false));
        assert!(!ok("https://127.0.0.1/", false));
        assert!(!ok("https://[::1]:8080/", false));
        assert!(!ok("https://169.254.169.254/latest", false));
        assert!(!ok("https://[::ffff:192.168.0.1]/", false));
        assert!(!ok("ftp://example.com/", true));
        assert!(ok("http://127.0.0.1:2583/", true));
    }

    #[test]
    fn txt_dids() {
        let r = |s: &str| s.as_bytes().to_vec();
        assert_eq!(
            did_of_txt(&[r("v=spf1"), r("did=did:plc:abc")]).as_deref(),
            Some("did:plc:abc")
        );
        assert_eq!(did_of_txt(&[r("did=did:plc:a"), r("did=did:plc:b")]), None);
        assert_eq!(did_of_txt(&[r("did=not a did")]), None);
        assert_eq!(did_of_txt(&[]), None);
    }

    /// A lookup whose first try has no answer, as lost packets or a slow
    /// first answer leave it at a cold start, is tried again within
    /// `DNS_WAIT`, and has its answer.
    #[tokio::test]
    async fn a_lookup_with_no_answer_at_first_tries_again() {
        let fake = tokio::net::UdpSocket::bind("127.0.0.1:0").await.unwrap();
        let port = fake.local_addr().unwrap().port();
        tokio::spawn(async move {
            let mut buf = [0; 512];
            let mut first = None;
            loop {
                let (n, from) = fake.recv_from(&mut buf).await.unwrap();
                let at = *first.get_or_insert_with(std::time::Instant::now);
                // Silent through the first try, its resends too.
                if at.elapsed() < Duration::from_millis(DNS_TRY_MS * 2 / 3) {
                    continue;
                }
                // The question back, as a response: no such name.
                let mut answer = buf[..n].to_vec();
                answer[2] |= 0x80;
                answer[3] = 0x83;
                fake.send_to(&answer, from).await.unwrap();
            }
        });
        let mut udp = ConnectionConfig::udp();
        udp.port = port;
        let server = NameServerConfig::new(Ipv4Addr::LOCALHOST.into(), true, vec![udp]);
        let net = Net {
            client: reqwest::Client::new(),
            dns: Arc::new(resolver(vec![server])),
            allow_private: false,
        };
        // An answer, that it has no record; not the lack of one.
        assert_eq!(net.txt("_atproto.alice.test").await, Ok(Vec::new()));
    }

    /// What the fake DNS server answers a question.
    pub(crate) enum Reply {
        /// These records, each its name and data.
        Records(Vec<(String, RData)>),
        /// That there is no such name.
        NoSuchName,
        /// That it cannot answer (`SERVFAIL`).
        Fail,
        /// Nothing at all.
        Silent,
    }

    /// A record of `name`'s.
    pub(crate) fn record(name: &str, data: RData) -> (String, RData) {
        (name.to_string(), data)
    }

    /// A TXT record of `name`'s, of one string.
    pub(crate) fn txt(name: &str, text: &str) -> (String, RData) {
        record(name, RData::TXT(TXT::new(vec![text.into()])))
    }

    /// An A record of `name`'s.
    pub(crate) fn a(name: &str, ip: &str) -> (String, RData) {
        record(name, RData::A(A(ip.parse().unwrap())))
    }

    /// A resolver asking only a DNS server on a loopback port, which
    /// answers each question as `reply` says of its name (no final dot)
    /// and type.
    pub(crate) async fn fake_dns(
        reply: impl Fn(&str, RecordType) -> Reply + Send + 'static,
    ) -> TokioResolver {
        let fake = Arc::new(tokio::net::UdpSocket::bind("127.0.0.1:0").await.unwrap());
        let port = fake.local_addr().unwrap().port();
        tokio::spawn(async move {
            let mut buf = [0; 512];
            loop {
                let (n, from) = fake.recv_from(&mut buf).await.unwrap();
                let asked = Message::from_vec(&buf[..n]).unwrap();
                let query = asked.queries[0].clone();
                let name = query.name().to_ascii();
                let mut answer = Message::response(asked.metadata.id, asked.metadata.op_code);
                answer.metadata.recursion_desired = true;
                answer.metadata.recursion_available = true;
                answer.add_query(query.clone());
                match reply(name.trim_end_matches('.'), query.query_type()) {
                    Reply::Records(records) => {
                        for (name, data) in records {
                            let name = DnsName::from_ascii(format!("{name}.")).unwrap();
                            answer.add_answer(Record::from_rdata(name, 60, data));
                        }
                    }
                    Reply::NoSuchName => answer.metadata.response_code = ResponseCode::NXDomain,
                    Reply::Fail => answer.metadata.response_code = ResponseCode::ServFail,
                    Reply::Silent => continue,
                }
                fake.send_to(&answer.to_vec().unwrap(), from).await.unwrap();
            }
        });
        let mut udp = ConnectionConfig::udp();
        udp.port = port;
        resolver(vec![NameServerConfig::new(
            Ipv4Addr::LOCALHOST.into(),
            true,
            vec![udp],
        )])
    }

    /// The client over a fake DNS server answering as `reply` says.
    pub(crate) async fn fake_net(
        allow_private: bool,
        reply: impl Fn(&str, RecordType) -> Reply + Send + 'static,
    ) -> Net {
        Net::over(fake_dns(reply).await, allow_private, DNS_WAIT)
    }

    #[tokio::test]
    async fn txt_records_from_dns() {
        let net = fake_net(false, |name, _| match name {
            "_atproto.alice.test" => Reply::Records(vec![
                record(
                    "_atproto.alice.test",
                    RData::CNAME(CNAME(DnsName::from_ascii("did.alice.test.").unwrap())),
                ),
                txt("did.alice.test", "did=did:plc:alice"),
            ]),
            _ => Reply::Fail,
        })
        .await;
        // The TXT records alone, of the name its CNAME names.
        assert_eq!(
            net.txt("_atproto.alice.test").await,
            Ok(vec![b"did=did:plc:alice".to_vec()])
        );
        // A server that cannot answer is no answer, not none.
        assert_eq!(
            net.txt("_atproto.bob.test").await,
            Err("_atproto.bob.test had no DNS answer".into())
        );
    }

    #[tokio::test]
    async fn hosts_resolve_to_their_public_addresses_alone() {
        let resolve = |net: Net, host: &str| {
            let only = PublicOnly {
                dns: net.dns.clone(),
                wait: Duration::from_millis(300),
            };
            let name: Name = host.parse().unwrap();
            async move { only.resolve(name).await }
        };
        let net = || {
            fake_net(false, |name, kind| match (name, kind) {
                ("mixed.test", RecordType::A) => Reply::Records(vec![
                    a("mixed.test", "10.0.0.1"),
                    a("mixed.test", "1.1.1.1"),
                    a("mixed.test", "127.0.0.1"),
                ]),
                ("inside.test", RecordType::A) => {
                    Reply::Records(vec![a("inside.test", "192.168.1.1")])
                }
                ("gone.test", _) => Reply::NoSuchName,
                ("silent.test", _) => Reply::Silent,
                ("broken.test", _) => Reply::Fail,
                _ => Reply::Records(Vec::new()),
            })
        };
        let found: Vec<SocketAddr> = resolve(net().await, "mixed.test").await.unwrap().collect();
        assert_eq!(found, ["1.1.1.1:0".parse::<SocketAddr>().unwrap()]);
        let refused = |host: &'static str| {
            let net = net();
            async move {
                let e = resolve(net.await, host).await.err().unwrap();
                let r = e.downcast_ref::<Refused>().unwrap();
                (r.to_string(), r.answered)
            }
        };
        assert_eq!(
            refused("inside.test").await,
            ("inside.test resolves to no public address".into(), true)
        );
        assert_eq!(
            refused("gone.test").await,
            ("gone.test does not resolve".into(), true)
        );
        assert_eq!(
            refused("broken.test").await,
            ("broken.test does not resolve".into(), false)
        );
        assert_eq!(
            refused("silent.test").await,
            ("silent.test did not resolve in time".into(), false)
        );
    }

    #[tokio::test]
    async fn refusals_before_a_request() {
        let net = fake_net(false, |name, _| Reply::Records(vec![a(name, "127.0.0.1")])).await;
        let wait = Duration::from_secs(5);
        let failed = |u: &str| {
            let url = Url::parse(u).unwrap();
            let net = &net;
            async move { net.fetch(&url, wait, 1024).await.err().unwrap() }
        };
        // A host whose every address is private is refused on DNS's answer.
        let f = failed("https://inside.test/").await;
        assert_eq!(
            (f.to_string(), f.answered),
            ("inside.test resolves to no public address".into(), true)
        );
        // A URL itself refused is no answer of anyone's.
        let f = failed("http://example.com/").await;
        assert_eq!(
            (f.why, f.answered),
            ("http://example.com is not https".into(), false)
        );
        let url = Url::parse("https://127.0.0.1/").unwrap();
        let f = net.fetch_json(&url, wait, 1024).await.err().unwrap();
        assert_eq!(String::from(f), "https://127.0.0.1 is not a public address");
    }

    #[tokio::test]
    async fn answers_read_within_their_bounds() {
        use axum::response::Redirect;
        use axum::routing::get;
        let app = axum::Router::new()
            .route(
                "/json",
                get(|headers: axum::http::HeaderMap| async move {
                    headers.get("accept").unwrap().to_str().unwrap().to_string()
                }),
            )
            .route("/big", get(|| async { "x".repeat(2048) }))
            .route(
                "/streamed",
                get(|| async {
                    let chunks = (0..4).map(|_| Ok::<_, std::io::Error>(vec![b'x'; 512]));
                    axum::body::Body::from_stream(futures::stream::iter(chunks))
                }),
            )
            .route("/slow", get(|| tokio::time::sleep(Duration::from_secs(5))))
            .route("/loop", get(|| async { Redirect::temporary("/loop") }))
            .route(
                "/away",
                get(|| async { Redirect::temporary("ftp://example.com/x") }),
            )
            .route("/there", get(|| async { Redirect::temporary("/json") }));
        let base = crate::tests::serve(app).await;
        let net = Net::over(resolver(Vec::new()), true, DNS_WAIT);
        let url = |p: &str| Url::parse(&format!("{base}{p}")).unwrap();
        let wait = Duration::from_secs(5);
        let got = net.fetch_json(&url("/json"), wait, 1024).await.unwrap();
        assert_eq!(
            (got.status, got.body, got.redirected),
            (200, b"application/json".to_vec(), false)
        );
        assert!(
            net.fetch(&url("/there"), wait, 1024)
                .await
                .unwrap()
                .redirected
        );
        let failed = |p: &str, max: usize, wait: Duration| {
            let url = url(p);
            let net = &net;
            async move {
                let f = net.fetch(&url, wait, max).await.err().unwrap();
                (f.why, f.answered)
            }
        };
        let too_large = ("its answer is too large".to_string(), true);
        // Said too large by its length, or found so as it is read.
        assert_eq!(failed("/big", 1024, wait).await, too_large);
        assert_eq!(failed("/streamed", 1024, wait).await, too_large);
        assert_eq!(
            failed("/slow", 1024, Duration::from_millis(100)).await,
            ("it did not answer in time".into(), false)
        );
        // Redirects: a few, and only where a request may go.
        assert_eq!(
            failed("/loop", 1024, wait).await,
            ("too many redirects".into(), true)
        );
        let (why, answered) = failed("/away", 1024, wait).await;
        assert!(why.ends_with("is not https") && answered, "{why}");
        // A request's own timeout, as the blob proxy's body has, and one
        // that could not be made.
        let slow = net
            .get(&url("/slow"))
            .unwrap()
            .timeout(Duration::from_millis(100));
        let f = net.send(slow, wait, 1024).await.err().unwrap();
        assert_eq!(
            (f.why, f.answered),
            ("it did not answer in time".into(), false)
        );
        let bad = net.get(&url("/json")).unwrap().header("x-bad", "a\nb");
        let f = net.send(bad, wait, 1024).await.err().unwrap();
        assert_eq!((f.why, f.answered), ("the request failed".into(), false));
        // An answer cut short fails as it is read.
        let cut = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let short = Url::parse(&format!("http://{}/", cut.local_addr().unwrap())).unwrap();
        tokio::spawn(async move {
            use tokio::io::{AsyncReadExt, AsyncWriteExt};
            let (mut s, _) = cut.accept().await.unwrap();
            let _ = s.read(&mut [0; 1024]).await.unwrap();
            let head = b"HTTP/1.1 200 OK\r\nContent-Length: 100\r\n\r\nshort";
            s.write_all(head).await.unwrap();
        });
        let f = net.fetch(&short, wait, 1024).await.err().unwrap();
        assert_eq!((f.why, f.answered), ("the request failed".into(), false));
    }

    /// A call sent in a trace hands it on as `traceparent`, and each call
    /// is logged by host and path alone: one given up on as `abandoned`.
    #[test]
    fn calls_hand_their_trace_on_and_are_logged() {
        use axum::routing::get;
        let rt = tokio::runtime::Builder::new_current_thread()
            .enable_all()
            .build()
            .unwrap();
        let id = "4bf92f3577b34da6a3ce929d0e0e4736";
        let lines = crate::telemetry::tests::logged(|| {
            rt.block_on(async {
                let parent = |h: axum::http::HeaderMap| async move {
                    let sent = h
                        .get("traceparent")
                        .map(|v| v.to_str().unwrap().to_string());
                    sent.unwrap_or_default()
                };
                let app = axum::Router::new()
                    .route("/parent", get(parent))
                    .route("/slow", get(|| tokio::time::sleep(Duration::from_secs(5))));
                let base = crate::tests::serve(app).await;
                let net = Net::over(resolver(Vec::new()), true, DNS_WAIT);
                let url = |p: &str| Url::parse(&format!("{base}{p}?secret=1")).unwrap();
                let req = net.get(&url("/parent")).unwrap();
                let sent = crate::telemetry::traced(id.into(), net.execute(req)).await;
                let said = sent.unwrap().text().await.unwrap();
                assert!(said.starts_with(&format!("00-{id}-")), "{said}");
                let req = net.get(&url("/parent")).unwrap();
                assert_eq!(net.execute(req).await.unwrap().text().await.unwrap(), "");
                // Cut off by its own wait: timed out.
                let gone = net
                    .fetch(&url("/slow"), Duration::from_millis(100), 1024)
                    .await;
                assert!(gone.is_err());
                // Given up on by what asked, long before its wait: abandoned.
                let slow = url("/slow");
                let fetching = net.fetch(&slow, Duration::from_secs(5), 1024);
                let left = tokio::time::timeout(Duration::from_millis(100), fetching).await;
                assert!(left.is_err());
            })
        });
        let calls: Vec<&serde_json::Value> = lines
            .iter()
            .filter(|l| l["message"] == "outgoing")
            .collect();
        assert_eq!(calls.len(), 4, "{lines:#?}");
        assert_eq!(calls[0]["trace_id"], id);
        assert_eq!(calls[0]["url.path"], "/parent");
        assert_eq!(calls[0]["http.response.status_code"], 200);
        assert_eq!(calls[0]["server.address"], "127.0.0.1");
        assert!(calls[1].get("trace_id").is_none());
        assert_eq!(
            (&calls[2]["error.type"], &calls[2]["level"]),
            (&"timeout".into(), &"WARN".into())
        );
        assert_eq!(
            (&calls[3]["error.type"], &calls[3]["level"]),
            (&"abandoned".into(), &"DEBUG".into())
        );
        assert!(!lines.iter().any(|l| l.to_string().contains("secret")));
    }
}