feat(NODE-7830): add srvAllowedHostsSuffix and srvHostValidator options

[PavelSafronov]

Description

Summary of Changes

Add two new ways to customize DNS resolution: srvAllowedHostsSuffix and srvHostValidator.

We are also modifying the behavior of the Driver for all mongodb+srv users: SRV host names are now normalized before comparison (lowercased, trailing dot removed, international names converted to xn-- form). As a result, a connection string whose SRV host name differs in case from the host names DNS returns, such as mongodb+srv://TEST1.TEST.BUILD.10GEN.CC, now passes SRV verification instead of failing with "Server record does not share hostname with parent URI".

Notes for Reviewers

This implements the following DRIVERS tickets:

1. DRIVERS-3329 - DRIVERS-3329: Configurable DNS domain validation for SRV records specifications#1950
2. DRIVERS-3632 - DRIVERS-3632 Introduce Custom Callback logic in Configurable DNS specifications#1980
3. DRIVERS-3664 - DRIVERS-3664 Configurable DNS domain validation for SRV records: clarifications specifications#1989

The specifications include this SHOULD step that we skip:

5. Drivers SHOULD raise an error if the resulting value is a public suffix, per the algorithm in
   Public Suffix List, unless the value is in the aforementioned list
   of valid names.

This is a SHOULD, so Node/Java/C# do not implement the Public Suffix List (PSL), only Python has added PSL support to their driver so far.

DRIVERS-3664 is open to make some changes to the relevant specs, current work should not be merged before 3664 is reviewed and merged.

For this work, we aren't pulling in all the specifications changes from main, they will be done with their respective NODE tickets:

• ping updates, NODE-4083
• uri-with-uppercase-hostname updates, NODE-5439, blocked on NODE-3757

An unrelated test fix adds some entries to test/mongodb_bundled.ts. Once we complete NODE-7850, these missing entries will cause a build failure, so in the future it won't be possible to get into this state.

Host name conversion follows the WHATWG URL Standard's domain parser; the spec allows drivers to choose their IDNA processing standard. The URL Standard was updated in June 2026 to return ASCII names lowercased even when their xn-- labels are not valid A-labels, but Node.js only picked this up in 24.20.0 (nodejs/node#64790, Ada 4.0.0), so earlier Node.js versions reject such names in url.domainToASCII. To behave the same on every Node.js version, and to keep accepting host names that main accepts today, we lowercase ASCII names ourselves instead of relying on url.domainToASCII.

Release Highlight

Configurable SRV host validation

This release adds two new methods of validating DNS:

1. srvAllowedHostsSuffix - A host name suffix that every host returned by the SRV lookup must end with. This option can be configured on the client or the connection string.
2. srvHostValidator - A synchronous function that decides whether a host returned by the SRV lookup may be used. This option can only be configured on the client. This function must accept a string and has to return a boolean; returning anything else, including the Promise returned by an async function, will result in an error.

Warning

Modifying the default SRV domain name validation can create vulnerabilities.

SRV host names are now compared in a normalized form (case-insensitively, without a trailing dot, and with internationalized names in xn-- form). Connection strings whose SRV host name differs in case from the host names returned by DNS, such as mongodb+srv://TEST1.TEST.BUILD.10GEN.CC, previously failed SRV verification and now connect.

Double check the following

• Lint is passing (npm run check:lint)
• Self-review completed using the steps outlined here
• PR title follows the correct format: type(NODE-xxxx)[!]: description
  • Example: feat(NODE-1234)!: rewriting everything in coffeescript
• Changes are covered by tests
• New TODOs have a related JIRA ticket

[Copilot]

Copilot review overview

🟡 Changes recommended

HostAddress reparsing defeats the intended cross-version handling on older supported Node releases, and the declared upstream prerequisite remains open.

Review effort: Balanced
Findings: 2

Open (2)

• Avoid URL revalidation of normalized SRV hosts during initial resolution · New
• Avoid URL revalidation of normalized hosts in SRV polling events · New

