Shared SSLContext can race between HTTP/1.1 and HTTP/2 connections via ALPN mutation

[MaciejZet]

Summary

The current master mutates a caller-provided ssl.SSLContext in
HTTPConnection._connect():

ssl_context.set_alpn_protocols(["http/1.1", "h2"] if self._http2 else ["http/1.1"])

When two concurrent connections share the same context, one configured with
http2=False and one with http2=True, the ALPN configuration can race.

Reproduction

Using current master at 10a658221deb38a4c5b16db55ab554b0bf731707, a deterministic
fake network backend synchronizes both start_tls() calls.

Observed:

writes:
[("http/1.1",), ("http/1.1", "h2")]

observed:
h2 -> ("http/1.1", "h2")
h1 -> ("http/1.1", "h2")

The HTTP/1.1 connection receives the ALPN list written by the concurrent HTTP/2
connection.

The same behavior reproduces in:

• async connections;
• sync connections;
• async HTTP proxy tunnel connections.

Expected behavior

One connection should not change the TLS protocol configuration observed by
another connection merely because they share a caller-provided SSLContext.

Question

Is sharing a caller-provided SSLContext between connections with different
http2 settings supported? If so, should httpcore isolate the ALPN configuration
per connection instead of mutating the shared context?

[IlyaKhalafi]

With the current code, I would use a separate SSLContext for each ALPN policy. Thread-safe connection pooling does not prevent the pools from changing the same context before a handshake.

I checked this with actual local TLS and HTTP requests on your commit 10a6582, using a backend wrapper to force the HTTP/1.1 connection to set ALPN first and the HTTP/2 connection second. The server supported both protocols and preferred h2.

Contexts	Pool settings	Negotiated responses
One shared context	http2=False, http2=True	HTTP/2, HTTP/2
Separate contexts	http2=False, http2=True	HTTP/1.1, HTTP/2
One shared context	Both http2=False	HTTP/1.1, HTTP/1.1

So this can affect the protocol actually used, not only the list observed by a fake backend. In the sync connection handler, negotiated h2 selects the HTTP/2 implementation even when that connection's http2 flag is false.

A practical workaround is to build equivalent contexts separately when creating the pools.

from contextlib import ExitStack
import ssl
import httpcore


def make_context():
    return ssl.create_default_context()


with ExitStack() as stack:
    h1 = stack.enter_context(
        httpcore.ConnectionPool(ssl_context=make_context(), http2=False)
    )
    h2 = stack.enter_context(
        httpcore.ConnectionPool(ssl_context=make_context(), http2=True)
    )
    # Send requests through the pool with the intended protocol policy.

If your existing context has custom trust roots, a client certificate or other TLS settings, apply those same settings in the builder. Create the contexts once per pool rather than once per request. Pre-setting ALPN on a shared context will not help because _connect() sets it again.

This is a mitigation for the observed behavior, not a statement of the maintainers' intended sharing contract. The runtime check covered synchronous direct connections on Python 3.14.6 with certificate and hostname verification enabled. It used controlled scheduling and did not test async or proxy connections.