From 14d964a4c853f12476001f672898bb77fdb3345f Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Wed, 8 May 2024 21:04:32 -0500 Subject: [PATCH 1/3] Rename source/uri-options/tests/README.rst to source/uri-options/tests/README.md --- source/uri-options/tests/{README.rst => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename source/uri-options/tests/{README.rst => README.md} (100%) diff --git a/source/uri-options/tests/README.rst b/source/uri-options/tests/README.md similarity index 100% rename from source/uri-options/tests/README.rst rename to source/uri-options/tests/README.md From d8ee3e3a3fc7240b4fb0c34e38dac3d84f2d1053 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Wed, 8 May 2024 21:04:51 -0500 Subject: [PATCH 2/3] Rename source/uri-options/uri-options.rst to source/uri-options/uri-options.md --- source/uri-options/tests/README.rst | 54 +++++++++++++++++++ .../{uri-options.rst => uri-options.md} | 0 2 files changed, 54 insertions(+) create mode 100644 source/uri-options/tests/README.rst rename source/uri-options/{uri-options.rst => uri-options.md} (100%) diff --git a/source/uri-options/tests/README.rst b/source/uri-options/tests/README.rst new file mode 100644 index 0000000000..f6a128bba9 --- /dev/null +++ b/source/uri-options/tests/README.rst @@ -0,0 +1,54 @@ +======================= +URI Options Tests +======================= + +The YAML and JSON files in this directory tree are platform-independent tests +that drivers can use to prove their conformance to the URI Options spec. + +These tests use the same format as the Connection String spec tests. + +Version +------- + +Files in the "specifications" repository have no version scheme. They are not +tied to a MongoDB server version. + +Format +------ + +Each YAML file contains an object with a single ``tests`` key. This key is an +array of test case objects, each of which have the following keys: + +- ``description``: A string describing the test. +- ``uri``: A string containing the URI to be parsed. +- ``valid``: A boolean indicating if the URI should be considered valid. +- ``warning``: A boolean indicating whether URI parsing should emit a warning. +- ``hosts``: Included for compatibility with the Connection String spec tests. This will always be ``~``. +- ``auth``: Included for compatibility with the Connection String spec tests. This will always be ``~``. +- ``options``: An object containing key/value pairs for each parsed query string + option. + +If a test case includes a null value for one of these keys (e.g. ``auth: ~``, +``hosts: ~``), no assertion is necessary. This both simplifies parsing of the +test files (keys should always exist) and allows flexibility for drivers that +might substitute default values *during* parsing (e.g. omitted ``hosts`` could be +parsed as ``["localhost"]``). + +The ``valid`` and ``warning`` fields are boolean in order to keep the tests +flexible. We are not concerned with asserting the format of specific error or +warnings messages strings. + +Under normal circumstances, it should not be necessary to specify both +``valid: false`` and ``warning: true``. Typically, a URI test case will either +yield an error (e.g. options conflict) or a warning (e.g. invalid type or value +for an option), but not both. + +Use as unit tests +================= + +Testing whether a URI is valid or not requires testing whether URI parsing (or +MongoClient construction) causes a warning due to a URI option being invalid and asserting that the +options parsed from the URI match those listed in the ``options`` field. + +Note that there are tests for each of the options marked as optional; drivers will need to implement +logic to skip over the optional tests that they don’t implement. diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.md similarity index 100% rename from source/uri-options/uri-options.rst rename to source/uri-options/uri-options.md From fc190f087e37c9eab5d91c57e45f6deab415cd66 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Wed, 8 May 2024 21:17:19 -0500 Subject: [PATCH 3/3] DRIVERS-2789 Convert URI Options Spec to Markdown --- .../connection-string-spec.md | 3 +- source/index.md | 1 + .../tests/README.md | 2 +- source/ocsp-support/tests/README.rst | 2 +- .../unified-test-format.md | 4 +- source/uri-options/tests/README.md | 69 +- source/uri-options/tests/README.rst | 54 -- source/uri-options/uri-options.md | 747 +++++------------- source/uri-options/uri-options.rst | 4 + 9 files changed, 245 insertions(+), 641 deletions(-) delete mode 100644 source/uri-options/tests/README.rst create mode 100644 source/uri-options/uri-options.rst diff --git a/source/connection-string/connection-string-spec.md b/source/connection-string/connection-string-spec.md index 5d051f4e47..3c558ef3cc 100644 --- a/source/connection-string/connection-string-spec.md +++ b/source/connection-string/connection-string-spec.md @@ -232,8 +232,7 @@ Unsupported value for "fsync" : "ifPossible" ### Repeated Keys If a key is repeated and the corresponding data type is not a List then the precedence of which key value pair will be -used is undefined except where defined otherwise by the -[URI options spec](https://github.com/mongodb/specifications/blob/master/source/uri-options/uri-options.rst). +used is undefined except where defined otherwise by the [URI options spec](../uri-options/uri-options.md). Where possible, a warning SHOULD be raised to inform the user that multiple options were found for the same value. diff --git a/source/index.md b/source/index.md index ae4d3ebf1d..1cf3d47ce7 100644 --- a/source/index.md +++ b/source/index.md @@ -32,5 +32,6 @@ - [Server Monitoring](server-discovery-and-monitoring/server-monitoring.md) - [Server Selection](server-selection/server-selection.md) - [Server Selection Test Plan](server-selection/server-selection-tests.md) +- [URI Options Specification](uri-options/uri-options.md) - [Unified Test Format](unified-test-format/unified-test-format.md) - [Wire Compression in Drivers](compression/OP_COMPRESSED.md) diff --git a/source/initial-dns-seedlist-discovery/tests/README.md b/source/initial-dns-seedlist-discovery/tests/README.md index 5b86b22200..50a77cb3f8 100644 --- a/source/initial-dns-seedlist-discovery/tests/README.md +++ b/source/initial-dns-seedlist-discovery/tests/README.md @@ -92,7 +92,7 @@ These YAML and JSON files contain the following fields: - `hosts`: the discovered topology's list of hosts once SDAM completes a scan - `numHosts`: the expected number of hosts discovered once SDAM completes a scan. This is mainly used to test `srvMaxHosts`, since randomly selected hosts cannot be deterministically asserted. -- `options`: the parsed [URI options](../../uri-options/uri-options.rst) as discovered from the +- `options`: the parsed [URI options](../../uri-options/uri-options.md) as discovered from the [Connection String](../../connection-string/connection-string-spec.md)'s "Connection Options" component and SRV resolution (e.g. TXT records, implicit `tls` default). - `parsed_options`: additional, parsed options from other diff --git a/source/ocsp-support/tests/README.rst b/source/ocsp-support/tests/README.rst index cbb8b6b9c4..263ec7a1f1 100644 --- a/source/ocsp-support/tests/README.rst +++ b/source/ocsp-support/tests/README.rst @@ -14,7 +14,7 @@ drivers can use to prove their conformance to the OCSP Support specification. These tests MUST BE implemented by all drivers. Additional YAML and JSON tests have also been added to the `URI -Options Tests <../../uri-options/tests/README.rst>`__. Specifically, +Options Tests <../../uri-options/tests/README.md>`__. Specifically, the `TLS Options Test <../../uri-options/tests/tls-options.yml>`__ has been updated with additional tests for the new URI options ``tlsDisableOCSPEndpointCheck`` and ``tlsDisableCertificateRevocationCheck``. diff --git a/source/unified-test-format/unified-test-format.md b/source/unified-test-format/unified-test-format.md index 4086c3b92f..01924be309 100644 --- a/source/unified-test-format/unified-test-format.md +++ b/source/unified-test-format/unified-test-format.md @@ -409,13 +409,13 @@ The structure of this object is as follows: - `uriOptions`: Optional object. Additional URI options to apply to the test suite's connection string that is used to create this client. Any keys in this object MUST override conflicting keys in the connection string. - Documentation for supported options may be found in the [URI Options](../uri-options/uri-options.rst) spec, with one + Documentation for supported options may be found in the [URI Options](../uri-options/uri-options.md) spec, with one notable exception: if `readPreferenceTags` is specified in this object, the key will map to an array of strings, each representing a tag set, since it is not feasible to define multiple `readPreferenceTags` keys in the object. Note also that when specifying `directConnection` as true, the connection string used to instantiate a client MUST only have a single seed and MUST NOT specify the `replicaSet` option. See the - [URI Options spec](../uri-options/uri-options.rst#directconnection-uri-option-with-multiple-seeds-or-srv-uri) for + [URI Options spec](../uri-options/uri-options.md#directconnection-uri-option-with-multiple-seeds-or-srv-uri) for more information. Any field in `uriOptions` may be a [$$placeholder](#placeholder) document and the test runner MUST support replacing diff --git a/source/uri-options/tests/README.md b/source/uri-options/tests/README.md index f6a128bba9..bda997051a 100644 --- a/source/uri-options/tests/README.md +++ b/source/uri-options/tests/README.md @@ -1,54 +1,43 @@ -======================= -URI Options Tests -======================= +# URI Options Tests -The YAML and JSON files in this directory tree are platform-independent tests -that drivers can use to prove their conformance to the URI Options spec. +The YAML and JSON files in this directory tree are platform-independent tests that drivers can use to prove their +conformance to the URI Options spec. These tests use the same format as the Connection String spec tests. -Version -------- +## Version -Files in the "specifications" repository have no version scheme. They are not -tied to a MongoDB server version. +Files in the "specifications" repository have no version scheme. They are not tied to a MongoDB server version. -Format ------- +## Format -Each YAML file contains an object with a single ``tests`` key. This key is an -array of test case objects, each of which have the following keys: +Each YAML file contains an object with a single `tests` key. This key is an array of test case objects, each of which +have the following keys: -- ``description``: A string describing the test. -- ``uri``: A string containing the URI to be parsed. -- ``valid``: A boolean indicating if the URI should be considered valid. -- ``warning``: A boolean indicating whether URI parsing should emit a warning. -- ``hosts``: Included for compatibility with the Connection String spec tests. This will always be ``~``. -- ``auth``: Included for compatibility with the Connection String spec tests. This will always be ``~``. -- ``options``: An object containing key/value pairs for each parsed query string - option. +- `description`: A string describing the test. +- `uri`: A string containing the URI to be parsed. +- `valid`: A boolean indicating if the URI should be considered valid. +- `warning`: A boolean indicating whether URI parsing should emit a warning. +- `hosts`: Included for compatibility with the Connection String spec tests. This will always be `~`. +- `auth`: Included for compatibility with the Connection String spec tests. This will always be `~`. +- `options`: An object containing key/value pairs for each parsed query string option. -If a test case includes a null value for one of these keys (e.g. ``auth: ~``, -``hosts: ~``), no assertion is necessary. This both simplifies parsing of the -test files (keys should always exist) and allows flexibility for drivers that -might substitute default values *during* parsing (e.g. omitted ``hosts`` could be -parsed as ``["localhost"]``). +If a test case includes a null value for one of these keys (e.g. `auth: ~`, `hosts: ~`), no assertion is necessary. This +both simplifies parsing of the test files (keys should always exist) and allows flexibility for drivers that might +substitute default values *during* parsing (e.g. omitted `hosts` could be parsed as `["localhost"]`). -The ``valid`` and ``warning`` fields are boolean in order to keep the tests -flexible. We are not concerned with asserting the format of specific error or -warnings messages strings. +The `valid` and `warning` fields are boolean in order to keep the tests flexible. We are not concerned with asserting +the format of specific error or warnings messages strings. -Under normal circumstances, it should not be necessary to specify both -``valid: false`` and ``warning: true``. Typically, a URI test case will either -yield an error (e.g. options conflict) or a warning (e.g. invalid type or value -for an option), but not both. +Under normal circumstances, it should not be necessary to specify both `valid: false` and `warning: true`. Typically, a +URI test case will either yield an error (e.g. options conflict) or a warning (e.g. invalid type or value for an +option), but not both. -Use as unit tests -================= +### Use as unit tests -Testing whether a URI is valid or not requires testing whether URI parsing (or -MongoClient construction) causes a warning due to a URI option being invalid and asserting that the -options parsed from the URI match those listed in the ``options`` field. +Testing whether a URI is valid or not requires testing whether URI parsing (or MongoClient construction) causes a +warning due to a URI option being invalid and asserting that the options parsed from the URI match those listed in the +`options` field. -Note that there are tests for each of the options marked as optional; drivers will need to implement -logic to skip over the optional tests that they don’t implement. +Note that there are tests for each of the options marked as optional; drivers will need to implement logic to skip over +the optional tests that they don't implement. diff --git a/source/uri-options/tests/README.rst b/source/uri-options/tests/README.rst deleted file mode 100644 index f6a128bba9..0000000000 --- a/source/uri-options/tests/README.rst +++ /dev/null @@ -1,54 +0,0 @@ -======================= -URI Options Tests -======================= - -The YAML and JSON files in this directory tree are platform-independent tests -that drivers can use to prove their conformance to the URI Options spec. - -These tests use the same format as the Connection String spec tests. - -Version -------- - -Files in the "specifications" repository have no version scheme. They are not -tied to a MongoDB server version. - -Format ------- - -Each YAML file contains an object with a single ``tests`` key. This key is an -array of test case objects, each of which have the following keys: - -- ``description``: A string describing the test. -- ``uri``: A string containing the URI to be parsed. -- ``valid``: A boolean indicating if the URI should be considered valid. -- ``warning``: A boolean indicating whether URI parsing should emit a warning. -- ``hosts``: Included for compatibility with the Connection String spec tests. This will always be ``~``. -- ``auth``: Included for compatibility with the Connection String spec tests. This will always be ``~``. -- ``options``: An object containing key/value pairs for each parsed query string - option. - -If a test case includes a null value for one of these keys (e.g. ``auth: ~``, -``hosts: ~``), no assertion is necessary. This both simplifies parsing of the -test files (keys should always exist) and allows flexibility for drivers that -might substitute default values *during* parsing (e.g. omitted ``hosts`` could be -parsed as ``["localhost"]``). - -The ``valid`` and ``warning`` fields are boolean in order to keep the tests -flexible. We are not concerned with asserting the format of specific error or -warnings messages strings. - -Under normal circumstances, it should not be necessary to specify both -``valid: false`` and ``warning: true``. Typically, a URI test case will either -yield an error (e.g. options conflict) or a warning (e.g. invalid type or value -for an option), but not both. - -Use as unit tests -================= - -Testing whether a URI is valid or not requires testing whether URI parsing (or -MongoClient construction) causes a warning due to a URI option being invalid and asserting that the -options parsed from the URI match those listed in the ``options`` field. - -Note that there are tests for each of the options marked as optional; drivers will need to implement -logic to skip over the optional tests that they don’t implement. diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index 8af993bc88..971d1f630c 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -1,555 +1,220 @@ -========================= -URI Options Specification -========================= +# URI Options Specification -:Status: Accepted -:Minimum Server Version: N/A +- Status: Accepted -**Abstract** ------------- +- Minimum Server Version: N/A -Historically, URI options have been defined in individual specs, and -drivers have defined any additional options independently of one another. -Because of the frustration due to there not being a single place where -all of the URI options are defined, this spec aims to do just that—namely, -provide a canonical list of URI options that each driver defines. +## Abstract + +Historically, URI options have been defined in individual specs, and drivers have defined any additional options +independently of one another. Because of the frustration due to there not being a single place where all of the URI +options are defined, this spec aims to do just that—namely, provide a canonical list of URI options that each driver +defines. **THIS SPEC DOES NOT REQUIRE DRIVERS TO MAKE ANY BREAKING CHANGES.** -**META** --------- - -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 `_. - -**Specification** ------------------ - -Conflicting TLS options -~~~~~~~~~~~~~~~~~~~~~~~ - -Per the `Connection String spec <../connection-string/connection-string-spec.md#repeated-keys>`__, -the behavior of duplicates of most URI options is undefined. However, due -to the security implications of certain options, drivers MUST raise an -error to the user during parsing if any of the following circumstances -occur: - -1. Both ``tlsInsecure`` and ``tlsAllowInvalidCertificates`` appear in the - URI options. -2. Both ``tlsInsecure`` and ``tlsAllowInvalidHostnames`` appear in the - URI options. -3. Both ``tlsInsecure`` and ``tlsDisableOCSPEndpointCheck`` appear in - the URI options. -4. Both ``tlsInsecure`` and ``tlsDisableCertificateRevocationCheck`` - appear in the URI options. -5. Both ``tlsAllowInvalidCertificates`` and - ``tlsDisableOCSPEndpointCheck`` appear in the URI options. -6. Both ``tlsAllowInvalidCertificates`` and - ``tlsDisableCertificateRevocationCheck`` appear in the URI options. -7. Both ``tlsDisableOCSPEndpointCheck`` and - ``tlsDisableCertificateRevocationCheck`` appear in the URI options. -8. All instances of ``tls`` and ``ssl`` in the URI options do not have the - same value. If all instances of ``tls`` and ``ssl`` have the same - value, an error MUST NOT be raised. - - -directConnection URI option with multiple seeds or SRV URI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The driver MUST report an error if the ``directConnection=true`` URI option -is specified with multiple seeds. - -The driver MUST report an error if the ``directConnection=true`` URI option -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. - - -srvServiceName and srvMaxHosts URI options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -For URI option validation pertaining to ``srvServiceName`` and ``srvMaxHosts``, -please see the -`Initial DNS Seedlist Discovery spec <../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#uri-validation>`_ -for details. +## META + +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). + +## Specification + +### Conflicting TLS options + +Per the [Connection String spec](../connection-string/connection-string-spec.md#repeated-keys), the behavior of +duplicates of most URI options is undefined. However, due to the security implications of certain options, drivers MUST +raise an error to the user during parsing if any of the following circumstances occur: + +1. Both `tlsInsecure` and `tlsAllowInvalidCertificates` appear in the URI options. +2. Both `tlsInsecure` and `tlsAllowInvalidHostnames` appear in the URI options. +3. Both `tlsInsecure` and `tlsDisableOCSPEndpointCheck` appear in the URI options. +4. Both `tlsInsecure` and `tlsDisableCertificateRevocationCheck` appear in the URI options. +5. Both `tlsAllowInvalidCertificates` and `tlsDisableOCSPEndpointCheck` appear in the URI options. +6. Both `tlsAllowInvalidCertificates` and `tlsDisableCertificateRevocationCheck` appear in the URI options. +7. Both `tlsDisableOCSPEndpointCheck` and `tlsDisableCertificateRevocationCheck` appear in the URI options. +8. All instances of `tls` and `ssl` in the URI options do not have the same value. If all instances of `tls` and `ssl` + have the same value, an error MUST NOT be raised. + +### directConnection URI option with multiple seeds or SRV URI +The driver MUST report an error if the `directConnection=true` URI option is specified with multiple seeds. -Load Balancer Mode -~~~~~~~~~~~~~~~~~~ - -For URI option validation in Load Balancer mode (i.e. ``loadBalanced=true``), -please see the -`Load Balancer spec <../load-balancers/load-balancers.md#uri-validation>`_ for -details. - - -SOCKS5 options -~~~~~~~~~~~~~~ - -For URI option validation pertaining to ``proxyHost``, ``proxyPort``, -``proxyUsername`` and ``proxyPassword`` please see the -`SOCKS5 support spec`_ for details. - - -List of specified options -~~~~~~~~~~~~~~~~~~~~~~~~~ - -Each driver option below MUST be implemented in each driver unless marked -as optional. If an option is marked as optional, a driver MUST meet any -conditions specified for leaving it out if it is not included. If a driver -already provides the option under a different name, the driver MAY -implement the old and new names as aliases. All keys and values MUST be -encoded in UTF-8. All integer options are 32-bit unless specified otherwise. -Note that all requirements and recommendations described in the `Connection -String spec -<../connection-string/connection-string-spec.md>`_ -pertaining to URI options apply here. - -.. _uri.options: - -.. list-table:: - :header-rows: 1 - :widths: 1 1 1 1 1 - - * - Name - - Accepted Values - - Default Value - - Optional to implement? - - Description - - * - appname - - any string that meets the criteria listed in the `handshake spec - `_ - - no appname specified - - no - - Passed into the server in the client metadata as part of the - connection handshake - - * - authMechanism - - any string; valid values are defined in the `auth spec - <../auth/auth.md#supported-authentication-methods>`_ - - None; default values for authentication exist for constructing authentication credentials per the - `auth spec <../auth/auth.md#supported-authentication-methods>`_, - but there is no default for the URI option itself. - - no - - The authentication mechanism method to use for connection to the - server - - * - authMechanismProperties - - comma separated key:value pairs, e.g. "opt1:val1,opt2:val2" - - no properties specified - - no - - Additional options provided for authentication (e.g. to enable hostname canonicalization for GSSAPI) - - * - authSource - - any string - - None; default values for authentication exist for constructing authentication credentials per the - `auth spec <../auth/auth.md#supported-authentication-methods>`_, - but there is no default for the URI option itself. - - no - - The database that connections should authenticate against - - * - compressors - - comma separated list of strings, e.g. "snappy,zlib" - - defined in `compression spec <../compression/OP_COMPRESSED.md#compressors>`_ - - no - - The list of allowed compression types for wire protocol messages - sent or received from the server - - * - connectTimeoutMS - - non-negative integer; 0 means "no timeout" - - 10,000 ms (unless a driver already has a different default) - - no - - Amount of time to wait for a single TCP socket connection to the - server to be established before erroring; note that this applies to - `SDAM hello and legacy hello operations `_ - - * - directConnection - - "true" or "false" - - defined in `SDAM spec `__ - - no - - Whether to connect to the deployment in Single topology. - - * - heartbeatFrequencyMS - - integer greater than or equal to 500 - - defined in `SDAM spec `__ - - no - - the interval between regular server monitoring checks - - * - journal - - "true" or "false" - - no "j" field specified - - no - - Default write concern "j" field for the client - - * - loadBalanced - - "true" or "false" - - defined in `Load Balancer spec <../load-balancers/load-balancers.md#loadbalanced>`__ - - no - - Whether the driver is connecting to a load balancer. - - * - localThresholdMS - - non-negative integer; 0 means 0 ms (i.e. the fastest eligible server - must be selected) - - defined in the `server selection spec <../server-selection/server-selection.md#localthresholdms>`__ - - no - - The amount of time beyond the fastest round trip time that a given - server’s round trip time can take and still be eligible for server selection - - * - maxIdleTimeMS - - non-negative integer; 0 means no minimum - - defined in the `Connection Pooling spec`_ - - required for drivers with connection pools - - The amount of time a connection can be idle before it's closed - - * - maxPoolSize - - non-negative integer; 0 means no maximum - - defined in the `Connection Pooling spec`_ - - required for drivers with connection pools - - The maximum number of clients or connections able to be created by a pool at a given time. This count includes connections which are currently checked out. - - * - maxConnecting - - positive integer - - defined in the `Connection Pooling spec`_ - - required for drivers with connection pools - - The maximum number of Connections a Pool may be establishing concurrently. - - * - maxStalenessSeconds - - -1 (no max staleness check) or integer >= 90 - - defined in `max staleness spec <../max-staleness/max-staleness.md#api>`_ - - no - - The maximum replication lag, in wall clock time, that a secondary can suffer and still be eligible for server selection - - * - minPoolSize - - 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. - - * - proxyHost - - any string - - defined in the `SOCKS5 support spec`_ - - no - - The IPv4/IPv6 address or domain name of a SOCKS5 proxy server used for connecting to MongoDB services. - - * - proxyPort - - non-negative integer - - defined in the `SOCKS5 support spec`_ - - no - - The port of the SOCKS5 proxy server specified in ``proxyHost``. - - * - proxyUsername - - any string - - defined in the `SOCKS5 support spec`_ - - no - - The username for username/password authentication to the SOCKS5 proxy server specified in ``proxyHost``. - - * - proxyPassword - - any string - - defined in the `SOCKS5 support spec`_ - - no - - The password for username/password authentication to the SOCKS5 proxy server specified in ``proxyHost``. - - * - readConcernLevel - - any string (`to allow for forwards compatibility with the server `_) - - no read concern specified - - no - - Default read concern for the client - - * - readPreference - - any string; currently supported values are defined in the `server selection spec <../server-selection/server-selection.md#mode>`__, but must be lowercase camelCase, e.g. "primaryPreferred" - - defined in `server selection spec <../server-selection/server-selection.md#mode>`__ - - no - - Default read preference for the client (excluding tags) - - * - readPreferenceTags - - comma-separated key:value pairs (e.g. "dc:ny,rack:1" and "dc:ny) - - can be specified multiple times; each instance of this key is a - separate tag set - - no tags specified - - no - - Default read preference tags for the client; only valid if the read preference mode is not primary - - The order of the tag sets in the read preference is the same as the order they are specified in the URI - - * - replicaSet - - any string - - no replica set name provided - - no - - The name of the replica set to connect to - - * - retryReads - - "true" or "false" - - defined in `retryable reads spec <../retryable-reads/retryable-reads.md#retryreads>`_ - - no - - Enables retryable reads on server 3.6+ - - * - retryWrites - - "true" or "false" - - defined in `retryable writes spec <../retryable-writes/retryable-writes.md#retrywrites>`_ - - no - - Enables retryable writes on server 3.6+ - - * - serverMonitoringMode - - "stream", "poll", or "auto" - - defined in `SDAM spec `__ - - required for multi-threaded or asynchronous drivers - - Configures which server monitoring protocol to use. - - * - 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. - - * - 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 `_ - - "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>`_ - - * - ssl - - "true" or "false" - - same as "tls" - - no - - alias of "tls"; required to ensure that Atlas connection strings continue to work - - * - - timeoutMS - - non-negative integer; 0 or unset means no timeout - - Defined in `Client Side Operations Timeout: timeoutMS <../client-side-operations-timeout/client-side-operations-timeout.md#timeoutms>`_. - - no - - Time limit for the full execution of an operation - - * - 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 - - - * - tlsAllowInvalidCertificates - - "true" or "false" - - error on invalid certificates - - required if the driver’s language/runtime allows bypassing hostname verification - - Specifies whether or not the driver should error when the server’s TLS certificate is invalid - - * - tlsAllowInvalidHostnames - - "true" or "false" - - error on invalid certificates - - required if the driver’s language/runtime allows bypassing hostname verification - - Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate - - * - tlsCAFile - - any string - - no certificate authorities specified - - required if the driver's language/runtime allows non-global configuration - - Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection - - * - tlsCertificateKeyFile - - any string - - no client certificate specified - - required if the driver's language/runtime allows non-global configuration - - Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated - - * - tlsCertificateKeyFilePassword - - any string - - no password specified - - required if the driver's language/runtime allows non-global configuration - - Password to decrypt the client private key to be used for TLS connections - - * - tlsDisableCertificateRevocationCheck - - "true" or "false" - - false i.e. driver will reach check a certificate's revocation status - - Yes - - Controls whether or not the driver will check a certificate's - revocation status via CRLs or OCSP. See the `OCSP Support Spec - <../ocsp-support/ocsp-support.rst#tlsDisableCertificateRevocationCheck>`__ - for additional information. - - * - tlsDisableOCSPEndpointCheck - - "true" or "false" - - false i.e. driver will reach out to OCSP endpoints `if needed - <../ocsp-support/ocsp-support.rst#id1>`__. - - Yes - - Controls whether or not the driver will reach out to OCSP - endpoints if needed. See the `OCSP Support Spec - <../ocsp-support/ocsp-support.rst#tlsDisableOCSPEndpointCheck>`__ - for additional information. - - * - tlsInsecure - - "true" or "false" - - No TLS constraints are relaxed - - no - - Relax TLS constraints as much as possible (e.g. allowing invalid certificates or hostname mismatches); drivers must document the exact constraints which are relaxed by this option being true - - * - w - - non-negative integer or string - - no "w" value specified - - no - - Default write concern "w" field for the client - - * - waitQueueTimeoutMS - - positive number - - defined in the `Connection Pooling spec`_ - - required for drivers with connection pools, with exceptions described in the `Connection Pooling spec`_ - - 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 check out a connection from a server's - connection pool before timing out - - * - wTimeoutMS - - non-negative 64-bit 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>`_ - - Default write concern "wtimeout" field for the client - - * - zlibCompressionLevel - - integer between -1 and 9 (inclusive) - - -1 (default compression level of the driver) - - no - - Specifies the level of compression when using zlib to compress wire - protocol messages; -1 signifies the default level, 0 signifies no - compression, 1 signifies the fastest speed, and 9 signifies the - best compression - -**Test Plan** -------------- - -Tests are implemented and described in the `tests `_ directory - -**Design Rationale** ---------------------- - -Why allow drivers to provide the canonical names as aliases to existing options? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -First and foremost, this spec aims not to introduce any breaking changes -to drivers. Forcing a driver to change the name of an option that it -provides will break any applications that use the old option. Moreover, it -is already possible to provide duplicate options in the URI by specifying -the same option more than once; drivers can use the same semantics to -resolve the conflicts as they did before, whether it’s raising an error, -using the first option provided, using the last option provided, or simply -telling users that the behavior is not defined. - -Why use "tls" as the prefix instead of "ssl" for related options? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Technically speaking, drivers already only support TLS, which supersedes -SSL. While SSL is commonly used in parlance to refer to TLS connections, -the fact remains that SSL is a weaker cryptographic protocol than TLS, and -we want to accurately reflect the strict requirements that drivers have in -ensuring the security of a TLS connection. - -Why use the names "tlsAllowInvalidHostnames" and "tlsAllowInvalidCertificates"? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The "tls" prefix is used for the same reasons described above. The use of the -terms "AllowInvalidHostnames" and "AllowInvalidCertificates" is an intentional -choice in order to convey the inherent unsafety of these options, which should -only be used for testing purposes. Additionally, both the server and the shell -use "AllowInvalid" for their equivalent options. - -Why provide multiple implementation options for the insecure TLS options (i.e. "tlsInsecure" vs. "tlsAllowInvalidHostnames"/"tlsAllowInvalidCertificates"? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Some TLS libraries (e.g. Go’s standard library implementation) do not provide -the ability to distinguish between allow invalid certificates and hostnames, -meaning they either both are allowed, or neither are. However, when more -granular options are available, it’s better to expose these to the user to -allow them to relax security constraints as little as they need. - - -Why leave the decision up to drivers to enable TLS implicitly when TLS options are present? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It can be useful to turn on TLS implicitly when options such as "tlsCAFile" are -present and "tls" is not present. However, with options such as -"tlsAllowInvalidHostnames", some drivers may not have the ability to -distinguish between "false" being provided and the option not being specified. -To keep the implicit enabling of TLS consistent between such options, we defer -the decision to enable TLS based on the presence of "tls"-prefixed options -(besides "tls" itself) to drivers. - -**Reference Implementations** ------------------------------ +The driver MUST report an error if the `directConnection=true` URI option 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. + +### srvServiceName and srvMaxHosts URI options + +For URI option validation pertaining to `srvServiceName` and `srvMaxHosts`, please see the +[Initial DNS Seedlist Discovery spec](../initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md#uri-validation) +for details. + +### Load Balancer Mode + +For URI option validation in Load Balancer mode (i.e. `loadBalanced=true`), please see the +[Load Balancer spec](../load-balancers/load-balancers.md#uri-validation) for details. + +### SOCKS5 options + +For URI option validation pertaining to `proxyHost`, `proxyPort`, `proxyUsername` and `proxyPassword` please see the +[SOCKS5 support spec](../socks5-support/socks5.rst#mongoclient-configuration) for details. + +### List of specified options + +Each driver option below MUST be implemented in each driver unless marked as optional. If an option is marked as +optional, a driver MUST meet any conditions specified for leaving it out if it is not included. If a driver already +provides the option under a different name, the driver MAY implement the old and new names as aliases. All keys and +values MUST be encoded in UTF-8. All integer options are 32-bit unless specified otherwise. Note that all requirements +and recommendations described in the [Connection String spec](../connection-string/connection-string-spec.md) pertaining +to URI options apply here. + +
+ +| Name | Accepted Values | Default Value | Optional to implement? | Description | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| appname | any string that meets the criteria listed in the [handshake spec](../mongodb-handshake/handshake.rst#client-application-name) | no appname specified | no | Passed into the server in the client metadata as part of the connection handshake | +| authMechanism | any string; valid values are defined in the [auth spec](../auth/auth.md#supported-authentication-methods) | None; default values for authentication exist for constructing authentication credentials per the [auth spec](../auth/auth.md#supported-authentication-methods), but there is no default for the URI option itself. | no | The authentication mechanism method to use for connection to the server | +| authMechanismProperties | comma separated key:value pairs, e.g. "opt1:val1,opt2:val2" | no properties specified | no | Additional options provided for authentication (e.g. to enable hostname canonicalization for GSSAPI) | +| authSource | any string | None; default values for authentication exist for constructing authentication credentials per the [auth spec](../auth/auth.md#supported-authentication-methods), but there is no default for the URI option itself. | no | The database that connections should authenticate against | +| compressors | comma separated list of strings, e.g. "snappy,zlib" | defined in [compression spec](../compression/OP_COMPRESSED.md#compressors) | no | The list of allowed compression types for wire protocol messages sent or received from the server | +| connectTimeoutMS | non-negative integer; 0 means "no timeout" | 10,000 ms (unless a driver already has a different default) | no | Amount of time to wait for a single TCP socket connection to the server to be established before erroring; note that this applies to [SDAM hello and legacy hello operations](../mongodb-handshake/handshake.rst) | +| directConnection | "true" or "false" | defined in [SDAM spec](../server-discovery-and-monitoring/server-discovery-and-monitoring.rst#initial-topology-type) | no | Whether to connect to the deployment in Single topology. | +| heartbeatFrequencyMS | integer greater than or equal to 500 | defined in [SDAM spec](../server-discovery-and-monitoring/server-discovery-and-monitoring.rst#heartbeatfrequencyms) | no | the interval between regular server monitoring checks | +| journal | "true" or "false" | no "j" field specified | no | Default write concern "j" field for the client | +| loadBalanced | "true" or "false" | defined in [Load Balancer spec](../load-balancers/load-balancers.md#loadbalanced) | no | Whether the driver is connecting to a load balancer. | +| localThresholdMS | non-negative integer; 0 means 0 ms (i.e. the fastest eligible server must be selected) | defined in the [server selection spec](../server-selection/server-selection.md#localthresholdms) | no | The amount of time beyond the fastest round trip time that a given server’s round trip time can take and still be eligible for server selection | +| maxIdleTimeMS | non-negative integer; 0 means no minimum | defined in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | required for drivers with connection pools | The amount of time a connection can be idle before it's closed | +| maxPoolSize | non-negative integer; 0 means no maximum | defined in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | required for drivers with connection pools | The maximum number of clients or connections able to be created by a pool at a given time. This count includes connections which are currently checked out. | +| maxConnecting | positive integer | defined in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | required for drivers with connection pools | The maximum number of Connections a Pool may be establishing concurrently. | +| maxStalenessSeconds | -1 (no max staleness check) or integer >= 90 | defined in [max staleness spec](../max-staleness/max-staleness.md#api) | no | The maximum replication lag, in wall clock time, that a secondary can suffer and still be eligible for server selection | +| minPoolSize | non-negative integer | defined in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | 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. | +| proxyHost | any string | defined in the [SOCKS5 support spec](../socks5-support/socks5.rst#mongoclient-configuration) | no | The IPv4/IPv6 address or domain name of a SOCKS5 proxy server used for connecting to MongoDB services. | +| proxyPort | non-negative integer | defined in the [SOCKS5 support spec](../socks5-support/socks5.rst#mongoclient-configuration) | no | The port of the SOCKS5 proxy server specified in `proxyHost`. | +| proxyUsername | any string | defined in the [SOCKS5 support spec](../socks5-support/socks5.rst#mongoclient-configuration) | no | The username for username/password authentication to the SOCKS5 proxy server specified in `proxyHost`. | +| proxyPassword | any string | defined in the [SOCKS5 support spec](../socks5-support/socks5.rst#mongoclient-configuration) | no | The password for username/password authentication to the SOCKS5 proxy server specified in `proxyHost`. | +| readConcernLevel | any string ([to allow for forwards compatibility with the server](../read-write-concern/read-write-concern.rst#unknown-levels-and-additional-options-for-string-based-readconcerns)) | no read concern specified | no | Default read concern for the client | +| readPreference | any string; currently supported values are defined in the [server selection spec](../server-selection/server-selection.md#mode), but must be lowercase camelCase, e.g. "primaryPreferred" | defined in [server selection spec](../server-selection/server-selection.md#mode) | no | Default read preference for the client (excluding tags) | +| readPreferenceTags | comma-separated key:value pairs (e.g. "dc:ny,rack:1" and "dc:ny)

can be specified multiple times; each instance of this key is a separate tag set | no tags specified | no | Default read preference tags for the client; only valid if the read preference mode is not primary

The order of the tag sets in the read preference is the same as the order they are specified in the URI | +| replicaSet | any string | no replica set name provided | no | The name of the replica set to connect to | +| retryReads | "true" or "false" | defined in [retryable reads spec](../retryable-reads/retryable-reads.md#retryreads) | no | Enables retryable reads on server 3.6+ | +| retryWrites | "true" or "false" | defined in [retryable writes spec](../retryable-writes/retryable-writes.md#retrywrites) | no | Enables retryable writes on server 3.6+ | +| serverMonitoringMode | "stream", "poll", or "auto" | defined in [SDAM spec](../server-discovery-and-monitoring/server-discovery-and-monitoring.rst#servermonitoringmode) | required for multi-threaded or asynchronous drivers | Configures which server monitoring protocol to use. | +| 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. | +| 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) | +| 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 | +| tlsAllowInvalidCertificates | "true" or "false" | error on invalid certificates | required if the driver’s language/runtime allows bypassing hostname verification | Specifies whether or not the driver should error when the server’s TLS certificate is invalid | +| tlsAllowInvalidHostnames | "true" or "false" | error on invalid certificates | required if the driver’s language/runtime allows bypassing hostname verification | Specifies whether or not the driver should error when there is a mismatch between the server’s hostname and the hostname specified by the TLS certificate | +| tlsCAFile | any string | no certificate authorities specified | required if the driver's language/runtime allows non-global configuration | Path to file with either a single or bundle of certificate authorities to be considered trusted when making a TLS connection | +| tlsCertificateKeyFile | any string | no client certificate specified | required if the driver's language/runtime allows non-global configuration | Path to the client certificate file or the client private key file; in the case that they both are needed, the files should be concatenated | +| tlsCertificateKeyFilePassword | any string | no password specified | required if the driver's language/runtime allows non-global configuration | Password to decrypt the client private key to be used for TLS connections | +| tlsDisableCertificateRevocationCheck | "true" or "false" | false i.e. driver will reach check a certificate's revocation status | Yes | Controls whether or not the driver will check a certificate's revocation status via CRLs or OCSP. See the [OCSP Support Spec](../ocsp-support/ocsp-support.rst#tlsDisableCertificateRevocationCheck) for additional information. | +| tlsDisableOCSPEndpointCheck | "true" or "false" | false i.e. driver will reach out to OCSP endpoints [if needed](../ocsp-support/ocsp-support.rst#id1). | Yes | Controls whether or not the driver will reach out to OCSP endpoints if needed. See the [OCSP Support Spec](../ocsp-support/ocsp-support.rst#tlsDisableOCSPEndpointCheck) for additional information. | +| tlsInsecure | "true" or "false" | No TLS constraints are relaxed | no | Relax TLS constraints as much as possible (e.g. allowing invalid certificates or hostname mismatches); drivers must document the exact constraints which are relaxed by this option being true | +| w | non-negative integer or string | no "w" value specified | no | Default write concern "w" field for the client | +| waitQueueTimeoutMS | positive number | defined in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | required for drivers with connection pools, with exceptions described in the [Connection Pooling spec](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1) | 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 check out a connection from a server's connection pool before timing out | +| wTimeoutMS | non-negative 64-bit 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)

Default write concern "wtimeout" field for the client | +| zlibCompressionLevel | integer between -1 and 9 (inclusive) | -1 (default compression level of the driver) | no | Specifies the level of compression when using zlib to compress wire protocol messages; -1 signifies the default level, 0 signifies no compression, 1 signifies the fastest speed, and 9 signifies the best compression | + +## Test Plan + +Tests are implemented and described in the [tests](tests/README.md) directory. + +## Design Rationale + +### Why allow drivers to provide the canonical names as aliases to existing options? + +First and foremost, this spec aims not to introduce any breaking changes to drivers. Forcing a driver to change the name +of an option that it provides will break any applications that use the old option. Moreover, it is already possible to +provide duplicate options in the URI by specifying the same option more than once; drivers can use the same semantics to +resolve the conflicts as they did before, whether it's raising an error, using the first option provided, using the last +option provided, or simply telling users that the behavior is not defined. + +### Why use "tls" as the prefix instead of "ssl" for related options? + +Technically speaking, drivers already only support TLS, which supersedes SSL. While SSL is commonly used in parlance to +refer to TLS connections, the fact remains that SSL is a weaker cryptographic protocol than TLS, and we want to +accurately reflect the strict requirements that drivers have in ensuring the security of a TLS connection. + +### Why use the names "tlsAllowInvalidHostnames" and "tlsAllowInvalidCertificates"? + +The "tls" prefix is used for the same reasons described above. The use of the terms "AllowInvalidHostnames" and +"AllowInvalidCertificates" is an intentional choice in order to convey the inherent unsafety of these options, which +should only be used for testing purposes. Additionally, both the server and the shell use "AllowInvalid" for their +equivalent options. + +### Why provide multiple implementation options for the insecure TLS options (i.e. "tlsInsecure" vs. "tlsAllowInvalidHostnames"/"tlsAllowInvalidCertificates"? + +Some TLS libraries (e.g. Go's standard library implementation) do not provide the ability to distinguish between allow +invalid certificates and hostnames, meaning they either both are allowed, or neither are. However, when more granular +options are available, it's better to expose these to the user to allow them to relax security constraints as little as +they need. + +### Why leave the decision up to drivers to enable TLS implicitly when TLS options are present? + +It can be useful to turn on TLS implicitly when options such as "tlsCAFile" are present and "tls" is not present. +However, with options such as "tlsAllowInvalidHostnames", some drivers may not have the ability to distinguish between +"false" being provided and the option not being specified. To keep the implicit enabling of TLS consistent between such +options, we defer the decision to enable TLS based on the presence of "tls"-prefixed options (besides "tls" itself) to +drivers. + +## Reference Implementations Ruby and Python -**Security Implication** ------------------------- +## Security Implication -Each of the "insecure" TLS options (i.e. "tlsInsecure", -"tlsAllowInvalidHostnames", "tlsAllowInvalidCertificates", -"tlsDisableOCSPEndpointCheck", and -"tlsDisableCertificateRevocationCheck") default to the more secure -option when TLS is enabled. In order to be backwards compatible with -existing driver behavior, neither TLS nor authentication is enabled by +Each of the "insecure" TLS options (i.e. "tlsInsecure", "tlsAllowInvalidHostnames", "tlsAllowInvalidCertificates", +"tlsDisableOCSPEndpointCheck", and "tlsDisableCertificateRevocationCheck") default to the more secure option when TLS is +enabled. In order to be backwards compatible with existing driver behavior, neither TLS nor authentication is enabled by default. -**Future Work** ---------------- - -This specification is intended to represent the current state of drivers URI -options rather than be a static description of the options at the time it was -written. Whenever another specification is written or modified in a way that -changes the name or the semantics of a URI option or adds a new URI option, -this specification MUST be updated to reflect those changes. - -Changelog ---------- - -:2023-08-21: Add serverMonitoringMode option. -:2022-10-05: Remove spec front matter and reformat changelog. -:2022-01-19: Add the timeoutMS option and deprecate some existing timeout options -:2021-12-14: Add SOCKS5 options -:2021-11-08: Add maxConnecting option. -:2021-10-14: Add srvMaxHosts option. Merge headings discussing URI validation - for directConnection option. -: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 -:2020-03-03: Add tlsDisableCertificateRevocationCheck option -:2020-02-26: Add tlsDisableOCSPEndpointCheck option -:2019-09-08: Add retryReads option -:2019-04-26: authSource and authMechanism have no default value -:2019-02-04: Specified errors for conflicting TLS-related URI options -:2019-01-25: Updated to reflect new Connection Monitoring and Pooling Spec - ----- - -.. _Connection Pooling spec: https://github.com/mongodb/specifications/blob/master/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool-options-1 -.. _SOCKS5 support spec: https://github.com/mongodb/specifications/blob/master/source/socks5-support/socks5.rst#mongoclient-configuration +## Future Work + +This specification is intended to represent the current state of drivers URI options rather than be a static description +of the options at the time it was written. Whenever another specification is written or modified in a way that changes +the name or the semantics of a URI option or adds a new URI option, this specification MUST be updated to reflect those +changes. + +## Changelog + +- 2024-05-08: Migrated from reStructuredText to Markdown. + +- 2023-08-21: Add serverMonitoringMode option. + +- 2022-10-05: Remove spec front matter and reformat changelog. + +- 2022-01-19: Add the timeoutMS option and deprecate some existing timeout options + +- 2021-12-14: Add SOCKS5 options + +- 2021-11-08: Add maxConnecting option. + +- 2021-10-14: Add srvMaxHosts option. Merge headings discussing URI validation\ + for directConnection option. + +- 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 + +- 2020-03-03: Add tlsDisableCertificateRevocationCheck option + +- 2020-02-26: Add tlsDisableOCSPEndpointCheck option + +- 2019-09-08: Add retryReads option + +- 2019-04-26: authSource and authMechanism have no default value + +- 2019-02-04: Specified errors for conflicting TLS-related URI options + +- 2019-01-25: Updated to reflect new Connection Monitoring and Pooling Spec + +______________________________________________________________________ diff --git a/source/uri-options/uri-options.rst b/source/uri-options/uri-options.rst new file mode 100644 index 0000000000..00c450c4a3 --- /dev/null +++ b/source/uri-options/uri-options.rst @@ -0,0 +1,4 @@ + +.. note:: + This specification has been converted to Markdown and renamed to + `uri-options.md `_.