[RFC proxmox 09/22] firewall-api-types: add FirewallRef type

[Dietmar Maurer <dietmar@proxmox.com>]

Introduce FirewallRef struct and FirewallRefType enum for representing
firewall address references (aliases and ipsets) with their metadata
(name, reference string, scope, and optional comment).

The FirewallRefType enum includes an UnknownEnumValue variant behind
the "enum-fallback" feature flag for forward compatibility with
unknown variants.

Extracted from Perl API.

Signed-off-by: Dietmar Maurer <dietmar@proxmox.com>
---
 .../src/firewall_ref.rs                       | 62 +++++++++++++++++++
 proxmox-firewall-api-types/src/lib.rs         |  3 +
 2 files changed, 65 insertions(+)
 create mode 100644 proxmox-firewall-api-types/src/firewall_ref.rs

diff --git a/proxmox-firewall-api-types/src/firewall_ref.rs b/proxmox-firewall-api-types/src/firewall_ref.rs
new file mode 100644
index 00000000..483e57ce
--- /dev/null
+++ b/proxmox-firewall-api-types/src/firewall_ref.rs
@@ -0,0 +1,62 @@
+use serde::{Deserialize, Serialize};
+
+#[cfg(feature = "enum-fallback")]
+use proxmox_fixed_string::FixedString;
+use proxmox_schema::api;
+
+#[api]
+/// Firewall address reference type (ipset or alias).
+#[derive(Clone, Copy, Debug, PartialEq, Deserialize, Serialize)]
+pub enum FirewallRefType {
+    #[serde(rename = "alias")]
+    /// alias.
+    Alias,
+    #[serde(rename = "ipset")]
+    /// ipset.
+    Ipset,
+    /// Unknown variants for forward compatibility.
+    #[cfg(feature = "enum-fallback")]
+    #[serde(untagged)]
+    UnknownEnumValue(FixedString),
+}
+
+#[api(
+    properties: {
+        comment: {
+            optional: true,
+            type: String,
+            description: "Descriptive comment",
+        },
+        name: {
+            type: String,
+            description: "The name of the alias or ipset.",
+        },
+        "ref": {
+            type: String,
+            description: "The reference string used in firewall rules.",
+        },
+        scope: {
+            type: String,
+            description: "The scope of the reference (e.g., SDN).",
+        },
+        type: {
+            type: FirewallRefType,
+        },
+    },
+)]
+/// Firewall address reference information.
+#[derive(Clone, Debug, PartialEq, serde::Deserialize, serde::Serialize)]
+pub struct FirewallRef {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub comment: Option<String>,
+
+    pub name: String,
+
+    #[serde(rename = "ref")]
+    pub r#ref: String,
+
+    pub scope: String,
+
+    #[serde(rename = "type")]
+    pub ty: FirewallRefType,
+}
diff --git a/proxmox-firewall-api-types/src/lib.rs b/proxmox-firewall-api-types/src/lib.rs
index ef672bfe..993115d8 100644
--- a/proxmox-firewall-api-types/src/lib.rs
+++ b/proxmox-firewall-api-types/src/lib.rs
@@ -17,3 +17,6 @@ pub use guest_options::FirewallGuestOptions;
 
 mod node_options;
 pub use node_options::FirewallNodeOptions;
+
+mod firewall_ref;
+pub use firewall_ref::{FirewallRef, FirewallRefType};
-- 
2.47.3