[修改] Client/ClientProxy/ClientEngine 模块增加 XML 文档注释，扩展连接器功能（SocketConnector 支持 DNS、ProxyConnectorBase 可自定义连接器）

Author: AlianBlank

src/GameFrameX.SuperSocket.Client.Proxy/HttpConnector.cs

@@ -5,6 +5,9 @@
 
 namespace GameFrameX.SuperSocket.Client.Proxy
 {
+    /// <summary>
+    /// Represents a connector for HTTP proxy connections.
+    /// </summary>
     public class HttpConnector : ProxyConnectorBase
     {
         private const string _requestTemplate = "CONNECT {0}:{1} HTTP/1.1\r\nHost: {0}:{1}\r\nProxy-Connection: Keep-Alive\r\n";
@@ -13,18 +16,39 @@ public class HttpConnector : ProxyConnectorBase
         private string _username;
         private string _password;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HttpConnector"/> class with the specified proxy endpoint.
+        /// </summary>
+        /// <param name="proxyEndPoint">The endpoint of the HTTP proxy server.</param>
         public HttpConnector(EndPoint proxyEndPoint)
             : base(proxyEndPoint)
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="HttpConnector"/> class with the specified proxy endpoint, username, and password.
+        /// </summary>
+        /// <param name="proxyEndPoint">The endpoint of the HTTP proxy server.</param>
+        /// <param name="username">The username for authentication.</param>
+        /// <param name="password">The password for authentication.</param>
         public HttpConnector(EndPoint proxyEndPoint, string username, string password)
             : this(proxyEndPoint)
         {
             _username = username;
             _password = password;
         }
 
+        /// <summary>
+        /// Connects to the specified remote endpoint through the HTTP proxy.
+        /// </summary>
+        /// <param name="remoteEndPoint">The remote endpoint to connect to.</param>
+        /// <param name="state">The connection state from the previous connector.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task representing the asynchronous connection operation. The result contains information about the connection status.</returns>
+        /// <remarks>
+        /// This method establishes a connection to the remote endpoint through the HTTP proxy using the CONNECT method.
+        /// It supports both DNS and IP endpoint types and handles proxy authentication if credentials are provided.
+        /// </remarks>
         protected override async ValueTask<ConnectState> ConnectProxyAsync(EndPoint remoteEndPoint, ConnectState state, CancellationToken cancellationToken)
         {
             var encoding = Encoding.ASCII;
@@ -84,6 +108,16 @@ await connection.SendAsync((writer) =>
             return state;
         }
 
+        /// <summary>
+        /// Processes the HTTP response from the proxy server.
+        /// </summary>
+        /// <param name="p">The text package containing the HTTP response.</param>
+        /// <param name="message">When this method returns, contains an error message if the response is invalid; otherwise, an empty string.</param>
+        /// <returns><c>true</c> if the response indicates a successful connection; otherwise, <c>false</c>.</returns>
+        /// <remarks>
+        /// A successful response should have a status code in the 2xx range (200-299).
+        /// This method validates the format of the HTTP response and extracts the status code.
+        /// </remarks>
         private bool HandleResponse(TextPackageInfo p, out string message)
         {
             message = string.Empty;

src/GameFrameX.SuperSocket.Client.Proxy/ProxyConnectorBase.cs

@@ -2,20 +2,53 @@
 
 namespace GameFrameX.SuperSocket.Client.Proxy
 {
+    /// <summary>
+    /// Provides a base class for proxy connectors.
+    /// </summary>
     public abstract class ProxyConnectorBase : ConnectorBase
     {
         private EndPoint _proxyEndPoint;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ProxyConnectorBase"/> class with the specified proxy endpoint.
+        /// </summary>
+        /// <param name="proxyEndPoint">The endpoint of the proxy server.</param>
         public ProxyConnectorBase(EndPoint proxyEndPoint)
         {
             _proxyEndPoint = proxyEndPoint;
         }
 
+        /// <summary>
+        /// Connects to the specified remote endpoint through the proxy.
+        /// </summary>
+        /// <param name="remoteEndPoint">The remote endpoint to connect to.</param>
+        /// <param name="state">The connection state.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task representing the asynchronous connection operation.</returns>
         protected abstract ValueTask<ConnectState> ConnectProxyAsync(EndPoint remoteEndPoint, ConnectState state, CancellationToken cancellationToken);
 
+        /// <summary>
+        ///  Creates the default connector for the proxy connection.
+        /// </summary>
+        protected virtual IConnector CreateDefaultConnector()
+        {
+            return new SocketConnector();
+        }
+
+        /// <summary>
+        /// Establishes a connection to the specified remote endpoint through the proxy.
+        /// </summary>
+        /// <param name="remoteEndPoint">The remote endpoint to connect to.</param>
+        /// <param name="state">The connection state.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task representing the asynchronous connection operation. The result contains information about the connection status.</returns>
+        /// <remarks>
+        /// This method first establishes a connection to the proxy server, and then calls <see cref="ConnectProxyAsync"/> to
+        /// establish a connection to the remote endpoint through the proxy.
+        /// </remarks>
         protected override async ValueTask<ConnectState> ConnectAsync(EndPoint remoteEndPoint, ConnectState state, CancellationToken cancellationToken)
         {
-            var socketConnector = new SocketConnector() as IConnector;
+            var socketConnector = CreateDefaultConnector();
             var proxyEndPoint = _proxyEndPoint;
 
             ConnectState result;

src/GameFrameX.SuperSocket.Client.Proxy/ProxyType.cs

@@ -1,10 +1,28 @@
 namespace GameFrameX.SuperSocket.Client.Proxy
 {
+    /// <summary>
+    /// Specifies the types of proxy servers supported.
+    /// </summary>
     public enum ProxyType
     {
+        /// <summary>
+        /// HTTP proxy.
+        /// </summary>
         Http,
+
+        /// <summary>
+        /// SOCKS4 proxy.
+        /// </summary>
         Socks4,
+
+        /// <summary>
+        /// SOCKS4a proxy.
+        /// </summary>
         Socks4a,
+
+        /// <summary>
+        /// SOCKS5 proxy.
+        /// </summary>
         Socks5
     }
 }

src/GameFrameX.SuperSocket.Client.Proxy/Socks4Connector.cs

@@ -2,8 +2,18 @@
 
 namespace GameFrameX.SuperSocket.Client.Proxy
 {
+    /// <summary>
+    /// Represents a connector for SOCKS4 proxy connections.
+    /// </summary>
     public class Socks4Connector : ConnectorBase
     {
+        /// <summary>
+        /// Connects to the specified remote endpoint through the SOCKS4 proxy.
+        /// </summary>
+        /// <param name="remoteEndPoint">The remote endpoint to connect to.</param>
+        /// <param name="state">The connection state.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task representing the asynchronous connection operation.</returns>
         protected override ValueTask<ConnectState> ConnectAsync(EndPoint remoteEndPoint, ConnectState state, CancellationToken cancellationToken)
         {
             throw new NotImplementedException();

src/GameFrameX.SuperSocket.Client.Proxy/Socks5Connector.cs

@@ -47,6 +47,12 @@ public Socks5Connector(EndPoint proxyEndPoint, string username, string password)
             _authenHandshakeRequest = AuthenHandshake;
         }
 
+        /// <summary>
+        /// Connects to the specified remote endpoint through the SOCKS5 proxy.
+        /// </summary>
+        /// <param name="remoteEndPoint">The remote endpoint to connect to.</param>
+        /// <param name="state">The connection state from the previous connector.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
         protected override async ValueTask<ConnectState> ConnectProxyAsync(EndPoint remoteEndPoint, ConnectState state, CancellationToken cancellationToken)
         {
             var connection = state.CreateConnection(new ConnectionOptions { ReadAsDemand = true });
@@ -283,35 +289,76 @@ enum Socket5ResponseType
             AuthEndPoint,
         }
 
+        /// <summary>
+        /// Represents the address type used in SOCKS5 protocol.
+        /// </summary>
         public class Socks5Address
         {
+            /// <summary>
+            /// Gets or sets the IP address.
+            /// </summary>
             public IPAddress IPAddress { get; set; }
 
+            /// <summary>
+            /// Gets or sets the domain name.
+            /// </summary>
             public string DomainName { get; set; }
         }
 
+        /// <summary>
+        /// Represents a SOCKS5 packet.
+        /// </summary>
         public class Socks5Pack
         {
+            /// <summary>
+            /// Gets or sets the version of the SOCKS5 protocol.
+            /// </summary>
             public byte Version { get; set; }
 
+            /// <summary>
+            /// Gets or sets the status of the SOCKS5 connection.
+            /// </summary>
             public byte Status { get; set; }
 
+            /// <summary>
+            /// Gets or sets the reserved byte.
+            /// </summary>
             public byte Reserve { get; set; }
 
+            /// <summary>
+            /// Gets or sets the destination address.
+            /// </summary>
             public Socks5Address DestAddr { get; set; }
 
+            /// <summary>
+            /// Gets or sets the destination port.
+            /// </summary>
             public short DestPort { get; set; }
         }
 
+        /// <summary>
+        /// Represents a pipeline filter for SOCKS5 authentication.
+        /// </summary>
         public class Socks5AuthPipelineFilter : FixedSizePipelineFilter<Socks5Pack>
         {
+            /// <summary>
+            /// Gets or sets the authentication step.
+            /// </summary>
             public int AuthStep { get; set; }
 
+            /// <summary>
+            /// Initializes a new instance of the <see cref="Socks5AuthPipelineFilter"/> class.
+            /// </summary>
             public Socks5AuthPipelineFilter()
                 : base(2)
             {
+
             }
 
+            /// <summary>
+            /// Gets the body length from the header.
+            /// </summary>
+            /// <param name="buffer">The buffer containing the header.</param>
             protected override Socks5Pack DecodePackage(ref ReadOnlySequence<byte> buffer)
             {
                 var reader = new SequenceReader<byte>(buffer);
@@ -331,13 +378,24 @@ protected override Socks5Pack DecodePackage(ref ReadOnlySequence<byte> buffer)
             }
         }
 
+        /// <summary>
+        /// Represents a pipeline filter for SOCKS5 address.
+        /// </summary>
         public class Socks5AddressPipelineFilter : FixedHeaderPipelineFilter<Socks5Pack>
         {
+            /// <summary>
+            /// Initializes a new instance of the <see cref="Socks5AddressPipelineFilter"/> class.
+            /// </summary>
             public Socks5AddressPipelineFilter()
                 : base(5)
             {
+
             }
 
+            /// <summary>
+            /// Gets the body length from the header.
+            /// </summary>
+            /// <param name="buffer">The buffer containing the header.</param>
             protected override int GetBodyLengthFromHeader(ref ReadOnlySequence<byte> buffer)
             {
                 var reader = new SequenceReader<byte>(buffer);
@@ -359,6 +417,10 @@ protected override int GetBodyLengthFromHeader(ref ReadOnlySequence<byte> buffer
                 throw new Exception($"Unsupported addressType: {addressType}");
             }
 
+            /// <summary>
+            /// Decodes the package from the buffer.
+            /// </summary>
+            /// <param name="buffer">The buffer containing the package data.</param>
             protected override Socks5Pack DecodePackage(ref ReadOnlySequence<byte> buffer)
             {
                 var reader = new SequenceReader<byte>(buffer);

src/GameFrameX.SuperSocket.Client/ConnectState.cs

@@ -1,12 +1,20 @@
+using System;
+using System.IO;
 using System.Net.Sockets;
 using GameFrameX.SuperSocket.Connection;
 using GameFrameX.SuperSocket.Connection.Sockets;
 using Microsoft.Extensions.ObjectPool;
 
 namespace GameFrameX.SuperSocket.Client
 {
+    /// <summary>
+    /// Represents the state of a connection, including its result, socket, and stream.
+    /// </summary>
     public class ConnectState
     {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConnectState"/> class.
+        /// </summary>
         public ConnectState()
         {
         }
@@ -16,16 +24,34 @@ private ConnectState(bool cancelled)
             Cancelled = cancelled;
         }
 
+        /// <summary>
+        /// Gets or sets a value indicating whether the connection was successful.
+        /// </summary>
         public bool Result { get; set; }
 
+        /// <summary>
+        /// Gets a value indicating whether the connection was cancelled.
+        /// </summary>
         public bool Cancelled { get; private set; }
 
+        /// <summary>
+        /// Gets or sets the exception that occurred during the connection attempt, if any.
+        /// </summary>
         public Exception Exception { get; set; }
 
+        /// <summary>
+        /// Gets or sets the socket associated with the connection.
+        /// </summary>
         public Socket Socket { get; set; }
 
+        /// <summary>
+        /// Gets or sets the stream associated with the connection.
+        /// </summary>
         public Stream Stream { get; set; }
 
+        /// <summary>
+        /// Represents a connection state that indicates the connection was cancelled.
+        /// </summary>
         public static readonly ConnectState CancelledState = new ConnectState(false);
 
         private static Lazy<ObjectPool<SocketSender>> _socketSenderPool = new Lazy<ObjectPool<SocketSender>>(() =>
@@ -35,14 +61,19 @@ private ConnectState(bool cancelled)
             return pool;
         });
 
+        /// <summary>
+        /// Creates a connection object based on the current state.
+        /// </summary>
+        /// <param name="connectionOptions">The connection options to use.</param>
+        /// <returns>An <see cref="IConnection"/> object representing the connection.</returns>
         public IConnection CreateConnection(ConnectionOptions connectionOptions)
         {
             var stream = this.Stream;
             var socket = this.Socket;
 
             if (stream != null)
             {
-                return new StreamPipeConnection(stream, socket.RemoteEndPoint, socket.LocalEndPoint, connectionOptions);
+                return new StreamPipeConnection(stream , socket.RemoteEndPoint, socket.LocalEndPoint, connectionOptions);
             }
             else
             {