[Search] Add knowledge base retrieve stream convenience APIs

[Xiaofei Cao (XiaofeiCao)]

Description

Adds regeneration-safe convenience APIs for knowledge-base retrieveStream on top of #49988.

• Adds async Flux and sync listener-based typed SSE APIs.
• Adds Search-local SSE models, parsing, and stream lifecycle support without changing azure-core.
• Adds typed wrappers for known events and a raw-data fallback for unknown event names.
• Treats terminal predicates as inclusive early-stop signals; EOF and HTTP 204 complete normally without a terminal event, matching [DO NOT MERGE] WIP, add/backport generic server-sent events support to Azure Core #50081.
• Keeps generated output reproducible through SearchCustomizations.
• Uses [Search 2026-08-01-preview] java SDK codegen #49988's repaired synonym-map convenience method without additional customization.

Testing

• Focused knowledge-base event conversion and sync/async client integration tests
• Generic SSE parser, Flux, response, and lifecycle coverage remains in [DO NOT MERGE] WIP, add/backport generic server-sent events support to Azure Core #50081
• SpotBugs and Revapi
• Java 8 and Java 21 compilation
• Isolated SDK regeneration consistency

[azure-pipelines]

Azure Pipelines:
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.

[Xiaofei Cao (XiaofeiCao)]

event model/wrapper deserialization tests

[Xiaofei Cao (XiaofeiCao)]

async retrieveStream

[Xiaofei Cao (XiaofeiCao)]

sync retrieveStream

[Xiaofei Cao (XiaofeiCao)]

For unknown events, we'll not throw exception, but put them all in this UnknownKnowledgeBaseRetrievalStreamEvent.

Welcome suggestions.

[efrainretana]

I think this is fine. I believe the other langs are doing the same

[azure-pipelines]

Azure Pipelines:
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.

[Copilot]

Pull request overview

This PR adds regeneration-safe, typed server-sent events (SSE) convenience APIs for Knowledge Base retrieveStream in azure-search-documents, including Search-local SSE parsing utilities and typed wrappers for known knowledge-base events with a forward-compatible “unknown event” fallback.

Changes:

• Introduces Search-local SSE public models (ServerSentEvent, ServerSentEventListener) and internal stream parsing/lifecycle utilities.
• Adds typed Knowledge Base retrieval stream event wrappers + converter, and new sync/async retrieveStream convenience APIs that emit/dispatch typed SSE events.
• Adds focused tests for stream event conversion and client integration, and updates the changelog.

Reviewed changes

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdk/search/azure-search-documents/src/test/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalStreamTests.java	Adds tests validating typed event conversion and sync/async streaming behavior.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/ServerSentEventListener.java	Adds public sync listener contract for SSE consumption.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/ServerSentEvent.java	Adds public typed SSE event model and internal construction hook.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStreams.java	Adds facade utilities to decode/listen to SSE streams from a single response.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStreamResponse.java	Validates SSE response status/content-type and supports body cancellation.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventStream.java	Implements SSE decoding and sync listener processing.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/models/implementation/sse/ServerSentEventHelper.java	Internal accessor helper for constructing ServerSentEvent.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseRetrievalStreamEvent.java	Adds base type for typed KB retrieval stream events + terminal flag.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/UnknownKnowledgeBaseRetrievalStreamEvent.java	Adds raw-data fallback model for unknown event names.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseRetrievalStartedStreamEvent.java	Adds typed wrapper for retrieval.started.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseActivityStartedStreamEvent.java	Adds typed wrapper for activity.started.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseActivityCompletedStreamEvent.java	Adds typed wrapper for activity.completed.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseAnswerCompletedStreamEvent.java	Adds typed wrapper for answer.completed.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseReferencesCompletedStreamEvent.java	Adds typed wrapper for references.completed.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseErrorStreamEvent.java	Adds typed terminal wrapper for error.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/models/KnowledgeBaseResponseCompletedStreamEvent.java	Adds typed terminal wrapper for response.completed.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/implementation/KnowledgeBaseRetrievalStreamEventConverter.java	Adds event-name-to-typed-model conversion logic.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalClient.java	Adds new public sync retrieveStream(..., listener) convenience API.
sdk/search/azure-search-documents/src/main/java/com/azure/search/documents/knowledgebases/KnowledgeBaseRetrievalAsyncClient.java	Adds new public async retrieveStream(...) convenience API returning Flux.
sdk/search/azure-search-documents/customizations/src/main/java/SearchCustomizations.java	Injects regeneration-safe additions for SSE + KB streaming APIs/models.
sdk/search/azure-search-documents/CHANGELOG.md	Documents the newly added typed SSE streaming APIs and models.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[Weidong Xu (weidongxu-microsoft)]

Agent feedback — for consideration only: ServerSentEventDecoder retains an entire event until a blank line dispatches it. Both the current line and accumulated data: lines are unbounded, so a malformed endpoint could cause excessive client memory use.

Would it be worth enforcing a maximum pending-event size? One possible starting point is 16 MiB of raw UTF-8, subject to confirmation against the service's largest legitimate serialized event, especially references.completed. A single counter for all non-delimiter bytes since the previous blank line would cover both one oversized line and many smaller data: lines. It could be checked before expanding lineBytes and reset after blank-line dispatch.

If adopted, useful boundary cases would include an over-limit unterminated line, aggregate data: lines over the limit, an event exactly at the limit, and resetting the counter between events.

[Weidong Xu (weidongxu-microsoft)]

A possible implementation shape:

private static final int MAX_PENDING_EVENT_BYTES = 16 * 1024 * 1024;

private int pendingEventBytes;

private void appendByte(byte value) {
    if (pendingEventBytes == MAX_PENDING_EVENT_BYTES) {
        throw new IllegalStateException(
            "Server-sent event exceeded the maximum size of "
                + MAX_PENDING_EVENT_BYTES + " bytes.");
    }

    pendingEventBytes++;

    if (lineLength == lineBytes.length) {
        int newLength = Math.min(lineBytes.length * 2, MAX_PENDING_EVENT_BYTES);
        lineBytes = Arrays.copyOf(lineBytes, newLength);
    }

    lineBytes[lineLength++] = value;
}

Then reset pendingEventBytes when processLine receives the blank line that dispatches the pending event. Checking before buffer growth also avoids integer overflow or allocating beyond the configured ceiling.

[Xiaofei Cao (XiaofeiCao)]

16mb sounds reasonable to me. efrainretana let us know if this is not suitable for retrieval response.