Merge branch 'master' into DRIVERS-2789-command-logging-and-monitoring

.github/workflows/lint.yml

@@ -14,16 +14,7 @@ jobs:
  steps:
  - uses: actions/checkout@v4
  - uses: actions/setup-python@v4
-
- # ref: https://github.com/pre-commit/action
- - uses: pre-commit/action@v3.0.0
- - name: Help message if pre-commit fail
- if: ${{ failure() }}
+ - name: "Run pre-commit"
  run: |
- echo "You can install pre-commit hooks to automatically run formatting"
- echo "on each commit with:"
- echo " pre-commit install"
- echo "or you can run by hand on staged files with"
- echo " pre-commit run"
- echo "or after-the-fact on already committed files with"
- echo " pre-commit run --all-files --hook-stage manual"
+ pip install -U -q pre-commit
+ pre-commit run --all-files --hook-stage manual

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
- rev: v4.5.0
+ rev: v4.6.0
  hooks:
  - id: check-case-conflict
  - id: check-executables-have-shebangs
@@ -15,7 +15,7 @@ repos:
 # We use the Python version instead of the original version which seems to require Docker
 # https://github.com/koalaman/shellcheck-precommit
 - repo: https://github.com/shellcheck-py/shellcheck-py
- rev: v0.9.0.6
+ rev: v0.10.0.1
  hooks:
  - id: shellcheck
  name: shellcheck
@@ -43,7 +43,7 @@ repos:
  [mdformat-gfm, mdformat-frontmatter, mdformat-footnote, mdformat-gfm-alerts]
 
 - repo: https://github.com/tcort/markdown-link-check
- rev: v3.11.2
+ rev: v3.12.2
  hooks:
  - id: markdown-link-check
  args: ["-c", "markdown_link_config.json"]
@@ -57,7 +57,7 @@ repos:
  stages: [manual]
 
 - repo: https://github.com/python-jsonschema/check-jsonschema
- rev: 0.27.3
+ rev: 0.28.4
  hooks:
  - id: check-github-workflows
 
@@ -69,10 +69,10 @@ repos:
  - id: rst-inline-touching-normal
 
 - repo: https://github.com/codespell-project/codespell
- rev: "v2.2.6"
+ rev: "v2.3.0"
  hooks:
  - id: codespell
- args: ["-L", "fle,re-use,merchantibility,synching,crate,nin,infinit,te"]
+ args: ["-L", "fle,re-use,merchantibility,synching,crate,nin,infinit,te,checkin"]
  exclude: |
  (?x)^(.*\.rst
  )$

.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration file for MkDocs projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.12"
+
+mkdocs:
+ configuration: mkdocs.yml
+
+# Optionally declare the Python requirements required to build your docs
+python:
+ install:
+ - requirements: source/requirements.txt

README.md

@@ -1,77 +1,13 @@
 # MongoDB Specifications
 
