aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/api/node.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/link_header'
 require 'aspera/transfer/spec'
 require 'aspera/rest'
 require 'aspera/oauth'
@@ -78,12 +79,12 @@ module Aspera
         attr_reader :api_options
         attr_reader :use_dynamic_key
 
-        def api_options=(h)
-          Aspera.assert_type(h, Hash)
-          h.each do |k, v|
-            Aspera.assert(@api_options.key?(k.to_sym)){"unknown api option: #{k} (#{OPTIONS.join(', ')})"}
-            Aspera.assert_type(v, TrueClass, FalseClass){"api options value for #{k} should be boolean"}
-            @api_options[k.to_sym] = v
+        def api_options=(options_hash)
+          Aspera.assert_type(options_hash, Hash)
+          options_hash.each do |key, val|
+            Aspera.assert(@api_options.key?(key.to_sym)){"unknown api option: #{key} (#{OPTIONS.join(', ')})"}
+            Aspera.assert_type(val, TrueClass, FalseClass){"api options value for #{key} should be boolean"}
+            @api_options[key.to_sym] = val
           end
         end
 
@@ -105,30 +106,30 @@ module Aspera
         end
 
         # Adds fields `public_keys` in provided Hash, if dynamic key is set.
-        # @param h [Hash] Hash to add public key to
+        # @param parameters [Hash] Hash to add public key to
         # @return [Hash] Hash with public key added
-        def add_public_key(h)
+        def add_public_key(parameters)
           if @dynamic_key
             ssh_key = Net::SSH::Buffer.from(:key, @dynamic_key)
             # Get pub key in OpenSSH public key format (authorized_keys)
