Add API to help set and revert response bodies

[davidfowl]

Background and Motivation

A very common pattern in ASP.NET Core middleware (and other middleware like components) is to set a temporary response body, execute some user code, then revert to the previous response body when unwinding. The steps go like this:

• Store a reference to the existing body
• Replace the body with the new stream
• Execute user code
• Grab the contents of the body stream and copy it to the previous stream
• Restore the previous body in a finally so exceptional cases are handled
• Don't forget to dispose any streams created

app.Use(async (context, next) =>
{
    var previous = context.Response.Body;
    try
    {
        using var stream = new FileBufferingWriteStream();
        context.Response.Body = stream;
        await next();
        await stream.CopyToAsync(previous);
    }
    finally
    {
         context.Response.Body = previous;
    }  
});

This code today is very manual and we could instead make it a bit more pleasant with some new APIs.

Proposed API

Please provide the specific public API signature diff that you are proposing. For example:

namespace Microsoft.AspNetCore.Http
{
    public class HttpResponse
    {
+      public ResponseBodyScope UseBody(Stream stream);
    }
    
+    public struct ResponseBodyScope : IDisposable, IAsyncDisposable
+    {
+         public Stream PreviousBody { get; }
+         public Stream CurrentBody { get; }
+         public void Dispose();
+         public ValueTask DisposeAsync();
+    }
}

Usage Examples

app.Use(async (context, next) =>
{
    using var scope = context.Response.UseBody(new FileBufferingWriteStream());
    await next();
    await scope.CurrentBody.CopyToAsync(scope.PreviousBody);
});

Alternative Designs

An alternative might be an explicit push/pop style API but that wouldn't automagically handle the pop in the failure case.

We may also want to consider a mode that auto-flushes to the previous response body but then failure cases also get weird (did you want to flush the response on failure?)

[Tratcher]

🚲: This temporarily replaces the response body that other APIs will write to. We want to avoid people confusing this with an API that would send content (e.g. UseBody(new FileStream("myFileToSend")).
SwapBody, SubstituteBody, SwapOutput, RedirectBody, RedirectOutput, UseOutput, ...

Don't forget to rewind.

scope.CurrentBody.Position = 0;
await scope.CurrentBody.CopyToAsync(scope.PreviousBody);

[davidfowl]

The fact that it's not async means it doesn't send content 😅

[jkotalik]

ReplaceBody?

Also, Pipes?

[davidfowl]

The pipe API isn't settable today and this isn't possible today. We could consider it though.

[mkArtakMSFT]

Holding on to this one for now since there is no clear value add at the moment and there is no clear customer-ask for this one.

[pranavkm]

API review feedback:

namespace Microsoft.AspNetCore.Http
{
    public class HttpResponse
    {
+      public ResponseBodyScope BeginBodyScope(Stream stream);
+      public ResponseBodyScope BeginBodyScope(PipeWriter writer);
    }
    
+    public readonly struct ResponseBodyScope : IDisposable
+    {
+         public Stream PreviousStream { get; }
+         public PipeWriter PreviousWriter { get; }
+         public void Dispose();
+    }
}

Usage

app.Use(async (context, next) =>
{
    async using var stream = new FileBufferingWriteStream();
    using var scope = context.Response.BeginBodyScope(stream);
    await next();
    stream.Position = 0;
    await stream.CopyToAsync(scope.PreviousStream);
});

app.Use(async (context, next) =>
{
    var pipe = new Pipe();
    using var scope = context.Response.BeginBodyScope(pipe.Writer);
    await next();
    await pipe.Writer.CompleteAsync();
    await pipe.Reader.CopyToAsync(scope.PreviousWriter);
    await pipe.Reader.CompleteAsync();
});