aspera-cli 4.14.0 → 4.16.0

data/lib/aspera/fasp/parameters.rb

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
 
 require 'aspera/log'
+require 'aspera/assert'
 require 'aspera/command_line_builder'
 require 'aspera/temp_file_manager'
 require 'aspera/fasp/error'
+require 'aspera/fasp/installation'
+require 'aspera/cli/formatter'
+require 'aspera/rest'
 require 'securerandom'
 require 'base64'
 require 'json'
@@ -16,19 +20,20 @@ module Aspera
     # translate transfer specification to ascp parameter list
     class Parameters
       # Agents shown in manual for parameters (sub list)
-      SUPPORTED_AGENTS = %i[direct node connect].freeze
+      SUPPORTED_AGENTS = %i[direct node connect trsdk httpgw].freeze
       # Short names of columns in manual
       SUPPORTED_AGENTS_SHORT = SUPPORTED_AGENTS.map{|a|a.to_s[0].to_sym}
       FILE_LIST_OPTIONS = ['--file-list', '--file-pair-list'].freeze
-      SUPPORTED_OPTIONS = %i[ascp_args wss].freeze
+      # options that can be provided to the constructor, and then in @options
+      SUPPORTED_OPTIONS = %i[ascp_args wss check_ignore quiet trusted_certs].freeze
 
-      private_constant :SUPPORTED_AGENTS, :FILE_LIST_OPTIONS
+      private_constant :SUPPORTED_AGENTS, :FILE_LIST_OPTIONS, :SUPPORTED_OPTIONS
 
       class << self
         # Temp folder for file lists, must contain only file lists
         # because of garbage collection takes any file there
         # this could be refined, as , for instance, on macos, temp folder is already user specific
-        @file_list_folder = TempFileManager.instance.new_file_path_global('asession_filelists')
+        @file_list_folder = TempFileManager.instance.new_file_path_global('asession_filelists') # cspell:disable-line
         @param_description_cache = nil
         # @return normalized description of transfer spec parameters, direct from yaml
         def description
@@ -48,7 +53,7 @@ module Aspera
             param = {name: name, type: [options[:accepted_types]].flatten.join(','), description: options[:desc]}
             # add flags for supported agents in doc
             SUPPORTED_AGENTS.each do |a|
-              param[a.to_s[0].to_sym] = options[:agents].nil? || options[:agents].include?(a) ? 'Y' : ''
+              param[a.to_s[0].to_sym] = Cli::Formatter.tick(options[:agents].nil? || options[:agents].include?(a))
             end
             # only keep lines that are usable in supported agents
             next if SUPPORTED_AGENTS_SHORT.inject(true){|m, j|m && param[j].empty?}
@@ -66,9 +71,12 @@ module Aspera
                 else
                   raise "error: #{param}"
                 end.map{|n|"{#{n}}"}.join('|')
-                conv = options[:cli].key?(:convert) ? '(conversion)' : ''
-                "#{options[:cli][:switch]} #{conv}#{values}"
-              else ''
+                conversion_tag = options[:cli].key?(:convert) ? '(conversion)' : ''
+                "#{options[:cli][:switch]} #{conversion_tag}#{values}"
+              when :special then Cli::Formatter.special('special')
+              when :ignore then Cli::Formatter.special('ignored')
+              else
+                param[:d].eql?(tick_yes) ? '' : 'n/a'
               end
             if options.key?(:enum)
               param[:description] += "\nAllowed values: #{options[:enum].join(', ')}"
@@ -119,21 +127,26 @@ module Aspera
 
       # @param options [Hash] key: :wss: bool, :ascp_args: array of strings
       def initialize(job_spec, options)
+        assert_type(job_spec, Hash)
+        assert_type(options, Hash)
         @job_spec = job_spec
         # check necessary options
-        raise 'Internal: missing options' unless (SUPPORTED_OPTIONS - options.keys).empty?
+        missing_options = SUPPORTED_OPTIONS - options.keys
+        assert(missing_options.empty?){"missing options: #{missing_options.join(', ')}"}
         @options = SUPPORTED_OPTIONS.each_with_object({}){|o, h| h[o] = options[o]}
