WebSocket keep-alive timeout API

[BrennanConroy]

Background and Motivation

dotnet/runtime is adding an API to control the keep-alive timeout see dotnet/runtime#48729 (comment)
Our WebSocket middleware exposes options to control the websocket options being used so we would want to expose an equivalent option.

Proposed API

namespace Microsoft.AspNetCore.Builder;

public class WebSocketOptions
{
    public TimeSpan KeepAliveInterval { get; set; }
+   public TimeSpan KeepAliveTimeout { get; set; }
}

Usage Examples

builder.AddWebSockets(o =>
{
    o.KeepAliveTimeout = TimeSpan.FromMinutes(1);
});

Alternative Designs

Risks

[dotnet-policy-service]

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.

[amcasey]

What's the distinction between KeepAliveInterval and KeepAliveTimeout?

[BrennanConroy]

KeepAliveInterval determined how often a Pong is sent to the other side. However, with the introduction of KeepAliveTimeout, if the value of KeepAliveTimeout is non-zero and non-infinite then KeepAliveInterval is how often a Ping is sent, and KeepAliveTimeout is how long we wait for a Pong response before closing the connection due to a timeout.

[amcasey]

Background: a Pong is a Ping for which no response/acknowledgement is expected

To paraphrase:

A KeepAliveInterval of 5 seconds with no (i.e. zero or infinite) KeepAliveTimeout means "send a Pong every 5 seconds".

A KeepAliveInterval of 5 seconds with a KeepAliveTimeout of 1 second means "send a Ping every 5 seconds and kill the connection if any ping acknowledgement (i.e. Pong) takes more than 1 second".

Is that right?

[amcasey]

I think another way to look at it would be that a keep alive frame with no timeout has no reason to look for a response, so it degrades from a Ping to a Pong?

[amcasey]

• What are the default values?
  • We can, but don't have to, use the same ones as runtime
• We also have KestrelServerLimits.KeepAliveTimeout
  • It doesn't accept 0
  • It defaults to 130 seconds
• What value do we use to express that there is no timeout?
  • MaxValue?
  • 0?
  • Timeout.InfiniteTimeSpan?
• Validate with a test that passing MaxValue doesn't break things (regardless of whether it means no timeout)
• A comment on the runtime PR suggests it was Ping before it was Pong

namespace Microsoft.AspNetCore.Builder;

public class WebSocketOptions
{
    public TimeSpan KeepAliveInterval { get; set; }
+   public TimeSpan KeepAliveTimeout { get; set; }
}

API Approved!

[BrennanConroy]

While implementing this we realized we should add the option to WebSocketAcceptContext as well.
Additional API below:

public class WebSocketAcceptContext
{
     public virtual TimeSpan? KeepAliveInterval { get; set; }
+    public TimeSpan? KeepAliveTimeout { get; set; }
}

The reason for nullability is so we can choose the “global” value from WebSocketOptions instead when null. And the reason it’s not virtual when the KeepAliveInterval is, is due to legacy reasons where we have a ExtendedWebSocketAcceptContext type that implements WebSocketAcceptContext but it is now obsolete and we’ve moved away from that concept.

builder.AddWebSockets(o =>
{
    o.KeepAliveTimeout = TimeSpan.FromMinutes(1);
});

var app = builder.Build();
app.UseWebSockets();

app.Use(async (context, next) =>
{
    if (context.WebSockets.IsWebSocketRequest)
    {
        var webSocket = await context.WebSockets.AcceptWebSocketAsync(new WebSocketAcceptContext()
        {
            KeepAliveTimeout = TimeSpan.FromSeconds(2)
        });

        // websocket send/receive

        return;
    }

    await n(c);
});