Add support for ServerSentEventsResult and extension methods

Author: captainsafia

eng/SharedFramework.External.props

@@ -42,6 +42,7 @@
     <ExternalAspNetCoreAppReference Include="Microsoft.Extensions.Options.DataAnnotations"                 Version="$(MicrosoftExtensionsOptionsDataAnnotationsVersion)" />
     <ExternalAspNetCoreAppReference Include="Microsoft.Extensions.Options"                                 Version="$(MicrosoftExtensionsOptionsVersion)" />
     <ExternalAspNetCoreAppReference Include="Microsoft.Extensions.Primitives"                              Version="$(MicrosoftExtensionsPrimitivesVersion)" />
+    <ExternalAspNetCoreAppReference Include="System.Net.ServerSentEvents"                             Version="$(SystemNextServerSentEvents)" />
     <ExternalAspNetCoreAppReference Include="System.Security.Cryptography.Xml"                             Version="$(SystemSecurityCryptographyXmlVersion)" />
     <ExternalAspNetCoreAppReference Include="System.Threading.RateLimiting"                                Version="$(SystemThreadingRateLimitingVersion)" />
 

src/Http/Http.Results/src/Microsoft.AspNetCore.Http.Results.csproj

@@ -28,6 +28,7 @@
     <Reference Include="Microsoft.AspNetCore.Hosting.Abstractions" />
     <Reference Include="Microsoft.AspNetCore.Http.Extensions" />
     <Reference Include="Microsoft.AspNetCore.Routing" />
+    <Reference Include="System.Net.ServerSentEvents" />
 
     <InternalsVisibleTo Include="Microsoft.AspNetCore.Http.Results.Tests" />
   </ItemGroup>

src/Http/Http.Results/src/PublicAPI.Unshipped.txt

@@ -1,2 +1,10 @@
-#nullable enable
+Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<T>
+Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<T>.ExecuteAsync(Microsoft.AspNetCore.Http.HttpContext! httpContext) -> System.Threading.Tasks.Task!
+Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<T>.StatusCode.get -> int?
 static Microsoft.AspNetCore.Http.HttpResults.RedirectHttpResult.IsLocalUrl(string? url) -> bool
+static Microsoft.AspNetCore.Http.Results.ServerSentEvents(System.Collections.Generic.IAsyncEnumerable<string!>! value, string? eventType = null) -> Microsoft.AspNetCore.Http.IResult!
+static Microsoft.AspNetCore.Http.Results.ServerSentEvents<T>(System.Collections.Generic.IAsyncEnumerable<System.Net.ServerSentEvents.SseItem<T>>! value) -> Microsoft.AspNetCore.Http.IResult!
+static Microsoft.AspNetCore.Http.Results.ServerSentEvents<T>(System.Collections.Generic.IAsyncEnumerable<T>! value, string? eventType = null) -> Microsoft.AspNetCore.Http.IResult!
+static Microsoft.AspNetCore.Http.TypedResults.ServerSentEvents(System.Collections.Generic.IAsyncEnumerable<string!>! values, string? eventType = null) -> Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<string!>!
+static Microsoft.AspNetCore.Http.TypedResults.ServerSentEvents<T>(System.Collections.Generic.IAsyncEnumerable<System.Net.ServerSentEvents.SseItem<T>>! values) -> Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<T>!
+static Microsoft.AspNetCore.Http.TypedResults.ServerSentEvents<T>(System.Collections.Generic.IAsyncEnumerable<T>! values, string? eventType = null) -> Microsoft.AspNetCore.Http.HttpResults.ServerSentEventsResult<T>!

src/Http/Http.Results/src/Results.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 using System.IO.Pipelines;
+using System.Net.ServerSentEvents;
 using System.Security.Claims;
 using System.Text;
 using System.Text.Json;
