Implement portable support for TCP_KEEPCNT, TCP_KEEPIDLE and TCP_KEEPINTVL socket options

[hexawyz]

Allow for configuring TCP Keepalive in a portable manner.

Rationale

TCP Keepalive is an optional feature of TCP that is implemented in most widely used OSes and the feature can already be enabled in .NET by using SocketOptionName.KeepAlive.
However, it is not possible, as of now, to set the various keepalive options using a standard .NET API.

Most platforms, more than simply allowing TCP keepalive, provide a subset of the following three options:

• Keepalive Time
• Keepalive Interval
• Keepalive Retry Count

Since Windows 2000, it has been possible to set both Keepalive Time and Keepalive Interval by using SIO_KEEPALIVE_VALS with Winsock IOCTL (Exposed via Socket.IOControl and IOControlCode.KeepAliveValues in .NET)
Under Linux, TCP Keepalive can be configured with setsockopt under the SOL_TCP level. The allowed parameters are TCP_KEEPCNT, TCP_KEEPIDLE and TCP_KEEPINTVL.

It seems OSX also has some good support for the feature since OSX Lion, only using slightly different names than Linux:
https://lists.apple.com/archives/macnetworkprog/2012/Jul/msg00005.html

From the docs, since Windows 10 version 1703 and 1709, settings that are code-compatible with Linux and OSX were introduced:
https://msdn.microsoft.com/en-us/library/windows/desktop/ms738596(v=vs.85).aspx

As explained in https://github.com/dotnet/corefx/issues/14237, it is impossible today to configure TCP keepalive on platforms other than Windows, where Socket.IOControl can do the trick.

Proposed API

enum SocketOptionName
{
//…
	#region SocketOptionLevel.Tcp
//…
	// TCP KeepAlive options
	TcpKeepAliveRetryCount = 16, // TCP_KEEPCNT value from Ws2ipdef.h
	TcpKeepAliveTime = 3, // TCP_KEEPIDLE = TCP_KEEPALIVE value from Ws2ipdef.h
	TcpKeepAliveInterval = 17, // TCP_KEEPINTVL value from Ws2ipdef.h
	#endregion
//…
}

Example

void EnableKeepAlive(Socket socket, byte retryCount, int keepAliveTimeInSeconds, int keepAliveIntervalInSeconds)
{
	socket.SetSocketOption(SocketOptionLevel.Socket, SocketOptionName.KeepAlive, true);
	socket.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveRetryCount, (int)retryCount);
	socket.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveTime, keepAliveTimeInSeconds);
	socket.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAliveInterval, keepAliveIntervalInSeconds);
}

Details

The PAL for each supported platform would translate the call to Socket.SetSocketOption(SocketOptionLevel.Tcp, SocketOptionName.TcpKeepAlive*, *) into the appropriate call for the platform.

• On Linux, and OSX ≥ 10.7, .NET enumeration values would be translated to corresponding system values for setsockopt().
• On Windows 10 version 1709 and newer, the flags would be transferred as-is to the underlying Winsock API, as they already are today.
• Ideally, TcpKeepAliveTime and TcpKeepAliveInterval would be marshalled to socket.IOControl(IOControlCode.KeepAliveValues, KeepAliveValues, null) for previous versions of windows, while TcpKeepAliveRetryCount would be simply ignored.

⚠️ Beware that commonly used socket option names TCP_KEEPIDLE (or TCP_KEEPALIVE) and TCP_KEEPINTVL are expressed in seconds, while SIO_KEEPALIVE_VALS expresses durations in milliseconds.

Questions

The TCP keepalive feature being optional, it is not required that all platforms support it or provide any specific way of configuring the feature.

• Should a call to a non supported TCP keepalive option throw an exception ?
• How should a caller determine if a given option is indeed supported on the current platform ?
• Should an additional socket property, similar to Socket.LingerState be also added (e.g. KeepAliveState of type KeepAliveOption), in order to group the various options and handle everything at one place ?
  • The feature could be used with something like socket.KeepAliveState = new KeepAliveOption(true, 15, 7200, 1)
  • This would also be more consistent with the way the feature is configured on legacy Windows system.

[karelz]

Sounds like a reasonable proposal to us (@karelz @Priya91 @wfurt) -- @davidsh @DavidGoll any opinions?

BTW: We already have protocol specific options (e.g. IpTimeToLive) on the type: https://apisof.net/catalog/System.Net.Sockets.SocketOptionName.IpTimeToLive

[luigiberrettini]

Should we throw an exception if isKeepAliveSupported is false?
To add an exception message is it sufficient to edit the resx file?

OS X version >= 10.7.0 i.e. Darwin kernel version >= 11.0.0:

var isKeepAliveSupported = Environment.OSVersion.Version.Major >= 11

Windows version >= 10.0.1709:

