dns2 2.1.0 → 2.3.0

package/README.md

@@ -1,7 +1,6 @@
 # dns2 
 
-![NPM version](https://img.shields.io/npm/v/dns2.svg?style=flat)
-[![Node.js CI](https://github.com/song940/node-dns/actions/workflows/node.js.yml/badge.svg)](https://github.com/song940/node-dns/actions/workflows/node.js.yml)
+![NPM version][npm-img] [![Build Status][ci-img]][ci-url]
 
 > A DNS Server and Client Implementation in Pure JavaScript with no dependencies.
 
@@ -27,10 +26,9 @@ DNS client will use UDP by default.
 const dns2 = require('dns2');
 
 const options = {
-  // available options
-  // dns: dns server ip address or hostname (string),
-  // port: dns server port (number),
-  // recursive: Recursion Desired flag (boolean, default true, since > v1.4.2)
+  // nameServers: ['8.8.8.8']  — array of DNS server IPs (default: Google + 114dns)
+  // port: 53                  — DNS server port (number)
+  // recursive: true           — Recursion Desired flag (boolean, default true)
 };
 const dns = new dns2(options);
 
@@ -40,6 +38,47 @@ const dns = new dns2(options);
 })();
 ```
 
+The high-level `DNS` class exposes convenience methods for common record types:
+
+| Method | Record type | Key answer fields |
+|---|---|---|
+| `resolveA(domain)` | A | `address` |
+| `resolveAAAA(domain)` | AAAA | `address` |
+| `resolveMX(domain)` | MX | `exchange`, `priority` |
+| `resolveCNAME(domain)` | CNAME | `domain` |
+| `resolveSOA(domain)` | SOA | `primary`, `admin`, `serial`, `refresh`, `retry`, `expiration`, `minimum` |
+| `resolvePTR(domain)` | PTR | `domain` |
+| `resolveDNSKEY(domain)` | DNSKEY | `publicKey`, `algorithm` |
+| `resolveRRSIG(domain)` | RRSIG | varies |
+
+For any record type not listed above, use `dns.resolve(domain, 'TYPE')` directly.
+
+#### Example: SOA record lookup
+
+SOA (Start of Authority) records contain the authoritative zone information for a domain.
+If the authoritative nameserver returns the SOA record in the answer section, it will appear
+in `result.answers`. Otherwise check `result.authorities`.
+
+```js
+const dns2 = require('dns2');
+
+const dns = new dns2({ nameServers: ['8.8.8.8'] });
+
+(async () => {
+  const result = await dns.resolveSOA('google.com');
+  const soa = result.answers[0] || result.authorities[0];
+  if (soa) {
+    console.log(soa.primary);     // ns1.google.com
+    console.log(soa.admin);       // dns-admin.google.com
+    console.log(soa.serial);      // zone serial number
+    console.log(soa.refresh);     // refresh interval (seconds)
+    console.log(soa.retry);       // retry interval (seconds)
+    console.log(soa.expiration);  // expiry (seconds)
+    console.log(soa.minimum);     // minimum TTL (seconds)
+  }
+})();
+```
+
 Another way to instanciate dns2 UDP Client:
 
 ```js
@@ -162,7 +201,6 @@ server.listen({
   udp: { 
     port: 5333,
     address: "127.0.0.1",
-    type: "udp4",  // IPv4 or IPv6 (Must be either "udp4" or "udp6")
   },
   
   // Optionally specify port and/or address for tcp server:
@@ -185,6 +223,52 @@ $ dig @127.0.0.1 -p5333 lsong.org
 Note that when implementing your own lookups, the contents of the query
 will be found in `request.questions[0].name`.
 
+### Responding with DNS Error Codes
+
+Use `Packet.RCODE` to send standard DNS error responses from your handler:
+
+| Constant | Value | Meaning |
+|---|---|---|
+| `Packet.RCODE.NOERROR`  | 0 | No error |
+| `Packet.RCODE.FORMERR`  | 1 | Format error |
+| `Packet.RCODE.SERVFAIL` | 2 | Server failure |
+| `Packet.RCODE.NXDOMAIN` | 3 | Non-existent domain |
+| `Packet.RCODE.NOTIMP`   | 4 | Not implemented |
+| `Packet.RCODE.REFUSED`  | 5 | Query refused |
+
+```js
+const dns2 = require('dns2');
+const { Packet } = dns2;
+
+const server = dns2.createServer({
+  udp: true,
+  handle: (request, send) => {
+    const response = Packet.createResponseFromRequest(request);
+    const [ question ] = request.questions;
+
+    if (question.name.endsWith('.internal')) {
+      // Refuse queries for internal names
+      response.header.rcode = Packet.RCODE.REFUSED;
+      return send(response);
+    }
+
+    if (!isKnownDomain(question.name)) {
+      // Domain does not exist
+      response.header.rcode = Packet.RCODE.NXDOMAIN;
+      return send(response);
+    }
+
+    // Normal answer ...
+    response.answers.push({ name: question.name, type: Packet.TYPE.A, class: Packet.CLASS.IN, ttl: 300, address: '1.2.3.4' });
+    send(response);
+  }
+});
+```
+
+### Performance and Benchmarking
+
+see [benchmark/README.md](benchmark/README.md)
+
 ### Relevant Specifications
 
 + [RFC-1034 - Domain Names - Concepts and Facilities](https://tools.ietf.org/html/rfc1034)
@@ -225,3 +309,7 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
+
+[npm-img]: https://img.shields.io/npm/v/dns2.svg?style=flat
+[ci-img]: https://github.com/song940/node-dns/actions/workflows/node.js.yml/badge.svg
+[ci-url]: https://github.com/song940/node-dns/actions/workflows/node.js.yml

package/client/doh.js

@@ -1,49 +1,89 @@
+const http = require('node:http');
+const https = require('node:https');
+const http2 = require('node:http2');
 const Packet = require('../packet');
 
-const defaultGet = url => new Promise((resolve, reject) => {
-  const headers = {
-    accept: 'application/dns-message',
-  };
-  const base = url.startsWith('https') ? require('https') : require('http');
-  const req = base.get(url, { headers }, resolve);
-  req.on('error', reject);
-});
+const protocols = {
+  'http:'  : http.get,
+  'https:' : https.get,
+  'h2:'    : (url, options, done) => {
+    const urlObj = new URL(url);
+    const client = http2.connect(url.replace('h2:', 'https:'));
+    const req = client.request({
+      ':path'   : `${urlObj.pathname}${urlObj.search}`,
+      ':method' : 'GET',
+      ...options.headers,
+    });
+
+    req.on('response', headers => {
+      client.close();
+      done({
+        headers,
+        statusCode : headers[':status'],
+        on         : req.on.bind(req),
+      });
+    });
+
+    req.on('error', err => {
+      client.close();
+      throw err;
+    });
 
-const readStream = stream => {
-  const buffer = [];
-  return new Promise((resolve, reject) => {
-    stream
-      .on('error', reject)
-      .on('data', chunk => buffer.push(chunk))
-      .on('end', () => resolve(Buffer.concat(buffer)));
-  });
+    req.end();
+  },
 };
 
-/**
- * @docs https://tools.ietf.org/html/rfc8484
- * @param {*} param0
- */
-const DOHClient = ({ dns, http, get = defaultGet } = {}) => {
-  return (name, type = 'A', cls = Packet.CLASS.IN, { clientIp, recursive = true } = {}) => {
-    const packet = new Packet();
-    // see https://github.com/song940/node-dns/issues/29
-    if (recursive) {
-      packet.header.rd = 1;
-    }
-    if (clientIp) {
-      packet.additionals.push(Packet.Resource.EDNS([
-        Packet.Resource.EDNS.ECS(clientIp),
-      ]));
-    }
-    packet.questions.push({
-      name,
-      class : cls,
-      type  : Packet.TYPE[type],
+const makeRequest = (url, query) => new Promise((resolve, reject) => {
+  const index = url.indexOf('://');
+  if (index === -1) url = `https://${url}`;
+  const u = new URL(url);
+  // The DNS query is included in a single variable named “dns” in the
+  // query component of the request URI.  The value of the “dns” variable
+  // is the content of the DNS request message, encoded with base64url
+  // [RFC4648](https://datatracker.ietf.org/doc/html/rfc8484#section-4.1).
+  const searchParams = u.searchParams;
+  searchParams.set('dns', query);
+  u.search = searchParams.toString();
+  const get = protocols[u.protocol];
+  if (!get) throw new Error(`Unsupported protocol: ${u.protocol}, must be specified (http://, https:// or h2://)`);
+  const req = get(u.toString(), { headers: { accept: 'application/dns-message' } }, resolve);
+  if (req) req.on('error', reject);
+});
+
+const readStream = res => new Promise((resolve, reject) => {
+  const chunks = [];
+  res
+    .on('error', reject)
+    .on('data', chunk => chunks.push(chunk))
+    .on('end', () => {
+      const data = Buffer.concat(chunks);
+      if (res.statusCode !== 200) {
+        reject(new Error(`HTTP ${res.statusCode}: ${data.toString()}`));
+      }
+      resolve(data);
     });
-    const query = packet.toBase64URL();
-    return Promise.resolve(get(`http${http ? '' : 's'}://${dns}/dns-query?dns=${query}`))
-      .then(readStream)
-      .then(Packet.parse);
+});
+
+const buildQuery = ({ name, type = 'A', cls = Packet.CLASS.IN, clientIp, recursive = true }) => {
+  const packet = new Packet();
+  packet.header.rd = recursive ? 1 : 0;
+
+  if (clientIp) {
+    packet.additionals.push(Packet.Resource.EDNS([
+      Packet.Resource.EDNS.ECS(clientIp),
+    ]));
+  }
+
+  packet.questions.push({ name, class: cls, type: Packet.TYPE[type] });
+  return packet.toBase64URL();
+};
+
+const DOHClient = ({ dns }) => {
+  return async(name, type, cls, options = {}) => {
+    const query = buildQuery({ name, type, cls, ...options });
+    const response = await makeRequest(dns, query);
+    const data = await readStream(response);
+    return Packet.parse(data);
   };
 };
 

package/client/google.js

@@ -1,4 +1,4 @@
-const https = require('https');
+const https = require('node:https');
 
 const get = url => new Promise(resolve =>
   https.get(url, resolve));

package/client/tcp.js

@@ -1,34 +1,49 @@
-const tcp = require('net');
+const tls = require('node:tls');
+const tcp = require('node:net');
 const Packet = require('../packet');
 
-module.exports = ({ dns = '1.1.1.1', port = 53 } = {}) => {
-  return async(name, type = 'A', cls = Packet.CLASS.IN, { clientIp, recursive = true } = {}) => {
-    const packet = new Packet();
-
-    // see https://github.com/song940/node-dns/issues/29
-    if (recursive) {
-      packet.header.rd = 1;
-    }
-    if (clientIp) {
-      packet.additionals.push(Packet.Resource.EDNS([
-        Packet.Resource.EDNS.ECS(clientIp),
-      ]));
-    }
-
-    packet.questions.push({
-      name,
-      class : cls,
-      type  : Packet.TYPE[type],
-    });
-    const message = packet.toBuffer();
-    const len = Buffer.alloc(2);
-    len.writeUInt16BE(message.length);
-    const client = tcp.connect({ host: dns, port });
-    client.end(Buffer.concat([ len, message ]));
+const makeQuery = ({ name, type = 'A', cls = Packet.CLASS.IN, clientIp, recursive = true }) => {
+  const packet = new Packet();
+  packet.header.rd = recursive ? 1 : 0;
+
+  if (clientIp) {
+    packet.additionals.push(Packet.Resource.EDNS([
+      Packet.Resource.EDNS.ECS(clientIp),
+    ]));
+  }
+
+  packet.questions.push({ name, class: cls, type: Packet.TYPE[type] });
+  return packet.toBuffer();
+};
+
+const sendQuery = (client, message) => {
+  const len = Buffer.alloc(2);
+  len.writeUInt16BE(message.length);
+  client.write(Buffer.concat([ len, message ]));
+};
+
+const protocols = {
+  'tcp:' : (host, port) => tcp.connect({ host, port }),
+  'tls:' : (host, port) => tls.connect({ host, port, servername: host }),
+};
+
+const TCPClient = ({ dns, protocol = 'tcp:', port = protocol === 'tls:' ? 853 : 53 } = {}) => {
+  if (!protocols[protocol]) {
+    throw new Error('Protocol must be tcp: or tls:');
+  }
+
+  return async(name, type, cls, options = {}) => {
+    const message = makeQuery({ name, type, cls, ...options });
+    const [ host ] = dns.split(':');
+    const client = protocols[protocol](host, port);
+
+    sendQuery(client, message);
     const data = await Packet.readStream(client);
-    if (!data.length) {
-      throw new Error('Empty TCP response');
-    }
+    client.end();
+
+    if (!data.length) throw new Error('Empty response');
     return Packet.parse(data);
   };
 };
+
+module.exports = TCPClient;

package/client/udp.js

@@ -1,15 +1,22 @@
-const udp = require('dgram');
+const udp = require('node:dgram');
+const net = require('node:net');
+const crypto = require('node:crypto');
 const Packet = require('../packet');
-const { equal } = require('assert');
-const { debuglog } = require('util');
+const { debuglog } = require('node:util');
 
 const debug = debuglog('dns2');
 
-module.exports = ({ dns = '8.8.8.8', port = 53, socketType = 'udp4' } = {}) => {
-  return (name, type = 'A', cls = Packet.CLASS.IN, { clientIp, recursive = true } = {}) => {
+module.exports = ({
+  dns = '8.8.8.8',
+  port = 53,
+  socketType = 'udp4',
+  timeout = 10000,
+  retryOverTCP = true,
+} = {}) => {
+  return (name, type = 'A', cls = Packet.CLASS.IN, options = {}) => {
+    const { clientIp, recursive = true } = options;
     const query = new Packet();
-    query.header.id = (Math.random() * 1e4) | 0;
-
+    query.header.id = crypto.randomInt(0x10000);
     // see https://github.com/song940/node-dns/issues/29
     if (recursive) {
       query.header.rd = 1;
@@ -25,15 +32,76 @@ module.exports = ({ dns = '8.8.8.8', port = 53, socketType = 'udp4' } = {}) => {
       type  : Packet.TYPE[type],
     });
     const client = new udp.Socket(socketType);
+    // Only enforce a strict source-address check when `dns` is an IP literal;
+    // hostnames would require an extra resolve to compare against.
+    const expectedAddress = net.isIP(dns) ? dns : null;
     return new Promise((resolve, reject) => {
-      client.once('message', function onMessage(message) {
-        client.close();
-        const response = Packet.parse(message);
-        equal(response.header.id, query.header.id);
+      let settled = false;
+      let timer;
+      const cleanup = () => {
+        if (settled) return;
+        settled = true;
+        if (timer) clearTimeout(timer);
+        client.removeListener('message', onMessage);
+        client.removeListener('error', onError);
+        try { client.close(); } catch (_) { /* already closed */ }
+      };
+      function onMessage(message, rinfo) {
+        // Drop packets that didn't come from the configured resolver.
+        if (rinfo.port !== port || (expectedAddress && rinfo.address !== expectedAddress)) {
+          debug('udp: dropping packet from unexpected sender %s:%d', rinfo.address, rinfo.port);
+          return;
+        }
+        let response;
+        try {
+          response = Packet.parse(message);
+        } catch (e) {
+          debug('udp: dropping unparseable packet: %s', e.message);
+          return;
+        }
+        // Stray / late reply from a reused ephemeral port — keep listening.
+        if (response.header.id !== query.header.id) {
+          debug('udp: dropping response with mismatched id %d (expected %d)',
+            response.header.id, query.header.id);
+          return;
+        }
+        // RFC 1035 §4.2.1: if the TC (truncated) bit is set the upstream had
+        // more data than fits in a 512-byte UDP datagram.  Retry over TCP so
+        // callers always receive a complete answer.
+        if (response.header.tc && retryOverTCP) {
+          debug('udp: TC bit set — retrying query over TCP');
+          cleanup();
+          const TCPClient = require('./tcp');
+          resolve(TCPClient({ dns, port })(name, type, cls, options));
+          return;
+        }
+        cleanup();
         resolve(response);
-      });
+      }
+      function onError(err) {
+        cleanup();
+        reject(err);
+      }
+      client.on('message', onMessage);
+      client.on('error', onError);
+
+      if (timeout > 0) {
+        timer = setTimeout(() => {
+          cleanup();
+          const err = new Error(`DNS query timed out after ${timeout}ms`);
+          err.code = 'ETIMEDOUT';
+          reject(err);
+        }, timeout);
+        timer.unref();
+      }
+
       debug('send', dns, query.toBuffer());
-      client.send(query.toBuffer(), port, dns, err => err && reject(err));
+      client.send(query.toBuffer(), port, dns, err => {
+        if (err) {
+          cleanup();
+          reject(err);
+        }
+      });
     });
   };
 };

package/example/client/doh.js

@@ -1,12 +1,22 @@
 const { DOHClient } = require('../..');
 
-process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
+// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 
-const resolve = DOHClient({
-  dns: '1.1.1.1',
-});
+// const resolve = DOHClient({
+//   dns: '1.1.1.1',
+// });
 
-(async() => {
-  const response = await resolve('google.com');
-  console.log(response.answers);
-})();
+// (async() => {
+//   const response = await resolve('google.com');
+//   console.log(response.answers);
+// })();
+
+// import DNS2 from 'dns2';
+
+// DOHClient({
+//   dns: 'h2://ada.openbld.net',
+// })('cdnjs.com', 'NS').then(console.log);
+
+DOHClient({
+  dns: 'https://1.0.0.1/dns-query',
+})('cdnjs.com', 'NS').then(console.log);

package/index.js

@@ -7,7 +7,7 @@ const {
   createDOHServer,
   createServer,
 } = require('./server');
-const EventEmitter = require('events');
+const EventEmitter = require('node:events');
 
 /**
  * [DNS description]
@@ -15,13 +15,19 @@ const EventEmitter = require('events');
  * @docs https://tools.ietf.org/html/rfc1035
  */
 class DNS extends EventEmitter {
-  constructor(options) {
+  constructor(options = {}) {
     super();
+    // Accept `dns` as a shorthand alias for `nameServers` so that
+    // `new DNS({ dns: '8.8.8.8' })` works as documented and intuited.
+    if (options.dns != null && options.nameServers == null) {
+      options = Object.assign({}, options, { nameServers: [].concat(options.dns) });
+    }
     Object.assign(this, {
       port             : 53,
       retries          : 3,
       timeout          : 3,
       recursive        : true,
+      retryOverTCP     : true,
       resolverProtocol : 'UDP',
       nameServers      : [
         '8.8.8.8',
@@ -34,27 +40,19 @@ class DNS extends EventEmitter {
     }, options);
   }
 
-  /**
-   * query
-   * @param {*} questions
-   */
-  query(name, type, cls, clientIp) {
-    const { port, nameServers, recursive, resolverProtocol = 'UDP' } = this;
-    const createResolver = DNS[resolverProtocol + 'Client'];
-    return Promise.race(nameServers.map(address => {
-      const resolve = createResolver({ dns: address, port, recursive });
-      return resolve(name, type, cls, clientIp);
-    }));
-  }
-
   /**
    * resolve
    * @param {*} domain
    * @param {*} type
    * @param {*} cls
    */
-  resolve(domain, type = 'ANY', cls = DNS.Packet.CLASS.IN, clientIp = undefined) {
-    return this.query(domain, type, cls, clientIp);
+  resolve(domain, type = 'ANY', cls = DNS.Packet.CLASS.IN, options = {}) {
+    const { port, nameServers, resolverProtocol = 'UDP', retryOverTCP } = this;
+    const createResolver = DNS[resolverProtocol + 'Client'];
+    return Promise.race(nameServers.map(address => {
+      const resolve = createResolver({ dns: address, port, retryOverTCP });
+      return resolve(domain, type, cls, options);
+    }));
   }
 
   resolveA(domain, clientIp) {
@@ -76,6 +74,18 @@ class DNS extends EventEmitter {
   resolvePTR(domain) {
     return this.resolve(domain, 'PTR');
   }
+
+  resolveDNSKEY(domain) {
+    return this.resolve(domain, 'DNSKEY');
+  }
+
+  resolveRRSIG(domain) {
+    return this.resolve(domain, 'RRSIG');
+  }
+
+  resolveSOA(domain) {
+    return this.resolve(domain, 'SOA');
+  }
 }
 
 DNS.TCPServer = TCPServer;