+[![Documentation Status](https://readthedocs.org/projects/specifications/badge/?version=latest)](http://specifications.readthedocs.io/en/latest/?badge=latest)
+
 This repository holds in progress and completed specification for features of MongoDB, Drivers, and associated products.
 Also contained is a rudimentary system for producing these documents.
 
 ## Driver Mantras
 
-When developing specifications -- and the drivers themselves -- we follow the following principles:
-
-### Strive to be idiomatic, but favor consistency
-
-Drivers attempt to provide the easiest way to work with MongoDB in a given language ecosystem, while specifications
-attempt to provide a consistent behavior and experience across all languages. Drivers should strive to be as idiomatic
-as possible while meeting the specification and staying true to the original intent.
-
-### No Knobs
-
-Too many choices stress out users. Whenever possible, we aim to minimize the number of configuration options exposed to
-users. In particular, if a typical user would have no idea how to choose a correct value, we pick a good default instead
-of adding a knob.
-
-### Topology agnostic
-
-Users test and deploy against different topologies or might scale up from replica sets to sharded clusters. Applications
-should never need to use the driver differently based on topology type.
-
-### Where possible, depend on server to return errors
-
-The features available to users depend on a server's version, topology, storage engine and configuration. So that
-drivers don't need to code and test all possible variations, and to maximize forward compatibility, always let users
-attempt operations and let the server error when it can't comply. Exceptions should be rare: for cases where the server
-might not error and correctness is at stake.
-
-### Minimize administrative helpers
-
-Administrative helpers are methods for admin tasks, like user creation. These are rarely used and have maintenance costs
-as the server changes the administrative API. Don't create administrative helpers; let users rely on "RunCommand" for
-administrative commands.
-
-### Check wire version, not server version
-
-When determining server capabilities within the driver, rely only on the maxWireVersion in the hello response, not on
-the X.Y.Z server version. An exception is testing server development releases, as the server bumps wire version early
-and then continues to add features until the GA.
-
-### When in doubt, use "MUST" not "SHOULD" in specs
-
-Specs guide our work. While there are occasionally valid technical reasons for drivers to differ in their behavior,
-avoid encouraging it with a wishy-washy "SHOULD" instead of a more assertive "MUST".
-
-### Defy augury
-
-While we have some idea of what the server will do in the future, don't design features with those expectations in mind.
-Design and implement based on what is expected in the next release.
-
-Case Study: In designing OP_MSG, we held off on designing support for Document Sequences in Replies in drivers until the
-server would support it. We subsequently decided not to implement that feature in the server.
-
-### The best way to see what the server does is to test it
-
-For any unusual case, relying on documentation or anecdote to anticipate the server's behavior in different
-versions/topologies/etc. is error-prone. The best way to check the server's behavior is to use a driver or the shell and
-test it directly.
-
-### Drivers follow semantic versioning
-
-Drivers should follow X.Y.Z versioning, where breaking API changes require a bump to X. See
-[semver.org](https://semver.org/) for more.
-
-### Backward breaking behavior changes and semver
-
-Backward breaking behavior changes can be more dangerous and disruptive than backward breaking API changes. When
-thinking about the implications of a behavior change, ask yourself what could happen if a user upgraded your library
-without carefully reading the changelog and/or adequately testing the change.
+See [Documentation](./source/driver-mantras.md).
 
 ## Writing Documents
 
@@ -110,13 +46,11 @@ entire test with a note (e.g. *Removed*).
 
 ## Building Documents
 
-We build the docs in `text` mode in CI to make sure they build without errors. We don't actually support building html,
-since we rely on GitHub to render the documents. To build locally, run:
+We use [mkdocs](https://www.mkdocs.org/) to render the documentation. To see a live view of the documentation, run:
 
 ```bash
-pip install sphinx
-cd source 
-sphinx-build -W -b text . docs_build index.rst
+pip install mkdocs
+mkdocs serve
 ```
 
 ## Converting to JSON

mkdocs.yml

@@ -0,0 +1,4 @@
+site_name: MongoDB Specifications
+docs_dir: source
+nav:
+ - 'index.md'

source/auth/auth.md

@@ -1,4 +1,4 @@
-# Driver Authentication
+# Authentication
 
 - Status: Accepted
 - Minimum Server Version: 2.6
@@ -148,7 +148,7 @@ Drivers MUST follow the following steps for an authentication handshake:
 
 If the authentication handshake fails for a socket, drivers MUST mark the server Unknown and clear the server's
 connection pool. (See [Q & A](#q--a) below and SDAM's
-[Why mark a server Unknown after an auth error](/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#why-mark-a-server-unknown-after-an-auth-error)
+[Why mark a server Unknown after an auth error](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#why-mark-a-server-unknown-after-an-auth-error)
 for rationale.)
 
 All blocking operations executed as part of the authentication handshake MUST apply timeouts per the
@@ -1201,15 +1201,6 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
 
 #### [MongoCredential](#mongocredential) Properties
 
-> [!NOTE]
-> Drivers MUST NOT url-decode the entire `authMechanismProperties` given in an connection string when the
-> `authMechanism` is `MONGODB-OIDC`. This is because the `TOKEN_RESOURCE` itself will typically be a URL and may contain
-> a `,` character. The values of the individual `authMechanismProperties` MUST still be url-decoded when given as part
-> of the connection string, and MUST NOT be url-decoded when not given as part of the connection string, such as through
-> a `MongoClient` or `Credential` property. Drivers MUST parse the `TOKEN_RESOURCE` by splitting only on the first `:`
-> character. Drivers MUST document that users must url-encode `TOKEN_RESOURCE` when it is provided in the connection
-> string and it contains and of the special characters in \[`,`, `+`, `&`, `%`\].
-
 - username\
  MAY be specified. Its meaning varies depending on the OIDC provider integration used.
 
@@ -1233,7 +1224,9 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
  - TOKEN_RESOURCE\
  The URI of the target resource. If `TOKEN_RESOURCE` is provided and `ENVIRONMENT` is not one of
  `["azure", "gcp"]` or `TOKEN_RESOURCE` is not provided and `ENVIRONMENT` is one of `["azure", "gcp"]`, the driver
- MUST raise an error.
+ MUST raise an error. Note: because the `TOKEN_RESOURCE` is often itself a URL, drivers MUST document that a
+ `TOKEN_RESOURCE` with a comma `,` must be given as a `MongoClient` configuration and not as part of the connection
+ string, and that the `TOKEN_RESOURCE` value can contain a colon `:` character.
 
  - OIDC_CALLBACK\
  An [OIDC Callback](#oidc-callback) that returns OIDC credentials. Drivers MAY allow the user to
@@ -1260,7 +1253,7 @@ in the MONGODB-OIDC specification, including sections or blocks that specificall
  performed after SRV record resolution, if applicable. This property is only required for drivers that support the
  [Human Authentication Flow](#human-authentication-flow).
 
-<div id="built-in-provider-integrations">
+<span id="built-in-provider-integrations"/>
 
 #### Built-in OIDC Environment Integrations
 
@@ -2049,6 +2042,8 @@ to EC2 instance metadata in ECS, for security reasons, Amazon states it's best p
 
 ## Changelog
 
+- 2024-05-29: Disallow comma character when `TOKEN_RESOURCE` is given in a connection string.
+
 - 2024-05-03: Clarify timeout behavior for OIDC machine callback. Add `serverless:forbid` to OIDC unified tests. Add an
  additional prose test for the behavior of `ALLOWED_HOSTS`.