[pbs-devel] [PATCH proxmox 1/1] pbs-api-types: add api types for streaming content api call

[Wolfgang Bumiller]

On Fri, Oct 03, 2025 at 10:50:33AM +0200, Dominik Csapak wrote:
> Main point are the two new structs
> * ContentType for api parameter to select a specific type of content to
>   be returned
> * ContentListItem, which contains either
>  - a namespace
>  - a snapshot (including namespace)
>  - a backup group (including namespace)

Random thought: With an "item" in a list of "Things" not being a "Thing"
we still call it a "ThingListItem" 🙄.
Can we rename SnapshotListItem to just Snapshot and GroupListItem to
Group and NamespaceListItem to Namespace?

> 
> Since the enums variants are newtypes, we need to annotate the 'serde
> tag' and given them an 'id-property' and 'id-schema' even though we
> don't need it, since it's only relevant for saving these on disk with
> section config.

Need to update the api macro to make the section-config part opt in
(with a deprecation period at first to not break stuff...)

> 
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
>  pbs-api-types/Cargo.toml       |  1 +
>  pbs-api-types/src/datastore.rs | 99 ++++++++++++++++++++++++++++++++++
>  2 files changed, 100 insertions(+)
> 
> diff --git a/pbs-api-types/Cargo.toml b/pbs-api-types/Cargo.toml
> index 358536d9..b3dee41d 100644
> --- a/pbs-api-types/Cargo.toml
> +++ b/pbs-api-types/Cargo.toml
> @@ -23,5 +23,6 @@ proxmox-lang.workspace=true
>  proxmox-s3-client = { workspace = true, features = [ "api-types" ] }
>  proxmox-schema = { workspace = true, features = [ "api-macro" ] }
>  proxmox-serde.workspace = true
> +proxmox-section-config.workspace = true
>  proxmox-time.workspace = true
>  proxmox-uuid = { workspace = true, features = [ "serde" ] }
> diff --git a/pbs-api-types/src/datastore.rs b/pbs-api-types/src/datastore.rs
> index fe73cbc4..f2999007 100644
> --- a/pbs-api-types/src/datastore.rs
> +++ b/pbs-api-types/src/datastore.rs
> @@ -1479,6 +1479,96 @@ pub struct NamespaceListItem {
>      pub comment: Option<String>,
>  }
>  
> +#[api]
> +/// A type of content of a datastore
> +#[derive(Serialize, Deserialize)]

Should this have a `#[serde(rename_all = "lowercase"/"kebab-case")]`?

> +pub enum ContentType {
> +    /// Namespace
> +    Namespace,
> +    /// Backup Group
> +    Group,
> +    /// Backup Snapshot
> +    Snapshot,
> +}
> +
> +#[api(
> +    properties: {
> +        ns: {
> +            type: BackupNamespace,
> +        },
> +        snapshot: {
> +            type: SnapshotListItem,
> +            flatten: true,
> +        },
> +    },
> +)]
> +#[derive(Serialize, Deserialize)]
> +/// Represents a snapshot in a datastore with namespace information
> +pub struct SnapshotContentItem {

We go from FooListItem to FooContentItem to mean that a namespace is
included.

NamespacedSnapshot?
SnapshotAndNamespace?

> +    /// The namespace of the snapshot
> +    ns: BackupNamespace,
> +    #[serde(flatten)]
> +    /// The snapshot information
> +    snapshot: SnapshotListItem,
> +}
> +
> +#[api(
> +    properties: {
> +        ns: {
> +            type: BackupNamespace,
> +        },
> +        group: {
> +            type: GroupListItem,
> +            flatten: true,
> +        },
> +    },
> +)]
> +#[derive(Serialize, Deserialize)]
> +/// Represents a snapshot in a datastore with namespace information
> +pub struct GroupContentItem {

NamespacedGroup?
GroupAndNamespace?

> +    /// The namespace of the snapshot
> +    ns: BackupNamespace,
> +    #[serde(flatten)]
> +    /// The backup group information
> +    group: GroupListItem,
> +}
> +
> +#[api(
> +    "id-property": "id",
> +    "id-schema": {
> +        type: String,
> +        description: "ID",
> +    },
> +)]
> +#[derive(Serialize, Deserialize)]
> +#[serde(rename_all = "kebab-case")]
> +#[serde(tag = "type")]
> +pub enum ContentListItem {

Content?

> +    NameSpace(NamespaceListItem),
> +    Group(GroupContentItem),
> +    Snapshot(SnapshotContentItem),
> +}
> +
> +impl From<NamespaceListItem> for ContentListItem {
> +    fn from(value: NamespaceListItem) -> Self {
> +        ContentListItem::NameSpace(value)
> +    }
> +}
> +
> +impl From<(BackupNamespace, GroupListItem)> for ContentListItem {
> +    fn from(value: (BackupNamespace, GroupListItem)) -> Self {
> +        let (ns, group) = value;
> +        ContentListItem::Group(GroupContentItem { ns, group })
> +    }
> +}
> +
> +impl From<(BackupNamespace, SnapshotListItem)> for ContentListItem {
> +    fn from(value: (BackupNamespace, SnapshotListItem)) -> Self {
> +        let (ns, snapshot) = value;
> +        ContentListItem::Snapshot(SnapshotContentItem { ns, snapshot })
> +    }
> +}
> +
>  #[api(
>      properties: {
>          "backup": { type: BackupDir },
> @@ -1759,6 +1849,15 @@ pub const ADMIN_DATASTORE_LIST_NAMESPACE_RETURN_TYPE: ReturnType = ReturnType {
>      .schema(),
>  };
>  
> +pub const ADMIN_DATASTORE_LIST_CONTENT_RETURN_TYPE: ReturnType = ReturnType {
> +    optional: false,
> +    schema: &ArraySchema::new(
> +        "Returns the list of namespaces, backup groups and snapshots of a datastore.",
> +        &ContentListItem::API_SCHEMA,
> +    )
> +    .schema(),
> +};
> +
>  pub const ADMIN_DATASTORE_PRUNE_RETURN_TYPE: ReturnType = ReturnType {
>      optional: false,
>      schema: &ArraySchema::new(
> -- 
> 2.47.3