[API Proposal]: Streaming APIs for the System.Net.Http.Json extensions

[IEvangelist]

Background and motivation

As of .NET 8 preview 5 (and starting with .NET 5), there are various extension methods within the System.Net.Http.Json namespace (specifically the System.Net.Http.Json NuGet package 📦) that expose JSON-centric functionality to conveniently encapsulate common workflows. Such as, but not limited to extending the HttpClient:

• GetFromJsonAsync
• PostAsJsonAsync
• PutAsJsonAsync
• PatchAsJsonAsync
• DeleteFromJsonAsync

All of these APIs are Task-like returning, i.e., either Task<TValue> or ValueTask<TValue> However, there are no extension methods for some of the streaming APIs, that return IAsyncEnumerable<TValue>. While this is obviously possible without the use of in-built extension methods, it would be really convenient for the runtime to include said extensions.

Ideally, we could encapsulate all of the logic required to efficiently delegate JSON-streaming calls to the JsonSerializer.DeserializeAsyncEnumerable functionality.

API Proposal

This would be scoped to GET on the HttpClient.

namespace System.Net.Http.Json;

public static partial class HttpClientJsonExtensions
{
    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        CancellationToken cancellationToken = default) { }
}

And the HttpContent:

public static partial class HttpContentJsonExtensions
{
    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content, 
        JsonSerializerOptions? options, 
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content, 
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content,
        JsonTypeInfo<T> jsonTypeInfo,
        CancellationToken cancellationToken = default) { }
}

Potential Implementation

This would essentially encapsulate the following logic:

public static class HttpRequestJsonExtensions
{
    public static async IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client, 
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri, 
        JsonSerializerOptions? options, 
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(client);

        TimeSpan timeout = client.Timeout;

        // Create the CTS before the initial SendAsync so that the SendAsync counts against the timeout.
        CancellationTokenSource? linkedCTS = null;
        if (timeout != Timeout.InfiniteTimeSpan)
        {
            linkedCTS = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
            linkedCTS.CancelAfter(timeout);
        }

        Task<HttpResponseMessage> responseTask;
        try
        {
            // Intentionally using cancellationToken instead of the linked one 
            // here as HttpClient will enforce the Timeout on its own for this part
            responseTask = client.GetAsync(
                CreateUri(requestUri), HttpCompletionOption.ResponseHeadersRead, cancellationToken);
        }
        catch
        {
            linkedCTS?.Dispose();
            throw;
        }

        using HttpResponseMessage response = await responseTask.ConfigureAwait(false);
        response.EnsureSuccessStatusCode();

        using Stream contentStream =
            await response.Content
                .ReadAsStreamAsync(cancellationToken)
                .ConfigureAwait(false);

        await foreach (TValue? value in JsonSerializer.DeserializeAsyncEnumerable<TValue>(
            contentStream, options, cancellationToken).ConfigureAwait(false))
        {
            yield return value;
        }
    }

    private static Uri? CreateUri(string? uri) =>
       string.IsNullOrEmpty(uri) ? null : new Uri(uri, UriKind.RelativeOrAbsolute);
}

I'd love to be the one to implement this, if it's approved.

API Usage

// Imagine an ASP.NET Core Minimal API that returns an IAsyncEnumerable<T> where T is a `TimeSeries`.
public record class TimeSeries(string Name, DateTime dateTime, decimal Value);

// Imagine that this is the consuming code.
HttpClient client = new();
await foreach (var timeSeries in client.GetFromJsonAsAsyncEnumerable<TimeSeries>("api/streaming/endpoint"))
{
    // Use timeSeries values
}

Alternative Designs

No response

Risks

No response

[ghost]

Tagging subscribers to this area: @dotnet/ncl
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

As of .NET 8 preview 5, there are various extension methods within the System.Net.Http.Json namespace (specifically the System.Net.Http.Json NuGet package 📦) that expose JSON-centric functionality to conveniently encapsulate common workflows. Such as, but not limited to extending the HttpClient:

• GetFromJsonAsync
• PostAsJsonAsync
• PutAsJsonAsync
• PatchAsJsonAsync
• DeleteFromJsonAsync

All of these APIs are Task-like returning, i.e.; either Task<T> or ValueTask<T> However, there are no extension methods for some of the streaming APIs, IAsyncEnumerable<T>.

API Proposal

namespace System.Net.Http.Json;

public static partial class HttpClientJsonExtensions
{
    static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }
}

API Usage

// Imagine an ASP.NET Core Minimal API that returns an IAsyncEnumerable<T> where T is a `TimeSeries`.
public record class TimeSeries(string Name, DateTime dateTime, decimal Value);

// Imagine that this is the consuming code.
HttpClient client = new();
await foreach (var timeSeries in client.GetFromJsonStreamAsync<TimeSeries>("api/streaming/endpoint"))
{
    // Use timeSeries values
}

Alternative Designs

No response

Risks

No response

Author:	IEvangelist
Assignees:	-
Labels:	api-suggestion, area-System.Net.Http
Milestone:	-

[ghost]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

As of .NET 8 preview 5, there are various extension methods within the System.Net.Http.Json namespace (specifically the System.Net.Http.Json NuGet package 📦) that expose JSON-centric functionality to conveniently encapsulate common workflows. Such as, but not limited to extending the HttpClient:

