Azure / Azure/azure-sdk-for-python
[core] add support for SSE/Streaming
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
SSE spec: https://html.spec.whatwg.org/multipage/server-sent-events.html
SSE streaming design gist: https://gist.github.com/kristapratico/d330af39962ea05b10384b865e37b36f
Stream examples: https://gist.github.com/kristapratico/0c7aad76a0fe19959ac7d1063b02a050
See the linked gist for details on the iterator design we want for SSE/JSONL Streaming in azure-core. We won't focus on handling events convenience helpers for the initial implementation so this issue just tracks implementation of the Stream class and its internal helper classes.
A Stream will be initialized with the response, a deserialization_callback, and an optional terminal event. Response headers can be checked to determine which Decoder class we should instantiate (SSE returns content-type == "text/event-stream"). When the user iterates over the stream, internally the general strategy should look like this:
- loop over response.iter_bytes()
- parse each chunk into lines and decode to utf-8 per the spec [SSE](https://html.spec.whatwg.org/multipage/server-sent-events.html#event-stream-interpretation) / [JSONL](https://jsonlines.org/examples/)
- process (decode data with specific decoder class) the lines in order as they are received until we encounter an event, 1) check if it contains the terminal event and end stream or 2) dispatch the event by calling the deserialization_callback on the JSON and returning to the caller
Additionally with SSE streams, we should [re-establish the connection](https://html.spec.whatwg.org/multipage/server-sent-events.html#sse-processing-model) if it gets broken while attempting to read from the server. The spec describes the process of setting the `Last-Event-ID` header and waiting the specified reconnection/retry time. If the reconnection fails, we do not re-attempt. Clients should reconnect if the connection is closed, but can be told to stop reconnecting using the HTTP 204 No Content response code.
Contributor guide
Assessment
This issue has not been assessed yet.