dns: add promisified dns module #21264

cjihrig · 2018-06-11T19:07:14Z

~~This is a work in progress attempt at a promisified DNS core module. I'm opening this early to see if people are generally interested in this approach.~~ ~~The entire API is not ported yet - mostly just missing lookup() and lookupService().~~

Some notes:

The new stuff is added to require('dns').promises, as similarly done in the fs API. Like in fs, they are lazy loaded and output an experimental warning.
There are currently no changes at the C++ layer because the DNS APIs come back to JavaScript to postprocess results before returning to user code.
~~This currently relies on process.binding('util').createPromise and friends, which are currently facing potential removal in another PR.~~
make test passed for me locally, so no regressions should exist in the callback based API.

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
tests and/or benchmarks are included
documentation is changed or added
commit message follows commit guidelines

nodejs-github-bot · 2018-06-11T19:07:15Z

@cjihrig build started: https://ci.nodejs.org/blue/organizations/jenkins/node-test-pull-request-lite-pipeline/detail/node-test-pull-request-lite-pipeline/42/pipeline

devsnek · 2018-06-11T19:44:31Z

ideally we shouldn't be using those promise utils, they can't be optimised by v8

also should be looped into the new module naming thing as this can't be used first-class by esm

cjihrig · 2018-06-11T21:26:30Z

ideally we shouldn't be using those promise utils, they can't be optimised by v8

OK, got rid of those.

addaleax

LGTM once tests and documentation are added :)

cjihrig · 2018-06-12T21:18:58Z

The full API has been ported, and docs+tests added.

addaleax

Can we add a sibling of the Resolver class, with Resolver.prototype.promises as its prototype?

cjihrig · 2018-06-12T23:30:38Z

CI run: https://ci.nodejs.org/job/node-test-pull-request/15424/

Can we add a sibling of the Resolver class, with Resolver.prototype.promises as its prototype?

Do you mean like class PromiseResolver extends Resolver.prototype.promises (although that name is horrible :-))?

addaleax · 2018-06-12T23:32:22Z

@cjihrig Yes, basically – I’d call it Resolver too, and put in on dns.promises.Resolver. :)

cjihrig · 2018-06-14T18:34:51Z

@addaleax I added a dns.promises.Resolver class. I decided to get rid of Resolver.prototype.promises since there is a better way to access the functionality now.

TimothyGu · 2018-06-15T03:35:42Z

lib/internal/dns/promises.js

+    req.hostname = hostname;
+    req.oncomplete = all ? onlookupall : onlookup;
+    req.resolve = resolve;
+    req.reject = reject;


Right now we seem to have two implicit "subclasses" of GetNameInfoReqWrap: one having a .callback property and is used for dns, while the other has .resolve and .reject properties. I would rather make this distinction explicit by having a GetAddrInfoPromiseReqWrap subclass that extends GetAddrInfoReqWrap.

Same for the other wrapper classes.

@TimothyGu I was aiming to avoid a lot of unnecessary duplicate code. The wraps behave exactly the same in the C++ layer.

@cjihrig Yeah I understand. What I'm trying to say is that you can have a JavaScript class that extends GetAddrInfoReqWrap. As long as its constructor calls super() properly it should work just fine. No duplication in C++ needed.

