Code refactoring and general library maintenance

Author: akacdev

.github/workflows/build-and-release.yml

@@ -4,12 +4,29 @@ namespace DnsOverHttps
 {
     internal class Constants
     {
+        /// <summary>
+        /// The hostname of the Dns-over-HTTPS resolver.
+        /// </summary>
         public const string Hostname = "1.1.1.1";
+        /// <summary>
+        /// The base URI to send requests to. 
+        /// </summary>
         public static readonly Uri BaseUri = new($"https://{Hostname}/dns-query");
+        /// <summary>
+        /// The preferred HTTP request version to use.
+        /// </summary>
         public static readonly Version HttpVersion = new(2, 0);
-
+        /// <summary>
+        /// The <c>User-Agent</c> header value to send along requests.
+        /// </summary>
         public const string UserAgent = "C# DnsOverHttps Client - actually-akac/DnsOverHttps";
+        /// <summary>
+        /// The <c>Accept</c> header value to send along requests.
+        /// </summary>
         public const string ContentType = "application/dns-json";
-        public const int MaxPreviewLength = 500;
+        /// <summary>
+        /// The maximum string length when displaying a preview of a response body.
+        /// </summary>
+        public const int PreviewMaxLength = 500;
     }
 }

DnsOverHttps/Constants.cs

