aspera-cli 4.25.3 → 4.25.5

data/lib/aspera/api/aoc.rb

@@ -7,11 +7,15 @@ require 'aspera/hash_ext'
 require 'aspera/data_repository'
 require 'aspera/transfer/spec'
 require 'aspera/api/node'
+require 'aspera/rest_list'
 require 'base64'
 
 module Aspera
   module Api
+    # Aspera on Cloud API client
     class AoC < Rest
+      include RestList
+
       PRODUCT_NAME = 'Aspera on Cloud'
       # use default workspace if it is set, else none
       DEFAULT_WORKSPACE = ''
@@ -144,18 +148,17 @@ module Aspera
 
         # Call `block` with same query using paging and response information.
         # Block must return a 2 element `Array` with data and http response
-        # @param query    [Hash] Additionnal query parameters
-        # @param progress [nil, Object] Uses methods: `long_operation_running` and `long_operation_terminated`
+        # @param query    [Hash] Additional query parameters
         # @return [Hash] Items and total number of items
         # @option return [Array<Hash>] :items The list of items
         # @option return [Integer] :total The total number of items
-        def call_paging(query: {}, progress: nil)
+        def call_paging(query: {})
           Aspera.assert_type(query, Hash){'query'}
           Aspera.assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
           query['per_page'] = 1000 unless query.key?('per_page')
-          max_items = query.delete(Rest::MAX_ITEMS)
-          max_pages = query.delete(Rest::MAX_PAGES)
+          max_items = query.delete(RestList::MAX_ITEMS)
+          max_pages = query.delete(RestList::MAX_PAGES)
           item_list = []
           total_count = nil
           current_page = query['page']
@@ -177,9 +180,9 @@ module Aspera
             break if !max_items.nil? && item_list.count >= max_items
             break if !max_pages.nil? && page_count >= max_pages
             break if total_count&.<=(item_list.count)
-            progress&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
+            RestParameters.instance.spinner_cb.call("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
-          progress&.long_operation_terminated
+          RestParameters.instance.spinner_cb.call(action: :success)
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
           return {items: item_list, total: total_count}
         end
@@ -210,7 +213,7 @@ module Aspera
           when 'upload' then %w[mkdir write]
           when Array
             Aspera.assert_array_all(levels, String){'access_levels'}
-            levels.each{ |level| Aspera.assert_value(level, Node::ACCESS_LEVELS){'access_level'}}
+            levels.each{ |level| Aspera.assert_values(level, Node::ACCESS_LEVELS){'access_level'}}
             levels
           else Aspera.error_unexpected_value(levels){"access_levels must be a list of #{Node::ACCESS_LEVELS.join(', ')} or one of edit, preview, download, upload"}
           end
@@ -232,8 +235,7 @@ module Aspera
         username: nil,
         password: nil,
         workspace: nil,
-        secret_finder: nil,
-        progress_disp: nil
+        secret_finder: nil
       )
         # Test here because link may set url
         Aspera.assert(url, 'Missing mandatory option: url', type: ParameterError)
@@ -244,7 +246,6 @@ module Aspera
         # key: access key
         # value: associated secret
         @secret_finder = secret_finder
-        @progress_disp = progress_disp
         @workspace_name = workspace
         @cache_user_info = nil
         @cache_url_token_info = nil
@@ -309,7 +310,7 @@ module Aspera
       # @param query [nil, Hash] Additional query
       # @return [Hash] {items: , total: }
       def read_with_paging(subpath, query = nil)
-        return self.class.call_paging(query: query, progress: @progress_disp) do |paged_query|
+        return self.class.call_paging(query: query) do |paged_query|
           read(subpath, query: paged_query, ret: :both)
         end
       end
@@ -495,7 +496,7 @@ module Aspera
       # in that case, the name is resolved and replaced with {type: , id: }
       # @param package_data    [Hash]   The whole package creation payload
       # @param rcpt_lst_field  [String] The field in structure, i.e. recipients or bcc_recipients
-      # @param new_user_option [Hash]   Additionnal fields for contact creation
+      # @param new_user_option [Hash]   Additional fields for contact creation
       # @return nil, `package_data` is modified
       def resolve_package_recipients(package_data, rcpt_lst_field, new_user_option)
         return unless package_data.key?(rcpt_lst_field)
@@ -513,7 +514,7 @@ module Aspera
             # email: user, else dropbox
             entity_type = short_recipient_info.include?('@') ? 'contacts' : 'dropboxes'
             begin
