Repository navigation
docs: dns docs for family = 0 and all = true is potentially misleading #51482
Description
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.
Activity
domdomegg commentedon Jan 16, 2024
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 commentedon Jan 16, 2024
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. :)
doc: fix `dns.lookup` and `dnsPromises.lookup` description
doc: fix `dns.lookup` and `dnsPromises.lookup` description
doc: fix `dns.lookup` and `dnsPromises.lookup` description
doc: fix dns.lookup family 0 and all description
doc: fix `dns.lookup` family `0` and `all` descriptions
doc: fix `dns.lookup` family `0` and `all` descriptions
doc: fix `dns.lookup` family `0` and `all` descriptions