Add support for emitting ServerSentEvents from minimal APIs

[captainsafia]

Background and Motivation

This proposal adds first-class support for SSE responses through the IResult pattern, making it consistent with other response types in minimal APIs. While ASP.NET Core has supported SSE through manual response writing, there hasn't been a built-in IResult implementation to return SSE streams from minimal API endpoints.

Proposed API

// Assembly: Microsoft.AspNetCore.Http.Results
namespace Microsoft.AspNetCore.Http;

public static class TypedResults 
{
+    public static ServerSentEventResult<string> ServerSentEvents<T>(
+        IAsyncEnumerable<string> value, 
+        string? eventType = null);
+
+    public static ServerSentEventResult<T> ServerSentEvents<T>(
+        IAsyncEnumerable<T> value, 
+        string? eventType = null);
+
+    public static ServerSentEventResult<T> ServerSentEvents<T>(
+        IAsyncEnumerable<SseItem<T>> value);
}

+ public sealed class ServerSentEventResult<T> : IResult, IEndpointMetadataProvider
+ {
+    static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
+ }

Usage Examples

Basic usage with simple values:

app.MapGet("/sse", () =>
{
    async IAsyncEnumerable<string> GenerateEvents(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        var counter = 0;
        while (!cancellationToken.IsCancellationRequested)
        {
            yield return $"Event {counter++} at {DateTime.UtcNow}";
            await Task.Delay(1000, cancellationToken);
        }
    }

    return TypedResults.ServerSentEvents(GenerateEvents());
});

Usage with custom event types:

app.MapGet("/notifications", () =>
{
    async IAsyncEnumerable<Notification> GetNotifications(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            yield return new Notification("New message received");
            await Task.Delay(5000, cancellationToken);
        }
    }

    return TypedResults.ServerSentEvents(GetNotifications(), eventType: "notification");
});

Raw string processing with string overload:

app.MapGet("/mixed-events", () =>
{
    async IAsyncEnumerable<string> GetMixedEvents(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        yield return "Starting";
        yield return "Going";
        yield return "Finished";
    }

    return TypedResults.ServerSentEvents(GetMixedEvents());
});

Fine-grained control with the SseItem<T> overload:

app.MapGet("/mixed-events", () =>
{
    async IAsyncEnumerable<SseItem<string>> GetMixedEvents(
        [EnumeratorCancellation] CancellationToken cancellationToken)
    {
        yield return new SseItem<string>("System starting", "init");
        yield return new SseItem<string>("Processing data", "progress") { EventId = "some-guid" };
        yield return new SseItem<string>("Complete", "done");
    }

    return TypedResults.ServerSentEvents(GetMixedEvents());
});

Alternative Designs

• The TypedResults extension methods do not expose an overload that takes an event ID. Instead, the user must use the SseItem<T> based overload of the extension method if they want to control the event ID at a more granular level.

Risks

N/A

[BrennanConroy]

FYI; SSE in firefox has had a long standing bug where EventSource in Javascript doesn't fire the Open event until the server has started sending data.
See https://source.dot.net/#Microsoft.AspNetCore.Http.Connections/Internal/Transports/ServerSentEventsServerTransport.cs,45 for what we do in SignalR. It might not be relevant to Minimal since when we return the SSE IResult we'll be writing SSE frames at that point? Unless we want bi-directional SSE in which case we'd somehow need to send a comment frame when app code wants to read SSE data.

We can also steal (share) the writing side of SSE from SignalR https://source.dot.net/#Microsoft.AspNetCore.Http.Connections/ServerSentEventsMessageFormatter.cs,c4a21cef091f2b21

[eiriktsarpalis]

Given that System.Net.ServerSentEvents is only exposed an OOB NuGet package, does it create any challenges when it comes to adding it as a dependency in the aspnetcore shared framework?

cc @halter73 @stephentoub

[stephentoub]

Given that System.Net.ServerSentEvents is only exposed an OOB NuGet package, does it create any challenges when it comes to adding it as a dependency in the aspnetcore shared framework?

cc @halter73 @stephentoub

It would end up being pulled into the aspnetcore shared framework. That happens with several other runtime packages.

[dotnet-policy-service]

Thank you for submitting this for API review. This will be reviewed by @dotnet/aspnet-api-review at the next meeting of the ASP.NET Core API Review group. Please ensure you take a look at the API review process documentation and ensure that:

• The PR contains changes to the reference-assembly that describe the API change. Or, you have included a snippet of reference-assembly-style code that illustrates the API change.
• The PR describes the impact to users, both positive (useful new APIs) and negative (breaking changes).
• Someone is assigned to "champion" this change in the meeting, and they understand the impact and design of the change.

[eiriktsarpalis]

@captainsafia under current API proposal what controls how individual T data gets serialized? Am I right to assume that it hardcodes to the configured serializer? That might not work for certain SSE wire formats, for example OpenAI/Copilot Agents require that the stream should end with this event:

data: [DONE]

This is a non-standard extension of the SSE specification, and it can only be achieved using either a custom marshalling delegate as with the System.Net.ServerSentEvents APIs or exposing an overload specifically accepting SseItem<string>.

[captainsafia]

@captainsafia under current API proposal what controls how individual T data gets serialized? Am I right to assume that it hardcodes to the configured serializer?

Correct. It defaults to the built-in serializer.

This is a non-standard extension of the SSE specification, and it can only be achieved using either a custom marshalling delegate as with the System.Net.ServerSentEvents APIs

To this end, I consdiered adding an overload that allows end-users to customize the Action<SseItem<T>, IBufferWriter<byte>> callback in the formatter. That would solve the problem here although I'm not sure how nice it is as an API.

[eiriktsarpalis]

Am I correct in assuming that the default handling of SseItem<string> would serialize individual payloads as JSON strings? The System.Net.SSE APIs expose overloads for SseItem<string> that emit text as-is into the event data. This is crucial since the SSE spec itself allows unstructured text on individual event data and in fact the OpenAI use case does need us to emit unstructured text.

Exposing an overload that takes a formatting callback would serve to unblock our use case, however it still puts the onus on the application author to create a callback that formats strings as raw strings. One possibility is specializing handling of SseItem<string> specifically so that it always get handled as raw text.