[API Proposal]: Add APIs to WebSocket which allow it to be read as a Stream

[christothes]

UPD 17-06-2025 by @CarnaViire
Updated API shape for the second review round:

namespace System.Net.WebSockets;

public class WebSocketStream : Stream
{
    internal WebSocketStream();

    public WebSocket WebSocket { get; }

    public static WebSocketStream Create(
        WebSocket webSocket,
        WebSocketMessageType writeMessageType,
        bool ownsWebSocket = false); // if ownsWebSocket == true, (default) closeTimeout = 60s

    public static WebSocketStream Create( // implicit ownsWebSocket = true
        WebSocket webSocket,
        WebSocketMessageType writeMessageType,
        TimeSpan closeTimeout); // if closeTimeout == 0, Dispose aborts the WebSocket

    public static WebSocketStream CreateWritableMessageStream(
        WebSocket webSocket,
        WebSocketMessageType writeMessageType);

    public static WebSocketStream CreateReadableMessageStream(WebSocket webSocket);

    ... // relevant Stream overrides
}

⤵️ Diff from the previous version

Previous (approved) version: #111217 (comment)

public class WebSocketStream : Stream
{
    internal WebSocketStream();

    public WebSocket WebSocket { get; }

    public static WebSocketStream Create(
        WebSocket webSocket,
+       WebSocketMessageType writeMessageType,
        bool ownsWebSocket = false);

+   public static WebSocketStream Create(
+       WebSocket webSocket,
+       WebSocketMessageType writeMessageType,
+       TimeSpan closeTimeout);

    public static WebSocketStream CreateWritableMessageStream(
        WebSocket webSocket,
+       WebSocketMessageType writeMessageType);

    public static WebSocketStream CreateReadableMessageStream(WebSocket webSocket);

    ... // relevant Stream overrides
}

⤵️ Usage examples

1. Duplex stream, continuously reading/writing Text data without frame alignment (e.g. STOMP)

using Stream transportStream = WebSocketStream.Create(connectedWebSocket, WebSocketMessageType.Text, ownsWebSocket: true);
// ...
await frame.SerializeToStreamAsync(transportStream, token); // integration with Stream-based APIs
// ...
using var transportReader = new StreamReader(transportStream, leaveOpen: true); // seamless UTF-8 conversion for text
var line = await transportReader.ReadLineAsync(cancellationToken);              // protocols with new line separators
// ...

2. Duplex stream, continuously reading/writing Binary data without frame alignment (e.g. AMQP)

// using Stream transportStream = new NetworkStream(tcpSocket, ownsSocket: true); // stream as an easy transport abstraction
using Stream transportStream = WebSocketStream.Create(connectedWebSocket, WebSocketMessageType.Binary, closeTimeout: TimeSpan.FromSeconds(10));
// ...
await transportStream.WriteAsync(sendPayload, cancellationToken);
// ...
var receivePayload = new byte[payloadLength];
await transportStream.ReadExactlyAsync(receivePayload, cancellationToken); // convenience methods

3. Single message read stream, parsing Json

using Stream messageStream = WebSocketStream.CreateReadableMessageStream(connectedWebSocket, WebSocketMessageType.Text);
var appMessage = await JsonSerializer.DeserializeAsync<AppMessage>(messageStream); // DeserializeAsync reads until EOS

4. Single message write stream, binary serialization

public async Task SendMessageAsync(AppMessage message, CancellationToken cancellationToken)
{
    using Stream messageStream = WebSocketStream.CreateWritableMessageStream(_connectedWebSocket, WebSocketMessageType.Binary);
    foreach (ReadOnlyMemory<byte> chunk in message.SplitToChunks())
    {
        await messageStream.WriteAsync(chunk, cancellationToken);
    }
} // implicit EOM sent on messageStream.Dispose()

---

EDITED by @stephentoub 4/7/2025 to add API for review:

+public sealed class WebSocketStream : Stream
+{
+    public WebSocketStream(WebSocket webSocket, bool ownsWebSocket = false);
+    public WebSocket WebSocket { get; }
+
+    ... // relevant Stream overrides
+}

Open questions:

• Name and polarity of the boolean. NetworkStream uses ownsSocket = false, but while it's the closest in relation to this class, it's also fairly unique i this approach. Most other .NET types use leaveOpen = false.
• There's a possible further designed expansion, where you could create a Stream to represent writing out a single message in parts, in which case all writes on the stream would be with EndOfMessage:false and then closing the stream would output an empty message with EndOfMessage:true. If we add that subsequently, how would we want it to show up? Should we instead have a factory method WebSocketStream.Create, and then later add a WebSocketStream.CreateMessage?

