Skip to content

Commit 6db8e7d

Browse files
committed
Sweep flip-flopped guidance in AGENTS.md to best-supported wording
Two substantive edits, plus guard rails to keep future review passes from flipping these claims again. src/MongoDB.Driver/Core/AGENTS.md - IDnsResolver substitutability (line 296): Tightened the verbose three-clause sentence that was hedging across all three prior positions. Now states internal clearly, explains the interface is for in-assembly tests via InternalsVisibleTo, and adds an explicit guard line ("Past versions of this file claimed users could substitute a custom IDnsResolver; do not re-introduce that claim"). Verified against source: both IDnsResolver and DnsClientWrapper are internal. - helloOk version (line 116): Current wording correctly omits a version number. Added a guard line citing ServerMonitor.cs / HelloResult.HelloOk as the runtime gate, and explicitly flagging both prior wrong values ("5.0+" and "4.4.2+") as not-to-be-reintroduced. Verified against source: ServerMonitor.cs uses previousDescription?.HelloOk ?? false as the runtime flag. Left as-is (best state already) - $polygon recommendation in GeoJsonObjectModel/AGENTS.md: Currently silent. Silence is correct — the audience for this object model targets 2dsphere, not legacy 2d, so there's no useful guidance to give. No edit. - GuidRepresentationMode.V2/V3 token in Bson/AGENTS.md: Token is mentioned twice, both times with the consistent claim that the mode was removed. This was the "token-level wobble" — the claim never actually flipped, only its surface mention came back. Keeping the token aids searchers who arrive looking for the old API; no edit. Why not more edits The other near-misses from the audit were monotone refinements rather than flip-flops, so they didn't need a "pick the best" decision — the current wording is already the most refined version (MinPoolSize -> MinConnections, AggregateToCollectionOperation retryability, DownloadStreamForwardOnly -> Seekable, "internal sealed" sweeping claim, pool warm-up).
1 parent b58abac commit 6db8e7d

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

src/MongoDB.Driver/Core/AGENTS.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -113,7 +113,7 @@ This file covers the **Server Discovery And Monitoring (SDAM)** topology layer,
113113

114114
- **`HelloResult`** wraps the `hello` (or legacy `isMaster`) command response.
115115
- Contains: topology version, server type, replica set info, compressor list, max BSON size, max wire version, etc.
116-
- **Hello vs isMaster selection:** Drivers send `hello` against servers that advertise `helloOk` in their initial reply and fall back to `isMaster` for older servers. The two responses are payload-compatible; only the command name differs.
116+
- **Hello vs isMaster selection:** Drivers send `hello` against servers that advertise `helloOk` in their initial reply and fall back to `isMaster` for older servers. The two responses are payload-compatible; only the command name differs. The gate is the runtime `HelloOk` flag (see `ServerMonitor.cs` and `HelloResult.HelloOk`), **not** a hardcoded server-version floor — past versions of this file cited "5.0+" and then "4.4.2+"; both are misleading and should not be re-introduced.
117117
- **Speculative authentication:** The hello may carry an embedded `"speculativeAuthenticate"` payload, allowing the first SASL step to ride on the handshake — see the auth-area `AGENTS.md` for which mechanisms speculate.
118118

119119
### Compression negotiation
@@ -293,7 +293,7 @@ This file covers the **Server Discovery And Monitoring (SDAM)** topology layer,
293293
**Files:** `Ensure.cs`, `EndPointHelper.cs`, `DnsClientWrapper.cs`, `Feature.cs`, `ExceptionMapper.cs`, `EnvironmentVariableProvider.cs`, and more.
294294

295295
- **`Ensure`** — precondition checks (NotNull, IsGreaterThanZero, etc.).
296-
- **`DnsClientWrapper`** — async DNS resolver. The implementation uses the `DnsClient` NuGet package (not `System.Net.Dns`) so SRV/TXT queries work consistently across platforms. `IDnsResolver` and `DnsClientWrapper` are both `internal`there is no public seam for substituting a custom resolver. `IDnsResolver` is the production abstraction consumed by `DnsMonitor` (production code goes through it), and it doubles as a test seam.
296+
- **`DnsClientWrapper`** — async DNS resolver. The implementation uses the `DnsClient` NuGet package (not `System.Net.Dns`) so SRV/TXT queries work consistently across platforms. Both `IDnsResolver` and `DnsClientWrapper` are `internal`; there is no public seam for plugging in a custom resolver. The interface exists so in-assembly tests (via `InternalsVisibleTo`) can substitute a fake — production code always goes through `DnsClientWrapper` from `DnsMonitor`. Past versions of this file claimed users could substitute a custom `IDnsResolver`; do not re-introduce that claim.
297297
- **`ExceptionMapper`** — classifies wire exceptions (network error, timeout, server error) into semantic types.
298298
- **`Feature`** — checks server version for feature availability (e.g., "does this server support transactions?").
299299
- **`EnvironmentVariableProvider`** — abstraction over `Environment.GetEnvironmentVariable` for testing.

0 commit comments

Comments
 (0)