-        Log.dump(:options, @options)
-        raise 'ascp args must be an Array' unless @options[:ascp_args].is_a?(Array)
-        raise 'ascp args must be an Array of String' if @options[:ascp_args].any?{|i|!i.is_a?(String)}
+        Log.log.debug{Log.dump(:parameters_options, @options)}
+        Log.log.debug{Log.dump(:dismiss_options, options.keys - SUPPORTED_OPTIONS)}
+        assert_type(@options[:ascp_args], Array){'ascp_args'}
+        assert(@options[:ascp_args].all?(String)){'ascp arguments must Strings'}
         @builder = Aspera::CommandLineBuilder.new(@job_spec, self.class.description)
       end
 
+      # either place source files on command line, or add file list file
       def process_file_list
         # is the file list provided through EX_ parameters?
         ascp_file_list_provided = self.class.ts_has_ascp_file_list(@job_spec, @options[:ascp_args])
         # set if paths is mandatory in ts
-        @builder.params_definition['paths'][:mandatory] = !@job_spec.key?('keepalive') && !ascp_file_list_provided
+        @builder.params_definition['paths'][:mandatory] = !@job_spec.key?('keepalive') && !ascp_file_list_provided # cspell:words keepalive
         # get paths in transfer spec (after setting if it is mandatory)
         ts_paths_array = @builder.read_param('paths')
         if ascp_file_list_provided && !ts_paths_array.nil?
@@ -153,20 +166,21 @@ module Aspera
               Log.log.debug('placing source file list on command line (no file list file)')
               @builder.add_command_line_options(ts_paths_array.map{|i|i['source']})
             else
-              raise "All elements of paths must have a 'source' key" unless ts_paths_array.all?{|i|i.key?('source')}
+              assert(ts_paths_array.all?{|i|i.key?('source')}){"All elements of paths must have a 'source' key"}
               is_pair_list = ts_paths_array.any?{|i|i.key?('destination')}
               raise "All elements of paths must be consistent with 'destination' key" if is_pair_list && !ts_paths_array.all?{|i|i.key?('destination')}
               # safer option: generate a file list file if there is storage defined for it
               # if there is one destination in paths, then use file-pair-list
               if is_pair_list
                 option = '--file-pair-list'
-                lines = ts_paths_array.each_with_object([]){|e, m|m.push(e['source'], e['destination'] || e['source']); }
+                lines = ts_paths_array.each_with_object([]){|e, m|m.push(e['source'], e['destination'] || e['source']) }
               else
                 option = '--file-list'
                 lines = ts_paths_array.map{|i|i['source']}
               end
               file_list_file = Aspera::TempFileManager.instance.new_file_path_in_folder(self.class.file_list_folder)
-              File.write(file_list_file, lines.join("\n"))
+              Log.log.debug{Log.dump(:file_list, lines)}
+              File.write(file_list_file, lines.join("\n"), encoding: 'UTF-8')
               Log.log.debug{"#{option}=\n#{File.read(file_list_file)}".red}
             end
           end
@@ -176,67 +190,92 @@ module Aspera
         @builder.add_command_line_options(["#{option}=#{file_list_file}"]) unless option.nil?
       end
 
-      # translate transfer spec to env vars and command line arguments for ascp
-      # NOTE: parameters starting with "EX_" (extended) are not standard
-      def ascp_args
-        env_args = {
-          args:         [],
-          env:          {},
-          ascp_version: :ascp
-        }
-        # some ssh credentials are required to avoid interactive password input
-        if !@job_spec.key?('remote_password') &&
-            !@job_spec.key?('ssh_private_key') &&
-            !@job_spec.key?('EX_ssh_key_paths')
-          raise Fasp::Error, 'required: password or ssh key (value or path)'
-        end
-
-        # special cases
-        @job_spec.delete('source_root') if @job_spec.key?('source_root') && @job_spec['source_root'].empty?
-
-        # use web socket session initiation ?
+      def remote_certificates
+        certificates_to_use = []
+        # use web socket secure for session ?
         if @builder.read_param('wss_enabled') && (@options[:wss] || !@job_spec.key?('fasp_port'))
           # by default use web socket session if available, unless removed by user
           @builder.add_command_line_options(['--ws-connect'])
