Skip to content
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

Jump to bottom

DRIVERS-2798 Drivers do not gossip $clusterTime on SDAM commands #1735

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+30 −4
Open

DRIVERS-2798 Drivers do not gossip $clusterTime on SDAM commands #1735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
20 changes: 16 additions & 4 deletions source/sessions/driver-sessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -710,7 +710,8 @@ expiration.

## Gossipping the cluster time

Drivers MUST gossip the cluster time when connected to a deployment that uses cluster times.
Drivers MUST gossip the cluster time when connected to a deployment that uses cluster times. However, drivers MUST NOT
gossip cluster time on SDAM commands.

Gossipping the cluster time is a process in which the driver participates in distributing the logical cluster time in a
deployment. Drivers learn the current cluster time (from a particular server's perspective) in responses they receive
Expand All @@ -722,7 +723,7 @@ received from a server.

### Receiving the current cluster time

Drivers MUST examine all responses from the server commands to see if they contain a top level field named
Drivers MUST examine all non-SDAM responses from the server commands to see if they contain a top level field named
`$clusterTime` formatted as follows:

```typescript
Expand All @@ -748,8 +749,9 @@ not participate in the comparison.

### Sending the highest seen cluster time

Whenever a driver sends a command to a server it MUST include the highest seen cluster time in a top level field called
`$clusterTime`, in the same format as it was received in (but see Gossipping with mixed server versions below).
Whenever a driver sends a non-SDAM command to a server it MUST include the highest seen cluster time in a top level
field called `$clusterTime`, in the same format as it was received in (but see Gossipping with mixed server versions
below).

### How to compute the `$clusterTime` to send to a server

Expand Down Expand Up @@ -791,6 +793,15 @@ the command. A server supports `$clusterTime` when the `maxWireVersion` >= 6.

This supports the (presumably short lived) scenario where not all servers have been upgraded to 3.6.

### Do not gossip on SDAM commands

Drivers MUST NOT gossip cluster time on SDAM commands. In earlier versions of this spec, drivers did gossip cluster time
on SDAM commands, however it was discovered that doing so provides little benefit and can result in a loss of
availability. For example, if the driver attempts to connect to a member of a different replica set, the driver can end
up with an invalid cluster time. Worse, this invalid cluster time may remain the highest for an indefinite time since
clocks between different clusters are not synced. This results in all operations failing until the application is
restarted. To fix this issue we decided it was more robust to stop gossiping on SDAM commands altogether.

## Test Plan

See the [README](tests/README.md) for tests.
Expand Down Expand Up @@ -918,6 +929,7 @@ has risks that do not justify the potential guaranteed `ServerSession` allocatio

## Changelog

- 2024-11-21: Drivers MUST NOT gossip $clusterTime on SDAM commands.
- 2024-05-08: Migrated from reStructuredText to Markdown.
- 2017-09-13: If causalConsistency option is omitted assume true
- 2017-09-16: Omit session ID when opening and authenticating a connection
Expand Down
14 changes: 14 additions & 0 deletions source/sessions/tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,20 @@ and configure a `MongoClient` with default options.
- Attempt to send a write command to the server (e.g., `insertOne`) with the explicit session passed in
- Assert that a client-side error is generated indicating that sessions are not supported

### 20. Drivers do not gossip `$clusterTime` on SDAM commands.

- Skip this test when connected to a deployment that does not support cluster times
- Create a client, C1, with a small heartbeatFrequencyMS
- `c1 = MongoClient(heartbeatFrequencyMS=10)`
- Run a ping command using C1 and record the `$clusterTime` in the response, as `clusterTime`.
- `clusterTime = c1.admin.command({"ping": 1})["$clusterTime"]`
- Using a separate client, C2, run an insert to advance the cluster time
- `c2.test.test.insert_one({"advance": "$clusterTime"})`
- Next, wait until the client C1 processes at least 1 SDAM heartbeat
- If possible, assert the SDAM heartbeats do not send `$clusterTime`
- Run a ping command using C1 and assert that `$clusterTime` sent is the same as the `clusterTime` recorded earlier.
This assertion proves that C1's `$clusterTime` was not advanced by gossiping through SDAM.

## Changelog

- 2024-05-08: Migrated from reStructuredText to Markdown.
Expand Down
Loading