DRIVERS-2789 Connection String Spec to Markdown (#1515)

Author: blink1073

source/collection-management/tests/README.md

@@ -0,0 +1,4 @@
+# Collection Management Tests
+
+This directory contains tests for collection management. They are implemented in the
+[Unified Test Format](../../unified-test-format/unified-test-format.md).

source/collection-management/tests/README.rst

@@ -0,0 +1,55 @@
+# Connection String Tests
+
+The YAML and JSON files in this directory tree are platform-independent tests that drivers can use to prove their
+conformance to the Connection String Spec.
+
+As the spec is primarily concerned with parsing the parts of a URI, these tests do not focus on host and option
+validation. Where necessary, the tests use options known to be (un)supported by drivers to assert behavior such as
+issuing a warning on repeated option keys. As such these YAML tests are in no way a replacement for more thorough
+testing. However, they can provide an initial verification of your implementation.
+
+## 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 (independent of whether or not the URI is
+  valid).
+- `hosts`: An array of host objects, each of which have the following keys:
+  - `type`: A string denoting the type of host. Possible values are "ipv4", "ip_literal", "hostname", and "unix".
+    Asserting the type is *optional*.
+  - `host`: A string containing the parsed host.
+  - `port`: An integer containing the parsed port number.
+- `auth`: An object containing the following keys:
+  - `username`: A string containing the parsed username. For auth mechanisms that do not utilize a password, this may be
+    the entire `userinfo` token (as discussed in [RFC 2396](https://www.ietf.org/rfc/rfc2396.txt)).
+  - `password`: A string containing the parsed password.
+  - `db`: A string containing the parsed authentication database. For legacy implementations that support namespaces
+    (databases and collections) this may be the full namespace eg: `<db>.<coll>`
+- `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: ~`, `port: ~`), 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 `port` could be parsed as 27017).
+
+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.
+
+### Use as unit tests
+
+Testing whether a URI is valid or not should simply be a matter of checking whether URI parsing (or MongoClient
+construction) raises an error or exception. Testing for emitted warnings may require more legwork (e.g. configuring a
+log handler and watching for output).
+
+Not all drivers may be able to directly assert the hosts, auth credentials, and options. Doing so may require exposing
+the driver's URI parsing component.
+
+The file `valid-db-with-dotted-name.yml` is a special case for testing drivers that allow dotted namespaces, instead of
+only database names, in the Auth Database portion of the URI.

source/connection-string/connection-string-spec.md

@@ -26,8 +26,8 @@ maintain seed lists at an application level.
 This specification builds on the `Connection String`_ specification. It adds a
 new protocol scheme and modifies how the `Host Information`_ is interpreted.
 
-.. _`Connection String`: ../connection-string/connection-string-spec.rst
-.. _`Host Information`: ../connection-string/connection-string-spec.rst#host-information
+.. _`Connection String`: ../connection-string/connection-string-spec.md
+.. _`Host Information`: ../connection-string/connection-string-spec.md#host-information
 
 META
 ====
@@ -196,7 +196,7 @@ A Client MUST use options specified in the Connection String, and options
 passed in as parameters in code to the MongoClient constructor (or equivalent
 API for each driver), to override options provided through TXT records.
 
-.. _`Connection String spec`: ../connection-string/connection-string-spec.rst#defining-connection-options
+.. _`Connection String spec`: ../connection-string/connection-string-spec.md#defining-connection-options
 
 If any connection string option in a TXT record is incorrectly formatted, a
 Client MUST throw a parse exception.

source/connection-string/connection-string-spec.rst

@@ -116,7 +116,7 @@ These YAML and JSON files contain the following fields:
 - ``comment``: a comment to indicate why a test would fail.
 - ``ping``: if false, the test runner should not run a "ping" operation.
 
-.. _`Connection String`: ../../connection-string/connection-string-spec.rst
+.. _`Connection String`: ../../connection-string/connection-string-spec.md
 .. _`URI options`: ../../uri-options/uri-options.rst
 
 For each YAML file:

source/connection-string/tests/README.md

@@ -30,7 +30,7 @@ document are to be interpreted as described in
 Conflicting TLS options
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Per the `Connection String spec <https://github.com/mongodb/specifications/blob/master/source/connection-string/connection-string-spec.rst#repeated-keys>`__,
+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
@@ -104,7 +104,7 @@ 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
-<https://github.com/mongodb/specifications/blob/master/source/connection-string/connection-string-spec.rst>`_
+<../connection-string/connection-string-spec.md>`_
 pertaining to URI options apply here.
 
 .. _uri.options: