feat(shared): align models with Proxmox API and fix deserialization issues (#57)

- Update XML documentation across all models to match official API descriptions
- VmConfigLxc: add LXC-specific overrides (arch, memory, ostype, tags, onboot,
  lock, protection) with correct LXC descriptions; fix lxc field type from
  IEnumerable<string> to IEnumerable<string[]> to match [[key,val],...] format
- NodeVmBase: use generic descriptions for status/name shared between QEMU and LXC
- NodeStorageContent: change Encrypted from string to bool (PBS fingerprint support)
- ResultExtension: fix CustomBooleanJsonConverter to handle non-numeric strings
  (e.g. fingerprints) by returning true instead of throwing an exception
- NodeStatus: add boot-info and current-kernel nested models
- NodeTask: add pstart field
- ClusterExtension: add GetWebUrl() extension method for ClusterResource
- bump version to 9.1.5

Author: franklupo

Directory.Packages.props

@@ -4,7 +4,7 @@
         <TargetFrameworks>net8.0;net9.0;net10.0;netstandard2.0</TargetFrameworks>
         <LangVersion>latest</LangVersion>
         <ImplicitUsings>enable</ImplicitUsings>
-        <Version>9.1.4</Version>
+        <Version>9.1.5</Version>
         <!-- <NoWarn>$(NoWarn);CS1591;CS0436</NoWarn> -->
         <Company>Corsinvest Srl</Company>
         <Authors>Corsinvest Srl</Authors>

src/Corsinvest.ProxmoxVE.Api.Extension/Utils/InfoHelper.cs

@@ -17,6 +17,7 @@ namespace Corsinvest.ProxmoxVE.Api.Extension.Utils;
 /// <summary>
 /// Global Info
 /// </summary>
+[Obsolete("This class is deprecated and will be removed in future versions. It is recommended to use specific API calls to retrieve the necessary information instead of relying on a global info collection.")]
 public static class InfoHelper
 {
     /// <summary>

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Access/AccessAcl.cs

@@ -13,9 +13,8 @@ namespace Corsinvest.ProxmoxVE.Api.Shared.Models.Access;
 public class AccessAcl: ModelBase
 {
     /// <summary>
-    /// Path
+    /// Access control path
     /// </summary>
-    /// <value></value>
     [JsonProperty("path")]
     public string Path { get; set; }
 
@@ -34,9 +33,8 @@ public class AccessAcl: ModelBase
     public string UsersGroupid { get; set; }
 
     /// <summary>
-    /// Propagate
+    /// Allow to propagate (inherit) permissions.
     /// </summary>
-    /// <value></value>
     [JsonProperty("propagate")]
     public int Propagate { get; set; }
 

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Access/AccessDomain.cs

@@ -20,9 +20,8 @@ public class AccessDomain : ModelBase
     public string Realm { get; set; }
 
     /// <summary>
-    /// Comment
+    /// A comment. The GUI use this text when you select a domain (Realm) on the login window.
     /// </summary>
-    /// <value></value>
     [JsonProperty("comment")]
     public string Comment { get; set; }
 
@@ -32,4 +31,10 @@ public class AccessDomain : ModelBase
     /// <value></value>
     [JsonProperty("type")]
     public string Type { get; set; }
+
+    /// <summary>
+    /// Two-factor authentication provider.
+    /// </summary>
+    [JsonProperty("tfa")]
+    public string Tfa { get; set; }
 }

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Access/AccessGroup.cs

@@ -20,9 +20,8 @@ public class AccessGroup : ModelBase
     public string Id { get; set; }
 
     /// <summary>
-    /// Users
+    /// list of users which form this group
     /// </summary>
-    /// <value></value>
     [JsonProperty("users")]
     public string Users { get; set; }
 

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Access/AccessTfa.cs

@@ -13,9 +13,8 @@ namespace Corsinvest.ProxmoxVE.Api.Shared.Models.Access;
 public class AccessTfa : ModelBase
 {
     /// <summary>
-    /// User id
+    /// User this entry belongs to.
     /// </summary>
-    /// <value></value>
     [JsonProperty("userid")]
     public string UserId { get; set; }
 
@@ -26,6 +25,18 @@ public class AccessTfa : ModelBase
     [JsonProperty("entries")]
     public IEnumerable<AccessTfaEntry> Entries { get; set; }
 
+    /// <summary>
+    /// Contains a timestamp until when a user is locked out of 2nd factors.
+    /// </summary>
+    [JsonProperty("tfa-locked-until")]
+    public long? TfaLockedUntil { get; set; }
+
+    /// <summary>
+    /// True if the user is currently locked out of TOTP factors.
+    /// </summary>
+    [JsonProperty("totp-locked")]
+    public bool TotpLocked { get; set; }
+
     /// <summary>
     /// TFA Entry
     /// </summary>

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Access/AccessUser.cs

@@ -13,23 +13,20 @@ namespace Corsinvest.ProxmoxVE.Api.Shared.Models.Access;
 public class AccessUser : ModelBase
 {
     /// <summary>
-    /// Enabled
+    /// Enable the account (default). You can set this to '0' to disable the account
     /// </summary>
-    /// <value></value>
     [JsonProperty("enable")]
-    public int Enable { get; set; }
+    public bool Enable { get; set; }
 
     /// <summary>
-    /// Id
+    /// Full User ID, in the `name@realm` format.
     /// </summary>
-    /// <value></value>
     [JsonProperty("userid")]
     public string Id { get; set; }
 
     /// <summary>
-    /// Expire
+    /// Account expiration date (seconds since epoch). '0' means no expiration date.
     /// </summary>
-    /// <value></value>
     [JsonProperty("expire")]
     public int Expire { get; set; }
 
@@ -47,7 +44,37 @@ public class AccessUser : ModelBase
     public string Comment { get; set; }
 
     /// <summary>
-    /// Realm Type
+    /// First name.
+    /// </summary>
+    [JsonProperty("firstname")]
+    public string Firstname { get; set; }
+
+    /// <summary>
+    /// Last name.
+    /// </summary>
+    [JsonProperty("lastname")]
+    public string Lastname { get; set; }
+
+    /// <summary>
+    /// Keys for two factor auth (yubico).
+    /// </summary>
+    [JsonProperty("keys")]
+    public string Keys { get; set; }
+
+    /// <summary>
+    /// Contains a timestamp until when a user is locked out of 2nd factors.
+    /// </summary>
+    [JsonProperty("tfa-locked-until")]
+    public long? TfaLockedUntil { get; set; }
+
+    /// <summary>
+    /// True if the user is currently locked out of TOTP factors.
+    /// </summary>
+    [JsonProperty("totp-locked")]
+    public bool TotpLocked { get; set; }
+
+    /// <summary>
+    /// The type of the users realm
     /// </summary>
     [JsonProperty("realm-type")]
     public string RealmType { get; set; }
@@ -76,7 +103,7 @@ public class Token
         public string Id { get; set; }
 
         /// <summary>
-        /// Expire
+        /// Account expiration date (seconds since epoch). '0' means no expiration date.
         /// </summary>
         [JsonProperty("expire")]
         public int Expire { get; set; }

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Cluster/ClusterExtension.cs

@@ -126,6 +126,20 @@ public static IEnumerable<string> GetDefaultColumns()
             nameof(ClusterResource.Uptime)
         ];
 
+    /// <summary>
+    /// Get web URL path for a cluster resource
+    /// </summary>
+    public static string GetWebUrl(this ClusterResource resource)
+        => resource.ResourceType switch
+        {
+            ClusterResourceType.Node    => PveWebUrlHelper.GetWebUrlNode(resource.Node),
+            ClusterResourceType.Storage => PveWebUrlHelper.GetWebUrlStorage(resource.Node, resource.Storage),
+            ClusterResourceType.Pool    => PveWebUrlHelper.GetWebUrlPool(resource.Pool),
+            ClusterResourceType.Vm when resource.VmType == VmType.Qemu => PveWebUrlHelper.GetWebUrlQemu(resource.Node, resource.VmId),
+            ClusterResourceType.Vm when resource.VmType == VmType.Lxc  => PveWebUrlHelper.GetWebUrlLxc(resource.Node, resource.VmId),
+            _ => string.Empty,
+        };
+
     /// <summary>
     /// Column for VM/CT
     /// </summary>

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Cluster/ClusterHaResource.cs

@@ -47,4 +47,21 @@ public class ClusterHaResource : ModelBase
     /// </summary>
     [JsonProperty("comment")]
     public string Comment { get; set; }
-}
+    /// <summary>
+    /// Failback.
+    /// </summary>
+    [JsonProperty("failback")]
+    public bool Failback { get; set; }
+
+    /// <summary>
+    /// Max relocate.
+    /// </summary>
+    [JsonProperty("max_relocate")]
+    public int MaxRelocate { get; set; }
+
+    /// <summary>
+    /// Max restart.
+    /// </summary>
+    [JsonProperty("max_restart")]
+    public int MaxRestart { get; set; }
+}

src/Corsinvest.ProxmoxVE.Api.Shared/Models/Cluster/ClusterHaStatusCurrent.cs

@@ -13,80 +13,80 @@ namespace Corsinvest.ProxmoxVE.Api.Shared.Models.Cluster;
 public class ClusterHaStatusCurrent : ModelBase
 {
     /// <summary>
-    /// Id
+    /// Status entry ID (quorum, master, lrm:&lt;node&gt;, service:&lt;sid&gt;).
     /// </summary>
     [JsonProperty("id")]
     public string Id { get; set; }
 
     /// <summary>
-    /// Node
+    /// Node associated to status entry.
     /// </summary>
     [JsonProperty("node")]
     public string Node { get; set; }
 
     /// <summary>
-    /// Quorate
+    /// For type 'quorum'. Whether the cluster is quorate or not.
     /// </summary>
     [JsonProperty("quorate")]
-    public int Quorate { get; set; }
+    public bool Quorate { get; set; }
 
     /// <summary>
-    /// Status
+    /// Status of the entry (value depends on type).
     /// </summary>
     [JsonProperty("status")]
     public string Status { get; set; }
 
     /// <summary>
-    /// Type
+    /// Type of status entry.
     /// </summary>
     [JsonProperty("type")]
     public string Type { get; set; }
 
     /// <summary>
-    /// Timestamp
+    /// For type 'lrm','master'. Timestamp of the status information.
     /// </summary>
     [JsonProperty("timestamp")]
     public long Timestamp { get; set; }
 
     /// <summary>
-    /// CrmState
+    /// For type 'service'. Service state as seen by the CRM.
     /// </summary>
     [JsonProperty("crm_state")]
     public string CrmState { get; set; }
 
     /// <summary>
-    /// Group
-    /// </summary>
-    [JsonProperty("group")]
-    public string Group { get; set; }
-
-    /// <summary>
-    /// MaxRelocate
+    /// For type 'service'.
     /// </summary>
     [JsonProperty("max_relocate")]
     public int MaxRelocate { get; set; }
 
     /// <summary>
-    /// MaxRestart
+    /// For type 'service'.
     /// </summary>
     [JsonProperty("max_restart")]
     public int MaxRestart { get; set; }
 
     /// <summary>
-    /// RequestState
+    /// For type 'service'. Requested service state.
     /// </summary>
     [JsonProperty("request_state")]
     public string RequestState { get; set; }
 
     /// <summary>
-    /// Sid
+    /// For type 'service'. Service ID.
     /// </summary>
     [JsonProperty("sid")]
     public string Sid { get; set; }
 
     /// <summary>
-    /// State
+    /// For type 'service'. Verbose service state.
     /// </summary>
     [JsonProperty("state")]
     public string State { get; set; }
+
+    /// <summary>
+    /// The HA resource is automatically migrated to the node with the highest priority according to their node affinity rule, if a node with a higher priority than the current node comes online.
+    /// </summary>
+    [JsonProperty("failback")]
+    public bool Failback { get; set; }
 }