[pbs-devel] [PATCH proxmox-backup 2/2] fix #6185: client/docs: explicitly mention archive name restrictions

[Christian Ebner]

On 2/20/25 16:22, Wolfgang Bumiller wrote:
> On Thu, Feb 20, 2025 at 01:09:20PM +0100, Christian Ebner wrote:
>> Mention in the docs and the api parameter description the limitations
>> for archive name labels. They must contain alphanumerics, hyphens and
>> underscores only to match the regex pattern.
>>
>> By setting this in the api parameter description, it will be included
>> in the man page for proxmox-backup-client.
>>
>> Fixes: https://bugzilla.proxmox.com/show_bug.cgi?id=6185
>> Signed-off-by: Christian Ebner <c.ebner at proxmox.com>
>> ---
>>   docs/backup-client.rst                 |  1 +
>>   pbs-client/src/backup_specification.rs | 10 ++++++----
>>   proxmox-backup-client/src/main.rs      |  3 ++-
>>   3 files changed, 9 insertions(+), 5 deletions(-)
>>
>> diff --git a/docs/backup-client.rst b/docs/backup-client.rst
>> index 1c2a98ed8..e11c0142a 100644
>> --- a/docs/backup-client.rst
>> +++ b/docs/backup-client.rst
>> @@ -169,6 +169,7 @@ the client. The format is:
>>   
>>       <archive-name>.<type>:<source-path>
>>   
>> +The ``archive-name`` must contain alphanumerics, hyphens and underscores only.
>>   Common types are ``.pxar`` for file archives and ``.img`` for block
>>   device images. To create a backup of a block device, run the following command:
>>   
>> diff --git a/pbs-client/src/backup_specification.rs b/pbs-client/src/backup_specification.rs
>> index b6fbc555c..ebf7f3f18 100644
>> --- a/pbs-client/src/backup_specification.rs
>> +++ b/pbs-client/src/backup_specification.rs
>> @@ -7,10 +7,12 @@ const_regex! {
>>       BACKUPSPEC_REGEX = r"^([a-zA-Z0-9_-]+\.(pxar|img|conf|log)):(.+)$";
>>   }
>>   
>> -pub const BACKUP_SOURCE_SCHEMA: Schema =
>> -    StringSchema::new("Backup source specification ([<label>:<path>]).")
>> -        .format(&ApiStringFormat::Pattern(&BACKUPSPEC_REGEX))
>> -        .schema();
>> +pub const BACKUP_SOURCE_SCHEMA: Schema = StringSchema::new(
>> +    r###"Backup source specification ([<label>:<path>]), the specification
>> +'label' must contain alphanumerics, hyphens and underscores only."###,
> 
> Is there a reason for including a newline here?
> Why not
> 
>      "Backup source specification ([<label>:<path>]), the specification \
>       'label' must contain alphanumerics, hyphens and underscores only.",

The newline was not intentional, no. Got unnoticed when looking at the 
resulting output.

> 
> When ending a regular quoted string with a backslash, the white space on
> the next line is ignored for the resulting string, so this is the same
> as:
> 
>      "Backup source specification ([<label>:<path>]), the specification 'label' must contain alphanumerics, hyphens and underscores only.",
> 
>> +)
>> +.format(&ApiStringFormat::Pattern(&BACKUPSPEC_REGEX))
>> +.schema();
>>   
>>   pub enum BackupSpecificationType {
>>       PXAR,
>> diff --git a/proxmox-backup-client/src/main.rs b/proxmox-backup-client/src/main.rs
>> index 589a097bb..1647d480a 100644
>> --- a/proxmox-backup-client/src/main.rs
>> +++ b/proxmox-backup-client/src/main.rs
>> @@ -628,7 +628,8 @@ fn spawn_catalog_upload(
>>          properties: {
>>              backupspec: {
>>                  type: Array,
>> -               description: "List of backup source specifications ([<label.ext>:<path>] ...)",
>> +               description: r###"List of backup source specifications ([<label.ext>:<path>] ...),
>> +the specifications 'label' must contain alphanumerics, hyphens and underscores only."###,
> 
> This, too, is weirdly formatted.

Acked, will send a v2 incorporating your feedback, thx!