-              full_recipient_info = lookup_by_name(entity_type, short_recipient_info, query: {'current_workspace_id' => ws_id})
+              full_recipient_info = lookup_by_name(entity_type, short_recipient_info, query: {'workspace_id' => ws_id})
             rescue EntityNotFound
               # dropboxes cannot be created on the fly
               Aspera.assert_values(entity_type, 'contacts', type: Error){"No such shared inbox in workspace #{ws_id}"}

data/lib/aspera/api/ats.rb

@@ -5,7 +5,7 @@ require 'aspera/rest'
 
 module Aspera
   module Api
-    # ATS API without authentication
+    # Aspera Transfer Service API client without authentication
     class Ats < Aspera::Rest
       SERVICE_BASE_URL = 'https://ats.aspera.io'
       # currently supported clouds

data/lib/aspera/api/cos_node.rb

@@ -7,9 +7,11 @@ require 'xmlsimple'
 
 module Aspera
   module Api
+    # Cloud Object Storage Node API Client
     class CosNode < Node
       IBM_CLOUD_TOKEN_URL = 'https://iam.cloud.ibm.com/identity'
       TOKEN_FIELD = 'delegated_refresh_token'
+      FASP_INFO_KEYS = %w[ATSEndpoint AccessKey].freeze
       class << self
         def parameters_from_svc_credentials(service_credentials, bucket_region)
           # check necessary contents
@@ -60,6 +62,9 @@ module Aspera
         ).body
         ats_info = XmlSimple.xml_in(xml_result_text, {'ForceArray' => false})
         Log.dump(:ats_info, ats_info)
