[API Proposal]: WebSockets over HTTP/2

[greenEkatherine]

Background and motivation

Currently we are supporting WebSockets over HTTP/1.1 only. For WebSockets over HTTP/2 the protocol is quite different and described by RFC #8441. It is already supported by Chrome and there are an interest from YARP and ASP.NET partners. The main improvement is that supporting WebSockets over HTTP/2 will give advantage of multiplexing connection.

API Proposal

    // EXISTING
    class ClientWebSocket : WebSocket
    {
        // EXISTING
        public Task ConnectAsync(Uri uri, CancellationToken cancellationToken);
        // NEW
        public Task ConnectAsync(Uri uri, HttpMessageInvoker invoker, CancellationToken cancellationToken);
    }

    // EXISTING
    class ClientWebSocketOptions
    {
        // NEW
        public System.Version HttpVersion { get { throw null; } 
            [System.Runtime.Versioning.UnsupportedOSPlatformAttribute("browser")]
            set { } };
        public System.Net.Http.HttpVersionPolicy HttpVersionPolicy { get { throw null; } 
           [System.Runtime.Versioning.UnsupportedOSPlatformAttribute("browser")]
           set { } };
    }
    
    class HttpMethod : IEquatable<HttpMethod>
    {
        // EXISTING
        // internal static HttpMethod Connect { get { throw null; } }
        // NEW
        public static HttpMethod Connect { get { throw null; } }
    }

    class HttpRequestHeaders : HttpHeaders
    {
        public string? Protocol { get { } set { } };
    }

API Usage

var handler = new SocketsHttpHandler();

ClientWebSocket ws = new();
ws.Options.HttpVersionPolicy = HttpVersionPolicy.RequestVersionOrHigher;
ws.Options.HttpVersion = HttpVersion.Version20;

ws.ConnectAsync(uri, new HttpMessageInvoker(handler), cancellationToken);

HttpRequestMessage request = new(HttpMethod.Connect, server.Address);
request.Headers.Protocol = "websocket";

Notes

• HttpVersion and HttpVersionPolicy in ClientWebSocketOptions are similar to HttpClient's property. ClientWebSocketOptions for browser is a class with completely different properties, so the new properties don't affect it.

• Providing an external handler to ClientWebSocket is important because it enables advantage of HTTP/2 multiplexing by reusing the same handler for other ordinary HTTP/2 streams. Generic handler HttpMessageInvoker in ConnectAsync is a better alternative than SocketsHttpHandler. There is no need to check that it is SocketsHttpHandler but it should be able to handle WebSocket requests and it is up to the user who provides it.

• The property for the :protocol header in HttpRequestHeaders is required because we need to guarantee that pseudo headers are appeared before all regular headers based on spec.

Other alternatives considered, but rejected:

• Pass a low-level SocketsHttpHandler instead of HttpMessageInvoker.
• Only one property HttpVersion if we do not require downgrade handling. In that case we rely on the version the user provides.

Risks

Adding new fields might increase memory usage.

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

Issue Details

---

Background and motivation

Currently we are supporting WebSockets over HTTP/1.1 only. For WebSockets over HTTP/2 the protocol is quite different and described by RFC #8441. It is already supported by Chrome and there are an interest from YARP and ASP.NET partners. The main improvement that sup-porting WebSockets over HTTP/2 will give advantage of multiplexing connection.

API Proposal

    // EXISTING
    class ClientWebSocket : WebSocket
    {
        // NEW
        public System.Version DefaultRequestVersion { get { throw null; } set { } };
        public System.Net.Http.HttpVersionPolicy DefaultVersionPolicy { get { throw null; } set { } };

        // EXISTING
        public Task ConnectAsync(Uri uri, CancellationToken cancellationToken);
        // NEW
        public Task ConnectAsync(Uri uri, CancellationToken cancellationToken, SocketsHttpHandler sharedHandler);
    }


### API Usage

