njord-ns-server 1.0.1 → 2.1.0

package/Makefile

@@ -1,5 +1,3 @@
-NODEUNIT 	:= ./node_modules/.bin/nodeunit
-BUNYAN 		:= ./node_modules/.bin/bunyan
 NPM 		:= $(shell which npm)
 
 .PHONY: setup
@@ -7,7 +5,5 @@ setup: $(NPM)
 	$(NPM) install
 
 .PHONY: test
-test: $(NODEUNIT)
-	$(NODEUNIT) test/*.test.js $(BUNYAN)
-
-
+test: $(NPM)
+	$(NPM) test

package/README.md

@@ -8,6 +8,20 @@ functionality that is in use today.
 
 
 
+## Requirements
+
+Node.js 20 or newer.
+
+## Testing
+
+```
+npm install
+npm test
+```
+
+The tests use the test runner that is built into Node.js, and query a running
+server with the `dns` resolver of Node.js, so no other tools are needed.
+
 ## Creating a DNS Server
 ```javascript
 var named = require('./lib/index');
@@ -30,7 +44,7 @@ server.on('query', function(query) {
 
 node-named provides helper functions for creating DNS records.
 The records are available under 'named.record.NAME' where NAME is one
-of ['A', 'AAAA', 'CNAME', 'SOA', 'MX', 'NS', 'TXT, 'SRV']. It is important to
+of ['A', 'AAAA', 'CNAME', 'SOA', 'MX', 'NS', 'PTR', 'TXT, 'SRV']. It is important to
 remember that these DNS records are not permanently added to the server.
 They only exist for the length of the particular request. After that, they are
 destroyed. This means you have to create your own lookup mechanism.
@@ -50,6 +64,7 @@ The following record types are supported
  * SOA (start of authority)
  * MX (mail server records)
  * NS (nameserver entries)
+ * PTR (reverse entries)
  * TXT (arbitrary text entries)
  * SRV (service discovery)
 
@@ -65,12 +80,69 @@ You can pass in an alternate logger if you wish. If you do not, then it will use
 bunyan by default. Your logger must expose the functions 'info', 'debug',
 'warn', 'trace', 'error', and 'notice'.
 
-### TODO
+### Validating records
+
+`record.valid()` tells you whether a record can be sent to a client, and
+`record.invalid()` which of its properties can not:
+```javascript
+var srv = new named.SRVRecord('sip example', 70000);
+srv.valid();    // false
+srv.invalid();  // [ 'target', 'port' ]
+```
+
+## TCP and zone transfers (AXFR)
+
+A server listens on UDP with `listen`, and on TCP with `listenTcp`. Queries
+that arrive over TCP are emitted and answered in the same way as the ones that
+arrive over UDP, and `query.transport()` tells them apart.
+
+A zone transfer is a query of the type `AXFR`, that is answered with all of
+the records of the zone, between two copies of its SOA record. A transfer that
+is too large for one DNS message is split over as many messages as it takes.
+```javascript
+server.listen(9999, '127.0.0.1');
+server.listenTcp(9999, '127.0.0.1');
+
+server.on('query', function(query) {
+  if (query.type() === 'AXFR') {
+    if (query.transport() !== 'tcp' || query.name() !== 'example.com') {
+      query.setError('erefuse');
+    } else {
+      query.addAnswer('example.com', soa, 300);
+      // ... one addAnswer for each record of the zone ...
+      query.addAnswer('example.com', soa, 300);
+    }
+  }
+  server.send(query);
+});
+```
+See `examples/axfr.js` for a complete server. Anyone who can reach the TCP
+port can ask for a transfer, so check `query._client.address` before you
+answer one.
 
- * Better record validation
- * Create DNS client for query recursor
- * Add support for PTR records
- * Add support for TCP AXFR requests
+## Recursor
+
+A recursor is a DNS client that answers a query by asking other DNS servers,
+which are the ones of the system unless you name them. A lookup that fails
+sets the response code of the query (`query.setError`), so the query can be
+sent either way.
+```javascript
+var recursor = named.createRecursor({servers: ['1.1.1.1', '8.8.8.8']});
+
+server.on('query', function(query) {
+  recursor.resolve(query, function() {
+    server.send(query);
+  });
+});
+```
+The client can be used by itself as well:
+```javascript
+recursor.lookup('example.com', 'MX').then(function(answers) {
+  // [ { record: MX { exchange: ..., priority: ... }, ttl: 60 }, ... ]
+});
+```
+The A, AAAA, CNAME, MX, NS, PTR, SOA, SRV and TXT records can be looked up.
+See `examples/recursor.js`.
 
 ## Tell me even more...
 
@@ -85,3 +157,7 @@ basis).
 
 There are a few handy ways to lookup DNS records in node.
 https://github.com/LCMApps/dns-lookup-cache
+
+## Release notes
+
+See [RELEASE.md](RELEASE.md) for what changed in each release.

package/RELEASE.md

@@ -0,0 +1,177 @@
+# Njord NS Server 2.1.0
+
+This release completes the TODO list of the project: PTR records, better
+validation of records, queries over TCP including zone transfers (AXFR), and a
+recursor that answers queries by asking other DNS servers.
+
+Everything is an addition to 2.0.0. Existing servers keep working without
+changes, with the exceptions listed under "Behaviour changes".
+
+## New features
+
+### PTR records
+
+`named.PTRRecord(target)` is the answer to a reverse lookup, such as a query
+for `1.2.0.192.in-addr.arpa`.
+
+### Record validation
+
+- `record.valid()` checks that names are valid host or domain names, that
+  addresses are valid addresses, and that numbers are integers within the
+  range of their field.
+- `record.invalid()` returns the names of the properties that hold invalid
+  data, for example `['target', 'port']`.
+- `query.addAnswer` throws a `RangeError` for a TTL that is not an integer
+  from 0 to 2147483647.
+
+### TCP and zone transfers (AXFR)
+
+- `server.listenTcp(port, [host], [onListen])` accepts queries over TCP, next
+  to or instead of the UDP socket of `server.listen`. `server.close()` closes
+  both.
+- Queries that arrive over TCP are emitted with the same `query` event and
+  answered with the same `server.send`. `query.transport()` returns `'udp'` or
+  `'tcp'`.
+- A zone transfer is a query of the type `AXFR`, answered with the SOA record
+  of the zone, its records, and the SOA record again. A response of more than
+  65535 bytes is split over several DNS messages.
+- Idle connections are closed after 30 seconds, which the `tcpTimeout` option
+  of `createServer` changes.
+
+There is no access control for zone transfers: check `query._client.address`
+before you answer one. See `examples/axfr.js`.
+
+### Recursor
+
+- `named.createRecursor({servers, timeout, tries, ttl})` creates a DNS client
+  on top of the resolver of Node.js (c-ares). Without `servers` it asks the
+  DNS servers of the system.
+- `recursor.resolve(query, [callback])` adds the answers that are found to a
+  query, or sets its response code when the lookup fails, so that the query
+  can be sent either way.
+- `recursor.lookup(name, type)` is the client by itself, and returns a promise
+  for a list of records with their TTL.
+- The A, AAAA, CNAME, MX, NS, PTR, SOA, SRV and TXT records can be looked up.
+
+The resolver only reports the TTL of A and AAAA records. The other records get
+the `ttl` of the recursor, which is 60 seconds by default. See
+`examples/recursor.js`.
+
+### Response codes
+
+`query.setError(name)` sets the response code of a query, with `'enoerr'`,
+`'eformat'`, `'eserver'`, `'enoname'`, `'enotimp'` or `'erefuse'`.
+
+## Behaviour changes
+
+- The target of a SRV record must be a domain name to be valid. It used to be
+  any text of up to 255 characters.
+- The port of a SRV record must be from 1 to 65535 to be valid.
+- An IPv6 address with a zone (`fe80::1%eth0`) is not valid.
+- The TTL of a MX record must be at most 2147483647 to be valid.
+- A TXT record of more than 255 bytes is valid, as it is sent as several
+  strings.
+- Host names may end with a dot, and may be the root (`.`), which is what a
+  null MX record and a SRV record of an unavailable service use.
+- `query.addAnswer` rejects a TTL that is negative, fractional or too large
+  when the answer is added. It used to fail when the response was sent.
+
+## Known limitations
+
+- A response that is too large for UDP is sent as it is. It is not truncated
+  to make the client retry over TCP.
+- `examples/cluster.js` does not run on Windows.
+
+## Testing
+
+```
+npm install
+npm test
+```
+
+The 105 tests cover the new features with a live server: queries over TCP, a
+zone transfer of 6000 records, and a recursor that asks a second server.
+
+---
+
+# Njord NS Server 2.0.0
+
+This release modernizes the codebase, updates every dependency, and makes
+encoding a response several times faster. The exported API is unchanged, but
+the minimum Node.js version is raised and a number of bugs are fixed in ways
+that callers can observe, hence the new major version.
+
+## Requirements
+
+Node.js 20 or newer (was 0.6).
+
+## Upgrading from 1.x
+
+No code changes are needed for most users: the exports, method signatures and
+events are the same, and `error.message()` is still a function. Check the list
+of behaviour changes below if you relied on any of the old behaviour.
+
+## Dependencies
+
+| Package   | 1.0.1 | 2.0.0   |
+|-----------|-------|---------|
+| bunyan    | 0.7.0 | 1.8.15  |
+| ipaddr.js | 0.1.1 | 2.5.0   |
+| nodeunit  | 0.9.0 | removed |
+
+The tests now use the test runner that is built into Node.js, so there are no
+development dependencies, and `dig` is no longer needed to run them.
+
+## Performance
+
+A response is written in a single pass into one buffer, instead of one small
+buffer per field. Names are compressed with DNS pointers (RFC 1035 4.1.4), so
+responses are smaller as well.
+
+Parsing a query and encoding its response, measured on one machine:
+
+| Response | 1.0.1 (ops/s) | 2.0.0 (ops/s) | Size (bytes) |
+|----------|---------------|---------------|--------------|
+| A        | 53k           | 236k          | 62 → 48      |
+| AAAA     | 41k           | 144k          | 74 → 60      |
+| SOA      | 44k           | 234k          | 113 → 79     |
+| 4 × MX   | 21k           | 118k          | 208 → 112    |
+
+This is a micro-benchmark of the protocol code, not of network throughput.
+
+## Behaviour changes
+
+- `record.valid()` validates the record. It used to return `true` for
+  everything.
+- `query.addAnswer(name, record, 0)` sends a TTL of 0. It used to be replaced
+  by the default of 5.
+- `server.listen(port, '::1')` listens on IPv6. A UDP4 socket used to be
+  opened whatever the address was.
+- The address family of the client of a query is the real one. It used to be
+  reported as `udp6` for every client.
+- The counts in the header of a response describe what is sent. A query with
+  EDNS options used to get a response that announced an additional record
+  which was not there.
+- The opcode of a query is decoded correctly, so `query.operation()` works for
+  status, notify and update messages.
+- Names with a trailing dot, and the root name, are encoded correctly.
+- TXT records longer than 255 bytes are split into several strings.
+- The constructors of the records leave the options that are passed to them
+  alone.
+- Invalid addresses and names are rejected when the response is encoded, which
+  is reported with the `uncaughtException` event of the server.
+
+## Other changes
+
+- `lib/` is written with classes and in strict mode, and no longer leaks
+  global variables.
+- The examples listen on port 9999, as their output always claimed.
+- `examples/cluster.js` documents that it does not run on Windows, where
+  Node.js can not share a UDP socket between the workers of a cluster.
+
+## Testing
+
+```
+npm install
+npm test
+```

package/docs/index.md

@@ -77,6 +77,8 @@ options is an object which may specify:
 
 - log: an optional bunyan logger
 - name: an optional name used to identify the server
+- tcpTimeout: the number of milliseconds after which an idle TCP connection is
+  closed. Defaults to 30000, and 0 disables the timeout.
 
 Here is an example a named server listening on port 53
 
@@ -99,6 +101,17 @@ This function is asyncronous. Whenever the server is litening a `listen` event
 will be emitted. The last parameter `onListen` will be executed but not attached
 to the listen event, when the server is listening.
 
+### server.listenTcp(port, [host], [onListen])
+
+Start accepting TCP connections on the specified `port` and `host`, next to
+or instead of the UDP socket of `server.listen`. TCP is what clients use for
+zone transfers (AXFR), and for answers that are too large for UDP.
+
+Queries that arrive over TCP are emitted with the same `query` event, and are
+answered with the same `server.send`. A client may send several queries over
+one connection. A response of more than 65535 bytes is sent as several DNS
+messages, which is how a large zone is transferred.
+
 ### server.send(queryResponse)
 
 Sends a `queryResponse` message. The queryResponse includes information about
@@ -111,8 +124,8 @@ will send a 'null-response' DNS message. This is the equivalent of an HTTP 404.
 
 ### server.close(onClose)
 
-Stops listening and closes the socket. `onClose` is an optional callback that
-will be attached to the underlying socket `close` event.
+Stops listening, on UDP as well as on TCP, and closes the open TCP connections.
+`onClose` is an optional callback that is called once everything is closed.
 
 ### Event: 'listening'
 
@@ -190,6 +203,22 @@ are responding with. In most cases this will be what the query.type() returns,
 but for instances like an 'A' or 'AAAA' request you may elect to respond with a
 CNAME record. 
 
+### query.transport()
+
+Returns `'udp'` or `'tcp'`, depending on how the query was received. A zone
+transfer (a query of the type 'AXFR') should only be answered over TCP.
+
+### query.setError(name)
+
+Sets the response code of the query. `name` is one of:
+
+- `'enoerr'`: no error, which is the default
+- `'eformat'`: the query could not be interpreted
+- `'eserver'`: the server failed to process the query
+- `'enoname'`: the name does not exist
+- `'enotimp'`: the kind of query is not implemented
+- `'erefuse'`: the server refuses to answer, for policy reasons
+
 ### query.operation()
 
 Returns the type of operation that the client is requesting. In almost all cases
@@ -202,6 +231,68 @@ Encodes the query and stores the results as a `buffer` in the query itself.
 This function should never need to be invoked, as the `server.send` function
 will automatically encode a query prior to being sent to the client.
 
+### query.encodeMessages(maxSize)
+
+Encodes the query as an array of buffers, each of which is a DNS message of at
+most `maxSize` bytes with as many of the answers as fit. This is what
+`server.send` uses for a query that was received over TCP.
+
+## Class: named.Recursor
+
+A DNS client that answers queries by asking other DNS servers. The lookups are
+made with the resolver of Node.js, which is built on c-ares.
+
+### named.createRecursor([options])
+
+options is an object which may specify:
+
+- servers: an array with the addresses of the servers to ask, each with an
+  optional port (`'192.0.2.1'`, `'192.0.2.1:5353'`, `'[2001:db8::1]:53'`).
+  Defaults to the DNS servers of the system.
+- timeout: the number of milliseconds to wait for an answer to each attempt
+- tries: the number of attempts that are made for each lookup
+- ttl: the ttl of the answers for which the server that was asked does not
+  report one, which it only does for A and AAAA records. Defaults to 60.
+
+### recursor.resolve(query, [callback])
+
+Looks up the question of a `query`, and adds what is found to it as answers.
+When the lookup fails the response code of the query is set instead: to
+'enoname' for a name that does not exist, to 'enotimp' for a type that can not
+be looked up, to 'erefuse' when the other server refuses, and to 'eserver' for
+everything else. In either case the query is ready to be sent.
+
+    server.on('query', function(query) {
+      recursor.resolve(query, function() {
+        server.send(query);
+      });
+    });
+
+`callback` is called with an error (which is `null`, as failed lookups are
+reported to the client) and the query. Without a callback a promise for the
+query is returned.
+
+### recursor.lookup(name, type)
+
+Looks up the records of a `type` for a `name`. Returns a promise for an array
+of objects with a `record` (an instance of `named.Record`) and its `ttl`.
+The promise is rejected with the error of the resolver, of which the `code` is
+one of the error codes of the `dns` module of Node.js, such as 'ENOTFOUND' and
+'ENODATA'.
+
+### recursor.types()
+
+Returns the types of record that can be looked up: A, AAAA, CNAME, MX, NS, PTR,
+SOA, SRV and TXT.
+
+### recursor.servers()
+
+Returns the addresses of the servers that are asked.
+
+### recursor.cancel()
+
+Cancels the lookups that are in progress, which then fail.
+
 
 ## Records
 
@@ -243,6 +334,17 @@ Create an IPv6 resource record.
 Create an Alias record. When these records are sent to the client, the client
 will often make an additional request for the alias itself.
 
+### named.NSRecord(target)
+
+Create a Name Server record. `target` is the name of a server that is
+authoritative for the domain.
+
+### named.PTRRecord(target)
+
+Create a Pointer record, which is the answer to a reverse lookup: a query for a
+name such as `1.2.0.192.in-addr.arpa`. `target` is the name of the host that
+has the address.
+
 ### named.MXRecord(exchange, options)
 
 Create a Mail Server record. A client making this request will often make an
@@ -269,14 +371,21 @@ Options:
 ### named.TXTRecord(target)
 
 Create a text resource record.
-`target` can be any text up to 500 bytes in length
+`target` can be any text. Text of more than 255 bytes is sent as several
+strings, which clients join again.
 
 ## Class: named.Record
 
 ### record.valid()
 
 This function will ensure that the data you used to create the record is in fact
-valid.
+valid. Names must be valid host or domain names, addresses must be valid
+addresses, and numbers must be integers within the range of their field.
+
+### record.invalid()
+
+Returns an array with the names of the properties of the record that hold
+invalid data, which is empty for a valid record.
 
 ## DnsError
 

package/examples/app.js

@@ -1,15 +1,17 @@
-var named = require('../lib');
-var server = named.createServer();
+'use strict';
 
-server.listen(53, '127.0.0.1', function() {
-  console.log('DNS server started on port 9999');
-});
+const named = require('../lib');
+
+const PORT = 9999;
+const server = named.createServer();
 
-console.log(named.SoaRecord);
+server.listen(PORT, '127.0.0.1', () => {
+  console.log('DNS server started on port %d', PORT);
+});
 
-server.on('query', function(query) {
-  var domain = query.name();
-  var record = new named.SOARecord(domain, {serial: 12345, ttl: 300});
+server.on('query', (query) => {
+  const domain = query.name();
+  const record = new named.SOARecord(domain, {serial: 12345, ttl: 300});
   query.addAnswer(domain, record, 300);
   server.send(query);
 });

package/examples/axfr.js

@@ -0,0 +1,74 @@
+'use strict';
+
+/**
+ * A server that listens on UDP as well as on TCP, and that transfers its zone
+ * to the clients that ask for it (AXFR).
+ *
+ * You can test it like this:
+ *
+ *   $ dig @127.0.0.1 -p 9999 www.example.com
+ *   $ dig @127.0.0.1 -p 9999 example.com AXFR
+ */
+
+const named = require('../lib');
+
+const PORT = 9999;
+const ZONE = 'example.com';
+const TTL = 300;
+
+const soa = new named.SOARecord('ns.' + ZONE, {serial: 2024010101});
+
+// name -> records
+const records = {
+  'example.com': [
+    new named.NSRecord('ns.example.com'),
+    new named.MXRecord('smtp.example.com', {priority: 10})
+  ],
+  'ns.example.com': [new named.ARecord('192.0.2.1')],
+  'smtp.example.com': [new named.ARecord('192.0.2.2')],
+  'www.example.com': [new named.CNAMERecord('example.com')],
+  '_sip._tcp.example.com': [new named.SRVRecord('sip.example.com', 5060)]
+};
+
+const server = named.createServer();
+
+server.on('query', (query) => {
+  const domain = query.name();
+  const type = query.type();
+  console.log('DNS Query: (%s) %s over %s', type, domain, query.transport());
+
+  if (type === 'AXFR') {
+    // Zone transfers are only possible over TCP. This is also the place to
+    // check query._client.address: a zone should not be given to everyone.
+    if (query.transport() !== 'tcp' || domain !== ZONE) {
+      query.setError('erefuse');
+    } else {
+      // a transfer starts and ends with the SOA record of the zone
+      query.addAnswer(ZONE, soa, TTL);
+      for (const name of Object.keys(records)) {
+        for (const record of records[name])
+          query.addAnswer(name, record, TTL);
+      }
+      query.addAnswer(ZONE, soa, TTL);
+    }
+  } else if (type === 'SOA' && domain === ZONE) {
+    query.addAnswer(ZONE, soa, TTL);
+  } else if (records[domain] === undefined) {
+    query.setError('enoname');
+  } else {
+    for (const record of records[domain]) {
+      if (record._type === type)
+        query.addAnswer(domain, record, TTL);
+    }
+  }
+
+  server.send(query);
+});
+
+server.listen(PORT, '127.0.0.1', () => {
+  console.log('DNS server started on udp port %d', PORT);
+});
+
+server.listenTcp(PORT, '127.0.0.1', () => {
+  console.log('DNS server started on tcp port %d', PORT);
+});