[修改] WebSocket 核心模块增加 XML 文档注释，优化编码器、管线过滤器、压缩扩展和帧读取器

Author: AlianBlank

src/GameFrameX.SuperSocket.WebSocket/CloseReason.cs

@@ -3,17 +3,59 @@
 
 namespace GameFrameX.SuperSocket.WebSocket
 {
+    /// <summary>
+    /// Represents the reasons for closing a WebSocket connection.
+    /// </summary>
     public enum CloseReason : short
     {
+        /// <summary>
+        /// Indicates a normal closure of the WebSocket connection.
+        /// </summary>
         NormalClosure = 1000,
+
+        /// <summary>
+        /// Indicates that the WebSocket connection is going away.
+        /// </summary>
         GoingAway = 1001,
+
+        /// <summary>
+        /// Indicates a protocol error occurred.
+        /// </summary>
         ProtocolError = 1002,
+
+        /// <summary>
+        /// Indicates that the data received is not acceptable.
+        /// </summary>
         NotAcceptableData = 1003,
+
+        /// <summary>
+        /// Indicates that the frame received is too large.
+        /// </summary>
         TooLargeFrame = 1009,
+
+        /// <summary>
+        /// Indicates that the data received contains invalid UTF-8.
+        /// </summary>
         InvalidUTF8 = 1007,
+
+        /// <summary>
+        /// Indicates a policy violation occurred.
+        /// </summary>
         ViolatePolicy = 1008,
+
+        /// <summary>
+        /// Indicates that the WebSocket extension does not match.
+        /// </summary>
         ExtensionNotMatch = 1010,
+
+        /// <summary>
+        /// Indicates an unexpected condition caused the closure.
+        /// </summary>
         UnexpectedCondition = 1011,
+
+        /// <summary>
+        /// Indicates that no status code was provided.
+        /// </summary>
         NoStatusCode = 1005
     }
 }

src/GameFrameX.SuperSocket.WebSocket/CloseStatus.cs

@@ -3,12 +3,24 @@
 
 namespace GameFrameX.SuperSocket.WebSocket
 {
+    /// <summary>
+    /// Represents the status of a WebSocket close operation.
+    /// </summary>
     public class CloseStatus
     {
+        /// <summary>
+        /// Gets or sets the reason for the WebSocket close operation.
+        /// </summary>
         public CloseReason Reason { get; set; }
 
+        /// <summary>
+        /// Gets or sets the reason text for the WebSocket close operation.
+        /// </summary>
         public string ReasonText { get; set; }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether the close operation was initiated by the remote endpoint.
+        /// </summary>
         public bool RemoteInitiated { get; set; }
     }
 }

src/GameFrameX.SuperSocket.WebSocket/ExtensionMethods.cs

