[DO NOT MERGE] WIP, add/backport generic server-sent events support to Azure Core

[Xiaofei Cao (XiaofeiCao)]

Scope

Adds Azure Core support for single-response generic SSE consumption. It parses one established Response<BinaryData>; it never reconnects, replays, or sends Last-Event-Id.

• New: ServerSentEvent<T>, ServerSentEventListener<T>, ServerSentEventStreams, incremental SSE parsing, body-owned response lifecycle, and optional typed terminal-event predicates.
• Updated: REST proxy live-body preservation, response logging protection, SSE media-type helpers, and non-replayable BinaryData streaming.
• Unchanged: HTTP pipeline, general policies, transports, and Reactor.
• Separate stacked work: generated client APIs, shared proxy declarations, and generated event conversion.

Contract

ServerSentEventStreams is exported from com.azure.core.http; parser and response-validation types remain internal. REST proxy methods return an ordinary, non-Closeable Response<BinaryData>. Its non-replayable body owns the physical HttpResponse and releases it when body consumption completes, fails, is interrupted, or is cancelled. Validation failures cancel an available body before propagating the error.

Non-204 responses require text/event-stream content. Event streams are decoded as UTF-8 regardless of an optional declared charset. Existing overloads complete on EOF or HTTP 204. Predicate overloads deliver the matching typed terminal event and complete; EOF before a match is an incomplete-stream error.

Accept: text/event-stream preserves a live body only when its q value is syntactically valid and greater than zero.

Validation

• Focused SSE, media-type, REST proxy, FluxInputStream, and BinaryData tests
• Full Azure Core unit and integration test suite
• Azure Core package build, Checkstyle, SpotBugs, JavaDoc, and Revapi

[azure-pipelines]

Azure Pipelines:
Successfully started running 1 pipeline(s).
34 pipeline(s) were filtered out due to trigger conditions.
There may be pipelines that require an authorized user to comment /azp run to run.

[Weidong Xu (weidongxu-microsoft)]

The incremental parser needs a bounded pending-event size before this is safe to ship.

appendByte doubles lineBytes without a maximum, and completed data: lines are accumulated in data until a blank line. A server (or intermediary) can therefore send either one unterminated line or an unlimited sequence of data: lines without an empty-line dispatch and make the client retain the entire stream until heap exhaustion. This affects both the async and listener paths.

Please enforce a documented maximum line/event size and terminate the stream with a clear exception when it is exceeded. Add tests for both an oversized single line and many bounded lines without a terminating blank line.

it is a draft

[Xiaofei Cao (XiaofeiCao)]

The incremental parser needs a bounded pending-event size before this is safe to ship.

appendByte doubles lineBytes without a maximum, and completed data: lines are accumulated in data until a blank line. A server (or intermediary) can therefore send either one unterminated line or an unlimited sequence of data: lines without an empty-line dispatch and make the client retain the entire stream until heap exhaustion. This affects both the async and listener paths.

Please enforce a documented maximum line/event size and terminate the stream with a clear exception when it is exceeded. Add tests for both an oversized single line and many bounded lines without a terminating blank line.

Some thoughts(evidence collected by agent):

• Our repo seems doesn't have a size limit for eagerly-read response body(BinaryData)
• Spring WebFlux's default event size limit is 256kb: https://docs.spring.io/spring-framework/reference/web/webflux-webclient/client-builder.html#webflux-client-builder-maxinmemorysize
• search's knowledgebase retrieval maxoutputsize official doc use 6000kb as example: https://learn.microsoft.com/en-us/azure/search/agentic-retrieval-how-to-retrieve?tabs=2026-05-01-preview&pivots=csharp#limit-final-grounding-documents
  and it's configurable
• .NET doesn't expose any event size limit in current azure-core

Spring's 256kb limit doesn't seem to fit our knowledgebase retrieval case. Since currently we don't have configuration for response body size(correct me if I'm wrong), I'd say we don't enforce this.

[Weidong Xu (weidongxu-microsoft)]

Three minor follow-ups from the API/protocol pass:

1. ServerSentEventStreams publicly accepts any Response<BinaryData>, but internally requires the runtime response to implement Closeable. Consider making that ownership requirement explicit in the API/type contract, or at least documenting it, so wrapped/custom responses don't fail unexpectedly.
2. isTextEventStreamContentType currently accepts an explicitly non-UTF-8 charset such as text/event-stream; charset=iso-8859-1, while the parser always decodes UTF-8. SSE is UTF-8-only, so an incompatible charset declaration should be rejected.
3. acceptsTextEventStream treats malformed or out-of-range quality values such as q=bogus, q=-1, and q=2 as enabled. It would be safer to validate the HTTP q-value grammar and only enable the media range for a valid value greater than zero.

