From 3363f1e917531cb9d19a0eaf4c86e91393e5033c Mon Sep 17 00:00:00 2001 From: Extremelyd1 <10898310+Extremelyd1@users.noreply.github.com> Date: Wed, 12 Feb 2025 19:45:59 +0100 Subject: [PATCH] Add missing documentation to changed files in connection refactor --- .../Client/ClientConnectionManager.cs | 47 ++++++++++++++++--- .../Client/ClientConnectionStatus.cs | 12 +++++ .../Client/ConnectionFailedResult.cs | 34 ++++++++++++-- HKMP/Networking/ConnectionManager.cs | 2 +- HKMP/Networking/Server/NetServer.cs | 20 +++++++- .../Server/ServerConnectionManager.cs | 41 ++++++++++++++++ HKMP/Networking/UdpUpdateManager.cs | 3 +- 7 files changed, 144 insertions(+), 15 deletions(-) diff --git a/HKMP/Networking/Client/ClientConnectionManager.cs b/HKMP/Networking/Client/ClientConnectionManager.cs index 84f4493..6af5524 100644 --- a/HKMP/Networking/Client/ClientConnectionManager.cs +++ b/HKMP/Networking/Client/ClientConnectionManager.cs @@ -8,12 +8,28 @@ namespace Hkmp.Networking.Client; +/// +/// Client-side manager for handling the initial connection to the server. +/// internal class ClientConnectionManager : ConnectionManager { + /// + /// The client-side chunk sender used to handle sending chunks. + /// private readonly ClientChunkSender _chunkSender; + /// + /// The client-side chunk received used to receive chunks. + /// private readonly ClientChunkReceiver _chunkReceiver; + /// + /// Event that is called when server info is received from the server we are trying to connect to. + /// public event Action ServerInfoReceivedEvent; + /// + /// Construct the connection manager with the given packet manager and chunk sender, and receiver instances. + /// Will register handlers in the packet manager that relate to the connection. + /// public ClientConnectionManager( PacketManager packetManager, ClientChunkSender chunkSender, @@ -29,40 +45,57 @@ ClientChunkReceiver chunkReceiver _chunkReceiver.ChunkReceivedEvent += OnChunkReceived; } + /// + /// Start establishing the connection to the server with the given information. + /// + /// The username of the player. + /// The authentication key of the player. + /// List of addon data that represents the enabled networked addons that the client uses. + /// public void StartConnection(string username, string authKey, List addonData) { Logger.Debug("StartConnection"); - SendUserInfo(username, authKey, addonData); - } - - private void SendUserInfo(string username, string authKey, List addonData) { + // Create a connection packet that will be the entire chunk we will be sending var connectionPacket = new ServerConnectionPacket(); - + + // Set the client info data in the connection packet connectionPacket.SetSendingPacketData(ServerConnectionPacketId.ClientInfo, new ClientInfo { Username = username, AuthKey = authKey, AddonData = addonData }); + // Create the raw packet from the connection packet var packet = new Packet.Packet(); connectionPacket.CreatePacket(packet); + // Enqueue the raw packet to be sent using the chunk sender _chunkSender.EnqueuePacket(packet); } + /// + /// Callback method for when server info is received from the server. + /// + /// The server info instance received from the server. private void OnServerInfoReceived(ServerInfo serverInfo) { Logger.Debug($"ServerInfo received, connection accepted: {serverInfo.ConnectionResult}"); ServerInfoReceivedEvent?.Invoke(serverInfo); } - + + /// + /// Callback method for when a new chunk is received from the server. + /// + /// The raw packet that contains the data from the chunk. private void OnChunkReceived(Packet.Packet packet) { + // Create the connection packet instance and try to read it var connectionPacket = new ClientConnectionPacket(); if (!connectionPacket.ReadPacket(packet)) { Logger.Debug("Received malformed connection packet chunk from server"); return; } - + + // Let the packet manager handle the connection packet, which will invoke the relevant data handlers PacketManager.HandleClientConnectionPacket(connectionPacket); } } diff --git a/HKMP/Networking/Client/ClientConnectionStatus.cs b/HKMP/Networking/Client/ClientConnectionStatus.cs index 438e52d..aaad49e 100644 --- a/HKMP/Networking/Client/ClientConnectionStatus.cs +++ b/HKMP/Networking/Client/ClientConnectionStatus.cs @@ -1,7 +1,19 @@ namespace Hkmp.Networking.Client; +/// +/// Enumeration of connection statuses for the client. +/// internal enum ClientConnectionStatus { + /// + /// Not connected to any server. + /// NotConnected, + /// + /// Trying to establish a connection to a server. + /// Connecting, + /// + /// Connected to a server. + /// Connected } diff --git a/HKMP/Networking/Client/ConnectionFailedResult.cs b/HKMP/Networking/Client/ConnectionFailedResult.cs index 46e66c3..64178a3 100644 --- a/HKMP/Networking/Client/ConnectionFailedResult.cs +++ b/HKMP/Networking/Client/ConnectionFailedResult.cs @@ -7,30 +7,54 @@ namespace Hkmp.Networking.Client; /// Class that encapsulates the result of a failed connection. /// internal class ConnectionFailedResult { - public ConnectionFailedReason Reason { get; set; } + /// + /// The reason that the connection failed. + /// + public ConnectionFailedReason Reason { get; init; } } /// /// Specialization class of for invalid addons. /// internal class ConnectionInvalidAddonsResult : ConnectionFailedResult { - public List AddonData { get; set; } + /// + /// The list of addon data that the server uses to compare against for clients. + /// + public List AddonData { get; init; } } /// /// Specialization class of for a generic failed connection with message. /// internal class ConnectionFailedMessageResult : ConnectionFailedResult { - public string Message { get; set; } + /// + /// The string message that describes the reason the connection failed. + /// + public string Message { get; init; } } /// /// Enumeration of reasons why the connection failed. /// internal enum ConnectionFailedReason { + /// + /// The client and server addon do not match. + /// InvalidAddons, - Other, + /// + /// The connection timed out (took too long to establish). + /// TimedOut, + /// + /// A socket exception occurred while trying to establish the connection. + /// SocketException, - IOException + /// + /// An IO exception occurred while trying to establish the connection. + /// + IOException, + /// + /// The reason is miscellaneous. + /// + Other, } diff --git a/HKMP/Networking/ConnectionManager.cs b/HKMP/Networking/ConnectionManager.cs index eb40025..bf85728 100644 --- a/HKMP/Networking/ConnectionManager.cs +++ b/HKMP/Networking/ConnectionManager.cs @@ -3,7 +3,7 @@ namespace Hkmp.Networking; /// -/// Class that manages sending packets while establishing connection to a server. +/// Abstract base class that manages handling the initial connection to a server. /// internal abstract class ConnectionManager { /// diff --git a/HKMP/Networking/Server/NetServer.cs b/HKMP/Networking/Server/NetServer.cs index 77114a9..167e92e 100644 --- a/HKMP/Networking/Server/NetServer.cs +++ b/HKMP/Networking/Server/NetServer.cs @@ -50,6 +50,9 @@ internal class NetServer : INetServer { /// private readonly ConcurrentDictionary _throttledClients; + /// + /// Concurrent queue that contains received data from a client ready for processing. + /// private readonly ConcurrentQueue _receivedQueue; /// @@ -272,6 +275,13 @@ private void HandleClientPackets(NetServerClient client, List pac } } + /// + /// Callback method for when a connection request is received. + /// + /// The ID of the client. + /// The client info instance containing details about the client. + /// The server info instance that should be modified to reflect whether the client's + /// connection is accepted or not. private void OnConnectionRequest(ushort clientId, ClientInfo clientInfo, ServerInfo serverInfo) { if (!_clientsById.TryGetValue(clientId, out var client)) { Logger.Error($"Connection request for client without known ID: {clientId}"); @@ -305,7 +315,12 @@ private void OnConnectionRequest(ushort clientId, ClientInfo clientInfo, ServerI }); } } - + + /// + /// Callback method for when client info is received in a connection packet. + /// + /// The ID of the client that sent the client info. + /// The client info instance. private void OnClientInfoReceived(ushort clientId, ClientInfo clientInfo) { if (!_clientsById.TryGetValue(clientId, out var client)) { Logger.Error($"ClientInfo received from client without known ID: {clientId}"); @@ -468,6 +483,9 @@ Func packetInstantiator /// Data class for storing received data from a given IP end-point. /// internal class ReceivedData { + /// + /// The DTLS server client that sent this data. + /// public DtlsServerClient DtlsServerClient { get; init; } /// diff --git a/HKMP/Networking/Server/ServerConnectionManager.cs b/HKMP/Networking/Server/ServerConnectionManager.cs index 2e8b691..8103d10 100644 --- a/HKMP/Networking/Server/ServerConnectionManager.cs +++ b/HKMP/Networking/Server/ServerConnectionManager.cs @@ -8,15 +8,36 @@ namespace Hkmp.Networking.Server; +/// +/// Server-side manager for handling the initial connection to a new client. +/// internal class ServerConnectionManager : ConnectionManager { + /// + /// Server-side chunk sender used to handle sending chunks. + /// private readonly ServerChunkSender _chunkSender; + /// + /// Server-side chunk received used to receive chunks. + /// private readonly ServerChunkReceiver _chunkReceiver; + /// + /// The ID of the client that this class manages. + /// private readonly ushort _clientId; + /// + /// Timer that triggers when the connection takes too long and thus times out. + /// private readonly Timer _timeoutTimer; + /// + /// Event that is called when the client has sent the client info, and thus we can check the connection request. + /// public event Action ConnectionRequestEvent; + /// + /// Event that is called when the connection times out. + /// public event Action ConnectionTimeoutEvent; public ServerConnectionManager( @@ -39,22 +60,37 @@ ushort clientId _chunkReceiver.ChunkReceivedEvent += OnChunkReceived; } + /// + /// Start accepting connections, which will start the timeout timer. + /// public void StartAcceptingConnection() { Logger.Debug("StartAcceptingConnection"); _timeoutTimer.Start(); } + /// + /// Stop accepting connections, which will stop the timeout timer. + /// public void StopAcceptingConnection() { Logger.Debug("StopAcceptingConnection"); _timeoutTimer.Stop(); } + /// + /// Finish up the connection and execute the given callback when it is finished. + /// + /// The action to execute when the connection is finished. public void FinishConnection(Action callback) { _chunkSender.FinishSendingData(callback); } + /// + /// Process the given (received) client info. This will invoke the and + /// communicate the resulting server info back to the client. + /// + /// public void ProcessClientInfo(ClientInfo clientInfo) { Logger.Debug($"Received client info from client with ID: {_clientId}"); @@ -75,6 +111,11 @@ public void ProcessClientInfo(ClientInfo clientInfo) { _chunkSender.EnqueuePacket(packet); } + /// + /// Callback method for when a chunk is received. Will construct a connection packet and try to read the chunk + /// into it. If successful, will let the packet manager handle the data in it. + /// + /// The raw packet that contains the data from the chunk. private void OnChunkReceived(Packet.Packet packet) { var connectionPacket = new ServerConnectionPacket(); if (!connectionPacket.ReadPacket(packet)) { diff --git a/HKMP/Networking/UdpUpdateManager.cs b/HKMP/Networking/UdpUpdateManager.cs index ada9934..85d7c1f 100644 --- a/HKMP/Networking/UdpUpdateManager.cs +++ b/HKMP/Networking/UdpUpdateManager.cs @@ -135,7 +135,8 @@ protected UdpUpdateManager() { } /// - /// Start the update manager and allow sending updates. + /// Start the update manager. This will start the send and heartbeat timers, which will respectively trigger + /// sending update packets and trigger on connection timing out. /// public void StartUpdates() { _lastSendRate = CurrentSendRate;