-          # TODO: option to give order ssh,ws (legacy http is implied bu ssh)
+          # TODO: option to give order ssh,ws (legacy http is implied by ssh)
           # This will need to be cleaned up in aspera core
           @job_spec['ssh_port'] = @builder.read_param('wss_port')
           @job_spec.delete('fasp_port')
           @job_spec.delete('EX_ssh_key_paths')
           @job_spec.delete('sshfp')
+          # ignore cert for wss ?
+          if @options[:check_ignore]&.call(@job_spec['remote_host'], @job_spec['wss_port'])
+            wss_cert_file = TempFileManager.instance.new_file_path_global('wss_cert')
+            wss_url = "https://#{@job_spec['remote_host']}:#{@job_spec['wss_port']}"
+            File.write(wss_cert_file, Rest.remote_certificates(wss_url))
+            certificates_to_use.push(wss_cert_file)
+          end
           # set location for CA bundle to be the one of Ruby, see env var SSL_CERT_FILE / SSL_CERT_DIR
-          @job_spec['EX_ssh_key_paths'] = [OpenSSL::X509::DEFAULT_CERT_FILE]
-          Log.log.debug('CA certs: EX_ssh_key_paths <- DEFAULT_CERT_FILE from openssl')
+          certificates_to_use.concat(@options[:trusted_certs]) if @options[:trusted_certs]
         else
           # remove unused parameter (avoid warning)
           @job_spec.delete('wss_port')
+          # add SSH bypass keys when authentication is token and no auth is provided
+          if @job_spec.key?('token') && !@job_spec.key?('remote_password')
+            # @job_spec['remote_password'] = Installation.instance.ssh_cert_uuid # not used: no passphrase
+            certificates_to_use.concat(Installation.instance.aspera_token_ssh_key_paths)
+          end
+        end
+        return certificates_to_use
+      end
+
+      # translate transfer spec to env vars and command line arguments for ascp
+      # NOTE: parameters starting with "EX_" (extended) are not standard
+      def ascp_args
+        env_args = {
+          args:         [],
+          env:          {},
+          ascp_version: :ascp
+        }
+
+        # special cases
+        @job_spec.delete('source_root') if @job_spec.key?('source_root') && @job_spec['source_root'].empty?
+
+        # notify multi-session was already used, anyway it was deleted by agent direct
+        assert(!@builder.read_param('multi_session'))
+
+        # add ssh or wss certificates
+        remote_certificates.each do |cert|
+          Log.log.trace1{"adding certificate: #{cert}"}
+          env_args[:args].unshift('-i', cert)
         end
 
         # process parameters as specified in table
         @builder.process_params
 
+        base64_destination = false
         # symbol must be index of Installation.paths
         if @builder.read_param('use_ascp4')
           env_args[:ascp_version] = :ascp4
         else
           env_args[:ascp_version] = :ascp
-          # destination will be base64 encoded, put before path arguments
-          @builder.add_command_line_options(['--dest64'])
+          base64_destination = true
         end
-        # get list of files to transfer and build arg for ascp
-        process_file_list
-        # optional args, at the end to override previous ones (to allow override)
+        # destination will be base64 encoded, put this before source path arguments
+        @builder.add_command_line_options(['--dest64']) if base64_destination
+        # optional arguments, at the end to override previous ones (to allow override)
         @builder.add_command_line_options(@builder.read_param('EX_ascp_args'))
         @builder.add_command_line_options(@options[:ascp_args])
+        # get list of source files to transfer and build arg for ascp
+        process_file_list
         # process destination folder
         destination_folder = @builder.read_param('destination_root') || '/'
         # ascp4 does not support base64 encoding of destination
-        destination_folder = Base64.strict_encode64(destination_folder) unless env_args[:ascp_version].eql?(:ascp4)
+        destination_folder = Base64.strict_encode64(destination_folder) if base64_destination
         # destination MUST be last command line argument to ascp
         @builder.add_command_line_options([destination_folder])