@TimothyGu It still seems a bit complex if we hang all the data (host, port, bindingName, etc.) onto a req wrap with C++ binding even though the C++ binding may not necessarily read those properties from the req wrap. The only property that matters to C++ should be wrap.oncomplete, so it may be cleaner if we create two JS classes, one for the callback and the other one for promises, each with a .handle (or a symbol property) pointing to those req wraps and add the data properties to the JS instances of those classes. Then the main difference between those two classes would just be how we call resolve/reject/callback(null, result)/callback(dnsException(...)) in handle.oncomplete. (That's basically what the two types of wraps do in the fs promises implementation although those are implemented in C++)

(It's a bit unfortunate that the resolves have a ChannelWrap that's not req wrap as _handle though)

On a second thought, it may not be feasible to separate the data properties to an outer object since we have been allowing users to retrieve them via the this bound to the callback...

EDIT: but we do not always bind the callback to the req wrap e.g. dns.lookup('127.0.0.1', function() { console.log(this) } gives you the global.

cjihrig · 2018-06-15T14:30:21Z

Green CI run: https://ci.nodejs.org/job/node-test-pull-request/15481/

targos · 2018-06-15T14:34:27Z

doc/api/dns.md

+-->
+
+Cancel all outstanding DNS queries made by this resolver. The corresponding
+callbacks will be called with an error with code `ECANCELLED`.


Should it say something like "the corresponding promises will be rejected with..."?

Good catch. Fixed.

vsemozhetbyt

Just some doc nits.

vsemozhetbyt · 2018-06-17T08:45:54Z

doc/api/dns.md

+that return `Promise` objects rather than using callbacks. The API is accessible
+via `require('dns').promises`.
+
+## Class: dnsPromises.Resolver


It seems this should be ### level, not ##, to reflect the hierarchy of not-promisified API.

vsemozhetbyt · 2018-06-17T08:46:12Z

doc/api/dns.md

+* [`resolver.resolveTxt()`][`dnsPromises.resolveTxt()`]
+* [`resolver.reverse()`][`dnsPromises.reverse()`]
+
+### resolver.cancel()


It seems this should be #### level, not ###, to reflect the hierarchy of not-promisified API.

doc/api/dns.md

+
+The following methods from the `dnsPromises` API are available:
+
+* [`resolver.getServers()`][`dnsPromises.getServers()`]


doc/api/dns.md

+The following methods from the `dnsPromises` API are available:
+
+* [`resolver.getServers()`][`dnsPromises.getServers()`]
+* [`resolver.setServers()`][`dnsPromises.setServers()`]


vsemozhetbyt · 2018-06-17T09:06:15Z

doc/api/dns.md

+-->
+
+Cancel all outstanding DNS queries made by this resolver. The corresponding
+`Promises` will be rejected with an error with code `ECANCELLED`.


`Promises` -> `Promise`s?

vsemozhetbyt · 2018-06-17T09:34:08Z

doc/api/dns.md

+    `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings,
+    with the TTL expressed in seconds.
+
+Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the


a IPv4 addresses -> IPv4 addresses

vsemozhetbyt · 2018-06-17T09:34:47Z

doc/api/dns.md

+    `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of
+    strings, with the TTL expressed in seconds.
+
+Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the


a IPv6 addresses -> IPv6 addresses

vsemozhetbyt · 2018-06-17T09:44:10Z

doc/api/dns.md

+treated separately.
+
+### dnsPromises.resolveAny(hostname)
+


Missing YAML.

vsemozhetbyt · 2018-06-17T09:46:59Z

doc/api/dns.md

+| `'A'` | `address`/`ttl` |
+| `'AAAA'` | `address`/`ttl` |
+| `'CNAME'` | `value` |
+| `'MX'` | Refer to [`dns.resolveMx()`][] |


[`dns. -> [`dnsPromises. in all table (with new bottom references)?

vsemozhetbyt · 2018-06-17T09:51:31Z

doc/api/dns.md

+Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an
+array of hostnames.
+
+On error, `err` is an [`Error`][] object, where `err.code` is


This note needs to be promisified)

joyeecheung

Code wise LGTM, regarding the internal structure we can refactor on top of this PR later.

joyeecheung · 2018-06-17T12:19:41Z

lib/internal/dns/promises.js

+'use strict';
+const {
+  bindDefaultResolver,
+  Resolver: Resolver_,


Can this be renamed to something like CallbackResolver or LegacyResolver to be more clear?

vsemozhetbyt · 2018-06-17T20:37:04Z

doc/api/dns.md

+
+Note that creating a new resolver uses the default server settings. Setting
+the servers used for a resolver using
+[`resolver.setServers()`][`dns.setServers()`] does not affect


Should this be [`resolver.setServers()`][`dnsPromises.setServers()`]?

vsemozhetbyt · 2018-06-17T20:48:49Z

doc/api/dns.md

@@ -659,6 +1104,22 @@ uses. For instance, _they do not use the configuration from `/etc/hosts`_.
 [`dns.resolveTxt()`]: #dns_dns_resolvetxt_hostname_callback
 [`dns.reverse()`]: #dns_dns_reverse_ip_callback
 [`dns.setServers()`]: #dns_dns_setservers_servers
+[`dnsPromises.getServers()`]: #dns_dnspromises_getservers
+[`dnsPromises.lookup()`]: #dns_dnspromises_lookup_hostname_options_callback


In all these hashes, _callback part needs to be deleted.

benjamingr · 2018-06-18T11:40:45Z

doc/api/dns.md

+resolver.setServers(['4.4.4.4']);
+
+// This request will use the server at 4.4.4.4, independent of global settings.
+resolver.resolve4('example.org').then((addresses) => {


Maybe show an example with async/await since according to polls that's what most users are doing?

benjamingr · 2018-06-18T11:41:22Z

doc/api/dns.md

+added: REPLACEME
+-->
+
+Cancel all outstanding DNS queries made by this resolver. The corresponding


This defacto introduces promise cancellation to Node.js - can we add a note to this that the API for cancellation may change?

Alternatively, we can remove it and revisit.

cancel(), getServers(), and setServers() don't technically use promises (or callbacks for that matter). They are just synchronous methods provided on the Resolver class that are included here too for completeness.

@cjihrig this is a promise cancellation API though since you are rejecting all promises with an error "from a distance".

I'd really prefer it if we took extra caution around it since we'll want one API for cancellation and ideally users can use the same one for say... promisified timers, fs and DNS.

Maybe we can avoid exposing this in the promise API, or rename it to something else?

I'm willing to remove it because it's a simple change. I don't agree with the change though, and I'm very -1 to renaming it.

Removing it until we have a more general strategy about cancellation with async functions SGTM. We can bring this up with TC39 at the next meeting if you'd like.

benjamingr · 2018-06-18T11:46:12Z

lib/internal/dns/promises.js

+  this.resolve(addresses);
+}
+
+function createLookupPromise(family, hostname, all, hints, verbatim) {


I would really prefer it if this method dind't do so much explicit construction:

async function createLookupPromise(family, hostname, all, hints, verbatim) { if (!hostname) { if (all) return []; else return { address: null, family: family === 6 ? 6 : 4 }; } const matchedFamily = isIP(hostname); if (matchedFamily !== 0) { const result = { address: hostname, family: matchedFamily } if(all) return [result]; return result; } return await new Promise((resolve, reject) => { const req = new GetAddrInfoReqWrap(); // ... req.resolve = resolve; } }

benjamingr

Not a huge fan of how the code is written and I think it can be simpler - but it looks correct and the effort and progress is really nice.

Left some comment and LGTMd the current code as experimental to iterate on :)

PR-URL: nodejs#21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Because reasons. PR-URL: nodejs#21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

cjihrig · 2018-06-20T17:48:57Z

Another CI run: https://ci.nodejs.org/job/node-test-pull-request/15536/ (AIX failures are unrelated, and I saw them on other CI runs today).

Landed in 7486c4d, with the cancel() removal in a77b30c (so it would make for an easy git revert).

PR-URL: #21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

Because reasons. PR-URL: #21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

benjamingr · 2018-06-21T07:52:12Z

Awesome, going to follow up with the nits from above :)

Notable changes: * build: * Node.js should now be about 60% faster to startup than the previous version, thanks to the use V8's code cache feature for core modules. [#21405](#21405) * dns: * An experimental promisified version of the dns module is now available. Give it a try with `require('dns').promises`. [#21264](#21264) * fs: * `fs.lchown` has been undeprecated now that libuv supports it. [#21498](#21498) * lib: * `Atomics.wake` is being renamed to `Atomics.notify` in the ECMAScript specification ([reference](tc39/ecma262#1220)). Since Node.js now has experimental support for worker threads, we are being proactive and added a `notify` alias, while emitting a warning if `wake` is used. [#21413](#21413) [#21518](#21518) * n-api: * Add API for asynchronous functions. [#17887](#17887) * util: * `util.inspect` is now able to return a result instead of throwing when the maximum call stack size is exceeded during inspection. [#20725](#20725) * vm: * Add `script.createCachedData()`. This API replaces the `produceCachedData` option of the `Script` constructor that is now deprecated. [#20300](#20300) * worker: * Support for relative paths has been added to the `Worker` constructor. Paths are interpreted relative to the current working directory. [#21407](#21407) PR-URL: #21629

Notable changes: * dns: * An experimental promisified version of the dns module is now available. Give it a try with `require('dns').promises`. [#21264](#21264) * fs: * `fs.lchown` has been undeprecated now that libuv supports it. [#21498](#21498) * lib: * `Atomics.wake` is being renamed to `Atomics.notify` in the ECMAScript specification ([reference](tc39/ecma262#1220)). Since Node.js now has experimental support for worker threads, we are being proactive and added a `notify` alias, while emitting a warning if `wake` is used. [#21413](#21413) [#21518](#21518) * n-api: * Add API for asynchronous functions. [#17887](#17887) * util: * `util.inspect` is now able to return a result instead of throwing when the maximum call stack size is exceeded during inspection. [#20725](#20725) * vm: * Add `script.createCachedData()`. This API replaces the `produceCachedData` option of the `Script` constructor that is now deprecated. [#20300](#20300) * worker: * Support for relative paths has been added to the `Worker` constructor. Paths are interpreted relative to the current working directory. [#21407](#21407) PR-URL: #21629

nodejs-github-bot added build Issues and PRs related to build files or the CI. dns Issues and PRs related to the dns subsystem. labels Jun 11, 2018

vsemozhetbyt added the promises Issues and PRs related to ECMAScript promises. label Jun 11, 2018

cjihrig force-pushed the dns branch from b45c873 to 8ccd3fd Compare June 11, 2018 21:25

addaleax approved these changes Jun 11, 2018

View reviewed changes

cjihrig force-pushed the dns branch 5 times, most recently from 26d49ec to 07345fe Compare June 12, 2018 21:16

cjihrig changed the title ~~WIP: add promisified dns module~~ dns: add promisified dns module Jun 12, 2018

Trott added the semver-minor PRs that contain new features and should be released in the next minor version. label Jun 12, 2018

addaleax reviewed Jun 12, 2018

View reviewed changes

jasnell approved these changes Jun 13, 2018

View reviewed changes

cjihrig force-pushed the dns branch from 07345fe to 776cab7 Compare June 14, 2018 18:33

TimothyGu reviewed Jun 15, 2018

View reviewed changes

cjihrig force-pushed the dns branch from 776cab7 to 72c072f Compare June 15, 2018 13:31

targos reviewed Jun 15, 2018

View reviewed changes

cjihrig force-pushed the dns branch from 72c072f to d017844 Compare June 15, 2018 14:37

vsemozhetbyt reviewed Jun 17, 2018

View reviewed changes

joyeecheung approved these changes Jun 17, 2018

View reviewed changes

cjihrig force-pushed the dns branch from d017844 to 16cbace Compare June 17, 2018 14:22

cjihrig force-pushed the dns branch from 16cbace to 72fed18 Compare June 17, 2018 14:31

vsemozhetbyt reviewed Jun 17, 2018

View reviewed changes

cjihrig force-pushed the dns branch from 72fed18 to 2a8c81d Compare June 18, 2018 00:35

benjamingr reviewed Jun 18, 2018

View reviewed changes

benjamingr approved these changes Jun 18, 2018

View reviewed changes

cjihrig force-pushed the dns branch from 2a8c81d to 577e3df Compare June 19, 2018 00:47

cjihrig added the tsc-review label Jun 19, 2018

cjihrig force-pushed the dns branch from 577e3df to bf3d96f Compare June 20, 2018 13:29

cjihrig added 2 commits June 20, 2018 13:35

dns: add promisified dns module

7486c4d

PR-URL: nodejs#21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

dns: remove Resolver#cancel() from promises API

a77b30c

Because reasons. PR-URL: nodejs#21264 Reviewed-By: Anna Henningsen <anna@addaleax.net> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com> Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>

cjihrig force-pushed the dns branch from bf3d96f to a77b30c Compare June 20, 2018 17:46

cjihrig merged commit a77b30c into nodejs:master Jun 20, 2018

cjihrig deleted the dns branch June 20, 2018 17:47

targos mentioned this pull request Jul 3, 2018

v10.6.0 proposal #21629

Merged

dshaw mentioned this pull request Jul 5, 2018

2018-07-06 User Feedback Team Meeting nodejs/user-feedback#76

Closed

maclover7 mentioned this pull request Jul 26, 2018

src,lib: rename FSReqWrap to FSReqCallback #21971

Closed

4 tasks

BridgeAR mentioned this pull request Oct 9, 2018

Summit Topic: Promises openjs-foundation/summit#119

Closed

rickyes mentioned this pull request Apr 27, 2020

dns.promises.Resolver does not have a .cancel() method #33091

Closed


		The following methods from the `dnsPromises` API are available:

		* [`resolver.getServers()`][`dnsPromises.getServers()`]

		treated separately.

		### dnsPromises.resolveAny(hostname)

dns: add promisified dns module #21264

dns: add promisified dns module #21264

Conversation

cjihrig commented Jun 11, 2018 • edited Loading

Checklist

nodejs-github-bot commented Jun 11, 2018

devsnek commented Jun 11, 2018 • edited Loading

cjihrig commented Jun 11, 2018

addaleax left a comment

Choose a reason for hiding this comment

cjihrig commented Jun 12, 2018

addaleax left a comment

Choose a reason for hiding this comment

cjihrig commented Jun 12, 2018

addaleax commented Jun 12, 2018

cjihrig commented Jun 14, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

TimothyGu Jun 15, 2018 • edited Loading

Choose a reason for hiding this comment

joyeecheung Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

joyeecheung Jun 16, 2018 • edited Loading

Choose a reason for hiding this comment

cjihrig commented Jun 15, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vsemozhetbyt left a comment

Choose a reason for hiding this comment

vsemozhetbyt Jun 17, 2018 • edited Loading

Choose a reason for hiding this comment

vsemozhetbyt Jun 17, 2018 • edited Loading

Choose a reason for hiding this comment

This comment was marked as resolved.

This comment was marked as resolved.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung left a comment

Choose a reason for hiding this comment

joyeecheung Jun 17, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

This comment was marked as off-topic.

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

benjamingr left a comment

Choose a reason for hiding this comment

cjihrig commented Jun 20, 2018

benjamingr commented Jun 21, 2018

cjihrig commented Jun 11, 2018 •

edited

Loading

devsnek commented Jun 11, 2018 •

edited

Loading

TimothyGu Jun 15, 2018 •

edited

Loading

joyeecheung Jun 16, 2018 •

edited

Loading

joyeecheung Jun 16, 2018 •

edited

Loading

vsemozhetbyt Jun 17, 2018 •

edited

Loading

vsemozhetbyt Jun 17, 2018 •

edited

Loading

joyeecheung Jun 17, 2018 •

edited

Loading