---

Background and motivation

Utilizing WebSockets is a convenient approach to writing real-time audio processing code for ASP.NET applications. One such scenario is implementing a real-time conversation with Open AI.

OpenAI's real-time API SendInputAudioAsync accept a Stream as input which leaves it up to the developer to write a custom Stream implementation that reads from an underlying WebSocket. It would be a nice enhancement to the WebSocket APIs if one could wrap read operations in a Stream.

API Proposal

public class WebSocket
{
    public Stream AsStream();
}

API Usage

using var webSocket = await context.WebSockets.AcceptWebSocketAsync();
using RealtimeConversationSession session = await InitSession(realtime);
// <...>
using var stream = webSocket.AsStream();
await session.SendInputAudioAsync(stream);

Alternative Designs

No response

Risks

WebSocket doesn’t provide synchronous methods for wire-based operations, so all of the Stream sync APIs (including Dispose, which presumably would need to not just Dispose the WebSocket but also CloseAsync it) would be sync-over-async.

[dotnet-policy-service]

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

[MihaZupan]

It's an interesting idea, though its use seems limited only to cases where you know that only the binary content is being transmitted (e.g. only the audio, no control data, no extra framing).
There's also the question of what happens with close messages -- does the user not care about the data, who's responsible for responding to them, do you send them during disposal.

I can see it being useful in cases where you just need an opaque Stream and happen to be using WebSocket as the transport.

Sample code if someone needed such a Stream could be something like this (untested):

public sealed class WebSocketStream : Stream
{
    private readonly WebSocket _webSocket;

    public WebSocketStream(WebSocket webSocket) => _webSocket = webSocket;

    public override bool CanRead => _webSocket.State is WebSocketState.Open or WebSocketState.CloseSent;
    public override bool CanWrite => _webSocket.State is WebSocketState.Open or WebSocketState.CloseReceived;
    public override bool CanSeek => false;

    public override void Flush() { }
    public override Task FlushAsync(CancellationToken cancellationToken) => Task.CompletedTask;

    public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) =>
        ReadAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask();

    public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken) =>
        WriteAsync(buffer.AsMemory(offset, count), cancellationToken).AsTask();

    public override async ValueTask<int> ReadAsync(Memory<byte> buffer, CancellationToken cancellationToken = default)
    {
        ValueWebSocketReceiveResult result = await _webSocket.ReceiveAsync(buffer, cancellationToken);

        if (result.MessageType != WebSocketMessageType.Binary)
        {
            if (result.MessageType == WebSocketMessageType.Close)
            {
                await _webSocket.SendAsync(ReadOnlyMemory<byte>.Empty, WebSocketMessageType.Close, endOfMessage: true, cancellationToken);
                return 0;
            }

            throw new Exception("Expected binary messages");
        }

        return result.Count;
    }

    public override ValueTask WriteAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default) =>
        _webSocket.SendAsync(buffer, WebSocketMessageType.Binary, endOfMessage: true, cancellationToken);

    public override ValueTask DisposeAsync()
    {
        Dispose(true);
        return default;
    }

    protected override void Dispose(bool disposing) => _webSocket.Dispose();

    public override int Read(byte[] buffer, int offset, int count) => ReadAsync(buffer, offset, count).GetAwaiter().GetResult();
    public override void Write(byte[] buffer, int offset, int count) => WriteAsync(buffer, offset, count).GetAwaiter().GetResult();

    public override long Length => throw new NotSupportedException();
    public override long Position { get => throw new NotSupportedException(); set => throw new NotSupportedException(); }
    public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException();
    public override void SetLength(long value) => throw new NotSupportedException();
}

[MihaZupan]

Triage: We see the value and it should be a relatively low amount of work to implement. Even a simple GH search shows many users implementing similar wrappers themselves, moving to 10.0.

We'll have to figure out a default for how we handle things like close messages, but it should otherwise be straightforward.

[CarnaViire]

I think we can also take inspiration from the NetworkStream, which does similar thing for a Socket

[stephentoub]

@antonfirsov, I see you assigned this to yourself in January. Are you working on it? If not, I'd like to push it forward.