Add Results.Stream overload that takes a Func<Stream, Task>

[davidfowl]

Background and Motivation

There are scenarios where APIs want to work directly on the response stream without buffering. Today the Stream overloads assume you have a stream that you have produced that is then copied to the underlying response stream, instead, we want to provide a result type that gives you access to the underlying response stream.

Example:

https://github.com/khalidabuhakmeh/dotnet-dramameter/blob/main/DramaMeter/Program.cs#L37-L43

Another is writing a blob storage results to the http response.

Proposed API

namespace Microsoft.AspNetCore.Http
{
    public static class Results
    {
+       public IResult Stream(Func<Stream, Task> streamWriterCallback, 
+                             string? contentType = null,
+                             string? fileDownloadName = null,
+                             DateTimeOffset? lastModified = null,
+                             EntityTagHeaderValue? entityTag = null,
+                             bool enableRangeProcessing = false);
    }
}

Usage Examples

app.MapGet("/", async (HttpContext http, string? level) => {
    level ??= "low";

    if (!levels.TryGetValue(level.Trim(), out var result))
        return Results.BadRequest("invalid level");

    var image = background.CloneAs<Rgba32>();
    image.Mutate(ctx => {
        ctx.Vignette(result.color); // match the background to the intensity
        ctx.DrawImage(foreground, new Point(0, 0), 1f);
        ctx.DrawImage(result.image, new Point(0, 0), opacity: 1f);
    });
    
    http.Response.Headers.CacheControl = $"public,max-age={FromHours(24).TotalSeconds}";
    return Results.Stream(stream => image.SaveAsync(stream, PngFormat.Instance), "image/png");
});

Risks

None

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.

[pranavkm]

- Func<Stream, Task> streamFactory
+Func<Stream, Task> writeHttpResponseStreamAsync,

or something like that. I think we'd spoken about this API when reviewing the Results type but left it alone at that time to get feedback. Also I think we should try and keep some parity between this and the API in controllers to allow users to migrate from one to another without too much effort (in particular since it's low cost for us to add support)

Thanks for contacting us.

We're moving this issue to the .NET 7 Planning milestone for future evaluation / consideration. We would like to keep this around to collect more feedback, which can help us with prioritizing this work. We will re-evaluate this issue, during our next planning meeting(s).
If we later determine, that the issue has no community involvement, or it's very rare and low-impact issue, we will close it - so that the team can focus on more important and high impact issues.
To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[pranavkm]

API review:

We decided to add a few more overloads during review.

public class Results
{

+ public IResult Stream(
+     Func<Stream, Task> streamWriterCallback, 
+     string? contentType = null,
+     string? fileDownloadName = null,
+     DateTimeOffset? lastModified = null,
+     EntityTagHeaderValue? entityTag = null,
+     bool enableRangeProcessing = false);

+ public IResult Stream(
+     PipeReader pipeReader, 
+     string? contentType = null,
+     string? fileDownloadName = null,
+     DateTimeOffset? lastModified = null,
+     EntityTagHeaderValue? entityTag = null,
+     bool enableRangeProcessing = false);


+ public IResult Stream(
+     Func<PipeWriter, Task> pipeWriterCallback, 
+     string? contentType = null,
+     string? fileDownloadName = null,
+     DateTimeOffset? lastModified = null,
+     EntityTagHeaderValue? entityTag = null,
+     bool enableRangeProcessing = false);


+ public IResult Bytes(
+     ReadOnlyMemory<byte> byteBuffer, 
+     string? contentType = null,
+     string? fileDownloadName = null,
+     bool enableRangeProcessing = false,
+     DateTimeOffset? lastModified = null,
+     EntityTagHeaderValue? entityTag = null);
}

public class ControllerBase
{
+  public PushFileStreamResult File(
+      Func<Stream, Task> streamWriterCallback, 
+      string? contentType = null,
+      string? fileDownloadName = null,
+      DateTimeOffset? lastModified = null,
+      EntityTagHeaderValue? entityTag = null,
+      bool enableRangeProcessing = false);

// This needs to add a remark that the byte buffer
// should not use a pooled source since it's lifetime
// isn't tied to the action result execution.
// Accessing FileContentResult.FileContents should copy the results from the memory
+ public FileContentResult File(
+     ReadOnlyMemory<byte> fileContents, 
+     string? contentType = null,
+     string? fileDownloadName = null,
+     bool enableRangeProcessing = false,
+     DateTimeOffset? lastModified = null,
+     EntityTagHeaderValue? entityTag = null);

+ public class PushFileStreamResult : FileResult
+ {
+    public Func<Stream, Task> StreamWriterCallback { get; set; }
+ }
}


We should also add PipeReader / PipeWriter overloads for controllers. @rafikiassumani-msft could we have someone propose the API for this and bring it to review?

[davidfowl]

I just tried to implement this and the overloads conflicts because of how we use optional parameters... We might need to rename these or find a clever workaround.

[davidfowl]

Actually this is fine, it's just the API analyzer complaining.