• Type: Icon: Task Task
    • Resolution: Unresolved
    • Priority: Icon: Unknown Unknown
    • None
    • Affects Version/s: None
    • Component/s: None
    • 2
    • 2
    • Not Needed
    • Needed
    • Hide

      1. What would you like to communicate to the user about this feature?
      2. Would you like the user to see examples of the syntax and/or executable code and its output?
      3. Which versions of the driver/connector does this apply to?

      Show
      1. What would you like to communicate to the user about this feature? 2. Would you like the user to see examples of the syntax and/or executable code and its output? 3. Which versions of the driver/connector does this apply to?

      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

            Assignee:
            warren.james@mongodb.com Warren James
            Reporter:
            bailey.pearson@mongodb.com Bailey Pearson
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated: