Documentation Update

jdomnitz · jdomnitz · commit c9844c000d5b · 2024-09-13T01:47:19.000-04:00
diff --git a/README.md b/README.md
@@ -11,4 +11,6 @@ A small, fast, modern DNS / MDNS / DNS-SD client
 * Resolution using common public recursive resolvers (Google, CloudFlare, etc.)
 * Support for DoH (DNS over HTTPS) with options for secure or insecure lookup
 * Leak protection to ensure sensitive queries are not shared with public DNS servers
-* Support for async, zerocopy, spans and all the modern .Net performance features
+* A DNS-SD and MDNS client with known answer suppression, passive caching and other mandatory and optional flood control features from the spec.
+* Support for async, zerocopy, spans and all the modern .Net performance features
+* See the TinyDNSDemo project for examples
diff --git a/TinyDNS/TinyDNS.csproj b/TinyDNS/TinyDNS.csproj
@@ -4,12 +4,16 @@
     <TargetFrameworks>net80</TargetFrameworks>
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
-    <Version>0.9.0</Version>
+    <Version>0.9.1</Version>
     <PackageLicenseExpression>AGPL-3.0-or-later</PackageLicenseExpression>
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <Authors>jdomnitz</Authors>
     <Company>SmartHomeOS and Contributors</Company>
     <PackageTags>dns; dns-client; doh; mdns; secure-dns</PackageTags>
+    <Title>Tiny DNS Client</Title>
+    <Description>A small, fast, modern DNS / MDNS / DNS-SD client</Description>
+    <Copyright>Copyright 2024 - Smart Home OS Contributors</Copyright>
+    <RepositoryUrl>https://github.com/SmartHomeOS/TinyDNS/</RepositoryUrl>
   </PropertyGroup>
 
   <PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net80|AnyCPU'">
diff --git a/TinyDNSDemo/DNS-SD.cs b/TinyDNSDemo/DNS-SD.cs
@@ -37,12 +37,17 @@ public async Task Run()
             mdns.AnswerReceived += Mdns_AnswerReceived;
             await mdns.Start();
 
+            //Query all services (unicast first since we are new to the network)
             var records = await mdns.QueryService(ALL_SERVICES, DEFAULT_DOMAIN, true);
             await ProcessRecords(records);
 
             await Task.Delay(10000);
-            records = await mdns.QueryService(ALL_SERVICES, DEFAULT_DOMAIN, true);
+
+            //Check for any services we didn't hear about in the last query (known answer suppression is automatic)
+            records = await mdns.QueryService(ALL_SERVICES, DEFAULT_DOMAIN, false);
             await ProcessRecords(records);
+
+            //In long running implementations, scanning should occur every 15-60 mins
         }
 
         private async Task Mdns_AnswerReceived(DNSMessageEvent e)
@@ -59,9 +64,10 @@ private async Task ProcessRecords(ResourceRecord[] records)
                     string? serviceName;
                     PtrRecord item = (PtrRecord)record;
                     if (!item.Domain.EndsWith(".local"))
-                        return; //NOT DNS-SD
+                        return; //NOT DNS-SD this is regular MDNS
                     if (item.Name.StartsWith(ALL_SERVICES))
                     {
+                        //These records tell us a service exists on the network for 1 or more hosts
                         serviceName = MDNS.GetServiceName(item.DomainLabels);
                         var cachedAnswers = await mdns.QueryService(serviceName!, DEFAULT_DOMAIN);
                         if (serviceName != null)
@@ -73,12 +79,14 @@ private async Task ProcessRecords(ResourceRecord[] records)
                         serviceName = MDNS.GetServiceName(item.DomainLabels);
                         if (serviceName == ALL_SERVICES)
                             continue;
+                        //These records are instance pointers - they tell us about hosts which have a specific service
                         string? serviceInstance = MDNS.GetInstanceName(item.DomainLabels);
                         
                         if (serviceName != null)
                         {
                             if (UpdateService(serviceName, serviceInstance))
                             {
+                                // Request details on this instance of the service
                                 var lst = await mdns.ResolveServiceInstance(serviceInstance!, serviceName!, DEFAULT_DOMAIN);
                                 foreach (var msg in lst)
                                     await ProcessRecords(msg.Answers);
@@ -88,6 +96,7 @@ private async Task ProcessRecords(ResourceRecord[] records)
                 }
                 else if (record.Type == DNSRecordType.SRV)
                 {
+                    // A detailed record of a host that is running a service on a particular port (with optional text info)
                     string? serviceName = MDNS.GetServiceName(((SRVRecord)record).Labels);
                     string? serviceInstance = MDNS.GetInstanceName(((SRVRecord)record).Labels);
                     List<ResourceRecord> rcds = new List<ResourceRecord>();
@@ -101,6 +110,7 @@ private async Task ProcessRecords(ResourceRecord[] records)
                 {
                     if (records.Any(r => r.Type == DNSRecordType.SRV && record.Name.Equals(r.Name)))
                         continue;
+                    //There are a few services that publish text without a SRV record - catch them here.  Most implementations won't need this.
                     string? serviceName = MDNS.GetServiceName(((TxtRecord)record).Labels);
                     string? serviceInstance = MDNS.GetInstanceName(((TxtRecord)record).Labels);
                     if (serviceInstance != null && serviceName != null)
