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

[Dietmar Maurer <dietmar@proxmox.com>]

I (and also generate.pl) tried to the name for the API definitions to avoid confusion.
On Thursday, 03/12/2026, 11:36, Wolfgang Bumiller <w.bumiller@proxmox.com> wrote:

From : Wolfgang Bumiller <w.bumiller@proxmox.com>
Sent on : Thursday, 03/12/2026, 11:36
To : Dietmar Maurer <dietmar@proxmox.com>
Cc : pve-devel@lists.proxmox.com
Subject : Re: [RFC proxmox 09/22] firewall-api-types: add FirewallRef type
On Mon, Feb 16, 2026 at 11:43:47AM +0100, Dietmar Maurer wrote:

 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 [http://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,


While I'm not strictly against this - wouldn't it be "simpler" to just
rename this to `reference` in the rust type, since we already need the
`serde(rename)` anyway?
Having a user of this type use `foo.r#ref` in the code feels a bit
awkward.


 +
 +    pub scope: String,
 +
 +    #[serde(rename = "type")]
 +    pub ty: FirewallRefType,
 +}
 diff --git a/proxmox-firewall-api-types/src/lib.rs [http://lib.rs/] b/proxmox-firewall-api-types/src/lib.rs [http://lib.rs/]
 index ef672bfe..993115d8 100644
 --- a/proxmox-firewall-api-types/src/lib.rs [http://lib.rs/]
 +++ b/proxmox-firewall-api-types/src/lib.rs [http://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