From cf1d754733506c368bf7625053c899e108f5e73c Mon Sep 17 00:00:00 2001 From: Iris Date: Wed, 30 Sep 2026 12:55:27 -0700 Subject: [PATCH 1/3] DRIVERS-3664 clarifiy confiurable dns validation --- .../initial-dns-seedlist-discovery.md | 24 ++++++++++++------- source/uri-options/uri-options.md | 5 +++- 2 files changed, 20 insertions(+), 9 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 1334a3a7e3..35eac5cbf3 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -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. @@ -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 @@ -425,6 +429,10 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog +- 2026-09-30: Specify that `srvAllowedHostsSuffix` has no hostname syntax validation beyond the listed steps (allowing + underscores), 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. diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index ef052493c2..4c80c816e8 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -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)

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 | @@ -185,6 +185,9 @@ changes. ## Changelog +- 2026-09-30: 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. From c88b31feaff14639c3884c8bc14ca24116478f02 Mon Sep 17 00:00:00 2001 From: Iris Date: Wed, 30 Sep 2026 13:31:15 -0700 Subject: [PATCH 2/3] add prose test --- source/initial-dns-seedlist-discovery/tests/README.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 747cfe85a4..ce7b9baae3 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -121,6 +121,15 @@ 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. + ## Test Setup The tests in the `replica-set` directory MUST be executed against a three-node replica set on localhost ports 27017, From 671d3088c7c12c16ebb0bcc1527b2f7c33b17db0 Mon Sep 17 00:00:00 2001 From: Iris Date: Thu, 1 Oct 2026 09:36:57 -0700 Subject: [PATCH 3/3] add test for _ (PS feedback) --- .../initial-dns-seedlist-discovery.md | 6 +++--- source/initial-dns-seedlist-discovery/tests/README.md | 10 ++++++++++ source/uri-options/uri-options.md | 2 +- 3 files changed, 14 insertions(+), 4 deletions(-) diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md index 35eac5cbf3..a40e820de8 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -429,9 +429,9 @@ In the future we could consider using the priority and weight fields of the SRV ## ChangeLog -- 2026-09-30: Specify that `srvAllowedHostsSuffix` has no hostname syntax validation beyond the listed steps (allowing - underscores), 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-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. diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index ce7b9baae3..50a1187723 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -130,6 +130,16 @@ 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, diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index 4c80c816e8..5c2417007d 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -185,7 +185,7 @@ changes. ## Changelog -- 2026-09-30: Clarify that `srvAllowedHostsSuffix` values are validated only by the steps in the Initial DNS Seedlist +- 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.