DRIVERS-521 Allow custom SRV service names with srvServiceName URI option (#1067)

benjirewis · web-flow · commit c48d7f416e51 · 2021-09-15T14:20:11.000-04:00
diff --git a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst
@@ -10,8 +10,8 @@ Initial DNS Seedlist Discovery
 :Authors: Derick Rethans
 :Status: Draft
 :Type: Standards
-:Last Modified: 2019-04-15
-:Version: 1.4.0
+:Last Modified: 2021-09-15
+:Version: 1.5.0
 :Spec Lead: Matt Broadstone
 :Advisory Group: \A. Jesse Jiryu Davis
 :Approver(s): Bernie Hackett, David Golden, Jeff Yemin, Matt Broadstone, A. Jesse Jiryu Davis
@@ -65,11 +65,13 @@ Seedlist Discovery
 ------------------
 
 In this preprocessing step, the driver will query the DNS server for SRV
-records on ``{hostname}.{domainname}``, prefixed with ``_mongodb._tcp.``:
-``_mongodb._tcp.{hostname}.{domainname}``. This DNS query is expected to
-respond with one or more SRV records. From the DNS result, the driver now MUST
-behave the same as if an ``mongodb://`` URI was provided with all the host
-names and port numbers that were returned as part of the DNS SRV query result.
+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}``. This DNS query
+is expected to respond with one or more SRV records. The driver MUST add all the host
+names and port numbers that were returned as part of the DNS SRV query result to the
+seedlist.
 
 The priority and weight fields in returned SRV records MUST be ignored.
 
@@ -274,6 +276,10 @@ SRV records.
 ChangeLog
 =========
 
+2021-09-15 - 1.5.0
+    Clarify that service name only defaults to ``mongodb``, and should be
+    defined by the ``srvServiceName`` URI option.
+
 2021-04-15 - 1.4.0
     Adding in behaviour for load balancer mode.
 
diff --git a/source/initial-dns-seedlist-discovery/tests/replica-set/srv-service-name.json b/source/initial-dns-seedlist-discovery/tests/replica-set/srv-service-name.json
@@ -0,0 +1,16 @@
+{
+  "uri": "mongodb+srv://test1.test.build.10gen.cc/?srvServiceName=customname",
+  "seeds": [
+    "localhost.test.build.10gen.cc:27017",
+    "localhost.test.build.10gen.cc:27018"
+  ],
+  "hosts": [
+    "localhost:27017",
+    "localhost:27018",
+    "localhost:27019"
+  ],
+  "options": {
+    "ssl": true,
+    "srvServiceName": "customname"
+  }
+}
diff --git a/source/initial-dns-seedlist-discovery/tests/replica-set/srv-service-name.yml b/source/initial-dns-seedlist-discovery/tests/replica-set/srv-service-name.yml
@@ -0,0 +1,11 @@
+uri: "mongodb+srv://test1.test.build.10gen.cc/?srvServiceName=customname"
+seeds:
+    - localhost.test.build.10gen.cc:27017
+    - localhost.test.build.10gen.cc:27018
+hosts:
+    - localhost:27017
+    - localhost:27018
+    - localhost:27019
+options:
+    ssl: true
+    srvServiceName: "customname"
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
@@ -9,8 +9,8 @@ Polling SRV Records for mongos Discovery
 :Author: Derick Rethans
 :Status: Accepted
 :Type: Standards
-:Last Modified: 2018-11-29
-:Version: 1.0
+:Last Modified: 2021-09-15
+:Version: 1.1.0
 :Spec Lead: David Golden
 
 .. contents::
