-
Notifications
You must be signed in to change notification settings - Fork 28.8k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
doc: note about dns ANY queries / RFC 8482 #26695
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
🎉
doc/api/dns.md
Outdated
Note that the operator of an authoritative DNS server might choose not to | ||
respond to `ANY` queries for reasons of local policy, motivated by security, | ||
performance, or other reasons. For that reason you may want to instead call | ||
individual methods like `resolve4()`, `resolveMx()`, etc. For more information |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you make these into links to the other functions in this page?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Would the text/markdown below work for you instead? I'm trying to avoid unnecessarily-lengthy sentences and unneeded details. I'm also enforcing some style rules here (like avoid personal pronouns).
Note that the operator of an authoritative DNS server might choose not to
respond to `ANY` queries. It may be better to call individual methods like
`resolve4()`, `resolveMx()`, and so on. For more information, see [RFC 8482][].
I'd also be OK with upgrading "It may be better" to "It is almost always better" or "It is always better" or "It is better", or "Whenever possible, use..." I went with "It may be better" because it seemed to most closely reflect your original text ("you may want to"). But if a stronger statement is correct and appropriate, let's use it.
(By the way, the style guide is at https://github.com/nodejs/node/blob/master/doc/STYLE_GUIDE.md. Worth looking at if you plan on writing lots of docs here, but less so if you plan on dropping a little piece in here or there and don't mind someone like me nit-picking the crud out of it. 😆 ) |
I modified the text to be more concise and use reference-style links. Note that I'm using the |
Co-Authored-By: tlhunter <me@thomashunter.name>
PR-URL: #26695 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Bryan English <bryan@bryanenglish.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Landed in 3b6344c (with a nit fix in bottom references sorting). |
We can normalize on |
PR-URL: nodejs#26695 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Bryan English <bryan@bryanenglish.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: #26695 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Bryan English <bryan@bryanenglish.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
PR-URL: #26695 Reviewed-By: Gus Caplan <me@gus.host> Reviewed-By: Rich Trott <rtrott@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: Bryan English <bryan@bryanenglish.com> Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This was inspired by the Cloudflare post, RFC8482 - Saying goodbye to ANY / RFC 8482.
The post calls out that the
ANY
query isn't always honored by various services and so this PR warns the developer that such discrepancies can exist and that they may need to call other methods one at a time instead.Checklist