IF Commons GitHub

dns

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-net FR-007

Names on the network (commons 0001-net FR-007). resolveDns asks for A, AAAA, CNAME, MX, NS, TXT and SRV records, with the records in these shapes (MX as { preference, exchange }, TXT as each record's strings, SRV as { priority, weight, port, target }), and answers with a Result whose error says whether the name does not exist, has no such record, or could not be asked: a name that does not resolve is an expected outcome, not an exception.

The question is asked here, over node:dgram (and node:net where the answer is too long for UDP), not through node:dns: the two runtimes' node:dns can disagree on exactly what this must tell apart (Bun reports a name without the record as one that does not exist), so one small stub resolver (RFC 1035, with EDNS0 for answers up to 1232 bytes over UDP) gives the same answer everywhere. The servers asked are the system's (node:dns's getServers, which reads /etc/resolv.conf or Windows's settings) or the one given; each is tried twice, for two seconds each time.

Names in records come without the trailing dot (mail.example.com, as Node gives them). The DNS is asked directly, so the hosts file (localhost) is not read.

import { resolveDns } from "./dns.ts";
const r = await resolveDns("example.com", "MX");
if (r.kind === "ok") for (const mx of r.value) console.log(mx.preference, mx.exchange);
else if (r.error.kind === "not-found") console.log("no such domain");

Source: commons/net/src/dns.ts

1 of 16 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

dnsnamespace
namespace dns
dns.RecordTypetypeno test imports it
type RecordType = "A" | "AAAA" | "CNAME" | "MX" | "NS" | "TXT" | "SRV";

The record types that can be asked for.

dns.MxRecordtypeno test imports it
type MxRecord = { readonly preference: number; readonly exchange: string };

A mail exchanger.

dns.SrvRecordtypeno test imports it
type SrvRecord = { readonly priority: number; readonly weight: number; readonly port: number; readonly target: string };

A service's host and port.

dns.RecordOftypeno test imports it
type RecordOf = {
  readonly A: string;
  readonly AAAA: string;
  readonly CNAME: string;
  readonly NS: string;
  readonly MX: MxRecord;
  readonly TXT: readonly string[];
  readonly SRV: SrvRecord;
};

The shape of one record of each type: an address or a name as a string, TXT as its strings (join them for the whole text).

dns.DnsErrortypeno test imports it
type DnsError =
  | { readonly kind: "not-found"; readonly name: string }
  | { readonly kind: "no-data"; readonly name: string; readonly type: RecordType }
  | { readonly kind: "failed"; readonly name: string; readonly code: string; readonly message: string };

Why there is no answer: the name does not exist (NXDOMAIN), it has no record of that type, or the DNS could not be asked (code is ESERVFAIL, EREFUSED, EFORMERR, ENOTIMP or ERCODE<n> for the server's answer, ETIMEOUT, ECANCELLED, EBADRESP for an answer that cannot be read, EBADNAME, ENOSERVERS, or the host's error code, such as ECONNREFUSED).

dns.NameServertypeno test imports it
type NameServer = { readonly ipAddr: string; readonly port?: number };

The server to ask, instead of the system's.

dns.ResolveDnsOptionstypeno test imports it
type ResolveDnsOptions = {
  /** The server to ask; the system's where not given. */
  readonly nameServer?: NameServer;
  /** Aborting it gives up (a `failed` error with code `ECANCELLED`). */
  readonly signal?: AbortSignal;
};

How to ask.

dns.resolveDnsfunctionno test imports it
function resolveDns<T extends RecordType>(name: string, type: T, options?: ResolveDnsOptions): Promise<Result<readonly RecordOf[T][], DnsError>>

The records of a type for a name, or why there are none.

RecordTypetypeno test imports it
type RecordType = "A" | "AAAA" | "CNAME" | "MX" | "NS" | "TXT" | "SRV";

The record types that can be asked for.

MxRecordtypeno test imports it
type MxRecord = { readonly preference: number; readonly exchange: string };

A mail exchanger.

SrvRecordtypeno test imports it
type SrvRecord = { readonly priority: number; readonly weight: number; readonly port: number; readonly target: string };

A service's host and port.

RecordOftypeno test imports it
type RecordOf = {
  readonly A: string;
  readonly AAAA: string;
  readonly CNAME: string;
  readonly NS: string;
  readonly MX: MxRecord;
  readonly TXT: readonly string[];
  readonly SRV: SrvRecord;
};

The shape of one record of each type: an address or a name as a string, TXT as its strings (join them for the whole text).

DnsErrortypeno test imports it
type DnsError =
  | { readonly kind: "not-found"; readonly name: string }
  | { readonly kind: "no-data"; readonly name: string; readonly type: RecordType }
  | { readonly kind: "failed"; readonly name: string; readonly code: string; readonly message: string };

Why there is no answer: the name does not exist (NXDOMAIN), it has no record of that type, or the DNS could not be asked (code is ESERVFAIL, EREFUSED, EFORMERR, ENOTIMP or ERCODE<n> for the server's answer, ETIMEOUT, ECANCELLED, EBADRESP for an answer that cannot be read, EBADNAME, ENOSERVERS, or the host's error code, such as ECONNREFUSED).

NameServertypeno test imports it
type NameServer = { readonly ipAddr: string; readonly port?: number };

The server to ask, instead of the system's.

ResolveDnsOptionstypeno test imports it
type ResolveDnsOptions = {
  /** The server to ask; the system's where not given. */
  readonly nameServer?: NameServer;
  /** Aborting it gives up (a `failed` error with code `ECANCELLED`). */
  readonly signal?: AbortSignal;
};

How to ask.

resolveDnsfunction
function resolveDns<T extends RecordType>(name: string, type: T, options?: ResolveDnsOptions): Promise<Result<readonly RecordOf[T][], DnsError>>

The records of a type for a name, or why there are none.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.