GODRIVER-3616 Apply client-level timeout to tailable cursors

[prestonvasquez]

GODRIVER-3616

Summary

Apply client-level timeouts for default ITERATION_MODE for tailable/awaitData cursors.

Background & Motivation

Detailed steps to reproduce the problem?
According to the CSOT specifications, the timeoutMS value must apply to cursor iteration methods such as cursor.Next():

When applying the timeoutMS option to next calls on cursor, drivers MUST ensure it applies to the entire call, not individual commands.

[Copilot]

Pull Request Overview

This PR adds support for client-level timeouts with Tailable Await Data (TAD) cursors by implementing a mechanism to apply client-level timeout when no context deadline is set.

• Adds client timeout handling to cursor operations for better timeout management
• Implements a functional options pattern for cursor configuration
• Integrates client timeout from collection to cursor initialization

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
mongo/cursor.go	Adds client timeout field and options pattern, implements timeout logic in cursor.next()
mongo/collection.go	Passes client timeout to cursor creation
internal/integration/cursor_test.go	Adds integration test for client-level timeout behavior with TAD cursors

---

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

[mongodb-drivers-pr-bot]

API Change Report

No changes found!

[mongodb-drivers-pr-bot]

🧪 Performance Results

Commit SHA: 5c404fb

There were no significant changes to the performance to report for version 68b86cfcfc0e9b0007f95beb.

Benchmark	Measurement	% Change	Patch Value	Stable Region	H-Score	Z-Score

For a comprehensive view of all microbenchmark results for this PR's commit, please check out the Evergreen perf task for this patch.

[matthewdale]

Is there a reason to use a value+bool pair here rather than a pointer like in other options APIs in the Go Driver? Also, is there a generic "optional value" type that we can try using here since it's an unexported API?

[prestonvasquez]

I prefer this solution to avoid referencing the value passed to withCursorOptionClientTimeout:

func withCursorOptionClientTimeout(dur *time.Duration) cursorOption {
	return func(opts *cursorOptions) {
		opts.clientTimeout = dur // Changes to clientTimeout changes dur
	}
}

Taking copy feels kind of awkward:

func withCursorOptionClientTimeout(dur *time.Duration) cursorOption {
	return func(opts *cursorOptions) {
		if dur != nil {
			durCopy := *dur
			opts.clientTimeout = &durCopy
		}
	}
}

Not passing the pointer requires extra setup in the collection methods.

IIRC you have a global solution, if you open a GODRIVER ticket I will add it as a TODO here.

[matthewdale]

Created GODRIVER-3650 to track that suggestion.

[matthewdale]

Looks good! 👍