From 2665a24c996e676167092768ec960cdcc4482d17 Mon Sep 17 00:00:00 2001 From: Steven Silvester Date: Thu, 12 Sep 2024 07:47:23 -0500 Subject: [PATCH] DRIVERS-2789 Finish Markdown Spec Migration (#1656) DRIVERS-2789 Finish Markdown Spec Migration --- .github/workflows/lint.yml | 12 + .gitignore | 3 +- .pre-commit-config.yaml | 5 - README.md | 4 + markdown_link_config.json | 15 - mkdocs.yml | 8 +- scripts/check_anchors/check-anchors.sh | 8 - scripts/check_anchors/index.js | 34 -- scripts/check_anchors/package-lock.json | 447 ------------------ scripts/check_anchors/package.json | 15 - source/auth/auth.md | 12 +- source/bson-decimal128/decimal128.md | 2 +- .../causal-consistency/causal-consistency.md | 2 +- source/change-streams/tests/README.md | 4 +- .../client-side-encryption.md | 32 +- source/client-side-encryption/subtype6.md | 5 +- source/client-side-encryption/tests/README.md | 79 ++-- .../client-side-operations-timeout.md | 2 +- .../tests/README.md | 9 +- .../connection-monitoring-and-pooling.md | 74 +-- .../tests/README.md | 2 +- .../tests/cmap-format/README.md | 4 +- .../tests/README.md | 3 +- .../tests/README.rst | 178 ------- source/crud/bulk-write.md | 8 +- source/crud/crud.md | 2 + .../unified/insertOne-dots_and_dollars.yml | 2 +- source/enumerate-databases.md | 6 +- source/index-management/index-management.md | 4 +- .../initial-dns-seedlist-discovery.md | 4 +- source/logging/logging.md | 2 +- source/message/OP_MSG.md | 2 + source/mongodb-handshake/handshake.md | 4 + source/ocsp-support/ocsp-support.md | 17 +- ...olling-srv-records-for-mongos-discovery.md | 4 +- .../read-write-concern/read-write-concern.md | 6 +- source/requirements.txt | 3 +- source/retryable-reads/retryable-reads.md | 7 +- .../listCollectionObjects-serverErrors.yml | 2 +- .../tests/unified/listCollectionObjects.yml | 2 +- .../listDatabaseObjects-serverErrors.yml | 2 +- .../tests/unified/listDatabaseObjects.yml | 2 +- source/retryable-writes/retryable-writes.md | 2 +- source/run-command/run-command.md | 6 +- .../run-command/tests/unified/runCommand.yml | 2 +- .../server-discovery-and-monitoring.md | 32 +- .../server-monitoring.md | 42 +- .../tests/README.md | 2 +- source/server-selection/server-selection.md | 43 +- source/serverless-testing/README.md | 2 +- .../transactions/tests/legacy-test-format.md | 10 +- source/transactions/transactions.md | 2 +- .../unified-test-format.md | 41 +- source/uri-options/uri-options.md | 98 ++-- 54 files changed, 332 insertions(+), 988 deletions(-) delete mode 100644 scripts/check_anchors/check-anchors.sh delete mode 100644 scripts/check_anchors/index.js delete mode 100644 scripts/check_anchors/package-lock.json delete mode 100644 scripts/check_anchors/package.json delete mode 100644 source/connections-survive-step-down/tests/README.rst diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 02f52237e2..c197600b6e 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -18,3 +18,15 @@ jobs: run: | pip install -U -q pre-commit pre-commit run --all-files --hook-stage manual + + mkdocs: + runs-on: ubuntu-latest + timeout-minutes: 5 + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + - name: Setup dependencies + run: pip install -r source/requirements.txt + - name: Check docs + run: mkdocs build --strict diff --git a/.gitignore b/.gitignore index 6511848e54..3ef5ceb240 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,5 @@ codereview.rc docs_build .pytest_cache node_modules -package-lock.json \ No newline at end of file +package-lock.json +site \ No newline at end of file diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 9695a9cdda..4da390e54b 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -36,11 +36,6 @@ repos: name: generate-index entry: python3 scripts/generate_index.py language: system - - id: check-anchors - name: check-anchors - types: [markdown] - entry: bash scripts/check_anchors/check-anchors.sh - language: node - id: markdown-link-format-check name: markdown-link-format-check types: [markdown] diff --git a/README.md b/README.md index 3f88b2fa57..850944940b 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,10 @@ pip install mkdocs mkdocs serve ``` +To build the docs, use `mkdocs build`. + +In CI we verify that there are no warnings. To replicate locally, run `mkdocs build --strict`. + ## Converting to JSON There are many YAML to JSON converters. There are even several converters called `yaml2json` in NPM. Alas, we are not diff --git a/markdown_link_config.json b/markdown_link_config.json index 0e37fded84..69f0a8fbf7 100644 --- a/markdown_link_config.json +++ b/markdown_link_config.json @@ -1,20 +1,8 @@ { "ignorePatterns": [ - { - "pattern": "^/source/server-discovery-and-monitoring/server-discovery-and-monitoring.rst#" - }, { "pattern": "^#" }, - { - "pattern": "^../command-logging-and-monitoring/command-monitoring.rst#security" - }, - { - "pattern": "^logging/logging.rst#log-severity-levels" - }, - { - "pattern": "./enumerate-indexes.rst" - }, { "pattern": "^https://github.com/10gen/mongo-enterprise-modules" }, @@ -23,9 +11,6 @@ }, { "pattern": "cloudkms.googleapis.com" - }, - { - "pattern": "subtype6#intent-to-encrypt" } ] } diff --git a/mkdocs.yml b/mkdocs.yml index 80494b1761..1ecdb0a14a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -4,5 +4,11 @@ nav: - 'index.md' markdown_extensions: - admonition + - toc: + permalink:  plugins: - - gh-admonitions \ No newline at end of file + - gh-admonitions +validation: + absolute_links: warn + unrecognized_links: warn + anchors: warn \ No newline at end of file diff --git a/scripts/check_anchors/check-anchors.sh b/scripts/check_anchors/check-anchors.sh deleted file mode 100644 index 0179a54de8..0000000000 --- a/scripts/check_anchors/check-anchors.sh +++ /dev/null @@ -1,8 +0,0 @@ -#!/bin/bash -ex - -SCRIPT_DIR=$(dirname ${BASH_SOURCE[0]}) -SCRIPT_DIR="$( cd -- "$SCRIPT_DIR" &> /dev/null && pwd )" -pushd $SCRIPT_DIR -npm install -popd -node $SCRIPT_DIR/index.js "$@" \ No newline at end of file diff --git a/scripts/check_anchors/index.js b/scripts/check_anchors/index.js deleted file mode 100644 index d4ef6e5464..0000000000 --- a/scripts/check_anchors/index.js +++ /dev/null @@ -1,34 +0,0 @@ -const fs = require("fs"); -const showdown = require('showdown'); -const jsdom = require("jsdom"); - -showdown.setFlavor('github'); -const converter = new showdown.Converter(); - -const files = process.argv.slice(2); - -for (let path of files) { - console.log("Checking file", path); - const text = fs.readFileSync(path, {encoding: "utf-8"}); - const html = converter.makeHtml(text); - const dom = new jsdom.JSDOM(html); - const doc = dom.window.document; - const links = doc.querySelectorAll("a"); - const errors = []; - for (var i = 0; i < links.length; i++) { - var link = links[i].getAttribute("href"); - if (link.startsWith('#')) { - if (!doc.getElementById(link.slice(1))) { - console.log('Could not find', link); - errors.push(link) - } - } - } - if (errors.length > 0) { - const all = doc.querySelectorAll('*[id]'); - for (var i = 0; i < all.length; i ++ ) { - console.log(all[i].id); - } - process.exit(1); - } -} diff --git a/scripts/check_anchors/package-lock.json b/scripts/check_anchors/package-lock.json deleted file mode 100644 index 86329d794d..0000000000 --- a/scripts/check_anchors/package-lock.json +++ /dev/null @@ -1,447 +0,0 @@ -{ - "name": "check_anchors", - "version": "1.0.0", - "lockfileVersion": 3, - "requires": true, - "packages": { - "": { - "name": "check_anchors", - "version": "1.0.0", - "license": "Apache-2.0", - "dependencies": { - "jsdom": "^24.0.0", - "showdown": "^2.1.0" - } - }, - "node_modules/agent-base": { - "version": "7.1.0", - "resolved": "https://registry.npmjs.org/agent-base/-/agent-base-7.1.0.tgz", - "integrity": "sha512-o/zjMZRhJxny7OyEF+Op8X+efiELC7k7yOjMzgfzVqOzXqkBkWI79YoTdOtsuWd5BWhAGAuOY/Xa6xpiaWXiNg==", - "dependencies": { - "debug": "^4.3.4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/asynckit": { - "version": "0.4.0", - "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", - "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==" - }, - "node_modules/combined-stream": { - "version": "1.0.8", - "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", - "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", - "dependencies": { - "delayed-stream": "~1.0.0" - }, - "engines": { - "node": ">= 0.8" - } - }, - "node_modules/commander": { - "version": "9.5.0", - "resolved": "https://registry.npmjs.org/commander/-/commander-9.5.0.tgz", - "integrity": "sha512-KRs7WVDKg86PWiuAqhDrAQnTXZKraVcCc6vFdL14qrZ/DcWwuRo7VoiYXalXO7S5GKpqYiVEwCbgFDfxNHKJBQ==", - "engines": { - "node": "^12.20.0 || >=14" - } - }, - "node_modules/cssstyle": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/cssstyle/-/cssstyle-4.0.1.tgz", - "integrity": "sha512-8ZYiJ3A/3OkDd093CBT/0UKDWry7ak4BdPTFP2+QEP7cmhouyq/Up709ASSj2cK02BbZiMgk7kYjZNS4QP5qrQ==", - "dependencies": { - "rrweb-cssom": "^0.6.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/data-urls": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/data-urls/-/data-urls-5.0.0.tgz", - "integrity": "sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==", - "dependencies": { - "whatwg-mimetype": "^4.0.0", - "whatwg-url": "^14.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/debug": { - "version": "4.3.4", - "resolved": "https://registry.npmjs.org/debug/-/debug-4.3.4.tgz", - "integrity": "sha512-PRWFHuSU3eDtQJPvnNY7Jcket1j0t5OuOsFzPPzsekD52Zl8qUfFIPEiswXqIvHWGVHOgX+7G/vCNNhehwxfkQ==", - "dependencies": { - "ms": "2.1.2" - }, - "engines": { - "node": ">=6.0" - }, - "peerDependenciesMeta": { - "supports-color": { - "optional": true - } - } - }, - "node_modules/decimal.js": { - "version": "10.4.3", - "resolved": "https://registry.npmjs.org/decimal.js/-/decimal.js-10.4.3.tgz", - "integrity": "sha512-VBBaLc1MgL5XpzgIP7ny5Z6Nx3UrRkIViUkPUdtl9aya5amy3De1gsUUSB1g3+3sExYNjCAsAznmukyxCb1GRA==" - }, - "node_modules/delayed-stream": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", - "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", - "engines": { - "node": ">=0.4.0" - } - }, - "node_modules/entities": { - "version": "4.5.0", - "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", - "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", - "engines": { - "node": ">=0.12" - }, - "funding": { - "url": "https://github.com/fb55/entities?sponsor=1" - } - }, - "node_modules/form-data": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.0.tgz", - "integrity": "sha512-ETEklSGi5t0QMZuiXoA/Q6vcnxcLQP5vdugSpuAyi6SVGi2clPPp+xgEhuMaHC+zGgn31Kd235W35f7Hykkaww==", - "dependencies": { - "asynckit": "^0.4.0", - "combined-stream": "^1.0.8", - "mime-types": "^2.1.12" - }, - "engines": { - "node": ">= 6" - } - }, - "node_modules/html-encoding-sniffer": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-4.0.0.tgz", - "integrity": "sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==", - "dependencies": { - "whatwg-encoding": "^3.1.1" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/http-proxy-agent": { - "version": "7.0.2", - "resolved": "https://registry.npmjs.org/http-proxy-agent/-/http-proxy-agent-7.0.2.tgz", - "integrity": "sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==", - "dependencies": { - "agent-base": "^7.1.0", - "debug": "^4.3.4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/https-proxy-agent": { - "version": "7.0.4", - "resolved": "https://registry.npmjs.org/https-proxy-agent/-/https-proxy-agent-7.0.4.tgz", - "integrity": "sha512-wlwpilI7YdjSkWaQ/7omYBMTliDcmCN8OLihO6I9B86g06lMyAoqgoDpV0XqoaPOKj+0DIdAvnsWfyAAhmimcg==", - "dependencies": { - "agent-base": "^7.0.2", - "debug": "4" - }, - "engines": { - "node": ">= 14" - } - }, - "node_modules/iconv-lite": { - "version": "0.6.3", - "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", - "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", - "dependencies": { - "safer-buffer": ">= 2.1.2 < 3.0.0" - }, - "engines": { - "node": ">=0.10.0" - } - }, - "node_modules/is-potential-custom-element-name": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/is-potential-custom-element-name/-/is-potential-custom-element-name-1.0.1.tgz", - "integrity": "sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==" - }, - "node_modules/jsdom": { - "version": "24.0.0", - "resolved": "https://registry.npmjs.org/jsdom/-/jsdom-24.0.0.tgz", - "integrity": "sha512-UDS2NayCvmXSXVP6mpTj+73JnNQadZlr9N68189xib2tx5Mls7swlTNao26IoHv46BZJFvXygyRtyXd1feAk1A==", - "dependencies": { - "cssstyle": "^4.0.1", - "data-urls": "^5.0.0", - "decimal.js": "^10.4.3", - "form-data": "^4.0.0", - "html-encoding-sniffer": "^4.0.0", - "http-proxy-agent": "^7.0.0", - "https-proxy-agent": "^7.0.2", - "is-potential-custom-element-name": "^1.0.1", - "nwsapi": "^2.2.7", - "parse5": "^7.1.2", - "rrweb-cssom": "^0.6.0", - "saxes": "^6.0.0", - "symbol-tree": "^3.2.4", - "tough-cookie": "^4.1.3", - "w3c-xmlserializer": "^5.0.0", - "webidl-conversions": "^7.0.0", - "whatwg-encoding": "^3.1.1", - "whatwg-mimetype": "^4.0.0", - "whatwg-url": "^14.0.0", - "ws": "^8.16.0", - "xml-name-validator": "^5.0.0" - }, - "engines": { - "node": ">=18" - }, - "peerDependencies": { - "canvas": "^2.11.2" - }, - "peerDependenciesMeta": { - "canvas": { - "optional": true - } - } - }, - "node_modules/mime-db": { - "version": "1.52.0", - "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", - "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/mime-types": { - "version": "2.1.35", - "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", - "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", - "dependencies": { - "mime-db": "1.52.0" - }, - "engines": { - "node": ">= 0.6" - } - }, - "node_modules/ms": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.2.tgz", - "integrity": "sha512-sGkPx+VjMtmA6MX27oA4FBFELFCZZ4S4XqeGOXCv68tT+jb3vk/RyaKWP0PTKyWtmLSM0b+adUTEvbs1PEaH2w==" - }, - "node_modules/nwsapi": { - "version": "2.2.7", - "resolved": "https://registry.npmjs.org/nwsapi/-/nwsapi-2.2.7.tgz", - "integrity": "sha512-ub5E4+FBPKwAZx0UwIQOjYWGHTEq5sPqHQNRN8Z9e4A7u3Tj1weLJsL59yH9vmvqEtBHaOmT6cYQKIZOxp35FQ==" - }, - "node_modules/parse5": { - "version": "7.1.2", - "resolved": "https://registry.npmjs.org/parse5/-/parse5-7.1.2.tgz", - "integrity": "sha512-Czj1WaSVpaoj0wbhMzLmWD69anp2WH7FXMB9n1Sy8/ZFF9jolSQVMu1Ij5WIyGmcBmhk7EOndpO4mIpihVqAXw==", - "dependencies": { - "entities": "^4.4.0" - }, - "funding": { - "url": "https://github.com/inikulin/parse5?sponsor=1" - } - }, - "node_modules/psl": { - "version": "1.9.0", - "resolved": "https://registry.npmjs.org/psl/-/psl-1.9.0.tgz", - "integrity": "sha512-E/ZsdU4HLs/68gYzgGTkMicWTLPdAftJLfJFlLUAAKZGkStNU72sZjT66SnMDVOfOWY/YAoiD7Jxa9iHvngcag==" - }, - "node_modules/punycode": { - "version": "2.3.1", - "resolved": "https://registry.npmjs.org/punycode/-/punycode-2.3.1.tgz", - "integrity": "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==", - "engines": { - "node": ">=6" - } - }, - "node_modules/querystringify": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/querystringify/-/querystringify-2.2.0.tgz", - "integrity": "sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==" - }, - "node_modules/requires-port": { - "version": "1.0.0", - "resolved": "https://registry.npmjs.org/requires-port/-/requires-port-1.0.0.tgz", - "integrity": "sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==" - }, - "node_modules/rrweb-cssom": { - "version": "0.6.0", - "resolved": "https://registry.npmjs.org/rrweb-cssom/-/rrweb-cssom-0.6.0.tgz", - "integrity": "sha512-APM0Gt1KoXBz0iIkkdB/kfvGOwC4UuJFeG/c+yV7wSc7q96cG/kJ0HiYCnzivD9SB53cLV1MlHFNfOuPaadYSw==" - }, - "node_modules/safer-buffer": { - "version": "2.1.2", - "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", - "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==" - }, - "node_modules/saxes": { - "version": "6.0.0", - "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz", - "integrity": "sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==", - "dependencies": { - "xmlchars": "^2.2.0" - }, - "engines": { - "node": ">=v12.22.7" - } - }, - "node_modules/showdown": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/showdown/-/showdown-2.1.0.tgz", - "integrity": "sha512-/6NVYu4U819R2pUIk79n67SYgJHWCce0a5xTP979WbNp0FL9MN1I1QK662IDU1b6JzKTvmhgI7T7JYIxBi3kMQ==", - "dependencies": { - "commander": "^9.0.0" - }, - "bin": { - "showdown": "bin/showdown.js" - }, - "funding": { - "type": "individual", - "url": "https://www.paypal.me/tiviesantos" - } - }, - "node_modules/symbol-tree": { - "version": "3.2.4", - "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz", - "integrity": "sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==" - }, - "node_modules/tough-cookie": { - "version": "4.1.3", - "resolved": "https://registry.npmjs.org/tough-cookie/-/tough-cookie-4.1.3.tgz", - "integrity": "sha512-aX/y5pVRkfRnfmuX+OdbSdXvPe6ieKX/G2s7e98f4poJHnqH3281gDPm/metm6E/WRamfx7WC4HUqkWHfQHprw==", - "dependencies": { - "psl": "^1.1.33", - "punycode": "^2.1.1", - "universalify": "^0.2.0", - "url-parse": "^1.5.3" - }, - "engines": { - "node": ">=6" - } - }, - "node_modules/tr46": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/tr46/-/tr46-5.0.0.tgz", - "integrity": "sha512-tk2G5R2KRwBd+ZN0zaEXpmzdKyOYksXwywulIX95MBODjSzMIuQnQ3m8JxgbhnL1LeVo7lqQKsYa1O3Htl7K5g==", - "dependencies": { - "punycode": "^2.3.1" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/universalify": { - "version": "0.2.0", - "resolved": "https://registry.npmjs.org/universalify/-/universalify-0.2.0.tgz", - "integrity": "sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==", - "engines": { - "node": ">= 4.0.0" - } - }, - "node_modules/url-parse": { - "version": "1.5.10", - "resolved": "https://registry.npmjs.org/url-parse/-/url-parse-1.5.10.tgz", - "integrity": "sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==", - "dependencies": { - "querystringify": "^2.1.1", - "requires-port": "^1.0.0" - } - }, - "node_modules/w3c-xmlserializer": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz", - "integrity": "sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==", - "dependencies": { - "xml-name-validator": "^5.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/webidl-conversions": { - "version": "7.0.0", - "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-7.0.0.tgz", - "integrity": "sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==", - "engines": { - "node": ">=12" - } - }, - "node_modules/whatwg-encoding": { - "version": "3.1.1", - "resolved": "https://registry.npmjs.org/whatwg-encoding/-/whatwg-encoding-3.1.1.tgz", - "integrity": "sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==", - "dependencies": { - "iconv-lite": "0.6.3" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/whatwg-mimetype": { - "version": "4.0.0", - "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-4.0.0.tgz", - "integrity": "sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==", - "engines": { - "node": ">=18" - } - }, - "node_modules/whatwg-url": { - "version": "14.0.0", - "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-14.0.0.tgz", - "integrity": "sha512-1lfMEm2IEr7RIV+f4lUNPOqfFL+pO+Xw3fJSqmjX9AbXcXcYOkCe1P6+9VBZB6n94af16NfZf+sSk0JCBZC9aw==", - "dependencies": { - "tr46": "^5.0.0", - "webidl-conversions": "^7.0.0" - }, - "engines": { - "node": ">=18" - } - }, - "node_modules/ws": { - "version": "8.17.1", - "resolved": "https://registry.npmjs.org/ws/-/ws-8.17.1.tgz", - "integrity": "sha512-6XQFvXTkbfUOZOKKILFG1PDK2NDQs4azKQl26T0YS5CxqWLgXajbPZ+h4gZekJyRqFU8pvnbAbbs/3TgRPy+GQ==", - "engines": { - "node": ">=10.0.0" - }, - "peerDependencies": { - "bufferutil": "^4.0.1", - "utf-8-validate": ">=5.0.2" - }, - "peerDependenciesMeta": { - "bufferutil": { - "optional": true - }, - "utf-8-validate": { - "optional": true - } - } - }, - "node_modules/xml-name-validator": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz", - "integrity": "sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==", - "engines": { - "node": ">=18" - } - }, - "node_modules/xmlchars": { - "version": "2.2.0", - "resolved": "https://registry.npmjs.org/xmlchars/-/xmlchars-2.2.0.tgz", - "integrity": "sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==" - } - } -} diff --git a/scripts/check_anchors/package.json b/scripts/check_anchors/package.json deleted file mode 100644 index ed2725d31c..0000000000 --- a/scripts/check_anchors/package.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "name": "check_anchors", - "version": "1.0.0", - "description": "Check Anchors in a Markdown File", - "main": "index.js", - "scripts": { - "test": "echo \"Error: no test specified\" && exit 1" - }, - "author": "", - "license": "Apache-2.0", - "dependencies": { - "jsdom": "^24.0.0", - "showdown": "^2.1.0" - } -} diff --git a/source/auth/auth.md b/source/auth/auth.md index 8e81de18fa..22ce56f2d7 100644 --- a/source/auth/auth.md +++ b/source/auth/auth.md @@ -18,7 +18,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH ### References -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/blob/master/source/server-discovery-and-monitoring/) +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) ## Specification @@ -153,7 +153,7 @@ Drivers MUST follow the following steps for an authentication handshake: invalid credential is the same as all credentials being invalid. 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 +connection pool. (See [Q & A](#q-and-a) below and SDAM's [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.) @@ -995,7 +995,7 @@ The order in which Drivers MUST search for credentials is: 4. The ECS endpoint if `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set. Otherwise, the EC2 endpoint. > [!NOTE] -> See *Should drivers support accessing Amazon EC2 instance metadata in Amazon ECS* in [Q & A](#q--a) +> See *Should drivers support accessing Amazon EC2 instance metadata in Amazon ECS* in [Q & A](#q-and-a) > > Drivers are not expected to handle > [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) requests directly. See @@ -1841,7 +1841,7 @@ def speculative_auth(connection): If any operation fails with `ReauthenticationRequired` (error code 391) and MONGODB-OIDC is in use, the driver MUST reauthenticate the connection. Drivers MUST NOT resend a `hello` message during reauthentication, instead using SASL messages directly. Drivers MUST NOT try to use Speculative Authentication during reauthentication. See the main -[reauthentication](#reauthentication-1) section for more information. +[reauthentication](#reauthentication) section for more information. To reauthenticate a connection, invalidate the access token stored on the connection (i.e. the *Connection Cache*) from the *Client Cache*, fetch a new access token, and re-run the SASL conversation. @@ -1859,6 +1859,8 @@ def reauth(connection): `mongodb://[username[:password]@]host1[:port1][,[host2:[port2]],...[hostN:[portN]]][/database][?options]` + + #### Auth Related Options - authMechanism @@ -2023,6 +2025,8 @@ during `saslStart`. The Java and .NET drivers currently uses eager authentication and abide by this specification. + + ## Q & A Q: According to [Authentication Handshake](#authentication-handshake), we are calling `hello` or legacy hello for every diff --git a/source/bson-decimal128/decimal128.md b/source/bson-decimal128/decimal128.md index fbb301df19..1f927cee62 100644 --- a/source/bson-decimal128/decimal128.md +++ b/source/bson-decimal128/decimal128.md @@ -329,7 +329,7 @@ BSON/Extended JSON Decimal128. ## Tests -See the [BSON Corpus](https://github.com/mongodb/specifications/tree/master/source/bson-corpus) for tests. +See the [BSON Corpus](../bson-corpus/bson-corpus.md) for tests. Most of the tests are converted from the [General Decimal Arithmetic Testcases](http://speleotrove.com/decimal/dectest.html). diff --git a/source/causal-consistency/causal-consistency.md b/source/causal-consistency/causal-consistency.md index f80bca1632..5125d08f09 100644 --- a/source/causal-consistency/causal-consistency.md +++ b/source/causal-consistency/causal-consistency.md @@ -248,7 +248,7 @@ For causal consistency the driver MUST send the `operationTime` saved in the `Cl ``` For the lists of commands that support causally consistent reads, see -[ReadConcern](../read-write-concern/read-write-concern.md#read-concern/) spec. +[ReadConcern](../read-write-concern/read-write-concern.md#read-concern) spec. The driver MUST merge the `ReadConcern` specified for the operation with the `operationTime` from the `ClientSession` (which goes in the `afterClusterTime` field) to generate the combined `readConcern` to send to the server. If the level diff --git a/source/change-streams/tests/README.md b/source/change-streams/tests/README.md index e6f873f995..13af89ce05 100644 --- a/source/change-streams/tests/README.md +++ b/source/change-streams/tests/README.md @@ -100,8 +100,8 @@ For each YAML file, for each element in `tests`: - Create the database `database_name` and the collection `database_name.collection_name` - Create the database `database2_name` and the collection `database2_name.collection2_name` - If the the `failPoint` field is present, configure the fail point on the primary server. See - [Server Fail Point](../../transactions/tests#server-fail-point) in the Transactions spec test documentation for more - information. + [Server Fail Point](../../transactions/tests/legacy-test-format.md#server-fail-point) in the Transactions spec test + documentation for more information. - Create a new MongoClient `client` - Begin monitoring all APM events for `client`. (If the driver uses global listeners, filter out all events that do not originate with `client`). Filter out any "internal" commands (e.g. `hello` or legacy hello) diff --git a/source/client-side-encryption/client-side-encryption.md b/source/client-side-encryption/client-side-encryption.md index e0d416739f..32c3c07bec 100644 --- a/source/client-side-encryption/client-side-encryption.md +++ b/source/client-side-encryption/client-side-encryption.md @@ -99,7 +99,7 @@ A local process the driver communicates with to determine how to encrypt values This term, spelled in all-lowercase with an underscore, refers to the client-side field-level-encryption dynamic library provided as part of a MongoDB Enterprise distribution. It replaces [mongocryptd](#mongocryptd) as the method of -`marking-up a database command for encryption `. +[marking-up a database command for encryption](./subtype6.md#intent-to-encrypt). See also: @@ -108,9 +108,8 @@ See also: **ciphertext** -One of the data formats of -[BSON binary subtype 6](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/subtype6.rst), -representing an encoded BSON document containing encrypted ciphertext and metadata. +One of the data formats of [BSON binary subtype 6](./subtype6.md), representing an encoded BSON document containing +encrypted ciphertext and metadata. **FLE** @@ -259,7 +258,7 @@ connect to [mongocryptd](#mongocryptd) and instead rely on [crypt_shared](#crypt [crypt_shared](#crypt_shared) is a dynamically-loaded C++ library providing query analysis for auto-encryption. It replaces [mongocryptd](#mongocryptd) for performing query analysis to - -[mark-up sensitive fields within a command](./subtype6#intent-to-encrypt). +[mark-up sensitive fields within a command](./subtype6.md#intent-to-encrypt). Drivers are not required to load and interact with [crypt_shared](#crypt_shared) directly. Instead, they inform [libmongocrypt](#libmongocrypt) where to find [crypt_shared](#crypt_shared) and [libmongocrypt](#libmongocrypt) will @@ -532,6 +531,8 @@ The following shows an example object of `KMSProviders`: } ``` + + ##### Automatic Credentials Certain values of [KMSProviders](#kmsproviders) indicate a request by the user that the associated KMS providers should @@ -833,6 +834,8 @@ and $askDb$ is a boolean value. The resulting `encryptedFields` $EF$ is found by 3. Otherwise, $EF$ is *not-found* 5. Otherwise, $EF$ is considered *not-found*. + + #### Create Collection Helper Drivers MUST support a BSON document option named `encryptedFields` for any @@ -876,7 +879,7 @@ remaining operations are not attempted: #### Create Encrypted Collection Helper To support automatic generation of encryption data keys, a helper $CreateEncryptedCollection(CE, database, collName, -collOpts, kmsProvider, masterKey)$ is defined, where $CE$ is a [ClientEncryption](#clientencryption-1) object, +collOpts, kmsProvider, masterKey)$ is defined, where $CE$ is a [ClientEncryption](#clientencryption) object, $kmsProvider$ is a [KMSProvider](#KMSProvider) and $masterKey$ is equivalent to the $masterKey$ defined in [DataKeyOpts](#datakeyopts). It has the following behavior: @@ -1155,7 +1158,7 @@ class RewrapManyDataKeyResult { } ``` -`bulkWriteResult` is the [result of the bulk write operation](../crud/crud.md##write-results) used to update the key +`bulkWriteResult` is the [result of the bulk write operation](../crud/crud.md#write-results) used to update the key vault collection with one or more rewrapped data keys. If `rewrapManyDataKey()` does not find any matching keys to rewrap, no bulk write operation will be executed and this field will be unset. This field may also be unset if the bulk write operation is unacknowledged as permitted by the [CRUD API Spec](../crud/crud.md#write-results). @@ -1570,8 +1573,7 @@ If the [crypt_shared](#crypt_shared) library is loaded, the driver MUST NOT atte Single-threaded drivers MUST connect with [serverSelectionTryOnce=false](../server-selection/server-selection.md#serverselectiontryonce), `connectTimeoutMS=10000`, and MUST bypass -[cooldownMS](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#cooldownms) when connecting to -mongocryptd. See +[cooldownMS](../server-discovery-and-monitoring/server-monitoring.md#cooldownms) when connecting to mongocryptd. See [Why are serverSelectionTryOnce and cooldownMS disabled for single-threaded drivers connecting to mongocryptd?](#why-are-serverselectiontryonce-and-cooldownms-disabled-for-single-threaded-drivers-connecting-to-mongocryptd) If the ClientEncryption is configured with `mongocryptdBypassSpawn=true`, then the driver is not responsible for @@ -1649,10 +1651,8 @@ CommandStartedEvent, and decryption MUST occur after generating a CommandSucceed ## Size limits for Write Commands Automatic encryption requires the driver to serialize write commands as a single BSON document before automatically -encrypting with libmongocrypt (analogous to constructing -[OP_MSG payload type 0](https://github.com/mongodb/specifications/blob/70628e30c96361346f7b6872571c0ec4d54846cb/source/message/OP_MSG.rst#sections), -not a document sequence). Automatic encryption returns a single (possibly modified) BSON document as the command to -send. +encrypting with libmongocrypt (analogous to constructing [OP_MSG payload type 0](../message/OP_MSG.md#sections), not a +document sequence). Automatic encryption returns a single (possibly modified) BSON document as the command to send. Because automatic encryption increases the size of commands, the driver MUST split bulk writes at a reduced size limit before undergoing automatic encryption. The write payload MUST be split at 2MiB (2097152). Where batch splitting occurs @@ -1791,9 +1791,7 @@ struct { } ``` -See -[Driver Spec: BSON Binary Subtype 6](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/subtype6.rst) -for more information. +See [Driver Spec: BSON Binary Subtype 6](./subtype6.md) for more information. ### JSONSchema "encrypt" @@ -2112,7 +2110,7 @@ server before making another attempt. Meaning if the first attempt to mongocrypt observe a 5 second delay. This is not configurable in the URI, so this must be overridden internally. Since mongocryptd is a local process, there should only be a very short delay after spawning mongocryptd for it to start listening on sockets. See the SDAM spec description of -[cooldownMS](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#cooldownms). +[cooldownMS](../server-discovery-and-monitoring/server-monitoring.md#cooldownms). Because single threaded drivers may exceed `serverSelectionTimeoutMS` by the duration of the topology scan, `connectTimeoutMS` is also reduced. diff --git a/source/client-side-encryption/subtype6.md b/source/client-side-encryption/subtype6.md index bcdd1500f5..90427e0685 100644 --- a/source/client-side-encryption/subtype6.md +++ b/source/client-side-encryption/subtype6.md @@ -10,7 +10,7 @@ ______________________________________________________________________ Client side encryption requires a new binary subtype to store (1) encrypted ciphertext with metadata, and (2) binary markings indicating what values must be encrypted in a document. (1) is stored in the server, but (2) is only used in the communication protocol between libmongocrypt and mongocryptd described in -[Driver Spec: Client Side Encryption Encryption](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/client-side-encryption.rst). +[Driver Spec: Client Side Encryption Encryption](../client-side-encryption/client-side-encryption.md). ## META @@ -84,8 +84,7 @@ struct { ## Test Plan -Covered in -[Driver Spec: Client Side Encryption Encryption](https://github.com/mongodb/specifications/tree/master/source/client-side-encryption/client-side-encryption.rst). +Covered in [Driver Spec: Client Side Encryption Encryption](../client-side-encryption/client-side-encryption.md). ## Design Rationale diff --git a/source/client-side-encryption/tests/README.md b/source/client-side-encryption/tests/README.md index 1514c740d4..7d606a1b40 100644 --- a/source/client-side-encryption/tests/README.md +++ b/source/client-side-encryption/tests/README.md @@ -20,8 +20,8 @@ is supported when all of the following are true: - Server version is 4.2.0 or higher. Legacy spec test runners can rely on `runOn.minServerVersion` for this check. - Driver has libmongocrypt enabled -- At least one of [crypt_shared](../client-side-encryption.rst#crypt_shared) and/or - [mongocryptd](../client-side-encryption.rst#mongocryptd) is available. +- At least one of [crypt_shared](../client-side-encryption.md#crypt_shared) and/or + [mongocryptd](../client-side-encryption.md#mongocryptd) is available. ## Spec Test Format @@ -130,8 +130,9 @@ Test credentials to create environments are available in "drivers/gcpkms" and "d Do the following before running spec tests: -- If available for the platform under test, obtain a [crypt_shared](../client-side-encryption.rst#crypt_shared) binary - and place it in a location accessible to the tests. Refer to: [Using crypt_shared](#using-crypt_shared) +- If available for the platform under test, obtain a [crypt_shared](../client-side-encryption.md#crypt_shared) binary + and place it in a location accessible to the tests. Refer to: + [Using crypt_shared](../client-side-encryption.md#enabling-crypt_shared) - Start the mongocryptd process. - Start a mongod process with **server version 4.2.0 or later**. - Place credentials somewhere in the environment outside of tracked code. (If testing on evergreen, project variables @@ -291,7 +292,7 @@ Then for each element in `tests`: 8. If the test includes a list of command-started events in `expectations`, compare them to the actual command-started events using the same logic as the - [Command Monitoring spec legacy test runner](https://github.com/mongodb/specifications/blob/09ee1ebc481f1502e3246971a9419e484d736207/source/command-monitoring/tests/README.rst). + [Command Monitoring spec legacy test runner](../../command-logging-and-monitoring/tests/README.md). 9. For each element in `outcome`: @@ -304,33 +305,33 @@ The spec test MUST be run with *and* without auth. ## Using `crypt_shared` -On platforms where [crypt_shared](../client-side-encryption.rst#crypt_shared) is available, drivers should prefer to -test with the `crypt_shared` library instead of spawning mongocryptd. +On platforms where [crypt_shared](../client-side-encryption.md#crypt_shared) is available, drivers should prefer to test +with the `crypt_shared` library instead of spawning mongocryptd. -[crypt_shared](../client-side-encryption.rst#crypt_shared) is released alongside the server. -[crypt_shared](../client-side-encryption.rst#crypt_shared) is only available in versions 6.0 and above. +[crypt_shared](../client-side-encryption.md#crypt_shared) is released alongside the server. +[crypt_shared](../client-side-encryption.md#crypt_shared) is only available in versions 6.0 and above. mongocryptd is released alongside the server. mongocryptd is available in versions 4.2 and above. Drivers MUST run all tests with mongocryptd on at least one platform for all tested server versions. -Drivers MUST run all tests with [crypt_shared](../client-side-encryption.rst#crypt_shared) on at least one platform for +Drivers MUST run all tests with [crypt_shared](../client-side-encryption.md#crypt_shared) on at least one platform for all tested server versions. For server versions \< 6.0, drivers MUST test with the latest major release of -[crypt_shared](../client-side-encryption.rst#crypt_shared). Using the latest major release of -[crypt_shared](../client-side-encryption.rst#crypt_shared) is supported with older server versions. +[crypt_shared](../client-side-encryption.md#crypt_shared). Using the latest major release of +[crypt_shared](../client-side-encryption.md#crypt_shared) is supported with older server versions. Note that some tests assert on mongocryptd-related behaviors (e.g. the `mongocryptdBypassSpawn` test). -Drivers under test should load the [crypt_shared](../client-side-encryption.rst#crypt_shared) library using either the +Drivers under test should load the [crypt_shared](../client-side-encryption.md#crypt_shared) library using either the `cryptSharedLibPath` public API option (as part of the AutoEncryption `extraOptions`), or by setting a special search path instead. -Some tests will require *not* using [crypt_shared](../client-side-encryption.rst#crypt_shared). For such tests, one +Some tests will require *not* using [crypt_shared](../client-side-encryption.md#crypt_shared). For such tests, one should ensure that `crypt_shared` will not be loaded. Refer to the client-side-encryption documentation for information on "disabling" `crypt_shared` and setting library search paths. > [!NOTE] -> The [crypt_shared](../client-side-encryption.rst#crypt_shared) dynamic library can be obtained using the +> The [crypt_shared](../client-side-encryption.md#crypt_shared) dynamic library can be obtained using the > [mongodl](https://github.com/mongodb-labs/drivers-evergreen-tools/blob/master/.evergreen/mongodl.py) Python script > from [drivers-evergreen-tools](https://github.com/mongodb-labs/drivers-evergreen-tools/): > @@ -590,7 +591,7 @@ Using `client_encrypted` perform the following operations: - `{ "_id": "over_2mib_2", "unencrypted": }` Expect the bulk write to succeed and split after first doc (i.e. two inserts occur). This may be verified using - [command monitoring](https://github.com/mongodb/specifications/tree/master/source/command-logging-and-monitoring/command-logging-and-monitoring.rst). + [command monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md). 4. Bulk insert the following: @@ -600,7 +601,7 @@ Using `client_encrypted` perform the following operations: `{ "_id": "encryption_exceeds_2mib_2", "unencrypted": < the string "a" repeated (2097152 - 2000) times > }` Expect the bulk write to succeed and split after first doc (i.e. two inserts occur). This may be verified using - [command logging and monitoring](https://github.com/mongodb/specifications/tree/master/source/command-logging-and-monitoring/command-logging-and-monitoring.rst). + [command logging and monitoring](../../command-logging-and-monitoring/command-logging-and-monitoring.md). 5. Insert `{ "_id": "under_16mib", "unencrypted": `. @@ -986,12 +987,12 @@ The method of passing TLS options for KMIP TLS connections is driver dependent. #### Via loading shared library -The following tests that loading [crypt_shared](../client-side-encryption.rst#crypt_shared) bypasses spawning +The following tests that loading [crypt_shared](../client-side-encryption.md#crypt_shared) bypasses spawning mongocryptd. > [!NOTE] -> IMPORTANT: This test requires the [crypt_shared](../client-side-encryption.rst#crypt_shared) library be loaded. If the -> [crypt_shared](../client-side-encryption.rst#crypt_shared) library is not available, skip the test. +> IMPORTANT: This test requires the [crypt_shared](../client-side-encryption.md#crypt_shared) library be loaded. If the +> [crypt_shared](../client-side-encryption.md#crypt_shared) library is not available, skip the test. 1. Create a MongoClient configured with auto encryption (referred to as `client_encrypted`) @@ -1027,7 +1028,7 @@ mongocryptd. timeout. > [!NOTE] -> IMPORTANT: If [crypt_shared](../client-side-encryption.rst#crypt_shared) is visible to the operating system's library +> IMPORTANT: If [crypt_shared](../client-side-encryption.md#crypt_shared) is visible to the operating system's library > search mechanism, the expected server error generated by the `Via mongocryptdBypassSpawn`, `Via bypassAutoEncryption`, > `Via bypassQueryAnalysis` tests will not appear because libmongocrypt will load the `crypt_shared` library instead of > consulting mongocryptd. For the following tests, it is required that libmongocrypt *not* load `crypt_shared`. Refer to @@ -1907,7 +1908,7 @@ as `key1Document`. Read the `"_id"` field of `key1Document` as `key1ID`. Drop and create the collection `db.explicit_encryption` using `encryptedFields` as an option. See -[FLE 2 CreateCollection() and Collection.Drop()](../client-side-encryption.md#fle-2-createcollection-and-collection-drop). +[FLE 2 CreateCollection() and Collection.Drop()](../client-side-encryption.md#create-collection-helper). Drop and create the collection `keyvault.datakeys`. @@ -2247,9 +2248,9 @@ for the field `cursor.firstBatch.encrypted`. ### 15. On-demand AWS Credentials These tests require valid AWS credentials. Refer: -[Automatic AWS Credentials](../client-side-encryption.rst#automatic-aws-credentials). +[Automatic AWS Credentials](../client-side-encryption.md#automatic-credentials). -For these cases, create a [ClientEncryption](../client-side-encryption.rst#clientencryption) object $C$ with the +For these cases, create a [ClientEncryption](../client-side-encryption.md#clientencryption) object $C$ with the following options: ```typescript @@ -2263,7 +2264,7 @@ class ClientEncryptionOpts { #### Case 1: Failure Do not run this test case in an environment where AWS credentials are available (e.g. via environment variables or a -metadata URL). (Refer: [Obtaining credentials for AWS](../../auth/auth.rst#obtaining-credentials)) +metadata URL). (Refer: [Obtaining credentials for AWS](../../auth/auth.md#obtaining-credentials)) Attempt to create a datakey with $C$ using the `"aws"` KMS provider. Expect this to fail due to a lack of KMS provider credentials. @@ -2408,9 +2409,9 @@ impossible by design to omit `RewrapManyDataKeyOpts.provider` when `RewrapManyDa ### 17. On-demand GCP Credentials -Refer: [Automatic GCP Credentials](../client-side-encryption.rst#automatic-gcp-credentials). +Refer: [Automatic GCP Credentials](../client-side-encryption.md#obtaining-gcp-credentials). -For these cases, create a [ClientEncryption](../client-side-encryption.rst#clientencryption) object $C$ with the +For these cases, create a [ClientEncryption](../client-side-encryption.md#clientencryption) object $C$ with the following options: ```typescript @@ -2467,7 +2468,7 @@ Expect the key to be successfully created. ### 18. Azure IMDS Credentials -Refer: [Automatic Azure Credentials](../client-side-encryption.rst#obtaining-an-access-token-for-azure-key-vault) +Refer: [Automatic Azure Credentials](../client-side-encryption.md#obtaining-an-access-token-for-azure-key-vault) The test cases for IMDS communication are specially designed to not require an Azure environment, while still exercising the core of the functionality. The design of these test cases encourages an implementation to separate the concerns of @@ -2486,7 +2487,7 @@ This will run the `imds` Bottle application defined in the `fake_azure` Python m command line arguments to control the bind host and TCP port (use `--help` for more information). For each test case, follow the process for obtaining the token as outlined in the -[automatic Azure credentials section](../client-side-encryption.rst#obtaining-an-access-token-for-azure-key-vault) with +[automatic Azure credentials section](../client-side-encryption.md#obtaining-an-access-token-for-azure-key-vault) with the following changes: 1. Instead of the standard IMDS TCP endpoint of `169.254.169.254:80`, communicate with the running `fake_azure` HTTP @@ -2573,9 +2574,9 @@ a timeout. ### 19. Azure IMDS Credentials Integration Test -Refer: [Automatic Azure Credentials](../client-side-encryption.rst#obtaining-an-access-token-for-azure-key-vault) +Refer: [Automatic Azure Credentials](../client-side-encryption.md#obtaining-an-access-token-for-azure-key-vault) -For these cases, create a [ClientEncryption](../client-side-encryption.rst#clientencryption) object $C$ with the +For these cases, create a [ClientEncryption](../client-side-encryption.md#clientencryption) object $C$ with the following options: ```typescript @@ -2628,7 +2629,7 @@ Expect the key to be successfully created. ### 20. Bypass creating mongocryptd client when shared library is loaded > [!NOTE] -> IMPORTANT: If [crypt_shared](../client-side-encryption.rst#crypt_shared) is not visible to the operating system's +> IMPORTANT: If [crypt_shared](../client-side-encryption.md#crypt_shared) is not visible to the operating system's > library search mechanism, this test should be skipped. The following tests that a mongocryptd client is not created when shared library is in-use. @@ -2672,7 +2673,7 @@ The Automatic Data Encryption Keys tests require MongoDB server 7.0+. The tests > libmongocrypt 1.8.0 is configured to use the QEv2 protocol. For each of the following test cases, assume `DB` is a valid open database handle, and assume a -[ClientEncryption](../client-side-encryption.rst#clientencryption) object `CE` created using the following options: +[ClientEncryption](../client-side-encryption.md#clientencryption) object `CE` created using the following options: ``` clientEncryptionOptions: { @@ -2703,7 +2704,7 @@ When testing `local`, set `masterKey` to `null`. #### Case 1: Simple Creation and Validation This test is the most basic to verify that -[CreateEncryptedCollection](../client-side-encryption.rst#create-encrypted-collection-helper) created a collection with +[CreateEncryptedCollection](../client-side-encryption.md#create-encrypted-collection-helper) created a collection with queryable encryption enabled. It verifies that the server rejects an attempt to insert plaintext in an encrypted fields. 1. Create a new create-collection options $Opts$ including the following: @@ -2737,7 +2738,7 @@ queryable encryption enabled. It verifies that the server rejects an attempt to #### Case 2: Missing `encryptedFields` -The [CreateEncryptedCollection](../client-side-encryption.rst#create-encrypted-collection-helper) helper should not +The [CreateEncryptedCollection](../client-side-encryption.md#create-encrypted-collection-helper) helper should not create a regular collection if there are no `encryptedFields` for the collection being created. Instead, it should generate an error indicated that the `encryptedFields` option is missing. @@ -2745,14 +2746,14 @@ generate an error indicated that the `encryptedFields` option is missing. 2. Invoke $CreateEncryptedCollection(CE, DB, "testing1", Opts, kmsProvider, masterKey)$. 3. Expect the invocation to fail with an error indicating that `encryptedFields` is not defined for the collection, and expect that no collection was created within the database. It would be *incorrect* for - [CreateEncryptedCollection](../client-side-encryption.rst#create-encrypted-collection-helper) to create a regular + [CreateEncryptedCollection](../client-side-encryption.md#create-encrypted-collection-helper) to create a regular collection without queryable encryption enabled. #### Case 3: Invalid `keyId` -The [CreateEncryptedCollection](../client-side-encryption.rst#create-encrypted-collection-helper) helper only inspects +The [CreateEncryptedCollection](../client-side-encryption.md#create-encrypted-collection-helper) helper only inspects `encryptedFields.fields` for `keyId` of `null`. -[CreateEncryptedCollection](../client-side-encryption.rst#create-encrypted-collection-helper) should forward all other +[CreateEncryptedCollection](../client-side-encryption.md#create-encrypted-collection-helper) should forward all other data as-is, even if it would be malformed. The server should generate an error when attempting to create a collection with such invalid settings. @@ -2847,7 +2848,7 @@ as `key1Document`. Read the `"_id"` field of `key1Document` as `key1ID`. Drop and create the collection `db.explicit_encryption` using `encryptedFields` as an option. See -[FLE 2 CreateCollection() and Collection.Drop()](../client-side-encryption.md#fle-2-createcollection-and-collection-drop). +[FLE 2 CreateCollection() and Collection.Drop()](../client-side-encryption.md#create-collection-helper). Drop and create the collection `keyvault.datakeys`. diff --git a/source/client-side-operations-timeout/client-side-operations-timeout.md b/source/client-side-operations-timeout/client-side-operations-timeout.md index b7355c464b..7d498d0011 100644 --- a/source/client-side-operations-timeout/client-side-operations-timeout.md +++ b/source/client-side-operations-timeout/client-side-operations-timeout.md @@ -430,7 +430,7 @@ See [runCommand behavior](#runcommand-behavior). ## Test Plan -See the [README.rst](tests/README.md) in the tests directory. +See the [README.md](tests/README.md) in the tests directory. ## Motivation for Change diff --git a/source/command-logging-and-monitoring/tests/README.md b/source/command-logging-and-monitoring/tests/README.md index 79d9b5cc30..d15ddc6995 100644 --- a/source/command-logging-and-monitoring/tests/README.md +++ b/source/command-logging-and-monitoring/tests/README.md @@ -7,11 +7,10 @@ ______________________________________________________________________ ### Automated Tests There are tests in the [Unified Test Format](../../unified-test-format/unified-test-format.md) for both logging and -monitoring in [/logging](./logging) and [/monitoring](./monitoring), respectively. Drivers MUST run the logging tests -with their max document length setting (as described in the -[logging specification](../../logging/logging.md#configurable-max-document-length)) set to a large value e.g. 10,000; -this is necessary in order for the driver to emit the full server reply (and to allow matching against that reply) on -certain MongoDB versions and topologies. +monitoring in `/logging` and `monitoring`, respectively. Drivers MUST run the logging tests with their max document +length setting (as described in the [logging specification](../../logging/logging.md#configurable-max-document-length)) +set to a large value e.g. 10,000; this is necessary in order for the driver to emit the full server reply (and to allow +matching against that reply) on certain MongoDB versions and topologies. ### Prose Tests diff --git a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md index 1474c5000c..bb8a454b13 100644 --- a/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md +++ b/source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md @@ -166,28 +166,28 @@ interface ConnectionPoolOptions { #### Connection -A driver-defined wrapper around a single TCP connection to an Endpoint. A [Connection](#connection-1) has the following +A driver-defined wrapper around a single TCP connection to an Endpoint. A [Connection](#connection) has the following properties: -- **Single Endpoint:** A [Connection](#connection-1) MUST be associated with a single Endpoint. A - [Connection](#connection-1) MUST NOT be associated with multiple Endpoints. -- **Single Lifetime:** A [Connection](#connection-1) MUST NOT be used after it is closed. -- **Single Owner:** A [Connection](#connection-1) MUST belong to exactly one Pool, and MUST NOT be shared across - multiple pools -- **Single Track:** A [Connection](#connection-1) MUST limit itself to one request / response at a time. A - [Connection](#connection-1) MUST NOT multiplex/pipeline requests to an Endpoint. -- **Monotonically Increasing ID:** A [Connection](#connection-1) MUST have an ID number associated with it. - [Connection](#connection-1) IDs within a Pool MUST be assigned in order of creation, starting at 1 and increasing by 1 +- **Single Endpoint:** A [Connection](#connection) MUST be associated with a single Endpoint. A + [Connection](#connection) MUST NOT be associated with multiple Endpoints. +- **Single Lifetime:** A [Connection](#connection) MUST NOT be used after it is closed. +- **Single Owner:** A [Connection](#connection) MUST belong to exactly one Pool, and MUST NOT be shared across multiple + pools +- **Single Track:** A [Connection](#connection) MUST limit itself to one request / response at a time. A + [Connection](#connection) MUST NOT multiplex/pipeline requests to an Endpoint. +- **Monotonically Increasing ID:** A [Connection](#connection) MUST have an ID number associated with it. + [Connection](#connection) IDs within a Pool MUST be assigned in order of creation, starting at 1 and increasing by 1 for each new Connection. - **Valid Connection:** A connection MUST NOT be checked out of the pool until it has successfully and fully completed a MongoDB Handshake and Authentication as specified in the [Handshake](../mongodb-handshake/handshake.md), [OP_COMPRESSED](../compression/OP_COMPRESSED.md), and [Authentication](../auth/auth.md) specifications. -- **Perishable**: it is possible for a [Connection](#connection-1) to become **Perished**. A [Connection](#connection-1) - is considered perished if any of the following are true: - - **Stale:** The [Connection](#connection-1) 's generation does not match the generation of the parent pool - - **Idle:** The [Connection](#connection-1) is currently "available" (as defined below) and has been for longer than +- **Perishable**: it is possible for a [Connection](#connection) to become **Perished**. A [Connection](#connection) is + considered perished if any of the following are true: + - **Stale:** The [Connection](#connection) 's generation does not match the generation of the parent pool + - **Idle:** The [Connection](#connection) is currently "available" (as defined below) and has been for longer than **maxIdleTimeMS**. - - **Errored:** The [Connection](#connection-1) has experienced an error that indicates it is no longer recommended for + - **Errored:** The [Connection](#connection) has experienced an error that indicates it is no longer recommended for use. Examples include, but are not limited to: - Network Error - Network Timeout @@ -281,7 +281,7 @@ Endpoint. The pool has the following properties: of [Connections](#connection) (including available and in use) MUST NOT exceed **maxPoolSize** - **Rate-limited:** A Pool MUST limit the number of [Connections](#connection) being [established](#establishing-a-connection-internal-implementation) concurrently via the **maxConnecting** - [pool option](#connection-pool-options-1). + [pool option](#connection-pool-options). ```typescript interface ConnectionPool { @@ -379,8 +379,8 @@ interface ConnectionPool { This specification does not define how a pool is to be created, leaving it up to the driver. Creation of a connection pool is generally an implementation detail of the driver, i.e., is not a part of the public API of the driver. The SDAM specification defines -[when](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#connection-pool-creation) the driver should -create connection pools. +[when](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#connection-pool-management) the driver +should create connection pools. When a pool is created, its state MUST initially be set to "paused". Even if minPoolSize is set, the pool MUST NOT begin being [populated](#populating-the-pool-with-a-connection-internal-implementation) with [Connections](#connection) until @@ -515,14 +515,14 @@ If minPoolSize is set, the [Connection](#connection) Pool MUST be populated unti it can be used for this. If the pool does not implement a background thread, the checkOut method is responsible for ensuring this requirement is met. -When populating the Pool, pendingConnectionCount has to be decremented after establishing a [Connection](#connection-1) +When populating the Pool, pendingConnectionCount has to be decremented after establishing a [Connection](#connection) similarly to how it is done in [Checking Out a Connection](#checking-out-a-connection) to signal that another -[Connection](#connection-1) is allowed to be established. Such a signal MUST become observable to any [Thread](#thread) +[Connection](#connection) is allowed to be established. Such a signal MUST become observable to any [Thread](#thread) after the action that [marks the established Connection as "available"](#marking-a-connection-as-available-internal-implementation) becomes observable to the [Thread](#thread). Informally, this order guarantees that no [Thread](#thread) tries to start -establishing a [Connection](#connection-1) when there is an "available" [Connection](#connection-1) established as a -result of populating the Pool. +establishing a [Connection](#connection) when there is an "available" [Connection](#connection) established as a result +of populating the Pool. ``` wait until pendingConnectionCount < maxConnecting and pool is "ready" @@ -537,23 +537,23 @@ except error: #### Checking Out a Connection -A Pool MUST have a method that allows the driver to check out a [Connection](#connection-1). Checking out a -[Connection](#connection-1) involves submitting a request to the WaitQueue and, once that request reaches the front of -the queue, having the Pool find or create a [Connection](#connection-1) to fulfill that request. Requests MUST be -subject to a timeout which is computed per the rules in +A Pool MUST have a method that allows the driver to check out a [Connection](#connection). Checking out a +[Connection](#connection) involves submitting a request to the WaitQueue and, once that request reaches the front of the +queue, having the Pool find or create a [Connection](#connection) to fulfill that request. Requests MUST be subject to a +timeout which is computed per the rules in [Client Side Operations Timeout: Server Selection](../client-side-operations-timeout/client-side-operations-timeout.md#server-selection). -To service a request for a [Connection](#connection-1), the Pool MUST first iterate over the list of available -[Connections](#connection), searching for a non-perished one to be returned. If a perished [Connection](#connection-1) -is encountered, such a [Connection](#connection-1) MUST be closed (as described in +To service a request for a [Connection](#connection), the Pool MUST first iterate over the list of available +[Connections](#connection), searching for a non-perished one to be returned. If a perished [Connection](#connection) is +encountered, such a [Connection](#connection) MUST be closed (as described in [Closing a Connection](#closing-a-connection-internal-implementation)) and the iteration of available -[Connections](#connection) MUST continue until either a non-perished available [Connection](#connection-1) is found or -the list of available [Connections](#connection) is exhausted. +[Connections](#connection) MUST continue until either a non-perished available [Connection](#connection) is found or the +list of available [Connections](#connection) is exhausted. If the list is exhausted, the total number of [Connections](#connection) is less than maxPoolSize, and -pendingConnectionCount \< maxConnecting, the pool MUST create a [Connection](#connection-1), establish it, mark it as -"in use" and return it. If totalConnectionCount == maxPoolSize or pendingConnectionCount == maxConnecting, then the pool -MUST wait to service the request until neither of those two conditions are met or until a [Connection](#connection-1) +pendingConnectionCount \< maxConnecting, the pool MUST create a [Connection](#connection), establish it, mark it as "in +use" and return it. If totalConnectionCount == maxPoolSize or pendingConnectionCount == maxConnecting, then the pool +MUST wait to service the request until neither of those two conditions are met or until a [Connection](#connection) becomes available, re-entering the checkOut loop in either case. This waiting MUST NOT prevent [Connections](#connection) from being checked into the pool. Additionally, the Pool MUST NOT service any newer checkOut requests before fulfilling the original one which could not be fulfilled. For drivers that implement the WaitQueue via a @@ -755,8 +755,8 @@ pendingConnectionCount to become less than maxConnecting when satisfying minPool rest of its duties, e.g., closing available perished connections, or end. The duration of intervals between the end of one Run and the beginning of the next Run is not specified, but the -[Test Format and Runner Specification](https://github.com/mongodb/specifications/tree/master/source/connection-monitoring-and-pooling/tests) -may restrict this duration, or introduce other restrictions to facilitate testing. +[Test Format and Runner Specification](../connection-monitoring-and-pooling/tests/README.md) may restrict this duration, +or introduce other restrictions to facilitate testing. ##### withConnection @@ -774,6 +774,8 @@ the pool. If a user subscribes to Connection Monitoring events, these events MUS "Connection Pool Behaviors". Events SHOULD be created and subscribed to in a manner idiomatic to their language and driver. + + #### Events See the [Load Balancer Specification](../load-balancers/load-balancers.md#events) for details on the `serviceId` field. diff --git a/source/connection-monitoring-and-pooling/tests/README.md b/source/connection-monitoring-and-pooling/tests/README.md index 4794e685c5..5ff15b3145 100644 --- a/source/connection-monitoring-and-pooling/tests/README.md +++ b/source/connection-monitoring-and-pooling/tests/README.md @@ -23,5 +23,5 @@ The following tests have not yet been automated, but MUST still be tested: ## Logging Tests -Tests for connection pool logging can be found in the [/logging](./logging) subdirectory and are written in the +Tests for connection pool logging can be found in the `/logging` subdirectory and are written in the [Unified Test Format](../../unified-test-format/unified-test-format.md). diff --git a/source/connection-monitoring-and-pooling/tests/cmap-format/README.md b/source/connection-monitoring-and-pooling/tests/cmap-format/README.md index fce9441fbe..764ee25164 100644 --- a/source/connection-monitoring-and-pooling/tests/cmap-format/README.md +++ b/source/connection-monitoring-and-pooling/tests/cmap-format/README.md @@ -22,8 +22,8 @@ Each YAML file has the following keys: All Unit Tests have some of the following fields: - `poolOptions`: If present, connection pool options to use when creating a pool; both - [standard ConnectionPoolOptions](../../connection-monitoring-and-pooling.md#connection-pool-options-1) and the - following test-specific options are allowed: + [standard ConnectionPoolOptions](../../connection-monitoring-and-pooling.md#connection-pool-options) and the following + test-specific options are allowed: - `backgroundThreadIntervalMS`: A time interval between the end of a [Background Thread Run](../../connection-monitoring-and-pooling.md#background-thread) and the beginning of the next Run. If a Connection Pool does not implement a Background Thread, the Test Runner MUST ignore the option. If the diff --git a/source/connections-survive-step-down/tests/README.md b/source/connections-survive-step-down/tests/README.md index b2a9db92b8..0b10ad9128 100644 --- a/source/connections-survive-step-down/tests/README.md +++ b/source/connections-survive-step-down/tests/README.md @@ -7,7 +7,8 @@ These tests apply only to replica set topologies. ## Server Fail Point -See: [Server Fail Point](../../transactions/tests#server-fail-point) in the Transactions spec test suite. +See: [Server Fail Point](../../transactions/tests/legacy-test-format.md#server-fail-point) in the Transactions spec test +suite. ### Disabling Fail Point after Test Execution diff --git a/source/connections-survive-step-down/tests/README.rst b/source/connections-survive-step-down/tests/README.rst deleted file mode 100644 index de52113939..0000000000 --- a/source/connections-survive-step-down/tests/README.rst +++ /dev/null @@ -1,178 +0,0 @@ -=========================================== -Connections Survive Primary Step Down Tests -=========================================== - -These tests can be used to verify a driver's compliance with server discovery -and monitoring requirements with respect to handling "not primary" and -"node is shutting down" error responses from the server. - -.. contents:: - -These tests apply only to replica set topologies. - -Server Fail Point ------------------ - -See: `Server Fail Point`_ in the Transactions spec test suite. - -.. _Server Fail Point: ../../transactions/tests#server-fail-point - -Disabling Fail Point after Test Execution -````````````````````````````````````````` - -After each test that configures a fail point, drivers should disable the -``failCommand`` fail point to avoid spurious failures in -subsequent tests. The fail point may be disabled like so:: - - db.runCommand({ - configureFailPoint: "failCommand", - mode: "off" - }); - -Consideration when using serverStatus -````````````````````````````````````` - -Drivers executing `serverStatus`_ for connection assertions MUST take its own -connection into account when making their calculations. Those drivers SHOULD -execute `serverStatus`_ using a separate client not under test. - - -Tests ------ - - -Test setup -`````````` - -For each test, make sure the following steps have been completed before running the actual test: - -- Create a ``MongoClient`` with ``retryWrites=false`` -- Create a collection object from the ``MongoClient``, using ``step-down`` for the database and collection name. -- Drop the test collection, using ``writeConcern`` "majority". -- Execute the "create" command to recreate the collection, using ``writeConcern`` - "majority". - -The driver should implement the following tests: - -getMore Iteration -````````````````` - -This test requires a replica set with server version 4.2 or higher. - -Perform the following operations: - -- Insert 5 documents into a collection with a majority write concern. -- Start a find operation on the collection with a batch size of 2, and - retrieve the first batch of results. -- Send a ``{replSetFreeze: 0}`` command to any secondary and verify that the - command succeeded. This command will unfreeze the secondary and ensure that - it will be eligible to be elected immediately. -- Send a ``{replSetStepDown: 30, force: true}`` command to the current primary and verify that - the command succeeded. -- Retrieve the next batch of results from the cursor obtained in the find - operation, and verify that this operation succeeded. -- If the driver implements the `CMAP`_ specification, verify that no new `PoolClearedEvent`_ has been - published. Otherwise verify that `connections.totalCreated`_ in `serverStatus`_ has not changed. - - -Not Primary - Keep Connection Pool -`````````````````````````````````` - -This test requires a replica set with server version 4.2 or higher. - -- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1}, - data: {failCommands: ["insert"], errorCode: 10107}}`` -- Execute an insert into the test collection of a ``{test: 1}`` - document. -- Verify that the insert failed with an operation failure with 10107 code. -- Execute an insert into the test collection of a ``{test: 1}`` - document and verify that it succeeds. -- If the driver implements the `CMAP`_ specification, verify that no new `PoolClearedEvent`_ has been - published. Otherwise verify that `connections.totalCreated`_ in `serverStatus`_ has not changed. - - - -Not Primary - Reset Connection Pool -``````````````````````````````````` - -This test requires a replica set with server version 4.0. - - -- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1}, - data: {failCommands: ["insert"], errorCode: 10107}}`` -- Execute an insert into the test collection of a ``{test: 1}`` - document. -- Verify that the insert failed with an operation failure with 10107 code. -- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_ - has been published -- Execute an insert into the test collection of a ``{test: 1}`` - document and verify that it succeeds. -- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_ - command to verify `connections.totalCreated`_ has increased by 1. - - -Shutdown in progress - Reset Connection Pool -```````````````````````````````````````````` - -This test should be run on all server versions >= 4.0. - -Perform the following operations on a client configured to NOT retry writes: - -- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1}, - data: {failCommands: ["insert"], errorCode: 91}}`` -- Execute an insert into the test collection of a ``{test: 1}`` - document. -- Verify that the insert failed with an operation failure with 91 code. -- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_ - has been published -- Execute an insert into the test collection of a ``{test: 1}`` - document and verify that it succeeds. -- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_ - command to verify `connections.totalCreated`_ has increased by 1. - - -Interrupted at shutdown - Reset Connection Pool -``````````````````````````````````````````````` - -This test should be run on all server versions >= 4.0. - -Perform the following operations on a client configured to NOT retry writes: - -- Set the following fail point: ``{configureFailPoint: "failCommand", mode: {times: 1}, - data: {failCommands: ["insert"], errorCode: 11600}}`` -- Execute an insert into the test collection of a ``{test: 1}`` - document. -- Verify that the insert failed with an operation failure with 11600 code. -- If the driver implements the `CMAP`_ specification, verify that a `PoolClearedEvent`_ - has been published -- Execute an insert into the test collection of a ``{test: 1}`` - document and verify that it succeeds. -- If the driver does NOT implement the `CMAP`_ specification, use the `serverStatus`_ - command to verify `connections.totalCreated`_ has increased by 1. - - - -Questions and Answers ---------------------- - -Do we need to wait for re-election after the first test? -```````````````````````````````````````````````````````` - -Since test setup requires creation of a collection, a primary must exist, so subsequent tests will block in server selection until a primary is available again. - - -Why do tests check for a successful insert operation in addition to checking that the pool was updated appropriately? -````````````````````````````````````````````````````````````````````````````````````````````````````````````````````` - -Ensuring that we can run a successful insert after the primary steps down and without needing to recreate the -``MongoClient`` serves to test the resiliency of drivers in the event of a failover/election. Even though checking for -a successful insert operation does not directly test functionality introduced in this specification, it is a -straightforward way to test driver resiliency against a live replica set undergoing an election. This testing -methodology is in contrast to the one adopted by the SDAM spec tests that rely entirely on mocking with no actual -server communication. - - -.. _CMAP: ../../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md -.. _PoolClearedEvent: /source/connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events -.. _serverStatus: https://www.mongodb.com/docs/manual/reference/command/serverStatus -.. _connections.totalCreated: https://www.mongodb.com/docs/manual/reference/command/serverStatus/#serverstatus.connections.totalCreated diff --git a/source/crud/bulk-write.md b/source/crud/bulk-write.md index 522affbb75..8090a979d3 100644 --- a/source/crud/bulk-write.md +++ b/source/crud/bulk-write.md @@ -9,7 +9,7 @@ This specification defines the driver API for the `bulkWrite` server command int in this specification allows users to perform insert, update, and delete operations against mixed namespaces in a minimized number of round trips, and to receive detailed results for each operation performed. This API is distinct from the [collection-level bulkWrite method](../crud/crud.md#insert-update-replace-delete-and-bulk-writes) defined in the -CRUD specification and the [deprecated bulk write specification](../driver-bulk-update.rst). +CRUD specification. ## Specification @@ -479,8 +479,7 @@ The `bulkWrite` server command has the following format: } ``` -Drivers MUST use document sequences ([`OP_MSG`](../message/OP_MSG.rst) payload type 1) for the `ops` and `nsInfo` -fields. +Drivers MUST use document sequences ([`OP_MSG`](../message/OP_MSG.md) payload type 1) for the `ops` and `nsInfo` fields. The `bulkWrite` command is executed on the "admin" database. @@ -764,8 +763,7 @@ immediately throw the exception. Otherwise, drivers MUST continue to iterate the ## Test Plan The majority of tests for `MongoClient.bulkWrite` are written in the -[Unified Test Format](../unified-test-format/unified-test-format.md) and reside in the -[CRUD unified tests directory](../crud/tests/unified/). +[Unified Test Format](../unified-test-format/unified-test-format.md) and reside in the CRUD unified tests directory. Additional prose tests are specified [here](../crud/tests/README.md). These tests require constructing very large documents to test batch splitting, which is not feasible in the unified test format at the time of writing this diff --git a/source/crud/crud.md b/source/crud/crud.md index cd9389c4e5..baa2422d09 100644 --- a/source/crud/crud.md +++ b/source/crud/crud.md @@ -1797,6 +1797,8 @@ class BulkWriteException { } ``` + + ##### Find And Modify ```typescript diff --git a/source/crud/tests/unified/insertOne-dots_and_dollars.yml b/source/crud/tests/unified/insertOne-dots_and_dollars.yml index f255b52413..fcfcfc71c6 100644 --- a/source/crud/tests/unified/insertOne-dots_and_dollars.yml +++ b/source/crud/tests/unified/insertOne-dots_and_dollars.yml @@ -198,7 +198,7 @@ tests: # Using "$db" here works for libmongoc so long as it's a string type; # however, neither $ref nor $id would be accepted on their own. # - # See https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#parsers + # See https://github.com/mongodb/specifications/blob/master/source/extended-json.md#parsers document: &dbrefLikeKey { _id: 1, a: { $db: "foo" } } expectResult: *insertResult expectEvents: diff --git a/source/enumerate-databases.md b/source/enumerate-databases.md index 3d300afb2b..a95651f90c 100644 --- a/source/enumerate-databases.md +++ b/source/enumerate-databases.md @@ -210,9 +210,9 @@ to be expanded to support this option. ## Design Rationale -The design of this specification is inspired by the [Collection Enumeration](./enumerate-collections.rst) and -[Index Enumeration](./enumerate-indexes.rst) specifications. Since most drivers already implement a `listDatabases` -command helper in some fashion, this spec is flexible when it comes to existing APIs. +The design of this specification is inspired by the [Collection Enumeration](./enumerate-collections.md) and +[Index Management](./index-management/index-management.md) specifications. Since most drivers already implement a +`listDatabases` command helper in some fashion, this spec is flexible when it comes to existing APIs. ## Backwards Compatibility diff --git a/source/index-management/index-management.md b/source/index-management/index-management.md index ab0d0ff945..031ffb17cc 100644 --- a/source/index-management/index-management.md +++ b/source/index-management/index-management.md @@ -391,7 +391,7 @@ interface IndexView extends Iterable { * requirement is dropped in favor of the driver language standard for handling iteration * over a sequence of objects. * - * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.rst + * @see https://github.com/mongodb/specifications/blob/master/source/enumerate-indexes.md * * @note For drivers that cannot make the IndexView iterable, they MUST implement a list * method. See below. @@ -824,6 +824,8 @@ In MongoDB 4.4, the `ns` field was removed from the index specifications returne populate the `ns` field of the models with the appropriate namespace if the server does not report it in the `listIndexes` command response. The `ns` field is not required to be a part of the models, however. + + #### Getting Index Names Drivers MAY implement a method to enumerate all indexes, and return only the index names. The helper operates the same 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 65e4275b8c..a56ee6fb33 100644 --- a/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md +++ b/source/initial-dns-seedlist-discovery/initial-dns-seedlist-discovery.md @@ -200,10 +200,10 @@ mongodb://mongodb1.mongodb.com:27317,mongodb2.mongodb.com:27107/?ssl=true&replic ## Test Plan -See README.md in the accompanying [test directory](tests). +See README.md in the accompanying [test directory](tests/README.md). Additionally, see the `mongodb+srv` test `invalid-uris.yml` in the -[Connection String Spec tests](../connection-string/tests). +[Connection String Spec tests](../connection-string/tests/README.md). ## Motivation diff --git a/source/logging/logging.md b/source/logging/logging.md index 2626d6084e..d1236bdd25 100644 --- a/source/logging/logging.md +++ b/source/logging/logging.md @@ -182,7 +182,7 @@ support both types of logging. Note that drivers implementing unstructured logging MUST still support some internal way to intercept the data contained in messages in a structured form, as this is required to implement the unified tests for logging conformance. See the -[unified test format specification](../unified-test-format/unified-test-format.md#expectedLogMessage) for details. +[unified test format specification](../unified-test-format/unified-test-format.md#expectedlogmessage) for details. #### Representing Documents in Log Messages diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index eb694cb2dc..fd781bbdaf 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -140,6 +140,8 @@ The client MUST be prepared to receive a response without `moreToCome` set prior even if an earlier response for the same cursor had the `moreToCome` flag set. To continue iterating such a cursor, the client MUST issue an explicit `getMore` request. + + ##### exhaustAllowed Setting this flag on a request indicates to the recipient that the sender is prepared to handle multiple replies (using diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 1f09f80d52..bcd682be00 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -156,6 +156,8 @@ the following structure: } ``` + + #### client.application.name This value is application configurable. @@ -281,6 +283,8 @@ Example: - "Oracle JVM EE 9.1.1" ``` + + #### client.env This value is optional and is not application configurable. diff --git a/source/ocsp-support/ocsp-support.md b/source/ocsp-support/ocsp-support.md index 8629600823..aa0ca63e1a 100644 --- a/source/ocsp-support/ocsp-support.md +++ b/source/ocsp-support/ocsp-support.md @@ -121,7 +121,7 @@ this option. This boolean option determines whether a MongoClient should refrain from reaching out to an OCSP endpoint i.e. whether non-stapled OCSP should be disabled. When set to true, a driver MUST NOT reach out to OCSP endpoints. When set to false, a driver MUST reach out to OCSP endpoints if needed (as described in -[Specification: Suggested OCSP Behavior](#suggested-ocsp-behavior-1)). +[Specification: Suggested OCSP Behavior](#suggested-ocsp-behavior)). For drivers that pass the ["Soft Fail Test"](tests/README.md#integration-tests-permutations-to-be-tested), this option MUST default to false. @@ -140,7 +140,7 @@ available (i.e. no methods are defined or the CRL distribution points/OCSP endpo This boolean option determines whether a MongoClient should refrain checking certificate revocation status. When set to true, a driver MUST NOT check certificate revocation status via CRLs or OCSP. When set to false, a driver MUST check certificate revocation status, reach out to OCSP endpoints if needed (as described in -[Specification: Suggested OCSP Behavior](#suggested-ocsp-behavior-1)). +[Specification: Suggested OCSP Behavior](#suggested-ocsp-behavior)). For drivers that pass the ["Soft Fail Test"](tests/README.md#integration-tests-permutations-to-be-tested) , this option MUST default to false. @@ -291,10 +291,9 @@ No additional Atlas connectivity tests will be added because the existing tests ### Suggested OCSP Behavior For drivers with finer-grain control over their OCSP behavior, the suggested OCSP behavior was chosen as a balance -between security and availability, erring on availability while minimizing network round trips. Therefore, in the -[Specification: Suggested OCSP Behavior](#suggested-ocsp-behavior-1) section, in order to minimize network round trips, -drivers are advised not to reach out to OCSP endpoints and CRL distribution points in order to verify the revocation -status of intermediate certificates. +between security and availability, erring on availability while minimizing network round trips. Therefore, in order to +minimize network round trips, drivers are advised not to reach out to OCSP endpoints and CRL distribution points in +order to verify the revocation status of intermediate certificates. ## Backwards Compatibility @@ -409,9 +408,9 @@ not adhering to that RFC. ### Why was the decision made to allow OCSP endpoint checking to be enabled/disabled via a URI option? We initially hoped that we would be able to not expose any options specifically related to OCSP to the user, in -accordance with the "No Knobs" [drivers mantra](../../README.md#driver-mantras) However, we later decided that users may -benefit from having the ability to disable OCSP endpoint checking when applications are deployed behind restrictive -firewall with outbound allowLists, and this benefit is worth adding another URI option. +accordance with the "No Knobs" [drivers mantra](../driver-mantras.md) However, we later decided that users may benefit +from having the ability to disable OCSP endpoint checking when applications are deployed behind restrictive firewall +with outbound allowLists, and this benefit is worth adding another URI option. ## Appendix 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 d1c2326b78..77b9200cd0 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 @@ -98,12 +98,12 @@ other operations. ### Single-Threaded Drivers The rescan MUST happen **before** scanning all servers as part of the normal -[scanning](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#scanning) functionality, but only if +[scanning](../server-discovery-and-monitoring/server-monitoring.md#scanning) functionality, but only if *rescanSRVIntervalMS* has passed. ## Test Plan -See README.rst in the accompanying [test directory](tests). +See README.md in the accompanying [test directory](tests/README.md). ## Motivation for Change diff --git a/source/read-write-concern/read-write-concern.md b/source/read-write-concern/read-write-concern.md index fbde9147cc..e5def07ef1 100644 --- a/source/read-write-concern/read-write-concern.md +++ b/source/read-write-concern/read-write-concern.md @@ -20,7 +20,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH MaxWireVersion The `maxWireVersion` value reported by the `hello` command. Server Selection The process of selecting a server to read or write from. See -[the server selection specification](https://github.com/mongodb/specifications/tree/master/source/server-selection). +[the server selection specification](../server-selection/server-selection.md). ## Specification @@ -126,6 +126,8 @@ driver MUST include the command's `ReadConcern` when sending the command. This i server default `ReadConcern`, so that the command can override the `Client`, `Database`, or `Collection`'s `ReadConcern` to use the server default instead. + + ##### Generic Command Method If your driver offers a generic `RunCommand` method on your `database` object, `ReadConcern` MUST NOT be applied @@ -507,7 +509,7 @@ concerns. ## Test Plan -Yaml tests are located here: +Yaml tests are located [here](../read-write-concern/tests/README.md) Below are English descriptions of other items that should be tested: diff --git a/source/requirements.txt b/source/requirements.txt index 90b21b95d9..195c3c68be 100644 --- a/source/requirements.txt +++ b/source/requirements.txt @@ -1,2 +1,3 @@ mkdocs -mkdocs-github-admonitions-plugin \ No newline at end of file +mkdocs-github-admonitions-plugin +mkdocs-htmlproofer-plugin \ No newline at end of file diff --git a/source/retryable-reads/retryable-reads.md b/source/retryable-reads/retryable-reads.md index 2e6a4bf656..417ee6e9c2 100644 --- a/source/retryable-reads/retryable-reads.md +++ b/source/retryable-reads/retryable-reads.md @@ -469,8 +469,9 @@ None. 1. A later specification may allow operations (including read) to be retried any number of times during a singular timeout period. -2. Any future changes to the the applicable parts of [retryable writes specification](../retryable-writes/) may also - need to be reflected in the retryable reads specification, and vice versa. +2. Any future changes to the the applicable parts of + [retryable writes specification](../retryable-writes/retryable-writes.md) may also need to be reflected in the + retryable reads specification, and vice versa. 3. We may revisit the decision not retry `Cursor.getMore()` (see [Q&A](#qa)). 4. Once [DRIVERS-560](https://jira.mongodb.org/browse/DRIVERS-560) is resolved, tests will be added to allow testing Retryable Reads on MongoDB 3.6. See the [test plan](./tests/README.md) for additional information. @@ -509,7 +510,7 @@ attempts are fruitless and would waste time. See [How To Write Resilient MongoDB Applications](https://emptysqua.re/blog/how-to-write-resilient-mongodb-applications/) for additional discussion on this strategy. -However when [Client Side Operations Timeout](../client-side-operations-timeout/client-side-operations-timeout.rst) is +However when [Client Side Operations Timeout](../client-side-operations-timeout/client-side-operations-timeout.md) is enabled, the driver will retry multiple times until the operation succeeds, a non-retryable error is encountered, or the timeout expires. Retrying multiple times provides greater resilience to cascading failures such as rolling server restarts during planned maintenance events. diff --git a/source/retryable-reads/tests/unified/listCollectionObjects-serverErrors.yml b/source/retryable-reads/tests/unified/listCollectionObjects-serverErrors.yml index 758c6165de..0489c890fd 100644 --- a/source/retryable-reads/tests/unified/listCollectionObjects-serverErrors.yml +++ b/source/retryable-reads/tests/unified/listCollectionObjects-serverErrors.yml @@ -1,6 +1,6 @@ # listCollectionObjects returns an array of MongoCollection objects. # Not all drivers support this functionality. For more details, see: -# https://github.com/mongodb/specifications/blob/v1/source/enumerate-collections.rst#returning-a-list-of-collection-objects +# https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.md#returning-a-list-of-collection-objects description: listCollectionObjects-serverErrors diff --git a/source/retryable-reads/tests/unified/listCollectionObjects.yml b/source/retryable-reads/tests/unified/listCollectionObjects.yml index 93da6bd85e..739ad65a42 100644 --- a/source/retryable-reads/tests/unified/listCollectionObjects.yml +++ b/source/retryable-reads/tests/unified/listCollectionObjects.yml @@ -1,6 +1,6 @@ # listCollectionObjects returns an array of MongoCollection objects. # Not all drivers support this functionality. For more details, see: -# https://github.com/mongodb/specifications/blob/v1/source/enumerate-collections.rst#returning-a-list-of-collection-objects +# https://github.com/mongodb/specifications/blob/master/source/enumerate-collections.md#returning-a-list-of-collection-objects description: listCollectionObjects diff --git a/source/retryable-reads/tests/unified/listDatabaseObjects-serverErrors.yml b/source/retryable-reads/tests/unified/listDatabaseObjects-serverErrors.yml index 06815e1e8b..6704febfad 100644 --- a/source/retryable-reads/tests/unified/listDatabaseObjects-serverErrors.yml +++ b/source/retryable-reads/tests/unified/listDatabaseObjects-serverErrors.yml @@ -1,6 +1,6 @@ # listDatabaseObjects returns an array of MongoDatabase objects. # Not all drivers support this functionality. For more details, see: -# https://github.com/mongodb/specifications/blob/v1/source/enumerate-databases.rst#enumerating-mongodatabase-objects +# https://github.com/mongodb/specifications/blob/master/source/enumerate-databases.md#enumerating-mongodatabase-objects description: listDatabaseObjects-serverErrors diff --git a/source/retryable-reads/tests/unified/listDatabaseObjects.yml b/source/retryable-reads/tests/unified/listDatabaseObjects.yml index 3c94b6cca5..a7d1e7eb50 100644 --- a/source/retryable-reads/tests/unified/listDatabaseObjects.yml +++ b/source/retryable-reads/tests/unified/listDatabaseObjects.yml @@ -1,6 +1,6 @@ # listDatabaseObjects returns an array of MongoDatabase objects. # Not all drivers support this functionality. For more details, see: -# https://github.com/mongodb/specifications/blob/v1/source/enumerate-databases.rst#enumerating-mongodatabase-objects +# https://github.com/mongodb/specifications/blob/master/source/enumerate-databases.md#enumerating-mongodatabase-objects description: listDatabaseObjects diff --git a/source/retryable-writes/retryable-writes.md b/source/retryable-writes/retryable-writes.md index a6fb0559ca..9d9d01ec71 100644 --- a/source/retryable-writes/retryable-writes.md +++ b/source/retryable-writes/retryable-writes.md @@ -567,7 +567,7 @@ outage. In the case of a persistent outage, multiple retry attempts are fruitles [How To Write Resilient MongoDB Applications](https://emptysqua.re/blog/how-to-write-resilient-mongodb-applications/) for additional discussion on this strategy. -However when [Client Side Operations Timeout](../client-side-operations-timeout/client-side-operations-timeout.rst) is +However when [Client Side Operations Timeout](../client-side-operations-timeout/client-side-operations-timeout.md) is enabled, the driver will retry multiple times until the operation succeeds, a non-retryable error is encountered, or the timeout expires. Retrying multiple times provides greater resilience to cascading failures such as rolling server restarts during planned maintenance events. diff --git a/source/run-command/run-command.md b/source/run-command/run-command.md index 1ca0054ecf..772c6df052 100644 --- a/source/run-command/run-command.md +++ b/source/run-command/run-command.md @@ -67,7 +67,7 @@ interface RunCommandOptions { * An optional timeout option to govern the amount of time that a single operation can execute before control is returned to the user. * This timeout applies to all of the work done to execute the operation, including but not limited to server selection, connection checkout, and server-side execution. * - * @ see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst + * @ see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.md */ timeoutMS?: number; } @@ -152,7 +152,7 @@ as-is. - See Read Concern's section on [Generic Command Method](../read-write-concern/read-write-concern.md#generic-command-method) - See Write Concern's section on - [Generic Command Method](../read-write-concern/read-write-concern.md#generic-command-method-1) + [Generic Command Method](../read-write-concern/read-write-concern.md#generic-command-method) ##### Retryability @@ -202,7 +202,7 @@ interface RunCursorCommandOptions extends RunCommandOptions { * * @defaultValue CURSOR_LIFETIME * - * @see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.rst + * @see https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.md */ timeoutMode?: ITERATION | CURSOR_LIFETIME; diff --git a/source/run-command/tests/unified/runCommand.yml b/source/run-command/tests/unified/runCommand.yml index 9b0bf1ad63..bc55d79205 100644 --- a/source/run-command/tests/unified/runCommand.yml +++ b/source/run-command/tests/unified/runCommand.yml @@ -143,7 +143,7 @@ tests: # This test assumes that the single topology contains a standalone server; # however, it is possible for a single topology to contain a direct # connection to another server type. - # See: https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.rst#topology-type-single + # See: https://github.com/mongodb/specifications/blob/master/source/server-selection/server-selection.md#topology-type-single - topologies: [ single ] operations: - name: runCommand diff --git a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md index cdbece9bad..19b29ba6ef 100644 --- a/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md +++ b/source/server-discovery-and-monitoring/server-discovery-and-monitoring.md @@ -135,7 +135,7 @@ A timeout that occurs while reading from or writing to a network socket. #### minHeartbeatFrequencyMS -Defined in the [Server Monitoring spec](server-monitoring.rst). This value MUST be 500 ms, and it MUST NOT be +Defined in the [Server Monitoring spec](server-monitoring.md). This value MUST be 500 ms, and it MUST NOT be configurable. #### pool generation number @@ -187,9 +187,11 @@ See [parsing a hello or legacy hello response](#parsing-a-hello-or-legacy-hello- > [!NOTE] > Single-threaded clients use the PossiblePrimary type to maintain proper -> [scanning order](server-monitoring.rst#scanning-order). Multi-threaded and asynchronous clients do not need this +> [scanning order](server-monitoring.md#scanning-order). Multi-threaded and asynchronous clients do not need this > ServerType; it is synonymous with Unknown. + + #### TopologyDescription The client's representation of everything it knows about the deployment's topology. @@ -335,6 +337,8 @@ option is not specified, the driver MUST start in Unknown topology, and follow t [TopologyType table](#topologytype-table) for transitioning to other topologies. In particular, the driver MUST NOT use the number of hosts from the initial SRV lookup to decide what topology to start in. + + #### heartbeatFrequencyMS The interval between server [checks](#check), counted from the end of the previous check until the beginning of the next @@ -381,7 +385,7 @@ servers from its `TopologyDescription` and set its `TopologyType` to `Unknown`, ### Monitoring -See the [Server Monitoring spec](server-monitoring.rst) for how a driver monitors each server. In summary, the client +See the [Server Monitoring spec](server-monitoring.md) for how a driver monitors each server. In summary, the client monitors each server in the topology. The scope of server monitoring is to provide the topology with updated ServerDescriptions based on hello or legacy hello command responses. @@ -467,7 +471,7 @@ field. Drivers MUST record the server's [round trip time](#round-trip-time) (RTT) after each successful call to hello or legacy hello. The Server Selection Spec describes how RTT is averaged and how it is used in server selection. Drivers MUST also -record the server's minimum RTT per [Server Monitoring (Measuring RTT)](server-monitoring.rst#measuring-rtt). +record the server's minimum RTT per [Server Monitoring (Measuring RTT)](server-monitoring.md#measuring-rtt). If a hello or legacy hello call fails, the RTT is not updated. Furthermore, while a server's type is Unknown its RTT is null, and if it changes from a known type to Unknown its RTT is set to null. However, if it changes from one known type @@ -734,6 +738,8 @@ else: See [TopologyType remains Unknown when one of the seeds is a Standalone](#topologytype-remains-unknown-when-one-of-the-seeds-is-a-standalone). + + ##### updateRSWithoutPrimary This subroutine is executed with the ServerDescription from an RSSecondary, RSArbiter, or RSOther when the TopologyType @@ -811,6 +817,8 @@ if there is no primary in topologyDescription.servers: The special handling of description.primary ensures that a single-threaded client [scans](#scan) the possible primary before other members. + + ##### updateRSFromPrimary This subroutine is executed with a ServerDescription of type RSPrimary: @@ -894,7 +902,7 @@ checkIfHasPrimary() A note on invalidating the old primary: when a new primary is discovered, the client finds the previous primary (there should be none or one) and replaces its description with a default ServerDescription of type "Unknown." A multi-threaded -client MUST [request an immediate check](server-monitoring.rst#requesting-an-immediate-check) for that server as soon as +client MUST [request an immediate check](server-monitoring.md#requesting-an-immediate-check) for that server as soon as possible. If the old primary server version is 4.0 or earlier, the client MUST clear its connection pool for the old primary, too: @@ -948,7 +956,7 @@ to be [data-bearing](server-discovery-and-monitoring.md#data-bearing-server-type [direct connection](server-discovery-and-monitoring.md#general-requirements) to the server is requested, and does not already have a connection pool, the driver MUST create the connection pool for the server. Additionally, if a driver implements a CMAP compliant connection pool, the server's pool (even if it already existed) MUST be marked as "ready". -See the [Server Monitoring spec](server-monitoring.rst) for more information. +See the [Server Monitoring spec](server-monitoring.md) for more information. Clearing the connection pool for a server MUST be synchronized with the update to the corresponding ServerDescription (e.g. by holding the lock on the TopologyDescription when clearing the pool). This prevents a possible race between the @@ -960,7 +968,7 @@ for more information. #### Network error during server check -See error handling in the [Server Monitoring spec](server-monitoring.rst). +See error handling in the [Server Monitoring spec](server-monitoring.md). #### Application errors @@ -1188,7 +1196,7 @@ new ServerDescription's error field, including the error message from the server [What is the purpose of topologyVersion?](#what-is-the-purpose-of-topologyversion)) Multi-threaded and asynchronous clients MUST -[request an immediate check](server-monitoring.rst#requesting-an-immediate-check) of the server. Unlike in the "network +[request an immediate check](server-monitoring.md#requesting-an-immediate-check) of the server. Unlike in the "network error" scenario above, a "not writable primary" or "node is recovering" error means the server is available but the client is wrong about its type, thus an immediate re-check is likely to provide useful information. @@ -1222,24 +1230,24 @@ connection pool if the TopologyType is not LoadBalanced. (See ### Monitoring SDAM events The required driver specification for providing lifecycle hooks into server discovery and monitoring for applications to -consume can be found in the [SDAM Monitoring Specification](server-discovery-and-monitoring-logging-and-monitoring.rst). +consume can be found in the [SDAM Monitoring Specification](server-discovery-and-monitoring-logging-and-monitoring.md). ### Implementation notes This section intends to provide generous guidance to driver authors. It is complementary to the reference implementations. Words like "should", "may", and so on are used more casually here. -See also, the implementation notes in the [Server Monitoring spec](server-monitoring.rst). +See also, the implementation notes in the [Server Monitoring spec](server-monitoring.md). #### Multi-threaded or asynchronous server selection While no suitable server is available for an operation, [the client MUST re-check all servers every minHeartbeatFrequencyMS](#the-client-must-re-check-all-servers-every-minheartbeatfrequencyms). -(See [requesting an immediate check](server-monitoring.rst#requesting-an-immediate-check).) +(See [requesting an immediate check](server-monitoring.md#requesting-an-immediate-check).) #### Single-threaded server selection -When a client that uses [single-threaded monitoring](server-monitoring.rst#single-threaded-monitoring) fails to select a +When a client that uses [single-threaded monitoring](server-monitoring.md#single-threaded-monitoring) fails to select a suitable server for any operation, it [scans](#scan) the servers, then attempts selection again, to see if the scan discovered suitable servers. It repeats, waiting [minHeartbeatFrequencyMS](#minheartbeatfrequencyms) after each scan, until a timeout. diff --git a/source/server-discovery-and-monitoring/server-monitoring.md b/source/server-discovery-and-monitoring/server-monitoring.md index 31aa9afb94..a9f58ebd3f 100644 --- a/source/server-discovery-and-monitoring/server-monitoring.md +++ b/source/server-discovery-and-monitoring/server-monitoring.md @@ -20,7 +20,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH ### Terms -See the terms in the [main SDAM spec](server-discovery-and-monitoring.rst). +See the terms in the [main SDAM spec](server-discovery-and-monitoring.md). #### check @@ -59,14 +59,16 @@ The hello or legacy hello command feature which allows the server to stream mult #### RTT Round trip time. The client's measurement of the duration of one hello or legacy hello call. The RTT is used to support -[localThresholdMS](../server-selection/server-selection.md#localThresholdMS) from the Server Selection spec and -[timeoutMS](../client-side-operations-timeout/client-side-operations-timeout.md#timeoutMS) from the +[localThresholdMS](../server-selection/server-selection.md#localthresholdms) from the Server Selection spec and +[timeoutMS](../client-side-operations-timeout/client-side-operations-timeout.md#timeoutms) from the [Client Side Operations Timeout Spec](../client-side-operations-timeout/client-side-operations-timeout.md). #### FaaS A Function-as-a-Service (FaaS) environment like AWS Lambda. + + #### serverMonitoringMode The serverMonitoringMode option configures which server monitoring protocol to use. Valid modes are "stream", "poll", or @@ -104,9 +106,9 @@ users configure the timeouts for monitoring sockets separately if necessary to p The client begins monitoring a server when: - ... the client is initialized and begins monitoring each seed. See - [initial servers](server-discovery-and-monitoring.rst#initial-servers). -- ... [updateRSWithoutPrimary](server-discovery-and-monitoring.rst#updateRSWithoutPrimary) or - [updateRSFromPrimary](server-discovery-and-monitoring.rst#updateRSFromPrimary) discovers new replica set members. + [initial servers](server-discovery-and-monitoring.md#initial-servers). +- ... [updateRSWithoutPrimary](server-discovery-and-monitoring.md#updateRSWithoutPrimary) or + [updateRSFromPrimary](server-discovery-and-monitoring.md#updateRSFromPrimary) discovers new replica set members. The following subsections specify how monitoring works, first in multi-threaded or asynchronous clients, and second in single-threaded clients. This spec provides detailed requirements for monitoring because it intends to make all drivers @@ -141,7 +143,7 @@ NOT run while a previous check is still in progress. ##### Requesting an immediate check At any time, the client can request that a monitor check its server immediately. (For example, after a "not writable -primary" error. See [error handling](server-discovery-and-monitoring.rst#error-handling).) If the monitor is sleeping +primary" error. See [error handling](server-discovery-and-monitoring.md#error-handling).) If the monitor is sleeping when this request arrives, it MUST wake and check as soon as possible. If a hello or legacy hello call is already in progress, the request MUST be ignored. If the previous check ended less than [minHeartbeatFrequencyMS](#minheartbeatfrequencyms) ago, the monitor MUST sleep until the minimum delay has passed, then @@ -169,6 +171,8 @@ have [streaming disabled](#streaming-disabled), it MUST use the [streaming proto #### Single-threaded monitoring + + ##### cooldownMS After a single-threaded client gets a network error trying to [check](#check) a server, the client skips re-checking the @@ -178,6 +182,8 @@ This avoids spending connectTimeoutMS on each unavailable server during each sca This value MUST be 5000 ms, and it MUST NOT be configurable. + + ##### Scanning Single-threaded clients MUST [scan](#scan) all servers synchronously, inline with regular application operations. Before @@ -235,11 +241,11 @@ This algorithm might be better understood with an example: 3. The secondary's hello or legacy hello response includes the "primary" field with the address of the server that the secondary thinks is primary. 4. The client creates a ServerDescription with that address, type PossiblePrimary, and lastUpdateTime "infinity ago". - (See [updateRSWithoutPrimary](server-discovery-and-monitoring.rst#updateRSWithoutPrimary).) + (See [updateRSWithoutPrimary](server-discovery-and-monitoring.md#updateRSWithoutPrimary).) 5. On the next iteration, there is still no RSPrimary, so the new PossiblePrimary is the top-priority server to check. 6. The PossiblePrimary is checked and replaced with an RSPrimary. The client has now acquired an authoritative host list. Any new hosts in the list are added to the TopologyDescription with lastUpdateTime "infinity ago". (See - [updateRSFromPrimary](server-discovery-and-monitoring.rst#updateRSFromPrimary).) + [updateRSFromPrimary](server-discovery-and-monitoring.md#updateRSFromPrimary).) 7. The client continues scanning until all known hosts have been checked. Another common case might be scanning a pool of mongoses. When the client first scans its seed list, they all have the @@ -264,7 +270,7 @@ breaks backwards compatibility. For both multi- and single-threaded drivers, the driver MUST NOT permit users to configure it less than minHeartbeatFrequencyMS (500ms). -(See [heartbeatFrequencyMS in the main SDAM spec](server-discovery-and-monitoring.rst#heartbeatFrequencyMS).) +(See [heartbeatFrequencyMS in the main SDAM spec](server-discovery-and-monitoring.md#heartbeatFrequencyMS).) ### Awaitable hello or legacy hello Server Specification @@ -460,7 +466,7 @@ streaming hello or legacy hello response MUST be interrupted such that threads m maxAwaitTimeMS. When a client marks a server Unknown from -[Network error when reading or writing](server-discovery-and-monitoring.rst#network-error-when-reading-or-writing), +[Network error when reading or writing](server-discovery-and-monitoring.md#network-error-when-reading-or-writing), clients MUST cancel the hello or legacy hello check on that server and close the current monitoring connection. (See [Drivers cancel in-progress monitor checks](#drivers-cancel-in-progress-monitor-checks).) @@ -475,7 +481,7 @@ another check. When a monitor completes a successful check against a server, it MUST mark the connection pool for that server as "ready", and doing so MUST be synchronized with the update to the topology (e.g. by marking the pool as ready in onServerDescriptionChanged). This is required to ensure a server does not get selected while its pool is still paused. -See the [Connection Pool](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#Connection-Pool) +See the [Connection Pool](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#connection-pool) definition in the CMAP specification for more details on marking the pool as "ready". ### Error handling @@ -490,9 +496,9 @@ the client MUST follow these steps: 3. Clear the connection pool for the server (See [Clear the connection pool on both network and command errors](#clear-the-connection-pool-on-both-network-and-command-errors)). For CMAP compliant drivers, clearing the pool MUST be synchronized with marking the server as Unknown (see - [Why synchronize clearing a server's pool with updating the topology?](server-discovery-and-monitoring.rst#why-synchronize-clearing-a-server-s-pool-with-updating-the-topology?)). + [Why synchronize clearing a server's pool with updating the topology?](server-discovery-and-monitoring.md#why-synchronize-clearing-a-servers-pool-with-updating-the-topology)). If this was a network timeout error, then the pool MUST be cleared with interruptInUseConnections = true (see - [Why does the pool need to support closing in use connections as part of its clear logic?](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#Why-does-the-pool-need-to-support-closing-in-use-connections-as-part-of-its-clear-logic?)) + [Why does the pool need to support closing in use connections as part of its clear logic?](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#why-does-the-pool-need-to-support-interrupting-in-use-connections-as-part-of-its-clear-logic)) 4. If this was a network error and the server was in a known state before the error, the client MUST NOT sleep and MUST begin the next check immediately. (See [retry hello or legacy hello calls once](#retry-hello-or-legacy-hello-calls-once) and @@ -824,7 +830,7 @@ the same rule for the sake of consistency. ### Monitors MUST use a dedicated connection for RTT commands When using the streaming protocol, a monitor needs to maintain an extra dedicated connection to periodically update its -average round trip time in order to support [localThresholdMS](../server-selection/server-selection.md#localThresholdMS) +average round trip time in order to support [localThresholdMS](../server-selection/server-selection.md#localthresholdms) from the Server Selection spec. It could pop a connection from its regular pool, but we rejected this option for a few reasons: @@ -865,7 +871,7 @@ ticking clock, since it will seem like it spends the least time on the wire. Additionally, systems using NTP will experience clock "slew". ntpd "slews" time by up to 500 parts-per-million to have the local time gradually approach the "true" time without big jumps - over a 10 second window that means a 5ms difference. If both sides are slewing in opposite directions, that can result in an effective difference of 10ms. Both -of these times are close enough to [localThresholdMS](../server-selection/server-selection.md#localThresholdMS) to +of these times are close enough to [localThresholdMS](../server-selection/server-selection.md#localthresholdms) to significantly affect which servers are viable in NEAREST calculations. Ensuring that all measurements use the same clock obviates the need for a more complicated solution, and mitigates the @@ -911,7 +917,7 @@ A monitor clears the connection pool when a server check fails with a network or with a network error it is likely that all connections to that server are also closed. (See [JAVA-1252](https://jira.mongodb.org/browse/JAVA-1252)). When the check fails with a network timeout error, a monitor MUST set interruptInUseConnections to true. See, -[Why does the pool need to support closing in use connections as part of its clear logic?](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#Why-does-the-pool-need-to-support-closing-in-use-connections-as-part-of-its-clear-logic?). +[Why does the pool need to support closing in use connections as part of its clear logic?](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#why-does-the-pool-need-to-support-interrupting-in-use-connections-as-part-of-its-clear-logic). When the server is shutting down, it may respond to hello or legacy hello commands with ShutdownInProgress errors before closing connections. In this case, the monitor clears the connection pool because all connections will be closed soon. @@ -919,7 +925,7 @@ Other command errors are unexpected but are handled identically. ### Why must streaming hello or legacy hello clients publish ServerHeartbeatStartedEvents? -The [SDAM Monitoring spec](server-discovery-and-monitoring-logging-and-monitoring.rst#heartbeats) guarantees that every +The [SDAM Monitoring spec](server-discovery-and-monitoring-logging-and-monitoring.md#heartbeats) guarantees that every ServerHeartbeatStartedEvent has either a correlating ServerHeartbeatSucceededEvent or ServerHeartbeatFailedEvent. This is consistent with Command Monitoring on exhaust cursors where the driver publishes a fake CommandStartedEvent before reading the next getMore response. diff --git a/source/server-discovery-and-monitoring/tests/README.md b/source/server-discovery-and-monitoring/tests/README.md index 23f4fe00ab..4f30022016 100644 --- a/source/server-discovery-and-monitoring/tests/README.md +++ b/source/server-discovery-and-monitoring/tests/README.md @@ -69,7 +69,7 @@ responses in the phases so far. It has the following keys: A "server" object represents a correct ServerDescription within the client's current TopologyDescription. It has the following keys: -- type: A ServerType name, like "RSSecondary". See [ServerType](../server-discovery-and-monitoring.rst#servertype) for +- type: A ServerType name, like "RSSecondary". See [ServerType](../server-discovery-and-monitoring.md#servertype) for details pertaining to async and multi-threaded drivers. - setName: A string with the expected replica set name, or null. - setVersion: absent or an integer. diff --git a/source/server-selection/server-selection.md b/source/server-selection/server-selection.md index 13ba821e25..193dbc6f20 100644 --- a/source/server-selection/server-selection.md +++ b/source/server-selection/server-selection.md @@ -162,8 +162,8 @@ The process by which a server is chosen for a database operation out of all pote An enumerated type indicating whether a server is up or down, whether it is a mongod or mongos, whether it belongs to a replica set and, if so, what role it serves in the replica set. See the -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec for more details. +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec for more +details. **Suitable** @@ -190,9 +190,8 @@ The state of a deployment, including its type, which servers are members, and th **Topology type** An enumerated type indicating the semantics for monitoring servers and selecting servers for database operations. See -the -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec for more details. +the [Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec for +more details. ### Assumptions @@ -203,8 +202,7 @@ spec for more details. reconfiguration. - Low-latency: all else being equal, faster responses to queries and writes are preferable. 2. Clients know the state of a deployment based on some form of ongoing monitoring, following the rules defined in the - [Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) - spec. + [Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec. - They know which members are up or down, what their tag sets are, and their types. - They know average round trip times to each available member. - They detect reconfiguration and the addition or removal of members. @@ -256,8 +254,7 @@ The serverSelectionTryOnce option MUST be true by default. If it is set false, t an appropriate server until the selection process times out (pausing [minHeartbeatFrequencyMS](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#minheartbeatfrequencyms) between attempts, as required by the -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec). +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec). Users of single-threaded drivers MUST be able to control this mode in one or both of these ways: @@ -276,9 +273,8 @@ for a ["try once" mode](#try-once-mode).) This controls when topology updates are scheduled. See [heartbeatFrequencyMS](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#heartbeatfrequencyms) in -the -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec for details. +the [Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec for +details. #### socketCheckIntervalMS @@ -294,7 +290,7 @@ See [checking an idle socket after socketCheckIntervalMS](#checking-an-idle-sock A constant, how often an idle primary writes a no-op to the oplog. See [idleWritePeriodMS](../max-staleness/max-staleness.md#idlewriteperiodms) in the -[Max Staleness](https://github.com/mongodb/specifications/tree/master/source/max-staleness) spec for details. +[Max Staleness](../max-staleness/max-staleness.md) spec for details. #### smallestMaxStalenessSeconds @@ -358,9 +354,8 @@ Otherwise, when there are no eligible secondaries, the primary is suitable. The primary and all secondaries are candidates, but only eligible candidates are suitable. *Note on other server types*: The -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec defines several other server types that could appear in a replica set. Such types are never candidates, eligible or -suitable. +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec defines +several other server types that could appear in a replica set. Such types are never candidates, eligible or suitable. @@ -384,9 +379,8 @@ maxStalenessSeconds >= smallestMaxStalenessSeconds ``` `heartbeatFrequencyMS` is defined in the -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec, and `idleWritePeriodMS` is defined to be 10 seconds in the -[Max Staleness](https://github.com/mongodb/specifications/tree/master/source/max-staleness) spec. +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec, and +`idleWritePeriodMS` is defined to be 10 seconds in the [Max Staleness](../max-staleness/max-staleness.md) spec. See "Smallest allowed value for maxStalenessSeconds" in the Max Staleness Spec. @@ -497,6 +491,8 @@ db.collection.find( hedge={'enabled': true}) ``` + + #### Passing read preference to mongos and load balancers If a server of type Mongos or LoadBalancer is selected for a read operation, the read preference is passed to the @@ -1324,8 +1320,8 @@ The server selection test plan is given in a separate document that describes th ### Use of topology types The prior version of the read preference spec had only a loose definition of server or topology types. The -[Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) -spec defines these terms explicitly and they are used here for consistency and clarity. +[Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) spec defines +these terms explicitly and they are used here for consistency and clarity. ### Consistency with mongos @@ -1603,9 +1599,8 @@ maxStalenessSeconds first, then tag_sets, and select Node 2. ## References -- [Server Discovery and Monitoring](https://github.com/mongodb/specifications/tree/master/source/server-discovery-and-monitoring) - specification -- [Driver Authentication](https://github.com/mongodb/specifications/blob/master/source/auth) specification +- [Server Discovery and Monitoring](../server-discovery-and-monitoring/server-discovery-and-monitoring.md) specification +- [Driver Authentication](../auth/auth.md) specification - [Connection Monitoring and Pooling](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md) specification diff --git a/source/serverless-testing/README.md b/source/serverless-testing/README.md index 8ebe6e81f2..8f837df3ad 100644 --- a/source/serverless-testing/README.md +++ b/source/serverless-testing/README.md @@ -85,7 +85,7 @@ testing suite: - Client Side Encryption - Drivers MUST test with a version of the `crypt_shared` shared library that matches the MongoDB Server version running in Serverless. See - [Using crypt_shared](https://github.com/mongodb/specifications/tree/e761591616849d9b507287811e77f7a359fb9587/source/client-side-encryption/tests#using-crypt-shared). + [Using crypt_shared](../client-side-encryption/client-side-encryption.md#enabling-crypt_shared). Note that the legacy JSON/YAML test formats for these specifications were updated to include a new `runOnRequirement` specifically for Atlas Serverless testing. To ensure these requirements are enforced properly, the runner MUST be diff --git a/source/transactions/tests/legacy-test-format.md b/source/transactions/tests/legacy-test-format.md index eb05c1f9fe..4b6fe3317c 100644 --- a/source/transactions/tests/legacy-test-format.md +++ b/source/transactions/tests/legacy-test-format.md @@ -57,10 +57,6 @@ The `data` option is a document that may be used to specify options that control - `blockTimeMS`: The number of milliseconds the affect commands should be blocked for. Required when blockConnection is true. [New in mongod 4.3.4](https://jira.mongodb.org/browse/SERVER-41070). -## Speeding Up Tests - -See [Speeding Up Tests](../../retryable-reads/tests/README.md#speeding-up-tests) in the retryable reads spec tests. - ## Test Format Each YAML file has the following keys: @@ -246,8 +242,8 @@ Then for each element in `tests`: 13. If the test includes a list of command-started events in `expectations`, compare them to the actual command-started events using the same logic as the - [legacy Command Monitoring Spec Tests runner](https://github.com/mongodb/specifications/blob/09ee1ebc481f1502e3246971a9419e484d736207/source/command-monitoring/tests/README.rst#expectations), - plus the rules in the Command-Started Events instructions below. + [legacy Command Monitoring Spec Tests runner](../../command-logging-and-monitoring/tests/README.md), plus the rules + in the Command-Started Events instructions below. 14. If `failPoint` is specified, disable the fail point to avoid spurious failures in subsequent tests. The fail point may be disabled like so: @@ -467,7 +463,7 @@ sharded transaction that uses the `dbVersion` concept so it is the only command - 2024-02-15: Migrated from reStructuredText to Markdown. -- 2024-02-07: Moved legacy test format docs to this file from README.rst. +- 2024-02-07: Moved legacy test format docs to this file from README.md. - 2023-09-28: Add `load-balanced` to test topology requirements. diff --git a/source/transactions/transactions.md b/source/transactions/transactions.md index 59aaf2502f..5e678c58b2 100644 --- a/source/transactions/transactions.md +++ b/source/transactions/transactions.md @@ -289,7 +289,7 @@ containing the message "Transaction already in progress" without modifying any s startTransaction SHOULD report an error if the driver can detect that transactions are not supported by the deployment. A deployment does not support transactions when the deployment does not support sessions, or maxWireVersion \< 7, or the maxWireVersion \< 8 and the topology type is Sharded, see -[How to Check Whether a Deployment Supports Sessions](../sessions/driver-sessions.md#how-to-check-whether-a-deployment-supports-sessions). +[How to Tell Whether a Connection Supports Sessions](../sessions/driver-sessions.md#how-to-tell-whether-a-connection-supports-sessions). Note that checking the maxWireVersion does not guarantee that the deployment supports transactions, for example a MongoDB 4.0 replica set using MMAPv1 will report maxWireVersion 7 but does not support transactions. In this case, Drivers rely on the deployment to report an error when a transaction is started. diff --git a/source/unified-test-format/unified-test-format.md b/source/unified-test-format/unified-test-format.md index b80d84fee2..7d60af7c5b 100644 --- a/source/unified-test-format/unified-test-format.md +++ b/source/unified-test-format/unified-test-format.md @@ -488,8 +488,8 @@ The structure of this object is as follows: - `ignoreCommandMonitoringEvents`: Optional array of one or more strings. Command names for which the test runner MUST ignore any observed command monitoring events. The command(s) will be ignored in addition to `configureFailPoint` and any commands containing sensitive information (per the - [Command Logging and Monitoring](../command-logging-and-monitoring/command-monitoring.rst#security) spec) unless - `observeSensitiveCommands` is true. + [Command Logging and Monitoring](../command-logging-and-monitoring/command-logging-and-monitoring.md#security) spec) + unless `observeSensitiveCommands` is true. Test files SHOULD NOT use this option unless one or more command monitoring events are specified in [observeEvents](#entity_client_observeEvents). @@ -971,7 +971,7 @@ The structure of each object is as follows: - `eventType`: Optional string. Specifies the type of the monitor which captured the events. Valid values are `command` for [Command Monitoring](../command-logging-and-monitoring/command-logging-and-monitoring.md#events-api) events, `cmap` for [CMAP](../connection-monitoring-and-pooling/connection-monitoring-and-pooling.md#events) events, and `sdam` - for [SDAM](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + for [SDAM](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) events. Defaults to `command` if omitted. - `events`: Required array of [expectedEvent](#expectedevent) objects. List of events, which are expected to be observed (in this order) on the corresponding client while executing [operations](#test_operations). If the array is empty, the @@ -1005,7 +1005,7 @@ The structure of this object is as follows: - `commandStartedEvent`: Optional object. Assertions for one or more - [CommandStartedEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#api) fields. + [CommandStartedEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1021,7 +1021,7 @@ The structure of this object is as follows: - `commandSucceededEvent`: Optional object. Assertions for one or more - [CommandSucceededEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#api) fields. + [CommandSucceededEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1037,7 +1037,7 @@ The structure of this object is as follows: - `commandFailedEvent`: Optional object. Assertions for one or more - [CommandFailedEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#api) fields. + [CommandFailedEvent](../command-logging-and-monitoring/command-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1129,7 +1129,7 @@ The structure of this object is as follows: - `serverDescriptionChangedEvent`: Optional object. Assertions for one or more - [ServerDescriptionChangedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + [ServerDescriptionChangedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1150,7 +1150,7 @@ The structure of this object is as follows: - `serverHeartbeatStartedEvent`: Optional object. Assertions for one or more - [ServerHeartbeatStartedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + [ServerHeartbeatStartedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1160,7 +1160,7 @@ The structure of this object is as follows: - `serverHeartbeatSucceededEvent`: Optional object. Assertions for one or more - [ServerHeartbeatSucceededEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + [ServerHeartbeatSucceededEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1170,7 +1170,7 @@ The structure of this object is as follows: - `serverHeartbeatFailedEvent`: Optional object. Assertions for one or more - [ServerHeartbeatFailedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + [ServerHeartbeatFailedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) fields. The structure of this object is as follows: @@ -1180,7 +1180,7 @@ The structure of this object is as follows: - `topologyDescriptionChangedEvent`: Optional object. Assertions for one - [TopologyDescriptionChangedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events) + [TopologyDescriptionChangedEvent](../server-discovery-and-monitoring/server-discovery-and-monitoring-logging-and-monitoring.md#events-api) object. The structure of this object is as follows: @@ -1241,6 +1241,8 @@ The structure of each object is as follows: `false`, observed logs after all specified logs have matched MUST cause a test failure; if `true`, observed logs after all specified logs have been matched MUST NOT cause a test failure. Defaults to `false`. + + #### expectedLogMessage A log message which is expected to be observed while executing the test's operations. @@ -1248,10 +1250,10 @@ A log message which is expected to be observed while executing the test's operat The structure of each object is as follows: - `level`: Required string. This MUST be one of the level names listed in - [log severity levels](logging/logging.rst#log-severity-levels). This specifies the expected level for the log message - and corresponds to the level used for the message in the specification that defines it. Note that since not all - drivers will necessarily support all log levels, some driver may need to map the specified level to the corresponding - driver-supported level. Test runners MUST assert that the actual level matches this value. + [log severity levels](../logging/logging.md#log-severity-levels). This specifies the expected level for the log + message and corresponds to the level used for the message in the specification that defines it. Note that since not + all drivers will necessarily support all log levels, some driver may need to map the specified level to the + corresponding driver-supported level. Test runners MUST assert that the actual level matches this value. - `component`: Required string. This MUST be one of the component names listed in [components](../logging/logging.md#components). This specifies the expected component for the log message. Note that @@ -1886,10 +1888,11 @@ first position (e.g. `rewind` in PHP). Iterates the cursor until either a single document is returned or an error is raised. This operation takes no arguments. If [expectResult](#operation_expectResult) is specified, it SHOULD be a single document. -Some specification sections (e.g. [Iterating the Change Stream](../change-streams/tests#iterating-the-change-stream)) -caution drivers that implement a blocking mode of iteration (e.g. asynchronous drivers) not to iterate the cursor -unnecessarily, as doing so could cause the test runner to block indefinitely. This should not be a concern for -`iterateUntilDocumentOrError` as iteration only continues until either a document or error is encountered. +Some specification sections (e.g. +[Iterating the Change Stream](../change-streams/tests/README.md#iterating-the-change-stream)) caution drivers that +implement a blocking mode of iteration (e.g. asynchronous drivers) not to iterate the cursor unnecessarily, as doing so +could cause the test runner to block indefinitely. This should not be a concern for `iterateUntilDocumentOrError` as +iteration only continues until either a document or error is encountered. #### iterateOnce diff --git a/source/uri-options/uri-options.md b/source/uri-options/uri-options.md index 2432a65383..a5dd2092d5 100644 --- a/source/uri-options/uri-options.md +++ b/source/uri-options/uri-options.md @@ -70,55 +70,55 @@ 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.md#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.md) | -| 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.md#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.md#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.md#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.md#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.md#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.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 | -| 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.md#tlsDisableCertificateRevocationCheck) for additional information. | -| tlsDisableOCSPEndpointCheck | "true" or "false" | false i.e. driver will reach out to OCSP endpoints [if needed](../ocsp-support/ocsp-support.md#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.md#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 | +| Name | Accepted Values | Default Value | Optional to implement? | Description | +| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| appname | any string that meets the criteria listed in the [handshake spec](../mongodb-handshake/handshake.md#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.md) | +| directConnection | "true" or "false" | defined in [SDAM spec](../server-discovery-and-monitoring/server-discovery-and-monitoring.md#initial-topologytype) | 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.md#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) | 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) | 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) | 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) | 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.md#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.md#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.md#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.md#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.md#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-monitoring.md#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.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 | +| 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.md#tlsdisablecertificaterevocationcheck) for additional information. | +| tlsDisableOCSPEndpointCheck | "true" or "false" | false i.e. driver will reach out to OCSP endpoints [if needed](../ocsp-support/ocsp-support.md#tlsdisableocspendpointcheck). | Yes | Controls whether or not the driver will reach out to OCSP endpoints if needed. See the [OCSP Support Spec](../ocsp-support/ocsp-support.md#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) | 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) | 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