@@ -5,6 +5,9 @@
 
 namespace GameFrameX.SuperSocket.WebSocket
 {
+    /// <summary>
+    /// Extension methods for WebSocket implementation.
+    /// </summary>
     public static partial class ExtensionMethods
     {
         private readonly static char[] m_CrCf = new char[] { '\r', '\n' };
@@ -53,6 +56,11 @@ public static void AppendWithCrCf(this StringBuilder builder)
             builder.Append(m_CrCf);
         }
 
+        /// <summary>
+        /// Creates a copy of the given ReadOnlySequence.
+        /// </summary>
+        /// <param name="seq">The sequence to copy.</param>
+        /// <returns>A new ReadOnlySequence that is a copy of the input sequence.</returns>
         internal static ReadOnlySequence<byte> CopySequence(ref this ReadOnlySequence<byte> seq)
         {
             SequenceSegment head = null;
@@ -71,6 +79,11 @@ internal static ReadOnlySequence<byte> CopySequence(ref this ReadOnlySequence<by
             return new ReadOnlySequence<byte>(head, 0, tail, tail.Memory.Length);
         }
 
+        /// <summary>
+        /// Destructs the given ReadOnlySequence into its head and tail segments.
+        /// </summary>
+        /// <param name="first">The sequence to destruct.</param>
+        /// <returns>A tuple containing the head and tail segments of the sequence.</returns>
         internal static (SequenceSegment, SequenceSegment) DestructSequence(ref this ReadOnlySequence<byte> first)
         {
             SequenceSegment head = first.Start.GetObject() as SequenceSegment;
@@ -90,6 +103,12 @@ internal static (SequenceSegment, SequenceSegment) DestructSequence(ref this Rea
             return (head, tail);
         }
 
+        /// <summary>
+        /// Concatenates two ReadOnlySequences into a single sequence.
+        /// </summary>
+        /// <param name="first">The first sequence.</param>
+        /// <param name="second">The second sequence.</param>
+        /// <returns>A new ReadOnlySequence that is the concatenation of the two input sequences.</returns>
         internal static ReadOnlySequence<byte> ConcatSequence(ref this ReadOnlySequence<byte> first, ref ReadOnlySequence<byte> second)
         {
             var (head, tail) = first.DestructSequence();
@@ -105,6 +124,12 @@ internal static ReadOnlySequence<byte> ConcatSequence(ref this ReadOnlySequence<
             return new ReadOnlySequence<byte>(head, 0, tail, tail.Memory.Length);
         }
 
+        /// <summary>
+        /// Concatenates a ReadOnlySequence with a single SequenceSegment.
+        /// </summary>
+        /// <param name="first">The sequence to concatenate.</param>
+        /// <param name="segment">The segment to append to the sequence.</param>
+        /// <returns>A new ReadOnlySequence that includes the appended segment.</returns>
         internal static ReadOnlySequence<byte> ConcatSequence(ref this ReadOnlySequence<byte> first, SequenceSegment segment)
         {
             var (head, tail) = first.DestructSequence();

src/GameFrameX.SuperSocket.WebSocket/Extensions/Compression/ReadOnlySequenceStream.cs

@@ -2,45 +2,71 @@
 
 namespace GameFrameX.SuperSocket.WebSocket.Extensions.Compression
 {
+    /// <summary>
+    /// Represents a read-only stream that reads data from a <see cref="ReadOnlySequence{T}"/>.
+    /// </summary>
     class ReadOnlySequenceStream : Stream
     {
         private ReadOnlySequence<byte> _sequence;
 
+        /// <summary>
+        /// Gets a value indicating whether the stream supports reading. Always returns true.
+        /// </summary>
         public override bool CanRead => true;
 
+        /// <summary>
+        /// Gets a value indicating whether the stream supports seeking. Always returns false.
+        /// </summary>
         public override bool CanSeek => false;
 
+        /// <summary>
+        /// Gets a value indicating whether the stream supports writing. Always returns false.
+        /// </summary>
         public override bool CanWrite => false;
 
         private long _length;
 
+        /// <summary>
+        /// Gets the length of the stream.
+        /// </summary>
         public override long Length => _length;
 
         /// <summary>
         /// Gets or sets the position within the stream. Not implemented.
         /// </summary>
         /// <exception cref="NotImplementedException">Always thrown.</exception>
-        public override long Position
-        {
-            get { throw new NotImplementedException(); }
-            set { throw new NotImplementedException(); }
-        }
+        public override long Position { get => throw new NotImplementedException(); set => throw new NotImplementedException(); }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ReadOnlySequenceStream"/> class with the specified sequence.
+        /// </summary>
+        /// <param name="sequence">The read-only sequence to read data from.</param>
         public ReadOnlySequenceStream(ReadOnlySequence<byte> sequence)
         {
             _sequence = sequence;
             _length = sequence.Length;
         }
 
+        /// <summary>
+        /// Flushes the stream. Not supported.
+        /// </summary>
+        /// <exception cref="NotSupportedException">Always thrown.</exception>
         public override void Flush()
         {
             throw new NotSupportedException();
         }
 
+        /// <summary>
+        /// Reads a sequence of bytes from the current stream and advances the position within the stream by the number of bytes read.
+        /// </summary>
+        /// <param name="buffer">The buffer to read data into.</param>
+        /// <param name="offset">The zero-based byte offset in the buffer at which to begin storing the data read from the stream.</param>
+        /// <param name="count">The maximum number of bytes to read.</param>
+        /// <returns>The total number of bytes read into the buffer.</returns>
         public override int Read(byte[] buffer, int offset, int count)
         {
             var firstSpan = _sequence.FirstSpan;
-
+            
             if (firstSpan.IsEmpty)
                 return 0;
 
@@ -52,16 +78,35 @@ public override int Read(byte[] buffer, int offset, int count)
             return len;
         }
 
+        /// <summary>
+        /// Sets the position within the stream. Not supported.
+        /// </summary>
+        /// <param name="offset">The byte offset relative to the <paramref name="origin"/>.</param>
+        /// <param name="origin">A value of type <see cref="SeekOrigin"/> indicating the reference point used to obtain the new position.</param>
+        /// <returns>Always throws a <see cref="NotSupportedException"/>.</returns>
+        /// <exception cref="NotSupportedException">Always thrown.</exception>
         public override long Seek(long offset, SeekOrigin origin)
         {
             throw new NotSupportedException();
         }
 
+        /// <summary>
+        /// Sets the length of the stream. Not supported.
+        /// </summary>
+        /// <param name="value">The desired length of the stream.</param>
+        /// <exception cref="NotSupportedException">Always thrown.</exception>
         public override void SetLength(long value)
         {
             throw new NotSupportedException();
         }
 
+        /// <summary>
+        /// Writes a sequence of bytes to the current stream. Not supported.
+        /// </summary>
+        /// <param name="buffer">The buffer containing data to write.</param>
+        /// <param name="offset">The zero-based byte offset in the buffer at which to begin copying bytes to the stream.</param>
+        /// <param name="count">The number of bytes to write to the stream.</param>
+        /// <exception cref="NotSupportedException">Always thrown.</exception>
         public override void Write(byte[] buffer, int offset, int count)
         {
             throw new NotSupportedException();

src/GameFrameX.SuperSocket.WebSocket/Extensions/Compression/WebSocketPerMessageCompressionExtension.cs

@@ -8,13 +8,18 @@
 namespace GameFrameX.SuperSocket.WebSocket.Extensions.Compression
 {
     /// <summary>
-    /// WebSocket Per-Message Compression Extension
-    /// https://tools.ietf.org/html/rfc7692
+    /// Implements the WebSocket Per-Message Compression Extension as defined in RFC 7692.
     /// </summary>
     public class WebSocketPerMessageCompressionExtension : IWebSocketExtension
     {
+        /// <summary>
+        /// Gets the name of the WebSocket Per-Message Compression Extension.
+        /// </summary>
         public string Name => PMCE;
 
+        /// <summary>
+        /// The name of the Per-Message Compression Extension.
+        /// </summary>
         public const string PMCE = "permessage-deflate";
 
         private const int _deflateBufferSize = 1024 * 1024 * 4;
@@ -24,6 +29,10 @@ public class WebSocketPerMessageCompressionExtension : IWebSocketExtension
         private static readonly byte[] LAST_FOUR_OCTETS = new byte[] { 0x00, 0x00, 0xFF, 0xFF };
         private static readonly ArrayPool<byte> _arrayPool = ArrayPool<byte>.Shared;
 
+        /// <summary>
+        /// Decodes a WebSocket package by decompressing its data.
+        /// </summary>
+        /// <param name="package">The WebSocket package to decode.</param>
         public void Decode(WebSocketPackage package)
         {
             if (!package.RSV1)
@@ -58,22 +67,30 @@ public void Decode(WebSocketPackage package)
             package.Data = new ReadOnlySequence<byte>(head, 0, tail, tail.Memory.Length);
         }
 
+        /// <summary>
+        /// Encodes a WebSocket package by compressing its data.
+        /// </summary>
+        /// <param name="package">The WebSocket package to encode.</param>
         public void Encode(WebSocketPackage package)
         {
             package.RSV1 = true;
 
             if (package.Data.IsEmpty)
                 EncodeTextMessage(package);
             else
-                EncodeDataMessage(package);
+                EncodeDataMessage(package);            
         }
 
+        /// <summary>
+        /// Encodes a text message in a WebSocket package using compression.
+        /// </summary>
+        /// <param name="package">The WebSocket package containing the text message.</param>
         private void EncodeTextMessage(WebSocketPackage package)
         {
             var encoder = _encoding.GetEncoder();
             var text = package.Message.AsSpan();
 
-            var completed = false;
+            var completed = false;      
 
             var outputStream = new WritableSequenceStream();
 
@@ -85,7 +102,7 @@ private void EncodeTextMessage(WebSocketPackage package)
                     Span<byte> span = buffer;
 
                     encoder.Convert(text, span, false, out int charsUsed, out int bytesUsed, out completed);
-
+                
                     if (charsUsed > 0)
                         text = text.Slice(charsUsed);
 
@@ -100,6 +117,10 @@ private void EncodeTextMessage(WebSocketPackage package)
             package.Data = data;
         }
 
+        /// <summary>
+        /// Removes the last four octets from the compressed data sequence.
+        /// </summary>
+        /// <param name="data">The compressed data sequence.</param>
         private void RemoveLastFourOctets(ref ReadOnlySequence<byte> data)
         {
             var octetsLen = LAST_FOUR_OCTETS.Length;
@@ -122,6 +143,10 @@ private void RemoveLastFourOctets(ref ReadOnlySequence<byte> data)
             data = data.Slice(0, data.Length - octetsLen);
         }
 
+        /// <summary>
+        /// Encodes a data message in a WebSocket package using compression.
+        /// </summary>
+        /// <param name="package">The WebSocket package containing the data message.</param>
         private void EncodeDataMessage(WebSocketPackage package)
         {
             var data = package.Data;