Add RFC 8297 (103 Early Hints) support to HttpClient5 (async)

[arturobernalg]

Introduces EarlyHintsListener to surface 103 Early Hints without altering final response flow.

Wires listener via HttpClientBuilder#setEarlyHintsListener(...) and HttpAsyncClientBuilder#setEarlyHintsListener(...).

Handles 103 in classic (MainClientExec) and async (EarlyHintsAsyncExec).

Early Hints (RFC 8297) allows servers to advise clients (typically via Link preload/preconnect) before the final response. Libraries should expose these hints while keeping normal processing intact.

[garydgregory]

Hi all,

The page https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103 suggests 103 should only be for HTTP/2 or later. Should this PR only apply to HTTP/2?

[arturobernalg]

Hi all,

The page https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103 suggests 103 should only be for HTTP/2 or later. Should this PR only apply to HTTP/2?

For what I understand MDN’s note is a deployment recommendation, not a protocol limit. RFC 8297 does not restrict 103 to HTTP/2+

[garydgregory]

Hi all,
The page https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103 suggests 103 should only be for HTTP/2 or later. Should this PR only apply to HTTP/2?

For what I understand MDN’s note is a deployment recommendation, not a protocol limit. RFC 8297 does not restrict 103 to HTTP/2+

Check. I wonder if the fact that this is an RFC marked "Experimental" should be of concern, or at least mentioned in the Javadoc.

[arturobernalg]

Hi all,

The page https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103 suggests 103 should only be for HTTP/2 or later. Should this PR only apply to HTTP/2?

For what I understand MDN’s note is a deployment recommendation, not a protocol limit. RFC 8297 does not restrict 103 to HTTP/2+

Check. I wonder if the fact that this is an RFC marked "Experimental" should be of concern, or at least mentioned in the Javadoc.

The RFC text is immutable, so the body still says “Experimental” (that’s the original 2017 publication). However, the IESG later changed the status to Proposed Standard; that action is recorded separately and Datatracker now shows the badge accordingly. Official status-change doc (Feb 5, 2025) is here. 
For reference, the original RFC body that still reads “Experimental” is here (unchanged by design).

[garydgregory]

Thank you for the details @arturobernalg 👌

[rschmitt]

The page https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/103 suggests 103 should only be for HTTP/2 or later.

And rightly so. HTTP/1.1's framing is inherently unreliable and they're still finding desync attacks in the wild. Additionally, this type of scheme works best with async IO, so that the 103 response can be handled as soon as it comes in, and only HTTP/2 is reliably implemented with async IO (since it's a multiplexed protocol). I also find it strange that this RFC provides no way for the client to signal its support for this feature, analogous to Expect: 100-continue. Who the hell would just turn this feature on in production for all clients?

I agree that the client should at least tolerate 103 responses, but I don't have a strong opinion about how to expose them. The dedicated callback in the PR seems reasonable.

[ok2c]

@arturobernalg I agree with @rschmitt I would not add this feature to the classic transport at all. The implementation for the classic i/o looks clumsy and it is not worth it.

[arturobernalg]

@arturobernalg I agree with @rschmitt I would not add this feature to the classic transport at all. The implementation for the classic i/o looks clumsy and it is not worth it.

@ok2c I’ll scope Early Hints to the async client only and drop the classic wiring.

[ok2c]

@arturobernalg Looks good overall. An example / sample app would be nice, though.

[ok2c]

@arturobernalg Why full class name?

[ok2c]

@arturobernalg This one still uses full class name. Should it?

[ok2c]

@arturobernalg There is still one unresolved comment

[arturobernalg]

@arturobernalg There is still one unresolved comment

solve. sorry @ok2c I overlooked it