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 <[email protected]>
> ---
> .../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
