CSOT refactoring

[vbabanin]

Description

Following a CSOT code walkthrough in scope of Client Bulk Write API, we identified several improvements to make the Client-Side Operations Timeout (CSOT) code more predictable, consistent, and maintainable. This PR introduces naming refinements, clearer APIs, and safer handling of TimeoutContext to improve readability and reduce potential misuse.

The main change in this PR is that methods whose execution time can be limited by a timeout, or which are executed on a particular ClientSession or RequestContext, must now accept a separate OperationContext parameter.

The guiding principle is to avoid storing OperationContext in fields whenever possible. Instead, the OperationContext is passed explicitly, making it more predictable where a timeout originates and easier to trace through the call chain. Since OperationContext propagates down the tree of method calls, it can also be overridden at any level.

Some exceptions remain in entities such as Cursor and ClientSession, which must hold a reference to a specific OperationContext for their entire lifecycle. However, when any of their methods is called, a new OperationContext is created from the original to overrode a tImeout and passed down the call chain. This makes it easier to trace overrides and insert debugging hooks in the methods where contexts are instantiated.

To further improve predictability and reasoning about the code, both OperationContext and TimeoutContext are now immutable.

Key changes

• Previously, ClusterBinding, ConnectionSource, and Cursor all shared the same OperationContext (and thus the same TimeoutContext), creating hidden coupling that required ad-hoc workarounds such as overriding the global timeout state and rolling it back to avoid side effects , see TimeoutContext.java#L298-L305. This change decouples OperationContext from ClusterBinding and ConnectionSource, requiring callers to explicitly provide it when invoking APIs such as getConnectionSource(OperationContext) and getConnection(OperationContext). By making the context an explicit parameter rather than relying on scattered internal state, the API becomes more predictable, easier to reason about, less prone to subtle lifecycle bugs and easier to compare with the CSOT spec.
• The core cursor logic has been extracted into CoreCursor, allowing both tailable and non-tailable cursor operations -whether in ITERATION or CURSOR_LIFETIME mode (as implemented by CommandBatchCursor) to wrap a CoreCursor and manage timeouts by passing an OperationContext to next, tryNext, and closemethods. This separation also enablesChangeStreamCursorto wrapCoreCursorand implement its distinct timeout semantics without conflicting withCommandBatchCursor’slogic. Previously,CommandBatchCursorcarried two unrelated concerns, including the resetTimeoutOnClosing flag, which existed solely to letChangeStreamCursor` override timeout behavior. The new approach enforces a more clear separation of concerns, with each cursor type independently managing its timeout policy.
  Diagrams to present the changes made in cursors: CSOT refactoring #1781 (comment)
• SyncOperationHelper and AsyncOperationHelper now propagate OperationContext to callbacks passed into withSourceAndConnection. Callbacks receive both the Connection and the OperationContext. Within withSourceAndConnection, the OperationContext passed to the callback includes minRTT, as the method creates a new context after selecting the ConnectionSource. This allows setting minRtt without mutating the original context from Operation.execute(), so in a callback a caller can chose what OperationContext to use further in the call chain, the original one without minRtt or the one with minRtt set.
• withSourceAndConnection encapsulates the server selection timeout logic, computing the effective timeout (min(serverSelectionTimeout, timeoutMS)) per the specification and applying it to both server selection and connection checkout. This keeps the logic centralized and original context immutable.

JAVA-5640 - CSOT clarity enhancement/refactoring.
JAVA-5644 - this issue is also fixed since TimeoutContext is fully immutable now.

[vbabanin]

Current cursor diagram

Refactored cursor diagram

[Copilot]

Pull Request Overview

This PR refactors the Client Side Operation Timeout (CSOT) implementation by removing the OperationContext from binding classes and instead passing it explicitly to operation execution methods. The changes modernize the API design and improve consistency across sync and async operations.

Key changes:

• Removed getOperationContext() methods from binding interfaces and implementations
• Modified operation execution methods to accept OperationContext as an explicit parameter
• Updated connection source methods to take OperationContext as parameter
• Refactored ClientSessionBinding to create session contexts at execution time rather than during binding creation

Reviewed Changes

Copilot reviewed 149 out of 150 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
driver-sync/src/test/unit/com/mongodb/client/internal/ClientSessionBindingSpecification.groovy	Updated test to verify binding delegates to wrapped binding with explicit OperationContext
driver-sync/src/test/resources/logback-test.xml	Changed log level from INFO to DEBUG for testing
driver-sync/src/test/functional/com/mongodb/client/AbstractClientSideOperationsTimeoutProseTest.java	Added imports and minor test method name changes
driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java	Refactored to create OperationContext with session context at execution time
driver-sync/src/main/com/mongodb/client/internal/MapReduceIterableImpl.java	Updated operation execution methods to accept OperationContext parameter
driver-sync/src/main/com/mongodb/client/internal/CryptConnection.java	Renamed timeout variable for consistency
driver-sync/src/main/com/mongodb/client/internal/CryptBinding.java	Removed getOperationContext() method and updated connection source methods
driver-sync/src/main/com/mongodb/client/internal/Crypt.java	Parameter renaming and method signature updates
driver-sync/src/main/com/mongodb/client/internal/CommandMarker.java	Parameter renaming from operationTimeout to timeout
driver-sync/src/main/com/mongodb/client/internal/CollectionInfoRetriever.java	Parameter renaming for consistency
driver-sync/src/main/com/mongodb/client/internal/ClientSessionBinding.java	Major refactoring to remove OperationContext from binding and create session context at execution time
driver-reactive-streams/src/test/unit/com/mongodb/reactivestreams/client/internal/ClientSessionBindingSpecification.groovy	Similar updates to sync version for async binding tests

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[rozza]

LGTM!

[vbabanin]

Full test build including test fixes from #1817 PR: Evergreen patch

Should_use_connectTimeoutMS_when_establishing_connection_in_background - is flaky on mainline.
AWS tests are the same as on mainline.

[vbabanin]

Moving to draft as merge conflict resolution is required.

[nhachicha]

this could use MongoNamespace.ADMIN_DB_COMMAND_NAMESPACE

[vbabanin]

Agreed - updated to use ADMIN_DB_COMMAND_NAMESPACE.

However, the "admin" constant seems to be currently duplicated in multiple places of the codebase, not just in ClientBulkWriteOperation. i suggest we replace the rest with MongoNamespace.ADMIN_DB_COMMAND_NAMESPACE in a separate cleanup PR.

[rozza]

LGTM - lets merge this.

I don't think the prose tests are critical failures for the alpha release - more a prose test issue. Worst case is merge this into main and add a ticket to review those test cases. #1833 might be the required fix.

Ship it!

[vbabanin]

All of the following tests that also appear as failures on mainline:

Test cause analysis

com.mongodb.reactivestreams.client.ClientSideOperationTimeoutProseTest.Should_use_connectTimeoutMS_when_establishing_connection_in_background
Mainline link

com.mongodb.client.ClientSideOperationTimeoutProseTest.Should_use_connectTimeoutMS_when_establishing_connection_in_background
Mainline link

com.mongodb.internal.connection.AwsAuthenticationSpecification.should_not_authenticate_when_provider_gives_invalid_session_token__async__true___0_
Mainline link

com.mongodb.internal.connection.AwsAuthenticationSpecification.should_not_authenticate_when_provider_gives_invalid_session_token__async__false___1_
Mainline link

com.mongodb.reactivestreams.client.CrudProseTest.6._MongoClient.bulkWrite_handles_individual_WriteErrors_across_batches--ordered_false
Mainline link