tangerine 1.4.9 → 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);

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.9",
+  "version": "1.5.0",
   "author": "Forward Email (https://forwardemail.net)",
   "bugs": {
     "url": "https://github.com/forwardemail/tangerine/issues"