aspera-cli 4.18.1 → 4.20.0

data/lib/aspera/cli/main.rb

@@ -94,7 +94,7 @@ module Aspera
         # create formatter, in case there is an exception, it is used to display.
         @plug_init[:formatter] = Formatter.new
         # create command line manager with arguments
-        @plug_init[:options] = Manager.new(PROGRAM_NAME, @argv)
+        @plug_init[:options] = Manager.new(Info::CMD_NAME, @argv)
         # formatter adds options
         @plug_init[:formatter].declare_options(options)
         ExtendedValue.instance.default_decoder = options.get_option(:struct_parser)
@@ -102,16 +102,18 @@ module Aspera
         current_prog_name = File.basename($PROGRAM_NAME)
         formatter.display_message(
           :error,
-          "#{Formatter::WARNING_FLASH} Please use '#{PROGRAM_NAME}' instead of '#{current_prog_name}'") unless current_prog_name.eql?(PROGRAM_NAME)
+          "#{Formatter::WARNING_FLASH} Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'") unless current_prog_name.eql?(Info::CMD_NAME)
         # declare and parse global options
         declare_global_options
         # the Config plugin adds the @preset parser, so declare before TransferAgent which may use it
-        @plug_init[:config] = Plugins::Config.new(**@plug_init, gem: GEM_NAME, name: PROGRAM_NAME, help: DOC_URL, version: Cli::VERSION)
+        @plug_init[:config] = Plugins::Config.new(**@plug_init, man_header: false)
         @plug_init[:persistency] = @plug_init[:config].persistency
         # data persistency
         Aspera.assert(@plug_init[:persistency]){'missing persistency object'}
         # the TransferAgent plugin may use the @preset parser
         @plug_init[:config].transfer = @plug_init[:transfer] = TransferAgent.new(options, config)
+        # add commands for config plugin after all options have been added
+        @plug_init[:config].add_manual_header(false)
         nil_keys = @plug_init.select{|_, value|value.nil?}.keys
         Aspera.assert(nil_keys.empty?){"nil : #{nil_keys}"}
         Log.log.debug('plugin env created'.red)
@@ -123,23 +125,23 @@ module Aspera
         t = ' ' * 8
         return <<~END_OF_BANNER
           NAME
-          #{t}#{PROGRAM_NAME} -- a command line tool for Aspera Applications (v#{Cli::VERSION})
+          #{t}#{Info::CMD_NAME} -- a command line tool for Aspera Applications (v#{Cli::VERSION})
 
           SYNOPSIS
-          #{t}#{PROGRAM_NAME} COMMANDS [OPTIONS] [ARGS]
+          #{t}#{Info::CMD_NAME} COMMANDS [OPTIONS] [ARGS]
 
           DESCRIPTION
           #{t}Use Aspera application to perform operations on command line.
-          #{t}Documentation and examples: #{GEM_URL}
-          #{t}execute: #{PROGRAM_NAME} conf doc
-          #{t}or visit: #{DOC_URL}
-          #{t}source repo: #{SRC_URL}
+          #{t}Documentation and examples: #{Info::GEM_URL}
+          #{t}execute: #{Info::CMD_NAME} conf doc
+          #{t}or visit: #{Info::DOC_URL}
+          #{t}source repo: #{Info::SRC_URL}
 
           ENVIRONMENT VARIABLES
           #{t}Any option can be set as an environment variable, refer to the manual
 
           COMMANDS
-          #{t}To list first level commands, execute: #{PROGRAM_NAME}
+          #{t}To list first level commands, execute: #{Info::CMD_NAME}
           #{t}Note that commands can be written shortened (provided it is unique).
 
           OPTIONS
@@ -199,16 +201,17 @@ module Aspera
 
       def exit_with_usage(include_all_plugins)
         Log.log.debug{"exit_with_usage(#{include_all_plugins})".bg_red}
-        # display main plugin options
+        # display main plugin options (+config)
         formatter.display_message(:error, options.parser)
         if include_all_plugins
           # list plugins that have a "require" field, i.e. all but main plugin
           PluginFactory.instance.plugin_list.each do |plugin_name_sym|
+            # config was already included in the global options
             next if plugin_name_sym.eql?(COMMAND_CONFIG)
             # override main option parser with a brand new, to avoid having global options
             plugin_env = @plug_init.clone
             plugin_env[:only_manual] = true # force declaration of all options
