feat: added note regarding compatibility with wildcard local dns matching

Author: titanism

README.md

@@ -58,6 +58,7 @@
   * [`tangerine.setServers(servers)`](#tangerinesetserversservers)
 * [Options](#options)
 * [Cache](#cache)
+* [Compatibility](#compatibility)
 * [Debugging](#debugging)
 * [Benchmarks](#benchmarks)
   * [Tangerine Benchmarks](#tangerine-benchmarks)
@@ -430,6 +431,15 @@ await tangerine.resolve('forwardemail.net'); // uses cached value
 This purge cache feature is useful for DNS records that have recently changed and have had their caches purged at the relevant DNS provider (e.g. [Cloudflare's Purge Cache tool](https://1.1.1.1/purge-cache/)).
 
 
+## Compatibility
+
+The only known compatibility issue is for locally running DNS servers that have wildcard DNS matching.
+
+If you are using `dnsmasq` with a wildcard match on "localhost" to "127.0.0.1", then the results may vary.  For example, if your `dnsmasq` configuration has `address=/localhost/127.0.0.1`, then any match of `localhost` will resolve to `127.0.0.1`.  This means that `dns.promises.lookup('foo.localhost')` will return `127.0.0.1` – however with :tangerine: Tangerine it will not return a value.
+
+The reason is because :tangerine: Tangerine only looks at either `/etc/hosts` (macOS/Linux) and `C:/Windows/System32/drivers/etc/hosts` (Windows).  It does not lookup BIND, dnsmasq, or other configurations running locally.  We would welcome a PR to resolve this (see `isCI` usage in test folder) – however it is a non-issue, as the workaround is to simply append a new line to the hostfile of `127.0.0.1 foo.localhost`.
+
+
 ## Debugging
 
 If you run into issues while using :tangerine: Tangerine, then these recommendations may help:

package.json

@@ -41,6 +41,7 @@
     "husky": "^8.0.3",
     "ioredis": "^5.3.1",
     "ioredis-mock": "^8.2.6",
+    "is-ci": "^3.0.1",
     "lint-staged": "^13.1.2",
     "lodash": "^4.17.21",
     "nock": "^13.3.0",

test/test.js

@@ -3,6 +3,7 @@ const fs = require('node:fs');
 const { Buffer } = require('node:buffer');
 const { isIP, isIPv4, isIPv6 } = require('node:net');
 
+const isCI = require('is-ci');
 const Redis = require('ioredis-mock');
 const _ = require('lodash');
 const got = require('got');
@@ -348,32 +349,39 @@ for (const host of [
   });
 
   // tangerine.lookup"${host}"[, options])
-  test(`lookup("${host}")`, async (t) => {
-    // returns { address: IP , family: 4 || 6 }
-    const tangerine = new Tangerine();
-    let r1;
-    let r2;
-    try {
-      r1 = await tangerine.lookup(host);
-    } catch (err) {
-      r1 = err;
-    }
+  //
+  // TODO: if the local DNS resolver on the server that c-ares communicates with
+  // is using a wildcard or regex based approach for matching hostnames
+  // then it won't match in these tests because we only check for /etc/hosts
+  // (see #compatibility section of README for more insight)
+  //
+  if (!isCI || !['.', 'foo.localhost', 'foo.bar.localhost'].includes(host))
+    test(`lookup("${host}")`, async (t) => {
+      // returns { address: IP , family: 4 || 6 }
+      const tangerine = new Tangerine();
+      let r1;
+      let r2;
+      try {
+        r1 = await tangerine.lookup(host);
+      } catch (err) {
+        r1 = err;
+      }
 
-    try {
-      r2 = await dns.promises.lookup(host);
-    } catch (err) {
-      r2 = err;
-    }
+      try {
+        r2 = await dns.promises.lookup(host);
+      } catch (err) {
+        r2 = err;
+      }
 
-    t.log(r1);
-    t.log(r2);
+      t.log(r1);
+      t.log(r2);
 
-    if (_.isPlainObject(r1)) r1 = [r1];
-    if (_.isPlainObject(r2)) r2 = [r2];
-    if (!_.isError(r1)) r1 = r1.every((o) => isIP(o.address) === o.family);
-    if (!_.isError(r2)) r2 = r2.every((o) => isIP(o.address) === o.family);
-    t.deepEqual(r1, r2);
-  });
+      if (_.isPlainObject(r1)) r1 = [r1];
+      if (_.isPlainObject(r2)) r2 = [r2];
+      if (!_.isError(r1)) r1 = r1.every((o) => isIP(o.address) === o.family);
+      if (!_.isError(r2)) r2 = r2.every((o) => isIP(o.address) === o.family);
+      t.deepEqual(r1, r2);
+    });
 
   // tangerine.resolve"${host}"[, rrtype])
   test(`resolve("${host}")`, async (t) => {
@@ -482,11 +490,7 @@ for (const host of [
   });
 
   // tangerine.resolveAny"${host}"[, abortController])
-  // TODO: figure out why we have to skip this (?)
-  //       basically it works locally, but on GitHub CI there is different results
-  //       r1 has results (e.g. ns servers)
-  //       r2 is err with ENODATA
-  if (host !== '.')
+  if (!isCI)
     test(`resolveAny("${host}")`, async (t) => {
       const tangerine = new Tangerine();
       const resolver = new Resolver();