Skip to content

DRIVERS-3664 Configurable DNS domain validation for SRV records: clarifications #1989

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.

Sign up for GitHub

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

Merged
Jibola merged 3 commits into from
Oct 6, 2026
Merged

DRIVERS-3664 Configurable DNS domain validation for SRV records: clarifications #1989

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cf1d754
DRIVERS-3664 clarifiy confiurable dns validation
sleepyStick Sep 30, 2026
c88b31f
add prose test
sleepyStick Sep 30, 2026
671d308
add test for _ (PS feedback)
sleepyStick Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 16 additions & 8 deletions source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,8 +71,8 @@ Only `{domainname}` is used during SRV record verification and `{subdomain}` is
This option is used to validate hosts. If present, its value MUST be treated as the `{domainname}` for
[DNS validation](#querying-dns) and
[SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md). For example,
`srvAllowedHostsSuffix=.mydomain.net`. Drivers MUST apply the following normalization and validation to the value, in
this order:
`srvAllowedHostsSuffix=.mydomain.net`. Drivers MUST apply only the following normalization and validation to the value,
in this order:

1. Any leading or trailing `.` MUST be stripped. For example, `srvAllowedHostsSuffix=.mydomain.net.` is treated as
`mydomain.net`. If the resulting stripped value is empty, an error MUST be raised.
Expand Down Expand Up @@ -118,12 +118,16 @@ for SRV host validation. If both `srvAllowedHostsSuffix` and `srvHostValidator`
Drivers MAY raise this error at any point between MongoClient construction and DNS resolution. The signature of
`srvHostValidator` MUST take in a string representing the SRV resolved hostname after applying the normalization
described in [Querying DNS](#querying-dns), and return a bool representing whether the given SRV hostname is valid or
not. If `srvHostValidator` raises an error during initial seedlist resolution, the driver MUST catch that error and wrap
it prior to re-raising the error to the user. During
[SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md), a driver MUST
NOT raise an error; an error raised by the validator is instead treated as though the validator had returned `false`.
Since this is a synchronous callback, drivers should advise users to not write a validator that blocks. This option MUST
only be configurable at the level of a `MongoClient`.
not. In languages that do not enforce types at compile time, drivers MUST raise an error if the provided
`srvHostValidator` is not a callable of the expected type. Drivers MAY raise this error at any point between MongoClient
construction and DNS resolution. During initial seedlist discovery, if `srvHostValidator` returns a value that is not a
bool, drivers MUST treat it as though the validator raised an error. If `srvHostValidator` raises an error during
initial seedlist resolution, the driver MUST catch that error and wrap it prior to re-raising the error to the user.
During [SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md), a driver
MUST NOT raise an error; an error raised by the validator is instead treated as though the validator had returned
`false` and any value that is not the boolean `true` MUST be treated as `false`. Since this is a synchronous callback,
drivers should advise users to not write a validator that blocks. This option MUST only be configurable at the level of
a `MongoClient`.

Notably, `srvHostValidator` relaxes existing security measures and must be used with caution. Thus, drivers MUST
document that this parameter is a dangerous option. For example, something like "WARNING: Modifying the default SRV
Expand Down Expand Up @@ -425,6 +429,10 @@ In the future we could consider using the priority and weight fields of the SRV

## ChangeLog

- 2026-10-01: Specify that `srvAllowedHostsSuffix` has no hostname syntax validation beyond the listed steps, and that a
`srvHostValidator` of the wrong type, or one returning a non-bool value, results in an error during initial seedlist
discovery and is treated as `false` during SRV polling.

- 2026-09-16: Add `srvHostValidator` as a MongoClient option, and allow `srvAllowedHostsSuffix` to be a single label
when that label is one of a fixed list of names reserved for private or special use.

Expand Down
19 changes: 19 additions & 0 deletions source/initial-dns-seedlist-discovery/tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,25 @@ resolving to `db.cluster.localhost` produces a seedlist containing `db.cluster.l
Assert that configuring a MongoClient with any `srvHostValidator` and the non-SRV URI `mongodb://localhost:27017` throws
an error.

### 14. Throw when `srvHostValidator` returns a non-boolean value

Drivers whose language cannot express a non-boolean return value for `srvHostValidator` -- because the type is checked
when the program is compiled -- MUST skip this test. During initial seedlist resolution, a validator that returns a
value that is not a bool results in an error.

Configure a validator that returns the string `"true"` and assert that the SRV `mongodb+srv://blogs.mongodb.com`
resolving to `cluster.mongodb.com` throws an error.

### 15. Accept an underscore in `srvAllowedHostsSuffix`

Drivers MUST NOT apply hostname syntax validation to `srvAllowedHostsSuffix` beyond the steps listed in
[srvAllowedHostsSuffix](../initial-dns-seedlist-discovery.md#srvallowedhostssuffix), so a value containing an underscore
must be accepted.

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

## Test Setup

The tests in the `replica-set` directory MUST be executed against a three-node replica set on localhost ports 27017,
Expand Down
5 changes: 4 additions & 1 deletion source/uri-options/uri-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ to URI options apply here.
| serverSelectionTimeoutMS | positive integer; a driver may also accept 0 to be used for a special case, provided that it documents the meaning | defined in [server selection spec](../server-selection/server-selection.md#serverselectiontimeoutms) | no | A timeout in milliseconds to block for server selection before raising an error |
| serverSelectionTryOnce | "true" or "false" | defined in [server selection spec](../server-selection/server-selection.md#serverselectiontryonce) | required for single-threaded drivers | Scan the topology only once after a server selection failure instead of repeatedly until the server selection times out |
| socketTimeoutMS | non-negative integer; 0 means no timeout | no timeout | no | NOTE: This option is deprecated in favor of [timeoutMS](../client-side-operations-timeout/client-side-operations-timeout.md#timeoutms)<br><br>Amount of time spent attempting to send or receive on a socket before timing out; note that this only applies to application operations, not SDAM. |
| srvAllowedHostsSuffix | a valid DNS hostname suffix (e.g. ".mydomain.net") | none; domain is inferred from the SRV hostname | no | A hostname suffix used to validate hosts returned via SRV lookup, replacing the domain inferred from the SRV hostname. Defined in the [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvallowedhostssuffix). |
| srvAllowedHostsSuffix | a string that passes the `srvAllowedHostsSuffix` normalization and validation (e.g. ".mydomain.net") | none; domain is inferred from the SRV hostname | no | A hostname suffix used to validate hosts returned via SRV lookup, replacing the domain inferred from the SRV hostname. Defined in the [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvallowedhostssuffix). |
| srvMaxHosts | non-negative integer; 0 means no maximum | defined in the [Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvmaxhosts) | no | The maximum number of SRV results to randomly select when initially populating the seedlist or, during SRV polling, adding new hosts to the topology. |
| srvServiceName | a valid SRV service name according to [RFC 6335](https://datatracker.ietf.org/doc/html/rfc6335#section-5.1) | "mongodb" | no | the service name to use for SRV lookup in [initial DNS seedlist discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvservicename) and [SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md) |
| ssl | "true" or "false" | same as "tls" | no | alias of "tls"; required to ensure that Atlas connection strings continue to work |
Expand Down Expand Up @@ -185,6 +185,9 @@ changes.

## Changelog

- 2026-10-01: Clarify that `srvAllowedHostsSuffix` values are validated only by the steps in the Initial DNS Seedlist
Discovery spec.

- 2026-09-03: Add `srvAllowedHostsSuffix` option.

- 2026-06-17: Remove pre-4.2 version references.
Expand Down
Loading