[修改] Server.Abstractions 增加 XML 文档注释，新增 ConsoleConnection 监听器/工厂，扩展会话容器、主机构建器和中间件接口

Author: AlianBlank

src/GameFrameX.SuperSocket.Server.Abstractions/AsyncEventHandler.cs

@@ -3,11 +3,32 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions
 {
+    /// <summary>
+    /// Represents an asynchronous event handler.
+    /// </summary>
+    /// <param name="sender">The source of the event.</param>
+    /// <param name="e">The event data.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public delegate ValueTask AsyncEventHandler(object sender, EventArgs e);
 
+    /// <summary>
+    /// Represents an asynchronous event handler with a specific event argument type.
+    /// </summary>
+    /// <typeparam name="TEventArgs">The type of the event data.</typeparam>
+    /// <param name="sender">The source of the event.</param>
+    /// <param name="e">The event data.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public delegate ValueTask AsyncEventHandler<TEventArgs>(object sender, TEventArgs e)
         where TEventArgs : EventArgs;
 
+    /// <summary>
+    /// Represents an asynchronous event handler with specific sender and event argument types.
+    /// </summary>
+    /// <typeparam name="TSender">The type of the event sender.</typeparam>
+    /// <typeparam name="TEventArgs">The type of the event data.</typeparam>
+    /// <param name="sender">The source of the event.</param>
+    /// <param name="e">The event data.</param>
+    /// <returns>A task that represents the asynchronous operation.</returns>
     public delegate ValueTask AsyncEventHandler<TSender, TEventArgs>(TSender sender, TEventArgs e)
         where TSender : class
         where TEventArgs : EventArgs;

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/ConsoleConnectionFactory.cs

@@ -0,0 +1,34 @@
+using GameFrameX.SuperSocket.Connection;
+using SuperSocket.Connection;
+
+namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
+{
+    /// <summary>
+    /// Factory for creating console connections.
+    /// </summary>
+    public class ConsoleConnectionFactory : IConnectionFactory
+    {
+        private readonly ConnectionOptions _connectionOptions;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConsoleConnectionFactory"/> class.
+        /// </summary>
+        /// <param name="connectionOptions">The connection options.</param>
+        public ConsoleConnectionFactory(ConnectionOptions connectionOptions)
+        {
+            _connectionOptions = connectionOptions;
+        }
+
+        /// <summary>
+        /// Creates a console connection.
+        /// </summary>
+        /// <param name="connection">The connection object (ignored for console connections).</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous creation operation.</returns>
+        public Task<IConnection> CreateConnection(object connection, CancellationToken cancellationToken)
+        {
+            var consoleConnection = new ConsoleConnection(_connectionOptions);
+            return Task.FromResult<IConnection>(consoleConnection);
+        }
+    }
+}

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/ConsoleConnectionListener.cs

@@ -0,0 +1,115 @@
+using GameFrameX.SuperSocket.Connection;
+using Microsoft.Extensions.Logging;
+
+namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
+{
+    /// <summary>
+    /// Listener for console connections that immediately creates a single connection.
+    /// </summary>
+    public class ConsoleConnectionListener : IConnectionListener
+    {
+        private readonly ILogger _logger;
+        private bool _isRunning;
+        private IConnection _consoleConnection;
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="ConsoleConnectionListener"/> class.
+        /// </summary>
+        /// <param name="options">The options for the listener.</param>
+        /// <param name="connectionFactory">The factory for creating connections.</param>
+        /// <param name="logger">The logger for logging events.</param>
+        public ConsoleConnectionListener(ListenOptions options, IConnectionFactory connectionFactory, ILogger logger)
+        {
+            Options = options;
+            ConnectionFactory = connectionFactory;
+            _logger = logger;
+        }
+
+        /// <inheritdoc/>
+        public ListenOptions Options { get; }
+
+        /// <inheritdoc/>
+        public IConnectionFactory ConnectionFactory { get; }
+
+        /// <inheritdoc/>
+        public bool IsRunning => _isRunning;
+
+        /// <inheritdoc/>
+        public event NewConnectionAcceptHandler NewConnectionAccept;
+
+        /// <inheritdoc/>
+        public bool Start()
+        {
+            if (_isRunning)
+                return true;
+
+            try
+            {
+                _isRunning = true;
+                
+                // Create the console connection immediately
+                _ = Task.Run(async () =>
+                {
+                    try
+                    {
+                        _consoleConnection = await ConnectionFactory.CreateConnection(null, default).ConfigureAwait(false);
+                        
+                        if (_consoleConnection != null && NewConnectionAccept != null)
+                        {
+                            await NewConnectionAccept(Options, _consoleConnection).ConfigureAwait(false);
+                        }
+                    }
+                    catch (Exception ex)
+                    {
+                        _logger?.LogError(ex, "Failed to create console connection");
+                    }
+                });
+
+                _logger?.LogInformation("Console connection listener started");
+                return true;
+            }
+            catch (Exception ex)
+            {
+                _logger?.LogError(ex, "Failed to start console connection listener");
+                _isRunning = false;
+                return false;
+            }
+        }
+
+        /// <inheritdoc/>
+        public async Task StopAsync()
+        {
+            if (!_isRunning)
+                return;
+
+            _isRunning = false;
+
+            if (_consoleConnection != null)
+            {
+                try
+                {
+                    await _consoleConnection.CloseAsync(CloseReason.ServerShutdown).ConfigureAwait(false);
+                }
+                catch (Exception ex)
+                {
+                    _logger?.LogWarning(ex, "Error closing console connection during shutdown");
+                }
+                finally
+                {
+                    _consoleConnection = null;
+                }
+            }
+
+            _logger?.LogInformation("Console connection listener stopped");
+        }
+
+        /// <inheritdoc/>
+        public void Dispose()
+        {
+            if (_isRunning)
+            {
+                StopAsync().GetAwaiter().GetResult();
+            }
+        }
+    }
+}

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/ConsoleConnectionListenerFactory.cs

@@ -0,0 +1,21 @@
+using GameFrameX.SuperSocket.Connection;
+using Microsoft.Extensions.Logging;
+
+namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
+{
+    /// <summary>
+    /// Factory for creating console connection listeners.
+    /// </summary>
+    public class ConsoleConnectionListenerFactory : IConnectionListenerFactory
+    {
+        /// <inheritdoc/>
+        public IConnectionListener CreateConnectionListener(ListenOptions options, ConnectionOptions connectionOptions, ILoggerFactory loggerFactory)
+        {
+            connectionOptions.Logger = loggerFactory.CreateLogger(nameof(IConnection));
+            var connectionListenerLogger = loggerFactory.CreateLogger(nameof(ConsoleConnectionListener));
+
+            var connectionFactory = new ConsoleConnectionFactory(connectionOptions);
+            return new ConsoleConnectionListener(options, connectionFactory, connectionListenerLogger);
+        }
+    }
+}

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionFactoryBuilder.cs

@@ -2,8 +2,17 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Defines a builder for creating connection factories.
+    /// </summary>
     public interface IConnectionFactoryBuilder
     {
+        /// <summary>
+        /// Builds a connection factory based on the specified listen and connection options.
+        /// </summary>
+        /// <param name="listenOptions">The options for the listener.</param>
+        /// <param name="connectionOptions">The options for the connection.</param>
+        /// <returns>A connection factory.</returns>
         IConnectionFactory Build(ListenOptions listenOptions, ConnectionOptions connectionOptions);
     }
 }

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionListener.cs