What changed in this PR

Adds configurable SRV host validation and normalized DNS-name comparison throughout initial discovery and polling.

Changes:

• Adds srvAllowedHostsSuffix and synchronous srvHostValidator options.
• Normalizes SRV names to lowercase A-label form without trailing dots.
• Adds unit, integration, type, and upstream conformance coverage.

The declared DRIVERS-3664 prerequisite remains open and blocked.

File	Description
src/​connection_string.ts	Parses options and validates initial SRV results.
src/​mongo_client.ts	Exposes and documents the new options.
src/​sdam/​srv_polling.ts	Applies validation during SRV polling.
src/​sdam/​topology.ts	Passes options into the SRV poller.
src/​utils.ts	Adds DNS normalization and shared verification.
test/​mongodb_bundled.ts	Exposes required test helpers.
test/​integration/​initial-dns-seedlist-discovery/​initial_dns_seedlist_discovery.prose.test.ts	Covers initial discovery behavior.
test/​unit/​assorted/​polling_srv_records_for_mongos_discovery.prose.test.ts	Covers validator polling behavior.
test/​unit/​connection_string.test.ts	Tests parsing, normalization, and validation.
test/​unit/​sdam/​srv_polling.test.ts	Tests poller filtering and normalization.
test/​unit/​utils.test.ts	Tests DNS normalization.
test/​types/​community/​client.test-d.ts	Verifies public option types.
test/​tools/​uri_spec_runner.ts	Supports the new URI option.
test/​spec/​uri-options/​srv-options.yml	Adds upstream YAML URI fixture.
test/​spec/​uri-options/​srv-options.json	Adds upstream JSON URI fixture.
test/​spec/​polling-srv-records-for-mongos-discovery/​README.md	Vendors polling prose tests.
test/​spec/​initial-dns-seedlist-discovery/​README.md	Vendors discovery prose tests.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-without_dot_pass.yml	Adds suffix success fixture.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-without_dot_pass.json	Adds suffix success fixture.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-without_dot_fail.yml	Adds suffix rejection fixture.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-without_dot_fail.json	Adds suffix rejection fixture.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-with_dot.yml	Covers leading-dot suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-with_dot.json	Covers leading-dot suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-trailing-dot.yml	Covers trailing-dot normalization.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-trailing-dot.json	Covers trailing-dot normalization.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-tld-only.yml	Covers single-label rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-tld-only.json	Covers single-label rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-public-suffix.yml	Covers public suffix rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-public-suffix.json	Covers public suffix rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-public-suffix-capitalized.yml	Covers normalized public suffix rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-public-suffix-capitalized.json	Covers normalized public suffix rejection.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-not-public-suffix.yml	Covers accepted registrable suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-psl-not-public-suffix.json	Covers accepted registrable suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-period-only.yml	Covers empty normalized suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-period-only.json	Covers empty normalized suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-mismatch.yml	Covers suffix mismatches.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-mismatch.json	Covers suffix mismatches.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-case-insensitive.yml	Covers case-insensitive suffixes.
test/​spec/​initial-dns-seedlist-discovery/​replica-set/​srvAllowedHostsSuffix-case-insensitive.json	Covers case-insensitive suffixes.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[tadjik1]

I would probably remove this comment or at least remove mentions of other drivers, otherwise it's unclear how their decisions impact our implementation. Instead we can add TODO for the ticket to fill the gap in the future, wdyt?

[PavelSafronov]

The Public Suffix List comes with a set of issues (for example, we'll need to sync it monthly) and with this change can actually be implemented by the caller if need be. So far only Python implements PSL, no other Drivers have agreed to add it yet. (Andre implemented one for Java, but this was shelved.) IMO, we shouldn't add it.

[tadjik1]

Yep, I agree. But still not sure if mention of Java and C# is really valuable here, it reads well in the PR description but it can be source of confusion in the future if left in the code (what about other drivers, what if the ones that we mention would add support).

[tadjik1]

Great work, thank you!