Use Case

As a... driver user
I want... clear and accurate documentation of the new CSOT behaviour
So that... I don't have to file a ticket/community post to figure out how CSOT should work

User Impact

• All potential users of the new CSOT features in the short term, all driver users in the long term as we will be removing the legacy behaviour in a future major

Dependencies

• upstream and/or downstream requirements and timelines to bear in mind

Unknowns

• Do we want a dedicated CSOT page on the manual, or would we prefer updating existing pages to explain how to use the new options?

Acceptance Criteria

Implementation Requirements

• None

Testing Requirements

• None

Documentation Requirements

• Add API documentation to explain how auto connect is "ignored" by timeoutMS behavior
• Add API documentation for new timeoutMS option
• Add API documentation to cover new cursor behaviour
  • document timeoutMode option
  • document interaction between timeoutMS, maxAwaitTimeMS and timeoutMode
  • document that CURSOR_LIFETIME mode should be used for short-lived cursors due to potential to hang for entirety of timeoutMS
• Add API documentation to cover new change stream behaviour
  • Document that users can call next/tryNext/hasNext again on a change stream that's timed out in iterator mode as it will have already resumed, provided that the timeout wasn't on the resume attempt
  • Document that when a change stream in emitter mode times out on a getMore, it will emit a MongoOperationTimeoutError as an error event, but will not close the change stream, which can be checked using ChangeStream.closed property
  • Suggest closing and recreating a change stream with a higher timeout if the timeout occurs before any events have been received since this is a signal that the server is timing out before it can finish processing the existing oplog (spec required)
  • document that timeout errors will be emitted if a change stream goes timeoutMS without emitting a change event
• Add API documentation for new Sessions behaviour
  • document defaultTimeMS option when constructing sessions
• Add API documentation for new Transaction behaviour
  • document that overriding timeoutMS for operations using an explicit session (withTransaction or client.startSession) will lead to a client-side error
  • document that any operations inside a withTransaction callback that don't use the session will not have the remaining timeout applied to them
• Add API documentation for the new GridFS behaviour
  • Document that the timeout for these methods may be breached if calls to interact with the stream take longer than the remaining timeout (spec required)
• Add API documentation for new runCommand behaviour
  • document that if maxTimeMS is specified in a runCommand alongside timeoutMS, then the maxTimeMS on the runCommand will be overwritten by the computed maxTimeMS as a result of CSOT (for read/write short-circuiting)
• Add manual documentation explaining that timeoutMS deprecates and supercedes the following user-configurable options
  • socketTimeoutMS
  • waitQueueTimeoutMS
  • wTimeoutMS
  • maxTimeMS
  • maxCommitTimeMS
• Add API documentation for CSFLE
  • TBD
• Add API documentation for collection-level bulk write
  • document that timeoutMS applies to entire bulk write, not individual commands
• Add API documentation for client-level bulk write
  • document that timeoutMS applies to entire bulk write, not individual commands
• Add API documentation for explain's interaction with timeoutMS

Follow Up Requirements

• None