src/PVE/CLIHandler.pm

   1 package PVE::CLIHandler;
   2
   3 use strict;
   4 use warnings;
   5
   6 use JSON;
   7 use Scalar::Util qw(weaken);
   8
   9 use PVE::SafeSyslog;
  10 use PVE::Exception qw(raise raise_param_exc);
  11 use PVE::RESTHandler;
  12 use PVE::PTY;
  13 use PVE::INotify;
  14 use PVE::CLIFormatter;
  15
  16 use base qw(PVE::RESTHandler);
  17
  18 # $cmddef defines which (sub)commands are available in a specific CLI class.
  19 # A real command is always an array consisting of its class, name, array of
  20 # position fixed (required) parameters and hash of predefined parameters when
  21 # mapping a CLI command t o an API call. Optionally an output method can be
  22 # passed at the end, e.g., for formatting or transformation purpose, and
  23 # a schema of additional properties/arguments which are added to
  24 # the method schema and gets passed to the formatter.
  25 #
  26 # [class, name, fixed_params, API_pre-set params, output_sub ]
  27 #
  28 # In case of so called 'simple commands', the $cmddef can be also just an
  29 # array.
  30 #
  31 # Examples:
  32 # $cmddef = {
  33 #     command => [ 'PVE::API2::Class', 'command', [ 'arg1', 'arg2' ], { node => $nodename } ],
  34 #     do => {
  35 #         this => [ 'PVE::API2::OtherClass', 'method', [ 'arg1' ], undef, sub {
  36 #             my ($res) = @_;
  37 #             print "$res\n";
  38 #         }],
  39 #         that => [ 'PVE::API2::OtherClass', 'subroutine' [] ],
  40 #     },
  41 #     dothat => { alias => 'do that' },
  42 # }
  43 my $cmddef;
  44 my $exename;
  45 my $cli_handler_class;
  46
  47 my $standard_mappings = {
  48     'pve-password' => {
  49         name => 'password',
  50         desc => '<password>',
  51         interactive => 1,
  52         func => sub {
  53             my ($value) = @_;
  54             return $value if $value;
  55             return PVE::PTY::get_confirmed_password();
  56         },
  57     },
  58 };
  59 sub get_standard_mapping {
  60     my ($name, $base) = @_;
  61
  62     my $std = $standard_mappings->{$name};
  63     die "no such standard mapping '$name'\n" if !$std;
  64
  65     my $res = $base || {};
  66
  67     foreach my $opt (keys %$std) {
  68         next if defined($res->{$opt});
  69         $res->{$opt} = $std->{$opt};
  70     }
  71
  72     return $res;
  73 }
  74
  75 my $gen_param_mapping_func = sub {
  76     my ($cli_handler_class) = @_;
  77
  78     my $param_mapping = $cli_handler_class->can('param_mapping');
  79
  80     if (!$param_mapping) {
  81         my $read_password = $cli_handler_class->can('read_password');
  82         my $string_param_mapping = $cli_handler_class->can('string_param_file_mapping');
  83
  84         return $string_param_mapping if !$read_password;
  85
  86         $param_mapping = sub {
  87             my ($name) = @_;
  88
  89             my $password_map = get_standard_mapping('pve-password', {
  90                 func => $read_password
  91             });
  92             my $map = $string_param_mapping ? $string_param_mapping->($name) : [];
  93             return [@$map, $password_map];
  94         };
  95     }
  96
  97     return $param_mapping;
  98 };
  99
 100 my $assert_initialized = sub {
 101     my @caller = caller;
 102     die "$caller[0]:$caller[2] - not initialized\n"
 103         if !($cmddef && $exename && $cli_handler_class);
 104 };
 105
 106 my $abort = sub {
 107     my ($reason, $cmd) = @_;
 108     print_usage_short (\*STDERR, $reason, $cmd);
 109     exit (-1);
 110 };
 111
 112 my $expand_command_name = sub {
 113     my ($def, $cmd, $enforce_exact) = @_;
 114
 115     return $cmd if exists $def->{$cmd}; # command is already complete
 116
 117     my $is_alias = sub { ref($_[0]) eq 'HASH' && exists($_[0]->{alias}) };
 118     my @expanded = grep { /^\Q$cmd\E/ && !$is_alias->($def->{$_}) } keys %$def;
 119
 120     return @expanded if !$enforce_exact;
 121
 122     return $expanded[0] if scalar(@expanded) == 1; # enforce exact match
 123
 124     return undef;
 125 };
 126
 127 my $get_commands = sub {
 128     my $def = shift // die "no command definition passed!";
 129     return [ grep { !(ref($def->{$_}) eq 'HASH' && defined($def->{$_}->{alias})) } sort keys %$def ];
 130 };
 131
 132 my $complete_command_names = sub { $get_commands->($cmddef) };
 133
 134 # traverses the command definition using the $argv array, resolving one level
 135 # of aliases.
 136 # Returns the matching (sub) command and its definition, and argument array for
 137 # this (sub) command and a hash where we marked which (sub) commands got
 138 # expanded (e.g. st => status) while traversing
 139 sub resolve_cmd {
 140     my ($argv, $is_alias) = @_;
 141
 142     my ($def, $cmd) = ($cmddef, $argv);
 143     my $cmdstr = $exename;
 144
 145     if (ref($argv) eq 'ARRAY') {
 146         my $expanded_last_arg;
 147         my $last_arg_id = scalar(@$argv) - 1;
 148
 149         for my $i (0..$last_arg_id) {
 150             $cmd = $expand_command_name->($def, $argv->[$i], 1);
 151             if (defined($cmd)) {
 152                 # If the argument was expanded (or was already complete) and it
 153                 # is the final argument, tell our caller about it:
 154                 $expanded_last_arg = $cmd if $i == $last_arg_id;
 155             } else {
 156                 # Otherwise continue with the unexpanded version of it.
 157                 $cmd = $argv->[$i];
 158             }
 159             $cmdstr .= " $cmd";
 160             if (!defined($def->{$cmd})) {
 161                 # $cmd still could be a valid prefix for bash_completion
 162                 # in that case keep $def as it is, else set it to undef
 163                 $def = undef if !$expand_command_name->($def, $cmd);
 164                 last;
 165             }
 166             $def = $def->{$cmd};
 167
 168             if (ref($def) eq 'ARRAY') {
 169                 # could expand to a real command, rest of $argv are its arguments
 170                 my $cmd_args = [ @$argv[$i+1..$last_arg_id] ];
 171                 return ($cmd, $def, $cmd_args, $expanded_last_arg, $cmdstr);
 172             }
 173
 174             if (defined($def->{alias})) {
 175                 die "alias loop detected for '$cmd'" if $is_alias; # avoids cycles
 176                 # replace aliased (sub)command with the expanded aliased command
 177                 splice @$argv, $i, 1, split(/ +/, $def->{alias});
 178                 return resolve_cmd($argv, 1);
 179             }
 180         }
 181         # got either a special command (bashcomplete, verifyapi) or an unknown
 182         # cmd, just return first entry as cmd and the rest of $argv as cmd_arg
 183         my $cmd_args = [ @$argv[1..$last_arg_id] ];
 184         return ($argv->[0], $def, $cmd_args, $expanded_last_arg, $cmdstr);
 185     }
 186     return ($cmd, $def, undef, undef, $cmdstr);
 187 }
 188
 189 sub generate_usage_str {
 190     my ($format, $cmd, $indent, $separator, $sortfunc) = @_;
 191
 192     $assert_initialized->();
 193     die 'format required' if !$format;
 194
 195     $sortfunc //= sub { sort keys %{$_[0]} };
 196     $separator //= '';
 197     $indent //= '';
 198
 199     my $param_cb = $gen_param_mapping_func->($cli_handler_class);
 200
 201     my ($subcmd, $def, undef, undef, $cmdstr) = resolve_cmd($cmd);
 202
 203     my $generate_weak;
 204     $generate_weak = sub {
 205         my ($indent, $separator, $def, $prefix) = @_;
 206
 207         my $str = '';
 208         if (ref($def) eq 'HASH') {
 209             my $oldclass = undef;
 210             foreach my $cmd (&$sortfunc($def)) {
 211
 212                 if (ref($def->{$cmd}) eq 'ARRAY') {
 213                     my ($class, $name, $arg_param, $fixed_param, undef, $formatter_properties) = @{$def->{$cmd}};
 214
 215                     $str .= $separator if $oldclass && $oldclass ne $class;
 216                     $str .= $indent;
 217                     $str .= $class->usage_str($name, "$prefix $cmd", $arg_param,
 218                                               $fixed_param, $format, $param_cb, $formatter_properties);
 219                     $oldclass = $class;
 220
 221                 } elsif (defined($def->{$cmd}->{alias}) && ($format eq 'asciidoc')) {
 222
 223                     $str .= "*$prefix $cmd*\n\nAn alias for '$exename $def->{$cmd}->{alias}'.\n\n";
 224
 225                 } else {
 226                     next if $def->{$cmd}->{alias};
 227
 228                     my $substr = $generate_weak->($indent, '', $def->{$cmd}, "$prefix $cmd");
 229                     if ($substr) {
 230                         $substr .= $separator if $substr !~ /\Q$separator\E{2}/;
 231                         $str .= $substr;
 232                     }
 233                 }
 234
 235             }
 236         } else {
 237             my ($class, $name, $arg_param, $fixed_param, undef, $formatter_properties) = @$def;
 238             $abort->("unknown command '$cmd'") if !$class;
 239
 240             $str .= $indent;
 241             $str .= $class->usage_str($name, $prefix, $arg_param, $fixed_param, $format, $param_cb, $formatter_properties);
 242         }
 243         return $str;
 244     };
 245     my $generate = $generate_weak;
 246     weaken($generate_weak);
 247
 248     return $generate->($indent, $separator, $def, $cmdstr);
 249 }
 250
 251 __PACKAGE__->register_method ({
 252     name => 'help',
 253     path => 'help',
 254     method => 'GET',
 255     description => "Get help about specified command.",
 256     parameters => {
 257         additionalProperties => 0,
 258         properties => {
 259             'extra-args' => PVE::JSONSchema::get_standard_option('extra-args', {
 260                 description => 'Shows help for a specific command',
 261                 completion => $complete_command_names,
 262             }),
 263             verbose => {
 264                 description => "Verbose output format.",
 265                 type => 'boolean',
 266                 optional => 1,
 267             },
 268         },
 269     },
 270     returns => { type => 'null' },
 271
 272     code => sub {
 273         my ($param) = @_;
 274
 275         $assert_initialized->();
 276
 277         my $cmd = $param->{'extra-args'};
 278
 279         my $verbose = defined($cmd) && $cmd;
 280         $verbose = $param->{verbose} if defined($param->{verbose});
 281
 282         if (!$cmd) {
 283             if ($verbose) {
 284                 print_usage_verbose();
 285             } else {
 286                 print_usage_short(\*STDOUT);
 287             }
 288             return undef;
 289         }
 290
 291         my $str;
 292         if ($verbose) {
 293             $str = generate_usage_str('full', $cmd, '');
 294         } else {
 295             $str = generate_usage_str('short', $cmd, ' ' x 7);
 296         }
 297         $str =~ s/^\s+//;
 298
 299         if ($verbose) {
 300             print "$str\n";
 301         } else {
 302             print "USAGE: $str\n";
 303         }
 304
 305         return undef;
 306
 307     }});
 308
 309 sub print_simple_asciidoc_synopsis {
 310     $assert_initialized->();
 311
 312     my $synopsis = "*${exename}* `help`\n\n";
 313     $synopsis .= generate_usage_str('asciidoc');
 314
 315     return $synopsis;
 316 }
 317
 318 sub print_asciidoc_synopsis {
 319     $assert_initialized->();
 320
 321     my $synopsis = "";
 322
 323     $synopsis .= "*${exename}* `<COMMAND> [ARGS] [OPTIONS]`\n\n";
 324
 325     $synopsis .= generate_usage_str('asciidoc');
 326
 327     $synopsis .= "\n";
 328
 329     return $synopsis;
 330 }
 331
 332 sub print_usage_verbose {
 333     $assert_initialized->();
 334
 335     print "USAGE: $exename <COMMAND> [ARGS] [OPTIONS]\n\n";
 336
 337     my $str = generate_usage_str('full');
 338
 339     print "$str\n";
 340 }
 341
 342 sub print_usage_short {
 343     my ($fd, $msg, $cmd) = @_;
 344
 345     $assert_initialized->();
 346
 347     print $fd "ERROR: $msg\n" if $msg;
 348     print $fd "USAGE: $exename <COMMAND> [ARGS] [OPTIONS]\n\n";
 349
 350     print {$fd} generate_usage_str('short', $cmd, ' ' x 7, $cmd ? '' : "\n", sub {
 351         my ($h) = @_;
 352         return sort {
 353             if (ref($h->{$a}) eq 'ARRAY' && ref($h->{$b}) eq 'ARRAY') {
 354                 # $a and $b are both real commands order them by their class
 355                 return $h->{$a}->[0] cmp $h->{$b}->[0] || $a cmp $b;
 356             } elsif (ref($h->{$a}) eq 'ARRAY' xor ref($h->{$b}) eq 'ARRAY') {
 357                 # real command and subcommand mixed, put sub commands first
 358                 return ref($h->{$b}) eq 'ARRAY' ? -1 : 1;
 359             } else {
 360                 # both are either from the same class or subcommands
 361                 return $a cmp $b;
 362             }
 363         } keys %$h;
 364     });
 365 }
 366
 367 my $print_bash_completion = sub {
 368     my ($simple_cmd, $bash_command, $cur, $prev) = @_;
 369
 370     my $debug = 0;
 371
 372     return if !(defined($cur) && defined($prev) && defined($bash_command));
 373     return if !defined($ENV{COMP_LINE});
 374     return if !defined($ENV{COMP_POINT});
 375
 376     my $cmdline = substr($ENV{COMP_LINE}, 0, $ENV{COMP_POINT});
 377     print STDERR "\nCMDLINE: $ENV{COMP_LINE}\n" if $debug;
 378
 379     my $args = PVE::Tools::split_args($cmdline);
 380     shift @$args; # no need for program name
 381     my $print_result = sub {
 382         foreach my $p (@_) {
 383             print "$p\n" if $p =~ m/^\Q$cur\E/;
 384         }
 385     };
 386
 387     my ($cmd, $def) = ($simple_cmd, $cmddef);
 388     if (!$simple_cmd) {
 389         ($cmd, $def, $args, my $expanded) = resolve_cmd($args);
 390
 391         if (defined($expanded) && $prev ne $expanded) {
 392             print "$expanded\n";
 393             return;
 394         }
 395
 396         if (ref($def) eq 'HASH') {
 397             &$print_result(@{$get_commands->($def)});
 398             return;
 399         }
 400     }
 401     return if !$def;
 402
 403     my $pos = scalar(@$args) - 1;
 404     $pos += 1 if $cmdline =~ m/\s+$/;
 405     print STDERR "pos: $pos\n" if $debug;
 406     return if $pos < 0;
 407
 408     my $skip_param = {};
 409
 410     my ($class, $name, $arg_param, $uri_param, undef, $formatter_properties) = @$def;
 411     $arg_param //= [];
 412     $uri_param //= {};
 413
 414     $arg_param = [ $arg_param ] if !ref($arg_param);
 415
 416     map { $skip_param->{$_} = 1; } @$arg_param;
 417     map { $skip_param->{$_} = 1; } keys %$uri_param;
 418
 419     my $info = $class->map_method_by_name($name);
 420
 421     my $prop = { %{$info->{parameters}->{properties}} }; # copy
 422     $prop = { %$prop, %$formatter_properties } if $formatter_properties;
 423
 424     my $print_parameter_completion = sub {
 425         my ($pname) = @_;
 426         my $d = $prop->{$pname};
 427         if ($d->{completion}) {
 428             my $vt = ref($d->{completion});
 429             if ($vt eq 'CODE') {
 430                 my $res = $d->{completion}->($cmd, $pname, $cur, $args);
 431                 &$print_result(@$res);
 432             }
 433         } elsif ($d->{type} eq 'boolean') {
 434             &$print_result('0', '1');
 435         } elsif ($d->{enum}) {
 436             &$print_result(@{$d->{enum}});
 437         }
 438     };
 439
 440     # positional arguments
 441     if ($pos < scalar(@$arg_param)) {
 442         my $pname = $arg_param->[$pos];
 443         &$print_parameter_completion($pname);
 444         return;
 445     }
 446
 447     my @option_list = ();
 448     foreach my $key (keys %$prop) {
 449         next if $skip_param->{$key};
 450         push @option_list, "--$key";
 451     }
 452
 453     if ($cur =~ m/^-/) {
 454         &$print_result(@option_list);
 455         return;
 456     }
 457
 458     if ($prev =~ m/^--?(.+)$/ && $prop->{$1}) {
 459         my $pname = $1;
 460         &$print_parameter_completion($pname);
 461         return;
 462     }
 463
 464     &$print_result(@option_list);
 465 };
 466
 467 sub verify_api {
 468     my ($class) = @_;
 469
 470     # simply verify all registered methods
 471     PVE::RESTHandler::validate_method_schemas();
 472 }
 473
 474 my $get_exe_name = sub {
 475     my ($class) = @_;
 476
 477     my $name = $class;
 478     $name =~ s/^.*:://;
 479     $name =~ s/_/-/g;
 480
 481     return $name;
 482 };
 483
 484 sub generate_bash_completions {
 485     my ($class) = @_;
 486
 487     # generate bash completion config
 488
 489     $exename = &$get_exe_name($class);
 490
 491     print <<__EOD__;
 492 # $exename bash completion
 493
 494 # see http://tiswww.case.edu/php/chet/bash/FAQ
 495 # and __ltrim_colon_completions() in /usr/share/bash-completion/bash_completion
 496 # this modifies global var, but I found no better way
 497 COMP_WORDBREAKS=\${COMP_WORDBREAKS//:}
 498
 499 complete -o default -C '$exename bashcomplete' $exename
 500 __EOD__
 501 }
 502
 503 sub generate_zsh_completions {
 504     my ($class) = @_;
 505
 506     # generate zsh completion config
 507
 508     $exename = &$get_exe_name($class);
 509
 510     print <<__EOD__;
 511 #compdef _$exename $exename
 512
 513 function _$exename() {
 514     local cwords line point cmd curr prev
 515     cwords=\${#words[@]}
 516     line=\$words
 517     point=\${#line}
 518     cmd=\${words[1]}
 519     curr=\${words[cwords]}
 520     prev=\${words[cwords-1]}
 521     compadd \$(COMP_CWORD="\$cwords" COMP_LINE="\$line" COMP_POINT="\$point" \\
 522         $exename bashcomplete "\$cmd" "\$curr" "\$prev")
 523 }
 524 __EOD__
 525 }
 526
 527 sub generate_asciidoc_synopsys {
 528     my ($class) = @_;
 529     $class->generate_asciidoc_synopsis();
 530 };
 531
 532 sub generate_asciidoc_synopsis {
 533     my ($class) = @_;
 534
 535     $cli_handler_class = $class;
 536
 537     $exename = &$get_exe_name($class);
 538
 539     no strict 'refs';
 540     my $def = ${"${class}::cmddef"};
 541     $cmddef = $def;
 542
 543     if (ref($def) eq 'ARRAY') {
 544         print_simple_asciidoc_synopsis();
 545     } else {
 546         $cmddef->{help} = [ __PACKAGE__, 'help', ['cmd'] ];
 547
 548         print_asciidoc_synopsis();
 549     }
 550 }
 551
 552 # overwrite this if you want to run/setup things early
 553 sub setup_environment {
 554     my ($class) = @_;
 555
 556     # do nothing by default
 557 }
 558
 559 my $handle_cmd  = sub {
 560     my ($args, $preparefunc, $param_cb) = @_;
 561
 562     $cmddef->{help} = [ __PACKAGE__, 'help', ['extra-args'] ];
 563
 564     my ($cmd, $def, $cmd_args, undef, $cmd_str) = resolve_cmd($args);
 565
 566     $abort->("no command specified") if !$cmd;
 567
 568     # call verifyapi before setup_environment(), don't execute any real code in
 569     # this case
 570     if ($cmd eq 'verifyapi') {
 571         PVE::RESTHandler::validate_method_schemas();
 572         return;
 573     }
 574
 575     $cli_handler_class->setup_environment();
 576
 577     if ($cmd eq 'bashcomplete') {
 578         &$print_bash_completion(undef, @$cmd_args);
 579         return;
 580     }
 581
 582     # checked special commands, if def is still a hash we got an incomplete sub command
 583     $abort->("incomplete command '$cmd_str'", $args) if ref($def) eq 'HASH';
 584
 585     &$preparefunc() if $preparefunc;
 586
 587     my ($class, $name, $arg_param, $uri_param, $outsub, $formatter_properties) = @{$def || []};
 588     $abort->("unknown command '$cmd_str'") if !$class;
 589
 590     my ($res, $formatter_params) = $class->cli_handler(
 591         $cmd_str, $name, $cmd_args, $arg_param, $uri_param, $param_cb, $formatter_properties);
 592
 593     if (defined $outsub) {
 594         my $result_schema = $class->map_method_by_name($name)->{returns};
 595         $outsub->($res, $result_schema, $formatter_params);
 596     }
 597 };
 598
 599 my $handle_simple_cmd = sub {
 600     my ($args, $preparefunc, $param_cb) = @_;
 601
 602     my ($class, $name, $arg_param, $uri_param, $outsub, $formatter_properties) = @{$cmddef};
 603     die "no class specified" if !$class;
 604
 605     if (scalar(@$args) >= 1) {
 606         if ($args->[0] eq 'help') {
 607             my $str = "USAGE: $name help\n";
 608             $str .= generate_usage_str('long');
 609             print STDERR "$str\n\n";
 610             return;
 611         } elsif ($args->[0] eq 'verifyapi') {
 612             PVE::RESTHandler::validate_method_schemas();
 613             return;
 614         }
 615     }
 616
 617     $cli_handler_class->setup_environment();
 618
 619     if (scalar(@$args) >= 1) {
 620         if ($args->[0] eq 'bashcomplete') {
 621             shift @$args;
 622             &$print_bash_completion($name, @$args);
 623             return;
 624         }
 625     }
 626
 627     &$preparefunc() if $preparefunc;
 628
 629     my ($res, $formatter_params) = $class->cli_handler(
 630         $name, $name, \@ARGV, $arg_param, $uri_param, $param_cb, $formatter_properties);
 631
 632     if (defined $outsub) {
 633         my $result_schema = $class->map_method_by_name($name)->{returns};
 634         $outsub->($res, $result_schema, $formatter_params);
 635     }
 636 };
 637
 638 sub run_cli_handler {
 639     my ($class, %params) = @_;
 640
 641     $cli_handler_class = $class;
 642
 643     $ENV{'PATH'} = '/sbin:/bin:/usr/sbin:/usr/bin';
 644
 645     foreach my $key (keys %params) {
 646         next if $key eq 'prepare';
 647         next if $key eq 'no_init'; # not used anymore
 648         next if $key eq 'no_rpcenv'; # not used anymore
 649         die "unknown parameter '$key'";
 650     }
 651
 652     my $preparefunc = $params{prepare};
 653
 654     my $param_cb = $gen_param_mapping_func->($cli_handler_class);
 655
 656     $exename = &$get_exe_name($class);
 657
 658     my $logid = $ENV{PVE_LOG_ID} || $exename;
 659     initlog($logid);
 660
 661     no strict 'refs';
 662     $cmddef = ${"${class}::cmddef"};
 663
 664     if (ref($cmddef) eq 'ARRAY') {
 665         $handle_simple_cmd->(\@ARGV, $preparefunc, $param_cb);
 666     } else {
 667         $handle_cmd->(\@ARGV, $preparefunc, $param_cb);
 668     }
 669
 670     exit 0;
 671 }
 672
 673 1;