PVE/API2/Cluster/Jobs.pm

   1 package PVE::API2::Cluster::Jobs;
   2
   3 use strict;
   4 use warnings;
   5
   6 use PVE::RESTHandler;
   7 use PVE::CalendarEvent;
   8
   9 use base qw(PVE::RESTHandler);
  10
  11 __PACKAGE__->register_method({
  12     name => 'index',
  13     path => '',
  14     method => 'GET',
  15     description => "Index for jobs related endpoints.",
  16     permissions => { user => 'all' },
  17     parameters => {
  18         additionalProperties => 0,
  19         properties => {},
  20     },
  21     returns => {
  22         type => 'array',
  23         description => 'Directory index.',
  24         items => {
  25             type => "object",
  26             properties => {
  27                 subdir => {
  28                     type => 'string',
  29                     description => 'API sub-directory endpoint',
  30                 },
  31             },
  32         },
  33         links => [ { rel => 'child', href => "{subdir}" } ],
  34     },
  35     code => sub {
  36         return [
  37            { subdir => 'schedule-analyze' },
  38         ];
  39     }});
  40
  41 __PACKAGE__->register_method({
  42     name => 'schedule-analyze',
  43     path => 'schedule-analyze',
  44     method => 'GET',
  45     description => "Returns a list of future schedule runtimes.",
  46     permissions => { user => 'all' },
  47     parameters => {
  48         additionalProperties => 0,
  49         properties => {
  50             schedule => {
  51                 description => "Job schedule. The format is a subset of `systemd` calendar events.",
  52                 type => 'string', format => 'pve-calendar-event',
  53                 maxLength => 128,
  54             },
  55             starttime => {
  56                 description => "UNIX timestamp to start the calculation from. Defaults to the current time.",
  57                 optional => 1,
  58                 type => 'integer',
  59             },
  60             iterations => {
  61                 description => "Number of event-iteration to simulate and return.",
  62                 optional => 1,
  63                 type => 'integer',
  64                 minimum => 1,
  65                 maximum => 100,
  66                 default => 10,
  67             },
  68         },
  69     },
  70     returns => {
  71         type => 'array',
  72         description => 'An array of the next <iterations> events since <starttime>.',
  73         items => {
  74             type => 'object',
  75             properties => {
  76                 timestamp => {
  77                     type => 'integer',
  78                     description => 'UNIX timestamp for the run.',
  79                 },
  80                 utc => {
  81                     type => 'string',
  82                     description => "UTC timestamp for the run.",
  83                 },
  84             },
  85         },
  86     },
  87     code => sub {
  88         my ($param) = @_;
  89
  90         my $starttime = $param->{starttime} // time();
  91         my $iterations = $param->{iterations} // 10;
  92         my $schedule = $param->{schedule};
  93
  94         my $result = [];
  95
  96         my $event = PVE::CalendarEvent::parse_calendar_event($schedule);
  97
  98         for (my $count = 0; $count < $iterations; $count++) {
  99             my $next = PVE::CalendarEvent::compute_next_event($event, $starttime);
 100             last if !defined($next);
 101             push @$result, {
 102                 timestamp => $next,
 103                 utc => scalar(gmtime($next)),
 104             };
 105             $starttime = $next;
 106         }
 107
 108         return $result;
 109     }});