@@ -978,6 +979,41 @@ public static IResult AcceptedAtRoute<TValue>(string? routeName, RouteValueDicti
 #pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
         => value is null ? TypedResults.AcceptedAtRoute(routeName, routeValues) : TypedResults.AcceptedAtRoute(value, routeName, routeValues);
 
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{TValue}"/> response.
+    /// </summary>
+    /// <param name="value">The value to be included in the HTTP response body.</param>
+    /// <param name="eventType">The event type to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{TValue}"/> for the response.</returns>
+    /// <remarks>
+    /// Strings serialized by this result type are serialized as raw strings without any additional formatting.
+    /// </remarks>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static IResult ServerSentEvents(IAsyncEnumerable<string> value, string? eventType = null)
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        => new ServerSentEventsResult<string>(value, eventType);
+
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{T}"/> response.
+    /// </summary>
+    /// <typeparam name="T">The type of object that will be serialized to the response body.</typeparam>
+    /// <param name="value">The value to be included in the HTTP response body.</param>
+    /// <param name="eventType">The event type to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{T}"/> for the response.</returns>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static IResult ServerSentEvents<T>(IAsyncEnumerable<T> value, string? eventType = null)
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        => new ServerSentEventsResult<T>(value, eventType);
+
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{T}"/> response.
+    /// </summary>
+    /// <typeparam name="T">The type of object that will be serialized to the response body.</typeparam>
+    /// <param name="value">The value to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{T}"/> for the response.</returns>
+    public static IResult ServerSentEvents<T>(IAsyncEnumerable<SseItem<T>> value)
+        => new ServerSentEventsResult<T>(value);
+
     /// <summary>
     /// Produces an empty result response, that when executed will do nothing.
     /// </summary>

src/Http/Http.Results/src/ServerSentEventsResult.cs

@@ -0,0 +1,94 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Buffers;
+using System.Net.ServerSentEvents;
+using System.Text;
+using Microsoft.AspNetCore.Http.Metadata;
+using System.Reflection;
+using Microsoft.AspNetCore.Builder;
+using System.Text.Json;
+using Microsoft.Extensions.Options;
+using Microsoft.AspNetCore.Http.Json;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Microsoft.AspNetCore.Http.HttpResults;
+
+/// <summary>
+/// Represents a result that writes a stream of server-sent events to the response.
+/// </summary>
+/// <typeparam name="T">The underlying type of the events emitted.</typeparam>
+public sealed class ServerSentEventsResult<T> : IResult, IEndpointMetadataProvider, IStatusCodeHttpResult
+{
+    private readonly IAsyncEnumerable<SseItem<T>> _events;
+
+    /// <inheritdoc/>
+    public int? StatusCode => StatusCodes.Status200OK;
+
+    internal ServerSentEventsResult(IAsyncEnumerable<T> events, string? eventType)
+    {
+        _events = WrapEvents(events, eventType);
+    }
+
+    internal ServerSentEventsResult(IAsyncEnumerable<SseItem<T>> events)
+    {
+        _events = events;
+    }
+
+    /// <inheritdoc />
+    public async Task ExecuteAsync(HttpContext httpContext)
+    {
+        ArgumentNullException.ThrowIfNull(httpContext);
+
+        httpContext.Response.ContentType = "text/event-stream";
+
+        await SseFormatter.WriteAsync(_events, httpContext.Response.Body,
+            (item, writer) => FormatSseItem(item, writer, httpContext),
+            httpContext.RequestAborted);
+    }
+
+    private static void FormatSseItem(SseItem<T> item, IBufferWriter<byte> writer, HttpContext httpContext)
+    {
+        // Emit string and null values as-is
+        if (item.Data is string stringData)
+        {
+            writer.Write(Encoding.UTF8.GetBytes(stringData));
+            return;
+        }
+
+        if (item.Data is null)
+        {
+            writer.Write([]);
+            return;
+        }
+
+        // For non-string types, use JSON serialization with options from DI
+        var jsonOptions = httpContext.RequestServices.GetService<IOptions<JsonOptions>>()?.Value ?? new JsonOptions();
+        var runtimeType = item.Data.GetType();
+        var jsonTypeInfo = jsonOptions.SerializerOptions.GetTypeInfo(typeof(T));
+
+        // Use the appropriate JsonTypeInfo based on whether we need polymorphic serialization
+        var typeInfo = jsonTypeInfo.ShouldUseWith(runtimeType)
+            ? jsonTypeInfo
+            : jsonOptions.SerializerOptions.GetTypeInfo(typeof(object));
+
+        var json = JsonSerializer.Serialize(item.Data, typeInfo);
+        writer.Write(Encoding.UTF8.GetBytes(json));
+    }
+
+    private static async IAsyncEnumerable<SseItem<T>> WrapEvents(IAsyncEnumerable<T> events, string? eventType = null)
+    {
+        await foreach (var item in events)
+        {
+            yield return new SseItem<T>(item, eventType);
+        }
+    }
+
+    static void IEndpointMetadataProvider.PopulateMetadata(MethodInfo method, EndpointBuilder builder)
+    {
+        ArgumentNullException.ThrowIfNull(method);
+        ArgumentNullException.ThrowIfNull(builder);
+
+        builder.Metadata.Add(new ProducesResponseTypeMetadata(StatusCodes.Status200OK, typeof(SseItem<T>), contentTypes: ["text/event-stream"]));
+    }
+}

src/Http/Http.Results/src/TypedResults.cs

@@ -3,6 +3,7 @@
 
 using System.Diagnostics.CodeAnalysis;
 using System.IO.Pipelines;
+using System.Net.ServerSentEvents;
 using System.Security.Claims;
 using System.Text;
 using System.Text.Json;
@@ -1068,6 +1069,41 @@ public static AcceptedAtRoute<TValue> AcceptedAtRoute<TValue>(TValue? value, str
     public static AcceptedAtRoute<TValue> AcceptedAtRoute<TValue>(TValue? value, string? routeName, RouteValueDictionary? routeValues)
         => new(routeName, routeValues, value);
 
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{TValue}"/> response.
+    /// </summary>
+    /// <param name="values">The value to be included in the HTTP response body.</param>
+    /// <param name="eventType">The event type to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{TValue}"/> for the response.</returns>
+    /// <remarks>
+    /// Strings serialized by this result type are serialized as raw strings without any additional formatting.
+    /// </remarks>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static ServerSentEventsResult<string> ServerSentEvents(IAsyncEnumerable<string> values, string? eventType = null)
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        => new(values, eventType);
+
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{T}"/> response.
+    /// </summary>
+    /// <typeparam name="T">The type of object that will be serialized to the response body.</typeparam>
+    /// <param name="values">The value to be included in the HTTP response body.</param>
+    /// <param name="eventType">The event type to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{T}"/> for the response.</returns>
+#pragma warning disable RS0026 // Do not add multiple public overloads with optional parameters
+    public static ServerSentEventsResult<T> ServerSentEvents<T>(IAsyncEnumerable<T> values, string? eventType = null)
+#pragma warning restore RS0026 // Do not add multiple public overloads with optional parameters
+        => new(values, eventType);
+
+    /// <summary>
+    /// Produces a <see cref="ServerSentEventsResult{T}"/> response.
+    /// </summary>
+    /// <typeparam name="T">The type of object that will be serialized to the response body.</typeparam>
+    /// <param name="values">The value to be included in the HTTP response body.</param>
+    /// <returns>The created <see cref="ServerSentEventsResult{T}"/> for the response.</returns>
+    public static ServerSentEventsResult<T> ServerSentEvents<T>(IAsyncEnumerable<SseItem<T>> values)
+        => new(values);
+
     /// <summary>
     /// Produces an empty result response, that when executed will do nothing.
     /// </summary>

src/Http/Http.Results/test/ResultsTests.cs

@@ -1777,7 +1777,8 @@ private static string GetMemberName(Expression expression)
         (() => Results.Unauthorized(), typeof(UnauthorizedHttpResult)),
         (() => Results.UnprocessableEntity(null), typeof(UnprocessableEntity)),
         (() => Results.UnprocessableEntity(new()), typeof(UnprocessableEntity<object>)),
-        (() => Results.ValidationProblem(new Dictionary<string, string[]>(), null, null, null, null, null, null), typeof(ProblemHttpResult))
+        (() => Results.ValidationProblem(new Dictionary<string, string[]>(), null, null, null, null, null, null), typeof(ProblemHttpResult)),
+        (() => Results.ServerSentEvents(AsyncEnumerable.Empty<string>(), null), typeof(ServerSentEventsResult<string>)),
     };
 
     public static IEnumerable<object[]> FactoryMethodsFromTuples() => FactoryMethodsTuples.Select(t => new object[] { t.Item1, t.Item2 });