[修改] Connection 模块增加 XML 文档注释，扩展连接接口（增加 SendAsync 重载、Dispose 等），新增 ConsoleConnection 和 CloseReason.Rejected

Author: AlianBlank

src/GameFrameX.SuperSocket.Connection/CloseReason.cs

@@ -1,58 +1,75 @@
 namespace GameFrameX.SuperSocket.Connection
 {
     /// <summary>
-    /// 关闭原因
+    /// Specifies the reasons for closing a connection.
     /// </summary>
     public enum CloseReason
     {
         /// <summary>
-        /// The socket is closed for unknown reason
+        /// The socket is closed for an unknown reason.
         /// </summary>
         Unknown = 0,
 
         /// <summary>
-        /// Close for server shutdown
+        /// The connection is closed due to server shutdown.
         /// </summary>
         ServerShutdown = 1,
 
         /// <summary>
-        /// The close behavior is initiated from the remote endpoint
+        /// The connection is closed by the remote endpoint.
         /// </summary>
         RemoteClosing = 2,
 
         /// <summary>
-        /// The close behavior is initiated from the local endpoint
+        /// The connection is closed by the local endpoint.
         /// </summary>
         LocalClosing = 3,
 
         /// <summary>
-        /// Application error
+        /// The connection is closed due to an application error.
         /// </summary>
         ApplicationError = 4,
 
         /// <summary>
-        /// The socket is closed for a socket error
+        /// The connection is closed due to a socket error.
         /// </summary>
         SocketError = 5,
 
         /// <summary>
-        /// The socket is closed by server for timeout
+        /// The connection is closed by the server due to a timeout.
         /// </summary>
         TimeOut = 6,
 
         /// <summary>
-        /// Protocol error 
+        /// The connection is closed due to a protocol error.
         /// </summary>
         ProtocolError = 7,
 
         /// <summary>
-        /// SuperSocket internal error
+        /// The connection is closed due to an internal error in SuperSocket.
         /// </summary>
         InternalError = 8,
+
+        /// <summary>
+        /// The connection is closed because it was rejected.
+        /// </summary>
+        Rejected = 9
     }
+
+    /// <summary>
+    /// Provides data for connection close events.
+    /// </summary>
     public class CloseEventArgs : EventArgs
     {
+        /// <summary>
+        /// Gets the reason for the connection closure.
+        /// </summary>
         public CloseReason Reason { get; private set; }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="CloseEventArgs"/> class with the specified close reason.
+        /// </summary>
+        /// <param name="reason">The reason for the connection closure.</param>
         public CloseEventArgs(CloseReason reason)
         {
             Reason = reason;

src/GameFrameX.SuperSocket.Connection/ConnectionBase.cs

@@ -1,33 +1,96 @@
-using System.IO.Pipelines;
+using System.Buffers;
+using System.IO.Pipelines;
 using System.Net;
 using GameFrameX.SuperSocket.ProtoBase;
 using GameFrameX.SuperSocket.ProtoBase.ProxyProtocol;
 
 namespace GameFrameX.SuperSocket.Connection
 {
+    /// <summary>
+    /// Provides an abstract base class for connections, defining common connection functionality.
+    /// </summary>
     public abstract class ConnectionBase : IConnection
     {
+        /// <summary>
+        /// Runs the connection asynchronously with the specified pipeline filter.
+        /// </summary>
+        /// <typeparam name="TPackageInfo">The type of the package information.</typeparam>
+        /// <param name="pipelineFilter">The pipeline filter to use for processing data.</param>
+        /// <returns>An asynchronous enumerable of package information.</returns>
         public abstract IAsyncEnumerable<TPackageInfo> RunAsync<TPackageInfo>(IPipelineFilter<TPackageInfo> pipelineFilter);
 
+        /// <summary>
+        /// Sends data over the connection asynchronously using the specified buffer.
+        /// </summary>
+        /// <param name="buffer">The buffer containing the data to send.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous send operation.</returns>
         public abstract ValueTask SendAsync(ReadOnlyMemory<byte> buffer, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Sends data over the connection asynchronously using the specified buffer.
+        /// </summary>
+        /// <param name="buffer">The buffer containing the data to send.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous send operation.</returns>
+        public abstract ValueTask SendAsync(ReadOnlySequence<byte> buffer, CancellationToken cancellationToken = default);
+
+        /// <summary>
+        /// Sends a package over the connection asynchronously using the specified encoder and package.
+        /// </summary>
+        /// <typeparam name="TPackage">The type of the package to send.</typeparam>
+        /// <param name="packageEncoder">The encoder to use for the package.</param>
+        /// <param name="package">The package to send.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous send operation.</returns>
         public abstract ValueTask SendAsync<TPackage>(IPackageEncoder<TPackage> packageEncoder, TPackage package, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Sends data over the connection asynchronously using a custom write action.
+        /// </summary>
+        /// <param name="write">The action to write data to the pipe writer.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous send operation.</returns>
         public abstract ValueTask SendAsync(Action<PipeWriter> write, CancellationToken cancellationToken = default);
 
+        /// <summary>
+        /// Gets a value indicating whether the connection is closed.
+        /// </summary>
         public bool IsClosed { get; private set; }
 
+        /// <summary>
+        /// Gets the remote endpoint of the connection.
+        /// </summary>
         public EndPoint RemoteEndPoint { get; protected set; }
 
+        /// <summary>
+        /// Gets the local endpoint of the connection.
+        /// </summary>
         public EndPoint LocalEndPoint { get; protected set; }
 
+        /// <summary>
+        /// Gets the reason for the connection closure, if available.
+        /// </summary>
         public CloseReason? CloseReason { get; protected set; }
 
+        /// <summary>
+        /// Gets the last active time of the connection.
+        /// </summary>
         public DateTimeOffset LastActiveTime { get; protected set; } = DateTimeOffset.Now;
 
+        /// <summary>
+        /// Gets the cancellation token associated with the connection.
+        /// </summary>
         public CancellationToken ConnectionToken { get; protected set; }
+
+        /// <summary>
+        /// Gets the proxy information associated with the connection.
+        /// </summary>
         public ProxyInfo ProxyInfo { get; protected set; }
 
+        /// <summary>
+        /// Handles actions to perform when the connection is closed.
+        /// </summary>
         protected virtual void OnClosed()
         {
             IsClosed = true;
@@ -45,10 +108,34 @@ protected virtual void OnClosed()
             closed.Invoke(this, new CloseEventArgs(closeReason));
         }
 
+        /// <summary>
+        /// Occurs when the connection is closed.
+        /// </summary>
         public event EventHandler<CloseEventArgs> Closed;
 
+        /// <summary>
+        /// Closes the connection asynchronously with the specified reason.
+        /// </summary>
+        /// <param name="closeReason">The reason for closing the connection.</param>
+        /// <returns>A task that represents the asynchronous close operation.</returns>
         public abstract ValueTask CloseAsync(CloseReason closeReason);
 
+        /// <summary>
+        /// Detaches the connection asynchronously.
+        /// </summary>
+        /// <returns>A task that represents the asynchronous detach operation.</returns>
         public abstract ValueTask DetachAsync();
+
+        public void Dispose()
+        {
+            DisposeAsync()
+                .AsTask()
+                .Wait();
+        }
+
+        public ValueTask DisposeAsync()
+        {
+            return CloseAsync(Connection.CloseReason.LocalClosing);
+        }
     }
 }

src/GameFrameX.SuperSocket.Connection/ConnectionExtensions.cs

@@ -3,8 +3,16 @@
 
 namespace GameFrameX.SuperSocket.Connection
 {
+    /// <summary>
+    /// Provides extension methods for working with connections.
+    /// </summary>
     public static class ConnectionExtensions
     {
+        /// <summary>
+        /// Gets the remote certificate associated with the connection, if available.
+        /// </summary>
+        /// <param name="connection">The connection to retrieve the remote certificate from.</param>
+        /// <returns>The remote certificate, or <c>null</c> if no certificate is available.</returns>
         public static X509Certificate GetRemoteCertificate(this IConnection connection)
         {
             if (connection is IStreamConnection streamConnection

src/GameFrameX.SuperSocket.Connection/ConnectionOptions.cs

@@ -3,38 +3,59 @@
 
 namespace GameFrameX.SuperSocket.Connection
 {
+    /// <summary>
+    /// Represents configuration options for managing connections.
+    /// </summary>
     public class ConnectionOptions
     {
-        // 1M by default
+        /// <summary>
+        /// Gets or sets the maximum package length in bytes. Default is 1 MB.
+        /// </summary>
         public int MaxPackageLength { get; set; } = 1024 * 1024;
 
-        // 4k by default
+        /// <summary>
+        /// Gets or sets the size of the receive buffer in bytes. Default is 4 KB.
+        /// </summary>
         public int ReceiveBufferSize { get; set; } = 1024 * 4;
 
-        // 4k by default
+        /// <summary>
+        /// Gets or sets the size of the send buffer in bytes. Default is 4 KB.
+        /// </summary>
         public int SendBufferSize { get; set; } = 1024 * 4;
 
-        // trigger the read only when the stream is being consumed
+        /// <summary>
+        /// Gets or sets a value indicating whether data should be read only when the stream is being consumed.
+        /// </summary>
         public bool ReadAsDemand { get; set; }
 
         /// <summary>
-        /// in milliseconds
+        /// Gets or sets the receive timeout in milliseconds.
         /// </summary>
-        /// <value></value>
         public int ReceiveTimeout { get; set; }
 
         /// <summary>
-        /// in milliseconds
+        /// Gets or sets the send timeout in milliseconds.
         /// </summary>
-        /// <value></value>
         public int SendTimeout { get; set; }
 
+        /// <summary>
+        /// Gets or sets the logger for the connection.
+        /// </summary>
         public ILogger Logger { get; set; }
 
+        /// <summary>
+        /// Gets or sets the input pipe for the connection.
+        /// </summary>
         public Pipe Input { get; set; }
 
+        /// <summary>
+        /// Gets or sets the output pipe for the connection.
+        /// </summary>
         public Pipe Output { get; set; }
 
+        /// <summary>
+        /// Gets or sets additional key-value pairs for connection configuration.
+        /// </summary>
         public Dictionary<string, string> Values { get; set; }
     }
 }