http/2: prototype ALPN fallback from HTTP/2 to HTTP/1.1 for client connections

[pjfanning]

Prototype for #1249, which is the blocker for #483.

Adds OutgoingConnectionBuilder.http2WithFallback(): it offers both h2 and http/1.1 over ALPN and runs the client layer matching whatever the server selected, instead of failing the stream when the server has no HTTP/2 support.

Opening as a draft — the mechanism works and is tested, but the shape is up for discussion (see Open questions below).

The problem this had to solve

ProtocolSwitch decides which stack to install on the first inbound SessionBytes. That is sound server-side, because in HTTP the client always speaks first. Mirroring it client-side deadlocks: if negotiation lands on http/1.1, the server sends nothing until it receives a request, and the switch is sitting on that request waiting for inbound bytes.

So the client needs a "handshake complete, ALPN known" signal, and none of the obvious sources provide one:

• Pekko's TLS stage emits no handshake-complete event — SslTlsInbound is only SessionBytes or SessionTruncated, and SessionBytes only arrives when there is application data.
• SSLSession does not expose the negotiated protocol; only SSLEngine.getApplicationProtocol does.
• setHandshakeApplicationProtocolSelector is only meaningful for the peer that selects the protocol (the server).
• HandshakeCompletedListener is SSLSocket-only.

What's here

AlpnObservingSSLEngine — delegating SSLEngine that watches getApplicationProtocol around wrap/unwrap and reports the result once, the first time it goes non-null. Passes the empty string through when the peer negotiated nothing, which is what the JDK reports for a server that ignores ALPN. Falls back to treating UnsupportedOperationException as "no protocol".

ClientProtocolSwitch — client-side counterpart of ProtocolSwitch, a 4-port BidiFlow stage that installs either layer once the promise completes. Two things it has to handle that the server side does not:

• Inbound elements can overtake the AsyncCallback (an HTTP/2 server sends SETTINGS immediately after the handshake), so they are buffered and replayed into the installed layer.
• The preStart pull on netIn may still be outstanding at install time, and an element can arrive before the sub-stream has demand — so connectIn guards against pulling twice and buffers what it cannot push yet. Without that guard this fails with Cannot pull port (ClientProtocolSwitch.netIn) twice.

Unlike ProtocolSwitch it needs no ServerTerminator plumbing: Http.ClientLayer and Http2Blueprint.clientStack.atop(unwrapTls) have the same shape and both carry NotUsed.

Http2Ext.outgoingConnectionWithNegotiation — builds the stack inside Flow.fromMaterializer so every materialization gets its own engine and promise. This matters: PersistentConnection.managedConnection re-materializes the connection flow on each reconnect, so the closed-over var plus "not reusable" guard that httpsWithAlpn uses server-side would break reconnection here.

Prerequisite bug fix — Http2JDKAlpnSupport.clientSetApplicationProtocols ignored its protocols parameter and hardcoded Array("h2"). Harmless before, since the only caller passed exactly that, but it is the seam this feature needs.

Tests

New Http2ClientFallbackSpec covers both directions against a real TLS server, using Http2.streamId presence on the server-side request as the discriminator for which stack actually ran:

• negotiates HTTP/2 against a server that supports it
• falls back to HTTP/1.1 against a server bound with withEnableHttp2(false)

Locally: the two new tests pass, and Http2ClientServerSpec, Http2ClientSpec, Http2PersistentClientSpec, Http2ServerSpec and TelemetrySpiSpec still pass (175 succeeded, 0 failed). http-core/mimaReportBinaryIssues, scalafmtAll, javafmtAll and headerCheck are clean.

Open questions

• Naming. http2WithFallback() sits next to http2(); other options are httpsWithNegotiation() or making it the behaviour of http2() itself. I kept http2() untouched deliberately — changing it would also change the ALPN list it puts on the wire for existing users.
• managedPersistentHttp2WithFallback() is not included. PersistentConnection assumes HTTP/2 multiplexing semantics, and I did not want to guess at how it should behave over a fallback connection.
• The delegating engine is ~30 mechanical methods. The alternative recorded in HTTP/2 client ALPN fallback needs a handshake-complete signal that the TLS stage does not emit #1249 is a TimerGraphStageLogic polling getApplicationProtocol, which is far less code but puts a poll loop in connection setup. Happy to switch if reviewers prefer that trade.
• Connection pool. Untouched; this is connection-level only.

🤖 Generated with Claude Code