From 5f4297abea385c40441b547c6d441930087cbb2a Mon Sep 17 00:00:00 2001 From: Iris Ho Date: Thu, 7 May 2026 14:39:28 -0700 Subject: [PATCH 01/14] use op_msg for all handshakes --- source/mongodb-handshake/handshake.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 5a62627326..6b30629e2e 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -49,11 +49,12 @@ MongoDB uses the `hello` or `isMaster` commands for handshakes and topology moni preferred command. `hello` must always be sent using the `OP_MSG` protocol. `isMaster` is referred to as "legacy hello" and is maintained for backwards compatibility with servers that do not support the `hello` command. -If a [server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST use the -`hello` command for the initial handshake and use the `OP_MSG` protocol. If server API version is not requested and -`loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake with the `OP_QUERY` -protocol (before switching to `OP_MSG` if the `maxWireVersion` indicates compatibility), and include `helloOk:true` in -the handshake request. +Drivers SHOULD use the `OP_MSG` protocol for all handshakes if their minWireVersion is 6 (MongoDB 3.6) or higher. If a +[server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST also use the +`hello` command for the initial handshake. If server API version is not requested and +`loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake, and include +`helloOk:true` in the handshake request. If the server does not understand `OP_MSG`, drivers MUST show the same error +message as when wire version checks fail (e.g. because the server's maxWireVersion is lower than the driver's minWireVersion). ASIDE: If the legacy handshake response includes `helloOk: true`, then subsequent topology monitoring commands MUST use the `hello` command. If the legacy handshake response does not include `helloOk: true`, then subsequent topology @@ -78,12 +79,11 @@ Consider the following pseudo-code for establishing a new connection: ```python conn = Connection() conn.connect() # Connect via TCP / TLS +conn.supports_op_msg = True # Always send the initial command via OP_MSG. if stable_api_configured or client_options.load_balanced: cmd = {"hello": 1} - conn.supports_op_msg = True # Send the initial command via OP_MSG. else: cmd = {"legacy hello": 1, "helloOk": 1} - conn.supports_op_msg = False # Send the initial command via OP_QUERY. cmd["backpressure"] = True cmd["client"] = client_metadata if client_options.compressors: @@ -99,9 +99,9 @@ if creds: reply = conn.send_command("admin", cmd) -if reply["maxWireVersion"] >= 6: - # Use OP_MSG for all future commands, including authentication. - conn.supports_op_msg = True +if reply["maxWireVersion"] < 6: + # Server is reporting that it doesn't support OpMSG + raise Error() # Store the negotiated compressor, see OP_COMPRESSED spec. if reply.get("compression"): @@ -564,6 +564,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog +- 2026-05-06: Allow OP_MSG for all handshakes. - 2025-09-04: Clarify that drivers do not append the same metadata multiple times. - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization. - 2024-11-05: Move handshake prose tests from spec file to prose test file. From 532906261ba2f6e59e736500f8fefab618ed7ac3 Mon Sep 17 00:00:00 2001 From: Iris Ho Date: Thu, 7 May 2026 14:46:55 -0700 Subject: [PATCH 02/14] no longer need to use op_query during handshake --- source/message/OP_MSG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index a8e8eb2edd..a6c15c1b03 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -20,7 +20,7 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH `OP_MSG` is only available in MongoDB 3.6 (`maxWireVersion >= 6`) and later. MongoDB drivers MUST perform the MongoDB handshake using `OP_MSG` if an API version was declared on the client. -If no API version was declared, drivers that have historically supported MongoDB 3.4 and earlier MUST perform the +If no API version was declared, drivers that have historically supported MongoDB 3.4 and earlier MAY perform the handshake using `OP_QUERY` to determine if the node supports `OP_MSG`. Drivers that have only ever supported MongoDB 3.6 and newer MAY default to using `OP_MSG`. From cc595db2b9e8a07c20c0f960f84df988d7cea0c3 Mon Sep 17 00:00:00 2001 From: Iris Ho Date: Thu, 7 May 2026 14:49:14 -0700 Subject: [PATCH 03/14] update changelogs --- source/message/OP_MSG.md | 1 + source/mongodb-handshake/handshake.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index a6c15c1b03..32f96a142c 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -409,6 +409,7 @@ In the near future, this opcode is expected to be extended and include support f ### Changelog +- 2026-05-07: Allow OP_MSG for all handshakes. - 2024-04-30: Convert from RestructuredText to Markdown. - 2022-10-05: Remove spec front matter. - 2022-01-13: Clarify that `OP_MSG` must be used when using stable API diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 6b30629e2e..ee8d34d61f 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -564,7 +564,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog -- 2026-05-06: Allow OP_MSG for all handshakes. +- 2026-05-07: Allow OP_MSG for all handshakes. - 2025-09-04: Clarify that drivers do not append the same metadata multiple times. - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization. - 2024-11-05: Move handshake prose tests from spec file to prose test file. From 6923bb51095900ac6cc90a2e956a8fea497b140d Mon Sep 17 00:00:00 2001 From: Iris Ho Date: Fri, 8 May 2026 10:15:39 -0700 Subject: [PATCH 04/14] update changelog date and error message when wire check fails --- source/message/OP_MSG.md | 2 +- source/mongodb-handshake/handshake.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index 32f96a142c..63f62aca35 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -409,7 +409,7 @@ In the near future, this opcode is expected to be extended and include support f ### Changelog -- 2026-05-07: Allow OP_MSG for all handshakes. +- 2026-05-08: Allow OP_MSG for all handshakes. - 2024-04-30: Convert from RestructuredText to Markdown. - 2022-10-05: Remove spec front matter. - 2022-01-13: Clarify that `OP_MSG` must be used when using stable API diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index ee8d34d61f..808ee33e48 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -101,7 +101,7 @@ reply = conn.send_command("admin", cmd) if reply["maxWireVersion"] < 6: # Server is reporting that it doesn't support OpMSG - raise Error() + raise Error("wire version check failed") # Store the negotiated compressor, see OP_COMPRESSED spec. if reply.get("compression"): @@ -564,7 +564,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog -- 2026-05-07: Allow OP_MSG for all handshakes. +- 2026-05-08: Allow OP_MSG for all handshakes. - 2025-09-04: Clarify that drivers do not append the same metadata multiple times. - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization. - 2024-11-05: Move handshake prose tests from spec file to prose test file. From 0ad2e4d747bc45919725f055f7e6d1333966b6f9 Mon Sep 17 00:00:00 2001 From: Iris Ho Date: Fri, 8 May 2026 11:17:36 -0700 Subject: [PATCH 05/14] run pre-commit --- source/mongodb-handshake/handshake.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 808ee33e48..718be5dfba 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -51,10 +51,10 @@ and is maintained for backwards compatibility with servers that do not support t Drivers SHOULD use the `OP_MSG` protocol for all handshakes if their minWireVersion is 6 (MongoDB 3.6) or higher. If a [server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST also use the -`hello` command for the initial handshake. If server API version is not requested and -`loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake, and include -`helloOk:true` in the handshake request. If the server does not understand `OP_MSG`, drivers MUST show the same error -message as when wire version checks fail (e.g. because the server's maxWireVersion is lower than the driver's minWireVersion). +`hello` command for the initial handshake. If server API version is not requested and `loadBalanced: False`, drivers +MUST use legacy hello for the first message of the initial handshake, and include `helloOk:true` in the handshake +request. If the server does not understand `OP_MSG`, drivers MUST show the same error message as when wire version +checks fail (e.g. because the server's maxWireVersion is lower than the driver's minWireVersion). ASIDE: If the legacy handshake response includes `helloOk: true`, then subsequent topology monitoring commands MUST use the `hello` command. If the legacy handshake response does not include `helloOk: true`, then subsequent topology From b1651dfb72d56af35e05790df6e8dbc044d4a2b5 Mon Sep 17 00:00:00 2001 From: Iris Date: Mon, 1 Jun 2026 16:21:47 -0700 Subject: [PATCH 06/14] link to handshake spec --- source/message/OP_MSG.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index 63f62aca35..f93218b458 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -20,9 +20,8 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH `OP_MSG` is only available in MongoDB 3.6 (`maxWireVersion >= 6`) and later. MongoDB drivers MUST perform the MongoDB handshake using `OP_MSG` if an API version was declared on the client. -If no API version was declared, drivers that have historically supported MongoDB 3.4 and earlier MAY perform the -handshake using `OP_QUERY` to determine if the node supports `OP_MSG`. Drivers that have only ever supported MongoDB 3.6 -and newer MAY default to using `OP_MSG`. +Refer to the [handshake specification](https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.md) +for the appropriate use of `OP_MSG` and `OP_QUERY`. If the node supports `OP_MSG`, any and all messages MUST use `OP_MSG`, optionally compressed with `OP_COMPRESSED`. Authentication messages MUST also use `OP_MSG` when it is supported, but MUST NOT use `OP_COMPRESSED`. From ea4314329ed2b68d7ec4c9f2e901036bbdc2ecff Mon Sep 17 00:00:00 2001 From: Iris Date: Mon, 1 Jun 2026 16:22:49 -0700 Subject: [PATCH 07/14] address JY review comments --- source/mongodb-handshake/handshake.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 718be5dfba..608fb4b14d 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -49,12 +49,12 @@ MongoDB uses the `hello` or `isMaster` commands for handshakes and topology moni preferred command. `hello` must always be sent using the `OP_MSG` protocol. `isMaster` is referred to as "legacy hello" and is maintained for backwards compatibility with servers that do not support the `hello` command. -Drivers SHOULD use the `OP_MSG` protocol for all handshakes if their minWireVersion is 6 (MongoDB 3.6) or higher. If a +Drivers MUST use the `OP_MSG` protocol for all handshakes if their minWireVersion is 6 (MongoDB 3.6) or higher. If a [server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST also use the `hello` command for the initial handshake. If server API version is not requested and `loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake, and include `helloOk:true` in the handshake -request. If the server does not understand `OP_MSG`, drivers MUST show the same error message as when wire version -checks fail (e.g. because the server's maxWireVersion is lower than the driver's minWireVersion). +request. If the server does not understand `OP_MSG`, the socket MAY be closed by the server and drivers MUST include the +original error and indicate that incompatible server is likely the cause. ASIDE: If the legacy handshake response includes `helloOk: true`, then subsequent topology monitoring commands MUST use the `hello` command. If the legacy handshake response does not include `helloOk: true`, then subsequent topology @@ -97,11 +97,11 @@ if creds: cmd["saslSupportedMechs"] = ... cmd["speculativeAuthenticate"] = ... -reply = conn.send_command("admin", cmd) - -if reply["maxWireVersion"] < 6: - # Server is reporting that it doesn't support OpMSG - raise Error("wire version check failed") +try: + reply = conn.send_command("admin", cmd) +except AutoReconnect as exc: + # Socket was closed, OpMSG might not be supported + raise AutoReconnect("wire version might not be supported") from exc # Store the negotiated compressor, see OP_COMPRESSED spec. if reply.get("compression"): From a99900a89dd9dcb82da9f68464755abfb65e190f Mon Sep 17 00:00:00 2001 From: Iris Date: Mon, 1 Jun 2026 16:28:07 -0700 Subject: [PATCH 08/14] tweak error type in pseudocode --- source/mongodb-handshake/handshake.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 608fb4b14d..eb330a7c57 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -101,7 +101,7 @@ try: reply = conn.send_command("admin", cmd) except AutoReconnect as exc: # Socket was closed, OpMSG might not be supported - raise AutoReconnect("wire version might not be supported") from exc + raise Error("wire version might not be supported") from exc # Store the negotiated compressor, see OP_COMPRESSED spec. if reply.get("compression"): From 5e3069d82cbb32b7413595e4d8b2e9d849eacc77 Mon Sep 17 00:00:00 2001 From: Iris Date: Mon, 1 Jun 2026 16:49:01 -0700 Subject: [PATCH 09/14] run pre-commit --- source/message/OP_MSG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index f93218b458..d06bccfd06 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -20,7 +20,8 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH `OP_MSG` is only available in MongoDB 3.6 (`maxWireVersion >= 6`) and later. MongoDB drivers MUST perform the MongoDB handshake using `OP_MSG` if an API version was declared on the client. -Refer to the [handshake specification](https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.md) +Refer to the +[handshake specification](https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.md) for the appropriate use of `OP_MSG` and `OP_QUERY`. If the node supports `OP_MSG`, any and all messages MUST use `OP_MSG`, optionally compressed with `OP_COMPRESSED`. From 6dc420e99701652fd94c6b4e0bfcb7b336941d85 Mon Sep 17 00:00:00 2001 From: Iris Date: Wed, 3 Jun 2026 10:29:06 -0700 Subject: [PATCH 10/14] let original error propigate through --- source/mongodb-handshake/handshake.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index eb330a7c57..b3b14b3d1e 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -53,8 +53,8 @@ Drivers MUST use the `OP_MSG` protocol for all handshakes if their minWireVersio [server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST also use the `hello` command for the initial handshake. If server API version is not requested and `loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake, and include `helloOk:true` in the handshake -request. If the server does not understand `OP_MSG`, the socket MAY be closed by the server and drivers MUST include the -original error and indicate that incompatible server is likely the cause. +request. If the server does not understand `OP_MSG`, the server will close the socket and drivers MUST include the +original error. ASIDE: If the legacy handshake response includes `helloOk: true`, then subsequent topology monitoring commands MUST use the `hello` command. If the legacy handshake response does not include `helloOk: true`, then subsequent topology @@ -97,11 +97,7 @@ if creds: cmd["saslSupportedMechs"] = ... cmd["speculativeAuthenticate"] = ... -try: - reply = conn.send_command("admin", cmd) -except AutoReconnect as exc: - # Socket was closed, OpMSG might not be supported - raise Error("wire version might not be supported") from exc +reply = conn.send_command("admin", cmd) # Store the negotiated compressor, see OP_COMPRESSED spec. if reply.get("compression"): @@ -564,7 +560,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog -- 2026-05-08: Allow OP_MSG for all handshakes. +- 2026-06-03: Allow OP_MSG for all handshakes. - 2025-09-04: Clarify that drivers do not append the same metadata multiple times. - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization. - 2024-11-05: Move handshake prose tests from spec file to prose test file. From feff6a83784e5885da6df2d5e7a6c8766bdaf284 Mon Sep 17 00:00:00 2001 From: Iris Date: Wed, 3 Jun 2026 17:24:59 -0700 Subject: [PATCH 11/14] add unified test --- .../tests/unified/opmsg-not-supported.json | 74 +++++++++++++++++++ .../tests/unified/opmsg-not-supported.yml | 45 +++++++++++ 2 files changed, 119 insertions(+) create mode 100644 source/mongodb-handshake/tests/unified/opmsg-not-supported.json create mode 100644 source/mongodb-handshake/tests/unified/opmsg-not-supported.yml diff --git a/source/mongodb-handshake/tests/unified/opmsg-not-supported.json b/source/mongodb-handshake/tests/unified/opmsg-not-supported.json new file mode 100644 index 0000000000..b0fb30f245 --- /dev/null +++ b/source/mongodb-handshake/tests/unified/opmsg-not-supported.json @@ -0,0 +1,74 @@ +{ + "description": "op_msg not supported", + "schemaVersion": "1.3", + "runOnRequirements": [ + { + "minServerVersion": "4.4" + } + ], + "createEntities": [ + { + "client": { + "id": "setupClient", + "useMultipleMongoses": false + } + }, + { + "client": { + "id": "client", + "useMultipleMongoses": false, + "uriOptions": { + "appName": "op-msg-handshake-test", + "serverSelectionTimeoutMS": 500 + } + } + }, + { + "database": { + "id": "database", + "client": "client", + "databaseName": "test" + } + } + ], + "tests": [ + { + "description": "server closing connection during initial hello produces an error", + "operations": [ + { + "name": "failPoint", + "object": "testRunner", + "arguments": { + "client": "setupClient", + "failPoint": { + "configureFailPoint": "failCommand", + "mode": "alwaysOn", + "data": { + "failCommands": [ + "hello", + "isMaster" + ], + "appName": "op-msg-handshake-test", + "closeConnection": true + } + } + } + }, + { + "name": "runCommand", + "object": "database", + "arguments": { + "commandName": "ping", + "command": { + "ping": 1 + } + }, + "expectError": { + "errorContains": "connection closed", + "isClientError": false + } + } + ] + } + ] +} diff --git a/source/mongodb-handshake/tests/unified/opmsg-not-supported.yml b/source/mongodb-handshake/tests/unified/opmsg-not-supported.yml new file mode 100644 index 0000000000..eebbddc28d --- /dev/null +++ b/source/mongodb-handshake/tests/unified/opmsg-not-supported.yml @@ -0,0 +1,45 @@ +description: "op_msg not supported" +schemaVersion: "1.3" +runOnRequirements: + - minServerVersion: "4.4" +createEntities: + - client: + id: "setupClient" + useMultipleMongoses: false + - client: + id: "client" + useMultipleMongoses: false + uriOptions: + appName: "op-msg-handshake-test" + serverSelectionTimeoutMS: 500 + - database: + id: "database" + client: "client" + databaseName: "test" +tests: + # If a server doesn't understand OP_MSG, it will just close the socket. + # This test ensures that the existing socket error is still propagated to the user. + - description: "server closing connection during initial hello produces an error" + operations: + - name: "failPoint" + object: "testRunner" + arguments: + client: "setupClient" + failPoint: + configureFailPoint: "failCommand" + mode: "alwaysOn" + data: + failCommands: + - "hello" + - "isMaster" + appName: "op-msg-handshake-test" + closeConnection: true + - name: "runCommand" + object: "database" + arguments: + commandName: "ping" + command: + ping: 1 + expectError: + errorContains: "connection closed" + isClientError: false From 45c7fa54a46c5e787b5c96045f8f36e9feff8ebe Mon Sep 17 00:00:00 2001 From: Iris Date: Wed, 3 Jun 2026 17:28:24 -0700 Subject: [PATCH 12/14] update changelog date --- source/message/OP_MSG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index d06bccfd06..51c86b7738 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -409,7 +409,7 @@ In the near future, this opcode is expected to be extended and include support f ### Changelog -- 2026-05-08: Allow OP_MSG for all handshakes. +- 2026-06-03: Allow OP_MSG for all handshakes. - 2024-04-30: Convert from RestructuredText to Markdown. - 2022-10-05: Remove spec front matter. - 2022-01-13: Clarify that `OP_MSG` must be used when using stable API From 75f06ac77efefa3ac6494b3114b9ee28897a960f Mon Sep 17 00:00:00 2001 From: Iris <58442094+sleepyStick@users.noreply.github.com> Date: Fri, 5 Jun 2026 12:28:07 -0700 Subject: [PATCH 13/14] Update source/message/OP_MSG.md Co-authored-by: Jeff Yemin --- source/message/OP_MSG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index 51c86b7738..4224dabda9 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -22,7 +22,7 @@ handshake using `OP_MSG` if an API version was declared on the client. Refer to the [handshake specification](https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.md) -for the appropriate use of `OP_MSG` and `OP_QUERY`. +for the appropriate use of `OP_MSG`. If the node supports `OP_MSG`, any and all messages MUST use `OP_MSG`, optionally compressed with `OP_COMPRESSED`. Authentication messages MUST also use `OP_MSG` when it is supported, but MUST NOT use `OP_COMPRESSED`. From 814437a388c2be7185b4bc5b323d7526a7f8b03d Mon Sep 17 00:00:00 2001 From: Iris Date: Fri, 5 Jun 2026 12:58:04 -0700 Subject: [PATCH 14/14] JY review --- source/message/OP_MSG.md | 14 +++++--------- source/mongodb-handshake/handshake.md | 9 ++++----- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index 4224dabda9..9238b469ac 100644 --- a/source/message/OP_MSG.md +++ b/source/message/OP_MSG.md @@ -17,15 +17,11 @@ The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SH #### Usage -`OP_MSG` is only available in MongoDB 3.6 (`maxWireVersion >= 6`) and later. MongoDB drivers MUST perform the MongoDB -handshake using `OP_MSG` if an API version was declared on the client. - -Refer to the +All messages, including authentication messages, MUST use `OP_MSG`. Refer to the [handshake specification](https://github.com/mongodb/specifications/blob/master/source/mongodb-handshake/handshake.md) -for the appropriate use of `OP_MSG`. - -If the node supports `OP_MSG`, any and all messages MUST use `OP_MSG`, optionally compressed with `OP_COMPRESSED`. -Authentication messages MUST also use `OP_MSG` when it is supported, but MUST NOT use `OP_COMPRESSED`. +for the appropriate use of `OP_MSG`. See also +[OP_COMPRESSED specification](https://github.com/mongodb/specifications/blob/master/source/compression/OP_COMPRESSED.md) +for more details. #### OP_MSG @@ -409,7 +405,7 @@ In the near future, this opcode is expected to be extended and include support f ### Changelog -- 2026-06-03: Allow OP_MSG for all handshakes. +- 2026-06-05: Use OP_MSG for all messages. - 2024-04-30: Convert from RestructuredText to Markdown. - 2022-10-05: Remove spec front matter. - 2022-01-13: Clarify that `OP_MSG` must be used when using stable API diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index b3b14b3d1e..777bb60a30 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -53,14 +53,14 @@ Drivers MUST use the `OP_MSG` protocol for all handshakes if their minWireVersio [server API version](../versioned-api/versioned-api.md) is requested or `loadBalanced: True`, drivers MUST also use the `hello` command for the initial handshake. If server API version is not requested and `loadBalanced: False`, drivers MUST use legacy hello for the first message of the initial handshake, and include `helloOk:true` in the handshake -request. If the server does not understand `OP_MSG`, the server will close the socket and drivers MUST include the -original error. +request. ASIDE: If the legacy handshake response includes `helloOk: true`, then subsequent topology monitoring commands MUST use the `hello` command. If the legacy handshake response does not include `helloOk: true`, then subsequent topology monitoring commands MUST use the legacy hello command. See the [Server Discovery and Monitoring spec](../server-discovery-and-monitoring/server-discovery-and-monitoring-summary.md) -for further information. +for further information. Additionally, note that if the server does not understand `OP_MSG`, the server will close the +socket. The initial handshake MUST be performed on every socket to any and all servers upon establishing the connection to MongoDB, including reconnects of dropped connections and newly discovered members of a cluster. It MUST be the first @@ -79,7 +79,6 @@ Consider the following pseudo-code for establishing a new connection: ```python conn = Connection() conn.connect() # Connect via TCP / TLS -conn.supports_op_msg = True # Always send the initial command via OP_MSG. if stable_api_configured or client_options.load_balanced: cmd = {"hello": 1} else: @@ -560,7 +559,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog -- 2026-06-03: Allow OP_MSG for all handshakes. +- 2026-06-05: Use OP_MSG for all handshakes. - 2025-09-04: Clarify that drivers do not append the same metadata multiple times. - 2025-06-09: Add requirement to allow appending to client metadata after `MongoClient` initialization. - 2024-11-05: Move handshake prose tests from spec file to prose test file.