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

[Dominik Csapak]

On 10/7/25 10:59 AM, Wolfgang Bumiller wrote:
> 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?
> 

I tried to keep the current namin scheme ;)

Since I'm not the best at naming, I'll take every suggestion in that 
regard^^

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

yep, but as long as we're not actively using it for these enum i think 
it's no harm to do it this way for now.

> 
>>
>> 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")]`?

yep

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

IMHO both a bit unwieldy, but '*ContentItem' is not better ..

I'd probably go with SnapshotWithNamespace (IMO 'with' suggests a
stronger correlation than 'and', but no strong opinion here) ?

> 
>> +    /// 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?
> 

same as above

>> +    /// 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?

'DatastoreContent' ? As i find Content alone a bit too generic
but i didn't want to do 'DatastoreContentListItem' ^^

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