Skip to content

DRIVERS-2944 Update handshake spec to allow using OP_MSG exclusively #1933

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sleepyStick wants to merge 5 commits into
base: master
Choose a base branch
from
Open

DRIVERS-2944 Update handshake spec to allow using OP_MSG exclusively #1933

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5f4297a
use op_msg for all handshakes
sleepyStick May 7, 2026
5329062
no longer need to use op_query during handshake
sleepyStick May 7, 2026
cc595db
update changelogs
sleepyStick May 7, 2026
6923bb5
update changelog date and error message when wire check fails
sleepyStick May 8, 2026
0ad2e4d
run pre-commit
sleepyStick May 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion source/message/OP_MSG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

Expand Down Expand Up @@ -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
Expand Down
21 changes: 11 additions & 10 deletions source/mongodb-handshake/handshake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand All @@ -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"):
Expand Down Expand Up @@ -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.
Expand Down
Loading