HTTPCLIENT-2396 - add Server-Sent Events client to HttpClient5.

[arturobernalg]

New SSE module for HttpClient5 with EventSource, SseExecutor, and spec-compliant parsing.
Pluggable reconnect strategies, resumable IDs, and Retry-After hints; H1/H2 ready.
Defaults are simple; advanced tuning exposed via builders and strategies.
Includes docs, examples, and tests; API surface ready for review.

[ok2c]

@arturobernalg Would it be OK for you to move implementation classes to impl package? It would make it easier to focus on the publicly visible APIs.

[ok2c]

@arturobernalg What is your motivation for proposing this new module? Do you have an application that would be using it? Is there any chance of someone else contributing to it as well?

That would be the second module where you would be the sole maintainer.

[arturobernalg]

@arturobernalg What is your motivation for proposing this new module? Do you have an application that would be using it? Is there any chance of someone else contributing to it as well?

That would be the second module where you would be the sole maintainer.

My motivation is to provide minimal, low-level support for Server-Sent Events on top of the existing async HttpClient APIs. Right now users who need SSE either implement their own ad-hoc parsing and reconnect logic, or pull in a separate client library.

I do have concrete use cases for this in long-lived monitoring / event streams and would use this module in those applications instead of maintaining custom SSE code.

The module is small, self-contained and builds only on existing HttpClient primitives. The public API is intentionally limited, so the maintenance cost should stay low even if I remain the primary maintainer.

[rschmitt]

@arturobernalg Would it be OK for you to move implementation classes to impl package? It would make it easier to focus on the publicly visible APIs.

I don't recommend doing this. Package-private (default) visibility is the only reliable Java language mechanism we have to encapsulate implementation details. If we put implementation details in an impl package, they all need to be declared public just so we can make internal calls to them from our actually-public APIs!

[ok2c]

The module is small, self-contained and builds only on existing HttpClient primitives. The public API is intentionally limited, so the maintenance cost should stay low even if I remain the primary maintainer.

@arturobernalg There were instances when a complete module had been contributed to the project in the past: caching in client and reactive in core, but in both instances those contributions were backed by a commercial entity. At the very least those modules had a user base. In your case there is no user base, so it is unclear how this new solution would be applied in real life settings. If there is no documentation no one will even find out about it unless they look at the source code. I have no objections to inclusion of this module into the project but I think your priorities needs to shift from producing more experimental features to documenting / applying those you have already contributed.

[ok2c]

I don't recommend doing this. Package-private (default) visibility is the only reliable Java language mechanism we have to encapsulate implementation details. If we put implementation details in an impl package, they all need to be declared public just so we can make internal calls to them from our actually-public APIs!

@rschmitt That seems to imply that public API classes would have some implementation code in them that needed to be kept private / not exposed to the API consumers, because here is nothing stopping classes in impl from re-using package private code within that package.

I understand this is more of a matter of taste, so let's agree to disagree here and let @arturobernalg decide what approach to take.

[ok2c]

@arturobernalg Could you please also add @Contract annotations as well?

[rschmitt]

@rschmitt That seems to imply that public API classes would have some implementation code in them that needed to be kept private / not exposed to the API consumers, because here is nothing stopping classes in impl from re-using package private code within that package.

To clarify, my concern with an impl package is that at least one API in it needs to be declared public in order to facilitate internal calls within the client, and those public APIs could conceivably be declared package-private instead if they were in the same Java package as the caller. I think this aspect of code organization is frequently overlooked, which is one reason why every mature Java library ends up adding its own @Internal annotation. The other reason is Java's crude language-level visibility mechanisms. (Jigsaw fixes this, but I think it was delivered too late to matter much.)