@@ -46,23 +46,23 @@ public async Task<Response> Resolve(string name, ResourceRecordType type = Resou
         {
             if (string.IsNullOrEmpty(name)) throw new ArgumentNullException(nameof(name), "Name is null or empty.");
 
-            string url =
-                $"?name={name.UrlEncode()}" +
-                (type == ResourceRecordType.A ? "" : $"&type={type.ToString().UrlEncode()}") +
-                (requestDnsSec == false ? "" : $"&do=1") +
-                (validateDnsSec == false ? "" : $"&cd=1");
+            string url = string.Concat(
+                $"?name={name.UrlEncode()}",
+                type == ResourceRecordType.A ? "" : $"&type={type.ToString().UrlEncode()}",
+                requestDnsSec == false ? "" : $"&do=1",
+                validateDnsSec == false ? "" : $"&cd=1");
 
-            HttpRequestMessage req = new(HttpMethod.Get, url);
-            HttpResponseMessage res = await Client.SendAsync(req);
+            using HttpRequestMessage req = new(HttpMethod.Get, url);
+            using HttpResponseMessage res = await Client.SendAsync(req);
 
             Response response = await res.Deseralize<Response>();
-
+            
             if (res.StatusCode != HttpStatusCode.OK || !string.IsNullOrEmpty(response.Error) || response.Comments is not null)
             {
-                string message =
-                    $"Failed to query type {type} of '{name}', received HTTP status code {res.StatusCode}." +
-                    (string.IsNullOrEmpty(response.Error) ? "" : $"\nError: {response.Error}") +
-                    (response.Comments is null ? "" : $"\nComments: {string.Join(", ", response.Comments)}");
+                string message = string.Concat(
+                    $"Failed to query type {type} of \"{name}\", received HTTP status code {res.StatusCode}.",
+                    string.IsNullOrEmpty(response.Error) ? "" : $"\nError: {response.Error}",
+                    response.Comments is null ? "" : $"\nComments: {string.Join(", ", response.Comments)}");
 
                 throw new DnsOverHttpsException(message, response);
             }
@@ -112,9 +112,10 @@ public async Task<Response[]> Resolve(string name, ResourceRecordType[] types, b
         /// <returns></returns>
         /// <exception cref="DnsOverHttpsException"></exception>
         /// <exception cref="ArgumentNullException"></exception>
-        public async Task<Answer> ResolveFirst(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
+        public async Task<Answer?> ResolveFirst(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
         {
             Response res = await Resolve(name, type, requestDnsSec, validateDnsSec);
+
             return res.Answers?.FirstOrDefault(x => x.Type == type);
         }
 
@@ -134,6 +135,7 @@ public async Task<Answer> ResolveFirst(string name, ResourceRecordType type = Re
         public async Task<Answer[]> ResolveAll(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
         {
             Response res = await Resolve(name, type, requestDnsSec, validateDnsSec);
+
             return res.Answers.Where(x => x.Type == ResourceRecordType.A).ToArray();
         }
     }

DnsOverHttps/DnsOverHttps.cs

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <!--Basic Information-->
-    <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
+    <TargetFrameworks>net6.0;net7.0;net8.0</TargetFrameworks>
     <PackageId>DnsOverHttps</PackageId>
     <Product>DnsOverHttps</Product>
     <Authors>akac</Authors>
@@ -53,4 +53,4 @@
     </None>
   </ItemGroup>
 
-</Project>
+</Project>

DnsOverHttps/DnsOverHttps.csproj

@@ -206,7 +206,7 @@ public enum ResourceRecordType : byte
     /// <summary>
     /// The result of a DNS over HTTPS query.
     /// </summary>
-    public class Response
+    public struct Response
     {
         /// <summary>
         /// A DNS response code.
@@ -289,7 +289,7 @@ public class Response
     /// <summary>   
     /// A DNS question sent by the client.
     /// </summary>
-    public class Question
+    public struct Question
     {
         /// <summary>
         /// The FQDN record name requested.
@@ -307,7 +307,7 @@ public class Question
     /// <summary>
     /// A DNS answer sent by the server.
     /// </summary>
-    public class Answer
+    public struct Answer
     {
         /// <summary>
         /// The record owner.

DnsOverHttps/Entities.cs

@@ -7,9 +7,12 @@ namespace DnsOverHttps
     /// </summary>
     public class DnsOverHttpsException : Exception
     {
+        /// <summary>
+        /// The DNS response that caused this exception.
+        /// </summary>
         public Response Response { get; set; }
 
         public DnsOverHttpsException(string message) : base(message) { }
-        public DnsOverHttpsException(string message, Response response) : base(message) { Response = response; }
+        public DnsOverHttpsException(string message, Response res) : base(message) { Response = res; }
     }
-}
+}

DnsOverHttps/Exceptions.cs

@@ -11,27 +11,68 @@ public static class Extensions
     {
         public static string UrlEncode(this string value) => WebUtility.UrlEncode(value);
 
-        public static async Task<string> GetPreview(this HttpResponseMessage res)
+        /// <summary>
+        /// Deserialize a JSON HTTP response into a given type.
+        /// </summary>
+        /// <typeparam name="T">The type to deserialize into.</typeparam>
+        /// <param name="res">The HTTP response message with JSON as a body.</param>
+        public static async Task<T> Deseralize<T>(this HttpResponseMessage res)
         {
-            string text = await res.Content.ReadAsStringAsync();
-            return text[..Math.Min(text.Length, Constants.MaxPreviewLength)];
-        }
-
-        public static async Task<T> Deseralize<T>(this HttpResponseMessage res, JsonSerializerOptions options = null)
-        {
-            Stream stream = await res.Content.ReadAsStreamAsync();
+            using Stream stream = await res.Content.ReadAsStreamAsync();
             if (stream.Length == 0) throw new DnsOverHttpsException("Response content is empty, can't parse as JSON.");
 
             try
             {
-                return await JsonSerializer.DeserializeAsync<T>(stream, options);
+                return await JsonSerializer.DeserializeAsync<T>(stream);
             }
             catch (Exception ex)
             {
-                throw new DnsOverHttpsException(
-                    $"Exception while parsing JSON: {ex.GetType().Name} => {ex.Message}\n" +
-                    $"Preview: {await res.GetPreview()}");
+                throw new DnsOverHttpsException($"Exception while parsing JSON: {ex.GetType().Name} => {ex.Message}\nPreview: {await stream.GetPreview()}");
             }
         }
+
+        /// <summary>
+        /// Serialize an object into a JSON HTTP Stream Content.
+        /// </summary>
+        /// <param name="obj">The object to serialize as JSON.</param>
+        public static async Task<StreamContent> Serialize(this object obj)
+        {
+            MemoryStream ms = new();
+            await JsonSerializer.SerializeAsync(ms, obj);
+            ms.Position = 0;
+
+            StreamContent sc = new(ms);
+            sc.Headers.ContentType = new("application/json");
+
+            return sc;
+        }
+
+        /// <summary>
+        /// Extract a short preview string from a HTTP response body.
+        /// </summary>
+        /// <param name="res">The HTTP response message with a body.</param>
+        public static async Task<string> GetPreview(this HttpResponseMessage res)
+        {
+            using Stream stream = await res.Content.ReadAsStreamAsync();
+            if (stream.Length == 0) throw new DnsOverHttpsException("Response content is empty, can't extract body.");
+
+            return await GetPreview(stream);
+        }
+
+        /// <summary>
+        /// Extract a short preview string from a HTTP response body.
+        /// </summary>
+        /// <param name="stream">The HTTP response stream.</param>
+        public static async Task<string> GetPreview(this Stream stream)
+        {
+            stream.Position = 0;
+            using StreamReader sr = new(stream);
+
+            char[] buffer = new char[Math.Min(stream.Length, Constants.PreviewMaxLength)];
+            int bytesRead = await sr.ReadAsync(buffer, 0, buffer.Length);
+            string text = new(buffer, 0, bytesRead);
+
+            return text;
+        }
     }
 }

DnsOverHttps/Extensions.cs

@@ -5,9 +5,11 @@
 ### An async and lightweight C# library for Cloudflare's DNS over HTTPS.
 
 ## Usage
-Provides an easy interface for interacting with Cloudflare's DNS over HTTPS endpoints. Learn more about it [here](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/).
+This library provides an easy interface for interacting with Cloudflare's DNS over HTTPS endpoints.
 
-To get started, add the library into your solution with either the `NuGet Package Manager` or the `dotnet` CLI.
+DoH is a protocol that enhances the privacy and security of DNS queries by encrypting them using HTTPS. This helps prevent unauthorized access or tampering of DNS data during transmission. Learn more about it [here](https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https/).
+
+To get started, import the library into your solution with either the `NuGet Package Manager` or the `dotnet` CLI.
 ```rust
 dotnet add package DnsOverHttps
 ```
@@ -19,15 +21,19 @@ using DnsOverHttps;
 
 Need more examples? Under the `Example` directory you can find a working demo project that implements this library.
 
-## Features
-- Built for **.NET 6** and **.NET 7**
+## Properties
+- Built for **.NET 8**, **.NET 7** and **.NET 6**
 - Fully **async**
-- Deep coverage of the API
 - Extensive **XML documentation**
-- **No external dependencies** (uses integrated HTTP and JSON)
-- **Custom exceptions** (`DnsOverHttpsException`) for advanced catching
+- **No external dependencies** (makes use of built-in `HttpClient` and `JsonSerializer`)
+- **Custom exceptions** (`DnsOverHttpsException`) for easy debugging
 - Example project to demonstrate all capabilities of the library
-- Execute DNS queries over HTTPS of any type
+
+## Features
+- Resolve one or all DNS records under a hostname
+- Ask for DNSSEC validation
+- Query in parallel
+- Specify advanced parameters
 
 ## Code Samples
 
@@ -38,26 +44,20 @@ DnsOverHttpsClient dns = new();
 
 ### Resolving A DNS records including DNSSEC
 ```csharp
-Response response = await dns.Resolve("discord.com", "A", true, true);
+Response response = await Client.Resolve("discord.com", ResourceRecordType.A, true, true);
 ```
 
 ### Using helper methods to return the first or all answers
 ```csharp
-Answer nsAnswer = await dns.GetFirst("example.com", "NS");
-Answer[] aAnswers = await dns.GetAll("reddit.com", "A");
+Answer? nsAnswer = await Client.ResolveFirst("example.com", ResourceRecordType.NS);
+Answer[] aAnswers = await Client.ResolveAll("reddit.com", ResourceRecordType.A);
 ```
 
-## Available Methods
-- Task\<Response> **Resolve**(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
-- Task\<Response[]> **Resolve**(string name, ResourceRecordType[] types, bool requestDnsSec = false, bool validateDnsSec = false)
-- Task\<Answer[]> **ResolveAll**(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
-- Task\<Answer> **ResolveFirst**(string name, ResourceRecordType type = ResourceRecordType.A, bool requestDnsSec = false, bool validateDnsSec = false)
-
 ## Resources
 - Cloudflare: https://cloudflare.com
 - 1.1.1.1: https://1.1.1.1
 - Introduction: https://developers.cloudflare.com/1.1.1.1/encryption/dns-over-https
 
-*This is a community-ran library. Not affiliated with Cloudflare.*
+*This is a community-ran library. Not affiliated with Cloudflare, Inc.*
 
 *Icon made by **Freepik** at [Flaticon](https://www.flaticon.com).*

DnsOverHttps/NuGet.md

@@ -2,11 +2,11 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFrameworks>net6.0;net7.0</TargetFrameworks>
+    <TargetFrameworks>net8.0</TargetFrameworks>
   </PropertyGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\DnsOverHttps\DnsOverHttps.csproj" />
   </ItemGroup>
 
-</Project>
+</Project>

Example/Example.csproj

@@ -6,55 +6,52 @@ namespace Example
 {
     public static class Program
     {
+        private static readonly DnsOverHttpsClient Client = new();
+
         public static async Task Main()
         {
-            DnsOverHttpsClient client = new();
-
-
             Console.WriteLine($"> Resolving the first NS record on example.com");
-            Answer nsAnswer = await client.ResolveFirst("example.com", ResourceRecordType.A);
+            Answer? nsAnswer = await Client.ResolveFirst("example.com", ResourceRecordType.NS);
 
             Console.WriteLine($"Result:");
             PrintAnswer(nsAnswer);
 
 
             Console.WriteLine($"\n> Resolving all A records on reddit.com");
-            Answer[] aAnswers = await client.ResolveAll("reddit.com", ResourceRecordType.A);
+            Answer[] aAnswers = await Client.ResolveAll("reddit.com", ResourceRecordType.A);
 
             Console.WriteLine($"Result:");
             foreach (Answer answer in aAnswers) PrintAnswer(answer);
             Console.WriteLine();
 
 
             Console.WriteLine($"\n> Resolving an invalid domain");
-            Answer nxDomain = await client.ResolveFirst("5525fe855b7366f93447cd039ab885.com", ResourceRecordType.A);
-            Console.WriteLine($"Result is {(nxDomain is null ? "null" : $"not null: {nxDomain.Data}")}");
+            Answer? nxDomain = await Client.ResolveFirst("5525fe855b7366f93447cd039ab885.com", ResourceRecordType.A);
+            Console.WriteLine($"Result is {(nxDomain is null ? "null" : $"not null: {nxDomain.Value.Data}")}");
             Console.WriteLine();
 
 
             Console.WriteLine($"\n> Resolving A records on discord.com with DNSSEC");
-            Response response = await client.Resolve("discord.com", ResourceRecordType.A, true, true);
+            Response response = await Client.Resolve("discord.com", ResourceRecordType.A, true, true);
 
             Console.WriteLine($"Result:");
             foreach (Answer answer in response.Answers) PrintAnswer(answer);
 
 
             Console.WriteLine($"\n> Resolving multiple records in parallel on github.com");
-            Response[] responses = await client.Resolve("discord.com", new ResourceRecordType[] { ResourceRecordType.A, ResourceRecordType.MX, ResourceRecordType.NS });
+            Response[] responses = await Client.Resolve("github.com", [ResourceRecordType.A, ResourceRecordType.MX, ResourceRecordType.NS]);
 
             foreach (Response resp in responses)
-            {
                 foreach (Answer answer in resp.Answers) PrintAnswer(answer);
-            }
 
 
             Console.WriteLine("\nDemo finished");
             Console.ReadKey();
         }
 
-        public static void PrintAnswer(Answer answer)
+        public static void PrintAnswer(Answer? answer)
         {
-            Console.WriteLine($"\tType: {answer.Type}; TTL: {answer.TTL}; Translation: {answer.Name} => {answer.Data}");
+            Console.WriteLine($"\tType: {answer.Value.Type}; TTL: {answer.Value.TTL}; Translation: {answer.Value.Name} => {answer.Value.Data}");
         }
     }
 }