Background and Motivation

We recently removed System.Net.Connections from 5.0. One feature we lost was the PlaintextFilter property on SocketsHttpHandler, which allowed you to inspect and modify unencrypted (i.e. "plaintext") HTTP protocol traffic in and out.

This new API provides the same capability without relying on System.Net.Connections. When you set this property, your callback will be invoked whenever SocketsHttpHandler constructs a new HTTP connection, after completing the TCP connect and TLS establishment. You can use the callback to wrap the underlying Stream in your own Stream.

Proposed API

namespace System.Net.Http
{
    public sealed class SocketsHttpPlaintextStreamFilterContext
    {
        public Stream PlaintextStream => _plaintextStream;
        public Version HttpVersion => _httpVersion;
        public HttpRequestMessage RequestMessage => _requestMessage;
    }
    public sealed class SocketsHttpHandler : HttpMessageHandler
    {
        public Func<SocketsHttpPlaintextStreamFilterContext, CancellationToken, ValueTask<Stream>>? PlaintextStreamFilter { get; set; }
    }
}

See ConnectCallback API for comparison: #41949

Alternative Designs

What's the right name for this feature? In the original Connections design, it was just PlaintextFilter.
Does including "Stream" in the name help?
"Plaintext" vs "Raw"? "Raw" may sound more like the on-the-wire, encrypted bits. "Plaintext" may provide better intuition here but isn't a super common term.
Should the property name include "Callback" for consistency with ConnectCallback?