feat: DNS-over-HTTPS (DoH) upstream forwarding (#14)

* feat: DNS-over-HTTPS upstream forwarding

Encrypt upstream queries via DoH — ISPs see HTTPS traffic on port 443,
not plaintext DNS on port 53. URL scheme determines transport:
https:// = DoH, bare IP = plain UDP. Falls back to Quad9 DoH when
system resolver cannot be detected.

- Upstream enum (Udp/Doh) with Display and PartialEq
- BytePacketBuffer::from_bytes constructor
- reqwest http2 feature for DoH server compatibility
- network_watch_loop guards against DoH→UDP silent downgrade
- 5 new tests (mock DoH server, HTTP errors, timeout)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* style: cargo fmt

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add DoH to README — Why Numa, comparison table, roadmap

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

src/api.rs

@@ -9,7 +9,7 @@ use axum::{Json, Router};
 use serde::{Deserialize, Serialize};
 
 use crate::ctx::ServerCtx;
-use crate::forward::forward_query;
+use crate::forward::{forward_query, Upstream};
 use crate::query_log::QueryLogFilter;
 use crate::question::QueryType;
 use crate::stats::QueryPath;
@@ -355,9 +355,9 @@ async fn diagnose(
     }
 
     // Check upstream (async, no locks held)
-    let upstream = *ctx.upstream.lock().unwrap();
+    let upstream = ctx.upstream.lock().unwrap().clone();
     let (upstream_matched, upstream_detail) =
-        forward_query_for_diagnose(&domain_lower, upstream, ctx.timeout).await;
+        forward_query_for_diagnose(&domain_lower, &upstream, ctx.timeout).await;
     steps.push(DiagnoseStep {
         source: "upstream".to_string(),
         matched: upstream_matched,
@@ -373,7 +373,7 @@ async fn diagnose(
 
 async fn forward_query_for_diagnose(
     domain: &str,
-    upstream: std::net::SocketAddr,
+    upstream: &Upstream,
     timeout: std::time::Duration,
 ) -> (bool, String) {
     use crate::packet::DnsPacket;

src/buffer.rs

@@ -21,6 +21,13 @@ impl BytePacketBuffer {
         }
     }
 
+    pub fn from_bytes(data: &[u8]) -> Self {
+        let mut buf = Self::new();
+        let len = data.len().min(BUF_SIZE);
+        buf.buf[..len].copy_from_slice(&data[..len]);
+        buf
+    }
+
     pub fn pos(&self) -> usize {
         self.pos
     }

src/ctx.rs

@@ -12,7 +12,7 @@ use crate::blocklist::BlocklistStore;
 use crate::buffer::BytePacketBuffer;
 use crate::cache::DnsCache;
 use crate::config::ZoneMap;
-use crate::forward::forward_query;
+use crate::forward::{forward_query, Upstream};
 use crate::header::ResultCode;
 use crate::lan::PeerStore;
 use crate::override_store::OverrideStore;
@@ -35,7 +35,7 @@ pub struct ServerCtx {
     pub services: Mutex<ServiceStore>,
     pub lan_peers: Mutex<PeerStore>,
     pub forwarding_rules: Vec<ForwardingRule>,
-    pub upstream: Mutex<SocketAddr>,
+    pub upstream: Mutex<Upstream>,
     pub upstream_auto: bool,
     pub upstream_port: u16,
     pub lan_ip: Mutex<std::net::Ipv4Addr>,
@@ -143,9 +143,11 @@ pub async fn handle_query(
                 (resp, QueryPath::Cached)
             } else {
                 let upstream =
-                    crate::system_dns::match_forwarding_rule(&qname, &ctx.forwarding_rules)
-                        .unwrap_or_else(|| *ctx.upstream.lock().unwrap());
-                match forward_query(&query, upstream, ctx.timeout).await {
+                    match crate::system_dns::match_forwarding_rule(&qname, &ctx.forwarding_rules) {
+                        Some(addr) => Upstream::Udp(addr),
+                        None => ctx.upstream.lock().unwrap().clone(),
+                    };
+                match forward_query(&query, &upstream, ctx.timeout).await {
                     Ok(resp) => {
                         ctx.cache.lock().unwrap().insert(&qname, qtype, &resp);
                         (resp, QueryPath::Forwarded)

src/forward.rs

@@ -1,3 +1,4 @@
+use std::fmt;
 use std::net::SocketAddr;
 use std::time::Duration;
 
@@ -8,7 +9,46 @@ use crate::buffer::BytePacketBuffer;
 use crate::packet::DnsPacket;
 use crate::Result;
 
+#[derive(Clone)]
+pub enum Upstream {
+    Udp(SocketAddr),
+    Doh {
+        url: String,
+        client: reqwest::Client,
+    },
+}
+
+impl PartialEq for Upstream {
+    fn eq(&self, other: &Self) -> bool {
+        match (self, other) {
+            (Self::Udp(a), Self::Udp(b)) => a == b,
+            (Self::Doh { url: a, .. }, Self::Doh { url: b, .. }) => a == b,
+            _ => false,
+        }
+    }
+}
+
+impl fmt::Display for Upstream {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            Upstream::Udp(addr) => write!(f, "{}", addr),
+            Upstream::Doh { url, .. } => f.write_str(url),
+        }
+    }
+}
+
 pub async fn forward_query(
+    query: &DnsPacket,
+    upstream: &Upstream,
+    timeout_duration: Duration,
+) -> Result<DnsPacket> {
+    match upstream {
+        Upstream::Udp(addr) => forward_udp(query, *addr, timeout_duration).await,
+        Upstream::Doh { url, client } => forward_doh(query, url, client, timeout_duration).await,
+    }
+}
+
+async fn forward_udp(
     query: &DnsPacket,
     upstream: SocketAddr,
     timeout_duration: Duration,
@@ -33,3 +73,174 @@ pub async fn forward_query(
 
     DnsPacket::from_buffer(&mut recv_buffer)
 }
+
+async fn forward_doh(
+    query: &DnsPacket,
+    url: &str,
+    client: &reqwest::Client,
+    timeout_duration: Duration,
+) -> Result<DnsPacket> {
+    let mut send_buffer = BytePacketBuffer::new();
+    query.write(&mut send_buffer)?;
+
+    let resp = timeout(
+        timeout_duration,
+        client
+            .post(url)
+            .header("content-type", "application/dns-message")
+            .header("accept", "application/dns-message")
+            .body(send_buffer.filled().to_vec())
+            .send(),
+    )
+    .await??
+    .error_for_status()?;
+
+    let bytes = resp.bytes().await?;
+    log::debug!("DoH response: {} bytes", bytes.len());
+
+    let mut recv_buffer = BytePacketBuffer::from_bytes(&bytes);
+    DnsPacket::from_buffer(&mut recv_buffer)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::future::IntoFuture;
+
+    use crate::header::ResultCode;
+    use crate::question::{DnsQuestion, QueryType};
+    use crate::record::DnsRecord;
+
+    #[test]
+    fn upstream_display_udp() {
+        let u = Upstream::Udp("9.9.9.9:53".parse().unwrap());
+        assert_eq!(u.to_string(), "9.9.9.9:53");
+    }
+
+    #[test]
+    fn upstream_display_doh() {
+        let u = Upstream::Doh {
+            url: "https://dns.quad9.net/dns-query".to_string(),
+            client: reqwest::Client::new(),
+        };
+        assert_eq!(u.to_string(), "https://dns.quad9.net/dns-query");
+    }
+
+    fn make_query() -> DnsPacket {
+        let mut q = DnsPacket::new();
+        q.header.id = 0xABCD;
+        q.header.recursion_desired = true;
+        q.questions
+            .push(DnsQuestion::new("example.com".to_string(), QueryType::A));
+        q
+    }
+
+    fn make_response(query: &DnsPacket) -> DnsPacket {
+        let mut resp = DnsPacket::response_from(query, ResultCode::NOERROR);
+        resp.answers.push(DnsRecord::A {
+            domain: "example.com".to_string(),
+            addr: "93.184.216.34".parse().unwrap(),
+            ttl: 300,
+        });
+        resp
+    }
+
+    fn to_wire(pkt: &DnsPacket) -> Vec<u8> {
+        let mut buf = BytePacketBuffer::new();
+        pkt.write(&mut buf).unwrap();
+        buf.filled().to_vec()
+    }
+
+    #[tokio::test]
+    async fn doh_mock_server_resolves() {
+        let query = make_query();
+        let response_bytes = to_wire(&make_response(&query));
+
+        let app = axum::Router::new().route(
+            "/dns-query",
+            axum::routing::post(move || {
+                let body = response_bytes.clone();
+                async move {
+                    (
+                        [(axum::http::header::CONTENT_TYPE, "application/dns-message")],
+                        body,
+                    )
+                }
+            }),
+        );
+
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        tokio::spawn(axum::serve(listener, app).into_future());
+
+        let upstream = Upstream::Doh {
+            url: format!("http://{}/dns-query", addr),
+            client: reqwest::Client::new(),
+        };
+
+        let result = forward_query(&query, &upstream, Duration::from_secs(2))
+            .await
+            .expect("DoH forward should succeed");
+
+        assert_eq!(result.header.id, 0xABCD);
+        assert!(result.header.response);
+        assert_eq!(result.header.rescode, ResultCode::NOERROR);
+        assert_eq!(result.answers.len(), 1);
+        match &result.answers[0] {
+            DnsRecord::A { domain, addr, ttl } => {
+                assert_eq!(domain, "example.com");
+                assert_eq!(
+                    *addr,
+                    "93.184.216.34".parse::<std::net::Ipv4Addr>().unwrap()
+                );
+                assert_eq!(*ttl, 300);
+            }
+            other => panic!("expected A record, got {:?}", other),
+        }
+    }
+
+    #[tokio::test]
+    async fn doh_http_error_propagates() {
+        let app = axum::Router::new().route(
+            "/dns-query",
+            axum::routing::post(|| async {
+                (axum::http::StatusCode::INTERNAL_SERVER_ERROR, "bad")
+            }),
+        );
+
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        tokio::spawn(axum::serve(listener, app).into_future());
+
+        let upstream = Upstream::Doh {
+            url: format!("http://{}/dns-query", addr),
+            client: reqwest::Client::new(),
+        };
+
+        let result = forward_query(&make_query(), &upstream, Duration::from_secs(2)).await;
+        assert!(result.is_err());
+    }
+
+    #[tokio::test]
+    async fn doh_timeout() {
+        let app = axum::Router::new().route(
+            "/dns-query",
+            axum::routing::post(|| async {
+                tokio::time::sleep(Duration::from_secs(10)).await;
+                "never"
+            }),
+        );
+
+        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+        let addr = listener.local_addr().unwrap();
+        tokio::spawn(axum::serve(listener, app).into_future());
+
+        let upstream = Upstream::Doh {
+            url: format!("http://{}/dns-query", addr),
+            client: reqwest::Client::new(),
+        };
+
+        let result = forward_query(&make_query(), &upstream, Duration::from_millis(100)).await;
+        assert!(result.is_err());
+    }
+}

src/main.rs

@@ -11,6 +11,7 @@ use numa::buffer::BytePacketBuffer;
 use numa::cache::DnsCache;
 use numa::config::{build_zone_map, load_config, ConfigLoad};
 use numa::ctx::{handle_query, ServerCtx};
+use numa::forward::Upstream;
 use numa::override_store::OverrideStore;
 use numa::query_log::QueryLog;
 use numa::service_store::ServiceStore;
@@ -111,13 +112,27 @@ async fn main() -> numa::Result<()> {
             .default_upstream
             .or_else(numa::system_dns::detect_dhcp_dns)
             .unwrap_or_else(|| {
-                info!("could not detect system DNS, falling back to 9.9.9.9 (Quad9)");
-                "9.9.9.9".to_string()
+                info!("could not detect system DNS, falling back to Quad9 DoH");
+                "https://dns.quad9.net/dns-query".to_string()
             })
     } else {
         config.upstream.address.clone()
     };
-    let upstream: SocketAddr = format!("{}:{}", upstream_addr, config.upstream.port).parse()?;
+
+    let upstream: Upstream = if upstream_addr.starts_with("https://") {
+        let client = reqwest::Client::builder()
+            .use_rustls_tls()
+            .build()
+            .unwrap_or_default();
+        Upstream::Doh {
+            url: upstream_addr,
+            client,
+        }
+    } else {
+        let addr: SocketAddr = format!("{}:{}", upstream_addr, config.upstream.port).parse()?;
+        Upstream::Udp(addr)
+    };
+    let upstream_label = upstream.to_string();
     let api_port = config.server.api_port;
 
     let mut blocklist = BlocklistStore::new();
@@ -217,7 +232,7 @@ async fn main() -> numa::Result<()> {
     let val_w = [
         config.server.bind_addr.len(),
         api_url.len(),
-        upstream.to_string().len(),
+        upstream_label.len(),
         config_label.len(),
         data_label.len(),
         services_label.len(),
@@ -261,7 +276,7 @@ async fn main() -> numa::Result<()> {
     row("DNS", g, &config.server.bind_addr);
     row("API", g, &api_url);
     row("Dashboard", g, &api_url);
-    row("Upstream", g, &upstream.to_string());
+    row("Upstream", g, &upstream_label);
     row("Zones", g, &format!("{} records", zone_count));
     row(
         "Cache",
@@ -298,7 +313,7 @@ async fn main() -> numa::Result<()> {
 
     info!(
         "numa listening on {}, upstream {}, {} zone records, cache max {}, API on port {}",
-        config.server.bind_addr, upstream, zone_count, config.cache.max_entries, api_port,
+        config.server.bind_addr, upstream_label, zone_count, config.cache.max_entries, api_port,
     );
 
     // Download blocklists on startup
@@ -413,20 +428,24 @@ async fn network_watch_loop(ctx: Arc<numa::ctx::ServerCtx>) {
             }
         }
 
-        // Check upstream change every 30s or immediately on LAN IP change
-        // (heavier — spawns scutil/ipconfig, only when auto-detected)
-        if ctx.upstream_auto && (changed || tick.is_multiple_of(6)) {
+        // Re-detect upstream every 30s or on LAN IP change (UDP only —
+        // DoH upstreams are explicitly configured via URL, not auto-detected)
+        if ctx.upstream_auto
+            && matches!(*ctx.upstream.lock().unwrap(), Upstream::Udp(_))
+            && (changed || tick.is_multiple_of(6))
+        {
             let dns_info = numa::system_dns::discover_system_dns();
             let new_addr = dns_info
                 .default_upstream
                 .or_else(numa::system_dns::detect_dhcp_dns)
                 .unwrap_or_else(|| "9.9.9.9".to_string());
-            if let Ok(new_upstream) =
+            if let Ok(new_sock) =
                 format!("{}:{}", new_addr, ctx.upstream_port).parse::<SocketAddr>()
             {
+                let new_upstream = Upstream::Udp(new_sock);
                 let mut upstream = ctx.upstream.lock().unwrap();
-                if new_upstream != *upstream {
-                    info!("upstream changed: {} → {}", *upstream, new_upstream);
+                if *upstream != new_upstream {
+                    info!("upstream changed: {} → {}", upstream, new_upstream);
                     *upstream = new_upstream;
                     changed = true;
                 }