-            plugin_env[:options] = Manager.new(PROGRAM_NAME)
+            plugin_env[:options] = Manager.new(Info::CMD_NAME)
             plugin_env[:options].parser.banner = '' # remove default banner
             get_plugin_instance_with_options(plugin_name_sym, plugin_env)
             # display generated help for plugin options
@@ -223,7 +226,7 @@ module Aspera
       # early debug for parser
       # Note: does not accept shortcuts
       def early_debug_setup
-        Log.instance.program_name = PROGRAM_NAME
+        Log.instance.program_name = Info::CMD_NAME
         @argv.each do |arg|
           case arg
           when '--' then break

data/lib/aspera/cli/manager.rb

@@ -20,7 +20,7 @@ module Aspera
         @method = method_name
         @option_name = option_name
         @has_writer = @object.respond_to?(writer_method)
-        Log.log.debug{"AttrAccessor: #{@option_name}: #{@object.class}.#{@method}: writer=#{@has_writer}"}
+        Log.log.trace1{"AttrAccessor: #{@option_name}: #{@object.class}.#{@method}: writer=#{@has_writer}"}
         Aspera.assert(@object.respond_to?(@method)) {"#{object} does not respond to #{method_name}"}
       end
 
@@ -328,7 +328,7 @@ module Aspera
         if opt[:read_write].eql?(:accessor)
           Aspera.assert_type(handler, Hash)
           Aspera.assert(handler.keys.sort.eql?(%i[m o]))
-          Log.log.debug{"set attr obj #{option_symbol} (#{handler[:o]},#{handler[:m]})"}
+          Log.log.trace1{"set attr obj: #{option_symbol} (#{handler[:o]},#{handler[:m]})"}
           opt[:accessor] = AttrAccessor.new(handler[:o], handler[:m], option_symbol)
         end
         set_option(option_symbol, default, where: 'default') unless default.nil?
@@ -372,7 +372,7 @@ module Aspera
           @parser.on(*on_args, &block)
         else Aspera.error_unexpected_value(values)
         end
-        Log.log.debug{"on_args=#{on_args}"}
+        Log.log.trace1{"on_args=#{on_args}"}
       end
 
       # Adds each of the keys of specified hash as an option
@@ -386,6 +386,11 @@ module Aspera
         end
       end
 
+      # allows a plugin to add an argument as next argument to process
+      def unshift_next_argument(argument)
+        @unprocessed_cmd_line_arguments.unshift(argument)
+      end
+
       # check if there were unprocessed values to generate error
       def command_or_arg_empty?
         return @unprocessed_cmd_line_arguments.empty?
@@ -435,7 +440,7 @@ module Aspera
 
       # removes already known options from the list
       def parse_options!
-        Log.log.debug('parse_options!'.red)
+        Log.log.trace1('parse_options!'.red)
         # first conf file, then env var
         consume_option_pairs(@option_pairs_batch, 'set')
         consume_option_pairs(@option_pairs_env, 'env')
@@ -443,16 +448,16 @@ module Aspera
         unknown_options = []
         begin
           # remove known options one by one, exception if unknown
-          Log.log.debug('before parse'.red)
+          Log.log.trace1('before parse'.red)
           @parser.parse!(@unprocessed_cmd_line_options)
-          Log.log.debug('After parse'.red)
+          Log.log.trace1('After parse'.red)
         rescue OptionParser::InvalidOption => e
-          Log.log.debug{"InvalidOption #{e}".red}
+          Log.log.trace1{"InvalidOption #{e}".red}
           # save for later processing
           unknown_options.push(e.args.first)
           retry
         end
-        Log.log.debug{"remains: #{unknown_options}"}
+        Log.log.trace1{"remains: #{unknown_options}"}
         # set unprocessed options for next time
         @unprocessed_cmd_line_options = unknown_options
       end
@@ -538,7 +543,7 @@ module Aspera
       # @param unprocessed_options [Array] list of options to apply (key_sym,value)
       # @param where [String] where the options come from
       def consume_option_pairs(unprocessed_options, where)
-        Log.log.debug{"consume_option_pairs: #{where}"}
+        Log.log.trace1{"consume_option_pairs: #{where}"}
         options_to_set = {}
         unprocessed_options.each do |k, v|
           if @declared_options.key?(k)
@@ -548,7 +553,7 @@ module Aspera
             end
             options_to_set[k] = v
           else
