PYTHON-5805 CSFLE/QE Support for HTTP Proxies

[blink1073]

PYTHON-5805

Changes in this PR

Adds kms_connect_callback, which lets the caller open the TCP connection to a KMS host so that CSFLE and Queryable Encryption KMS traffic can be tunneled through an HTTP proxy. Networks that force outbound port 443 through a proxy currently make CSFLE and QE unusable, and no workaround exists.

New public API:

• kms_connect_callback on AutoEncryptionOpts, ClientEncryption, and AsyncClientEncryption. The callback receives the KMS host, port, and remaining timeout, and returns a connected socket. The driver then performs the KMS TLS handshake over that socket, so certificate and hostname verification continue to target the KMS host rather than the proxy. The async API requires a coroutine function; the synchronous API requires a regular function.
• KMSConnectContext, a frozen dataclass carrying the values passed to the callback. Its docstring holds worked HTTP CONNECT examples for a plain proxy and for a TLS proxy, in both synchronous and async form.

Internal changes:

• Split TLS wrapping out of the configured-socket helpers so a caller-supplied socket can be wrapped against the KMS host. Pure code motion; the connection path is otherwise unchanged.
• A callback that returns anything other than a plain connected socket fails immediately instead of being retried. Network errors from the callback remain retryable, so libmongocrypt re-invokes the callback.
• Rejecting an already-TLS-wrapped socket produces an actionable error. Python cannot layer TLS over an ssl.SSLSocket, so a TLS proxy callback must relay through a socket.socketpair and return the plain end. Without the explicit check, the failure surfaces as an opaque handshake error with no indication of the cause.
• Added a guard so the flavor-specific wording in the generated synchronous docstring cannot silently revert.

Implements the six prose tests from section 28 of the client-side-encryption test specification. Case 5 is skipped as a known specification discrepancy: PyMongo does not implement ClientEncryptionOpts.timeoutMS, so explicit encryption operations establish no CSOT deadline and the assertion that case makes cannot fail. Tracked in PYTHON-6037.

Test Plan

Prose tests against real AWS KMS, with the proxies from drivers-evergreen-tools, in both flavors: 10 passed, 2 skipped, 0 failed. Cases 1, 2, 3, 4 and 6 pass; case 5 skips on PYTHON-6037. Both proxies recorded connect_count 1, and the plain proxy logged connect_target kms.us-east-1.amazonaws.com:443, confirming that real KMS traffic went through the tunnel. Case 2 is the meaningful security check, because a real AWS KMS certificate would not validate against the proxy's own CA.

Unit tests covering the callback contract: 12 passed, needing no server or credentials.

Evergreen patch across 7 encryption variants (RHEL8, macOS and Windows, each with and without crypt_shared, plus PyOpenSSL on RHEL8): https://spruce.corp.mongodb.com/version/6a84cd3db6c0e20007477689

just lint, just typing and just docs are all clean. just docs runs sphinx-build -W, so the new docstrings render without warnings.

For the TLS-wrapping refactor, which touches every connection the driver makes, I compared the sets of failing test IDs between the merge base and this branch using an identical test scope. The symmetric difference is exactly the newly added tests, so no pre-existing test changed state.

Checklist

Checklist for Author

• Did you update the changelog (if necessary)?
• Is there test coverage?
• Is any followup work tracked in a JIRA ticket? If so, add link(s).
  • PYTHON-6037 Support timeoutMS on ClientEncryption: https://jira.mongodb.org/browse/PYTHON-6037

Checklist for Reviewer

• Does the title of the PR reference a JIRA Ticket?
• Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
• Is all relevant documentation (README or docstring) updated?

[blink1073]

Superseded: opened while this fork's main was 12 commits stale, so the diff pinned a base of 500e1d0 and showed 23 commits / 76 files. Fork main is now synced; reopening so the diff shows only this branch's 11 commits.