Bind bootstrap DNS lookups to -S source address (#1)

.gitignore

@@ -1,3 +1,4 @@
+build/
 CMakeCache.txt
 CTestTestfile.cmake
 CMakeFiles/

CMakeLists.txt

@@ -182,6 +182,14 @@ else()
   message(STATUS "python3 found: ${PYTHON3_EXE}")
 
   enable_testing()
+
+  # Robot framework tests
   add_test(NAME robot COMMAND ${PYTHON3_EXE} -m robot.run functional_tests.robot
-           WORKING_DIRECTORY tests/robot)
+           WORKING_DIRECTORY ${CMAKE_SOURCE_DIR}/tests/robot)
 endif()
+
+# Clean target (removes entire build directory)
+add_custom_target(distclean
+  COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}
+  COMMENT "Removing build directory"
+)

README.md

@@ -187,7 +187,7 @@ Usage: ./https_dns_proxy [-a <listen_addr>] [-p <listen_port>] [-T <tcp_client_l
                          supports it (http, https, socks4a, socks5h), otherwise
                          initial DNS resolution will still be done via the
                          bootstrap DNS servers.
-  -S source_addr         Source IPv4/v6 address for outbound HTTPS connections.
+  -S source_addr         Source IPv4/v6 address for outbound HTTPS and bootstrap DNS.
                          (Default: system default)
   -x                     Use HTTP/1.1 instead of HTTP/2. Useful with broken
                          or limited builds of libcurl.
@@ -231,6 +231,17 @@ pip3 install robotframework
 python3 -m robot.run tests/robot/functional_tests.robot
 ```
 
+## Docker bootstrap DNS test
+
+There is a repeatable Docker-based test suite for validating proxy behavior
+including `-S` source address binding:
+
+```
+tests/docker/run_all_tests.sh
+```
+
+If your Docker CLI is not on `PATH`, you can set `DOCKER_BIN` to its full path.
+
 ## TODO
 
 * Add some tests.
@@ -241,4 +252,3 @@ python3 -m robot.run tests/robot/functional_tests.robot
 * Aaron Drew (aarond10@gmail.com): Original https_dns_proxy.
 * Soumya ([github.com/soumya92](https://github.com/soumya92)): RFC 8484 implementation.
 * baranyaib90 ([github.com/baranyaib90](https://github.com/baranyaib90)): fixes and improvements.
-

src/dns_poller.c

@@ -1,3 +1,4 @@
+#include <arpa/inet.h>
 #include <netdb.h>
 #include <string.h>
 
@@ -127,6 +128,36 @@ static void ares_cb(void *arg, int status, int __attribute__((unused)) timeouts,
   }
 }
 
+static void set_bootstrap_source_addr(ares_channel channel,
+                                      const char *source_addr,
+                                      int family) {
+  if (!source_addr) {
+    return;
+  }
+
+  struct in_addr addr_v4;
+  struct in6_addr addr_v6;
+
+  if (inet_pton(AF_INET, source_addr, &addr_v4) == 1) {
+    if (family == AF_INET6) {
+      WLOG("Bootstrap source address '%s' is IPv4, but IPv6-only mode is set",
+           source_addr);
+      return;
+    }
+    ares_set_local_ip4(channel, ntohl(addr_v4.s_addr));
+  } else if (inet_pton(AF_INET6, source_addr, &addr_v6) == 1) {
+    if (family == AF_INET) {
+      WLOG("Bootstrap source address '%s' is IPv6, but IPv4-only mode is set",
+           source_addr);
+      return;
+    }
+    ares_set_local_ip6(channel, (const unsigned char *)&addr_v6);
+  } else {
+    WLOG("Bootstrap source address '%s' is not a valid IP literal", source_addr);
+    return;
+  }
+}
+
 static ev_tstamp get_timeout(dns_poller_t *d)
 {
     static struct timeval max_tv = {.tv_sec = 5, .tv_usec = 0};
@@ -179,6 +210,7 @@ static void timer_cb(struct ev_loop __attribute__((unused)) *loop,
 void dns_poller_init(dns_poller_t *d, struct ev_loop *loop,
                      const char *bootstrap_dns,
                      int bootstrap_dns_polling_interval,
+                     const char *source_addr,
                      const char *hostname,
                      int family, dns_poller_cb cb, void *cb_data) {
   int r = ares_library_init(ARES_LIB_INIT_ALL);
@@ -207,6 +239,7 @@ void dns_poller_init(dns_poller_t *d, struct ev_loop *loop,
   d->loop = loop;
   d->hostname = hostname;
   d->family = family;
+  set_bootstrap_source_addr(d->ares, source_addr, family);
   d->cb = cb;
   d->polling_interval = bootstrap_dns_polling_interval;
   d->request_ongoing = 0;

src/dns_poller.h

@@ -37,13 +37,15 @@ typedef struct {
 // provided ev_loop. `bootstrap_dns` is a comma-separated list of DNS servers to
 // use for the lookup `hostname` every `interval_seconds`. For each successful
 // lookup, `cb` will be called with the resolved address.
+// `source_addr` optionally binds bootstrap DNS lookups to a specific IP.
 // `family` should be AF_INET for IPv4 or AF_UNSPEC for both IPv4 and IPv6.
 //
 // Note: hostname *not* copied. It should remain valid until
 // dns_poller_cleanup called.
 void dns_poller_init(dns_poller_t *d, struct ev_loop *loop,
                      const char *bootstrap_dns,
                      int bootstrap_dns_polling_interval,
+                     const char *source_addr,
                      const char *hostname,
                      int family, dns_poller_cb cb, void *cb_data);
 

src/main.c

@@ -423,7 +423,8 @@ int main(int argc, char *argv[]) {
     if (hostname_from_url(opt.resolver_url, hostname, sizeof(hostname))) {
       app.using_dns_poller = 1;
       dns_poller_init(&dns_poller, loop, opt.bootstrap_dns,
-                      opt.bootstrap_dns_polling_interval, hostname,
+                      opt.bootstrap_dns_polling_interval, opt.source_addr,
+                      hostname,
                       opt.ipv4 ? AF_INET : AF_UNSPEC,
                       dns_poll_cb, &app);
       ILOG("DNS polling initialized for '%s'", hostname);

src/options.c

@@ -254,7 +254,7 @@ void options_show_usage(int __attribute__((unused)) argc, char **argv) {
   printf("                         supports it (http, https, socks4a, socks5h), otherwise\n");
   printf("                         initial DNS resolution will still be done via the\n");
   printf("                         bootstrap DNS servers.\n");
-  printf("  -S source_addr         Source IPv4/v6 address for outbound HTTPS connections.\n");
+  printf("  -S source_addr         Source IPv4/v6 address for outbound HTTPS and bootstrap DNS.\n");
   printf("                         (Default: system default)\n");
   printf("  -x                     Use HTTP/1.1 instead of HTTP/2. Useful with broken\n"
          "                         or limited builds of libcurl.\n");

tests/docker/Dockerfile

@@ -0,0 +1,27 @@
+FROM ubuntu:24.04
+
+# Install all build and test dependencies in one layer
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+    iproute2 \
+    cmake \
+    build-essential \
+    libcurl4-openssl-dev \
+    libc-ares-dev \
+    libev-dev \
+    libsystemd-dev \
+    python3 \
+    python3-pip \
+    python3-venv \
+    dnsutils \
+    valgrind \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Robot Framework
+RUN pip3 install --break-system-packages robotframework
+
+WORKDIR /src
+
+# Default command: build and run tests
+# Symlink needed because Robot test expects binary at project root
+CMD ["bash", "-c", "cmake -S . -B build && cmake --build build && ln -sf build/https_dns_proxy https_dns_proxy && ctest --test-dir build --output-on-failure"]

tests/docker/run_all_tests.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Docker-based test runner for https_dns_proxy
+#
+# When to use:
+# - Full regression testing before commits/PRs
+# - CI/CD pipelines
+# - Developing on macOS (proxy uses Linux-specific syscalls like accept4, MSG_MORE)
+#
+# Runtime: ~2-3 minutes
+
+docker_bin="${DOCKER_BIN:-docker}"
+if ! command -v "$docker_bin" >/dev/null 2>&1; then
+  echo "docker not found; set DOCKER_BIN or install Docker." >&2
+  exit 1
+fi
+
+image="https_dns_proxy_test:latest"
+
+echo "==> Building Docker test image..."
+"$docker_bin" build -t "$image" -f tests/docker/Dockerfile . -q
+
+echo "==> Running tests..."
+"$docker_bin" run --rm \
+  --dns 1.1.1.1 --dns 8.8.8.8 \
+  -v "$PWD":/src "$image"

tests/robot/functional_tests.robot

@@ -203,8 +203,47 @@ Truncate UDP Impossible
   ...  Verify Truncation  txtfill4096.test.dnscheck.tools  4096  12  100  ANSWER: 0
 
 Source Address Binding
-  [Documentation]  Test source address binding with -S flag
+  [Documentation]  Test -S flag binds both HTTPS and bootstrap DNS to source address
+  [Tags]  bootstrap
+
   ${eth0_ip} =  Run  ip -4 addr show eth0 | grep inet | awk '{print $2}' | cut -d/ -f1 | tr -d '\\n'
-  Start Proxy  -S  ${eth0_ip}
+
+  # Use explicit resolver hostname to force bootstrap DNS resolution
+  Start Proxy  -S  ${eth0_ip}  -b  1.1.1.1,8.8.8.8  -r  https://dns.google/dns-query
+
+  # Wait for bootstrap DNS to complete
+  Sleep  2s
+
+  # Verify source address binding was applied
   Set To Dictionary  ${expected_logs}  Using source address=1
+
+  # Verify bootstrap DNS completed successfully
+  Set To Dictionary  ${expected_logs}  Received new DNS server IP=1
+
+  # Verify no bootstrap DNS failures
+  Append To List  ${error_logs}  DNS lookup of 'dns.google' failed
+
+  # Verify proxy works (HTTPS connection uses source binding)
   Run Dig
+
+Source Address Binding IPv6 With IPv4 Only Mode
+  [Documentation]  Test that IPv6 source address with -4 flag logs warning
+  [Tags]  bootstrap  validation
+
+  # Start proxy with IPv6 address in IPv4-only mode (-4 flag)
+  Start Proxy  -4  -S  ::1  -b  1.1.1.1,8.8.8.8  -r  https://dns.google/dns-query
+  Sleep  1s
+
+  # Verify warning is logged about address family mismatch
+  Set To Dictionary  ${expected_logs}  Bootstrap source address '::1' is IPv6, but IPv4-only mode is set=1
+
+Source Address Binding Invalid Address
+  [Documentation]  Test that invalid source address logs warning
+  [Tags]  bootstrap  validation
+
+  # Start proxy with invalid IP address
+  Start Proxy  -S  not-an-ip-address  -b  1.1.1.1,8.8.8.8  -r  https://dns.google/dns-query
+  Sleep  1s
+
+  # Verify warning is logged about invalid address
+  Set To Dictionary  ${expected_logs}  Bootstrap source address 'not-an-ip-address' is not a valid IP literal=1