-            Log.log.debug{"unprocessed: #{k}: #{v}"}
+            Log.log.trace1{"unprocessed: #{k}: #{v}"}
           end
         end
         options_to_set.each do |k, v|

data/lib/aspera/cli/plugin.rb

@@ -5,7 +5,7 @@ require 'aspera/assert'
 
 module Aspera
   module Cli
-    # base class for plugins modules
+    # Base class for plugins
     class Plugin
       # operations without id
       GLOBAL_OPS = %i[create list].freeze
@@ -24,10 +24,7 @@ module Aspera
 
       class << self
         def declare_generic_options(options)
-          options.declare(:query, 'Additional filter for for some commands (list/delete)', types: Hash)
-          options.declare(
-            :value, 'Value for create, update, list filter', types: Hash,
-            deprecation: '(4.14) Use positional value for create/modify or option: query for list/delete')
+          options.declare(:query, 'Additional filter for for some commands (list/delete)', types: [Hash, Array])
           options.declare(:property, 'Name of property to set (modify operation)')
           options.declare(:bulk, 'Bulk operation (only some)', values: :bool, default: :no)
           options.declare(:bfail, 'Bulk operation error handling', values: :bool, default: :yes)
@@ -36,25 +33,29 @@ module Aspera
 
       attr_accessor(*INIT_PARAMS)
 
-      def initialize(options:, transfer:, config:, formatter:, persistency:, only_manual:)
+      def initialize(options:, transfer:, config:, formatter:, persistency:, only_manual:, man_header: true)
+        # check presence in descendant of mandatory method and constant
+        Aspera.assert(respond_to?(:execute_action)){"Missing method 'execute_action' in #{self.class}"}
+        Aspera.assert(self.class.constants.include?(:ACTIONS)){"Missing constant 'ACTIONS' in #{self.class}"}
         @options = options
         @transfer = transfer
         @config = config
         @formatter = formatter
         @persistency = persistency
         @only_manual = only_manual
-        # check presence in descendant of mandatory method and constant
-        Aspera.assert(respond_to?(:execute_action)){"Missing method 'execute_action' in #{self.class}"}
-        Aspera.assert(self.class.constants.include?(:ACTIONS)){'ACTIONS shall be redefined by subclass'}
+        add_manual_header if man_header
+      end
+
+      def add_manual_header(has_options = true)
         # manual header for all plugins
         options.parser.separator('')
         options.parser.separator("COMMAND: #{self.class.name.split('::').last.downcase}")
         options.parser.separator("SUBCOMMANDS: #{self.class.const_get(:ACTIONS).map(&:to_s).sort.join(' ')}")
-        options.parser.separator('OPTIONS:')
+        options.parser.separator('OPTIONS:') if has_options
       end
 
+      # @return a hash of instance variables
       def init_params
-        # return a hash of instance variables
         INIT_PARAMS.map{|p| [p, instance_variable_get("@#{p}".to_sym)]}.to_h
       end
 
@@ -156,7 +157,7 @@ module Aspera
         when :create
           raise 'cannot create singleton' if is_singleton
           return do_bulk_operation(command: command, descr: 'data', fields: display_fields) do |params|
-            rest_api.create(res_class_path, params)[:data]
+            rest_api.create(res_class_path, params)
           end
         when :delete
           raise 'cannot delete singleton' if is_singleton
@@ -171,9 +172,9 @@ module Aspera
             {'id' => one_id}
           end
         when :show
-          return {type: :single_object, data: rest_api.read(one_res_path)[:data], fields: display_fields}
+          return {type: :single_object, data: rest_api.read(one_res_path), fields: display_fields}
         when :list
-          resp = rest_api.read(res_class_path, query_read_delete)
+          resp = rest_api.call(operation: 'GET', subpath: res_class_path, headers: {'Accept' => 'application/json'}, query: query_read_delete)
           return Main.result_empty if resp[:http].code == '204'
           data = resp[:data]
           # TODO: not generic : which application is this for ?
@@ -214,7 +215,7 @@ module Aspera
         return entity_command(command, rest_api, res_class_path, **opts, &block)
       end
 
-      # query parameters in URL suitable for REST list/GET and delete/DELETE
+      # query parameters in URL suitable for REST: list/GET and delete/DELETE
       def query_read_delete(default: nil)
         query = options.get_option(:query)
         # dup default, as it could be frozen
