feat: support Server-Sent Events as a streaming content format (#2232)

glennawatson · web-flow · commit d9b3d5f3ac28 · 2026-07-15T19:23:22.000+10:00
- Add StreamingContentFormat.ServerSentEvents and map text/event-stream to it in DetectStreamingFormat
- Stream each SSE data event into IAsyncEnumerable&lt;T&gt; via SseParser, deserializing payloads through the existing source-generated/reflection JSON metadata path so it stays trim and Native AOT clean
- Reference System.Net.ServerSentEvents on targets that lack it in-box (net4x/netstandard2.0/net8.0/net9.0); net10.0+ use the framework reference
- Inherit both generated and reflection execution paths through the shared streaming seam (no generator change)
- Cover generated/reflection paths and source-gen/reflection serializers; document in README and breaking-changes
diff --git a/README.md b/README.md
@@ -1035,14 +1035,35 @@ await foreach (var company in api.GetDocuments())
 ```
 
 The frame format is auto-detected from the response content type: a content type of `application/jsonl`,
-`application/x-ndjson`, or `application/x-jsonlines` is read as JSON Lines (one value per line); anything else is read
-as a single streamed JSON array. To observe cancellation, add a `CancellationToken` parameter, or use
-`WithCancellation(token)` on the enumerable.
+`application/x-ndjson`, or `application/x-jsonlines` is read as JSON Lines (one value per line); `text/event-stream` is
+read as Server-Sent Events (see below); anything else is read as a single streamed JSON array. To observe cancellation,
+add a `CancellationToken` parameter, or use `WithCancellation(token)` on the enumerable.
 
 Streaming requires the configured `ContentSerializer` to implement `IStreamingContentSerializer`. The default
 `SystemTextJsonContentSerializer` does; a serializer that does not will throw `NotSupportedException` when the sequence
 is enumerated.
 
+##### Consuming Server-Sent Events
+
+When the endpoint responds with `text/event-stream`, Refit parses each Server-Sent Events (SSE) `data` event and
+deserializes its payload to `T`, yielding one item per event as it arrives (the event `type`/`id` envelope is dropped):
+
+```csharp
+public interface IChatApi
+{
+    [Get("/chat/stream")]
+    IAsyncEnumerable<ChatToken> StreamAsync();
+}
+
+await foreach (var token in api.StreamAsync())
+{
+    // one ChatToken per `data:` event, streamed live
+}
+```
+
+If you need the raw event envelope (event type or id), return `Task<Stream>` and feed the unbuffered stream to
+`System.Net.ServerSentEvents.SseParser` directly.
+
 #### XML Content
 
 XML requests and responses are serialized/deserialized using _System.Xml.Serialization.XmlSerializer_.
diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md
@@ -199,6 +199,13 @@ visible in three places.
   generator discovers adapters declared in your project at compile time and emits a direct `Adapt` call — no reflection,
   so adapter-backed methods stay trim and Native AOT clean; the reflection request builder resolves adapters registered
   in `RefitSettings.ReturnTypeAdapters`. See [Custom return types](../README.md#custom-return-types-ireturntypeadapter).
+* **Server-Sent Events as a streaming format.** A `text/event-stream` response returned to an `IAsyncEnumerable<T>`
+  method now streams one deserialized `T` per SSE `data` event, live and unbuffered, through the same seam as JSON
+  arrays and JSON Lines — no generator or reflection change, so both generated and reflection clients inherit it. This
+  adds the `StreamingContentFormat.ServerSentEvents` enum member and takes a new `System.Net.ServerSentEvents` package
+  reference on the targets that lack it in-box (net4x/netstandard2.0/net8.0/net9.0; it is a framework reference on
+  net10.0+). Each event's payload is deserialized through the configured `System.Text.Json` metadata path, so it stays
+  trim and Native AOT clean. See [Consuming Server-Sent Events](../README.md#consuming-server-sent-events).
 * **Obtain the built request without sending it.** A method declared to return `Task<HttpRequestMessage>` builds the
   full request (method, URL, headers, and body/multipart content) and hands it back to the caller instead of dispatching
   it — the equivalent of Retrofit's `Call.request()`, useful for inspection, signing, logging, or manual dispatch. Both
diff --git a/src/Directory.Packages.props b/src/Directory.Packages.props
@@ -64,6 +64,7 @@
   <ItemGroup Label="Microsoft Runtime And Extensions">
     <PackageVersion Include="Microsoft.Extensions.Http" Version="$(MicrosoftExtensionsVersion)"/>
     <PackageVersion Include="System.Net.Http.Json" Version="$(SystemTextJsonVersion)"/>
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="$(SystemTextJsonVersion)"/>
     <PackageVersion Include="System.Text.Json" Version="$(SystemTextJsonVersion)"/>
   </ItemGroup>
 
diff --git a/src/Refit/PublicAPI/net10.0/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net10.0/PublicAPI.Shipped.txt
@@ -365,6 +365,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net11.0/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net11.0/PublicAPI.Shipped.txt
@@ -365,6 +365,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net462/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net462/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net470/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net470/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net471/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net471/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net472/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net472/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net48/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net48/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net481/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net481/PublicAPI.Shipped.txt
@@ -361,6 +361,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net8.0/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net8.0/PublicAPI.Shipped.txt
@@ -365,6 +365,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/PublicAPI/net9.0/PublicAPI.Shipped.txt b/src/Refit/PublicAPI/net9.0/PublicAPI.Shipped.txt
@@ -365,6 +365,7 @@ Refit.StreamPart.Value.get -> System.IO.Stream!
 Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonArray = 0 -> Refit.StreamingContentFormat
 Refit.StreamingContentFormat.JsonLines = 1 -> Refit.StreamingContentFormat
+Refit.StreamingContentFormat.ServerSentEvents = 2 -> Refit.StreamingContentFormat
 Refit.SystemTextJsonContentSerializer
 Refit.SystemTextJsonContentSerializer.DeserializeFromString<T>(string! content) -> T?
 Refit.SystemTextJsonContentSerializer.DeserializeStreamAsync<T>(System.IO.Stream! stream, Refit.StreamingContentFormat format, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) -> System.Collections.Generic.IAsyncEnumerable<T?>!
diff --git a/src/Refit/Refit.csproj b/src/Refit/Refit.csproj
@@ -42,6 +42,11 @@
     <PackageReference Include="System.Net.Http.Json"/>
   </ItemGroup>
 
+  <!-- System.Net.ServerSentEvents is a default framework reference only on net10.0+; reference the package on the targets that lack it (net4x/netstandard2.0/net8.0/net9.0). -->
+  <ItemGroup Condition="'$(TargetFramework)' == 'netstandard2.0' Or '$(TargetFramework)' == 'net462' Or '$(TargetFramework)' == 'net470' Or '$(TargetFramework)' == 'net471' Or '$(TargetFramework)' == 'net472' Or '$(TargetFramework)' == 'net48' Or '$(TargetFramework)' == 'net481' Or '$(TargetFramework)' == 'net8.0' Or '$(TargetFramework)' == 'net9.0'">
+    <PackageReference Include="System.Net.ServerSentEvents"/>
+  </ItemGroup>
+
   <ItemGroup>
     <PackageVersion Include="Microsoft.NETFramework.ReferenceAssemblies" Version="$(NetFrameworkReferenceAssembliesVersion)"/>
   </ItemGroup>
diff --git a/src/Refit/RequestExecutionHelpers.Streaming.cs b/src/Refit/RequestExecutionHelpers.Streaming.cs
@@ -87,6 +87,11 @@ await AddAuthorizationHeaderFromGetterAsync(request, settings, cancellationToken
     private static StreamingContentFormat DetectStreamingFormat(HttpContent content)
     {
         var mediaType = content.Headers.ContentType?.MediaType;
+        if (string.Equals(mediaType, "text/event-stream", StringComparison.OrdinalIgnoreCase))
+        {
+            return StreamingContentFormat.ServerSentEvents;
+        }
+
         return string.Equals(mediaType, "application/jsonl", StringComparison.OrdinalIgnoreCase)
             || string.Equals(mediaType, "application/x-ndjson", StringComparison.OrdinalIgnoreCase)
             || string.Equals(mediaType, "application/x-jsonlines", StringComparison.OrdinalIgnoreCase)
diff --git a/src/Refit/StreamingContentFormat.cs b/src/Refit/StreamingContentFormat.cs
@@ -11,5 +11,8 @@ public enum StreamingContentFormat
     JsonArray,
 
     /// <summary>The body is newline-delimited JSON (JSON Lines): one JSON value per line. See <see href="https://jsonlines.org"/>.</summary>
-    JsonLines
+    JsonLines,
+
+    /// <summary>The body is a server-sent events (SSE) stream: each event's <c>data</c> payload is a JSON value, yielded live as it arrives.</summary>
+    ServerSentEvents
 }
diff --git a/src/Refit/SystemTextJsonContentSerializer.cs b/src/Refit/SystemTextJsonContentSerializer.cs
@@ -4,11 +4,12 @@
 
 #if !NET9_0_OR_GREATER
 using System.Buffers;
-using System.Runtime.CompilerServices;
 #endif
 using System.Diagnostics.CodeAnalysis;
 using System.Net.Http.Json;
+using System.Net.ServerSentEvents;
 using System.Reflection;
+using System.Runtime.CompilerServices;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 #if NET8_0_OR_GREATER
@@ -196,9 +197,12 @@ jsonSerializerOptions.TypeInfoResolver is not null
     {
         ArgumentExceptionHelper.ThrowIfNull(stream);
 
-        return format == StreamingContentFormat.JsonLines
-            ? DeserializeJsonLinesAsync<T>(stream, cancellationToken)
-            : DeserializeJsonArrayAsync<T>(stream, cancellationToken);
+        return format switch
+        {
+            StreamingContentFormat.ServerSentEvents => DeserializeServerSentEventsAsync<T>(stream, cancellationToken),
+            StreamingContentFormat.JsonLines => DeserializeJsonLinesAsync<T>(stream, cancellationToken),
+            _ => DeserializeJsonArrayAsync<T>(stream, cancellationToken),
+        };
     }
 
     /// <summary>
@@ -617,6 +621,61 @@ private void SerializeToWriterReflection<T>(T item, Utf8JsonWriter writer) =>
         JsonSerializer.Deserialize<T>(utf8Json, jsonSerializerOptions);
 #endif
 
+    /// <summary>Streams the JSON <c>data</c> payload of each server-sent event, yielding one deserialized value per event as it arrives.</summary>
+    /// <typeparam name="T">The element type each event's <c>data</c> payload is deserialized to.</typeparam>
+    /// <param name="stream">The unbuffered response body stream.</param>
+    /// <param name="cancellationToken">A token to cancel enumeration.</param>
+    /// <returns>An asynchronous sequence of deserialized event payloads.</returns>
+    [SuppressMessage(
+        "Design",
+        "SST2307:Generic method type parameters should be inferable from the parameters",
+        Justification = "Type parameter intentionally specified explicitly by callers.")]
+    [ExcludeFromCodeCoverage] // async-iterator dispose-mode epilogue: the compiler-generated <>w__disposeMode false-edge cannot be exercised or removed.
+    private async IAsyncEnumerable<T?> DeserializeServerSentEventsAsync<T>(
+        Stream stream,
+        [EnumeratorCancellation] CancellationToken cancellationToken)
+    {
+        var parser = SseParser.Create(stream, DeserializeSseData<T>);
+        await foreach (var item in parser.EnumerateAsync(cancellationToken).ConfigureAwait(false))
+        {
+            yield return item.Data;
+        }
+    }
+
+    /// <summary>Deserializes a single server-sent event's UTF-8 JSON <c>data</c> payload, using source-gen metadata when a resolver is configured.</summary>
+    /// <typeparam name="T">The element type to deserialize.</typeparam>
+    /// <param name="eventType">The event's <c>event</c> field; ignored because only the <c>data</c> payload is surfaced.</param>
+    /// <param name="data">The UTF-8 encoded JSON payload bytes.</param>
+    /// <returns>The deserialized value.</returns>
+    [SuppressMessage(
+        "Design",
+        "SST2307:Generic method type parameters should be inferable from the parameters",
+        Justification = "Type parameter intentionally specified explicitly by callers.")]
+    private T? DeserializeSseData<T>(string eventType, ReadOnlySpan<byte> data)
+    {
+        _ = eventType;
+#if NET8_0_OR_GREATER
+        return jsonSerializerOptions.TypeInfoResolver is not null
+            ? JsonSerializer.Deserialize(data, GetJsonTypeInfo<T>())
+            : DeserializeSseDataReflection<T>(data);
+#else
+        return DeserializeSseDataReflection<T>(data);
+#endif
+    }
+
+    /// <summary>Deserializes a server-sent event payload using reflection-based metadata.</summary>
+    /// <typeparam name="T">The element type to deserialize.</typeparam>
+    /// <param name="utf8Json">The UTF-8 encoded JSON payload bytes.</param>
+    /// <returns>The deserialized value.</returns>
+    [UnconditionalSuppressMessage("Trimming", "IL2026", Justification = ReflectionFallbackJustification)]
+    [UnconditionalSuppressMessage("AOT", "IL3050", Justification = ReflectionFallbackJustification)]
+    [SuppressMessage(
+        "Design",
+        "SST2307:Generic method type parameters should be inferable from the parameters",
+        Justification = "Type parameter intentionally specified explicitly by callers.")]
+    private T? DeserializeSseDataReflection<T>(ReadOnlySpan<byte> utf8Json) =>
+        JsonSerializer.Deserialize<T>(utf8Json, jsonSerializerOptions);
+
     /// <summary>Deserializes a buffered string using reflection-based metadata.</summary>
     /// <typeparam name="T">The type to deserialize.</typeparam>
     /// <param name="content">The buffered content string.</param>
diff --git a/src/tests/Refit.Tests/IStreamingApi.cs b/src/tests/Refit.Tests/IStreamingApi.cs
@@ -29,12 +29,24 @@ public interface IStreamingApi
     [Get("/array")]
     IAsyncEnumerable<StreamItem> GetArrayCancellable(CancellationToken cancellationToken);
 
+    /// <summary>Streams the <c>data</c> payload of each event in a server-sent events response.</summary>
+    /// <returns>The streamed items.</returns>
+    [SuppressMessage("Design", "CA1024:Use properties where appropriate", Justification = "Refit endpoint method fixture; must remain a method to exercise the generator.")]
+    [Get("/events")]
+    IAsyncEnumerable<StreamItem> GetEvents();
+
     /// <summary>Streams a JSON array from a dynamic route, exercising the reflection (non-inline) path.</summary>
     /// <param name="group">The route segment value.</param>
     /// <returns>The streamed items.</returns>
     [Get("/groups/{group}/array")]
     IAsyncEnumerable<StreamItem> GetGroupArray(string group);
 
+    /// <summary>Streams a server-sent events response from a dynamic route, exercising the reflection (non-inline) path.</summary>
+    /// <param name="group">The route segment value.</param>
+    /// <returns>The streamed items.</returns>
+    [Get("/groups/{group}/events")]
+    IAsyncEnumerable<StreamItem> GetGroupEvents(string group);
+
     /// <summary>Streams from a dynamic route with a cancellation token, exercising the reflection path's token linking.</summary>
     /// <param name="group">The route segment value.</param>
     /// <param name="cancellationToken">A token to cancel streaming.</param>
diff --git a/src/tests/Refit.Tests/StreamingResponseTests.cs b/src/tests/Refit.Tests/StreamingResponseTests.cs
