Trio backend does not report TLS errors

[pquentin]

Consider the following script:

import httpx
import trio


async def main():
    async with httpx.AsyncClient() as client:
        await client.get("https://tls-v1-0.badssl.com:1010")


trio.run(main)

Since my Python/OpenSSL distribution rightfully doesn't support TLS 1.0, the connection fails as expected. But I'm only getting a generic ConnectError without a clear reason. When using asyncio, the reason is attached to the ConnectError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] ssl/tls alert handshake failure (_ssl.c:1032).

Traceback with Trio

Traceback (most recent call last):
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 101, in map_httpcore_exceptions
    yield
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 394, in handle_async_request
    resp = await self._pool.handle_async_request(req)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_async/connection_pool.py", line 256, in handle_async_request
    raise exc from None
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_async/connection_pool.py", line 236, in handle_async_request
    response = await connection.handle_async_request(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        pool_request.request
        ^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 101, in handle_async_request
    raise exc
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 78, in handle_async_request
    stream = await self._connect(request)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 156, in _connect
    stream = await stream.start_tls(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_backends/trio.py", line 72, in start_tls
    with map_exceptions(exc_map):
         ~~~~~~~~~~~~~~^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 162, in __exit__
    self.gen.throw(value)
    ~~~~~~~~~~~~~~^^^^^^^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpcore/_exceptions.py", line 14, in map_exceptions
    raise to_exc(exc) from exc
httpcore.ConnectError

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File ".../repro.py", line 10, in <module>
    trio.run(main)
    ~~~~~~~~^^^^^^
  File ".../.venv/lib/python3.13/site-packages/trio/_core/_run.py", line 2547, in run
    raise runner.main_task_outcome.error
  File ".../repro.py", line 7, in main
    await client.get("https://tls-v1-0.badssl.com:1010")
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1768, in get
    return await self.request(
           ^^^^^^^^^^^^^^^^^^^
    ...<9 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1540, in request
    return await self.send(request, auth=auth, follow_redirects=follow_redirects)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1629, in send
    response = await self._send_handling_auth(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
    response = await self._send_handling_redirects(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<3 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
    response = await self._send_single_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1730, in _send_single_request
    response = await transport.handle_async_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 393, in handle_async_request
    with map_httpcore_exceptions():
         ~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 162, in __exit__
    self.gen.throw(value)
    ~~~~~~~~~~~~~~^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 118, in map_httpcore_exceptions
    raise mapped_exc(message) from exc
httpx.ConnectError

Traceback with asyncio

Traceback (most recent call last):
  File ".../.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 101, in map_httpcore_exceptions
    yield
  File ".../.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 394, in handle_async_request
    resp = await self._pool.handle_async_request(req)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpcore/_async/connection_pool.py", line 256, in handle_async_request
    raise exc from None
  File ".../.venv/lib/python3.13/site-packages/httpcore/_async/connection_pool.py", line 236, in handle_async_request
    response = await connection.handle_async_request(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        pool_request.request
        ^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 101, in handle_async_request
    raise exc
  File ".../.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 78, in handle_async_request
    stream = await self._connect(request)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpcore/_async/connection.py", line 156, in _connect
    stream = await stream.start_tls(**kwargs)
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpcore/_backends/anyio.py", line 67, in start_tls
    with map_exceptions(exc_map):
         ~~~~~~~~~~~~~~^^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 162, in __exit__
    self.gen.throw(value)
    ~~~~~~~~~~~~~~^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpcore/_exceptions.py", line 14, in map_exceptions
    raise to_exc(exc) from exc
httpcore.ConnectError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] ssl/tls alert handshake failure (_ssl.c:1032)

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File ".../repro.py", line 10, in <module>
    asyncio.run(main())
    ~~~~~~~~~~~^^^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 195, in run
    return runner.run(main)
           ~~~~~~~~~~^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/runners.py", line 118, in run
    return self._loop.run_until_complete(task)
           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/asyncio/base_events.py", line 725, in run_until_complete
    return future.result()
           ~~~~~~~~~~~~~^^
  File "/.../repro.py", line 7, in main
    await client.get("https://tls-v1-0.badssl.com:1010")
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1768, in get
    return await self.request(
           ^^^^^^^^^^^^^^^^^^^
    ...<9 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1540, in request
    return await self.send(request, auth=auth, follow_redirects=follow_redirects)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1629, in send
    response = await self._send_handling_auth(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<4 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1657, in _send_handling_auth
    response = await self._send_handling_redirects(
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    ...<3 lines>...
    )
    ^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1694, in _send_handling_redirects
    response = await self._send_single_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_client.py", line 1730, in _send_single_request
    response = await transport.handle_async_request(request)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ".../.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 393, in handle_async_request
    with map_httpcore_exceptions():
         ~~~~~~~~~~~~~~~~~~~~~~~^^
  File "/opt/homebrew/Cellar/[email protected]/3.13.7/Frameworks/Python.framework/Versions/3.13/lib/python3.13/contextlib.py", line 162, in __exit__
    self.gen.throw(value)
    ~~~~~~~~~~~~~~^^^^^^^
  File "/Users/q/src/elasticsearch-py/.venv/lib/python3.13/site-packages/httpx/_transports/default.py", line 118, in map_httpcore_exceptions
    raise mapped_exc(message) from exc
httpx.ConnectError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] ssl/tls alert handshake failure (_ssl.c:1032)

Why is that? While asyncio raises the SSLError directly, Trio wraps it into a BrokenResourceError, and the message is only in the nested SSLError. For this reason, the current exception map approach doesn't work. Note that the fix applied to AnyIO last year won't help here, as AnyIO, just like asyncio, raises the SSLError exception directly.

Finally, in case it's helpful, here are my experiments using Trio and AnyIO directly:

Using Trio directly

import ssl
import trio


async def main():
    stream = await trio.open_ssl_over_tcp_stream(
        "tls-v1-0.badssl.com",
        1010,
        https_compatible=True,
        ssl_context=ssl.create_default_context(),
    )
    await stream.send_all(
        b"GET / HTTP/1.1\r\nHost: tls-v1-0.badssl.com\r\nConnection: close\r\n\r\n"
    )


trio.run(main)

Using AnyIO directly

import ssl

from anyio import connect_tcp, run


async def main():
    # These two steps are only required for certificates that are not trusted by the
    # installed CA certificates on your machine, so you can skip this part if you
    # use Let's Encrypt or a commercial certificate vendor
    context = ssl.create_default_context(ssl.Purpose.SERVER_AUTH)

    async with await connect_tcp(
        "tls-v1-0.badssl.com", 1010, ssl_context=context
    ) as client:
        await client.send(
            b"GET / HTTP/1.1\r\nHost: tls-v1-0.badssl.com\r\nConnection: close\r\n\r\n"
        )
        response = await client.receive()
        print(response)


run(main, backend="trio")

Happy to open an httpcore issue if this is considered a valid problem.

[lovelydinosaur]

Heya @pquentin, really good to hear from you. 😄

Thanks for the sensibly neat report.

Okay, so trio's BrokenResource doesn't include the string parameter, so from your "Using Trio directly" example...

• str(exc) - Returns "".
• str(exc.__cause__) - Returns the SSL error text.

I've considered opening an issue with trio, for example...

https://github.com/python-trio/trio/blob/84fbcb783d6543a8583df35979f270dec9348b1e/src/trio/_ssl.py#L504

    except (_stdlib_ssl.SSLError, _stdlib_ssl.CertificateError) as exc:
        self._state = _State.BROKEN
        raise trio.BrokenResourceError from exc

The class does document that __cause__ may be more illuminating here.

Options here...

• On the trio side, the team might appreciate a pull request including the text details directly in the exception.
• On the httpcore side, we could resolve this. (Falling back to .__cause__ for the exception details if needed.)

Either of those would resolve the issue as you've stated it. (?)

Overall tho there's also a bit of a gap between the user experience of...

<excessively long traceback> "ssl.SSLError: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1028)"

...vs the browser experience...