Add DNS over HTTPS (DoH) client and resolvers

docker-compose.yml

@@ -10,7 +10,8 @@ services:
       - ./tests:/usr/src/code/tests
       - ./phpunit.xml:/usr/src/code/phpunit.xml
     dns:
-      - 127.0.0.1
+      - 8.8.8.8
+      - 1.1.1.1
     networks:
       - dns
     ports:

src/DNS/Http/Client.php

@@ -0,0 +1,223 @@
+<?php
+
+namespace Utopia\DNS\Http;
+
+use Exception;
+use Utopia\DNS\Message;
+
+/**
+ * DNS over HTTPS Client
+ *
+ * Implements DNS queries over HTTPS as specified in RFC 8484.
+ * Supports both GET and POST methods for sending DNS queries.
+ */
+class Client
+{
+    public const METHOD_GET = 'GET';
+    public const METHOD_POST = 'POST';
+
+    /**
+     * Create a new DNS over HTTPS client
+     *
+     * @param string $endpoint DoH endpoint URL (e.g., https://cloudflare-dns.com/dns-query)
+     * @param int $timeout Total request timeout in seconds
+     * @param int $connectTimeout Connection timeout in seconds
+     * @param string $method HTTP method to use (GET or POST)
+     */
+    public function __construct(
+        protected string $endpoint,
+        protected int $timeout = 5,
+        protected int $connectTimeout = 2,
+        protected string $method = self::METHOD_POST
+    ) {
+        if (!filter_var($endpoint, FILTER_VALIDATE_URL) || parse_url($endpoint, PHP_URL_SCHEME) !== 'https') {
+            throw new Exception('Invalid DoH endpoint URL. Must be a valid HTTPS URL.');
+        }
+
+        if (!in_array($method, [self::METHOD_GET, self::METHOD_POST])) {
+            throw new Exception('Invalid HTTP method. Use GET or POST.');
+        }
+    }
+
+    /**
+     * Send a DNS query over HTTPS
+     *
+     * @param Message $message The DNS query message
+     * @return Message The DNS response message
+     * @throws Exception On connection or protocol errors
+     */
+    public function query(Message $message): Message
+    {
+        if ($this->method === self::METHOD_GET) {
+            return $this->queryGet($message);
+        }
+
+        return $this->queryPost($message);
+    }
+
+    /**
+     * Send a DNS query using HTTP POST method
+     *
+     * RFC 8484 Section 4.1: POST request with application/dns-message body
+     *
+     * @param Message $message The DNS query message
+     * @return Message The DNS response message
+     */
+    protected function queryPost(Message $message): Message
+    {
+        $packet = $message->encode();
+
+        $ch = curl_init();
+
+        if ($ch === false) {
+            throw new Exception('Failed to initialize cURL handle.');
+        }
+
+        curl_setopt_array($ch, [
+            CURLOPT_URL => $this->endpoint,
+            CURLOPT_POST => true,
+            CURLOPT_POSTFIELDS => $packet,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_TIMEOUT => $this->timeout,
+            CURLOPT_CONNECTTIMEOUT => $this->connectTimeout,
+            CURLOPT_HTTPHEADER => [
+                'Content-Type: application/dns-message',
+                'Accept: application/dns-message',
+            ],
+            CURLOPT_FOLLOWLOCATION => true,
+            CURLOPT_MAXREDIRS => 3,
+            CURLOPT_REDIR_PROTOCOLS => CURLPROTO_HTTPS,
+        ]);
+
+        $response = curl_exec($ch);
+        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $error = curl_error($ch);
+        $errno = curl_errno($ch);
+
+        curl_close($ch);
+
+        if ($errno !== 0) {
+            throw new Exception("DoH request failed: $error (Error code: $errno)");
+        }
+
+        if ($httpCode !== 200) {
+            throw new Exception("DoH server returned HTTP $httpCode");
+        }
+
+        if (!is_string($response) || $response === '') {
+            throw new Exception('Empty response received from DoH server');
+        }
+
+        return $this->decodeResponse($message, $response);
+    }
+
+    /**
+     * Send a DNS query using HTTP GET method
+     *
+     * RFC 8484 Section 4.1: GET request with base64url-encoded dns parameter
+     *
+     * @param Message $message The DNS query message
+     * @return Message The DNS response message
+     */
+    protected function queryGet(Message $message): Message
+    {
+        $packet = $message->encode();
+        $encoded = $this->base64UrlEncode($packet);
+
+        $separator = str_contains($this->endpoint, '?') ? '&' : '?';
+        $url = $this->endpoint . $separator . 'dns=' . $encoded;
+
+        $ch = curl_init();
+
+        if ($ch === false) {
+            throw new Exception('Failed to initialize cURL handle.');
+        }
+
+        curl_setopt_array($ch, [
+            CURLOPT_URL => $url,
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_TIMEOUT => $this->timeout,
+            CURLOPT_CONNECTTIMEOUT => $this->connectTimeout,
+            CURLOPT_HTTPHEADER => [
+                'Accept: application/dns-message',
+            ],
+            CURLOPT_FOLLOWLOCATION => true,
+            CURLOPT_MAXREDIRS => 3,
+            CURLOPT_REDIR_PROTOCOLS => CURLPROTO_HTTPS,
+        ]);
+
+        $response = curl_exec($ch);
+        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
+        $error = curl_error($ch);
+        $errno = curl_errno($ch);
+
+        curl_close($ch);
+
+        if ($errno !== 0) {
+            throw new Exception("DoH request failed: $error (Error code: $errno)");
+        }
+
+        if ($httpCode !== 200) {
+            throw new Exception("DoH server returned HTTP $httpCode");
+        }
+
+        if (!is_string($response) || $response === '') {
+            throw new Exception('Empty response received from DoH server');
+        }
+
+        return $this->decodeResponse($message, $response);
+    }
+
+    /**
+     * Decode the DNS response and validate the transaction ID
+     *
+     * @param Message $query Original query message
+     * @param string $payload Raw response data
+     * @return Message Decoded response message
+     */
+    protected function decodeResponse(Message $query, string $payload): Message
+    {
+        $response = Message::decode($payload);
+
+        if ($response->header->id !== $query->header->id) {
+            throw new Exception(
+                "Mismatched DNS transaction ID. Expected {$query->header->id}, got {$response->header->id}"
+            );
+        }
+
+        return $response;
+    }
+
+    /**
+     * Encode data using base64url encoding (RFC 4648 Section 5)
+     *
+     * Required for the GET method as per RFC 8484 Section 4.1
+     *
+     * @param string $data Binary data to encode
+     * @return string Base64url-encoded string (no padding)
+     */
+    protected function base64UrlEncode(string $data): string
+    {
+        return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');
+    }
+
+    /**
+     * Get the DoH endpoint URL
+     *
+     * @return string The endpoint URL
+     */
+    public function getEndpoint(): string
+    {
+        return $this->endpoint;
+    }
+
+    /**
+     * Get the HTTP method being used
+     *
+     * @return string The HTTP method (GET or POST)
+     */
+    public function getMethod(): string
+    {
+        return $this->method;
+    }
+}

