Provide a way to get a PipeReader from a ReadOnlySequence<byte>

[Alxandr]

Background and Motivation

Sometimes you have data available in memory (either already downloaded or read from file or generated by your process), represented as a ReadOnlySequence<byte> (which may or may not be a single contiguous Span<byte>), and you need to feed that into an API that expects a PipeReader. This is basically the same usecase as a MemoryStream over a byte[], except it's in the new APIs of Pipes and ReadOnlySequence<byte>s. The exact signature for this API isn't too terribly important (wether it's an extension method on ReadOnlySequence<byte>, an overload of PipeReader.Create or new MemoryPipeReader(sequence)), since this template requires a proposed API, I will be writing the static Create, as that is closest to what exist for Stream.

Proposed API

namespace System.IO.Pipelines
{
    public abstract class PipeReader
    {
+       public static PipeReader Create(ReadOnlySequence<byte> sequence);

Usage Examples

var data = GenerateDataAsSequence();
var obj = await DeserializeAsync(PipeReader.Create(data));

Alternative Designs

Using the package Nerdbank.Streams, it's possible to achieve a similar result going through a Stream;

var data = GenerateDataAsSequence();
var obj = await DeserializeAsync(PipeReader.Create(data.AsStream()));

Alternatively, the fake "generate" method here needs to be rewritten to take a writer:

var pipe = new Pipe();
var task = GenerateDataIntoPipe(pipe.Writer);
var obj = await DeserializeAsync(pipe.Reader);
await task;

While this is probably the better solution in many cases, you don't always have access to rewrite the APIs that generate the data.

Risks

The only risk I can see is an expanded API surface area to teach/maintain.

[BrennanConroy]

Triage: This would definitely make some of the tests in AspNetCore nicer.

You should be able to write an extension method for this and party on that.

[Alxandr]

I have written one of these for our tests actually, however it contains some extra features for testing purposes, like being able to simulate "network delays" (not actual delays, but how the data is split up for the reads). I use this to test APIs that consume PipeReaders to ensure they are agnostic with regards to where any buffer boundaries ends up being, so I run tests with a few different strategies ranging from "give all data on the first read" to "give a single byte more for every call to read". That's very useful for testing, this however I imagine would be useful whenever you have a data in memory already (for instance if you've downloaded a pipe already, and want to reuse the data somewhere that expects a pipe).

[davidfowl]

I think the API as proposed is good, I don't think it should be an extension method as the pattern we have so far introduced is a factory method.

[davidfowl]

@Alxandr once the API is approved would you be OK doing the work?

[Alxandr]

I could probably do that, sure :).

[terrajobst]

Video

• We could also overloads to create a reader straight from a byte[] or ReadOnlyMemory<byte> but those can be constructed by creating a sequence, so we can add them later if we think that's common enough.
• We don't believe this method needs any options

namespace System.IO.Pipelines
{
    public abstract class PipeReader
    {
        public static PipeReader Create(ReadOnlySequence<byte> sequence);
    }
}

[davidfowl]

@Alxandr the API's been approved! Have at it. I'll gladly review the implementation.