var os = Environment.OSVersion;
var version = Environment.OSVersion.Version;
var isKeepAliveSupported = os.PlatformID == PlatformID.Win32NT && (version.Major > 10 || version.Major == 10 && version.Build >= 16299)

[wfurt]

.netcore is supported on OSX 10.12 and above. Even if we don't add explicit check, the socket call should fail and return error.

[luigiberrettini]

On versions below Windows 10 1709 it is not possible to retrieve the keep-alive values set via IOControl and an exception will be thrown when calling the getter of the KeepAliveOption 😞

[luigiberrettini]

I created a branch and implemented the features requested to close this issue, but would like to know if there is a way to test them better or to try them (e.g. the F5 way like in simple .NET projects), before opening a PR

[wfurt]

First step is to get API approved @luigiberrettini. I did not see that in the debates. Is this something you can take on @karelz and pitch that to the committee?
Having working prototype is certainly good step.

[karelz]

Sadly, it is too late for 2.1. We are busy finishing the release for next Preview. Let's open the API discussion next week for post-2.1 release.

[luigiberrettini]

I am sorry it took me too long to implement it 😞

[karelz]

@luigiberrettini while it would be useful to have it, it is not the end of the day to land it in the next release. The priority of this API was not very high. When it came to our attention over last few weeks, it was already fairly late for 2.1 anyway.

[luigiberrettini]

I've created some tests to check if setting socket options related to keep-alive works.
Unfortunately, even if both Linux and OS X kernels supports the option name constants I used, the tests are failing:

• Linux
• OS X

Do you have an idea of why the SocketPal.SetSockOpt is throwing a System.Net.Sockets.SocketException: Operation not supported?

[hexawyz]

I think you are reproducing the problem from https://github.com/dotnet/corefx/issues/14237 in these tests. (Also the reason why I opened this issue)

The values used in SocketOptionName were obviously derived from Windows headers, thus allowing the current Windows SocketPal to simply forward the SocketOptionName value to the underlying API. (But we can expect this to change someday)
However, for non Windows platforms, the SocketOptionName values will always have to be converted into their platform-specific equivalent. This means that any SocketOptionName value that is not specifically supported by the SocketPal will not work.

Calling the native setsockopt API via P/Invoke would still work, however.

[luigiberrettini]

I found the problem is TryGetPlatformSocketOption which is called passing option level (SocketOptionLevel.Socket in my code but SocketOptionLevel.Tcp in this issue proposal) and name:

extern "C"
Error SystemNative_SetSockOpt(intptr_t socket, int32_t socketOptionLevel, int32_t socketOptionName, uint8_t* optionValue, int32_t optionLen)]
{
    // ...
    int optLevel, optName;
    if (!TryGetPlatformSocketOption(socketOptionLevel, socketOptionName, optLevel, optName))
    {
        return PAL_ENOTSUP;
    }
    // ...
    int err = setsockopt(fd, optLevel, optName, optionValue, static_cast<socklen_t>(optionLen));
    // ...
}

It has misleading parameter names and return false for options not present in the SocketOptionName enum:

static bool TryGetPlatformSocketOption(int32_t socketOptionName, int32_t socketOptionLevel, int& optLevel, int& optName)
{
    // ...
}

This means that the keep-alive:

• retry count TCP_KEEPCNT (Linux = 0x6, OS X = 0x102) generates a PAL_ENOTSUP error and does not call the setsockopt syscall
• time TCP_KEEPIDLE (Linux = 0x4) is equal to PAL_SO_REUSEADDR and PAL_SO_IP_TTL therefore generates an error calling the setsockopt syscall
• time TCP_KEEPALIVE (OS X = 0x10) is equal to PAL_SO_DONTROUTE and PAL_SO_IP_DROP_SOURCE_MEMBERSHIP therefore generates an error calling the setsockopt syscall
• interval TCP_KEEPINTVL (Linux = 0x5, OS X = 0x101) generates a PAL_ENOTSUP error and does not call the setsockopt syscall

[luigiberrettini]

Thanks @GoldenCrystal!

It now works with P/Invoke:

• Linux
• OS X

Here is the code:

• Interop
• TestSuite

[karelz]

API discussion with Networking team:

• We should think how to expose it in HttpClientHandler/SocketsHttpHandler (I think there is already existing related issue)
• If platform does not support the option, we should not throw (it's annoying), just do noop + document it + log diagnostic entry
• The KeepAliveOption is problematic if we cannot get the information on all platforms. Also it is weird if the setter is noop (or even worse - exception) on some platforms for some values (e.g. RetryCount on pre-Win10). Until we have confirmation it is implementable on all OSs in a reasonable way, we should skip this part and focus on the 3 enum values first.

Summary: Networking team is fine with the first part of the API. We are going to bring it to BCL API review.

[terrajobst]

Video

Looks good.

Can we double check what happens if options are no-ops or are unsupported. Do we throw? If so, should the name of the option indicate that things might be unsupported or are no-ops?