@@ -229,30 +230,15 @@ module Aspera
         return query
       end
 
-      # TODO: when deprecation of `value` is completed: remove this method, replace with options.get_option(:query)
-      # deprecation: 4.14
-      def query_option(mandatory: false, default: nil)
-        option = :value
-        value = options.get_option(option, mandatory: false)
-        if value.nil?
-          option = :query
-          value = options.get_option(option, mandatory: mandatory, default: default)
-        end
-        return value
-      end
-
       # Retrieves an extended value from command line, used for creation or modification of entities
       # @param command [Symbol] command name for error message
       # @param type [Class] expected type of value, either a Class, an Array of Class
       # @param bulk [Boolean] if true, value must be an Array of <type>
       # @param default [Object] default value if not provided
-      # TODO: when deprecation of `value` is completed: remove line with :value
       def value_create_modify(command:, description: nil, type: Hash, bulk: false, default: nil)
-        value = options.get_option(:value)
-        Log.log.warn("option `value` is deprecated. Use positional parameter for #{command}") unless value.nil?
         value = options.get_next_argument(
           "parameters for #{command}#{description.nil? ? '' : " (#{description})"}", mandatory: default.nil?,
-          validation: bulk ? Array : type) if value.nil?
+          validation: bulk ? Array : type)
         value = default if value.nil?
         unless type.nil?
           type = [type] unless type.is_a?(Array)

data/lib/aspera/cli/plugin_factory.rb

@@ -3,7 +3,7 @@
 require 'singleton'
 module Aspera
   module Cli
-    # option is retrieved from another object using accessor
+    # Instantiate plugin from well-known locations
     class PluginFactory
       include Singleton
 
@@ -19,14 +19,17 @@ module Aspera
         @plugins = {}
       end
 
+      # @return list of registered plugins
       def plugin_list
         @plugins.keys
       end
 
+      # @return path to source file of plugin
       def plugin_source(plugin_name_sym)
         @plugins[plugin_name_sym][:source]
       end
 
+      # add a folder to the list of folders to look for plugins
       def add_lookup_folder(folder)
         @lookup_folders.unshift(folder)
       end
@@ -43,6 +46,7 @@ module Aspera
         end
       end
 
+      # @return Class object for plugin
       def plugin_class(plugin_name_sym)
         raise "ERROR: plugin not found: #{plugin_name_sym}" unless @plugins.key?(plugin_name_sym)
         require @plugins[plugin_name_sym][:require_stanza]
@@ -50,6 +54,9 @@ module Aspera
         return Object.const_get("#{Module.nesting[1]}::#{PLUGINS_MODULE}::#{plugin_name_sym.to_s.capitalize}")
       end
 
+      # Create specified plugin
+      # @param plugin_name_sym [Symbol] name of plugin
+      # @param args [Hash] arguments to pass to plugin constructor
       def create(plugin_name_sym, **args)
         # TODO: check that ancestor is Plugin?
         plugin_class(plugin_name_sym).new(**args)
@@ -57,6 +64,8 @@ module Aspera
 
       private
 
+      # add plugin information to list
+      # @param path [String] path to plugin source file
       def add_plugin_info(path)
         raise "ERROR: plugin path must end with #{RUBY_FILE_EXT}" if !path.end_with?(RUBY_FILE_EXT)
         plugin_symbol = File.basename(path, RUBY_FILE_EXT).to_sym

data/lib/aspera/cli/plugins/alee.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'aspera/api/aoc'
+require 'aspera/api/alee'
 require 'aspera/nagios'
 
 module Aspera
@@ -16,7 +16,7 @@ module Aspera
             nagios = Nagios.new
             begin
               api = Api::Alee.new(nil, nil, version: 'ping')
-              result = api.call(operation: 'GET', subpath: '')
+              result = api.call(operation: 'GET')
               raise "unexpected response: #{result[:http].body}" unless result[:http].body.eql?('pong')
               nagios.add_ok('api', 'answered ok')
             rescue StandardError => e
@@ -27,7 +27,7 @@ module Aspera
             entitlement_id = options.get_option(:username, mandatory: true)
             customer_id = options.get_option(:password, mandatory: true)
             api_metering = Api::Alee.new(entitlement_id, customer_id)
-            return {type: :single_object, data: api_metering.read('entitlement')[:data]}
+            return {type: :single_object, data: api_metering.read('entitlement')}
           end
         end
       end