@@ -2,20 +2,49 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Represents a delegate that handles new connection accept events.
+    /// </summary>
+    /// <param name="listenOptions">The options for the listener that accepted the connection.</param>
+    /// <param name="connection">The newly accepted connection.</param>
+    /// <returns>A task that represents the asynchronous handling operation.</returns>
     public delegate ValueTask NewConnectionAcceptHandler(ListenOptions listenOptions, IConnection connection);
 
+    /// <summary>
+    /// Represents a listener for incoming connections.
+    /// </summary>
     public interface IConnectionListener : IDisposable
     {
+        /// <summary>
+        /// Gets the options for the listener.
+        /// </summary>
         ListenOptions Options { get; }
 
+        /// <summary>
+        /// Starts the connection listener.
+        /// </summary>
+        /// <returns><c>true</c> if the listener started successfully; otherwise, <c>false</c>.</returns>
         bool Start();
 
+        /// <summary>
+        /// Occurs when a new connection is accepted.
+        /// </summary>
         event NewConnectionAcceptHandler NewConnectionAccept;
 
+        /// <summary>
+        /// Stops the connection listener asynchronously.
+        /// </summary>
+        /// <returns>A task that represents the asynchronous stop operation.</returns>
         Task StopAsync();
 
+        /// <summary>
+        /// Gets a value indicating whether the listener is running.
+        /// </summary>
         bool IsRunning { get; }
 
+        /// <summary>
+        /// Gets the factory for creating connections.
+        /// </summary>
         IConnectionFactory ConnectionFactory { get; }
     }
 }

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionListenerFactory.cs

