feat: add DNS resolution for upstream hostname endpoints (#77)

Addresses the "DNS resolution for provider endpoints" item in #23.

  Upstream endpoints currently require literal `IP:port` addresses
  (`127.0.0.1:8080`). This makes it impossible to route to external
  providers or Kubernetes services by hostname (e.g.
  `api.openai.com:443`, `my-service.ns.svc.cluster.local:8080`).

  This adds a `resolve_address()` function that tries direct
  `SocketAddr` parsing first, then falls back to DNS resolution via
  `ToSocketAddrs`. Existing `IP:port` configs are unchanged.

  ## Summary
  - Replace inline `address.parse::<SocketAddr>()` with
    `resolve_address()` in `upstream_peer.rs`
  - `resolve_address()` tries `SocketAddr` parse first (zero-cost for
    IP addresses), falls back to `ToSocketAddrs` for hostnames
  - Clear error messages for DNS failure and zero-address results
  - SNI is automatically derived from the hostname when `sni` is not
    explicitly configured (existing behavior, no change)

  ## Test plan
  - [x] `resolve_address` parses `127.0.0.1:8080` directly
  - [x] `resolve_address` resolves `localhost:8080` via DNS
  - [x] `resolve_address` fails for address without port
  - [x] `build_peer` succeeds with hostname address (`localhost:8080`)
  - [x] `build_peer` fails for unresolvable hostname
  - [x] All 20 existing `upstream_peer` tests pass
  - [x] `cargo check --workspace` clean

Signed-off-by: Brent Salisbury <bsalisbu@redhat.com>

Author: nerdalert

examples/README.md

@@ -35,6 +35,7 @@ page.
 | [rate-limiting.yaml](configs/traffic-management/rate-limiting.yaml) | Token bucket rate limiter with per-IP and global modes |
 | [static-response.yaml](configs/traffic-management/static-response.yaml) | Fixed response without upstream |
 | [redirect.yaml](configs/traffic-management/redirect.yaml) | 3xx redirects with path/query template substitution |
+| [hostname-upstream.yaml](configs/traffic-management/hostname-upstream.yaml) | Resolve hostname upstream endpoints such as `localhost:9000` |
 
 ### Payload Processing
 

examples/configs/traffic-management/hostname-upstream.yaml

@@ -0,0 +1,30 @@
+# Hostname Upstream Endpoints
+#
+# Demonstrates using DNS hostnames instead of IP addresses for
+# upstream endpoints. The proxy resolves hostnames to IP addresses
+# at connection time, preferring IPv4 when multiple records exist.
+#
+# Example:
+#
+#   curl http://localhost:8080/
+#
+# The request is forwarded to the backend resolved from the
+# hostname endpoint.
+
+listeners:
+  - name: default
+    address: "0.0.0.0:8080"
+    filter_chains: [main]
+
+filter_chains:
+  - name: main
+    filters:
+      - filter: router
+        routes:
+          - path_prefix: "/"
+            cluster: backend
+      - filter: load_balancer
+        clusters:
+          - name: backend
+            endpoints:
+              - "localhost:9000"

protocol/src/http/pingora/handler/upstream_peer.rs

@@ -5,7 +5,7 @@
 //!
 //! [`Upstream`]: praxis_core::connectivity::Upstream
 
-use std::sync::Arc;
+use std::{net::ToSocketAddrs, sync::Arc};
 
 use pingora_core::{Result, upstreams::peer::HttpPeer};
 use praxis_core::connectivity::Upstream;
@@ -49,13 +49,7 @@ pub(super) fn execute(ctx: &mut PingoraRequestCtx) -> Result<Box<HttpPeer>> {
 /// [`HttpPeer`]: pingora_core::upstreams::peer::HttpPeer
 /// [`CachedClusterTls`]: praxis_tls::CachedClusterTls
 fn build_peer(upstream: &Upstream) -> Result<Box<HttpPeer>> {
-    let addr: std::net::SocketAddr = upstream.address.parse().map_err(|e| {
-        tracing::warn!(address = %upstream.address, error = %e, "failed to parse upstream address");
-        pingora_core::Error::explain(
-            pingora_core::ErrorType::InternalError,
-            "upstream address resolution failed".to_owned(),
-        )
-    })?;
+    let addr: std::net::SocketAddr = resolve_address(&upstream.address)?;
 
     let tls_enabled = upstream.tls.is_some();
     let sni = upstream
@@ -133,6 +127,57 @@ fn derive_sni(address: &str) -> String {
     host.to_owned()
 }
 
+/// Resolve an upstream address to a [`SocketAddr`].
+///
+/// Tries direct [`SocketAddr`] parsing first. If that fails (e.g. the
+/// address contains a hostname like `api.openai.com:443`), falls back
+/// to [`ToSocketAddrs`] which performs DNS resolution.
+///
+/// When DNS returns multiple records, prefers IPv4 addresses to avoid
+/// connectivity issues in dual-stack environments where IPv6 may be
+/// unreachable.
+///
+/// Note: DNS resolution is synchronous and runs on the request path.
+/// A future iteration may move resolution to config/load-balancer
+/// time or integrate an async cached resolver.
+///
+/// [`SocketAddr`]: std::net::SocketAddr
+/// [`ToSocketAddrs`]: std::net::ToSocketAddrs
+fn resolve_address(address: &str) -> Result<std::net::SocketAddr> {
+    if let Ok(addr) = address.parse::<std::net::SocketAddr>() {
+        return Ok(addr);
+    }
+
+    let addrs: Vec<std::net::SocketAddr> = address
+        .to_socket_addrs()
+        .map_err(|e| {
+            tracing::warn!(address, error = %e, "failed to resolve upstream address");
+            pingora_core::Error::explain(
+                pingora_core::ErrorType::InternalError,
+                format!("upstream address resolution failed for '{address}': {e}"),
+            )
+        })?
+        .collect();
+
+    select_preferred_address(&addrs, address)
+}
+
+/// Select the preferred address from resolved results, favoring IPv4.
+fn select_preferred_address(addrs: &[std::net::SocketAddr], address: &str) -> Result<std::net::SocketAddr> {
+    addrs
+        .iter()
+        .find(|a| a.is_ipv4())
+        .or_else(|| addrs.first())
+        .copied()
+        .ok_or_else(|| {
+            tracing::warn!(address, "DNS resolved but returned no addresses");
+            pingora_core::Error::explain(
+                pingora_core::ErrorType::InternalError,
+                format!("upstream address '{address}' resolved to zero addresses"),
+            )
+        })
+}
+
 // -----------------------------------------------------------------------------
 // Tests
 // -----------------------------------------------------------------------------
@@ -145,6 +190,7 @@ fn derive_sni(address: &str) -> String {
     clippy::field_reassign_with_default,
     clippy::too_many_lines,
     clippy::significant_drop_tightening,
+    clippy::print_stderr,
     reason = "tests"
 )]
 mod tests {
@@ -250,11 +296,73 @@ mod tests {
         );
     }
 
+    #[test]
+    fn resolve_address_parses_socket_addr() {
+        let addr = resolve_address("127.0.0.1:8080").expect("socket addr should parse");
+        assert_eq!(addr.port(), 8080, "port should match");
+    }
+
+    #[test]
+    fn resolve_address_resolves_localhost() {
+        if !localhost_resolution_available() {
+            eprintln!("skipping: localhost did not resolve in this environment");
+            return;
+        }
+        let addr = resolve_address("localhost:8080").expect("localhost should resolve");
+        assert_eq!(addr.port(), 8080, "port should match");
+    }
+
+    #[test]
+    fn resolve_address_fails_for_no_port() {
+        assert!(
+            resolve_address("127.0.0.1").is_err(),
+            "address without port should return error"
+        );
+    }
+
+    #[test]
+    fn hostname_address_builds_peer() {
+        if !localhost_resolution_available() {
+            eprintln!("skipping: localhost did not resolve in this environment");
+            return;
+        }
+        assert!(
+            build_peer(&make_upstream("localhost:8080")).is_ok(),
+            "hostname address should build peer via DNS resolution"
+        );
+    }
+
+    #[test]
+    fn select_preferred_address_prefers_ipv4_from_mixed_results() {
+        let ipv6: std::net::SocketAddr = "[::1]:8080".parse().unwrap();
+        let ipv4: std::net::SocketAddr = "127.0.0.1:8080".parse().unwrap();
+        let selected =
+            select_preferred_address(&[ipv6, ipv4], "mixed.example:8080").expect("mixed results should select address");
+        assert_eq!(selected, ipv4, "IPv4 should be preferred over IPv6");
+    }
+
+    #[test]
+    fn select_preferred_address_returns_ipv6_when_ipv6_only() {
+        let ipv6: std::net::SocketAddr = "[::1]:8080".parse().unwrap();
+        let selected =
+            select_preferred_address(&[ipv6], "ipv6.example:8080").expect("IPv6-only results should select IPv6");
+        assert_eq!(selected, ipv6, "IPv6 should be used when it is the only result");
+    }
+
+    #[test]
+    fn select_preferred_address_errors_on_empty_results() {
+        let err = select_preferred_address(&[], "empty.example:8080").expect_err("empty DNS result should fail");
+        assert!(
+            err.to_string().contains("resolved to zero addresses"),
+            "unexpected error: {err}"
+        );
+    }
+
     #[test]
     fn invalid_address_returns_error() {
         assert!(
-            build_peer(&make_upstream("not-an-address")).is_err(),
-            "invalid address should return error"
+            build_peer(&make_upstream("invalid host:8080")).is_err(),
+            "syntactically invalid address should return error"
         );
     }
 
@@ -367,6 +475,13 @@ mod tests {
     // Test Utilities
     // -------------------------------------------------------------------------
 
+    /// Check whether `localhost` DNS resolution is available in this environment.
+    fn localhost_resolution_available() -> bool {
+        "localhost:8080"
+            .to_socket_addrs()
+            .is_ok_and(|mut addrs| addrs.next().is_some())
+    }
+
     /// Create a test upstream with the given address (no TLS).
     fn make_upstream(address: &str) -> Upstream {
         Upstream {

tests/integration/tests/suite/examples/hostname_upstream.rs

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 Praxis Contributors
+
+//! Tests for the hostname upstream example configuration.
+
+use std::collections::HashMap;
+
+use praxis_test_utils::{free_port, http_get, start_backend_with_shutdown};
+
+// -----------------------------------------------------------------------------
+// Tests
+// -----------------------------------------------------------------------------
+
+#[test]
+fn hostname_upstream_routes_to_backend() {
+    let backend_port_guard = start_backend_with_shutdown("hostname-backend");
+    let backend_port = backend_port_guard.port();
+    let proxy_port = free_port();
+    let config = super::load_example_config(
+        "traffic-management/hostname-upstream.yaml",
+        proxy_port,
+        HashMap::from([("localhost:9000", backend_port)]),
+    );
+    let proxy = praxis_test_utils::start_proxy(&config);
+    let (status, body) = http_get(proxy.addr(), "/", None);
+    assert_eq!(status, 200, "hostname upstream example should return 200");
+    assert_eq!(body, "hostname-backend", "proxy should forward to hostname upstream");
+}

tests/integration/tests/suite/examples/mod.rs

@@ -15,6 +15,7 @@ mod conditional_filters;
 mod default_config;
 mod header_manipulation;
 mod health_checks;
+mod hostname_upstream;
 mod least_connections;
 mod logging;
 mod max_body_guard;