doc: improve dns module's documentation

[misterdjules]

Make the difference between dns.lookup and other functions even clearer.

[chrisdickinson]

It might be good to preface this sentence with something like "Though the call will be asynchronous from JavaScript's perspective, it is implemented internally [...]"

[chrisdickinson]

This LGTM.

[saghul]

I would just say it's a wrapper around getaddrinfo, there is no need to hide it :-)

[misterdjules]

@saghul This information is present in the "Implementation considerations" section below, do you think it should be mentioned here instead?

[saghul]

Overall I think it should be clear from the start that dns.lookup == getaddrinfo, IMHO it would simplify the docs.

[sam-github]

I agree. I knew there were two functions, one calling getaddrinfo in the thread pool, the other doing direct async dns via c-ares, and last time I used the dns module directly I had to spend a few minutes sifting through the documentation to figure out which of lookup() and resolve() was which... I kindof lament that the one that calls getaddrinfo isn't dns.getaddrinfo().

[misterdjules]

@saghul I agree with you, but my original concern was that by mentioning that dns.lookup == getaddrinfo in the introduction we would expose too much of the implementation's details to everyone right from the start. For instance, if we wanted to be precise for Windows users, we would need to mention GetAddrInfoW in addition to getaddrinfo (although they probably behave in a very similar way).

Instead, I thought that describing the general semantics and the concept of dns.lookup in the introduction would be sufficient, and would work for any implementation, even if these implementations change in the future. People interested in the implementation details could still consult the section that is reserved for that.

@sam-github The goal of this PR is exactly to address the problem you mentioned.

[sam-github]

I'm probably completely biased, as somebody who has implemented DNS protocols, so take this with a grain of salt... but I think a few words like the following is sufficient information for people who know something about addr resolution, and there is a risk that somebody who doesn't is unlikely to know anything about /etc/hosts or nsswitch.conf, and to be just puzzled by your additional explanation, even though it is quite accurate and detailed.

• lookup calls the system resolver (via getaddrinfo) in the threadpool, so guarantees compatibility with other application's lookups, at the price of not being possible to parallelize more than the thread pool (link to uv threadpool docs... and wish there were node threadpool docs).
• resolve uses a full async and parallel DNS resolver outside of the node threadpool, so is suitable for much higher parallelism, but can only find names resolvable directly via DNS.

[misterdjules]

@sam-github @saghul Thank you very much for taking the time to review this proposal. I'm going to update it by taking your great suggestions into account and I'll let you know when I'm done.

@sam-github I like how you summed up the changes. I think it's definitely clearer and quicker to read for people who are familiar with node and name resolution, but in my opinion we need something a bit more detailed for people who are less familiar with these concepts.

I'd also like to see if we could use a more "collaborative" tool to work on this proposal. Maybe drafting this in the Wiki would be easier for collaboration?

[tjfontaine]

This is definitely a step in the right direction, landed in 542234a, thanks!