• GetFromJsonAsync
• PostAsJsonAsync
• PutAsJsonAsync
• PatchAsJsonAsync
• DeleteFromJsonAsync

All of these APIs are Task-like returning, i.e.; either Task<T> or ValueTask<T> However, there are no extension methods for some of the streaming APIs, IAsyncEnumerable<T>.

API Proposal

namespace System.Net.Http.Json;

public static partial class HttpClientJsonExtensions
{
    static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }
}

This would essentially encapsulate the following logic:

public static class HttpRequestJsonExtensions
{
    public static async IAsyncEnumerable<TValue?> GetFromJsonStreamAsync<TValue>(
        this HttpClient client, 
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri, 
        JsonSerializerOptions? options, 
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        ArgumentNullException.ThrowIfNull(client);

        TimeSpan timeout = client.Timeout;

        // Create the CTS before the initial SendAsync so that the SendAsync counts against the timeout.
        CancellationTokenSource? linkedCTS = null;
        if (timeout != Timeout.InfiniteTimeSpan)
        {
            linkedCTS = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
            linkedCTS.CancelAfter(timeout);
        }

        // We call SendAsync outside of the async Core method to propagate exception even without awaiting the returned task.
        Task<HttpResponseMessage> responseTask;
        try
        {
            // Intentionally using cancellationToken instead of the linked one here as HttpClient will enforce the Timeout on its own for this part
            responseTask = client.GetAsync(CreateUri(requestUri), HttpCompletionOption.ResponseHeadersRead, cancellationToken);
        }
        catch
        {
            linkedCTS?.Dispose();
            throw;
        }

        using HttpResponseMessage response = await responseTask.ConfigureAwait(false);
        response.EnsureSuccessStatusCode();

        using Stream contentStream =
            await response.Content
                .ReadAsStreamAsync(cancellationToken)
                .ConfigureAwait(false);

        await foreach (TValue? value in JsonSerializer.DeserializeAsyncEnumerable<TValue>(contentStream, options, cancellationToken).ConfigureAwait(false))
        {
            yield return value;
        }
    }

    private static Uri? CreateUri(string? uri) =>
       string.IsNullOrEmpty(uri) ? null : new Uri(uri, UriKind.RelativeOrAbsolute);
}

I'd love to be the one to implement this, if it's approved.

API Usage

// Imagine an ASP.NET Core Minimal API that returns an IAsyncEnumerable<T> where T is a `TimeSeries`.
public record class TimeSeries(string Name, DateTime dateTime, decimal Value);

// Imagine that this is the consuming code.
HttpClient client = new();
await foreach (var timeSeries in client.GetFromJsonStreamAsync<TimeSeries>("api/streaming/endpoint"))
{
    // Use timeSeries values
}

Alternative Designs

No response

Risks

No response

Author:	IEvangelist
Assignees:	-
Labels:	api-suggestion, area-System.Text.Json, untriaged
Milestone:	-

[eiriktsarpalis]

I think it's something we could consider for GET and maybe POST, but not PUT, PATCH or DELETE since these typically don't produce responses that could be streamed. We should also include an overload accepting JsonTypeInfo for AOT apps:

public static partial class HttpClientJsonExtensions
{
    public static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default) { }
}

[IEvangelist]

Per request by @eiriktsarpalis, here is a POC branch, and the commit with the proposed additions: main...IEvangelist:runtime:streaming-json-http-apis.

[eiriktsarpalis]

Looks good overall, couple of remarks:

1. Looking at the existing GetFromJsonAsync overloads it seems we also need a JsonSerializerContext overload for consistency?
2. Following naming convention from the JsonSerializer class, I think the new method group should be called GetFromJsonAsAsyncEnumerable.

[IEvangelist]

I've updated my POC branch, and the API proposal description with the suggested names. As for the JsonSerializerContext overloads, those are specifically on the object? overloads which don't feel appropriate here.

[dersia]

I think it's something we could consider for GET and maybe POST, but not PUT, PATCH or DELETE since these typically don't produce responses that could be streamed. We should also include an overload accepting JsonTypeInfo for AOT apps:

public static partial class HttpClientJsonExtensions
{
    public static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default) { }

    public static IAsyncEnumerable<TValue> GetFromJsonStreamAsync<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default) { }
}

Although I agree, that PUT, PATCH and DELETE shouldn't produce output, I have seen too many projects where those endpoints still create stream able output. So I would suggest to add those for completion.

[terrajobst]

Video

• Makes sense as proposed
  • We believe the other verbs POST, PUT, DELETE are less useful. Users can dispatch to the extension methods on the HttpContent.

namespace System.Net.Http.Json;

public static partial class HttpClientJsonExtensions
{
    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        JsonSerializerOptions? options,
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        JsonTypeInfo<TValue> jsonTypeInfo,
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        [StringSyntax(StringSyntaxAttribute.Uri)] string? requestUri,
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<TValue?> GetFromJsonAsAsyncEnumerable<TValue>(
        this HttpClient client,
        Uri? requestUri,
        CancellationToken cancellationToken = default);
}
public static partial class HttpContentJsonExtensions
{
    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content, 
        JsonSerializerOptions? options, 
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content, 
        CancellationToken cancellationToken = default);

    public static IAsyncEnumerable<T?> ReadFromJsonAsAsyncEnumerable<T>(
        this HttpContent content,
        JsonTypeInfo<T> jsonTypeInfo,
        CancellationToken cancellationToken = default);
}