aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/cli/main.rb

@@ -1,480 +0,0 @@
-# frozen_string_literal: true
-
-require 'aspera/cli/manager'
-require 'aspera/cli/formatter'
-require 'aspera/cli/plugins/config'
-require 'aspera/cli/extended_value'
-require 'aspera/cli/plugins/factory'
-require 'aspera/cli/transfer_agent'
-require 'aspera/cli/version'
-require 'aspera/cli/info'
-require 'aspera/cli/hints'
-require 'aspera/secret_hider'
-require 'aspera/log'
-require 'aspera/assert'
-require 'aspera/schema/documentation'
-require 'aspera/schema/registry'
-require 'net/ssh/errors'
-require 'openssl'
-
-module Aspera
-  module Cli
-    # Global objects shared with plugins
-    class Context
-      # @type [Array<Symbol>]
-      MEMBERS = %i[options transfer config formatter persistency man_header].freeze
-      # @!attribute [rw] options
-      #   @return [Manager] the command line options manager
-      # @!attribute [rw] transfer
-      #   @return [TransferAgent] the transfer agent, used by transfer plugins
-      # @!attribute [rw] config
-      #   @return [Plugins::Config] the configuration plugin, used by plugins to get configuration values and presets
-      # @!attribute [rw] formatter
-      #   @return [Formatter] the formatter, used by plugins to display results and messages
-      # @!attribute [rw] persistency
-      #   @return [Object] # whatever the type is
-      # @!attribute [rw] man_header
-      #   @return [Boolean] whether to display the manual header in plugin help
-      attr_accessor(*MEMBERS)
-
-      # Initialize all members to nil, so that they are defined and can be validated later
-      # @return [nil]
-      def initialize
-        MEMBERS.each{ |i| instance_variable_set(:"@#{i}", nil)}
-      end
-
-      # Validate that all members are set, raise exception if not
-      # @raise [Aspera::AssertionError] if any member is not set
-      # @return [nil]
-      def validate
-        MEMBERS.each do |i|
-          Aspera.assert(instance_variable_defined?(:"@#{i}"))
-          Aspera.assert(!instance_variable_get(:"@#{i}").nil?)
-        end
-      end
-
-      # Check if the context is in manual-only mode
-      # @return [Boolean] true if in manual-only mode
-      def only_manual?
-        transfer.eql?(:only_manual)
-      end
-
-      # Set the context to manual-only mode
-      # @return [Symbol] :only_manual
-      def only_manual!
-        @transfer = :only_manual
-      end
-    end
-
-    # The main CLI class
-    class Main
-      # Plugins store transfer result using this key and use result_transfer_multiple()
-      STATUS_FIELD = 'status'
-      COMMAND_CONFIG = :config
-      COMMAND_HELP = :help
-      # Types that go to result of type = text
-      SCALAR_TYPES = [String, Integer, Symbol].freeze
-      USER_INTERFACES = %i[text graphical].freeze
-
-      private_constant :COMMAND_CONFIG, :COMMAND_HELP, :SCALAR_TYPES, :USER_INTERFACES
-
-      class << self
-        # Create a special result type (only used internally here)
-        # @param special_sym [Symbol] the special result type
-        # @return [Hash] result hash with type :special
-        def result_special(special_sym); {type: :special, data: special_sym}; end
-
-        # Expect some list, but nothing to display
-        # @return [Hash] result hash for empty list
-        def result_empty; result_special(:empty); end
-
-        # Nothing expected
-        # @return [Hash] result hash for nothing
-        def result_nothing; result_special(:nothing); end
-
-        # Result is some status, such as "complete", "deleted"...
-        # @param status [String] The status
-        # @return [Hash] result hash with type :status
-        def result_status(status); return {type: :status, data: status}; end
-
-        # Text result coming from command result
-        # @param data [String, Integer, Symbol] the text data to display
-        # @return [Hash] result hash with type :text
-        def result_text(data); return {type: :text, data: data}; end
-
-        # Create a success result
-        # @return [Hash] result hash with status 'complete'
-        def result_success; return result_status('complete'); end
-
-        # Process statuses of finished transfer sessions
-        # @param statuses [Array] array of transfer session statuses
-        # @raise [Symbol] exception if there is one error
-        # @return [Hash] empty status result if all transfers succeeded
-        def result_transfer(statuses)
-          worst = TransferAgent.session_status(statuses)
-          raise worst unless worst.eql?(:success)
-          return Main.result_nothing
-        end
-
-        # Used when one command executes several transfer jobs (each job being possibly multi session)
-        # @param status_table [Array] [{STATUS_FIELD=>[status array],...},...]
-        # @return a status object suitable as command result
-        # Each element has a key STATUS_FIELD which contains the result of possibly multiple sessions
-        def result_transfer_multiple(status_table)
-          global_status = :success
-          # Transform status array into string and find if there was problem
-          status_table.each do |item|
-            worst = TransferAgent.session_status(item[STATUS_FIELD])
-            global_status = worst unless worst.eql?(:success)
-            item[STATUS_FIELD] = item[STATUS_FIELD].join(',')
-          end
-          raise global_status unless global_status.eql?(:success)
-          return result_object_list(status_table)
-        end
-
-        # Display image for that URL or directly blob
-        # @param url_or_blob [String] URL or blob to display as image
-        # @return [Hash] result hash with type :image
-        def result_image(url_or_blob)
-          return {type: :image, data: url_or_blob}
-        end
-
-        # A single object, must be Hash
-        # @param data [Hash] the object data
-        # @param fields [Array<String>, nil] optional list of fields to display
-        # @return [Hash] result hash with type :single_object
-        def result_single_object(data, fields: nil)
-          return {type: :single_object, data: data, fields: fields}
-        end
-
-        # An Array of Hash
-        # @param data [Array<Hash>] array of objects
-        # @param fields [Array<String>, nil] optional list of fields to display
-        # @param total [Integer, nil] optional total count
-        # @return [Hash] result hash with type :object_list
-        def result_object_list(data, fields: nil, total: nil)
-          return {type: :object_list, data: data, fields: fields, total: total}
-        end
-
-        # A list of values
-        # @param data [Array] The list of values
-        # @param name [String] The name of the list (used for display)
-        # @return [Hash] result hash with type :value_list
-        def result_value_list(data, name: 'id')
-          Aspera.assert_type(data, Array)
-          Aspera.assert_type(name, String)
-          return {type: :value_list, data: data, name: name}
-        end
-
-        # Determines type of result based on data
-        # @param data [Object] the data to analyze and format
-        # @return [Hash] result hash with appropriate type based on data
-        def result_auto(data)
-          case data
-          when NilClass
-            return result_special(:null)
-          when Hash
-            return result_single_object(data)
-          when Array
-            all_types = data.map(&:class).uniq
-            return result_object_list(data) if all_types.eql?([Hash])
-            unsupported_types = all_types - SCALAR_TYPES
-            return result_value_list(data, name: 'list') if unsupported_types.empty?
-            Aspera.error_unexpected_value(unsupported_types){'list item types'}
-          when *SCALAR_TYPES
-            return result_text(data)
-          else Aspera.error_unexpected_value(data.class.name){'result type'}
-          end
-        end
-      end
-
-      # Minimum initialization, no exception raised
-      # @param argv [Array<String>] command line arguments
-      # @return [nil]
-      def initialize(argv)
-        @argv = argv
-        Log.dump(:argv, @argv, level: :trace2)
-        @option_help = false
-        @option_show_config = false
-        @bash_completion = false
-        @context = Context.new
-      end
-
-      # This is the main function called by initial script just after constructor
-      # Processes command line arguments, executes commands, and handles exceptions
-      # @return [nil]
-      def process_command_line
-        # Catch exception information , if any
-        exception_info = nil
-        # False if command shall not be executed (e.g. --show-config)
-        execute_command = true
-        # Catch exceptions
-        begin
-          init_agents_and_options
-          # Find plugins, shall be after parse! ?
-          Plugins::Factory.instance.add_plugins_from_lookup_folders
-          # Help requested without command ? (plugins must be known here)
-          show_usage if @option_help && @context.options.command_or_arg_empty?
-          generate_bash_completion if @bash_completion
-          @context.config.periodic_check_newer_gem_version
-          command_sym =
-            if @option_show_config && @context.options.command_or_arg_empty?
-              COMMAND_CONFIG
-            else
-              @context.options.get_next_command(Plugins::Factory.instance.plugin_list.unshift(COMMAND_HELP))
-            end
-          # Command will not be executed, but we need manual
-          @context.options.fail_on_missing_mandatory = false if @option_help || @option_show_config
-          # Main plugin is not dynamically instantiated
-          case command_sym
-          when COMMAND_HELP
-            show_usage
-          when COMMAND_CONFIG
-            command_plugin = @context.config
-          else
-            # Get plugin, set options, etc
-            command_plugin = get_plugin_instance_with_options(command_sym)
-            # Parse plugin specific options
-            @context.options.parse_options!
-          end
-          # Help requested for current plugin
-          show_usage(all: false) if @option_help
-          if @option_show_config
-            @context.formatter.display_results(type: :single_object, data: @context.options.known_options(only_defined: true).stringify_keys)
-            execute_command = false
-          end
-          # Locking for single execution (only after "per plugin" option, in case lock port is there)
-          lock_port = @context.options.get_option(:lock_port)
-          if !lock_port.nil?
-            begin
-              # No need to close later, will be freed on process exit. must save in member else it is garbage collected
-              Log.log.debug{"Opening lock port #{lock_port}"}
-              # Loopback address, could also be 'localhost'
-              @tcp_server = TCPServer.new('127.0.0.1', lock_port)
-            rescue StandardError => e
-              execute_command = false
-              Log.log.warn{"Another instance is already running (#{e.message})."}
-            end
-          end
-          pid_file = @context.options.get_option(:pid_file)
-          if !pid_file.nil?
-            File.write(pid_file, Process.pid)
-            Log.log.debug{"Wrote pid #{Process.pid} to #{pid_file}"}
-            at_exit{File.delete(pid_file)}
-          end
-          # Execute and display (if not exclusive execution)
-          @context.formatter.display_results(**command_plugin.execute_action) if execute_command
-          # Save config file if command modified it
-          @context.config.save_config_file_if_needed
-          # Finish
-          @context.transfer.shutdown
-        rescue Net::SSH::AuthenticationFailed => e; exception_info = {e: e, t: 'SSH', security: true}
-        rescue OpenSSL::SSL::SSLError => e;         exception_info = {e: e, t: 'SSL'}
-        rescue Cli::BadArgument => e;               exception_info = {e: e, t: 'Argument', usage: true}
-        rescue Cli::MissingArgument => e;           exception_info = {e: e, t: 'Missing', usage: true}
-        rescue Cli::BadIdentifier => e;             exception_info = {e: e, t: 'Identifier'}
-        rescue Cli::SchemaRequest => e;             exception_info = {e: e, t: 'Schema'}
-        rescue Cli::Error => e;                     exception_info = {e: e, t: 'Tool', usage: true}
-        rescue Transfer::Error => e;                exception_info = {e: e, t: 'Transfer'}
-        rescue RestCallError => e;                  exception_info = {e: e, t: 'Rest'}
-        rescue SocketError => e;                    exception_info = {e: e, t: 'Network'}
-        rescue StandardError => e;                  exception_info = {e: e, t: "Other(#{e.class.name})", debug: true}
-        rescue Interrupt => e;                      exception_info = {e: e, t: 'Interruption', debug: true}
-        end
-        # Cleanup file list files
-        TempFileManager.instance.cleanup
-        # 1- processing of error condition
-        unless exception_info.nil?
-          Log.log.warn(exception_info[:e].message) if Log.instance.logger_type.eql?(:syslog) && exception_info[:security]
-          Log.log.error{"#{exception_info[:t]}: #{exception_info[:e].message}"} unless exception_info[:e].is_a?(Cli::SchemaRequest)
-          Log.log.debug{(['Backtrace:'] + exception_info[:e].backtrace).join("\n")} if exception_info[:debug]
-          @context.formatter.display_message(:error, 'Use option -h to get help.') if exception_info[:usage]
-          # Is that a known error condition with proposal for remediation ?
-          Hints.hint_for(exception_info[:e], @context.formatter)
-          # Requested help for a Hash parameter/option ?
-          if exception_info[:e].is_a?(Cli::SchemaRequest)
-            Log.log.info{"#{exception_info[:t]}: #{exception_info[:e].message}"}
-            schema_path = exception_info[:e].path
-            if schema_path.nil?
-              Log.log.warn{'Sorry, no schema provided yet. Please refer to the manual or API.'}
-            else
-              builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_path)).build
-              @context.formatter.display_results(**Main.result_object_list(builder.rows, fields: builder.columns))
-            end
-          end
-        end
-        # 2- processing of command not processed (due to exception or bad command line)
-        if execute_command || @option_show_config
-          @context.options.final_errors.each do |msg|
-            Log.log.error{"Argument: #{msg}"}
-            # Add code as exception if there is not already an error
-            exception_info = {e: Exception.new(msg), t: 'UnusedArg'} if exception_info.nil?
-          end
-        end
-        # 3- in case of error, fail the process status
-        unless exception_info.nil?
-          # Show stack trace in debug mode
-          raise exception_info[:e] if Log.log.debug?
-          # Else give hint and exit
-          @context.formatter.display_message(:error, 'Use --log-level=debug to get more details.') if exception_info[:debug]
-          Process.exit(1)
-        end
-        return
-      end
-
-      # Display usage information and help
-      # @param all [Boolean] if true, show help for all plugins; if false, show only current plugin
-      # @param exit [Boolean] if true, exit the process after displaying help
-      # @return [nil]
-      def show_usage(all: true, exit: true)
-        # Display main plugin options (+config)
-        @context.formatter.display_message(:error, @context.options.parser)
-        if all
-          @context.only_manual!
-          # List plugins that have a "require" field, i.e. all but main plugin
-          Plugins::Factory.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
-            @context.options = Manager.new(Info::CMD_NAME)
-            @context.options.parser.banner = '' # Remove default banner
-            get_plugin_instance_with_options(plugin_name_sym)
-            # Display generated help for plugin options
-            @context.formatter.display_message(:error, @context.options.parser.help)
-          end
-        end
-        Process.exit(0) if exit
-      end
-
-      private
-
-      # Initialize agents and options
-      # This can throw exception if there is a problem with the environment, needs to be caught by execute method
-      # @raise [StandardError] if there is a problem with the environment
-      # @return [nil]
-      def init_agents_and_options
-        @context.man_header = true
-        # Create formatter, in case there is an exception, it is used to display.
-        @context.formatter = Formatter.new
-        # Create command line manager with arguments
-        @context.options = Manager.new(Info::CMD_NAME, @argv)
-        # Formatter adds options
-        @context.formatter.declare_options(@context.options)
-        # Compare $0 with expected name
-        current_prog_name = File.basename($PROGRAM_NAME)
-        Aspera.assert(current_prog_name.eql?(Info::CMD_NAME), type: :warn){"Please use '#{Info::CMD_NAME}' instead of '#{current_prog_name}'"}
-        # Declare and parse global options
-        declare_global_options
-        # Do not display config commands if help is asked
-        @context.man_header = false
-        # The Config plugin adds the @preset parser, so declare before TransferAgent which may use it
-        @context.config = Plugins::Config.new(context: @context)
-        @context.man_header = true
-        # Data persistency is set in config
-        Aspera.assert(@context.persistency){'missing persistency object'}
-        # The TransferAgent plugin may use the @preset parser
-        @context.transfer = TransferAgent.new(@context.options, @context.config)
-        # Add commands for config plugin after all options have been added
-        @context.config.add_manual_header(false)
-        @context.validate
-        # Set banner when all environment is created so that additional extended value modifiers are known, e.g. @preset
-        @context.options.parser.banner = app_banner
-      end
-
-      # Generate the application banner for help display
-      # @return [String] formatted banner text
-      def app_banner
-        t = ' ' * 8
-        return <<~END_OF_BANNER
-          NAME
-          #{t}#{Info::CMD_NAME} -- a command line tool for Aspera Applications (v#{Cli::VERSION})
-
-          SYNOPSIS
-          #{t}#{Info::CMD_NAME} COMMANDS [OPTIONS] [ARGS]
-
-          DESCRIPTION
-          #{t}Use Aspera application to perform operations on command line.
-          #{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: #{Info::CMD_NAME}
-          #{t}Note that commands can be written shortened (provided it is unique).
-
-          OPTIONS
-          #{t}Options begin with a '-' (minus), and value is provided on command line.
-          #{t}Special values are supported beginning with special prefix @pfx:, where pfx is one of:
-          #{t}#{ExtendedValue.instance.modifiers.join(', ')}
-          #{t}Dates format is 'DD-MM-YY HH:MM:SS', or 'now' or '-<num>h'
-
-          ARGS
-          #{t}Some commands require mandatory arguments, e.g. a path.
-        END_OF_BANNER
-      end
-
-      # Define header for manual and declare all global options
-      # @return [nil]
-      def declare_global_options
-        Log.log.debug('declare_global_options')
-        @context.options.declare(:help, 'Show this message', allowed: Allowed::TYPES_NONE, short: 'h'){@option_help = true}
-        @context.options.declare(:bash_comp, 'Generate bash completion for command', allowed: Allowed::TYPES_NONE){@bash_completion = true}
-        @context.options.declare(:show_config, 'Display parameters used for the provided action', allowed: Allowed::TYPES_NONE){@option_show_config = true}
-        @context.options.declare(:version, 'Display version', allowed: Allowed::TYPES_NONE, short: 'v'){@context.formatter.display_message(:data, Cli::VERSION); Process.exit(0)} # rubocop:disable Style/Semicolon
-        @context.options.declare(
-          :ui, 'Method to start browser',
-          allowed: USER_INTERFACES,
-          handler: {o: Environment.instance, m: :url_method}
-        )
-        @context.options.declare(
-          :invalid_characters, 'Replacement character and invalid filename characters',
-          handler: {o: Environment.instance, m: :file_illegal_characters}
-        )
-        @context.options.declare(:log_level, 'Log level', allowed: Log::LEVELS, handler: {o: Log.instance, m: :level})
-        @context.options.declare(:log_format, 'Log formatter', allowed: [Proc, Logger::Formatter, String], handler: {o: Log.instance, m: :formatter})
-        @context.options.declare(:logger, 'Logging method', allowed: Log::LOG_TYPES, handler: {o: Log.instance, m: :logger_type})
-        @context.options.declare(:lock_port, 'Prevent dual execution of a command, e.g. in cron', allowed: Allowed::TYPES_INTEGER)
-        @context.options.declare(:once_only, 'Process only new items (some commands)', allowed: Allowed::TYPES_BOOLEAN, default: false)
-        @context.options.declare(:log_secrets, 'Show passwords in logs', allowed: Allowed::TYPES_BOOLEAN, handler: {o: SecretHider.instance, m: :log_secrets})
-        @context.options.declare(:clean_temp, 'Cleanup temporary files on exit', allowed: Allowed::TYPES_BOOLEAN, handler: {o: TempFileManager.instance, m: :cleanup_on_exit})
-        @context.options.declare(:temp_folder, 'Temporary folder', handler: {o: TempFileManager.instance, m: :global_temp})
-        @context.options.declare(:pid_file, 'Write process identifier to file, delete on exit')
-        @context.options.declare(
-          :parser, 'Default parser for structured parameters and options',
-          handler: {o: ExtendedValue.instance, m: :default_decoder},
-          allowed: ExtendedValue::DEFAULT_DECODERS,
-          default: ExtendedValue::DEFAULT_DECODERS.first
-        )
-        # Parse declared options
-        @context.options.parse_options!
-      end
-
-      # Get the plugin instance based on name
-      # Also loads the plugin options, and default values from conf file
-      # @param plugin_name_sym [Symbol] symbol for plugin name
-      # @return [Plugins::Base] the plugin instance
-      def get_plugin_instance_with_options(plugin_name_sym)
-        Log.log.debug{"get_plugin_instance_with_options(#{plugin_name_sym})"}
-        # Load default params only if no param already loaded before plugin instantiation
-        @context.config.add_plugin_default_preset(plugin_name_sym)
-        command_plugin = Plugins::Factory.instance.create(plugin_name_sym, context: @context)
-        return command_plugin
-      end
-
-      # Generate bash completion suggestions
-      # @return [nil]
-      def generate_bash_completion
-        if @context.options.get_next_argument('', multiple: true, mandatory: false).nil?
-          Plugins::Factory.instance.plugin_list.each{ |p| puts p}
-        else
-          Log.log.warn('only first level completion so far')
-        end
-        Process.exit(0)
-      end
-    end
-  end
-end