-
-        @builder.add_env_args(env_args[:env], env_args[:args])
-
+        @builder.add_env_args(env_args)
+        env_args[:args].unshift('-q') if @options[:quiet]
+        # add fallback cert and key as arguments if needed
+        if ['1', 1, true, 'force'].include?(@job_spec['http_fallback'])
+          env_args[:args].unshift('-Y', Installation.instance.path(:fallback_private_key))
+          env_args[:args].unshift('-I', Installation.instance.path(:fallback_certificate))
+        end
+        Log.log.debug{"ascp args: #{env_args}"}
         return env_args
       end
     end # Parameters

data/lib/aspera/fasp/parameters.yaml

@@ -2,13 +2,13 @@
 # accepted_types : accepted types for non-enum
 # default        : default value if not specified
 # enum           : set with list of values for enum types accepted in transfer spec
-# agents         : supported agents (for doc only)
+# agents         : supported agents (for doc only), if not specified: all
 # required       : optional, default: false
 # cli.type       : ascp: type of parameter, one of CLI_OPTION_TYPES
 # cli.switch     : ascp: switch for ascp command line
 # cli.convert    : ascp: transform value: either a Hash with conversion values, or name of class
 # cli.variable   : ascp: name of env var
-# cspell:words dgram
+# cspell:words dgram dnat dnats faspmgr asperanoded xattrs keepalive datagram
 ---
 cipher:
   :desc: "In transit encryption type."
@@ -79,7 +79,11 @@ destination_root:
   :cli:
     :type: :special
 destination_root_id:
-  :desc: The file ID of the destination root directory. Required when using Bearer token auth for the destination node.
+  :desc: |-
+    The file ID of the destination root directory.
+    Required when using Bearer token auth for the destination node.
+
+
   :accepted_types: :string
   :agents:
   - :sdk
@@ -177,7 +181,7 @@ multi_session:
 
   :accepted_types: :int
   :cli:
-    :type: :ignore
+    :type: :special
     :switch: "-C"
 multi_session_threshold:
   :desc: |-
@@ -227,15 +231,37 @@ precalculate_job_size:
   :cli:
     :type: :opt_without_arg
 preserve_access_time:
+  :desc: |-
+    Preserve the source-file access timestamps at the destination.
+    Because source access times are updated by the transfer operation,
+    the timestamp that is preserved is the one just before to the transfer.
+
+
   :cli:
     :type: :opt_without_arg
 preserve_creation_time:
+  :desc: |-
+    (Windows only) Preserve source-file creation timestamps at the destination.
+    Only Windows systems retain information about creation time.
+    If the destination is not a Windows computer, this option is ignored.
+
+
   :cli:
     :type: :opt_without_arg
 preserve_modification_time:
+  :desc: |-
+    Set the modification time, the last time a file or directory was modified (written), of a transferred file
+    to the modification of the source file or directory.
+    Preserve source-file modification timestamps at the destination.
+
+
   :cli:
     :type: :opt_without_arg
 preserve_times:
+  :desc: Preserve file timestamps. 
+  :agents:
+  - :sdk
+  - :node
   :cli:
     :type: :opt_without_arg
 rate_policy:
@@ -437,6 +463,7 @@ use_ascp4:
   :cli:
     :type: :special
 use_system_ssh:
+  :desc: TODO, comment...
   :accepted_types: :string
   :agents:
   - :sdk
@@ -454,22 +481,46 @@ source_root:
     :switch: "--source-prefix64"
     :convert: Aspera::Fasp::Parameters.convert_base64
 min_rate_cap_kbps:
+  :desc: |-
+    The highest minimum rate that an incoming transfer can request, in kilobits per second.
+    Client minimum rate requests that exceed the minimum rate cap are ignored.
+    The default value of unlimited applies no cap to the minimum rate. (Default: 0)
+
+
   :accepted_types: :int
   :cli:
     :type: :ignore
 lock_rate_policy:
+  :desc: If true, lock the rate policy to the default value.
   :accepted_types: :bool
+  :agents:
+  - :sdk
+  - :connect
   :cli:
     :type: :ignore
 lock_target_rate_kbps:
+  :desc: |-
+    If true, lock the target transfer rate to the default value set for target_rate_kbps.
+    If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
+
+
   :accepted_types: :bool
   :cli:
     :type: :ignore
 lock_min_rate_kbps:
+  :desc: |-
+    If true, lock the minimum transfer rate to the value set for min_rate_kbps.
+    If false, users can adjust the transfer rate up to the value set for target_rate_cap_kbps.
+
+
   :accepted_types: :bool
+  :agents:
+  - :sdk
+  - :connect
   :cli:
     :type: :ignore
 apply_local_docroot:
+  :desc: Apply local docroot to source paths.
   :agents:
   - :direct
   - :sdk
@@ -561,7 +612,7 @@ remove_empty_source_directory:
     :type: :opt_without_arg
 EX_at_rest_password:
   :desc: Content protection password
-  :deprecation: "Use standard spec parameter: content_protection_password"
+  :deprecation: "(4.13) Use standard spec parameter: content_protection_password"
   :agents:
   - :direct
   :cli:
@@ -573,6 +624,7 @@ EX_proxy_password:
     May be overridden by password in URL provided in parameter: proxy.
 
 
+  :deprecation: (4.14) Use env var ASPERA_PROXY_PASS
   :agents:
   - :direct
   :cli:
@@ -580,14 +632,17 @@ EX_proxy_password:
     :variable: ASPERA_PROXY_PASS
 EX_license_text:
   :desc: "License file text override.\nBy default ascp looks for license file near executable."
+  :deprecation: (4.14) Use env var ASPERA_SCP_LICENSE
   :agents:
   - :direct
   :cli:
     :type: :envvar
     :variable: ASPERA_SCP_LICENSE
 keepalive:
+  :desc: The session is running in persistent session mode.
   :agents:
-  - :none
+  - :sdk
+  - :direct
   :cli:
     :type: :opt_without_arg
 dgram_size:
@@ -610,6 +665,7 @@ sshfp:
     :switch: "--check-sshfp"
 EX_http_proxy_url:
   :desc: Specify the proxy server address used by HTTP Fallback
+  :deprecation: (4.14) TODO, use proxy option ?
   :agents:
   - :direct
   :cli:
@@ -617,6 +673,7 @@ EX_http_proxy_url:
     :switch: "-x"
 EX_ssh_key_paths:
   :desc: Use public key authentication for SSH and specify the private key file paths
+  :deprecation: (4.14) Use option transfer_info.ascp_args
   :accepted_types: :array
   :agents:
   - :direct
@@ -625,6 +682,7 @@ EX_ssh_key_paths:
     :switch: "-i"
 EX_http_transfer_jpeg:
   :desc: HTTP transfers as JPEG file
+  :deprecation: (4.14) Use option transfer_info.ascp_args
   :accepted_types: :int
   :default: '0'
   :agents:
@@ -634,6 +692,7 @@ EX_http_transfer_jpeg:
     :switch: "-j"
 EX_no_read:
   :desc: no read source
+  :deprecation: (4.14) Use option transfer_info.ascp_args
   :agents:
   - :direct
   :cli:
@@ -641,12 +700,14 @@ EX_no_read:
     :switch: "--no-read"
 EX_no_write:
   :desc: no write on destination
+  :deprecation: (4.14) Use option transfer_info.ascp_args
   :agents:
   - :direct
   :cli:
     :type: :opt_without_arg
     :switch: "--no-write"
 target_rate_percentage:
+  :desc: "TODO: remove ?"
   :cli:
     :type: :ignore
 rate_policy_allowed:
@@ -661,15 +722,18 @@ rate_policy_allowed:
   :cli:
     :type: :ignore
 fasp_url:
+  :desc: Only used in Faspex.
   :agents:
   - :unknown
   :cli:
     :type: :ignore
 lock_min_rate:
+  :desc: "TODO: remove ?"
   :accepted_types: :bool
   :cli:
     :type: :ignore
 lock_target_rate:
+  :desc: "TODO: remove ?"
   :accepted_types: :bool
   :cli:
     :type: :ignore