```csharp
var handler = new SocketsHttpHandler();

ClientWebSocket ws = new();
ws.DefaultVersionPolicy = HttpVersionPolicy.RequestVersionOrHigher;
ws.DefaultRequestVersion = HttpVersion.Version20;

ws.ConnectAsync(uri, cancellationToken, handler);

Alternative Designs

We may consider only one property DefaultRequestVersion if we do not require downgrade handling. In that case we rely on the version the user provides.

Risks

Adding new fields into ClientWebSocket object will increase memory usage.

Author:	greenEkatherine
Assignees:	-
Labels:	api-suggestion, area-System.Net, untriaged
Milestone:	-

[greenEkatherine]

Internal Changes

ClientWebSocket

To make downgrade for WebSocket from HTTP/2 to HTTP/1.1 possible we need to add additional header with the key because we cannot generate it later in HttpClient. Other headers can be easily added and renamed to construct HTTP/1.1 WebSocket connection request from HTTP/2 ws request.
HTTP/2 example:

HTTP/1.1 example:

HttpConnectionPool

Since YARP is using SocketsHttpHandler directly, we need to handle downgrade (if we decide to allow it) inside the HttpConnectionPool. It will check the new setting ID of the Http2Connection EnableConnect -- based on the server response.

To make things easier we also should consider the new property IsWebSocketRequest of HttpRequestMessage. It will check headers once to confirm that it is a websocket request (either h1 or h2) and we will not need to do it few times during downgrade.

[stephentoub]

public System.Version DefaultRequestVersion { get { throw null; } set { } };
public System.Net.Http.HttpVersionPolicy DefaultVersionPolicy { get { throw null; } set { } };

Why "default"? We typically use that for statics providing a default value for any instance, but that's apparently not the case here.

    public Task ConnectAsync(Uri uri, CancellationToken cancellationToken, SocketsHttpHandler sharedHandler);

This is concerning. It ties ClientWebSocket to the underlying implementation that should be used. ClientWebSocket has historically used HttpWebRequest, WinHttpHandler, and SocketsHttpHandler, and even today has a browser-based implementation for wasm.

[CarnaViire]

RequestVersion and VersionPolicy for connect request might look better as a part of ClientWebSocketOptions. But we might also want to have an additional HttpVersion property on ClientWebSocket itself if we support downgrade (so we could know what exactly was established)

[MihaZupan]

It will check the new setting ID of the Http2Connection EnableConnect

Can you elaborate on what you meant here?

To make downgrade for WebSocket from HTTP/2 to HTTP/1.1 possible we need to add additional header with the key because we cannot generate it later in HttpClient. Other headers can be easily added and renamed to construct HTTP/1.1 WebSocket connection request from HTTP/2 ws request.

Would the downgrade be handled by the WebSocket layer (i.e. calling into the handler multiple times)?
Or did you mean that Websockets would be a special case the handler recognized to adapt headers as needed?

[CarnaViire]

Would the downgrade be handled by the WebSocket layer (i.e. calling into the handler multiple times)?
Or did you mean that Websockets would be a special case the handler recognized to adapt headers as needed?

I believe both alternatives are considered, but for YARP it will be better if it was handled by HTTP layer

[greenEkatherine]

I agree with @stephentoub and @CarnaViire suggestions to rename policy and version properties and move it into ClientWebSocketOptions:

    // EXISTING
    class ClientWebSocketOptions
    {
        // NEW
        public System.Version RequestVersion { get { throw null; } set { } };
        public System.Net.Http.HttpVersionPolicy VersionPolicy { get { throw null; } set { } };
    }

Would using HttpClient be better from that perspective?

    public Task ConnectAsync(Uri uri, CancellationToken cancellationToken, SocketsHttpHandler sharedHandler);

This is concerning. It ties ClientWebSocket to the underlying implementation that should be used. ClientWebSocket has historically used HttpWebRequest, WinHttpHandler, and SocketsHttpHandler, and even today has a browser-based implementation for wasm.

Providing an external handler is a keypoint here because in that case we are able to take advantage of HTTP/2 multiplexing by reusing the same handler for other ordinary HTTP/2 streams.

[stephentoub]

Providing an external handler is a keypoint here because in that case we are able to take advantage of HTTP/2 multiplexing by reusing the same handler for other ordinary HTTP/2 streams.

Understood. It doesn't change it being problematic, though. What happens if we decide we no longer want ClientWebSocket to be implemented with SocketsHttpHandler (which is an implementation detail, and which isn't even used in all builds)? That's not theoretical; we've already made such a change at least twice before with this type.

We should think through alternatives. If we ship the proposed API, that's it, forever-more this is implemented with SocketsHttpHandler.

[greenEkatherine]

It will check the new setting ID of the Http2Connection EnableConnect

Can you elaborate on what you meant here?

Based on the https://datatracker.ietf.org/doc/html/rfc8441#section-3 we should add a new SETTINGS parameter that a server sends to a client. My suggestion is to add a new property into Http2Connection to indicate this setting, so the HttpConnectionPool would be able to check its value of a connection and perform downgrade if needed.

[Tratcher]

    public Task ConnectAsync(Uri uri, CancellationToken cancellationToken, SocketsHttpHandler sharedHandler);

This is concerning. It ties ClientWebSocket to the underlying implementation that should be used. ClientWebSocket has historically used HttpWebRequest, WinHttpHandler, and SocketsHttpHandler, and even today has a browser-based implementation for wasm.

It should at least be a HttpMessageInvoker.