data/lib/aspera/json_rpc.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-# cspell:ignore blankslate
-
-require 'aspera/rest_error_analyzer'
-require 'aspera/assert'
-require 'blankslate'
-
-Aspera::RestErrorAnalyzer.instance.add_simple_handler(name: 'JSON RPC', path: %w[error message], always: true)
-
-module Aspera
-  # a very simple JSON RPC client
-  class JsonRpcClient < BlankSlate
-    JSON_RPC_VERSION = '2.0'
-    reveal :instance_variable_get
-    reveal :inspect
-    reveal :to_s
-
-    def initialize(api, namespace = nil)
-      super()
-      @api = api
-      @namespace = namespace
-      @request_id = 0
-    end
-
-    def respond_to_missing?(_sym, _include_private = false)
-      true
-    end
-
-    def method_missing(method, *args, &block)
-      args = args.first if args.size == 1 && args.first.is_a?(Hash)
-      data = @api.create('', {
-        jsonrpc: JSON_RPC_VERSION,
-        method:  "#{@namespace}#{method}",
-        params:  args,
-        id:      @request_id += 1
-      })
-      Aspera.assert_type(data, Hash){'response'}
-      Aspera.assert(data['jsonrpc'] == JSON_RPC_VERSION){'bad version in response'}
-      Aspera.assert(data.key?('id')){'missing id in response'}
-      Aspera.assert(!(data.key?('error') && data.key?('result'))){'both error and response'}
-      Aspera.assert(
-        !data.key?('error') ||
-        data['error'].is_a?(Hash) &&
-        data['error']['code'].is_a?(Integer) &&
-        data['error']['message'].is_a?(String)
-      ){'bad error response'}
-      return data['result']
-    end
-  end
-end