tangerine 1.4.8 → 1.5.0

package/README.md

@@ -56,6 +56,7 @@
   * [`tangerine.reverse(ip[, abortController, purgeCache])`](#tangerinereverseip-abortcontroller-purgecache)
   * [`tangerine.setDefaultResultOrder(order)`](#tangerinesetdefaultresultorderorder)
   * [`tangerine.setServers(servers)`](#tangerinesetserversservers)
+  * [`tangerine.spoofPacket(hostname, rrtype, answers)`](#tangerinespoofpackethostname-rrtype-answers)
 * [Options](#options)
 * [Cache](#cache)
 * [Compatibility](#compatibility)
@@ -331,6 +332,48 @@ This mirrors output from <https://github.com/rthalley/dnspython>.
 
 ### `tangerine.setServers(servers)`
 
+### `tangerine.spoofPacket(hostname, rrtype, answers)`
+
+This method is useful for writing tests to spoof DNS packets in-memory.
+
+The `rrtype` must be either `"TXT"` or `"MX"`, and `answers` must be an Array of DNS resource record answers.
+
+For example, if you want to spoof TXT and MX records:
+
+```js
+const Redis = require('ioredis-mock');
+const Tangerine = require('tangerine');
+const ip = require('ip');
+
+const cache = new Redis();
+const tangerine = new Tangerine({ cache });
+
+const obj = {};
+
+obj['txt:forwardmail.net'] = tangerine.spoofPacket('forwardmail.net', 'TXT', [
+  `v=spf1 ip4:${ip.address()} -all`
+]);
+
+obj['mx:forwardemail.net'] = tangerine.spoofPacket('forwardemail.net', 'MX', [
+  { exchange: 'mx1.forwardemail.net', preference: 0 },
+  { exchange: 'mx2.forwardemail.net', preference: 0 }
+]);
+
+await cache.mset(obj);
+
+//
+// NOTE: spoofed values are used below (this means no DNS query performed)
+//
+
+const txt = await tangerine.resolveTxt('forwardemail.net');
+console.log('txt', txt);
+
+const mx = await tangerine.resolveMx('forwardemail.net');
+console.log('mx', mx);
+```
+
+**Pull requests are welcome to add support for other `rrtype` values for this method.**
+
 
 ## Options
 

package/index.js

@@ -1428,6 +1428,74 @@ class Tangerine extends dns.promises.Resolver {
     this.options.servers = new Set(servers);
   }
 
+  spoofPacket(name, rrtype, answers = []) {
+    if (typeof name !== 'string') {
+      const err = new TypeError('The "name" argument must be of type string.');
+      err.code = 'ERR_INVALID_ARG_TYPE';
+      throw err;
+    }
+
+    if (typeof rrtype !== 'string') {
+      const err = new TypeError(
+        'The "rrtype" argument must be of type string.'
+      );
+      err.code = 'ERR_INVALID_ARG_TYPE';
+      throw err;
+    }
+
+    if (!this.constructor.TYPES.has(rrtype)) {
+      const err = new TypeError("The argument 'rrtype' is invalid.");
+      err.code = 'ERR_INVALID_ARG_VALUE';
+      throw err;
+    }
+
+    if (!Array.isArray(answers)) {
+      const err = new TypeError("The argument 'answers' is invalid.");
+      err.code = 'ERR_INVALID_ARG_VALUE';
+      throw err;
+    }
+
+    return {
+      id: 0,
+      type: 'response',
+      flags: 384,
+      flag_qr: true,
+      opcode: 'QUERY',
+      flag_aa: false,
+      flag_tc: false,
+      flag_rd: true,
+      flag_ra: true,
+      flag_z: false,
+      flag_ad: false,
+      flag_cd: false,
+      rcode: 'NOERROR',
+      questions: [{ name, type: rrtype, class: 'IN' }],
+      answers: answers.map((answer) => ({
+        name,
+        type: rrtype,
+        ttl: 300,
+        class: 'IN',
+        flush: false,
+        data: rrtype === 'TXT' ? [answer] : answer
+      })),
+      authorities: [],
+      additionals: [
+        {
+          name: '.',
+          type: 'OPT',
+          udpPayloadSize: 1232,
+          extendedRcode: 0,
+          ednsVersion: 0,
+          flags: 0,
+          flag_do: false,
+          options: [Array]
+        }
+      ],
+      ttl: 300,
+      expires: Date.now() + 10000
+    };
+  }
+
   // eslint-disable-next-line complexity
   async resolve(name, rrtype = 'A', options = {}, abortController) {
     if (typeof name !== 'string') {
@@ -1481,6 +1549,17 @@ class Tangerine extends dns.promises.Resolver {
       //       (this saves us from duplicating the same `...sort().filter(Number.isFinite)` logic)
       //
       data = await this.options.cache.get(key);
+      //
+      // if it's not an object then assume that
+      // the cache implementation does not have JSON.parse built-in
+      // and so we should try to parse it on our own (user-friendly)
+      //
+      if (typeof data === 'string') {
+        try {
+          data = JSON.parse(data);
+        } catch {}
+      }
+
       // safeguard in case cache pollution
       if (data && typeof data === 'object') {
         debug('cache retrieved', key);
@@ -1847,19 +1926,30 @@ class Tangerine extends dns.promises.Resolver {
         // if it returns answers with `type: TLSA` then recursively lookup
         // 3 1 1 D6FEA64D4E68CAEAB7CBB2E0F905D7F3CA3308B12FD88C5B469F08AD 7E05C7C7
         return result.answers.map((answer) => {
-          if (!Buffer.isBuffer(answer.data))
-            throw new Error('Buffer was not available');
-
-          // <https://www.mailhardener.com/kb/dane>
-          return {
+          const obj = {
             name: answer.name,
-            ttl: answer.ttl,
-            // <https://github.com/rthalley/dnspython/blob/98b12e9e43847dac615bb690355d2fabaff969d2/dns/rdtypes/tlsabase.py#L35>
-            usage: answer.data.subarray(0, 1).readUInt8(),
-            selector: answer.data.subarray(1, 2).readUInt8(),
-            mtype: answer.data.subarray(2, 3).readUInt8(),
-            cert: answer.data.subarray(3)
+            ttl: answer.ttl
           };
+
+          // <https://www.mailhardener.com/kb/dane>
+          // <https://github.com/rthalley/dnspython/blob/98b12e9e43847dac615bb690355d2fabaff969d2/dns/rdtypes/tlsabase.py#L35>
+          if (Buffer.isBuffer(answer.data)) {
+            obj.usage = answer.data.subarray(0, 1).readUInt8();
+            obj.selector = answer.data.subarray(1, 2).readUInt8();
+            obj.mtype = answer.data.subarray(2, 3).readUInt8();
+            obj.cert = answer.data.subarray(3);
+          } else {
+            obj.usage = answer.data.usage;
+            obj.selector = answer.data.selector;
+            obj.mtype = answer.data.matchingType;
+            obj.cert = answer.data.certificate;
+          }
+
+          // aliases to match Cloudflare DNS response
+          obj.matchingType = obj.mtype;
+          obj.certificate = obj.cert;
+
+          return obj;
         });
       }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tangerine",
   "description": "Tangerine is the best Node.js drop-in replacement for dns.promises.Resolver using DNS over HTTPS (\"DoH\") via undici with built-in retries, timeouts, smart server rotation, AbortControllers, and caching support for multiple backends (with TTL and purge support).",
-  "version": "1.4.8",
+  "version": "1.5.0",
   "author": "Forward Email (https://forwardemail.net)",
   "bugs": {
     "url": "https://github.com/forwardemail/tangerine/issues"