@@ -3,8 +3,18 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Defines a factory for creating connection listeners.
+    /// </summary>
     public interface IConnectionListenerFactory
     {
+        /// <summary>
+        /// Creates a connection listener based on the specified options.
+        /// </summary>
+        /// <param name="options">The options for the listener.</param>
+        /// <param name="connectionOptions">The options for the connection.</param>
+        /// <param name="loggerFactory">The factory for creating loggers.</param>
+        /// <returns>A connection listener.</returns>
         IConnectionListener CreateConnectionListener(ListenOptions options, ConnectionOptions connectionOptions, ILoggerFactory loggerFactory);
     }
 }

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionRegister.cs

@@ -1,12 +1,15 @@
-using System;
-using Microsoft.Extensions.Logging;
-using GameFrameX.SuperSocket.ProtoBase;
-using System.Threading.Tasks;
-
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Defines a register for managing connections.
+    /// </summary>
     public interface IConnectionRegister
     {
+        /// <summary>
+        /// Registers a connection asynchronously.
+        /// </summary>
+        /// <param name="connection">The connection to register.</param>
+        /// <returns>A task that represents the asynchronous registration operation.</returns>
         Task RegisterConnection(object connection);
     }
 }

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionStreamInitializer.cs

@@ -5,10 +5,24 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Defines an initializer for connection streams.
+    /// </summary>
     public interface IConnectionStreamInitializer
     {
+        /// <summary>
+        /// Sets up the initializer with the specified listen options.
+        /// </summary>
+        /// <param name="listenOptions">The options for the listener.</param>
         void Setup(ListenOptions listenOptions);
 
+        /// <summary>
+        /// Initializes a connection stream asynchronously.
+        /// </summary>
+        /// <param name="socket">The socket associated with the connection.</param>
+        /// <param name="stream">The existing stream to initialize.</param>
+        /// <param name="cancellationToken">A token to monitor for cancellation requests.</param>
+        /// <returns>A task that represents the asynchronous initialization operation.</returns>
         Task<Stream> InitializeAsync(Socket socket, Stream stream, CancellationToken cancellationToken);
     }
 }

src/GameFrameX.SuperSocket.Server.Abstractions/Connections/IConnectionStreamInitializersFactory.cs

@@ -7,8 +7,16 @@
 
 namespace GameFrameX.SuperSocket.Server.Abstractions.Connections
 {
+    /// <summary>
+    /// Defines a factory for creating connection stream initializers.
+    /// </summary>
     public interface IConnectionStreamInitializersFactory
     {
+        /// <summary>
+        /// Creates a collection of connection stream initializers based on the specified listen options.
+        /// </summary>
+        /// <param name="listenOptions">The options for the listener.</param>
+        /// <returns>A collection of connection stream initializers.</returns>
         IEnumerable<IConnectionStreamInitializer> Create(ListenOptions listenOptions);
     }
 }