diff --git a/source/message/OP_MSG.md b/source/message/OP_MSG.md index a8e8eb2edd..63f62aca35 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`. @@ -409,6 +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. - 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 5a62627326..718be5dfba 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("wire version check failed") # 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-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.