DRIVERS-2884 Avoid connection churn when operations timeout

[prestonvasquez]

This PR implements the design for connection pooling improvements described in DRIVERS-2884, based on the CSOT (Client-Side Operation Timeout) spec. It addresses connection churn caused by network timeouts during operations, especially in environments with low client-side timeouts and high latency.

When a connection is checked out after a network timeout, the driver now attempts to resume and complete reading any pending server response (instead of closing and discarding the connection). This may require multiple checkouts.
Each pending response read is subject to a cumulative 3-second static timeout. The timeout is refreshed after each successful read, acknowledging that progress is being made. If no data is read and the timeout is exceeded, the connection is closed.

To reduce unnecessary latency, if the timeout has expired while the connection was idle in the pool, a non-blocking single-byte read is performed; if no data is available, the connection is closed immediately.
This update introduces new CMAP events and logging messages (PendingResponseStarted, PendingResponseSucceeded, PendingResponseFailed) to improve observability of this path.

Please complete the following before merging:

• Update changelog.
• Make sure there are generated JSON files from the YAML test files.
• Test changes in at least one language driver. Go: GODRIVER-3173 Complete pending reads on conn checkout mongo-go-driver#1977
• Test these changes against all server versions and topologies (including standalone, replica set, sharded
  clusters, and serverless).

[baileympearson]

Agreed. Can we clarify that in the description of duration? We can take inspiration from the definitions of duration for checkout failed and checkout succeeded events. Ex:

  /**
   * The time it took to establish the connection.
   * In accordance with the definition of establishment of a connection
   * specified by `ConnectionPoolOptions.maxConnecting`,
   * it is the time elapsed between emitting a `ConnectionCreatedEvent`
   * and emitting this event as part of the same checking out.
   *
   * Naturally, when establishing a connection is part of checking out,
   * this duration is not greater than
   * `ConnectionCheckedOutEvent`/`ConnectionCheckOutFailedEvent.duration`.
   *
   * A driver MAY choose the type idiomatic to the driver.
   * If the type chosen does not convey units, e.g., `int64`,
   * then the driver MAY include units in the name, e.g., `durationMS`.
   */
  duration: Duration;

So, maybe something like:

  /**
   * The time it took to complete the pending read.
   * This duration is defined as the time elapsed between emitting a `PendingResponseStarted` event
   * and emitting this event as part of the same checking out.
   *
   * A driver MAY choose the type idiomatic to the driver.
   * If the type chosen does not convey units, e.g., `int64`,
   * then the driver MAY include units in the name, e.g., `durationMS`.
   */
  duration: Duration;

[baileympearson]

(same comment for other definitions of duration in this PR).

[prestonvasquez]

This seems to be a sufficient check that if the awaitPendingResponse function fails with a non-timeout error the connection should be closed.

[ShaneHarvey]

a network error encountered when checking out a connection that must attempt to discard a pending response

Is this sentence correct? I'm getting tripped up by the "that must attempt". Should it be

a network error encountered when reading a pending response during connection checkout.

[baileympearson]

Could we add server selection events to this list (maybe we could use logging tests for this, even though not all drivers have implemented the CLAM spec?)? It would be nice to clarify that the retry happens because the error returned is retryable and we use the existing retry mechanism, not that we retry checkout directly. Basically:

- connectionPendingResponseStarted: {} # Pending read fails on first find
          - connectionPendingResponseFailed:
              reason: error
          - connectionClosedEvent:
              reason: error
          - serverSelectionStarted
          - serverSelectionFinished
          - connectionCheckedOutEvent: {}
          - connectionCheckedInEvent: {} # Find finishes.

[baileympearson]

This test fails in Node because isTimeoutError only applies when timeoutMS is configured:

isTimeoutError: Optional boolean. If true, the test runner MUST assert that the error represents a timeout due to use of the timeoutMS option. If false, the test runner MUST assert that the error does not represent a timeout.

Maybe splitting hairs here but in Node, we only throw a CSOT timeout error when timeoutMS is enabled for the operation. Because the findOne doesn't have timeoutMS configured, even though the timeout is caused by a CSOT-enabled command, the findOne itself doesn't throw a CSOT timeout error.

Zooming out further from just the test runner - what do you think the best solution would be for this situation? Should Node just throw a CSOT timeout error in this circumstance?