GODRIVER-3659 Filter CMAP/SDAM events for awaitMinPoolSizeMS

[prestonvasquez]

GODRIVER-3659

Summary

This PR implements event filtering for awaitMinPoolSizeMS in the unified test runner, as specified in the unified test format specification.

A naive implementation would clear specific event arrays after initialization:

client.pooled = nil
client.serverDescriptionChanged = nil
client.serverHeartbeatStartedEvent = nil
// ... clear each SDAM event type

However, if we add a new CMAP or SDAM event type in the future, we must remember to update this clearing block. Forgetting to do so means initialization events leak into test assertions, causing false failures.

The eventSequencer assigns a monotonically increasing sequence number to each CMAP and SDAM event as it's recorded. After pool initialization completes, we capture the current sequence as a cutoff. When verifying test expectations, we filter out any events with sequence numbers at or below the cutoff. This approach is future-proof because new event types automatically participate in filtering as long as they call the appropriate recording method in their event processor.

Background & Motivation

PR #2196 added support for awaitMinPoolSizeMS to the unified test runner, but was merged before the specification PR mongodb/specifications#1834 was finalized. As a result, the initial implementation used a simplified approach that doesn't match the final specification requirements.

Per the spec, when awaitMinPoolSizeMS is specified:

Any CMAP and SDAM event/log listeners configured on the client should ignore any events that occur before the pool is being populated.

[Copilot]

Pull Request Overview

This PR implements event filtering for awaitMinPoolSizeMS in the unified test runner to comply with the specification requirement that CMAP and SDAM events occurring during connection pool initialization should be ignored. The implementation uses a sequence-based filtering approach where events are assigned monotonically increasing sequence numbers, and a cutoff is set after pool initialization completes.

Key Changes:

• Replaced boolean awaitMinPoolSize field with awaitMinPoolSizeMS integer field to specify timeout duration
• Introduced eventSequencer to track event ordering via sequence numbers and filter events below a cutoff threshold
• Modified event processing functions to record sequence numbers for all CMAP and SDAM events

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
internal/integration/unified/entity.go	Updated entityOptions to use awaitMinPoolSizeMS with timeout duration instead of boolean flag
internal/integration/unified/client_entity.go	Added eventSequencer type and filtering logic; updated awaitMinimumPoolSize to accept timeout parameter and set cutoff after pool initialization
internal/integration/unified/event_verification.go	Modified event verification functions to use filterEventsBySeq for filtering CMAP and SDAM events
internal/integration/unified/client_entity_test.go	Added comprehensive unit tests for eventSequencer functionality

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mongodb-drivers-pr-bot]

🧪 Performance Results

Commit SHA: 8c9477a

The following benchmark tests for version 691e1e2fac48dc00079ebe4f had statistically significant changes (i.e., |z-score| > 1.96):

Benchmark	Measurement	% Change	Patch Value	Stable Region	H-Score	Z-Score
BenchmarkBSONDeepDocumentEncoding	ops_per_second_med	7.3348	77881.6199	Avg: 72559.4998 Med: 71844.2417 Stdev: 2655.7612	0.7290	2.0040
BenchmarkBSONDeepDocumentEncoding	ops_per_second_max	6.7826	81287.5955	Avg: 76124.4029 Med: 75443.2290 Stdev: 2470.0234	0.7413	2.0903
BenchmarkMultiInsertLargeDocument	allocated_bytes_per_op	5.4527	28562638.0000	Avg: 27085745.6667 Med: 27345034.0000 Stdev: 531834.3823	0.8321	2.7770
BenchmarkBSONFullDocumentEncoding	allocated_bytes_per_op	0.1287	5204.0000	Avg: 5197.3125 Med: 5197.0000 Stdev: 1.3525	0.8908	4.9447

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

[mongodb-drivers-pr-bot]

API Change Report

No changes found!

[prestonvasquez]

An alternative to this is to re-initialize the event containers here. While this is a much simpler solution, it could be buggy depending if we need to re-initialize event logic for some other reason somewhere else. The eventSequencer future-proofs this issue.

[prestonvasquez]

Closing to focus on a simpler solution for now.