@@ -79,8 +79,10 @@ 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 ``_mongodb._tcp.``:
-  ``_mongodb._tcp.{hostname}.{domainname}``.
+  ``{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:
@@ -227,4 +229,6 @@ No future work is expected.
 Changelog
 =========
 
-No changes yet.
+2021-09-15 - 1.1.0
+    Clarify that service name only defaults to ``mongodb``, and should be
+    defined by the ``srvServiceName`` URI option.
diff --git a/source/uri-options/tests/srv-service-name-option.json b/source/uri-options/tests/srv-service-name-option.json
@@ -0,0 +1,24 @@
+{
+  "tests": [
+    {
+      "description": "SRV URI with custom srvServiceName",
+      "uri": "mongodb+srv://test1.test.build.10gen.cc/?srvServiceName=customname",
+      "valid": true,
+      "warning": false,
+      "hosts": null,
+      "auth": null,
+      "options": {
+        "srvServiceName": "customname"
+      }
+    },
+    {
+      "description": "Non-SRV URI with custom srvServiceName",
+      "uri": "mongodb://example.com/?srvServiceName=customname",
+      "valid": false,
+      "warning": true,
+      "hosts": null,
+      "auth": null,
+      "options": {}
+    }
+  ]
+}
diff --git a/source/uri-options/tests/srv-service-name-option.yml b/source/uri-options/tests/srv-service-name-option.yml
@@ -0,0 +1,16 @@
+tests:
+    - description: "SRV URI with custom srvServiceName"
+      uri: "mongodb+srv://test1.test.build.10gen.cc/?srvServiceName=customname"
+      valid: true
+      warning: false
+      hosts: ~
+      auth: ~
+      options:
+          srvServiceName: "customname"
+    - description: "Non-SRV URI with custom srvServiceName"
+      uri: "mongodb://example.com/?srvServiceName=customname"
+      valid: false
+      warning: true
+      hosts: ~
+      auth: ~
+      options: {}
diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.rst
@@ -3,15 +3,15 @@ URI Options Specification
 =========================
 
 :Spec Title: URI Options Specification
-:Spec Version: 1.7.1
+:Spec Version: 1.8.0
 :Author: Sam Rossi
 :Spec Lead: Bernie Hackett
 :Advisory Group: Scott L'Hommedieu
 :Approver(s): Cailin Nelson, Jeff Yemin, Matt Broadstone, Dan Pasette, Prashant Mital, Spencer Jackson
 :Informed: drivers@
 :Status: Accepted (Could be Draft, Accepted, Rejected, Final, or Replaced)
 :Type: Standards
-:Last Modified: 2021-09-13
+:Last Modified: 2021-09-15
 
 
 **Abstract**
@@ -71,6 +71,14 @@ is specified with an SRV URI, because the URI may resolve to multiple
 hosts. The driver MUST allow specifying ``directConnection=false`` URI
 option with an SRV URI.
 
+Non-SRV URI with srvServiceName URI option
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The driver MUST report an error if the ``srvServiceName`` URI option is
+specified with a non-SRV URI (i.e. ``mongodb://``) because SRV lookup
+only occurs with SRV URIs. The driver MUST allow specifying the ``srvServiceName``
+URI option with an SRV URI.
+
 Multiple seeds with directConnection URI option
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -208,7 +216,7 @@ pertaining to URI options apply here.
      - non-negative integer
      - defined in the `Connection Pooling spec`_
      - required for drivers with connection pools
-     - The number of connections the driver should create and maintain in the pool even when no operations are occurring. This count includes connections which are currently checked out. 
+     - The number of connections the driver should create and maintain in the pool even when no operations are occurring. This count includes connections which are currently checked out.
 
    * - readConcernLevel
      - any string (`to allow for forwards compatibility with the server <https://github.com/mongodb/specifications/blob/master/source/read-write-concern/read-write-concern.rst#unknown-levels-and-additional-options-for-string-based-readconcerns>`_)
@@ -269,6 +277,14 @@ pertaining to URI options apply here.
      - no
      - 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
 
+   * - srvServiceName
+     - a valid SRV service name according to `RFC 6335 <https://datatracker.ietf.org/doc/html/rfc6335#section-5.1>`_; can be longer than 15 characters as long as the 63 (62 with prepended underscore)
+       character DNS query limit is not surpassed
+     - "mongodb"
+     - no
+     - the service name to use for SRV lookup in `initial DNS seedlist discovery <../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.rst>`_
+       and `SRV polling <../polling-srv-records-for-mongos-discovery/polling-srv-records-for-mongos-discovery.rst>`_
+
    * - ssl
      - "true" or "false"
      - same as "tls"
@@ -455,6 +471,7 @@ this specification MUST be updated to reflect those changes.
 Changes
 -------
 
+- 2021-09-15 Add srvServiceName option
 - 2021-09-13 Fix link to load balancer spec
 - 2021-04-15 Adding in behaviour for load balancer mode.
 - 2021-04-08 Updated to refer to hello and legacy hello
