DRIVERS-3632 Introduce Custom Callback logic in Configurable DNS by sleepyStick · Pull Request #1980 · mongodb/specifications

sleepyStick · 2026-09-10T00:27:27Z

Please complete the following before merging:

Is the relevant DRIVERS ticket in the PR title?

Update changelog.
Test changes in at least one language driver.
pymongo pr: PYTHON-6080 Introduce Custom Callback logic in Configurable DNS mongo-python-driver#3051
Test these changes against all server versions and topologies (including standalone, replica set, and sharded
clusters).

aclark4life · 2026-09-10T18:59:46Z

+    hostname has fewer than three `.` separated parts, the returned hostname MUST have at least one more domain level
+    than the SRV record hostname.
+- When [`srvAllowedHostsSuffix`](#srvallowedhostssuffix) is configured, the returned host name MUST end in
+    `srvAllowedHostsSuffix` after normalization.


Suggest tightening:

MUST end in
. followed by the srvAllowedHostsSuffix value.

thanks, done in 3610322

aclark4life · 2026-09-10T19:18:23Z

+
+Configure a MongoClient with `srvAllowedHostsSuffix=.mongodb.com` and assert that the SRV
+`mongodb+srv://blogs.mongodb.com` resolving to `CLUSTER.MONGODB.COM.` produces a seedlist containing
+`cluster.mongodb.com`.


This asserts the seedlist stores the normalized host name, but Querying DNS only requires normalization "before validating returned hostnames". A driver that normalizes only for the comparison and seeds the DNS-returned string is conforming today and would fail this test. Test 7 works because the srvHostValidator signature explicitly requires the normalized form as the callback input but there's no equivalent sentence for the seedlist. Could we add a similar sentence to Querying DNS?

E.g.

Before validating returned hostnames, drivers MUST normalize them as follows, in this order:

Any trailing . MUST be stripped. For example, host.mydomain.net. becomes host.mydomain.net.

The hostname MUST be converted to its A-label (Punycode) form.

The hostname MUST be normalized to lowercase using ASCII case folding.

Drivers MUST use the normalized hostnames, rather than the hostnames exactly as returned by DNS, to populate the
seedlist.

ah good call, fixed in 3610322

aclark4life · 2026-09-10T19:26:56Z

+
+Run this test twice: once with a validator that returns `false` for every host name, and once with a validator that
+raises an error for every host name. In both cases the driver MUST treat the returned host name as non-compliant, and
+MUST NOT raise an error to the application or stop rescanning.


Suggest tightening so we don't imply reconfigure mongo client.

Run this test twice: once with a validator that returns false for every host name, and once with a validator that
raises an error for every host name.

The validator's behavior MUST be controlled by state external to the validator (e.g. a flag the validator reads) so that it can be changed later in the test without reconfiguring the MongoClient.

In both cases the driver MUST treat the returned host name as non-compliant, and MUST NOT raise an error to the
application or stop rescanning.

thanks, done in 3610322

aclark4life · 2026-09-10T19:30:55Z

+
+Then reconfigure the validator to return `true` for every host name, wait until `2*rescanSRVIntervalMS`, and assert that
+rescanning was not stopped by the earlier failures: the final topology description MUST contain
+`localhost.test.build.10gen.cc:27019` in addition to the two original hosts.


Suggest tightening

Then change the validator's behavior so that it returns true for every host name. Because the earlier rescans
obtained no verified hosts, the driver has temporarily set rescanSRVIntervalMS to heartbeatFrequencyMS, so the next
rescan occurs within heartbeatFrequencyMS. Wait until 2*heartbeatFrequencyMS and assert that rescanning was not
stopped by the earlier failures: the final topology description MUST contain localhost.test.build.10gen.cc:27019 in
addition to the two original hosts.

thanks, done in 3610322

adelinowona · 2026-09-11T18:02:45Z

Should we also add a prose test for the reserved single labels?

added in c0cd20a!

adelinowona · 2026-09-11T18:10:18Z

+### 5. srvHostValidator accepts a host the default verification would reject
+
+When `srvHostValidator` is configured, it replaces the default verification entirely, so a returned address the default
+check would reject MUST be accepted if the validator returns `true`.
+
+Configure a validator that returns `true` for every host name and assert that the SRV `mongodb+srv://blogs.mongodb.com`
+resolving to `blogs.evil.com` produces a seedlist containing `blogs.evil.com`.


The default verification has two parts: (1) the returned host must share the SRV's {domainname}, and (2) when the SRV hostname has fewer than three . separated parts, the returned host must add at least one level.

This prose test currently only pins down part 1. Should we add another case that pins down part 2? something like mongodb+srv://mongo.corp resolving to mongo.corp

ah good call, modified the test to cover both parts in c0cd20a

adelinowona · 2026-09-11T18:16:10Z

 The driver MUST report an error if any of `srvServiceName`, `srvMaxHosts`, or `srvAllowedHostsSuffix` URI options are
 specified with a non-SRV URI (i.e. scheme other than `mongodb+srv`). The driver MUST allow specifying the
 `srvServiceName`, `srvMaxHosts`, and `srvAllowedHostsSuffix` URI options with an SRV URI (i.e. `mongodb+srv` scheme).
+While not a URI option, `srvHostValidator` also MUST only be allowed with the use of an SRV URI.


This MUST currently has no test. Should we add a prose test for it?

This also has the same open question as the mutual-exclusion error — when it surfaces isn't stated anywhere. Whatever timing sentence lands for the mutual-exclusion error should cover this check too.

yes! added in c0cd20a

adelinowona · 2026-09-11T18:32:18Z

 mongodb+srv://cluster.test.internal.example.com/?srvAllowedHostsSuffix=.internal.example.com
 ```

+### Rationale for `srvHostValidator`


Should we also add a rational entry for the allowlist?

done in dae1abe! let me know if there's information i'm missing in the entry!

…cords-for-mongos-discovery.md Co-authored-by: Adelin Owona <51498470+adelinowona@users.noreply.github.com>

…covery.md Co-authored-by: Adelin Owona <51498470+adelinowona@users.noreply.github.com>

aclark4life · 2026-09-11T21:26:29Z

+the program is compiled -- MUST skip this test.
+
+Assert that configuring a MongoClient with a `srvHostValidator` that is not callable, such as the string
+`"notacallable"`, throws a runtime error.


Is throwing a runtime error when the validator is not callable described in the spec?

ah modified to be just any error in c0cd20a-- thanks for calling this out!

aclark4life · 2026-09-11T21:39:43Z

+- When [`srvHostValidator`](#srvhostvalidator) is configured, the driver MUST pass each returned host name to the
+    validator and MUST treat the value it returns as the complete verdict: a returned host name is valid if and only if
+    the validator returns `true`. Drivers MUST NOT additionally apply the `{domainname}` check or the domain level
+    requirement described above, whether before or after calling the validator.


Can we add this to ensure all returned hosts are validated?

The driver MUST call the validator once for every returned host name, before any srvMaxHosts selection is applied.

not 100% the same language, but there is:

A driver MUST verify every host name returned through SRV records.

above it. Would you prefer this exact language instead?

…cords-for-mongos-discovery.md Co-authored-by: Qingyang Hu <103950869+qingyang-hu@users.noreply.github.com>

DRIVERS-3632 add srvHostValidator

d5719cd

sleepyStick marked this pull request as ready for review September 10, 2026 18:15

sleepyStick requested a review from a team as a code owner September 10, 2026 18:15

sleepyStick requested a review from qingyang-hu September 10, 2026 18:15

aclark4life requested changes Sep 10, 2026

View reviewed changes

sleepyStick added 2 commits September 10, 2026 20:40

edit language and add a test

c15a304

AC feedback

3610322

sleepyStick requested review from aclark4life, adelinowona and sanych-sun September 11, 2026 16:22

adelinowona requested changes Sep 11, 2026

View reviewed changes

sleepyStick and others added 2 commits September 11, 2026 13:55

Update source/polling-srv-records-for-mongos-discovery/polling-srv-re…

1987ae1

…cords-for-mongos-discovery.md Co-authored-by: Adelin Owona <51498470+adelinowona@users.noreply.github.com>

Update source/initial-dns-seedlist-discovery/initial-dns-seedlist-dis…

78a5918

…covery.md Co-authored-by: Adelin Owona <51498470+adelinowona@users.noreply.github.com>

aclark4life requested changes Sep 11, 2026

View reviewed changes

sleepyStick added 2 commits September 14, 2026 12:59

address feedback

c0cd20a

add rational for allowlist

dae1abe

sleepyStick requested review from aclark4life and adelinowona September 15, 2026 14:46

qingyang-hu reviewed Sep 15, 2026

View reviewed changes

Comment thread source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md Outdated

Comment thread source/polling-srv-records-for-mongos-discovery/tests/README.md

sleepyStick and others added 2 commits September 15, 2026 09:10

Update source/polling-srv-records-for-mongos-discovery/polling-srv-re…

3c5a277

…cords-for-mongos-discovery.md Co-authored-by: Qingyang Hu <103950869+qingyang-hu@users.noreply.github.com>

fix lint

5db4409

sleepyStick requested a review from qingyang-hu September 15, 2026 18:55

fix lint

d965713

Uh oh!

Conversation

sleepyStick commented Sep 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

sleepyStick commented Sep 10, 2026 •

edited

Loading