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

[Wolfgang Bumiller <w.bumiller@proxmox.com>]

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         |  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 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