tangerine 1.0.4 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -24
- package/index.js +31 -20
- package/package.json +11 -4
package/README.md
CHANGED
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
* [ECMAScript modules (ESM)](#ecmascript-modules-esm)
|
|
34
34
|
* [CommonJS (CJS)](#commonjs-cjs)
|
|
35
35
|
* [API](#api)
|
|
36
|
-
* [`new Tangerine(options)`](#new-tangerineoptions)
|
|
36
|
+
* [`new Tangerine(options[, request])`](#new-tangerineoptions-request)
|
|
37
37
|
* [`tangerine.cancel()`](#tangerinecancel)
|
|
38
38
|
* [`tangerine.getServers()`](#tangerinegetservers)
|
|
39
39
|
* [`tangerine.lookup(hostname[, options])`](#tangerinelookuphostname-options)
|
|
@@ -66,7 +66,7 @@
|
|
|
66
66
|
## Install
|
|
67
67
|
|
|
68
68
|
```sh
|
|
69
|
-
npm install tangerine
|
|
69
|
+
npm install tangerine undici
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
```diff
|
|
@@ -195,8 +195,36 @@ tangerine.resolve('forwardemail.net', 'A').then(console.log);
|
|
|
195
195
|
|
|
196
196
|
## API
|
|
197
197
|
|
|
198
|
-
### `new Tangerine(options)`
|
|
198
|
+
### `new Tangerine(options[, request])`
|
|
199
199
|
|
|
200
|
+
* The `request` argument is a `Function` that defaults to [undici.request](https://undici.nodejs.org/#/?id=undicirequesturl-options-promise).
|
|
201
|
+
* This is an HTTP library request async or Promise returning function to be used for making requests.
|
|
202
|
+
|
|
203
|
+
* You could alternatively use [got](https://github.com/sindresorhus/got) or any other HTTP library of your choice that accepts `fn(url, options)`. However, we suggest to stick with the default of `undici` due to these [benchmark tests](http-library-benchmarks).
|
|
204
|
+
|
|
205
|
+
```js
|
|
206
|
+
const tangerine = new Tangerine(
|
|
207
|
+
{
|
|
208
|
+
requestOptions: {
|
|
209
|
+
responseType: 'buffer',
|
|
210
|
+
decompress: false,
|
|
211
|
+
retry: {
|
|
212
|
+
limit: 0
|
|
213
|
+
}
|
|
214
|
+
},
|
|
215
|
+
requestTimeout: (ms) => ({ timeout: { request: ms } })
|
|
216
|
+
},
|
|
217
|
+
got
|
|
218
|
+
);
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
* It should return an object with `body`, `headers`, and either a `status` or `statusCode` property.
|
|
222
|
+
|
|
223
|
+
* The `body` property returned should be either a `Buffer` or `Stream`.
|
|
224
|
+
|
|
225
|
+
* Specify default request options based off the library under `requestOptions` below
|
|
226
|
+
|
|
227
|
+
* See `requestTimeout` function below, as it is required to be set properly if you are using a custom HTTP library function.
|
|
200
228
|
* Instance methods of [dns.promises.Resolver](https://nodejs.org/api/dns.html) are mirrored to :tangerine: Tangerine.
|
|
201
229
|
* Resolver methods accept an optional `abortController` argument, which is an instance of [AbortController](https://developer.mozilla.org/en-US/docs/Web/API/AbortController). Note that :tangerine: Tangerine manages `AbortController` usage internally – so you most likely won't need to pass your own (see [index.js](https://github.com/forwardemail/tangerine/blob/main/index.js) for more insight).
|
|
202
230
|
* See the complete list of [Options](#options) below.
|
|
@@ -251,27 +279,28 @@ Tangerine supports a new `ecsSubnet` property in the `options` Object argument.
|
|
|
251
279
|
|
|
252
280
|
Similar to the `options` argument from `new dns.promises.Resolver(options)` invocation – :tangerine: Tangerine also has its own options with default `dns` behavior mirrored. See [index.js](https://github.com/forwardemail/tangerine/blob/main/index.js) for more insight into how these options work.
|
|
253
281
|
|
|
254
|
-
| Property | Type | Default Value
|
|
255
|
-
| ------------------------- | ---------------------- |
|
|
256
|
-
| `timeout` | `Number` | `5000`
|
|
257
|
-
| `tries` | `Number` | `4`
|
|
258
|
-
| `servers` | `Set` or `Array` | `new Set(['1.1.1.1', '1.0.0.1'])`
|
|
259
|
-
| `
|
|
260
|
-
| `
|
|
261
|
-
| `
|
|
262
|
-
| `
|
|
263
|
-
| `
|
|
264
|
-
| `
|
|
265
|
-
| `
|
|
266
|
-
| `
|
|
267
|
-
| `
|
|
268
|
-
| `
|
|
269
|
-
| `
|
|
270
|
-
| `
|
|
271
|
-
| `
|
|
272
|
-
| `
|
|
273
|
-
| `
|
|
274
|
-
| `
|
|
282
|
+
| Property | Type | Default Value | Description |
|
|
283
|
+
| ------------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
284
|
+
| `timeout` | `Number` | `5000` | Number of milliseconds for requests to timeout. |
|
|
285
|
+
| `tries` | `Number` | `4` | Number of tries per `server` in `servers` to attempt. |
|
|
286
|
+
| `servers` | `Set` or `Array` | `new Set(['1.1.1.1', '1.0.0.1'])` | A Set or Array of [RFC 5952](https://tools.ietf.org/html/rfc5952#section-6) formatted addresses for DNS queries (matches default Node.js dns module behavior). Duplicates will be removed as this is converted to a `Set` internally. Defaults to Cloudflare's of `1.1.1.1` and `1.0.0.1`. If an `Array` is passed, then it will be converted to a `Set`. |
|
|
287
|
+
| `requestOptions` | `Object` | Defaults to an Object with `requestOptions.method` and `requestOptions.headers` properties and values below | Default options to pass to [undici](https://github.com/nodejs/undici) (or your custom HTTP library function passed as `request`). |
|
|
288
|
+
| `requestOptions.method` | `String` | Defaults to `"GET"` (must be either `"GET"` or `"POST"`, case-insensitive depending on library you use). | Default HTTP method to use for DNS over HTTP ("DoH") requests. |
|
|
289
|
+
| `requestOptions.headers` | `Object` | Defaults to `{ 'content-type': 'application/dns-message', 'user-agent': pkg.name + "/" + pkg.version, accept: 'application/dns-message', bodyTimeout: timeout }`. | Default HTTP headers to use for DNS over HTTP ("DoH") requests. |
|
|
290
|
+
| `requestTimeout` | `Function` | Defaults to `(ms) => ({ bodyTimeout })` for setting undici timeout properly. | This function accepts an argument `ms` which is the number of milliseconds to wait for the request to timeout (since we use a back-off strategy that mirrors the Node.js DNS module). This function is required to be passed and customized if you are using a custom HTTP library. If you're using a custom HTTP library such as `got`, you'd set this to `requestTimeout: (ms) => ({ timeout: { request: ms } })` |
|
|
291
|
+
| `protocol` | `String` | Defaults to `"https"`. | Default HTTP protocol to use for DNS over HTTPS ("DoH") requests. |
|
|
292
|
+
| `dnsOrder` | `String` | Defaults to `"verbatim"` for Node.js v17.0.0+ and `"ipv4first"` for older versions. | Sets the default result order of `lookup` invocations (see [dns.setDefaultResultOrder](https://nodejs.org/api/dns.html#dnssetdefaultresultorderorder) for more insight). |
|
|
293
|
+
| `logger` | `Object` | `false` | This is the default logger. We recommend using [Cabin](https://github.com/cabinjs) instead of using `console` as your default logger. Set this value to `false` to disable logging entirely (uses noop function). |
|
|
294
|
+
| `id` | `Number` or `Function` | `0` | Default `id` to be passed for DNS packet creation. This could alternatively be a synchronous or asynchronous function that returns a `Number` (e.g. `id: () => Tangerine.getRandomInt(1, 65534)`). |
|
|
295
|
+
| `concurrency` | `Number` | `os.cpus().length` | Default concurrency to use for `resolveAny` lookup via [p-map](https://github.com/sindresorhus/p-map). The default value is the number of CPU's available to the system using the Node.js `os` module [os.cpus()](https://nodejs.org/api/os.html#oscpus) method. |
|
|
296
|
+
| `ipv4` | `String` | `"0.0.0.0"` | Default IPv4 address to use for HTTP agent `localAddress` if DNS `server` was an IPv4 address. |
|
|
297
|
+
| `ipv6` | `String` | `"::0"` | Default IPv6 address to use for HTTP agent `localAddress` if DNS `server` was an IPv6 address. |
|
|
298
|
+
| `ipv4Port` | `Number` | `undefined` | Default port to use for HTTP agent `localPort` if DNS `server` was an IPv4 address. |
|
|
299
|
+
| `ipv6Port` | `Number` | `undefined` | Default port to use for HTTP agent `localPort` if DNS `server` was an IPv6 address. |
|
|
300
|
+
| `cache` | `Map` or `Boolean` | `new Map()` | Set this to `false` in order to disable caching. Default `Map` instance to use for caching. Entries are by type, e.g. `map.set('TXT', new Keyv({})`). If cache set values are not provided, then they will default to a new instance of `Keyv`. See cache setup and usage in [index.js](https://github.com/forwardemail/tangerine/blob/main/index.js) for more insight. You can iterate over `Tangerine.TYPES` if necessary to create a similar cache setup. |
|
|
301
|
+
| `returnHTTPErrors` | `Boolean` | `false` | Whether to return HTTP errors instead of mapping them to corresponding DNS errors. |
|
|
302
|
+
| `smartRotate` | `Boolean` | `true` | Whether to do smart server rotation if servers fail. |
|
|
303
|
+
| `defaultHTTPErrorMessage` | `String` | `"Unsuccessful HTTP response"` | Default fallback message if `statusCode` returned from HTTP request was not found in [http.STATUS_CODES](https://nodejs.org/api/http.html#httpstatus_codes). |
|
|
275
304
|
|
|
276
305
|
|
|
277
306
|
## Debugging
|
package/index.js
CHANGED
|
@@ -12,12 +12,10 @@ const getStream = require('get-stream');
|
|
|
12
12
|
const ipaddr = require('ipaddr.js');
|
|
13
13
|
const mergeOptions = require('merge-options');
|
|
14
14
|
const pMap = require('p-map');
|
|
15
|
-
const pTimeout = require('p-timeout');
|
|
16
15
|
const pWaitFor = require('p-wait-for');
|
|
17
16
|
const packet = require('dns-packet');
|
|
18
17
|
const semver = require('semver');
|
|
19
18
|
const { getService } = require('port-numbers');
|
|
20
|
-
const { request } = require('undici');
|
|
21
19
|
|
|
22
20
|
const pkg = require('./package.json');
|
|
23
21
|
|
|
@@ -215,7 +213,7 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
215
213
|
return err;
|
|
216
214
|
}
|
|
217
215
|
|
|
218
|
-
constructor(options = {}) {
|
|
216
|
+
constructor(options = {}, request = require('undici').request) {
|
|
219
217
|
const timeout =
|
|
220
218
|
options.timeout && options.timeout !== -1 ? options.timeout : 5000;
|
|
221
219
|
const tries = options.tries || 4;
|
|
@@ -225,6 +223,13 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
225
223
|
tries
|
|
226
224
|
});
|
|
227
225
|
|
|
226
|
+
if (typeof request !== 'function')
|
|
227
|
+
throw new Error(
|
|
228
|
+
'Request option must be a function (e.g. `undici.request` or `got`)'
|
|
229
|
+
);
|
|
230
|
+
|
|
231
|
+
this.request = request;
|
|
232
|
+
|
|
228
233
|
this.options = mergeOptions(
|
|
229
234
|
{
|
|
230
235
|
// <https://github.com/nodejs/node/issues/33353#issuecomment-627259827>
|
|
@@ -238,7 +243,7 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
238
243
|
// dns servers will optionally retry in series
|
|
239
244
|
// and servers that error will get shifted to the end of list
|
|
240
245
|
servers: new Set(['1.1.1.1', '1.0.0.1']),
|
|
241
|
-
|
|
246
|
+
requestOptions: {
|
|
242
247
|
method: 'GET',
|
|
243
248
|
headers: {
|
|
244
249
|
'content-type': 'application/dns-message',
|
|
@@ -246,6 +251,7 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
246
251
|
accept: 'application/dns-message'
|
|
247
252
|
}
|
|
248
253
|
},
|
|
254
|
+
requestTimeout: (ms) => ({ bodyTimeout: ms }),
|
|
249
255
|
//
|
|
250
256
|
// NOTE: we set the default to "get" since it is faster from `benchmark` results
|
|
251
257
|
//
|
|
@@ -291,6 +297,14 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
291
297
|
if (!Number.isFinite(this.options.tries) || this.options.tries < 1)
|
|
292
298
|
throw new Error('Tries must be >= 1');
|
|
293
299
|
|
|
300
|
+
// request option method must be either GET or POST
|
|
301
|
+
if (
|
|
302
|
+
!['get', 'post'].includes(
|
|
303
|
+
this.options.requestOptions.method.toLowerCase()
|
|
304
|
+
)
|
|
305
|
+
)
|
|
306
|
+
throw new Error('Request options method must be either GET or POST');
|
|
307
|
+
|
|
294
308
|
// perform validation by re-using `setServers` method
|
|
295
309
|
this.setServers([...this.options.servers]);
|
|
296
310
|
|
|
@@ -725,12 +739,7 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
725
739
|
// was too confusing and the documentation was lacking, misleading, or incredibly complex
|
|
726
740
|
// <https://github.com/sindresorhus/got/issues/2226>
|
|
727
741
|
//
|
|
728
|
-
async #request(
|
|
729
|
-
pkt,
|
|
730
|
-
server,
|
|
731
|
-
abortController,
|
|
732
|
-
requestTimeout = this.options.timeout
|
|
733
|
-
) {
|
|
742
|
+
async #request(pkt, server, abortController, timeout = this.options.timeout) {
|
|
734
743
|
// safeguard in case aborted
|
|
735
744
|
if (abortController.signal.aborted) return;
|
|
736
745
|
|
|
@@ -746,25 +755,24 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
746
755
|
}
|
|
747
756
|
|
|
748
757
|
const options = {
|
|
749
|
-
|
|
750
|
-
...this.options.
|
|
758
|
+
...this.options.requestOptions,
|
|
759
|
+
...this.options.requestTimeout(timeout), // returns `{ bodyTimeout: requestTimeout }`
|
|
760
|
+
signal: abortController.signal
|
|
751
761
|
};
|
|
752
762
|
|
|
753
763
|
if (localAddress !== '0.0.0.0') options.localAddress = localAddress;
|
|
754
764
|
if (localPort) options.localPort = localPort;
|
|
755
765
|
|
|
756
766
|
// <https://github.com/hildjj/dohdec/blob/43564118c40f2127af871bdb4d40f615409d4b9c/pkg/dohdec/lib/doh.js#L117-L120>
|
|
757
|
-
if (this.options.
|
|
767
|
+
if (this.options.requestOptions.method.toLowerCase() === 'get') {
|
|
758
768
|
if (!dohdec) await pWaitFor(() => Boolean(dohdec));
|
|
759
769
|
url += `?dns=${dohdec.DNSoverHTTPS.base64urlEncode(pkt)}`;
|
|
760
770
|
} else {
|
|
761
771
|
options.body = pkt;
|
|
762
772
|
}
|
|
763
773
|
|
|
764
|
-
debug('request', { url, options
|
|
765
|
-
const response = await
|
|
766
|
-
signal: abortController.signal
|
|
767
|
-
});
|
|
774
|
+
debug('request', { url, options });
|
|
775
|
+
const response = await this.request(url, options);
|
|
768
776
|
return response;
|
|
769
777
|
}
|
|
770
778
|
|
|
@@ -807,13 +815,16 @@ class Tangerine extends dns.promises.Resolver {
|
|
|
807
815
|
// if aborted signal then returns early
|
|
808
816
|
// eslint-disable-next-line max-depth
|
|
809
817
|
if (response) {
|
|
810
|
-
const {
|
|
818
|
+
const { body, headers } = response;
|
|
819
|
+
const statusCode = response.status || response.statusCode;
|
|
811
820
|
debug('response', { statusCode, headers });
|
|
812
821
|
|
|
813
822
|
// eslint-disable-next-line max-depth
|
|
814
823
|
if (body && statusCode >= 200 && statusCode < 300) {
|
|
815
|
-
|
|
816
|
-
|
|
824
|
+
buffer = Buffer.isBuffer(body)
|
|
825
|
+
? body
|
|
826
|
+
: // eslint-disable-next-line no-await-in-loop
|
|
827
|
+
await getStream.buffer(body);
|
|
817
828
|
// eslint-disable-next-line max-depth
|
|
818
829
|
if (!abortController.signal.aborted) abortController.abort();
|
|
819
830
|
break;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tangerine",
|
|
3
3
|
"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 via Keyv.",
|
|
4
|
-
"version": "1.0
|
|
4
|
+
"version": "1.2.0",
|
|
5
5
|
"author": "Forward Email (https://forwardemail.net)",
|
|
6
6
|
"bugs": {
|
|
7
7
|
"url": "https://github.com/forwardemail/tangerine/issues"
|
|
@@ -17,11 +17,9 @@
|
|
|
17
17
|
"keyv": "^4.5.2",
|
|
18
18
|
"merge-options": "3.0.4",
|
|
19
19
|
"p-map": "4",
|
|
20
|
-
"p-timeout": "4",
|
|
21
20
|
"p-wait-for": "3",
|
|
22
21
|
"port-numbers": "^6.0.1",
|
|
23
|
-
"semver": "^7.3.8"
|
|
24
|
-
"undici": "^5.20.0"
|
|
22
|
+
"semver": "^7.3.8"
|
|
25
23
|
},
|
|
26
24
|
"devDependencies": {
|
|
27
25
|
"@commitlint/cli": "^17.4.4",
|
|
@@ -47,6 +45,7 @@
|
|
|
47
45
|
"request": "^2.88.2",
|
|
48
46
|
"sort-keys": "4.2.0",
|
|
49
47
|
"superagent": "^8.0.9",
|
|
48
|
+
"undici": "^5.20.0",
|
|
50
49
|
"xo": "^0.53.1"
|
|
51
50
|
},
|
|
52
51
|
"engines": {
|
|
@@ -133,6 +132,14 @@
|
|
|
133
132
|
],
|
|
134
133
|
"license": "MIT",
|
|
135
134
|
"main": "index.js",
|
|
135
|
+
"peerDependencies": {
|
|
136
|
+
"undici": "*"
|
|
137
|
+
},
|
|
138
|
+
"peerDependenciesMeta": {
|
|
139
|
+
"undici": {
|
|
140
|
+
"optional": true
|
|
141
|
+
}
|
|
142
|
+
},
|
|
136
143
|
"publishConfig": {
|
|
137
144
|
"access": "public"
|
|
138
145
|
},
|