PVE/APIClient/Helpers.pm

   1 package PVE::APIClient::Helpers;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Storable;
   7 use JSON;
   8 use File::Path qw(make_path);
   9
  10 use PVE::APIClient::JSONSchema;
  11 use PVE::APIClient::Exception qw(raise);
  12 use Encode::Locale;
  13 use Encode;
  14 use HTTP::Status qw(:constants);
  15
  16 my $pve_api_definition;
  17
  18 my $pve_api_definition_fn = "/usr/share/pve-client/pve-api-definition.dat";
  19
  20 my $method_map = {
  21     create => 'POST',
  22     set => 'PUT',
  23     get => 'GET',
  24     delete => 'DELETE',
  25 };
  26
  27 my $default_output_format = 'text';
  28 my $client_output_format =  $default_output_format;
  29
  30 sub set_output_format {
  31     my ($format) = @_;
  32
  33     if (!defined($format)) {
  34         $client_output_format =  $default_output_format;
  35     } else {
  36         $client_output_format =  $format;
  37     }
  38 }
  39
  40 sub get_output_format {
  41     return $client_output_format;
  42 }
  43
  44 sub print_result {
  45     my ($data, $result_schema) = @_;
  46
  47     my $format = get_output_format();
  48
  49     return if $result_schema->{type} eq 'null';
  50
  51     # TODO: implement different output formats ($format)
  52
  53     if ($format eq 'json') {
  54        print to_json($data, {utf8 => 1, allow_nonref => 1, canonical => 1, pretty => 1 });
  55     } elsif ($format eq 'text') {
  56        my $type = $result_schema->{type};
  57        if ($type eq 'object') {
  58            die "implement me";
  59        } elsif ($type eq 'array') {
  60            my $item_type = $result_schema->{items}->{type};
  61            if ($item_type eq 'object') {
  62                die "implement me";
  63            } elsif ($item_type eq 'array') {
  64                die "implement me";
  65            } else {
  66                foreach my $el (@$data) {
  67                    print "$el\n"
  68                }
  69            }
  70        } else {
  71            print "$data\n";
  72        }
  73     } else {
  74        die "internal error: unknown output format"; # should not happen
  75     }
  76 }
  77
  78 my $__real_remove_formats; $__real_remove_formats = sub {
  79     my ($properties) = @_;
  80
  81     foreach my $pname (keys %$properties) {
  82         if (my $d = $properties->{$pname}) {
  83             if (defined(my $format = $d->{format})) {
  84                 if (ref($format)) {
  85                     $__real_remove_formats->($format);
  86                 } elsif (!PVE::APIClient::JSONSchema::get_format($format)) {
  87                     # simply remove unknown format definitions
  88                     delete $d->{format};
  89                 }
  90             }
  91         }
  92     }
  93 };
  94
  95 my $remove_unknown_formats; $remove_unknown_formats = sub {
  96     my ($tree) = @_;
  97
  98     my $class = ref($tree);
  99     return if !$class;
 100
 101     if ($class eq 'ARRAY') {
 102        foreach my $el (@$tree) {
 103            $remove_unknown_formats->($el);
 104        }
 105     } elsif ($class eq 'HASH') {
 106         if (my $info = $tree->{info}) {
 107             for my $method (qw(GET PUT PUSH DELETE)) {
 108                 next if !$info->{$method};
 109                 my $properties = $info->{$method}->{parameters}->{properties};
 110                 $__real_remove_formats->($properties) if $properties;
 111             }
 112         }
 113         if ($tree->{children}) {
 114             $remove_unknown_formats->($tree->{children});
 115         }
 116     }
 117     return;
 118 };
 119
 120 sub get_api_definition {
 121
 122     if (!defined($pve_api_definition)) {
 123         open(my $fh, '<',  $pve_api_definition_fn) ||
 124             die "unable to open '$pve_api_definition_fn' - $!\n";
 125         $pve_api_definition = Storable::fd_retrieve($fh);
 126
 127         $remove_unknown_formats->($pve_api_definition);
 128     }
 129
 130     return $pve_api_definition;
 131 }
 132
 133 my $map_path_to_info = sub {
 134     my ($child_list, $stack, $uri_param) = @_;
 135
 136     while (defined(my $comp = shift @$stack)) {
 137         foreach my $child (@$child_list) {
 138             my $text = $child->{text};
 139
 140             if ($text eq $comp) {
 141                 # found
 142             } elsif ($text =~ m/^\{(\S+)\}$/) {
 143                 # found
 144                 $uri_param->{$1} = $comp;
 145             } else {
 146                 next; # text next child
 147             }
 148             if ($child->{leaf} || !scalar(@$stack)) {
 149                 return $child;
 150             } else {
 151                 $child_list = $child->{children};
 152                 last; # test next path component
 153             }
 154         }
 155     }
 156     return undef;
 157 };
 158
 159 sub find_method_info {
 160     my ($path, $method, $uri_param, $noerr) = @_;
 161
 162     $uri_param //= {};
 163
 164     my $stack = [ grep { length($_) > 0 }  split('\/+' , $path)]; # skip empty fragments
 165
 166     my $api = get_api_definition();
 167
 168     my $child = scalar(@$stack) ? $map_path_to_info->($api->{children}, $stack, $uri_param) : $api;
 169
 170     if (!($child && $child->{info} && $child->{info}->{$method})) {
 171         return undef if $noerr;
 172         die "unable to find API method '$method' for path '$path'\n";
 173     }
 174
 175     return $child->{info}->{$method};
 176 }
 177
 178 sub complete_api_call_options {
 179     my ($cmd, $prop, $prev, $cur, $args) = @_;
 180
 181     my $print_result = sub {
 182         foreach my $p (@_) {
 183             print "$p\n" if $p =~ m/^$cur/;
 184         }
 185     };
 186
 187     my $print_parameter_completion = sub {
 188         my ($pname) = @_;
 189         my $d = $prop->{$pname};
 190         if ($d->{completion}) {
 191             my $vt = ref($d->{completion});
 192             if ($vt eq 'CODE') {
 193                 my $res = $d->{completion}->($cmd, $pname, $cur, $args);
 194                 &$print_result(@$res);
 195             }
 196         } elsif ($d->{type} eq 'boolean') {
 197             &$print_result('0', '1');
 198         } elsif ($d->{enum}) {
 199             &$print_result(@{$d->{enum}});
 200         }
 201     };
 202
 203     my @option_list = ();
 204     foreach my $key (keys %$prop) {
 205         push @option_list, "--$key";
 206     }
 207
 208     if ($cur =~ m/^-/) {
 209         &$print_result(@option_list);
 210         return;
 211     }
 212
 213     if ($prev =~ m/^--?(.+)$/ && $prop->{$1}) {
 214         my $pname = $1;
 215         &$print_parameter_completion($pname);
 216         return;
 217     }
 218
 219     &$print_result(@option_list);
 220 }
 221
 222 sub merge_api_definition_properties {
 223     my ($path, $method, $properties) = @_;
 224
 225     my $info = PVE::APIClient::Helpers::find_method_info($path, $method);
 226
 227     return { %{$info->{parameters}->{properties}}, %$properties };
 228 }
 229
 230 sub complete_api_path {
 231     my ($text) = @_;
 232
 233     my $api = get_api_definition(); # make sure API data is loaded
 234
 235     $text =~ s!^/!!;
 236
 237     my ($dir, $rest) = $text =~ m|^(?:(.*)/)?(?:([^/]*))?$|;
 238
 239     my $info;
 240     if (!defined($dir)) {
 241         $dir = '';
 242         $info = $api;
 243     } else {
 244         my $stack = [ grep { length($_) > 0 }  split('\/+' , $dir)]; # skip empty fragments
 245         $info = $map_path_to_info->($api->{children}, $stack, {});
 246     }
 247
 248     my $res = [];
 249     if ($info) {
 250         my $prefix = length($dir) ? "/$dir/" : '/';
 251         if (my $children = $info->{children}) {
 252             foreach my $c (@$children) {
 253                 my $ctext = $c->{text};
 254                 if ($ctext =~ m/^\{(\S+)\}$/) {
 255                     push @$res, "$prefix$ctext";
 256                     push @$res, "$prefix$ctext/";
 257                     if (length($rest)) {
 258                         push @$res, "$prefix$rest";
 259                         push @$res, "$prefix$rest/";
 260                     }
 261                 } elsif ($ctext =~ m/^\Q$rest/) {
 262                     push @$res, "$prefix$ctext";
 263                     push @$res, "$prefix$ctext/" if $c->{children};
 264                 }
 265             }
 266         }
 267     }
 268
 269     return $res;
 270 }
 271
 272 # test for command lines with api calls (or similar bash completion calls):
 273 # example1: pveclient api get remote1 /cluster
 274 sub extract_path_info {
 275     my ($uri_param) = @_;
 276
 277     my $info;
 278
 279     my $test_path_properties = sub {
 280         my ($args) = @_;
 281
 282         return if scalar(@$args) < 5;
 283         return if $args->[1] ne 'api';
 284
 285         my $path = $args->[4];
 286         if (my $method = $method_map->{$args->[2]}) {
 287             $info = find_method_info($path, $method, $uri_param, 1);
 288         }
 289     };
 290
 291     if (defined(my $cmd = $ARGV[0])) {
 292         if ($cmd eq 'api') {
 293             $test_path_properties->([$0, @ARGV]);
 294         } elsif ($cmd eq 'bashcomplete') {
 295             my $cmdline = substr($ENV{COMP_LINE}, 0, $ENV{COMP_POINT});
 296             my $args = PVE::APIClient::Tools::split_args($cmdline);
 297             $test_path_properties->($args);
 298         }
 299     }
 300
 301     return $info;
 302 }
 303
 304 sub get_vmid_resource {
 305     my ($conn, $vmid) = @_;
 306
 307     my $resources = $conn->get('api2/json/cluster/resources', {type => 'vm'});
 308
 309     my $resource;
 310     for my $tmp (@$resources) {
 311         if ($tmp->{vmid} eq $vmid) {
 312             $resource = $tmp;
 313             last;
 314         }
 315     }
 316
 317     if (!defined($resource)) {
 318         die "\"$vmid\" not found";
 319     }
 320
 321     return $resource;
 322 }
 323
 324 sub poll_task {
 325     my ($conn, $node, $upid, $quiet) = @_;
 326
 327     my $path = "api2/json/nodes/$node/tasks/$upid/status";
 328
 329     my $task_status;
 330     my $last_line = 0;
 331     while(1) {
 332         if (!$quiet) {
 333             my $path = "api2/json/nodes/$node/tasks/$upid/log";
 334             my $task_log = $conn->get($path, {start => $last_line});
 335
 336             my $printme = '';
 337             for my $li (@$task_log) {
 338                 if ($li->{t} eq 'no content') {
 339                     next;
 340                 }
 341                 $printme .= $li->{t} . "\n";
 342                 $last_line = $li->{n};
 343             }
 344
 345             if ($printme ne '') {
 346                 print $printme;
 347             }
 348         }
 349
 350         $task_status = $conn->get($path, {});
 351
 352         if ($task_status->{status} eq "stopped") {
 353             last;
 354         }
 355
 356         sleep(2);
 357     }
 358
 359     if ($task_status->{exitstatus} ne "OK") {
 360         die $task_status->{exitstatus};
 361     }
 362
 363     return $task_status->{exitstatus};
 364 }
 365
 366 sub configuration_directory {
 367
 368     my $home = $ENV{HOME} // '';
 369     my $xdg = $ENV{XDG_CONFIG_HOME} // '';
 370
 371     my $subdir = "pveclient";
 372
 373     return "$xdg/$subdir" if length($xdg);
 374
 375     return "$home/.config/$subdir" if length($home);
 376
 377     die "neither XDG_CONFIG_HOME nor HOME environment variable set\n";
 378 }
 379
 380 my $ticket_cache_filename = "/.tickets";
 381
 382 sub ticket_cache_lookup {
 383     my ($remote) = @_;
 384
 385     my $dir = configuration_directory();
 386     my $filename = "$dir/$ticket_cache_filename";
 387
 388     my $data = {};
 389     eval { $data = from_json(PVE::APIClient::Tools::file_get_contents($filename)); };
 390     # ignore errors
 391
 392     my $ticket = $data->{$remote};
 393     return undef if !defined($ticket);
 394
 395     my $min_age = - 60;
 396     my $max_age = 3600*2 - 60;
 397
 398     if ($ticket =~ m/:([a-fA-F0-9]{8})::/) {
 399         my $ttime = hex($1);
 400         my $ctime = time();
 401         my $age = $ctime - $ttime;
 402
 403         return $ticket if ($age > $min_age) && ($age < $max_age);
 404     }
 405
 406     return undef;
 407 }
 408
 409 sub ticket_cache_update {
 410     my ($remote, $ticket) = @_;
 411
 412     my $dir = configuration_directory();
 413     my $filename = "$dir/$ticket_cache_filename";
 414
 415     my $code = sub {
 416         make_path($dir);
 417         my $data = {};
 418         if (-f $filename) {
 419             my $raw = PVE::APIClient::Tools::file_get_contents($filename);
 420             eval { $data = from_json($raw); };
 421             # ignore errors
 422         }
 423         $data->{$remote} = $ticket;
 424
 425         PVE::APIClient::Tools::file_set_contents($filename, to_json($data), 0600);
 426     };
 427
 428     PVE::APIClient::Tools::lock_file($filename, undef, $code);
 429     die $@ if $@;
 430 }
 431
 432
 433 1;