-            h['public_keys'] = [
+            parameters['public_keys'] = [
               ssh_key.read_string,
               Base64.strict_encode64(ssh_key.to_s)
             ].join(' ')
           end
-          return h
+          return parameters
         end
 
         # Adds fields `ssh_private_key` in provided Hash, if dynamic key is set.
-        # @param h [Hash] Hash to add private key to
-        def add_private_key(h)
-          h['ssh_private_key'] = @dynamic_key.to_pem if @dynamic_key
-          return h
+        # @param parameters [Hash] Hash to add private key to
+        def add_private_key(parameters)
+          parameters['ssh_private_key'] = @dynamic_key.to_pem if @dynamic_key
+          return parameters
         end
 
         # For access keys: provide expression to match entry in folder
-        # @param match_expression one of supported types
-        # @return lambda function
+        # @param match_expression [Proc, Regexp, String] one of supported types
+        # @return [Proc] lambda function
         def file_matcher(match_expression)
           case match_expression
           when Proc then return match_expression
@@ -146,7 +147,8 @@ module Aspera
         end
 
         # Split path into folder + filename
-        # @return [Array] containing folder + inside folder/file
+        # @param path [String] file path to split
+        # @return [Array(String, String)] containing folder + inside folder/file
         def split_folder(path)
           folder = path.split(PATH_SEPARATOR)
           inside = folder.pop
@@ -160,7 +162,8 @@ module Aspera
         end
 
         # Decode node scope into access key and scope
-        # @return [Hash]
+        # @param scope [String] scope string to decode
+        # @return [Hash] decoded scope with access key and scope parts
         def decode_scope(scope)
           items = scope.split(Scope::SEPARATOR, 2)
           Aspera.assert(items.length.eql?(2)){"invalid scope: #{scope}"}
@@ -174,9 +177,9 @@ module Aspera
         # @param private_key [OpenSSL::PKey::RSA] Private key to sign the token
         def bearer_token(access_key:, payload:, private_key:)
           Aspera.assert_type(payload, Hash)
-          Aspera.assert(payload.key?('user_id'))
+          Aspera.assert(payload.key?('user_id'), 'payload must have user_id')
           Aspera.assert_type(payload['user_id'], String)
-          Aspera.assert(!payload['user_id'].empty?)
+          Aspera.assert(!payload['user_id'].empty?, 'user_id must not be empty')
           Aspera.assert_type(private_key, OpenSSL::PKey::RSA)
           # Manage convenience parameters
           expiration_sec = payload['_validity'] || BEARER_TOKEN_VALIDITY_DEFAULT
@@ -205,7 +208,7 @@ module Aspera
           # If username is not provided, use the access key from the token
           if access_key.nil?
             access_key = Node.decode_scope(Node.decode_bearer_token(OAuth::Factory.bearer_token(bearer_auth))['scope'])[:access_key]
-            Aspera.assert(!access_key.nil?)
+            Aspera.assert(!access_key.nil?, 'access_key could not be determined from token')
           end
           return {
             HEADER_X_ASPERA_ACCESS_KEY => access_key,
@@ -240,7 +243,7 @@ module Aspera
         return tspec
       end
 
-      # @returns [Node, nil] a Node Api object or nil if no App defined
+      # @return [Node, nil] a Node Api object or nil if no App defined
       def node_id_to_node(node_id)
         if !@app_info.nil?
           return self if node_id.eql?(@app_info.node_info['id'])
@@ -337,7 +340,7 @@ module Aspera
       # @param top_file_path [String] path of top folder (default = /)
       # @para query [Hash, nil] optional query for `read`
       def process_folder_tree(method_sym:, state:, top_file_id:, top_file_path: '/', query: nil)
-        Aspera.assert(!top_file_path.nil?){'top_file_path not set'}
+        Aspera.assert(!top_file_path.nil?, 'top_file_path not set')
         Log.log.debug{"process_folder_tree: node=#{@app_info ? @app_info.node_info['id'] : 'nil'}, file id=#{top_file_id},  path=#{top_file_path}"}
         # Start at top folder
         folders_to_explore = [{id: top_file_id, path: top_file_path}]
@@ -390,7 +393,7 @@ module Aspera
         return NodeFileId.new(self, top_file_id) if path_elements.empty?
         resolve_state = {path: path_elements, consumed: [], result: nil, process_last_link: process_last_link}
         process_folder_tree(method_sym: :process_api_fid, state: resolve_state, top_file_id: top_file_id)
-        raise ParameterError, "Entry not found: #{resolve_state[:path].first} in /#{resolve_state[:consumed].join(PATH_SEPARATOR)}" if resolve_state[:result].nil?
+        Aspera.assert(!resolve_state[:result].nil?, type: ParameterError){"Entry not found: #{resolve_state[:path].first} in /#{resolve_state[:consumed].join(PATH_SEPARATOR)}"}
         Log.log.debug{"resolve_api_fid: #{path} -> #{resolve_state[:result].node_api.base_url} #{resolve_state[:result].file_id}"}
         return resolve_state[:result]
       end
@@ -405,7 +408,7 @@ module Aspera
       #     - 'destination' [String]: Destination path (optional)
       def resolve_api_fid_paths(top_file_id, paths)
         Aspera.assert_type(paths, Array)
-        Aspera.assert(paths.size.positive?)
+        Aspera.assert(paths.size.positive?, 'paths must not be empty')
         split_sources = paths.map{ |p| Pathname(p['source']).each_filename.to_a}
         root = []
         split_sources.map(&:size).min.times do |i|
@@ -490,7 +493,7 @@ module Aspera
         case auth_params[:type]
         when :basic
           ak_name = auth_params[:username]
-          Aspera.assert(auth_params[:password]){'no secret in node object'}
+          Aspera.assert(auth_params[:password], 'no secret in node object')
           ak_token = Rest.basic_authorization(auth_params[:username], auth_params[:password])
         when :oauth2
           ak_name = params[:headers][HEADER_X_ASPERA_ACCESS_KEY]
@@ -551,7 +554,7 @@ module Aspera
       def read_with_paging(subpath, query = nil, iteration: nil, **call_args)
         Aspera.assert_type(iteration, Array, NilClass){'iteration'}
         Aspera.assert_type(query, Hash, NilClass){'query'}
-        Aspera.assert(!call_args.key?(:query))
+        Aspera.assert(!call_args.key?(:query), ':query must not be in call_args (use query parameter)')
         query = {} if query.nil?
         query[:iteration_token] = iteration[0] unless iteration.nil? || iteration[0].nil?
         max = query.delete(RestList::MAX_ITEMS)
@@ -572,7 +575,7 @@ module Aspera
           # Update progress spinner
           RestParameters.instance.spinner_cb.call(item_list.length)
           # Parse Link header according to RFC 8288 to extract next iteration token
-          next_url = Rest.parse_link_header(http['Link'], rel: 'next')
+          next_url = LinkHeader.parse(http['Link']).find_href(rel: 'next')
           next_iteration_token = nil
           if next_url
             begin
@@ -629,7 +632,7 @@ module Aspera
       private
 
       # Method called in loop for each entry for `resolve_api_fid`
-      # @return `true` to continue digging, `false` to stop processing: set state[:result] if found
+      # @return [Boolean] `true` to continue digging, `false` to stop processing: set state[:result] if found
       def process_api_fid(entry, path, state)
         # Stop digging here if not in right path
         return false unless entry['name'].eql?(state[:path].first)
@@ -656,7 +659,7 @@ module Aspera
               # We found it
               other_node = nil
               other_node = node_id_to_node(entry['target_node_id']) if entry_has_link_information(entry)
-              raise Error, 'Cannot resolve link' if other_node.nil?
+              Aspera.assert(!other_node.nil?, type: Error){'Cannot resolve link'}
               state[:result] = NodeFileId.new(other_node, entry['target_id'])
             else
               # We found it but we do not process the link

data/lib/aspera/api/queries/bss_subscription_account.graphql

@@ -0,0 +1,18 @@
+query ($organization_id: ID!) {
+  aoc (organization_id: $organization_id) {
+    bssSubscription {
+      aocVersion endDate startDate termMonths plan trial termType
+      aocOrganizations { id }
+      additionalStorageVolumeGb additionalEgressVolumeGb
+      term { startDate endDate transferVolumeGb egressVolumeGb storageVolumeGb transferVolumeOffsetGb }
+      paygoRate { transferRate storageRate currency }
+      aocPlanData {
+        tier trial
+        workspaces { max }
+        users { planAmount max }
+        samlIntegration activity sharedInboxes uniqueUrls support watermarking byok
+        automation { planAmount, max }
+      }
+    }
+  }
+}

data/lib/aspera/api/queries/bss_subscription_usage.graphql

@@ -0,0 +1,18 @@
+query ($organization_id: ID!, $startDate: Date!, $endDate: Date!, $aggregate: TransferUsageAggregateOption!) {
+  aoc (organization_id: $organization_id) {
+    bssSubscription {
+      aocOrganizations { id }
+      additionalStorageVolumeGb additionalEgressVolumeGb
+      aocPlanData { tier trial }
+      term { transferVolumeGb egressVolumeGb storageVolumeGb startDate endDate transferVolumeOffsetGb }
+      termMonths
+      transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+      egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+    }
+    subscriptionEntitlements {
+      id
+      transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+      egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+    }
+  }
+}

data/lib/aspera/ascmd.rb

@@ -28,18 +28,18 @@ module Aspera
     ENUM_START = 1
 
     # Description of result structures (see ascmdtypes.h).
-    # Base types are big endian
-    # key = name of type
-    # index in array `fields` is: the numerical type of TLV - `ENUM_START`. i.e. add `ENUM_START` to index, to get `T`
-    # decoding always start at `result`
-    # some fields have special handling indicated by `special`
-    # field_list, list_tlv_list, list_tlv_restart are composed with a list of TLV
-    # decode:
-    # - :base : value
-    # - :buffer_list : an array of {btype,buffer}
-    # - :field_list : a hash, or array
-    # :check: ???
-    # rubocop:disable Layout/FirstHashElementLineBreak
+    # Base types are big endian.
+    # Keys are type names; the index in each `fields` array equals (TLV numerical type - `ENUM_START`).
+    # Decoding always starts at `result`.
+    # Some fields have special handling indicated by `special`:
+    #   - `:field_list`       : a Hash or Array of child TLVs
+    #   - `:list_tlv_list`    : a list of TLV sub-lists (Array of Hash)
+    #   - `:list_tlv_restart` : same but restarted per entry
+    # `decode` values:
+    #   - `:base`        : a single scalar value (unpack with `unpack`)
+    #   - `:buffer_list` : an Array of `{btype, buffer}` entries
+    #   - `:field_list`  : a Hash or Array built from child TLVs
+    # rubocop:disable-next Layout/FirstHashElementLineBreak
     TYPES_DESCR = {
       result: {decode: :field_list,
                fields: [{name: :file, is_a: :stat}, {name: :dir, is_a: :stat, special: :list_tlv_list}, {name: :size, is_a: :size}, {name: :error, is_a: :error},
@@ -73,7 +73,6 @@ module Aspera
       zstr:   {decode: :base, unpack: 'Z*'},
       blist:  {decode: :buffer_list}
     }.freeze
-    # rubocop:enable Layout/FirstHashElementLineBreak
 
     private_constant :TYPES_DESCR, :ENUM_START, :OPS_ARGS
 
@@ -87,8 +86,8 @@ module Aspera
 
     # execute an "as" command on a remote server
     # Version 2 allows use of reverse proxy with multiple addresses.
-    # @param [Symbol] one of OPERATIONS
-    # @param [Array] parameters for "as" command
+    # @param action_sym [Symbol] one of OPERATIONS
+    # @param arguments  [Array]  parameters for "as" command
     # @return [Boolean,Array,Hash] result of command, type depends on command
     def execute_single(action_sym, arguments, version: 1, host: nil)
       arguments = [] if arguments.nil?
@@ -129,10 +128,10 @@ module Aspera
       Log.log.trace1{"execute_single:#{stdin_input}"}
       # execute, get binary output
       byte_buffer = @command_executor.execute(remote_cmd, input: stdin_input).unpack('C*')
-      Aspera.assert(!byte_buffer.empty?){'empty answer from server'}
+      Aspera.assert(!byte_buffer.empty?, 'empty answer from server')
       # get hash or table result
       result = self.class.parse(byte_buffer, :result)
-      Aspera.assert(byte_buffer.empty?){'unparsed bytes remaining'}
+      Aspera.assert(byte_buffer.empty?, 'unparsed bytes remaining')
       # get and delete info,always present in results
       system_info = result[:info]
       result.delete(:info)
@@ -169,25 +168,28 @@ module Aspera
     end
 
     class << self
-      # Get description of structure's field, @param struct_name, @param typed_buffer provides field name
+      # Get description of structure's field
+      # @param struct_name   [Symbol] name of the structure type
+      # @param typed_buffer  [Hash]   typed buffer providing the field name via `:btype`
+      # @return [Hash] field description
       def field_description(struct_name, typed_buffer)
         result = TYPES_DESCR[struct_name][:fields][typed_buffer[:btype] - ENUM_START]
-        raise "Unrecognized field for #{struct_name}: #{typed_buffer[:btype]}\n#{typed_buffer[:buffer]}" if result.nil?
+        Aspera.assert(!result.nil?){"Unrecognized field for #{struct_name}: #{typed_buffer[:btype]}\n#{typed_buffer[:buffer]}"}
         return result
       end
 
       # Decodes the provided buffer as provided type name
-      # @return a decoded type: single, Array, or Hash
+      # @return [Boolean, Array, Hash] a decoded type: single, Array, or Hash
       def parse(buffer, type_name, indent_level = nil)
         indent_level = (indent_level || -1) + 1
         type_descr = TYPES_DESCR[type_name]
-        raise "Unexpected type #{type_name}" if type_descr.nil?
+        Aspera.assert(!type_descr.nil?){"Unexpected type #{type_name}"}
         Log.log.trace1{"#{'   .' * indent_level}parse:#{type_name}:#{type_descr[:decode]}:#{buffer[0, 16]}...".red}
         result = nil
         case type_descr[:decode]
         when :base
           num_bytes = type_name.eql?(:zstr) ? buffer.length : type_descr[:size]
-          Aspera.assert(buffer.length >= num_bytes){'not enough bytes'}
+          Aspera.assert(buffer.length >= num_bytes, 'not enough bytes')
           byte_array = buffer.shift(num_bytes)
           byte_array = [byte_array] unless byte_array.is_a?(Array)
           result = byte_array.pack('C*').unpack1(type_descr[:unpack])
@@ -200,7 +202,7 @@ module Aspera
           until buffer.empty?
             btype = parse(buffer, :int8, indent_level)
             length = parse(buffer, :int32, indent_level)
-            Aspera.assert(buffer.length >= length){'not enough bytes'}
+            Aspera.assert(buffer.length >= length, 'not enough bytes')
             value = buffer.shift(length)
             result.push({btype: btype, buffer: value})
             Log.log.trace1{"#{'   .' * indent_level}:buffer_list[#{result.length - 1}] #{result.last}"}

data/lib/aspera/ascp/installation.rb

@@ -27,6 +27,10 @@ module Aspera
     # It is used by object : AgentDirect to find necessary resources
     # By default it takes the first Aspera product found
     # The user can specify `ascp` location by calling: `sdk_folder=` method
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of Installation
+    #   @return [Installation] the singleton instance
     class Installation
       include Singleton
 
@@ -57,16 +61,16 @@ module Aspera
       # - "product:FIRST" to use ascp from first found product
       def sdk_folder=(ascp_location)
         Aspera.assert_type(ascp_location, String){'ascp_location'}
-        Aspera.assert(!ascp_location.empty?){'ascp location cannot be empty: check your config file'}
+        Aspera.assert(!ascp_location.empty?, 'ascp location cannot be empty: check your config file')
         folder =
           if ascp_location.start_with?(USE_PRODUCT_PREFIX)
             product_name = ascp_location.delete_prefix(USE_PRODUCT_PREFIX)
             if product_name.eql?(FIRST_FOUND)
               pl = installed_products.first
-              raise "No Aspera transfer module or SDK found.\nRefer to the manual or install SDK with command:\nascli conf transferd install" if pl.nil?
+              Aspera.assert(!pl.nil?){"No Aspera transfer module or SDK found.\nRefer to the manual or install SDK with command:\nascli conf transferd install"}
             else
               pl = installed_products.find{ |i| i[:name].eql?(product_name)}
-              raise "No such product installed: #{product_name}" if pl.nil?
+              Aspera.assert(!pl.nil?){"No such product installed: #{product_name}"}
             end
             File.dirname(pl[:ascp_path])
           else
@@ -84,14 +88,14 @@ module Aspera
       # @return [Hash] with key = file name (String), and value = path to file
       def file_paths
         return SDK_FILES.to_h do |v|
-                 [v.to_s, begin
-                   path(v)
-                 rescue Errno::ENOENT => e
-                   e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
-                 rescue => e
-                   e.message
-                 end]
-               end
+          [v.to_s, begin
+            path(v)
+          rescue Errno::ENOENT => e
+            e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
+          rescue => e
+            e.message
+          end]
+        end
       end
 
       # TODO: if using another product than SDK, should use files from there
@@ -102,18 +106,18 @@ module Aspera
 
       # Get path of one resource file of currently activated product
       # keys and certs are generated locally... (they are well known values, arch. independent)
-      # @param k [Symbol] key of the resource file
+      # @param file_type [Symbol] key of the resource file
       # @return [String, nil] Full path to the resource file or nil if not found
-      def path(k)
+      def path(file_type)
         file_is_required = true
-        case k
+        case file_type
         when *EXE_FILES
-          file_is_required = k.eql?(:ascp)
+          file_is_required = file_type.eql?(:ascp)
           file = Products::Transferd.transferd_path
-          file = File.join(File.dirname(file), Environment.instance.exe_file(k.to_s)) unless k.eql?(:transferd)
+          file = File.join(File.dirname(file), Environment.instance.exe_file(file_type.to_s)) unless file_type.eql?(:transferd)
         when :ssh_private_dsa, :ssh_private_rsa
           # assume last 3 letters are type
-          type = k.to_s[-3..].to_sym
+          type = file_type.to_s[-3..].to_sym
           file = check_or_create_sdk_file("aspera_bypass_#{type}.pem"){DataRepository.instance.item(type)}
         when :aspera_license
           file = check_or_create_sdk_file('aspera-license'){DataRepository.instance.item(:license)}
@@ -130,22 +134,23 @@ module Aspera
             check_or_create_sdk_file('aspera_fallback_cert_private_key.pem', force: true){private_key.to_pem}
             check_or_create_sdk_file('aspera_fallback_cert.pem', force: true){cert.to_pem}
           end
-          file = k.eql?(:fallback_certificate) ? file_cert : file_key
-        else Aspera.error_unexpected_value(k)
+          file = file_type.eql?(:fallback_certificate) ? file_cert : file_key
+        else Aspera.error_unexpected_value(file_type)
         end
         return unless file_is_required || File.exist?(file)
-        Aspera.assert(File.exist?(file), type: Errno::ENOENT){"#{k} not found (#{file})"}
+        Aspera.assert(File.exist?(file), type: Errno::ENOENT){"#{file_type} not found (#{file})"}
         return file
       end
 
       # default bypass key phrase
-      # @return [String]
+      # @return [String] UUID used as bypass key phrase for SSH certificate
       def ssh_cert_uuid
         return DataRepository.instance.item(:uuid)
       end
 
       # get paths of SSH keys to use for ascp client
-      # @param types [Symbol] types to use
+      # @param types [Symbol] types to use (one of CLIENT_SSH_KEY_OPTIONS)
+      # @return [Array<String>] list of private key file paths
       def aspera_token_ssh_key_paths(types)
         Aspera.assert_values(types, CLIENT_SSH_KEY_OPTIONS)
         return case types
@@ -166,13 +171,11 @@ module Aspera
         Aspera.assert_type(exe_path, String)
         Aspera.assert_type(vers_arg, String)
         return unless File.exist?(exe_path)
-        exe_version = nil
-        cmd_out = %x("#{exe_path}" #{vers_arg})
-        raise "An error occurred when testing #{exe_path}: #{cmd_out}" unless $CHILD_STATUS == 0
+        cmd_out, _err, status = Environment.secure_execute(exe_path, vers_arg, mode: :capture, exception: false)
+        raise "An error occurred when testing #{exe_path}: #{cmd_out}" unless status.success?
         # get version from ascp, only after full extract, as windows requires DLLs (SSL/TLS/etc...)
         m = cmd_out.match(/ version ([0-9.]+)/)
-        exe_version = m[1].gsub(/\.$/, '') unless m.nil?
-        return exe_version
+        m.nil? ? nil : m[1].gsub(/\.$/, '')
       end
 
       # Extract some stings from ascp logs
@@ -230,15 +233,15 @@ module Aspera
         return ascp_data
       end
 
-      # @return the url for download of SDK archive for the given platform and version
+      # @return [String] the url for download of SDK archive for the given platform and version
       def sdk_url_for_platform(platform: nil, version: nil)
         all_locations = sdk_locations
         platform = Environment.instance.architecture if platform.nil?
         locations = all_locations.select{ |l| l['platform'].eql?(platform)}
-        raise "No SDK for platform: #{platform}, available: #{all_locations.map{ |i| i['platform']}.uniq}" if locations.empty?
+        Aspera.assert(!locations.empty?){"No SDK for platform: #{platform}, available: #{all_locations.map{ |i| i['platform']}.uniq}"}
         version = locations.max_by{ |entry| Gem::Version.new(entry['version'])}['version'] if version.nil?
         info = locations.select{ |entry| entry['version'].eql?(version)}
-        raise "No such version: #{version} for #{platform}" if info.empty?
+        Aspera.assert(!info.empty?){"No such version: #{version} for #{platform}"}
         return info.first['url']
       end
 
@@ -247,7 +250,7 @@ module Aspera
       # @yieldparam entry_stream [IO, Gem::Package::TarReader::Entry] Data stream
       # @yieldparam link_target [String, nil] Link target if symlink, nil otherwise
       def extract_archive_files(sdk_archive_path)
-        Aspera.assert(block_given?){'missing block'}
+        Aspera.assert(block_given?, 'missing block')
         case sdk_archive_path
         # Windows and Mac use zip
         when /\.zip$/
@@ -278,15 +281,14 @@ module Aspera
         end
       end
 
-      # Retrieves ascp binary for current system architecture from URL or file
+      # Downloads and extracts the SDK archive for the current platform into +folder+
       # @param folder  [String]      Destination folder path
       # @param url     [nil, String] URL to SDK archive, if nil: default url for version
       # @param version [nil, String] Specific version, if nil: latest version
       # @param backup  [Boolean]     If destination folder exists, then rename
       # @yieldparam entry_name [String] File path from archive
       # @yieldreturn [String, nil] Destination sub folder (end with /) or file, or nil to not extract
-      # @return [Array] name, ascp version (from execution), folder
-      def install_sdk(folder:, url: nil, version: nil, backup: true)
+      def download_sdk(folder:, url: nil, version: nil, backup: true)
         url ||= sdk_url_for_platform(version: version)
         # Rename old install
         if backup && Dir.exist?(folder) && !Dir.empty?(folder)
@@ -368,12 +370,13 @@ module Aspera
         end
       end
 
-      # Retrieve SDK either from specified URL, or specified version from standard location, or latest version
-      # @param url [nil, String] URL
-      # @param version [nil, String] URL
-      def retrieve_sdk(url: nil, version: nil)
+      # Downloads, installs and configures the SDK, returns name, version and install folder
+      # @param url     [nil, String] URL to SDK archive, if nil: default url for version
+      # @param version [nil, String] Specific version, if nil: latest version
+      # @return [Array<String>] sdk name, sdk version, install folder
+      def install_sdk(url: nil, version: nil)
         folder = Products::Transferd.sdk_directory
-        install_sdk(folder: folder, url: url, version: version)
+        download_sdk(folder: folder, url: url, version: version)
         # Ensure necessary files are there, or generate them, restrict file access on SDK executables
         SDK_FILES.each do |file_id_sym|
           file_path = path(file_id_sym)
@@ -429,7 +432,7 @@ module Aspera
 
       public
 
-      # @return the list of installed products in format of product_locations_on_current_os
+      # @return [Array<Hash>] the list of installed products in format of product_locations_on_current_os
       def installed_products
         return @found_products unless @found_products.nil?
         # :expected  M app name is taken from the manifest if present, else defaults to this value

data/lib/aspera/ascp/management.rb

@@ -12,7 +12,7 @@ module Aspera
       # https://www.ibm.com/support/pages/error-code-reference-tables
       # mgmtmess.c : as_mgmt_err_is_retryable
       # Note that the fact that an error is retry-able is not internally defined by protocol, it's client-side responsibility
-      # rubocop:disable Layout/FirstHashElementLineBreak
+      # rubocop:disable-next Layout/FirstHashElementLineBreak
       ERRORS = {
         # id   retry-able    mnemo/code                        message                                              additional info
         0  => {r: false, c: 'UNKNOWN',                     m: 'unknown',                                        a: 'unknown'},
@@ -93,7 +93,6 @@ module Aspera
         66 => {r: false, c: 'PEER_REQUIRES_FIPS',          m: 'Peer rejects cipher due to FIPS mode enabled on peer',
                                                                 a: 'Peer rejects cipher due to FIPS mode enabled on peer'}
       }.freeze
-      # rubocop:enable Layout/FirstHashElementLineBreak
       # cspell: disable
       OPERATIONS = %w[
         NOP
@@ -307,7 +306,7 @@ module Aspera
         def field_snake_to_native(name)
           field = name.delete('_')
           result = PARAMETERS.find{ |w| w.casecmp?(field)}
-          raise "No such field: #{name}" if result.nil?
+          Aspera.assert(!result.nil?){"No such field: #{name}"}
           result
         end