src/DNS/Resolver/Http.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Utopia\DNS\Resolver;
+
+use Utopia\DNS\Http\Client;
+use Utopia\DNS\Message;
+use Utopia\DNS\Resolver;
+
+/**
+ * DNS over HTTPS Resolver
+ *
+ * A resolver that forwards DNS queries to a DoH server over HTTPS.
+ * Implements RFC 8484 for DNS queries over HTTP/HTTPS.
+ */
+class Http implements Resolver
+{
+    protected Client $client;
+    protected string $endpoint;
+
+    /**
+     * Create a new HTTP (DoH) resolver
+     *
+     * @param string $endpoint DoH endpoint URL (e.g., https://cloudflare-dns.com/dns-query)
+     * @param int $timeout Total request timeout in seconds
+     * @param int $connectTimeout Connection timeout in seconds
+     * @param string $method HTTP method to use (GET or POST)
+     */
+    public function __construct(
+        string $endpoint,
+        int $timeout = 5,
+        int $connectTimeout = 2,
+        string $method = Client::METHOD_POST
+    ) {
+        $this->endpoint = $endpoint;
+        $this->client = new Client($endpoint, $timeout, $connectTimeout, $method);
+    }
+
+    /**
+     * Resolve DNS query by forwarding to the DoH server
+     *
+     * @param Message $query The DNS query message
+     * @return Message The DNS response message
+     */
+    public function resolve(Message $query): Message
+    {
+        return $this->client->query($query);
+    }
+
+    /**
+     * Get the name of the resolver
+     *
+     * @return string The resolver name
+     */
+    public function getName(): string
+    {
+        return "HTTP ($this->endpoint)";
+    }
+
+    /**
+     * Get the underlying HTTP client
+     *
+     * @return Client The client instance
+     */
+    public function getClient(): Client
+    {
+        return $this->client;
+    }
+}

src/DNS/Resolver/Http/Cloudflare.php

@@ -0,0 +1,49 @@
+<?php
+
+namespace Utopia\DNS\Resolver\Http;
+
+use Utopia\DNS\Http\Client;
+use Utopia\DNS\Resolver\Http;
+
+/**
+ * Cloudflare DNS over HTTPS Resolver
+ *
+ * Uses Cloudflare's public DoH endpoints:
+ * - Primary: https://cloudflare-dns.com/dns-query
+ * - Backup: https://one.one.one.one/dns-query
+ *
+ * @see https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/
+ */
+class Cloudflare extends Http
+{
+    public const ENDPOINT_PRIMARY = 'https://cloudflare-dns.com/dns-query';
+    public const ENDPOINT_BACKUP = 'https://one.one.one.one/dns-query';
+
+    /**
+     * Create a new Cloudflare HTTP (DoH) resolver
+     *
+     * @param bool $useBackup Use backup endpoint instead of primary
+     * @param int $timeout Total request timeout in seconds
+     * @param int $connectTimeout Connection timeout in seconds
+     * @param string $method HTTP method to use (GET or POST)
+     */
+    public function __construct(
+        bool $useBackup = false,
+        int $timeout = 5,
+        int $connectTimeout = 2,
+        string $method = Client::METHOD_POST
+    ) {
+        $endpoint = $useBackup ? self::ENDPOINT_BACKUP : self::ENDPOINT_PRIMARY;
+        parent::__construct($endpoint, $timeout, $connectTimeout, $method);
+    }
+
+    /**
+     * Get the name of the resolver
+     *
+     * @return string The resolver name
+     */
+    public function getName(): string
+    {
+        return "Cloudflare HTTP ($this->endpoint)";
+    }
+}