These are non-blocking compared with the pending-event size concern.

[Weidong Xu (weidongxu-microsoft)]

Agent-generated Java SSE interface design comparison and recommendations: https://gist.github.com/weidongxu-microsoft/f99f792a78f16cef8c9c1674c68e7d1b

[Weidong Xu (weidongxu-microsoft)]

Agent-generated Java SSE interface design comparison and recommendations: https://gist.github.com/weidongxu-microsoft/f99f792a78f16cef8c9c1674c68e7d1b

Summary aside, this is more or less the "alternative design" we've discussed. A closable stream pattern for sync.

[Alan Zimmer (alzimmermsft)]

I'd prefer we kept closer to the protocol layer with the typing here and remove <T>. Replacing T data with String data and letting the SSE consumer handle String -> T.

[Xiaofei Cao (XiaofeiCao)]

There's ServerSentEventFrame for this: https://github.com/XiaofeiCao/azure-sdk-for-java/blob/5fa41d4a0f0c64386c5930c5c676a88a6039e32d/sdk/core/azure-core/src/main/java/com/azure/core/implementation/util/ServerSentEventStream.java#L469

In this draft, I'm exposing ServerSentEvent to user via

Flux<ServerSentEvent<KnowledgeBaseRetrievalStreamEvent>> retrieveStream();

, maybe a generic one would be more suitable?

[Alan Zimmer (alzimmermsft)]

Let's not hide this constructor, it really doesn't benefit us to do so. Let's scope the constructor to properties that are required to create an event and add setters and getters for optional properties. Or, just keep everything in the constructor and pass null accordingly.

[Xiaofei Cao (XiaofeiCao)]

If I'm understanding correctly, ServerSentEvent is kinda like an immutable response model.
If it's exposed to user, I'd prefer hiding it. But we could have more discussion on whether to expose it, or directly return, e.g. Flux<KnowledegBaseRetrievalStreamEvent. Would like to hear your opinion on this one.

[Alan Zimmer (alzimmermsft)]

Do we have any cases where Azure services use multiple Accept header values and use this part of the HTTP spec?

[Xiaofei Cao (XiaofeiCao)]

Originally I thought I saw one in recording files:
https://github.com/Azure/azure-sdk-assets/blob/9e19803afadaf24ee00ff403a60eae684667944f/java/sdk/compute/azure-resourcemanager-compute/src/test/resources/session-records/ManagedDiskOperationsTests.canCopyStartIncrementalSnapshot.json#L705

checked again and it turns out to be fallback logic by us..
https://github.com/microsoft/typespec/blob/main/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/util/MethodUtil.java#L58

Then no, haven't seen other cases. Let me remove this check.

[Alan Zimmer (alzimmermsft)]

Why do we fail if the charset isn't UTF-8? We are capable of supporting other character encodings, even have CoreUtils.bomAwareToString which returns a String based on a leading byte order mark or the charset defined in the Content-Type header.

[Xiaofei Cao (XiaofeiCao)]

good question, it is for simplicity here.. yeah, we probably don't want to restrict the encoding here.

CoreUtils.bomAwareToString seems to require reading the whole stream, which may not be suitable for sse stream here, CMIIW.

I'm letting agent figure this out..

[Xiaofei Cao (XiaofeiCao)]

Done by agent. Hopefully the correctness is ensured by the added tests..

[Xiaofei Cao (XiaofeiCao)]

Seems sse can only be decoded as utf8:

Event streams are always decoded as UTF-8. There is no way to specify another character encoding.

See https://html.spec.whatwg.org/multipage/server-sent-events.html#server-sent-events-intro

[Alan Zimmer (alzimmermsft)]

Should we instead write a Subscriber / Flux type for this, similar to what we did for FluxUtil.writeFile and FluxUtil.readFile?

[Xiaofei Cao (XiaofeiCao)]

agent produced additional 250+ lines of code and pretty hard to reason about.

Compared to FluxUtil.writeFile, there's extra complexity which standard Reactor operator already handles(below is from agent):

For SSE it had to additionally handle parser state across buffers, zero-to-many events per buffer, queued frames, downstream demand, EOF flushing, synchronous errors, cancellation, and reentrant requests. It duplicated Reactor’s demand, cancellation, and signal-ordering machinery. Standard Reactor operators express those guarantees more clearly, so I simplified it to a per-subscription decoder pipeline with bounded read-ahead.