+        Aspera.assert_hash_all(ats_info, String, nil){'ats_info'}
+        Aspera.assert((FASP_INFO_KEYS - ats_info.keys).empty?){'ats_info missing required keys'}
+        Aspera.assert_hash_all(ats_info['AccessKey'], String, String){'ats_info'}
         @storage_credentials = {
           'type'  => 'token',
           'token' => {TOKEN_FIELD => nil}

data/lib/aspera/api/faspex.rb

@@ -2,10 +2,11 @@
 
 require 'aspera/rest'
 require 'aspera/oauth/base'
+require 'aspera/rest_list'
 require 'digest'
 
 module Aspera
-  # Implement OAuth for Faspex public link
+  # OAuth for Faspex public link
   class FaspexPubLink < OAuth::Base
     class << self
       attr_accessor :additional_info
@@ -55,14 +56,14 @@ module Aspera
   end
   OAuth::Factory.instance.register_token_creator(FaspexPubLink)
   module Api
+    # Aspera Faspex 5 API Client
     class Faspex < Aspera::Rest
+      include RestList
+
       # endpoint for authentication API
       PATH_AUTH = 'auth'
       PATH_API_V5 = 'api/v5'
       PATH_HEALTH = 'configuration/ping'
-      private_constant :PATH_AUTH,
-        :PATH_API_V5,
-        :PATH_HEALTH
       RECIPIENT_TYPES = %w[user workgroup external_user distribution_list shared_inbox].freeze
       PACKAGE_TERMINATED = %w[completed failed].freeze
       # list of supported mailbox types (to list packages)
@@ -91,7 +92,7 @@ module Aspera
       JOB_RUNNING = %w[queued working].freeze
       PATH_STANDARD_ROOT = '/aspera/faspex'
       PATH_API_DETECT = "#{PATH_API_V5}/#{PATH_HEALTH}"
-      HEADER_ITERATION_TOKEN = 'X-Aspera-Next-Iteration-Token'
+      HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
       HEADER_FASPEX_VERSION = 'X-IBM-Aspera'
       EMAIL_NOTIF_LIST = %w[
         welcome_email
@@ -136,9 +137,19 @@ module Aspera
       end
       attr_reader :pub_link_context
 
+      # @param url             Faspex URL, can be a public link
+      # @param auth            Authentication method: :boot (token in header), :web (open browser), :jwt (client_id + private key), :public_link (context in URL)
+      # @param password        For :boot auth, the token copied directly from browser in developer mode
+      # @param client_id       For :web and :jwt auth, the client_id of web UI application
+      # @param client_secret   For :web auth, the client_secret of web UI application (not needed for :jwt)
+      # @param redirect_uri    For :web auth, the redirect_uri of web UI application (must be the same as in application configuration)
+      # @param username        For :jwt auth, the username of the user to impersonate
+      # @param private_key     For :jwt auth, the private key to sign JWT token
+      # @param passphrase      For :jwt auth, the passphrase of the private key
       def initialize(
         url:,
         auth:,
+        root: PATH_API_V5,
         password: nil,
         client_id: nil,
         client_secret: nil,
@@ -152,23 +163,23 @@ module Aspera
         super(**
           case auth
           when :public_link
-            # Get URL of final redirect of public link
-            redir_url = Rest.new(base_url: url, redirect_max: 3).call(operation: 'GET', ret: :resp).uri.to_s
-            Log.dump(:redir_url, redir_url, level: :trace1)
-            # get context from query
-            encoded_context = Rest.query_to_h(URI.parse(redir_url).query)['context']
+            # Get URL of final redirect of provided public link
+            final_url = Rest.new(base_url: url, redirect_max: 3).call(operation: 'GET', ret: :resp).uri.to_s
+            Log.dump(:final_url, final_url, level: :trace1)
+            # Get context from query
+            encoded_context = Rest.query_to_h(URI.parse(final_url).query)['context']
             raise ParameterError, 'Bad faspex5 public link, missing context in query' if encoded_context.nil?
             # public link information (contains passcode and allowed usage)
             @pub_link_context = JSON.parse(Base64.decode64(encoded_context))
             Log.dump(:pub_link_context, @pub_link_context, level: :trace1)
             # Get the base url, i.e. .../aspera/faspex
-            base_url = redir_url.gsub(%r{/public/.*}, '').gsub(/\?.*/, '')
+            base_url = final_url.gsub(%r{/public/.*}, '').gsub(/\?.*/, '')
             # Get web UI client_id and redirect_uri
             # TODO: change this for something more reliable
             config = JSON.parse(Rest.new(base_url: "#{base_url}/config.js", redirect_max: 3).call(operation: 'GET').sub(/^[^=]+=/, '').gsub(/([a-z_]+):/, '"\1":').delete("\n ").tr("'", '"')).symbolize_keys
-            Log.dump(:configjs, config)
+            Log.dump(:config_js, config)
             {
-              base_url: "#{base_url}/#{PATH_API_V5}",
+              base_url: "#{base_url}/#{root}",
               auth:     {
                 type:         :oauth2,
                 base_url:     "#{base_url}/#{PATH_AUTH}",
@@ -185,7 +196,7 @@ module Aspera
             Aspera.assert(password, type: ParameterError){'Missing password'}
             # the password here is the token copied directly from browser in developer mode
             {
-              base_url: "#{url}/#{PATH_API_V5}",
+              base_url: "#{url}/#{root}",
               headers:  {'Authorization' => password}
             }
           when :web
@@ -193,7 +204,7 @@ module Aspera
             Aspera.assert(redirect_uri, type: ParameterError){'Missing redirect_uri'}
             # opens a browser and ask user to auth using web
             {
-              base_url: "#{url}/#{PATH_API_V5}",
+              base_url: "#{url}/#{root}",
               auth:     {
                 type:         :oauth2,
                 base_url:     "#{url}/#{PATH_AUTH}",
@@ -208,7 +219,7 @@ module Aspera
             Aspera.assert(client_id, type: ParameterError){'Missing client_id'}
             Aspera.assert(private_key, type: ParameterError){'Missing private_key'}
             {
-              base_url: "#{url}/#{PATH_API_V5}",
+              base_url: "#{url}/#{root}",
               auth:     {
                 type:            :oauth2,
                 base_url:        "#{url}/#{PATH_AUTH}",
@@ -229,10 +240,6 @@ module Aspera
           end
         )
       end
-
-      def auth_api
-        Rest.new(**params, base_url: base_url.sub(PATH_API_V5, PATH_AUTH))
-      end
     end
   end
 end

data/lib/aspera/api/httpgw.rb

@@ -4,13 +4,18 @@ require 'aspera/log'
 require 'aspera/rest'
 require 'aspera/transfer/faux_file'
 require 'aspera/assert'
+require 'net/protocol'
 require 'securerandom'
 require 'websocket'
 require 'base64'
 require 'json'
 
+# throw exception on error, instead of error code
+WebSocket.should_raise = true
+
 module Aspera
   module Api
+    # Aspera HTTP Gateway API client
     # Start a transfer using Aspera HTTP Gateway, using web socket secure for uploads
     # ref: https://api.ibm.com/explorer/catalog/aspera/product/ibm-aspera/api/http-gateway-api/doc/guides-toc
     # https://developer.ibm.com/apis/catalog?search=%22aspera%20http%22
@@ -75,6 +80,15 @@ module Aspera
         Log.log.trace2{"#{LOG_WS_SEND}counts: #{@shared_info[:count]}"}
       end
 
+      # Check header ourself and give precise error message, as websocket will only throw error without details
+      # @param [String] Response Header
+      # @return [String] Response Header
+      def validated_ws_response_header(header)
+        first_line = header.split("\r\n").first
+        raise RestCallError.new({messages: ["Unexpected: #{first_line}", 'Expected: 101 Switching Protocols']}) unless first_line.split(/\s+/, 3)[1].eql?('101')
+        header
+      end
+
       # message processing for read thread
       def process_received_message(message)
         Log.log.debug{"#{LOG_WS_RECV}message: [#{message}] (#{message.class})"}
@@ -153,8 +167,9 @@ module Aspera
         @ws_handshake = ::WebSocket::Handshake::Client.new(url: upload_url, headers: {})
         @ws_io.write(@ws_handshake.to_s)
         sleep(0.1)
-        @ws_handshake << @ws_io.readuntil("\r\n\r\n")
-        Aspera.assert(@ws_handshake.finished?){'Error in websocket handshake'}
+        # Get whole HTTP response header, Check and process
+        # no need to check `finished?` or result of `<<` (true), as we give the whole header at once
+        @ws_handshake << validated_ws_response_header(@ws_io.readuntil("\r\n\r\n"))
         Log.log.debug{"#{LOG_WS_SEND}handshake success"}
         # data shared between main thread and read thread
         @shared_info = {
@@ -232,14 +247,15 @@ module Aspera
         # throttling may have skipped last one
         @notify_cb&.call(:transfer, session_id: session_id, info: session_sent_bytes)
         @notify_cb&.call(:session_end, session_id: session_id)
-        @notify_cb&.call(:end)
         ws_send(ws_type: :close, data: nil)
         Log.log.debug("Finished upload, waiting for end of #{THR_RECV} thread.")
         @ws_read_thread.join
         Log.log.debug{'Read thread joined'}
+      ensure
         # session no more used
         @ws_io = nil
         http_session&.finish
+        @notify_cb&.call(:end)
       end
 
       def download(transfer_spec)

data/lib/aspera/api/node.rb

@@ -6,16 +6,17 @@ require 'aspera/oauth'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/environment'
-require 'zlib'
 require 'base64'
 require 'openssl'
 require 'pathname'
+require 'zlib'
 require 'net/ssh/buffer'
 
 module Aspera
   module Api
-    # Provides additional functions using node API with gen4 extensions (access keys)
-    class Node < Aspera::Rest
+    # Aspera Node API client
+    # with gen4 extensions (access keys)
+    class Node < Rest
       # Format of node scope : node.<access key>:<scope>
       module Scope
         # Node sub-scopes
@@ -42,9 +43,10 @@ module Aspera
       ACCESS_LEVELS = %w[delete list mkdir preview read rename write].freeze
       # Special HTTP Headers
       HEADER_X_ASPERA_ACCESS_KEY = 'X-Aspera-AccessKey'
-      HEADER_X_TOTAL_COUNT = 'X-Total-Count'
       HEADER_X_CACHE_CONTROL = 'X-Aspera-Cache-Control'
+      HEADER_X_TOTAL_COUNT = 'X-Total-Count'
       HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
+      HEADER_ACCEPT_VERSION = 'Accept-Version'
       # / in cloud
       PATH_SEPARATOR = '/'
 
@@ -52,22 +54,36 @@ module Aspera
       OAuth::Factory.instance.register_decoder(lambda{ |token| Node.decode_bearer_token(token)})
 
       # Class instance variable, access with accessors on class
-      @use_standard_ports = true
-      @use_node_cache = true
-
-      class << self
+      @api_options = {
         # Set to false to read transfer parameters from download_setup
-        attr_accessor :use_standard_ports
+        standard_ports: true,
         # Set to false to bypass cache in redis
-        attr_accessor :use_node_cache
+        cache:          true,
+        accept_v4:      true
+      }
+      OPTIONS = @api_options.keys.freeze
+
+      class << self
+        attr_reader :api_options
         attr_reader :use_dynamic_key
 
-        # Adds cache control header, as globally specified to read request
-        # Use like this: read(...,**cache_control)
-        def cache_control
-          headers = {'Accept' => Mime::JSON}
-          headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless use_node_cache
-          {headers: headers}
+        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
+          end
+        end
+
+        # Adds cache control header for node API /files/:id
+        # as globally specified to read request
+        # Use like this: read(..., headers: add_cache_control)
+        # @param headers [Hash] optional initial headers to add to
+        # @return [Hash] headers with cache control header added if needed
+        def add_cache_control(headers = {})
+          headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless api_options[:cache]
+          headers
         end
 
         # Set private key to be used
@@ -180,8 +196,8 @@ module Aspera
             Aspera.assert(!access_key.nil?)
           end
           return {
-            Node::HEADER_X_ASPERA_ACCESS_KEY => access_key,
-            'Authorization'                  => bearer_auth
+            HEADER_X_ASPERA_ACCESS_KEY => access_key,
+            'Authorization'            => bearer_auth
           }
         end
       end
@@ -248,6 +264,50 @@ module Aspera
         return false
       end
 
+      # Read folder content, with pagination management for gen4, not recursive
+      # if `Accept-Version: 4.0` is not specified:
+      #     if `page` and `per_page` are not specified, then all entries are returned.
+      #     if either `page` or `per_page` is specified, then both are required, else 400
+      # if `Accept-Version: 4.0` is specified:
+      #     those queries are not available: page (not mentioned), sort, min_size, max_size, min_modified_time, max_modified_time, target_id, target_node_id, files_prefetch_count, page, name_iglob : either ignored or result in API error 400.
+      #     query include is accepted, but seems to do nothing as access_levels and recursive_counts are already included in results.
+      #     query `iteration_token` is accepted and allows to get paginated results, with `X-Aspera-Next-Iteration-Token` header in response to get next page token. `X-Aspera-Total-Count` header gives total count of entries.
+      def read_folder_content(file_id, query = nil, exception: true, path: nil)
+        folder_items = []
+        begin
+          query ||= {}
+          headers = self.class.add_cache_control
+          use_v4 = self.class.api_options[:accept_v4]
+          return read("files/#{file_id}/files", query, headers: headers) unless use_v4 || query.key?('page') || query.key?('per_page')
+          if use_v4
+            headers[HEADER_ACCEPT_VERSION] = '4.0'
+            query['per_page'] = 1000 unless query.key?('per_page')
+          elsif query.key?('per_page') && !query.key?('page')
+            query['page'] = 0
+          end
+          loop do
+            RestParameters.instance.spinner_cb.call(folder_items.count)
+            data, http = read("files/#{file_id}/files", query, headers: headers, ret: :both)
+            folder_items.concat(data)
+            if use_v4
+              iteration_token = http[HEADER_X_NEXT_ITER_TOKEN]
+              break if iteration_token.nil? || iteration_token.empty?
+              query['iteration_token'] = iteration_token
+            else
+              break if data['item_count'].eql?(0)
+              query['offset'] += data['item_count']
+            end
+          end
+        rescue StandardError => e
+          raise e if exception
+          Log.log.warn{"#{path}: #{e.class} #{e.message}"}
+          Log.log.debug{(['Backtrace:'] + e.backtrace).join("\n")}
+        ensure
+          RestParameters.instance.spinner_cb.call(folder_items.count, action: :success)
+        end
+        folder_items
+      end
+
       # Recursively browse in a folder (with non-recursive method)
       # Entries of folders are processed if the processing method returns true
       # Links are processed on the respective node
@@ -267,14 +327,7 @@ module Aspera
           current_item = folders_to_explore.shift
           Log.log.debug{"Exploring #{current_item[:path]}".bg_green}
           # Get folder content
-          folder_contents =
-            begin
-              # TODO: use header
-              read("files/#{current_item[:id]}/files", query, **self.class.cache_control)
-            rescue StandardError => e
-              Log.log.warn{"#{current_item[:path]}: #{e.class} #{e.message}"}
-              []
-            end
+          folder_contents = read_folder_content(current_item[:id], query, exception: false, path: current_item[:path])
           Log.dump(:folder_contents, folder_contents)
           folder_contents.each do |entry|
             if entry.key?('error')
@@ -309,7 +362,7 @@ module Aspera
       # @param path [String] file or folder path (end with "/" is like setting process_last_link)
       # @param process_last_link [Boolean] if true, follow the last link
       # @return [Hash] Result data
-      # @option return [Aspera::Rest] :api     REST client instance
+      # @option return [Rest] :api     REST client instance
       # @option return [String]       :file_id File identifier
       def resolve_api_fid(top_file_id, path, process_last_link = false)
         Aspera.assert_type(top_file_id, String)
@@ -445,7 +498,7 @@ module Aspera
         # Add application specific tags (AoC)
         @app_info[:api].add_ts_tags(transfer_spec: transfer_spec, app_info: @app_info) unless @app_info.nil?
         # Add remote host info
-        if self.class.use_standard_ports
+        if self.class.api_options[:standard_ports]
           # Get default TCP/UDP ports and transfer user
           transfer_spec.merge!(Transfer::Spec::AK_TSPEC_BASE)
           # By default: same address as node API
@@ -456,7 +509,7 @@ module Aspera
           # Get the transfer user from info on access key
           transfer_spec['remote_user'] = info['transfer_user'] if info['transfer_user']
           # Get settings from name.value array to hash key.value
-          settings = info['settings']&.each_with_object({}){ |i, h| h[i['name']] = i['value']}
+          settings = info['settings']&.to_h{ |i| [i['name'], i['value']]}
           # Check WSS ports
           Transfer::Spec::WSS_FIELDS.each do |i|
             transfer_spec[i] = settings[i] if settings.key?(i)
@@ -468,6 +521,46 @@ module Aspera
         return transfer_spec
       end
 
+      # Executes `GET` call in loop using `iteration_token` (`/ops/transfers`)
+      # @param iteration [Array]   a single element array with the iteration token or nil
+      # @param call_args [Hash]    additional arguments to pass to `Rest.call`
+      # @return [Array] list of items returned by the API call
+      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))
+        query = {} if query.nil?
+        query[:iteration_token] = iteration[0] unless iteration.nil?
+        max = query.delete(RestList::MAX_ITEMS)
+        item_list = []
+        loop do
+          data, http = read(subpath, query, **call_args, ret: :both)
+          Aspera.assert_type(data, Array){"Expected data to be an Array, got: #{data.class}"}
+          # no data
+          break if data.empty?
+          # get next iteration token from link
+          next_iteration_token = nil
+          link_info = http['Link']
+          unless link_info.nil?
+            m = link_info.match(/<([^>]+)>/)
+            Aspera.assert(m){"Cannot parse iteration in Link: #{link_info}"}
+            next_iteration_token = Rest.query_to_h(URI.parse(m[1]).query)['iteration_token']
+          end
+          # same as last iteration: stop
+          break if next_iteration_token&.eql?(query[:iteration_token])
+          query[:iteration_token] = next_iteration_token
+          item_list.concat(data)
+          if max&.<=(item_list.length)
+            item_list = item_list.slice(0, max)
+            break
+          end
+          break if next_iteration_token.nil?
+        end
+        # save iteration token if needed
+        iteration[0] = query[:iteration_token] unless iteration.nil?
+        item_list
+      end
+
       private
 
       # Method called in loop for each entry for `resolve_api_fid`

data/lib/aspera/ascp/installation.rb

@@ -83,16 +83,15 @@ module Aspera
 
       # @return [Hash] with key = file name (String), and value = path to file
       def file_paths
-        return SDK_FILES.each_with_object({}) do |v, m|
-          m[v.to_s] =
-            begin
-              path(v)
-            rescue Errno::ENOENT => e
-              e.message.gsub(/.*assertion failed: /, '').gsub(/\): .*/, ')')
-            rescue => e
-              e.message
-            end
-        end
+        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
       end
 
       # TODO: if using another product than SDK, should use files from there

data/lib/aspera/cli/error.rb

@@ -9,7 +9,15 @@ module Aspera
     class MissingArgument < Error; end
     class NoSuchElement < Error; end
 
+    # Raised when a lookup for a specific entity fails to return exactly one result.
+    #
+    # Provides a formatted message indicating whether the entity was missing
+    # or if multiple matches were found (ambiguity).
     class BadIdentifier < Error
+      # @param res_type [String] The type of entity being looked up (e.g., 'user').
+      # @param res_id   [String] The value of the identifier that failed.
+      # @param field    [String] The name of the field used for lookup (defaults to 'identifier').
+      # @param count    [Integer] The number of matches found (0 for not found, >1 for ambiguous).
       def initialize(res_type, res_id, field: 'identifier', count: 0)
         msg = count.eql?(0) ? 'not found' : "found #{count}"
         super("#{res_type} with #{field}=#{res_id}: #{msg}")