Don't retry on certificate verification error

[ccbest]

Right now the retries= behavior will retry a connection in the event of a TLS certificate verification error. Allowing certain transient errors such as SSLEOFError (peer closing mid-handshake) and TLSV1_ALERT_INTERNAL_ERROR (overloaded server) is appropriate, but a failed certificate verification won't change upon retrying.

PR #1156 introduces an SSLError exception that could be further subclassed as CertificateError(SSLError) (mapped to ssl.SSLCertVerificationError), which could then be excluded from retries.

To avoid over-representing the impact, only users that opted in to retries= are affected since it defaults to 0. It's also worth noting that urllib3 has this same behavior so there's probably a discussion about consistency that should be considered, but it seems more accurate to me that retrying the connection should get shortcut to prevent excess connections+handshakes.

Happy to take this on if it sounds like something you'd want to implement.

[0xshubhs]

Your premise checks out, and the chain is exactly three hops. Worth writing out, because it tells you where the fix has to go and it isn't httpx2.

ssl.SSLCertVerificationError subclasses ssl.SSLError, and the anyio backend maps that straight onto ConnectError (src/httpcore2/httpcore2/_backends/anyio.py:67):

exc_map: ExceptionMapping = {
    ...
    ssl.SSLError: ConnectError,
}
with map_exceptions(exc_map):
    ...
    ssl_stream = await anyio.streams.tls.TLSStream.wrap(...)

Then the retry loop catches it (src/httpcore2/httpcore2/_async/connection.py:143):

except (ConnectError, ConnectTimeout):
    if retries_left <= 0:
        raise
    retries_left -= 1

The try spans both connect_tcp and start_tls (:107 through :141), so a handshake failure sits inside the retried region rather than just the TCP connect.

The part that matters for your PR is that httpx2 has no retry loop at all. It forwards the parameter and nothing else (src/httpx2/httpx2/_transports/default.py:161 and :304):

retries=retries,

and its own exception mapping at default.py:81 only runs after httpcore2 has already exhausted the retries. So adding CertificateError(SSLError) in httpx2's _exceptions.py gets you a better public exception type, which is worth having on its own, but it won't change retry behaviour by a single handshake.

The good news is that httpcore2 lives in this same repo under src/httpcore2/, so it's one PR rather than a cross-repo dance.

A narrow fix works here because map_exceptions takes the first isinstance hit in insertion order (_exceptions.py:15):

for from_exc, to_exc in map.items():
    if isinstance(exc, from_exc):
        raise to_exc(exc) from exc

So putting ssl.SSLCertVerificationError above ssl.SSLError in that dict is enough to route it to something non-retryable, with no change to the loop itself.

One practical note, _sync is generated from _async by scripts/unasync.py:85, so edit the async side and regenerate rather than patching both by hand.

On the urllib3 consistency question, I'd say the shared behaviour comes from the same structural cause in both libraries, SSLError being a single bucket that covers both "the peer flaked" and "this certificate does not validate". That's a reason to expect urllib3 has the same bug, not much of a reason to keep it.