Refactor IPAM model classes to use records for Address, Subnetwork, Vlan, Vrf, Section, Tag, Domain, Nameserver, and Session; enhance documentation and implement value equality for records.

classlib/Helpers/SessionManager.cs

@@ -1,44 +1,60 @@
 namespace PS.IPAM.Helpers;
+
 using System;
 using System.Management.Automation;
 using System.Net.Http;
 using System.Net.Http.Headers;
+using System.Runtime.InteropServices;
 using System.Text;
 using System.Threading.Tasks;
 using Newtonsoft.Json;
-using PS.IPAM;
 
+/// <summary>
+/// Manages phpIPAM API sessions including creation, validation, and lifecycle.
+/// </summary>
 public static class SessionManager
 {
     private static Session? _currentSession;
 
+    /// <summary>
+    /// Gets or sets the current active session.
+    /// </summary>
     public static Session? CurrentSession
     {
         get => _currentSession;
         set => _currentSession = value;
     }
 
-    public static string TestSession()
+    /// <summary>
+    /// Tests the current session status.
+    /// </summary>
+    /// <returns>The session status indicating validity or issues.</returns>
+    public static SessionStatus GetSessionStatus()
     {
         if (_currentSession == null)
         {
-            return "NoToken";
+            return SessionStatus.NoSession;
         }
 
         if (_currentSession.Expires == null)
         {
-            return "Valid";
+            return SessionStatus.Valid;
         }
 
-        if (_currentSession.Expires < DateTime.Now)
-        {
-            return "Expired";
-        }
-
-        return "Valid";
+        return _currentSession.Expires < DateTime.Now
+            ? SessionStatus.Expired
+            : SessionStatus.Valid;
     }
 
-    public static async Task<Session> CreateSessionWithCredentials(
+    /// <summary>
+    /// Creates a new session using username/password credentials.
+    /// </summary>
+    /// <param name="url">The phpIPAM server URL.</param>
+    /// <param name="appId">The API application ID.</param>
+    /// <param name="credentials">The PowerShell credential object.</param>
+    /// <param name="ignoreSsl">Whether to ignore SSL certificate errors.</param>
+    /// <returns>The created session.</returns>
+    public static async Task<Session> CreateSessionWithCredentialsAsync(
         string url,
         string appId,
         PSCredential credentials,
@@ -46,7 +62,7 @@ public static class SessionManager
     {
         var uri = $"{url}/api/{appId}/user";
         var auth = Convert.ToBase64String(
-            Encoding.UTF8.GetBytes($"{credentials.UserName}:{GetPassword(credentials)}"));
+            Encoding.UTF8.GetBytes($"{credentials.UserName}:{GetPasswordString(credentials)}"));
 
         using var client = CreateHttpClient(ignoreSsl);
         client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
@@ -58,14 +74,15 @@ public static class SessionManager
 
         if (jsonResponse?.success != true)
         {
-            throw new Exception(jsonResponse?.error?.ToString() ?? "Failed to create session");
+            throw new InvalidOperationException(
+                jsonResponse?.error?.ToString() ?? "Failed to create session");
         }
 
         var token = jsonResponse.data.token.ToString();
         var expires = DateTime.Parse(jsonResponse.data.expires.ToString());
 
         _currentSession = new Session(
-            AuthType.credentials,
+            AuthType.Credentials,
             token,
             appId,
             url,
@@ -76,13 +93,17 @@ public static class SessionManager
         return _currentSession;
     }
 
-    public static Session CreateSessionWithToken(
-        string url,
-        string appId,
-        string token)
+    /// <summary>
+    /// Creates a new session using a static API token.
+    /// </summary>
+    /// <param name="url">The phpIPAM server URL.</param>
+    /// <param name="appId">The API application ID.</param>
+    /// <param name="token">The API token.</param>
+    /// <returns>The created session.</returns>
+    public static Session CreateSessionWithToken(string url, string appId, string token)
     {
         _currentSession = new Session(
-            AuthType.token,
+            AuthType.Token,
             token,
             appId,
             url,
@@ -93,24 +114,20 @@ public static class SessionManager
         return _currentSession;
     }
 
+    /// <summary>
+    /// Closes the current session and clears session data.
+    /// </summary>
     public static void CloseSession()
     {
         _currentSession = null;
     }
 
-    private static string GetPassword(PSCredential credential)
-    {
-        var ptr = System.Runtime.InteropServices.Marshal.SecureStringToBSTR(credential.Password);
-        try
-        {
-            return System.Runtime.InteropServices.Marshal.PtrToStringBSTR(ptr);
-        }
-        finally
-        {
-            System.Runtime.InteropServices.Marshal.ZeroFreeBSTR(ptr);
-        }
-    }
-
+    /// <summary>
+    /// Creates an HttpClient with optional SSL bypass.
+    /// </summary>
+    /// <param name="ignoreSsl">Whether to ignore SSL certificate errors.</param>
+    /// <param name="handler">Optional custom message handler for testing.</param>
+    /// <returns>A configured HttpClient instance.</returns>
     public static HttpClient CreateHttpClient(bool ignoreSsl = false, HttpMessageHandler? handler = null)
     {
         if (handler != null)
@@ -122,10 +139,27 @@ public static class SessionManager
         {
             var sslHandler = new HttpClientHandler
             {
-                ServerCertificateCustomValidationCallback = (message, cert, chain, errors) => true
+                ServerCertificateCustomValidationCallback = (_, _, _, _) => true
             };
             return new HttpClient(sslHandler);
         }
+
         return new HttpClient();
     }
+
+    /// <summary>
+    /// Extracts the plain text password from a PSCredential object.
+    /// </summary>
+    private static string GetPasswordString(PSCredential credential)
+    {
+        var ptr = Marshal.SecureStringToBSTR(credential.Password);
+        try
+        {
+            return Marshal.PtrToStringBSTR(ptr);
+        }
+        finally
+        {
+            Marshal.ZeroFreeBSTR(ptr);
+        }
+    }
 }