resolv-conf 1.0.2 → 2.0.0

package/LICENSE.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2020 Joe Hildebrand
+Copyright (c) 2020-2024 Joe Hildebrand
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

package/README.md

@@ -1,8 +1,13 @@
 # Parse resolv.conf
 
-This repo uses the Linux documentation for [resolv.conf(5)](https://man7.org/linux/man-pages/man5/resolv.conf.5.html) to parse the configuration for DNS resolution on your system.  Windows uses a different approach, so the best you can do is likely the Node built-in [`dns.getServers()`](https://nodejs.org/api/dns.html#dns_dns_getservers).
+This repo uses the Linux documentation for
+[resolv.conf(5)](https://man7.org/linux/man-pages/man5/resolv.conf.5.html) to
+parse the configuration for DNS resolution on your system.  Windows uses a
+different approach, so the best you can do is likely the Node built-in
+[`dns.getServers()`](https://nodejs.org/api/dns.html#dns_dns_getservers).
 
-Note that the defaults and environment variables listed in the docs were also implemented.
+Note that the defaults and environment variables listed in the docs were also
+implemented.
 
 ## Install
 
@@ -13,8 +18,8 @@ npm install resolv-conf
 ## Usage
 
 ```js
-const resolv = require('resolv-conf')
-await resolv.parseFile()  // filename is optional
+import {parseFile, parse} from 'resolv-conf';
+const config = await parseFile();  // filename is optional
 
 // returns:
 // {
@@ -26,21 +31,24 @@ await resolv.parseFile()  // filename is optional
 // }
 
 // if you already have text from the file:
-resolv.parse(text)
+const config2 = parse(text);
 ```
 
-## Errors
+## Options
 
-Unrecoverable parse errors will throw an exception with `location`, `expected`, `found`, and `message` properties.
+Options will have dashes turned into underscores.  For example, `no-aaaa` will be
+available as `config.options.no_aaaa`.
 
-Recoverable errors (e.g. invalid IP addresses) will show up in the result object in the `errors` property, and valid defaults will be chosen for that option if need be.
+## Errors
 
-## Other libraries
+Unrecoverable parse errors will throw an exception with `location`,
+`expected`, `found`, and `message` properties.
 
-I looked at [resolv](https://github.com/fmahnke/resolv), but didn't feel like it was close enough to what I needed, it didn't have tests, etc.  Since the project hadn't been touched in several years, I figured it was easier to start over.  (Sorry, @fmahnke; let me know if that was a bad assumption and I'm happy to collaborate.)
+Recoverable errors (e.g. invalid IP addresses) will show up in the result
+object in the `errors` property, and valid defaults will be chosen for that
+option if need be.
 
 ## Status
 
-[![Tests](https://github.com/hildjj/resolv-conf/workflows/Tests/badge.svg)](https://github.com/hildjj/resolv-conf/actions?query=workflow%3ATests)
-[![Coverage Status](https://coveralls.io/repos/github/hildjj/resolv-conf/badge.svg?branch=master)](https://coveralls.io/github/hildjj/resolv-conf?branch=master)
-[![RunKit](https://img.shields.io/static/v1?label=Try%20it%20online%20on&message=RunKit&color=f55fa6&logo=runkit)](https://runkit.com/hildjj/5feaeb406e1b55001a1211f9)
+[![Tests](https://github.com/hildjj/resolv-conf/actions/workflows/node.js.yml/badge.svg)](https://github.com/hildjj/resolv-conf/actions/workflows/node.js.yml)
+[![codecov](https://codecov.io/gh/hildjj/resolv-conf/graph/badge.svg?token=Y4Z2ALWXAA)](https://codecov.io/gh/hildjj/resolv-conf)

package/lib/defaults.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Add default parameters to a parsed resolv.conf file.
+ *
+ * @param {GatheredLines} parsed Just what was in the file.
+ * @param {Record<string, number>} port The ports detected in the file.
+ * @returns {ResolvResults} With the defaults and environment variables filled
+ *   in.
+ */
+export function resolv(parsed: GatheredLines, port: Record<string, number>): ResolvResults;
+/**
+ * Convert a string to a number, if possible.
+ *
+ * @param {string | null} val
+ * @returns {boolean | string | number}
+ */
+export function maybeNum(val: string | null): boolean | string | number;
+/**
+ *
+ * @param {object[]} list
+ * @returns {GatheredLines}
+ */
+export function gather(list: object[]): GatheredLines;
+/**
+ * The v4/v6 address and netmask.
+ */
+export type AddrMask = {
+    /**
+     * IP address.
+     */
+    address: string;
+    /**
+     * Netmask for the address.
+     */
+    mask?: string | undefined;
+};
+/**
+ * Options parsed from resolv.conf.  Note that option names have dashes ('-')
+ * converted to underscores ('_') for easier use in JS.
+ */
+export type KnownResolvOptions = {
+    /**
+     * Sets RES_DEBUG.
+     */
+    debug?: boolean | undefined;
+    /**
+     * Sets a threshold for the number of dots which must
+     * appear in a name given to query before an initial absolute query will be
+     * made.  The default for n is 1, meaning that if there are any dots in a
+     * name, the name will be tried first as an absolute name before any search
+     * list elements are appended to it.  The value for this option is silently
+     * capped to 15.
+     */
+    ndots: number;
+    /**
+     * Sets the amount of time the resolver will wait for
+     * a response from a remote name server before retrying the query via a
+     * different name server. This may not be the total time taken by any
+     * resolver API call and there is no guarantee that a single resolver API
+     * call maps to a single timeout. Measured in seconds, the default is
+     * RES_TIMEOUT (currently 5).  The value for this option is silently capped
+     * to 30.
+     */
+    timeout?: number | undefined;
+    /**
+     * Sets the number of times the resolver will send a
+     * query to its name servers before giving up and returning an error to the
+     * calling application.  The default is RES_DFLRETRY (currently 2).  The
+     * value for this option is silently capped to 5.
+     */
+    attempts?: number | undefined;
+    /**
+     * Sets RES_ROTATE, which causes round-robin
+     * selection of name servers from among those listed.  This has the effect
+     * of spreading the query load among all listed servers, rather than having
+     * all clients try the first listed server first every time.
+     */
+    rotate?: boolean | undefined;
+    /**
+     * Sets RES_NOAAAA in _res.options, which suppresses
+     * AAAA queries made by the stub resolver, including AAAA lookups triggered
+     * by NSS-based interfaces such as getaddrinfo(3).  Only DNS lookups are
+     * affected: IPv6 data in hosts(5) is still used, getaddrinfo(3) with
+     * AI_PASSIVE will still produce IPv6 addresses, and configured IPv6 name
+     * servers are still used. To produce correct Name Error (NXDOMAIN) results,
+     * AAAA queries are translated to A queries.  This option is intended
+     * preliminary for diagnostic purposes, to rule out that AAAA DNS queries
+     * have adverse impact.  It is incompatible with EDNS0 usage and DNSSEC
+     * validation by applications.
+     */
+    no_aaaa?: boolean | undefined;
+    /**
+     * Sets RES_NOCHECKNAME, which disables the
+     * modern BIND checking of incoming hostnames and mail names for invalid
+     * characters such as underscore (_), non-ASCII, or control characters.
+     */
+    no_check_names?: boolean | undefined;
+    /**
+     * Sets RES_USE_INET6.  This has the effect of trying
+     * an AAAA query before an A query inside the gethostbyname(3) function, and
+     * of mapping IPv4 responses in IPv6 "tunneled form" if no AAAA records are
+     * found but an A record set exists. Since glibc 2.25, this option is
+     * deprecated; applications should use getaddrinfo(3), rather than
+     * gethostbyname(3).
+     */
+    inet6?: boolean | undefined;
+    /**
+     * Sets RES_USE_EDNS0.  This enables support for the
+     * DNS extensions described in RFC 2671.
+     */
+    edns0?: boolean | undefined;
+    /**
+     * Sets RES_SNGLKUP.  By default, glibc
+     * performs IPv4 and IPv6 lookups in parallel since glibc 2.9.  Some
+     * appliance DNS servers cannot handle these queries properly and make the
+     * requests time out.  This option disables the behavior and makes glibc
+     * perform the IPv6 and IPv4 requests sequentially (at the cost of some
+     * slowdown of the resolving process).
+     */
+    single_request?: boolean | undefined;
+    /**
+     * Sets RES_SNGLKUPREOP.  The resolver
+     * uses the same socket for the A and AAAA requests. Some hardware
+     * mistakenly sends back only one reply. When that happens the client system
+     * will sit and wait for the second reply.  Turning this option on changes
+     * this behavior so that if two requests from the same port are not handled
+     * correctly it will close the socket and open a new one before sending the
+     * second request.
+     */
+    single_request_reopen?: boolean | undefined;
+    /**
+     * Sets RES_NOTLDQUERY.  This option causes
+     * res_nsearch() to not attempt to resolve an unqualified name as if it were
+     * a top level domain (TLD).  This option can cause problems if the site has
+     * ``localhost'' as a TLD rather than having localhost on one or more
+     * elements of the search list.  This option has no effect if neither
+     * RES_DEFNAMES or RES_DNSRCH is set.
+     */
+    no_tld_query?: boolean | undefined;
+    /**
+     * Sets RES_USEVC.  This option forces the use of TCP
+     * for DNS resolutions.
+     */
+    use_vc?: boolean | undefined;
+    /**
+     * Sets RES_NORELOAD in _res.options.  This option
+     * disables automatic reloading of a changed configuration file.
+     */
+    no_reload?: boolean | undefined;
+    /**
+     * Sets RES_TRUSTAD in _res.options.  This option
+     * controls the AD bit behavior of the stub resolver. If a validating
+     * resolver sets the AD bit in a response, it indicates that the data in the
+     * response was verified according to the DNSSEC protocol.  In order to rely
+     * on the AD bit, the local system has to trust both the DNSSEC- validating
+     * resolver and the network path to it, which is why an explicit opt-in is
+     * required.  If the trust-ad option is active, the stub resolver sets the
+     * AD bit in outgoing DNS queries (to enable AD bit support), and preserves
+     * the AD bit in responses.  Without this option, the AD bit is not set in
+     * queries, and it is always removed from responses before they are returned
+     * to the application.  This means that applications can trust the AD bit in
+     * responses if the trust-ad option has been set correctly.
+     */
+    trust_ad?: boolean | undefined;
+    /**
+     * Do not require IP source address on the reply
+     * packet to be equal to the server's address.  BSD only.
+     */
+    insecure1?: boolean | undefined;
+    /**
+     * Do not check if the query section of the reply
+     * packet is equal to that of the query packet. For testing purposes only.
+     * BSD only.
+     */
+    insecure2?: boolean | undefined;
+    /**
+     * Forces the use of TCP for queries. Normal behaviour
+     * is to query via UDP but fall back to TCP on failure.  BSD only.
+     */
+    tcp?: boolean | undefined;
+};
+export type ResolvOptions = KnownResolvOptions & Record<string, any>;
+export type ResolvError = {
+    text: string;
+    location: import('peggy').LocationRange;
+};
+export type GatheredLines = {
+    /**
+     * The nameserver IP addresses to try,
+     * in order.
+     */
+    nameserver?: string[] | undefined;
+    /**
+     * Ports to use when talking to each
+     * nameserver.  The default is in the "" key.  A key will be added for each
+     * nameserver.
+     */
+    port?: Record<string, number> | undefined;
+    /**
+     * The domains to search if the target
+     * doesn't have at least options.ndots dots in it.
+     */
+    search?: string[] | undefined;
+    /**
+     * Sort the results according to these
+     * addresses and netmasks.
+     */
+    sortlist?: AddrMask[] | undefined;
+    /**
+     * Various options.  Things
+     * that can be converted to numbers will have been, and things that are
+     * flags will have the value true.
+     */
+    options?: [name: string, value: any][] | undefined;
+    /**
+     * Errors encountered while parsing the
+     * file, extracted here rather than causing overall parsing to fail.
+     */
+    errors?: ResolvError[] | undefined;
+    /**
+     * Specifies the total amount of time allowed for
+     * a name resolution.  This time interval is divided by the number of
+     * nameservers and the number of retries allowed for each nameserver. Only
+     * on MacOS.
+     */
+    timeout?: number | undefined;
+    /**
+     * Only required for those clients that
+     * share a domain name with other clients.  Queries will be sent to these
+     * clients in order by ascending search_order value.  For example, this
+     * allows two clients for the ".local" domain, which is used by Apple's
+     * multicast DNS, but which may also be used at some sites as private DNS
+     * domain name.  Only on MacOS.
+     */
+    search_order?: number | undefined;
+    /**
+     * Specify which type of Internet
+     * protocol family to prefer, if a host is reachable using different address
+     * families. By default IPv4 addresses are queried first, and then IPv6
+     * addresses.  Only on BSD.
+     */
+    family?: ("inet4" | "inet6")[] | undefined;
+    /**
+     * This keyword is used by the
+     * library routines gethostbyname(3) and gethostbyaddr(3). It specifies
+     * which databases should be searched, and the order to do so.  Only on BSD.
+     */
+    lookup?: ("file" | "yp" | "bind")[] | undefined;
+};
+/**
+ * The results from parsing a resolv.conf file.
+ */
+export type ResolvResults = {
+    /**
+     * The nameserver IP addresses to try, in
+     * order.
+     */
+    nameserver: Array<string>;
+    /**
+     * Ports to use when talking to each
+     * nameserver.  The default is in the "" key.  A key will be added for each
+     * nameserver.
+     */
+    port: Record<string, number>;
+    /**
+     * The domains to search if the target
+     * doesn't have at least options.ndots dots in it.
+     */
+    search: Array<string>;
+    /**
+     * Sort the results according to these
+     * addresses and netmasks.
+     */
+    sortlist?: AddrMask[] | undefined;
+    /**
+     * Specifies the total amount of time allowed for
+     * a name resolution.  This time interval is divided by the number of
+     * nameservers and the number of retries allowed for each nameserver. Only
+     * on MacOS.
+     */
+    timeout?: number | undefined;
+    /**
+     * Only required for those clients that
+     * share a domain name with other clients.  Queries will be sent to these
+     * clients in order by ascending search_order value.  For example, this
+     * allows two clients for the ".local" domain, which is used by Apple's
+     * multicast DNS, but which may also be used at some sites as private DNS
+     * domain name.  Only on MacOS.
+     */
+    search_order?: number | undefined;
+    /**
+     * This keyword is used by the
+     * library routines gethostbyname(3) and gethostbyaddr(3). It specifies
+     * which databases should be searched, and the order to do so.  Only on BSD.
+     */
+    lookup?: ("file" | "yp" | "bind")[] | undefined;
+    /**
+     * Specify which type of Internet
+     * protocol family to prefer, if a host is reachable using different address
+     * families. By default IPv4 addresses are queried first, and then IPv6
+     * addresses.  Only on BSD.
+     */
+    family?: ("inet4" | "inet6")[] | undefined;
+    /**
+     * Various options.  Things that can be
+     * converted to numbers will have been, and things that are flags will have
+     * the value true.
+     */
+    options: ResolvOptions;
+    /**
+     * Errors encountered while parsing the
+     * file, extracted here rather than causing overall parsing to fail.
+     */
+    errors?: ResolvError[] | undefined;
+};