Timeout during AnyIOStream.start_tls causes stuck connections in the pool when using AsyncHTTPProxy

[ariallas]

Example

Hi!
Please excuse my hacky way to demonstrate the issue:

Setup:

• python 3.11.5
• httpcore[asyncio]==1.0.5
• proxy.py

import asyncio
import logging
import random

import httpcore
import httpcore._backends.anyio

# Wrapper for start_tls to artificially cause a timeout
def random_timeout_wrapper(f):
    async def _wrapper(*args, **kwargs):
        if random.randrange(2) == 1:
            if len(args) == 4:
                args = args[:3]
            kwargs["timeout"] = 0.001
            print(f"\nAbout to time out\n")
        return await f(*args, **kwargs)

    return _wrapper

httpcore._backends.anyio.AnyIOStream.start_tls = random_timeout_wrapper(
    httpcore._backends.anyio.AnyIOStream.start_tls
)

async def async_main():
    logging.basicConfig(level=0)

    async with httpcore.AsyncHTTPProxy(
        proxy_url="http://127.0.0.1:8080/", max_connections=256
    ) as proxy:
        while True:
            try:
                response = await proxy.request("GET", "https://www.example.com/")
                print(response)
                print(proxy.connections)
            except Exception as e:
                pass
            await asyncio.sleep(2)

if __name__ == "__main__":
    asyncio.run(async_main())

To replicate:

• Start proxy.py: proxy --hostname 127.0.0.1 --port 8080
• Start the script
• Shutdown and restart the proxy a couple of times

You should see that every time a timeout happens during start_tls, after just having reconnected to the proxy, there is a new stuck connection in the pool that looks like this: <AsyncTunnelHTTPConnection ['http://127.0.0.1:8080', HTTP/1.1, ACTIVE, Request Count: 1]>

Context

We have a bunch of Telegram bots on python-telegram-bot running behind a proxy. Once every couple of weeks they all simultaneously stop responding - judging by the logs this seems to be the root issue.

[TayfurYldz]

The failure window described here is still visible in current main.

AsyncTunnelHTTPConnection first sends CONNECT through its underlying AsyncHTTPConnection, gets the tunnel's network_stream, and then performs:

stream = await stream.start_tls(...)

Only after TLS succeeds does it replace self._connection with an HTTP/1.1 or HTTP/2 connection for the remote origin and set self._connected = True.

If start_tls() raises, neither of those final state transitions happens. The object therefore keeps the underlying proxy HTTP connection that has already completed CONNECT. From the pool's point of view that wrapper can remain an active connection, but the CONNECT tunnel is not a reusable ordinary proxy HTTP connection anymore. Retrying initialization on that same state is invalid.

So the cleanup invariant should be: once CONNECT succeeds, failure of TLS upgrade must make that tunnel connection unusable and close its underlying stream/connection before propagating the timeout/error. The critical cleanup should also be cancellation-safe, for the same reason response cleanup is shielded elsewhere in current async httpcore.

A focused regression test can avoid a real proxy: have a mock proxy return a successful CONNECT and a network stream whose start_tls() raises ConnectTimeout; after the request fails, assert the tunnel wrapper is closed/expired and the pool can create a fresh connection for the next request rather than retaining an ACTIVE half-initialized tunnel.

That targets the actual ownership transition—CONNECT has consumed the proxy connection, TLS failed before the remote HTTP connection was installed—rather than special-casing timeout as such.