docs: dns docs for family = 0 and all = true is potentially misleading

[domdomegg]

Affected URL(s)

https://nodejs.org/api/dns.html#dnslookuphostname-options-callback

Description of the problem

I think the docs are potentially misleading on the family = 0 dns lookup option.

Currently, the docs read: "The value 0 indicates that IPv4 and IPv6 addresses are both returned."

I initially interpreted this as "[NOT CORRECT] setting the family value to 0 and all to true will mean on a system that supports both IPv4 and IPv6, an IPv4 and IPv6 address will be returned"

However, what I think this actually means is "setting the family value to 0 and all to true will mean on a system that supports both IPv4 and IPv6, either an IPv4 or IPv6 address, or both will be returned - depending on the underlying DNS implementation"

As a short example demoing this behaviour (at least on Ubuntu 22.04.3, running Node v20.11.0):

require('node:dns').lookup('localhost', { all: true, family: 0 }, console.log)
// null [ { address: '127.0.0.1', family: 4 } ]

require('node:dns').lookup('localhost', { all: true, family: 4 }, console.log)
// null [ { address: '127.0.0.1', family: 4 } ]

require('node:dns').lookup('localhost', { all: true, family: 6 }, console.log)
// null [ { address: '::1', family: 6 } ]

Meaning if a user really does want both (rather than just accepts either), they should do two calls: one for IPv4 and one for IPv6 separately.

Some evidence for it being potentially confusing:

• In the wild, it seems to have been (ab)used assuming this is how it behaves: https://github.com/fastify/fastify/blob/main/test/upgrade.test.js#L10
• ChatGPT seems to interpret it this way: https://chat.openai.com/share/45d56342-ba83-4ead-a899-ad89ee4fbac4

Also see #28159.

[domdomegg]

The alternative angle is to view this as a potential feature for the dns module - where the behaviour of dns.lookup('localhost', { all: true, family: 0 }, console.log) is standardised across platforms to produce IPv4 and IPv6 results when available. Especially because even if documented, people still may depend on this behaviour because it works on some (most?) machines.

[duncanchiu409]

The current implementation is "setting the family value to 0 and all to true will mean on a system that supports both IPv4 and IPv6, either an IPv4 or IPv6 address". If I am not wrong. :)