-
Type: Task
-
Resolution: Unresolved
-
Priority: Unknown
-
None
-
Affects Version/s: None
-
Component/s: None
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
- has to be done before
-
NODE-6197 Merge CSOT feature branch
- In Progress
1.
|
Add CSOT documentation for Change Streams | NODE-6457 | Needs Verification | Warren James |