Add some comments to various internal HTTP/2 types (#57151)

* Add type comment for Http2Frame

* Add type comment for Http2FrameReader

* Add type comment for Http2PeerSettings

* Add type comment for FlowControl

* Add type comment for InputFlowControl

* Add type comment for StreamInputFlowControl

* Add type comment for HttpConnection

* Add type comments for some HTTP/2 stream types

* Add type comment for Http2FrameWriter

* Add type comment for Http2KeepAlive

* Add type comment for Http2Connection

* Add type comment for Http2MessageBody

* Add partial comments for output producer types

* Use <para> tags

* Use one space after a period

* Add additional notes to Http2Connection

Author: amcasey

src/Servers/Kestrel/Core/src/Internal/Http/HttpProtocol.cs

@@ -23,6 +23,13 @@ namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
 using BadHttpRequestException = Microsoft.AspNetCore.Http.BadHttpRequestException;
 
+/// <remarks>
+/// Request processing code (especially <see cref="ProcessRequestsAsync"/>) shared across HTTP protocols
+/// via inheritance.
+/// <para/>
+/// HTTP/1.1 uses it at the connection level and resets it between requests.
+/// HTTP/2 and HTTP/3 use it at the stream level.
+/// </remarks>
 internal abstract partial class HttpProtocol : IHttpResponseControl
 {
     private static readonly byte[] _bytesConnectionClose = Encoding.ASCII.GetBytes("\r\nConnection: close");

src/Servers/Kestrel/Core/src/Internal/Http/IHttpOutputProducer.cs

@@ -5,6 +5,9 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http;
 
+/// <remarks>
+/// Used to plug HTTP version-specific functionality into <see cref="HttpProtocol"/>.
+/// </remarks>
 internal interface IHttpOutputProducer
 {
     ValueTask<FlushResult> WriteChunkAsync(ReadOnlySpan<byte> data, CancellationToken cancellationToken);
@@ -13,6 +16,7 @@ internal interface IHttpOutputProducer
     void WriteResponseHeaders(int statusCode, string? reasonPhrase, HttpResponseHeaders responseHeaders, bool autoChunk, bool appCompleted);
     // This takes ReadOnlySpan instead of ReadOnlyMemory because it always synchronously copies data before flushing.
     ValueTask<FlushResult> WriteDataToPipeAsync(ReadOnlySpan<byte> data, CancellationToken cancellationToken);
+    // Test hook
     Task WriteDataAsync(ReadOnlySpan<byte> data, CancellationToken cancellationToken);
     ValueTask<FlushResult> WriteStreamSuffixAsync();
     void Advance(int bytes);

src/Servers/Kestrel/Core/src/Internal/Http2/FlowControl/FlowControl.cs

@@ -5,6 +5,13 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2.FlowControl;
 
+/// <summary>
+/// Represents the flow control window for an <see cref="InputFlowControl"/>.
+/// Mutated as the available quota changes.
+/// </summary>
+/// <remarks>
+/// "FlowControlWindow" would probably be a clearer name.
+/// </remarks>
 internal struct FlowControl
 {
     public FlowControl(uint initialWindowSize)

src/Servers/Kestrel/Core/src/Internal/Http2/FlowControl/InputFlowControl.cs

@@ -5,6 +5,18 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2.FlowControl;
 
+/// <summary>
+/// Represents the in-bound flow control state of a stream or connection.
+/// </summary>
+/// <remarks>
+/// Owns a <see cref="FlowControl"/> that it uses to track the present window size.
+/// <para/>
+/// <see cref="Http2Connection"/> owns an instance for the connection-level flow control.
+/// <see cref="StreamInputFlowControl"/> owns an instance for the stream-level flow control.
+/// <para/>
+/// Reusable after calling <see cref="Reset"/>.
+/// </remarks>
+/// <seealso href="https://datatracker.ietf.org/doc/html/rfc9113#name-flow-control"/>
 internal sealed class InputFlowControl
 {
     private readonly int _initialWindowSize;

src/Servers/Kestrel/Core/src/Internal/Http2/FlowControl/StreamInputFlowControl.cs

@@ -5,6 +5,19 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2.FlowControl;
 
+/// <summary>
+/// Represents the in-bound flow control state of a stream.
+/// </summary>
+/// <remarks>
+/// Owns an <see cref="InputFlowControl"/> for the stream-level flow control and
+/// references another (owned by a <see cref="Http2Connection"/>) for the
+/// connection-level flow control.
+/// <para/>
+/// <see cref="Http2Stream"/> owns an instance for the stream-level flow control.
+/// <para/>
+/// Reusable after calling <see cref="Reset"/>.
+/// </remarks>
+/// <seealso href="https://datatracker.ietf.org/doc/html/rfc9113#name-flow-control"/>
 internal sealed class StreamInputFlowControl
 {
     private readonly InputFlowControl _connectionLevelFlowControl;

src/Servers/Kestrel/Core/src/Internal/Http2/Http2Connection.cs

@@ -21,6 +21,22 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2;
 
+/// <summary>
+/// An HTTP/2 connection - owns the request processing and lifetime.
+/// <para/>
+/// Responsible for reading incoming HTTP/2 frames. New requests create streams and execution
+/// for the request is dispatched to the thread pool.
+/// <para/>
+/// </summary>
+/// <remarks>
+/// Owned by <see cref="HttpConnection"/>.
+/// <para/>
+/// For performance, streams are pooled when an HTTP/2 request completes gracefully. Future requests
+/// reuse a pooled stream if available. There are limits on the number of pooled streams, and unused
+/// streams are automatically removed from the pool after a timeout.
+/// <para/>
+/// The connection itself is not reusable.
+/// </remarks>
 internal sealed partial class Http2Connection : IHttp2StreamLifetimeHandler, IHttpStreamHeadersHandler, IRequestProcessor
 {
     // This uses C# compiler's ability to refer to static data directly. For more information see https://vcsjones.dev/2019/02/01/csharp-readonly-span-bytes-static

src/Servers/Kestrel/Core/src/Internal/Http2/Http2FrameWriter.cs

@@ -14,6 +14,21 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2;
 
+/// <summary>
+/// Encodes HTTP/2 stream responses as frames and sends them over the wire.
+/// </summary>
+/// <remarks>
+/// Owned by <see cref="Http2Connection"/>.
+/// <para/>
+/// Since a connection has multiple streams, this class maintains a <see cref="Channel{T}"/> (i.e. bounded queue)
+/// of <see cref="Http2OutputProducer"/> instances (each of which is owned by a stream) that want to write frames.
+/// <para/>
+/// Reuses a single <see cref="Http2Frame"/>, which it populates based on the next <see cref="Http2OutputProducer"/>
+/// (and corresponding <see cref="Http2Stream{TContext}"/>) and then serializes to binary in
+/// <see cref="WriteToOutputPipe"/>.
+/// <para/>
+/// Tracks the outgoing connection window size while <see cref="Http2OutputProducer"/> tracks the stream window size.
+/// </remarks>
 internal sealed class Http2FrameWriter
 {
     // Literal Header Field without Indexing - Indexed Name (Index 8 - :status)

src/Servers/Kestrel/Core/src/Internal/Http2/Http2KeepAlive.cs

@@ -13,6 +13,11 @@ internal enum KeepAliveState
     Timeout
 }
 
+/// <summary>
+/// Used by a <see cref="Http2Connection"/> to determine whether the connection is still alive.
+/// If no frames have been received within a given period of time, triggers a ping that should
+/// draw a response. After a further timeout, signals that the connection should be dropped.
+/// </summary>
 internal sealed class Http2KeepAlive
 {
     // An empty ping payload

src/Servers/Kestrel/Core/src/Internal/Http2/Http2MessageBody.cs

@@ -10,6 +10,14 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2;
 
+/// <summary>
+/// Exposes the bytes of an incoming request.
+/// </summary>
+/// <remarks>
+/// Owned by an <see cref="Http2Stream"/>.
+/// <para/>
+/// Reusable after calling <see cref="Reset"/>.
+/// </remarks>
 internal sealed class Http2MessageBody : MessageBody
 {
     private readonly Http2Stream _context;

src/Servers/Kestrel/Core/src/Internal/Http2/Http2OutputProducer.cs

@@ -12,6 +12,13 @@
 
 namespace Microsoft.AspNetCore.Server.Kestrel.Core.Internal.Http2;
 
+/// <remarks>
+/// Owned by <see cref="Http2Stream"/>.
+/// <para/>
+/// Tracks the outgoing stream flow control window.
+/// <para/>
+/// Reusable after calling <see cref="StreamReset"/> (<see cref="Reset"/> is unrelated and does nothing).
+/// </remarks>
 internal sealed class Http2OutputProducer : IHttpOutputProducer, IHttpOutputAborter, IDisposable
 {
     private int StreamId => _stream.StreamId;