@@ -684,13 +748,15 @@ cipher_allowed:
   :cli:
     :type: :ignore
 obfuscate_file_names:
+  :desc: HTTP Gateway obfuscates file names when set to true.
   :accepted_types: :bool
   :agents:
-  - :unknown
+  - :httpgw
   :cli:
     :type: :ignore
 EX_file_list:
   :desc: source file list
+  :deprecation: (4.14) Use command line file list, or option transfer_info.ascp_args
   :agents:
   - :direct
   :cli:
@@ -698,6 +764,7 @@ EX_file_list:
     :switch: "--file-list"
 EX_file_pair_list:
   :desc: source file pair list
+  :deprecation: (4.14) Use command line file pair list, or option transfer_info.ascp_args
   :agents:
   - :direct
   :cli:
@@ -705,7 +772,7 @@ EX_file_pair_list:
     :switch: "--file-pair-list"
 EX_ascp_args:
   :desc: Add native command line arguments to ascp
-  :deprecation: Use parameter ascp_args in option transfer_info
+  :deprecation: (4.13) Use option transfer_info.ascp_args
   :accepted_types: :array
   :agents:
   - :direct

data/lib/aspera/fasp/products.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+# cspell:ignore LOCALAPPDATA
+require 'aspera/environment'
+
+module Aspera
+  module Fasp
+    # find Aspera standard products installation in standard paths
+    class Products
+      # known product names
+      CONNECT = 'IBM Aspera Connect'
+      ASPERA = 'IBM Aspera (Client)'
+      CLI_V1 = 'Aspera CLI (deprecated)'
+      DRIVE = 'Aspera Drive (deprecated)'
+      HSTS = 'IBM Aspera High-Speed Transfer Server'
+      # product information manifest: XML (part of aspera product)
+      INFO_META_FILE = 'product-info.mf'
+      BIN_SUBFOLDER = 'bin'
+      ETC_SUBFOLDER = 'etc'
+      VAR_RUN_SUBFOLDER = File.join('var', 'run')
+
+      @@found_products = nil # rubocop:disable Style/ClassVars
+      class << self
+        # @return product folders depending on OS fields
+        # :expected  M app name is taken from the manifest if present, else defaults to this value
+        # :app_root  M main folder for the application
+        # :log_root  O location of log files (Linux uses syslog)
+        # :run_root  O only for Connect Client, location of http port file
+        # :sub_bin   O subfolder with executables, default : bin
+        def product_locations_on_current_os
+          result =
+            case Aspera::Environment.os
+            when Aspera::Environment::OS_WINDOWS then [{
+              expected: CONNECT,
+              app_root: File.join(ENV.fetch('LOCALAPPDATA', nil), 'Programs', 'Aspera', 'Aspera Connect'),
+              log_root: File.join(ENV.fetch('LOCALAPPDATA', nil), 'Aspera', 'Aspera Connect', 'var', 'log'),
+              run_root: File.join(ENV.fetch('LOCALAPPDATA', nil), 'Aspera', 'Aspera Connect')
+            }, {
+              expected: CLI_V1,
+              app_root: File.join('C:', 'Program Files', 'Aspera', 'cli'),
+              log_root: File.join('C:', 'Program Files', 'Aspera', 'cli', 'var', 'log')
+            }, {
+              expected: HSTS,
+              app_root: File.join('C:', 'Program Files', 'Aspera', 'Enterprise Server'),
+              log_root: File.join('C:', 'Program Files', 'Aspera', 'Enterprise Server', 'var', 'log')
+            }]
+            when Aspera::Environment::OS_X then [{
+              expected: CONNECT,
+              app_root: File.join(Dir.home, 'Applications', 'Aspera Connect.app'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'Aspera_Connect'),
+              run_root: File.join(Dir.home, 'Library', 'Application Support', 'Aspera', 'Aspera Connect'),
+              sub_bin:  File.join('Contents', 'Resources')
+            }, {
+              expected: CONNECT,
+              app_root: File.join('', 'Applications', 'Aspera Connect.app'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'Aspera_Connect'),
+              run_root: File.join(Dir.home, 'Library', 'Application Support', 'Aspera', 'Aspera Connect'),
+              sub_bin:  File.join('Contents', 'Resources')
+            }, {
+              expected: CLI_V1,
+              app_root: File.join(Dir.home, 'Applications', 'Aspera CLI'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'Aspera')
+            }, {
+              expected: HSTS,
+              app_root: File.join('', 'Library', 'Aspera'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'Aspera')
+            }, {
+              expected: DRIVE,
+              app_root: File.join('', 'Applications', 'Aspera Drive.app'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'Aspera_Drive'),
+              sub_bin:  File.join('Contents', 'Resources')
+            }, {
+              expected: ASPERA,
+              app_root: File.join('', 'Applications', 'IBM Aspera.app'),
+              log_root: File.join(Dir.home, 'Library', 'Logs', 'IBM Aspera'),
+              sub_bin:  File.join('Contents', 'Resources', 'sdk', 'aspera', 'bin')
+            }]
+            else [{ # other: Linux and Unix family
+              expected: CONNECT,
+              app_root: File.join(Dir.home, '.aspera', 'connect'),
+              run_root: File.join(Dir.home, '.aspera', 'connect')
+            }, {
+              expected: CLI_V1,
+              app_root: File.join(Dir.home, '.aspera', 'cli')
+            }, {
+              expected: HSTS,
+              app_root: File.join('', 'opt', 'aspera')
+            }]
+            end
+          result # .each {|item| item.deep_do {|h, _k, _v, _m|h.freeze}}.freeze
+        end
+
+        # @return the list of installed products in format of product_locations_on_current_os
+        def installed_products
+          if @@found_products.nil?
+            scan_locations = product_locations_on_current_os.clone
+            # add SDK as first search path
+            scan_locations.unshift({
+              expected: 'SDK',
+              app_root: Installation.instance.sdk_folder,
+              sub_bin:  ''
+            })
+            # search installed products: with ascp
+            @@found_products = scan_locations.select! do |item| # rubocop:disable Style/ClassVars
+              # skip if not main folder
+              next false unless Dir.exist?(item[:app_root])
+              Log.log.debug{"Found #{item[:app_root]}"}
+              sub_bin = item[:sub_bin] || BIN_SUBFOLDER
+              item[:ascp_path] = File.join(item[:app_root], sub_bin, ascp_filename)
+              # skip if no ascp
+              next false unless File.exist?(item[:ascp_path])
+              # read info from product info file if present
+              product_info_file = "#{item[:app_root]}/#{INFO_META_FILE}"
+              if File.exist?(product_info_file)
+                res_s = XmlSimple.xml_in(File.read(product_info_file), {'ForceArray' => false})
+                item[:name] = res_s['name']
+                item[:version] = res_s['version']
+              else
+                item[:name] = item[:expected]
+              end
+              true # select this version
+            end
+          end
+          return @@found_products
+        end
+
+        # filename for ascp with optional extension (Windows)
+        def ascp_filename
+          return 'ascp' + Environment.exe_extension
+        end
+
+        # @return folder paths for specified applications
+        # @param name Connect or CLI
+        def folders(name)
+          found = Products.installed_products.select{|i|i[:expected].eql?(name) || i[:name].eql?(name)}
+          raise "Product: #{name} not found, please install." if found.empty?
+          return found.first
+        end
+
+        # @return the file path of local connect where API's URI can be read
+        def connect_uri
+          connect = folders(CONNECT)
+          folder = File.join(connect[:run_root], VAR_RUN_SUBFOLDER)
+          ['', 's'].each do |ext|
+            uri_file = File.join(folder, "http#{ext}.uri")
+            Log.log.debug{"checking connect port file: #{uri_file}"}
+            if File.exist?(uri_file)
+              return File.open(uri_file, &:gets).strip
+            end
+          end
+          raise "no connect uri file found in #{folder}"
+        end
+
+        # @ return path to configuration file of aspera CLI
+        # def cli_conf_file
+        #  connect = folders(PRODUCT_CLI_V1)
+        #  return File.join(connect[:app_root], BIN_SUBFOLDER, '.aspera_cli_conf')
+        # end
+      end
+    end
+  end
+end