[pve-devel] [PATCH manager 3/5] api: cluster: add jobs/schedule-analyze api call

[Dominik Csapak <d.csapak@proxmox.com>]

a simple api call to simulate calendar event triggers
takes a schedule, an optional number (default 10), an optional starttime
(default 'now') and returns a list with unix timestamps, as well as
humanly readable utc timestamps.

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
---
 PVE/API2/Cluster.pm       |   5 ++
 PVE/API2/Cluster/Jobs.pm  | 107 ++++++++++++++++++++++++++++++++++++++
 PVE/API2/Cluster/Makefile |   1 +
 3 files changed, 113 insertions(+)
 create mode 100644 PVE/API2/Cluster/Jobs.pm

diff --git a/PVE/API2/Cluster.pm b/PVE/API2/Cluster.pm
index 3b918e55..205f9883 100644
--- a/PVE/API2/Cluster.pm
+++ b/PVE/API2/Cluster.pm
@@ -25,6 +25,7 @@ use PVE::API2::ACMEPlugin;
 use PVE::API2::Backup;
 use PVE::API2::Cluster::BackupInfo;
 use PVE::API2::Cluster::Ceph;
+use PVE::API2::Cluster::Jobs;
 use PVE::API2::Cluster::MetricServer;
 use PVE::API2::ClusterConfig;
 use PVE::API2::Firewall::Cluster;
@@ -84,6 +85,10 @@ __PACKAGE__->register_method ({
     path => 'ceph',
 });
 
+__PACKAGE__->register_method ({
+    subclass => "PVE::API2::Cluster::Jobs",
+    path => 'jobs',
+});
 if ($have_sdn) {
     __PACKAGE__->register_method ({
        subclass => "PVE::API2::Network::SDN",
diff --git a/PVE/API2/Cluster/Jobs.pm b/PVE/API2/Cluster/Jobs.pm
new file mode 100644
index 00000000..79a6e85e
--- /dev/null
+++ b/PVE/API2/Cluster/Jobs.pm
@@ -0,0 +1,107 @@
+package PVE::API2::Cluster::Jobs;
+
+use strict;
+use warnings;
+
+use PVE::RESTHandler;
+use PVE::CalendarEvent;
+
+use base qw(PVE::RESTHandler);
+
+__PACKAGE__->register_method({
+    name => 'index',
+    path => '',
+    method => 'GET',
+    description => "Index for jobs related endpoints.",
+    parameters => {
+	additionalProperties => 0,
+	properties => {},
+    },
+    returns => {
+	type => 'array',
+	description => 'Directory index.',
+	items => {
+	    type => "object",
+	    properties => {
+		subdir => {
+		    type => 'string',
+		    description => 'API sub-directory endpoint',
+		},
+	    },
+	},
+	links => [ { rel => 'child', href => "{subdir}" } ],
+    },
+    code => sub {
+	return [
+	   { subdir => 'schedule-analyze' },
+	];
+    }});
+
+__PACKAGE__->register_method({
+    name => 'schedule-analyze',
+    path => 'schedule-analyze',
+    method => 'GET',
+    description => "Returns a list of future schedule runtimes.",
+    permissions => { user => 'all' },
+    parameters => {
+	additionalProperties => 0,
+	properties => {
+	    schedule => {
+		description => "Backup schedule. The format is a subset of `systemd` calendar events.",
+		type => 'string', format => 'pve-calendar-event',
+		maxLength => 128,
+	    },
+	    starttime => {
+		description => "UNIX timestamp to start the calculation from. Defaults to the current time.",
+		optional => 1,
+		type => 'integer',
+	    },
+	    number => {
+		description => "Number of timestamps to return.",
+		optional => 1,
+		type => 'integer',
+		minimum => 1,
+		maximum => 100,
+		default => 10,
+	    },
+	},
+    },
+    returns => {
+	type => 'array',
+	description => 'Contains the guest objects.',
+	items => {
+	    type => 'object',
+	    properties => {
+		timestamp => {
+		    type => 'integer',
+		    description => 'UNIX timestamp for the run.',
+		},
+		utc => {
+		    type => 'string',
+		    description => "UTC timestamp for the run.",
+		},
+	    },
+	},
+    },
+    code => sub {
+	my ($param) = @_;
+
+	my $starttime = $param->{starttime} // time();
+	my $number = $param->{number} // 10;
+	my $schedule = $param->{schedule};
+
+	my $result = [];
+
+	my $event = PVE::CalendarEvent::parse_calendar_event($schedule);
+
+	for (my $count = 0; $count < $number; $count++) {
+	    my $next = PVE::CalendarEvent::compute_next_event($event, $starttime);
+	    push @$result, {
+		timestamp => $next,
+		utc => scalar(gmtime($next)),
+	    };
+	    $starttime = $next;
+	}
+
+	return $result;
+    }});
diff --git a/PVE/API2/Cluster/Makefile b/PVE/API2/Cluster/Makefile
index 742a1007..8d306507 100644
--- a/PVE/API2/Cluster/Makefile
+++ b/PVE/API2/Cluster/Makefile
@@ -5,6 +5,7 @@ include ../../../defines.mk
 PERLSOURCE= 			\
 	BackupInfo.pm		\
 	MetricServer.pm		\
+	Jobs.pm			\
 	Ceph.pm
 
 all:
-- 
2.30.2