From 7f119f124491758e907474fe444be089e0cea5c6 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Thu, 22 Aug 2024 08:30:49 -0500 Subject: [PATCH] DRIVERS-2789 Convert Polling SRV Records to Markdown --- source/index.md | 1 + .../initial-dns-seedlist-discovery.md | 2 +- ...olling-srv-records-for-mongos-discovery.md | 298 +++++++----------- ...lling-srv-records-for-mongos-discovery.rst | 4 + .../tests/README.md | 253 +++++++-------- source/uri-options/uri-options.md | 2 +- 6 files changed, 243 insertions(+), 317 deletions(-) create mode 100644 source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst diff --git a/source/index.md b/source/index.md index 2534bf4b5e..ddcc24d13b 100644 --- a/source/index.md +++ b/source/index.md @@ -32,6 +32,7 @@ - [OP_MSG](message/OP_MSG.md) - [ObjectID format](./objectid.md) - [Performance Benchmarking](benchmarking/benchmarking.md) +- [Polling SRV Records for mongos Discovery](polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md) - [Retryable Reads](retryable-reads/retryable-reads.md) - [Retryable Writes](retryable-writes/retryable-writes.md) - [SDAM Logging and Monitoring Specification](server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md) 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 0e3da0797a..4f4c340a31 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -44,7 +44,7 @@ specification following the `Host Information`. This includes the `Auth database This option is used to limit the number of mongos connections that may be created for sharded topologies. This option limits the number of SRV records used to populate the seedlist during initial discovery, as well as the number of additional hosts that may be added during -[SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst). This option +[SRV polling](../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md). This option requires a non-negative integer and defaults to zero (i.e. no limit). This option MUST only be configurable at the level of a `MongoClient`. diff --git a/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md b/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md index 7691629d33..974f7ba3ff 100644 --- a/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md +++ b/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.md @@ -1,238 +1,176 @@ -.. role:: javascript(code) - :language: javascript +# Polling SRV Records for mongos Discovery -======================================== -Polling SRV Records for mongos Discovery -======================================== +- Status: Accepted +- Minimum Server Version: N/A -:Status: Accepted -:Minimum Server Version: N/A +______________________________________________________________________ -.. contents:: +## Abstract --------- +Currently the [Initial DNS Seedlist Discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) +functionality provides a static seedlist when a MongoClient is constructed. Periodically polling the DNS SRV records +would allow for the mongos proxy list to be updated without having to change client configuration. -Abstract -======== +This specification builds on top of the original Initial DNS Seedlist Discovery specification, and modifies the +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) specification's +definition of monitoring a set of mongos servers in a Sharded TopologyType. -Currently the `Initial DNS Seedlist Discovery`_ functionality provides a static -seedlist when a MongoClient is constructed. Periodically polling the DNS SRV -records would allow for the mongos proxy list to be updated without having to -change client configuration. +## META -This specification builds on top of the original Initial DNS Seedlist -Discovery specification, and modifies the `Server Discovery and Monitoring`_ -specification's definition of monitoring a set of mongos servers in a Sharded -TopologyType. +The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and +"OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). -.. _`Initial DNS Seedlist Discovery`: ../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md -.. _`Server Discovery and Monitoring`: ../server-discovery-and-monitoring/server-discovery-and-monitoring.md +## Specification -META -==== +### Terms -The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, -“SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be -interpreted as described in `RFC 2119 `_. +#### rescan, rescanning -Specification -============= +A rescan is the periodic scan of all DNS SRV records to discover a new set of mongos hosts. -Terms ------ +#### rescanSRVIntervalMS -rescan, rescanning -~~~~~~~~~~~~~~~~~~ +An internal value representing how often the DNS SRV records should be queried for. -A rescan is the periodic scan of all DNS SRV records to discover a new set of -mongos hosts. +### Implementation -rescanSRVIntervalMS -~~~~~~~~~~~~~~~~~~~ +If the initial topology was created through a `mongodb+srv://` URI, then drivers MUST implement this specification by +periodically rescanning the SRV DNS records. There MUST NOT be an option to turn this behaviour off. -An internal value representing how often the DNS SRV records should be queried -for. +Drivers MUST NOT implement this specification if they do not adhere fully to the +[Initial DNS Seedlist Discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) specification. -Implementation --------------- - -If the initial topology was created through a ``mongodb+srv://`` URI, then -drivers MUST implement this specification by periodically rescanning the SRV -DNS records. There MUST NOT be an option to turn this behaviour off. - -Drivers MUST NOT implement this specification if they do not adhere fully to -the `Initial DNS Seedlist Discovery`_ specification. - -This feature is only available when the Server Discovery has determined that -the TopologyType is Sharded, or Unknown. Drivers MUST NOT rescan SRV DNS -records when the Topology is not Sharded (i.e. Single, ReplicaSetNoPrimary, or +This feature is only available when the Server Discovery has determined that the TopologyType is Sharded, or Unknown. +Drivers MUST NOT rescan SRV DNS records when the Topology is not Sharded (i.e. Single, ReplicaSetNoPrimary, or ReplicaSetWithPrimary). -The discovery of a set of mongos servers is explained in the seedlist_ -discovery section of the original specification. The behaviour of the periodic -rescan is similar, but not identical to the behaviour of initial seedlist -discovery. Periodic scan MUST follow these rules: - -- The driver will query the DNS server for SRV records on - ``{hostname}.{domainname}``, prefixed with the SRV service name and protocol. - The SRV service name is provided in the srvServiceName_ URI option and - defaults to ``mongodb``. The protocol is always ``tcp``. After prefixing, the - URI should look like: ``_{srvServiceName}._tcp.{hostname}.{domainname}``. - -- A driver MUST verify that the host names returned through SRV records have - the same parent ``{domainname}``. When this verification fails, a driver: - +The discovery of a set of mongos servers is explained in the +[seedlist](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#seedlist-discovery) discovery section of +the original specification. The behaviour of the periodic rescan is similar, but not identical to the behaviour of +initial seedlist discovery. Periodic scan MUST follow these rules: + +- The driver will query the DNS server for SRV records on `{hostname}.{domainname}`, prefixed with the SRV service name + and protocol. The SRV service name is provided in the + [srvServiceName](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvservicename) URI option and + defaults to `mongodb`. The protocol is always `tcp`. After prefixing, the URI should look like: + `_{srvServiceName}._tcp.{hostname}.{domainname}`. +- A driver MUST verify that the host names returned through SRV records have the same parent `{domainname}`. When this + verification fails, a driver: - MUST NOT add such a non-compliant host name to the topology - MUST NOT raise an error - SHOULD log the non-compliance, including the host name - MUST NOT initiate a connection to any such host - -- If the DNS request returns no verified hosts in SRV records, no SRV records - at all, or a DNS error happens, the driver: - +- If the DNS request returns no verified hosts in SRV records, no SRV records at all, or a DNS error happens, the + driver: - MUST NOT change the topology - MUST NOT raise an error - - SHOULD log this situation, including the reason why the DNS records - could not be found, if possible - - MUST temporarily set *rescanSRVIntervalMS* to *heartbeatFrequencyMS* until - at least one verified SRV record is obtained. - -- For all verified host names, as returned through the DNS SRV query, the - driver: - - - MUST remove all hosts that are part of the topology, but are no longer - in the returned set of valid hosts - - MUST NOT remove all hosts, and then re-add the ones that were returned. - Hosts that have not changed, MUST be left alone and unchanged. - - If srvMaxHosts_ is zero or greater than or equal to the number of valid - hosts, each valid new host MUST be added to the topology as Unknown. - - If srvMaxHosts_ is greater than zero and less than the number of valid - hosts, valid new hosts MUST be randomly selected and added to the topology - as Unknown until the topology has ``srvMaxHosts`` hosts. Drivers MUST use - the same randomization algorithm as they do for `initial selection`_. - -- Priorities and weights in SRV records MUST continue to be ignored, and MUST - NOT dictate which mongos server is used for new connections. - -The rescan needs to happen periodically. As SRV records contain a TTL value, -this value can be used to indicate when a rescan needs to happen. Different -SRV records can have different TTL values. The *rescanSRVIntervalMS* value MUST -be set to the lowest of the individual TTL values associated with the -different SRV records in the most recent rescan, but MUST NOT be lower -than *60 seconds*. If a driver is unable to access the TTL values of SRV -records, it MUST rescan every 60 seconds. - -Drivers SHOULD endeavour to rescan and obtain a new list of mongos servers -every *rescanSRVIntervalMS* value. The *rescanSRVIntervalMS* period SHOULD be -calculated from the **end** of the previous rescan (or the **end** of the -initial DNS seedlist discovery scan). - -.. _seedlist: ../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#seedlist-discovery -.. _srvMaxHosts: ../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvmaxhosts -.. _srvServiceName: ../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvservicename -.. _`initial selection`: ../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#querying-dns - -Multi-Threaded Drivers ----------------------- - -A threaded driver MUST use a separate monitoring thread for scanning the DNS -records so that DNS lookups don't block other operations. - -Single-Threaded Drivers ------------------------ + - SHOULD log this situation, including the reason why the DNS records could not be found, if possible + - MUST temporarily set *rescanSRVIntervalMS* to *heartbeatFrequencyMS* until at least one verified SRV record is + obtained. +- For all verified host names, as returned through the DNS SRV query, the driver: + - MUST remove all hosts that are part of the topology, but are no longer in the returned set of valid hosts + - MUST NOT remove all hosts, and then re-add the ones that were returned. Hosts that have not changed, MUST be left + alone and unchanged. + - If [srvMaxHosts](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvmaxhosts) is zero or greater + than or equal to the number of valid hosts, each valid new host MUST be added to the topology as Unknown. + - If [srvMaxHosts](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#srvmaxhosts) is greater than + zero and less than the number of valid hosts, valid new hosts MUST be randomly selected and added to the topology as + Unknown until the topology has `srvMaxHosts` hosts. Drivers MUST use the same randomization algorithm as they do for + [initial selection](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#querying-dns). +- Priorities and weights in SRV records MUST continue to be ignored, and MUST NOT dictate which mongos server is used + for new connections. + +The rescan needs to happen periodically. As SRV records contain a TTL value, this value can be used to indicate when a +rescan needs to happen. Different SRV records can have different TTL values. The *rescanSRVIntervalMS* value MUST be set +to the lowest of the individual TTL values associated with the different SRV records in the most recent rescan, but MUST +NOT be lower than *60 seconds*. If a driver is unable to access the TTL values of SRV records, it MUST rescan every 60 +seconds. + +Drivers SHOULD endeavour to rescan and obtain a new list of mongos servers every *rescanSRVIntervalMS* value. The +*rescanSRVIntervalMS* period SHOULD be calculated from the **end** of the previous rescan (or the **end** of the initial +DNS seedlist discovery scan). + +### Multi-Threaded Drivers + +A threaded driver MUST use a separate monitoring thread for scanning the DNS records so that DNS lookups don't block +other operations. + +### Single-Threaded Drivers The rescan MUST happen **before** scanning all servers as part of the normal -scanning_ functionality, but only if *rescanSRVIntervalMS* has passed. - -.. _scanning: ../server-discovery-and-monitoring/server-discovery-and-monitoring.md#scanning +[scanning](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#scanning) functionality, but only if +*rescanSRVIntervalMS* has passed. -Test Plan -========= +## Test Plan -See README.rst in the accompanying `test directory`_. +See README.rst in the accompanying [test directory](tests). -.. _`test directory`: tests +## Motivation for Change -Motivation for Change -===================== +The original [Initial DNS Seedlist Discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) +specification only regulates the initial list of mongos hosts to be used instead of a single hostname from a connection +URI. Although this makes the initial configuration of a set of mongos servers a lot easier, it does not provide a method +for updating the list of mongos servers in the topology. -The original `Initial DNS Seedlist Discovery`_ specification only regulates -the initial list of mongos hosts to be used instead of a single hostname from -a connection URI. Although this makes the initial configuration of a set of -mongos servers a lot easier, it does not provide a method for updating the -list of mongos servers in the topology. - -Since the introduction of the ``mongodb+srv://`` schema to provide an initial -seedlist, some users have requested additional functionality to be able to -update the configured list of mongos hosts that make up the initially seeded +Since the introduction of the `mongodb+srv://` schema to provide an initial seedlist, some users have requested +additional functionality to be able to update the configured list of mongos hosts that make up the initially seeded topology: -- https://jira.mongodb.org/browse/JAVA-2927 +- -Design Rationale -================ +## Design Rationale -From the scope document ------------------------ +### From the scope document -Should DNS polling use heartbeatFrequencyMS or DNS cache TTLs? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#### Should DNS polling use heartbeatFrequencyMS or DNS cache TTLs? -We have selected to use lowest TTLs among all DNS SRV records, with a caveat -that the rescan frequency is not lower than 60 seconds. +We have selected to use lowest TTLs among all DNS SRV records, with a caveat that the rescan frequency is not lower than +60 seconds. -Should DNS polling also have a "fast polling" mode when no servers are available? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#### Should DNS polling also have a "fast polling" mode when no servers are available? -We have not opted to have a "fast polling" mode, but we did include a -provision that a rescan needs to happen when DNS records are not available. In -that case, a rescan would happen every *heartbeatFrequencyMS*. The rationale -being that polling DNS really often really fast does not make a lot of sense -due to DNS caching, which often uses the TTL already anyway, but when we have -no TTL records to reference we still need a fallback frequency. +We have not opted to have a "fast polling" mode, but we did include a provision that a rescan needs to happen when DNS +records are not available. In that case, a rescan would happen every *heartbeatFrequencyMS*. The rationale being that +polling DNS really often really fast does not make a lot of sense due to DNS caching, which often uses the TTL already +anyway, but when we have no TTL records to reference we still need a fallback frequency. -For the design --------------- +### For the design -No option to turn off periodic rescanning -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +#### No option to turn off periodic rescanning -The design does not allow for an option to turn off the periodic rescanning of -SRV records on the basis that we try to have as few options as possible: the -"no knobs" philosophy. +The design does not allow for an option to turn off the periodic rescanning of SRV records on the basis that we try to +have as few options as possible: the "no knobs" philosophy. -Backwards Compatibility -======================= +## Backwards Compatibility -This specification changes the behaviour of server monitoring by introducing a -repeating DNS lookup of the SRV records. Although this is an improvement in -the ``mongodb+srv://`` scheme it can nonetheless break expectations with users -that were familiar with the old behaviour. We do not expect this to negatively -impact users. +This specification changes the behaviour of server monitoring by introducing a repeating DNS lookup of the SRV records. +Although this is an improvement in the `mongodb+srv://` scheme it can nonetheless break expectations with users that +were familiar with the old behaviour. We do not expect this to negatively impact users. -Reference Implementation -======================== +## Reference Implementation Reference implementations are made for the following drivers: - Perl - C# -Security Implication -==================== +## Security Implication -This specification has no security implications beyond the ones associated -with the original `Initial DNS Seedlist Discovery`_ specification. +This specification has no security implications beyond the ones associated with the original +[Initial DNS Seedlist Discovery](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) specification. -Future work -=========== +## Future work No future work is expected. -Changelog -========= +## Changelog + +- 2024-08-22: Migrated from reStructuredText to Markdown. + +- 2022-10-05: Revise spec front matter and reformat changelog. + +- 2021-10-14: Specify behavior for `srvMaxHosts` MongoClient option. -:2022-10-05: Revise spec front matter and reformat changelog. -:2021-10-14: Specify behavior for ``srvMaxHosts`` MongoClient option. -:2021-09-15: Clarify that service name only defaults to ``mongodb``, and should - be defined by the ``srvServiceName`` URI option. +- 2021-09-15: Clarify that service name only defaults to `mongodb`, and should\ + be defined by the `srvServiceName` URI + option. diff --git a/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst b/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst new file mode 100644 index 0000000000..6b72de7beb --- /dev/null +++ b/source/polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst @@ -0,0 +1,4 @@ + +.. note:: + This specification has been converted to Markdown and renamed to + `polling-srv-records-for-mongos-discovery.md `_. diff --git a/source/polling-srv-records-for-mongos-discovery/tests/README.md b/source/polling-srv-records-for-mongos-discovery/tests/README.md index a32a921f14..1309a41748 100644 --- a/source/polling-srv-records-for-mongos-discovery/tests/README.md +++ b/source/polling-srv-records-for-mongos-discovery/tests/README.md @@ -1,219 +1,202 @@ -================= -SRV Polling Tests -================= +# SRV Polling Tests -.. contents:: +## Introduction -Introduction -============ +This directory contains prose test descriptions that drivers can use to prove their conformance to the SRV polling +specification. -This directory contains prose test descriptions that drivers can use -to prove their conformance to the SRV polling specification. +Without (automated) access to a DNS server configuration, it is nearly impossible to implement functional tests for a +correct implementation of this specification. However, it might be possible to mock changes to DNS SRV records such that +automated testing is doable. In any case, the following tests should be executed, either manually, or programmatically. -Without (automated) access to a DNS server configuration, it is nearly -impossible to implement functional tests for a correct implementation of this -specification. However, it might be possible to mock changes to DNS SRV -records such that automated testing is doable. In any case, the following -tests should be executed, either manually, or programmatically. +## Configuring the Test Environment -Configuring the Test Environment -================================ +To test, start a sharded cluster with mongos servers on ports 27017, 27018, 27019, and 27020. -To test, start a sharded cluster with mongos servers on ports 27017, 27018, -27019, and 27020. +For each test, take as a starting point the test1, test3, and test22 SRV records from the +[test set-up](../../initial-dns-seedlist-discovery/tests/README.md) from the +[Initial DNS Seedlist Discovery](../../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md) specification: -For each test, take as a starting point the test1, test3, and test22 SRV records from -the `test set-up`_ from the `Initial DNS Seedlist Discovery`_ specification:: +``` +Record TTL Class Address +localhost.test.test.build.10gen.cc. 86400 IN A 127.0.0.1 - Record TTL Class Address - localhost.test.test.build.10gen.cc. 86400 IN A 127.0.0.1 +Record TTL Class Port Target +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +_mongodb._tcp.test3.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. +_customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. +``` - Record TTL Class Port Target - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. - _mongodb._tcp.test3.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. - _customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27017 localhost.test.build.10gen.cc. +## Prose Tests -.. _`test set-up`: ../../initial-dns-seedlist-discovery/tests/README.md -.. _`Initial DNS Seedlist Discovery`: ../../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +### Changing DNS records with test1.test.build.10gen.cc -Prose Tests -=========== +The following tests MUST setup a MongoClient using the `test1.test.build.10gen.cc` SRV record. Each test MUST mock the +described DNS changes and then verify that the new list of hosts is present. -Changing DNS records with test1.test.build.10gen.cc -``````````````````````````````````````````````````` +#### 1. Addition of a new DNS record -The following tests MUST setup a MongoClient using the -``test1.test.build.10gen.cc`` SRV record. Each test MUST mock the described -DNS changes and then verify that the new list of hosts is present. +Add the following record: -1. Addition of a new DNS record -------------------------------- +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +``` -Add the following record:: +#### 2. Removal of an existing DNS record - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +Remove the following record: -2. Removal of an existing DNS record ------------------------------------- +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` -Remove the following record:: +#### 3. Replacement of a DNS record - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +Replace the following record: -3. Replacement of a DNS record ------------------------------- +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` -Replace the following record:: +with: - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +``` -with:: +#### 4. Replacement of both existing DNS records with *one* new record - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +Replace both records with: -4. Replacement of both existing DNS records with *one* new record ------------------------------------------------------------------ +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +``` -Replace both records with:: +#### 5. Replacement of both existing DNS records with *two* new records - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +Replace both records with: -5. Replacement of both existing DNS records with *two* new records ------------------------------------------------------------------- +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` -Replace both records with:: +### Error scenarios with test1.test.build.10gen.cc - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +The following tests MUST setup a MongoClient using the `test1.test.build.10gen.cc` SRV record. Each test MUST mock the +described error situation and assert that the internal list of discovered mongos servers has not changed. -Error scenarios with test1.test.build.10gen.cc -`````````````````````````````````````````````` - -The following tests MUST setup a MongoClient using the -``test1.test.build.10gen.cc`` SRV record. Each test MUST mock the described -error situation and assert that the internal list of discovered mongos servers -has not changed. - -6. DNS record lookup timeout ----------------------------- +#### 6. DNS record lookup timeout Mock a DNS record lookup timeout error. -7. DNS record lookup failure ----------------------------- +#### 7. DNS record lookup failure Mock a DNS record lookup failure (i.e. domain no longer exists because it's no longer registered). -8. Removal of all DNS SRV records ---------------------------------- +#### 8. Removal of all DNS SRV records Mock a DNS record lookup that returns zero SRV records. -Changing DNS records with test3.test.build.10gen.cc -``````````````````````````````````````````````````` - -The following tests MUST setup a MongoClient using the -``test3.test.build.10gen.cc`` SRV record. Each test MUST mock the described -situation and make the specified assertions. +### Changing DNS records with test3.test.build.10gen.cc -9. Test that SRV polling is not done for load balalanced clusters ------------------------------------------------------------------ +The following tests MUST setup a MongoClient using the `test3.test.build.10gen.cc` SRV record. Each test MUST mock the +described situation and make the specified assertions. -Connect to ``mongodb+srv://test3.test.build.10gen.cc/?loadBalanced=true``, -mock the addition of the following DNS record:: +#### 9. Test that SRV polling is not done for load balalanced clusters - _mongodb._tcp.test3.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +Connect to `mongodb+srv://test3.test.build.10gen.cc/?loadBalanced=true`, mock the addition of the following DNS record: -Wait until ``2*rescanSRVIntervalMS`` and assert that the final topology description -only contains one server: ``localhost.test.build.10gen.cc.`` at port ``27017``. +``` +_mongodb._tcp.test3.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` +Wait until `2*rescanSRVIntervalMS` and assert that the final topology description only contains one server: +`localhost.test.build.10gen.cc.` at port `27017`. -SRV polling with srvMaxHosts MongoClient option -``````````````````````````````````````````````` +### SRV polling with srvMaxHosts MongoClient option -The following tests MUST setup a MongoClient using the ``srvMaxHosts`` option -and ``test1.test.build.10gen.cc`` SRV record. Each test MUST mock the described -DNS changes and then verify that the new list of hosts is present. +The following tests MUST setup a MongoClient using the `srvMaxHosts` option and `test1.test.build.10gen.cc` SRV record. +Each test MUST mock the described DNS changes and then verify that the new list of hosts is present. +#### 10. All DNS records are selected (srvMaxHosts = 0) -10. All DNS records are selected (srvMaxHosts = 0) --------------------------------------------------- +Configure the MongoClient with `srvMaxHosts=0`. -Configure the MongoClient with ``srvMaxHosts=0``. +Replace the following record: -Replace the following record:: +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +with: -with:: +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. - -Wait until ``2*rescanSRVIntervalMS`` and assert that the final topology description -contains the following hosts: +Wait until `2*rescanSRVIntervalMS` and assert that the final topology description contains the following hosts: - localhost.test.build.10gen.cc:27017 - localhost.test.build.10gen.cc:27019 - localhost.test.build.10gen.cc:27020 +#### 11. All DNS records are selected (srvMaxHosts >= records) -11. All DNS records are selected (srvMaxHosts >= records) ---------------------------------------------------------- - -Configure the MongoClient with ``srvMaxHosts=2``. +Configure the MongoClient with `srvMaxHosts=2`. -Replace both records with:: +Replace both records with: - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` -Wait until ``2*rescanSRVIntervalMS`` and assert that the final topology description -contains the following hosts: +Wait until `2*rescanSRVIntervalMS` and assert that the final topology description contains the following hosts: - localhost.test.build.10gen.cc:27019 - localhost.test.build.10gen.cc:27020 +#### 12. New DNS records are randomly selected (srvMaxHosts > 0) -12. New DNS records are randomly selected (srvMaxHosts > 0) ------------------------------------------------------------ - -Configure the MongoClient with ``srvMaxHosts=2``. +Configure the MongoClient with `srvMaxHosts=2`. -Replace the following record:: +Replace the following record: - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27018 localhost.test.build.10gen.cc. +``` -with:: +with: - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. - _mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +_mongodb._tcp.test1.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` -Wait until ``2*rescanSRVIntervalMS`` and assert that the topology has two hosts -present and that one of the hosts is ``localhost.test.build.10gen.cc:27017``. -The second, new host will have been randomly selected and cannot be +Wait until `2*rescanSRVIntervalMS` and assert that the topology has two hosts present and that one of the hosts is +`localhost.test.build.10gen.cc:27017`. The second, new host will have been randomly selected and cannot be deterministically asserted. -SRV polling with srvServiceName MongoClient option -`````````````````````````````````````````````````` +### SRV polling with srvServiceName MongoClient option -The following test MUST setup a MongoClient using the ``srvServiceName`` option -and the ``test22.test.build.10gen.cc`` SRV record. The test MUST mock the described -DNS changes and then verify that the new list of hosts is present. +The following test MUST setup a MongoClient using the `srvServiceName` option and the `test22.test.build.10gen.cc` SRV +record. The test MUST mock the described DNS changes and then verify that the new list of hosts is present. -13. DNS record with custom service name can be found ----------------------------------------------------- +#### 13. DNS record with custom service name can be found -Configure the MongoClient with ``srvServiceName=customname``. +Configure the MongoClient with `srvServiceName=customname`. -Replace both records with:: +Replace both records with: - _customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. - _customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` +_customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27019 localhost.test.build.10gen.cc. +_customname._tcp.test22.test.build.10gen.cc. 86400 IN SRV 27020 localhost.test.build.10gen.cc. +``` -Wait until ``2*rescanSRVIntervalMS`` and assert that the final topology description -contains the following hosts: +Wait until `2*rescanSRVIntervalMS` and assert that the final topology description contains the following hosts: - localhost.test.build.10gen.cc:27019 - localhost.test.build.10gen.cc:27020 diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index 046be4494f..4197f57e9e 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -103,7 +103,7 @@ to URI options apply here. | 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. | | 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.rst) | +| 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 | | | | | | | | tls | "true" or "false" | TLS required if "mongodb+srv" scheme; otherwise, drivers may may enable TLS by default if other "tls"-prefixed options are present

Drivers MUST clearly document the conditions under which TLS is enabled implicitly | no | Whether or not to require TLS for connections to the server |