Re: [PATCH manager] api: backup: add return schema for backup jobs

[Thomas Lamprecht <t.lamprecht@proxmox.com>]

Am 01.04.26 um 12:00 schrieb Lukas Wagner:
>>> +my $backup_job_return_schema = PVE::VZDump::Common::json_config_properties({
>>> +    id => get_standard_option('pve-backup-jobid'),
>>> +    schedule => {
>>> +        description => "Backup schedule. The format is a subset of `systemd` calendar events.",
>>> +        type => 'string',
>>> +        format => 'pve-calendar-event',
>>> +        maxLength => 128,
>>> +        optional => 1,
>>> +    },
>>> +    starttime => {
>>> +        type => 'string',
>>> +        description => "Job Start time.",
>>> +        pattern => '\d{1,2}:\d{1,2}',
>>> +        typetext => 'HH:MM',
>>> +        optional => 1,
>>> +    },
>>> +    dow => {
>>> +        type => 'string',
>>> +        format => 'pve-day-of-week-list',
>>> +        optional => 1,
>>> +        description => "Day of week selection.",
>>> +        requires => 'starttime',
>>> +        default => ALL_DAYS,
>>> +    },
>> I'd apply this with the following on-top or squashed-in, ack?

Hmm, we might actually just drop above two legacy fields here (soon).

As for the modern jobs.cfg (based on PVE::Job::Registry in pve-common) we do not
have them anymore at all, AFAICT, so those are only possible for the old CRON
based vzdump.cron, and those we map in the API endpoint via:

 my $data = cfs_read_file('vzdump.cron');
 
 my $res = $data->{jobs} || [];                      
 foreach my $job (@$res) {
     $job->{schedule} = $convert_to_schedule->($job);
 }

The convert_to_schedule method keeps the current starttime/dow params, but the
API contract now is basically, dow and starttime might be there, if a vzdum.cron
still exists and nobody updated/added/removed any backup job since a while, as
that would convert them to the modern jobs.cfg, having keept the old vzdump.cron
only around to ensure that PVE nodes with older pve-mananger in a cluster still
handle pre-existing backup old-style jobs correctly.
But that was introduced mostly in commit 305921b1a ("api/backup: handle new
vzdump jobs") [0] back in PVE 7.1 days, so we probably can just drop that, and
we probably also do not need to wait until a next major release, as vzdum.cron
cannot really be used anymore in practice (besides manual editing, which I do
not care that much for). And for the backup job API response it's rather a clear
cut, schedule is _always_ present, starttime/dow basically never, and all (API)
clients need to cope with schedule since PVE 7.1, so dropping it from the return
schema and (not a must, but nicer) deleting them from the response should be fine.

I know, it's a bit annoying to have those legacy ghosts in scope for such
patches, but it has some value to clean a few of them up when they resurface,
especially when doing this with the end goal of encoding such types in rust in
pve-api-types for use with PDM, as all legacy cruft we can safely shave off can
make our life simpler.

[0]: https://git.proxmox.com/?p=pve-manager.git;a=commitdiff;h=305921b1a