aspera-cli 4.16.0 → 4.17.0

data/lib/aspera/persistency_folder.rb

@@ -35,7 +35,7 @@ module Aspera
     end
 
     def put(object_id, value)
-      assert_type(value, String)
+      Aspera.assert_type(value, String)
       persist_filepath = id_to_filepath(object_id)
       Log.log.debug{"persistency saving: #{persist_filepath}"}
       FileUtils.rm_f(persist_filepath)
@@ -68,7 +68,7 @@ module Aspera
 
     # @param object_id String or Array
     def id_to_filepath(object_id)
-      assert_type(object_id, String)
+      Aspera.assert_type(object_id, String)
       FileUtils.mkdir_p(@folder)
       Environment.restrict_file_access(@folder)
       return File.join(@folder, "#{object_id}#{FILE_SUFFIX}")

data/lib/aspera/preview/generator.rb

@@ -54,7 +54,7 @@ module Aspera
         end
         @processing_method = @processing_method.to_sym
         Log.log.debug{"method: #{@processing_method}"}
-        assert(respond_to?(@processing_method, true)){"no processing know for #{conversion_type} -> #{@preview_format_sym}"}
+        Aspera.assert(respond_to?(@processing_method, true)){"no processing know for #{conversion_type} -> #{@preview_format_sym}"}
       end
 
       # create preview as specified in constructor
@@ -88,7 +88,7 @@ module Aspera
       # @param total_count of parts
       # @param index of part (start at 1)
       def get_offset(duration, start_offset, total_count, index)
-        assert_type(duration, Float){'duration'}
+        Aspera.assert_type(duration, Float){'duration'}
         return start_offset + ((index - 1) * (duration - start_offset) / total_count)
       end
 
@@ -151,10 +151,10 @@ module Aspera
       # do a simple re-encoding
       def convert_video_to_mp4_using_reencode
         options = @options.reencode_ffmpeg
-        assert_type(options, Hash){'reencode_ffmpeg'}
+        Aspera.assert_type(options, Hash){'reencode_ffmpeg'}
         options.each do |k, v|
-          assert_values(k, FFMPEG_OPTIONS_LIST){'key'}
-          assert_type(v, Array){k}
+          Aspera.assert_values(k, FFMPEG_OPTIONS_LIST){'key'}
+          Aspera.assert_type(v, Array){k}
         end
         Utils.ffmpeg(
           in_f: @source_file_path,

data/lib/aspera/preview/terminal.rb

@@ -4,6 +4,7 @@
 
 require 'rainbow'
 require 'io/console'
+require 'aspera/log'
 module Aspera
   module Preview
     # Display a picture in the terminal, either using coloured characters or iTerm2
@@ -40,9 +41,9 @@ module Aspera
           (term_rows, term_columns) = IO.console.winsize
           term_rows -= reserve
           # compute scaling to fit terminal
-          fit_term_ratio = [term_rows / image.rows.to_f, term_columns / image.columns.to_f].min
+          fit_term_ratio = [term_rows.to_f * font_ratio / image.rows.to_f, term_columns.to_f / image.columns.to_f].min
           height_ratio = double ? 2.0 : 1.0
-          image = image.scale((image.columns * fit_term_ratio * font_ratio).to_i, (image.rows * fit_term_ratio * height_ratio).to_i)
+          image = image.scale((image.columns * fit_term_ratio).to_i, (image.rows * fit_term_ratio * height_ratio / font_ratio).to_i)
           # quantum depth is 8 or 16, see: `convert xc: -format "%q" info:`
           shift_for_8_bit = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
           # get all pixel colors, adjusted for Rainbow

data/lib/aspera/preview/utils.rb

@@ -44,7 +44,7 @@ module Aspera
         # one could use "system", but we would need to redirect stdout/err
         # @return true if su
         def external_command(command_sym, command_args, check_code: true)
-          assert_values(command_sym, EXTERNAL_TOOLS){'command'}
+          Aspera.assert_values(command_sym, EXTERNAL_TOOLS){'command'}
           # build command line, and quote special characters
           command_line = command_args.clone.unshift(command_sym).map{|i| shell_quote(i.to_s)}.join(' ')
           Log.log.debug{"cmd=#{command_line}".blue}
@@ -59,7 +59,7 @@ module Aspera
         end
 
         def ffmpeg(a)
-          assert_type(a, Hash)
+          Aspera.assert_type(a, Hash)
           # input_file,input_args,output_file,output_args
           a[:gl_p] ||= [
             '-y', # overwrite output without asking
@@ -67,7 +67,7 @@ module Aspera
           ]
           a[:in_p] ||= []
           a[:out_p] ||= []
-          assert(%i[gl_p in_f in_p out_f out_p].eql?(a.keys.sort)){"wrong params (#{a.keys.sort})"}
+          Aspera.assert(%i[gl_p in_f in_p out_f out_p].eql?(a.keys.sort)){"wrong params (#{a.keys.sort})"}
           external_command(:ffmpeg, [a[:gl_p], a[:in_p], '-i', a[:in_f], a[:out_p], a[:out_f]].flatten)
         end
 

data/lib/aspera/proxy_auto_config.rb

@@ -11,7 +11,7 @@ module URI
     alias_method :find_proxy_orig, :find_proxy
     class << self
       def register_proxy_finder
-        assert(block_given?)
+        Aspera.assert(block_given?)
         # overload the method in URI : call user's provided block and fallback to original method
         define_method(:find_proxy) {|env_vars=ENV| yield(to_s) || find_proxy_orig(env_vars)}
       end
@@ -109,12 +109,12 @@ END_OF_JAVASCRIPT
         parts = item.strip.split
         case parts.shift
         when 'DIRECT'
-          assert(parts.empty?){'DIRECT has no param'}
+          Aspera.assert(parts.empty?){'DIRECT has no param'}
           Log.log.debug('ignoring proxy DIRECT')
         when 'PROXY'
           addr_port = parts.shift
-          assert_type(addr_port, String)
-          assert(parts.empty?){'PROXY shall have one param'}
+          Aspera.assert_type(addr_port, String)
+          Aspera.assert(parts.empty?){'PROXY shall have one param'}
           begin
             # PAC proxy addresses are <host>:<port>
             if /:[0-9]+$/.match?(addr_port)

data/lib/aspera/rest.rb

@@ -56,19 +56,19 @@ module Aspera
         return values.first.eql?(ARRAY_PARAMS)
       end
 
-      # build URI from URL and parameters and check it is http or https
-      def build_uri(url, params=nil)
+      # build URI from URL and parameters and check it is http or https, encode array [] parameters
+      def build_uri(url, query_hash=nil)
         uri = URI.parse(url)
-        assert(%w[http https].include?(uri.scheme)){"REST endpoint shall be http/s not #{uri.scheme}"}
-        return uri if params.nil?
-        Log.log.debug{Log.dump('params', params)}
-        assert_type(params, Hash)
-        return uri if params.empty?
+        Aspera.assert(%w[http https].include?(uri.scheme)){"REST endpoint shall be http/s not #{uri.scheme}"}
+        return uri if query_hash.nil?
+        Log.log.debug{Log.dump('query', query_hash)}
+        Aspera.assert_type(query_hash, Hash)
+        return uri if query_hash.empty?
         query = []
-        params.each do |k, v|
+        query_hash.each do |k, v|
           case v
           when Array
-            # support array url params, there is no standard. Either p[]=1&p[]=2, or p=1&p=2
+            # support array for query parameter, there is no standard. Either p[]=1&p[]=2, or p=1&p=2
             suffix = array_params?(v) ? v.shift : ''
             v.each do |e|
               query.push(["#{k}#{suffix}", e])
@@ -86,7 +86,7 @@ module Aspera
         URI.decode_www_form(query).each_with_object({}){|v, h|h[v.first] = v.last }
       end
 
-      # start a HTTP/S session, also used for web sockets
+      # Start a HTTP/S session, also used for web sockets
       # @param base_url [String] base url of HTTP/S session
       # @return [Net::HTTP] a started HTTP session
       def start_http_session(base_url)
@@ -105,31 +105,34 @@ module Aspera
       # little hack, handy because HTTP debug, proxy, etc... will be available
       # used implement web sockets after `start_http_session`
       def io_http_session(http_session)
-        assert_type(http_session, Net::HTTP)
+        Aspera.assert_type(http_session, Net::HTTP)
         # Net::BufferedIO in net/protocol.rb
         result = http_session.instance_variable_get(:@socket)
-        assert(!result.nil?){"no socket for #{http_session}"}
+        Aspera.assert(!result.nil?){"no socket for #{http_session}"}
         return result
       end
 
       # @return [String] PEM certificates of remote server
-      def remote_certificates(url)
+      def remote_certificate_chain(url, as_string: true)
+        result = []
         # initiate a session to retrieve remote certificate
         http_session = Rest.start_http_session(url)
         begin
           # retrieve underlying openssl socket
-          return Rest.io_http_session(http_session).io.peer_cert_chain.reverse.map(&:to_pem).join("\n")
+          result = Rest.io_http_session(http_session).io.peer_cert_chain
         rescue
-          return http_session.peer_cert.to_pem
+          result = http_session.peer_cert
         ensure
           http_session.finish
         end
+        result = result.map(&:to_pem).join("\n") if as_string
+        return result
       end
 
       # set global parameters
       def set_parameters(**options)
         options.each do |key, value|
-          assert(@@global.key?(key)){"unknown Rest option #{key}"}
+          Aspera.assert(@@global.key?(key)){"Unknown Rest option #{key}"}
           @@global[key] = value
         end
       end
@@ -145,135 +148,169 @@ module Aspera
     # create and start keep alive connection on demand
     def http_session
       if @http_session.nil?
-        @http_session = self.class.start_http_session(@params[:base_url])
+        @http_session = self.class.start_http_session(@base_url)
       end
       return @http_session
     end
 
-    public
-
-    attr_reader :params
-
-    def oauth
-      if @oauth.nil?
-        assert(@params[:auth][:type].eql?(:oauth2)){'no OAuth defined'}
-        @oauth = Oauth.new(@params[:auth])
-      end
-      return @oauth
-    end
-
-    # @param a_rest_params [Hash] default call parameters (merged at call)
-    def initialize(a_rest_params)
-      assert_type(a_rest_params, Hash)
-      assert_type(a_rest_params[:base_url], String)
-      @params = a_rest_params.clone
-      Log.log.debug{Log.dump('REST params', @params)}
-      # base url without trailing slashes (note: string may be frozen)
-      @params[:base_url] = @params[:base_url].gsub(%r{/+$}, '')
-      @http_session = nil
-      # default is no auth
-      @params[:auth] ||= {type: :none}
-      @params[:not_auth_codes] ||= ['401']
-      @oauth = nil
-      Log.log.debug{Log.dump('REST params(2)', @params)}
-    end
-
-    def oauth_token(force_refresh: false)
-      assert_values(force_refresh, [true, false])
-      return oauth.get_authorization(use_refresh_token: force_refresh)
-    end
-
-    def build_request(call_data)
+    def build_request(
+      operation:,
+      subpath:,
+      url_params:,
+      json_params:,
+      www_body_params:,
+      text_body_params:,
+      headers:
+    )
       # TODO: shall we percent encode subpath (spaces) test with access key delete with space in id
       # URI.escape()
-      uri = self.class.build_uri("#{call_data[:base_url]}#{['', '/'].include?(call_data[:subpath]) ? '' : '/'}#{call_data[:subpath]}", call_data[:url_params])
+      separator = !['', '/'].include?(subpath) || @base_url.end_with?('/') ? '/' : ''
+      uri = self.class.build_uri("#{@base_url}#{separator}#{subpath}", url_params)
       Log.log.debug{"URI=#{uri}"}
       begin
         # instantiate request object based on string name
-        req = Net::HTTP.const_get(call_data[:operation].capitalize).new(uri)
+        req = Net::HTTP.const_get(operation.capitalize).new(uri)
       rescue NameError
-        raise "unsupported operation : #{call_data[:operation]}"
+        raise "unsupported operation : #{operation}"
       end
-      if call_data.key?(:json_params) && !call_data[:json_params].nil?
-        req.body = JSON.generate(call_data[:json_params]) # , ascii_only: true
-        Log.log.debug{Log.dump('body JSON data', call_data[:json_params])}
+      if !json_params.nil?
+        req.body = JSON.generate(json_params) # , ascii_only: true
         req['Content-Type'] = 'application/json'
-        # call_data[:headers]['Accept']='application/json'
       end
-      if call_data.key?(:www_body_params)
-        req.body = URI.encode_www_form(call_data[:www_body_params])
-        Log.log.debug{"body www data=#{req.body.chomp}"}
+      if !www_body_params.nil?
+        req.body = URI.encode_www_form(www_body_params)
         req['Content-Type'] = 'application/x-www-form-urlencoded'
       end
-      if call_data.key?(:text_body_params)
-        req.body = call_data[:text_body_params]
-        Log.log.debug{"body data=#{req.body.chomp}"}
+      if !text_body_params.nil?
+        req.body = text_body_params
       end
       # set headers
-      if call_data.key?(:headers)
-        call_data[:headers].each_key do |key|
-          req[key] = call_data[:headers][key]
-        end
+      headers.each do |key, value|
+        req[key] = value
       end
       # :type = :basic
-      req.basic_auth(call_data[:auth][:username], call_data[:auth][:password]) if call_data[:auth][:type].eql?(:basic)
+      req.basic_auth(@auth_params[:username], @auth_params[:password]) if @auth_params[:type].eql?(:basic)
       Log.log.debug{Log.dump(:req_body, req.body)}
       return req
     end
 
+    public
+
+    attr_reader :auth_params
+    attr_reader :base_url
+
+    def params
+      return {
+        base_url:       @base_url,
+        auth:           @auth_params,
+        not_auth_codes: @not_auth_codes,
+        redirect_max:   @redirect_max,
+        headers:        @headers
+      }
+    end
+
+    # @param base_url [String] base URL of REST API
+    # @param auth [Hash] authentication parameters:
+    #     :type (:none, :basic, :url, :oauth2)
+    #     :username   [:basic]
+    #     :password   [:basic]
+    #     :url_query  [:url]    a hash
+    #     :*          [:oauth2] see OAuth::Factory class
+    # @param not_auth_codes [Array] codes that trigger a refresh/regeneration of bearer token
+    # @param redirect_max [int] max redirections allowed
+    def initialize(
+      base_url:,
+      auth: nil,
+      not_auth_codes: nil,
+      redirect_max: 0,
+      headers: nil
+    )
+      Aspera.assert_type(base_url, String)
+      # base url with max one trailing slashes (note: string may be frozen)
+      @base_url = base_url.gsub(%r{//+$}, '/')
+      # default is no auth
+      @auth_params = auth.nil? ? {type: :none} : auth
+      Aspera.assert_type(@auth_params, Hash)
+      Aspera.assert(@auth_params.key?(:type)){'no auth type defined'}
+      @not_auth_codes = not_auth_codes.nil? ? ['401'] : not_auth_codes
+      Aspera.assert_type(@not_auth_codes, Array)
+      # persistent session
+      @http_session = nil
+      # OAuth object (created on demand)
+      @oauth = nil
+      @redirect_max = redirect_max
+      @headers = headers.nil? ? {} : headers
+      Aspera.assert_type(@headers, Hash)
+      @headers['User-Agent'] ||= @@global[:user_agent]
+    end
+
+    # @return the OAuth object (create, or cached if already created)
+    def oauth
+      if @oauth.nil?
+        Aspera.assert(@auth_params[:type].eql?(:oauth2)){'no OAuth defined'}
+        oauth_parameters = @auth_params.reject { |k, _v| k.eql?(:type) }
+        Log.log.debug{Log.dump('oauth parameters', oauth_parameters)}
+        @oauth = OAuth::Factory.instance.create(**oauth_parameters)
+      end
+      return @oauth
+    end
+
+    def oauth_token(force_refresh: false)
+      Aspera.assert_values(force_refresh, [true, false])
+      return oauth.get_authorization(use_refresh_token: force_refresh)
+    end
+
     # HTTP/S REST call
-    # call_data has keys:
-    # :auth
-    # :operation
-    # :subpath
-    # :headers
-    # :json_params
-    # :url_params
-    # :www_body_params
-    # :text_body_params
-    # :save_to_file (filepath) default: nil
-    # :return_error (bool) default: nil
-    # :redirect_max (int) default: 0
-    # :not_auth_codes (array) codes that trigger a refresh/regeneration of bearer token
-    # ----
-    # authentication (:auth) :
-    # :type (:none, :basic, :oauth2, :url)
-    # :username   [:basic]
-    # :password   [:basic]
-    # :url_query  [:url] a hash
-    # :*          [:oauth2] see Oauth class
-    def call(call_data)
-      assert_type(call_data, Hash)
-      call_data[:subpath] = '' if call_data[:subpath].nil?
-      Log.log.debug{"accessing #{call_data[:subpath]}".red.bold.bg_green}
-      call_data[:headers] ||= {}
-      call_data[:headers]['User-Agent'] ||= @@global[:user_agent]
-      # defaults from @params are overridden by call data
-      call_data = @params.deep_merge(call_data)
-      case call_data[:auth][:type]
+    # @param save_to_file (filepath)
+    # @param return_error (bool)
+    def call(
+      operation:,
+      subpath: nil,
+      json_params: nil,
+      url_params: nil,
+      www_body_params: nil,
+      text_body_params: nil,
+      save_to_file: nil,
+      return_error: false,
+      headers: nil
+    )
+      subpath = subpath.to_s if subpath.is_a?(Symbol)
+      subpath = '' if subpath.nil?
+      Aspera.assert_type(subpath, String)
+      if headers.nil?
+        headers = @headers.clone
+      else
+        h = headers
+        headers = @headers.clone
+        headers.merge!(h)
+      end
+      Aspera.assert_type(headers, Hash)
+      Log.log.debug{"#{operation} [#{subpath}]".red.bold.bg_green}
+      case @auth_params[:type]
       when :none
         # no auth
       when :basic
         Log.log.debug('using Basic auth')
         # done in build_req
       when :oauth2
-        call_data[:headers]['Authorization'] = oauth_token unless call_data[:headers].key?('Authorization')
+        headers['Authorization'] = oauth_token unless headers.key?('Authorization')
       when :url
-        call_data[:url_params] ||= {}
-        call_data[:auth][:url_query].each do |key, value|
-          call_data[:url_params][key] = value
+        url_params ||= {}
+        @auth_params[:url_query].each do |key, value|
+          url_params[key] = value
         end
-      else error_unexpected_value(call_data[:auth][:type])
+      else Aspera.error_unexpected_value(@auth_params[:type])
       end
-      req = build_request(call_data)
-      Log.log.debug{"call_data = #{call_data}"}
       result = {http: nil}
       # start a block to be able to retry the actual HTTP request
       begin
+        req = build_request(
+          operation: operation, subpath: subpath, json_params: json_params, url_params: url_params, www_body_params: www_body_params,
+          text_body_params: text_body_params, headers: headers)
         # we try the call, and will retry only if oauth, as we can, first with refresh, and then re-auth if refresh is bad
         oauth_tries ||= 2
         # initialize with number of initial retries allowed, nil gives zero
-        tries_remain_redirect = call_data[:redirect_max].to_i if tries_remain_redirect.nil?
+        tries_remain_redirect = @redirect_max.to_i if tries_remain_redirect.nil?
         Log.log.debug("send request (retries=#{tries_remain_redirect})")
         result_mime = nil
         file_saved = false
@@ -282,13 +319,13 @@ module Aspera
           result[:http] = response
           result_mime = (result[:http]['Content-Type'] || 'text/plain').split(';').first.downcase
           # JSON data needs to be parsed, in case it contains an error code
-          if !call_data[:save_to_file].nil? &&
+          if !save_to_file.nil? &&
               result[:http].code.to_s.start_with?('2') &&
               !result[:http]['Content-Length'].nil? &&
               !JSON_DECODE.include?(result_mime)
             total_size = result[:http]['Content-Length'].to_i
             Log.log.debug('before write file')
-            target_file = call_data[:save_to_file]
+            target_file = save_to_file
             # override user's path to path in header
             if !response['Content-Disposition'].nil? && (m = response['Content-Disposition'].match(/filename="([^"]+)"/))
               target_file = File.join(File.dirname(target_file), m[1])
@@ -321,13 +358,13 @@ module Aspera
         else # when 'text/plain'
           result[:http].body
         end
-        Log.log.debug{Log.dump("result: parsed: #{result_mime}", result[:data])}
-        Log.log.debug{"result: code=#{result[:http].code}"}
+        Log.log.debug{"result: code=#{result[:http].code} mime=#{result_mime}"}
+        Log.log.debug{Log.dump('data', result[:data])}
         RestErrorAnalyzer.instance.raise_on_error(req, result)
-        File.write(call_data[:save_to_file], result[:http].body) unless file_saved || call_data[:save_to_file].nil?
+        File.write(save_to_file, result[:http].body) unless file_saved || save_to_file.nil?
       rescue RestCallError => e
         # not authorized: oauth token expired
-        if call_data[:not_auth_codes].include?(result[:http].code.to_s) && call_data[:auth][:type].eql?(:oauth2)
+        if @not_auth_codes.include?(result[:http].code.to_s) && @auth_params[:type].eql?(:oauth2)
           begin
             # try to use refresh token
             req['Authorization'] = oauth_token(force_refresh: true)
@@ -337,35 +374,28 @@ module Aspera
             # regenerate a brand new token
             req['Authorization'] = oauth_token(force_refresh: true)
           end
-          Log.log.debug{"using new token=#{call_data[:headers]['Authorization']}"}
-          retry unless (oauth_tries -= 1).zero?
+          Log.log.debug{"using new token=#{headers['Authorization']}"}
+          retry if (oauth_tries -= 1).nonzero?
         end # if oauth
         # redirect ? (any code beginning with 3)
-        if tries_remain_redirect.positive? && e.response.is_a?(Net::HTTPRedirection)
+        if e.response.is_a?(Net::HTTPRedirection) && tries_remain_redirect.positive?
           tries_remain_redirect -= 1
-          current_uri = URI.parse(call_data[:base_url])
+          current_uri = URI.parse(@base_url)
           new_url = e.response['location']
           # special case: relative redirect
           if URI.parse(new_url).host.nil?
             # we don't manage relative redirects with non-absolute path
-            assert(new_url.start_with?('/')){"redirect location is relative: #{new_url}, but does not start with /."}
-            new_url = current_uri.scheme + '://' + current_uri.host + new_url
-          end
-          Log.log.info{"URL is moved: #{new_url}"}
-          redirection_uri = URI.parse(new_url)
-          call_data[:base_url] = new_url
-          call_data[:subpath] = ''
-          if current_uri.host.eql?(redirection_uri.host) && current_uri.port.eql?(redirection_uri.port)
-            req = build_request(call_data)
-            retry
-          else
-            # change host
-            Log.log.info{"Redirect changes host: #{current_uri.host} -> #{redirection_uri.host}"}
-            return self.class.new(call_data).call(call_data)
+            Aspera.assert(new_url.start_with?('/')){"redirect location is relative: #{new_url}, but does not start with /."}
+            new_url = "#{current_uri.scheme}://#{current_uri.host}#{new_url}"
           end
+          # forwards the request to the new location
+          return self.class.new(base_url: new_url, redirect_max: tries_remain_redirect).call(
+            operation: operation, json_params: json_params,
+            url_params: url_params, www_body_params: www_body_params, text_body_params: text_body_params,
+            save_to_file: save_to_file, return_error: return_error, headers: headers)
         end
         # raise exception if could not retry and not return error in result
-        raise e unless call_data[:return_error]
+        raise e unless return_error
       end # begin request
       Log.log.debug{"result=#{result}"}
       return result
@@ -377,36 +407,37 @@ module Aspera
 
     # @param encoding : one of: :json_params, :url_params
     def create(subpath, params, encoding=:json_params)
-      return call({operation: 'POST', subpath: subpath, headers: {'Accept' => 'application/json'}, encoding => params})
+      return call(operation: 'POST', subpath: subpath, headers: {'Accept' => 'application/json'}, encoding => params)
     end
 
-    def read(subpath, options=nil)
-      return call({operation: 'GET', subpath: subpath, headers: {'Accept' => 'application/json'}, url_params: options})
+    def read(subpath, query=nil)
+      return call(operation: 'GET', subpath: subpath, headers: {'Accept' => 'application/json'}, url_params: query)
     end
 
     def update(subpath, params)
-      return call({operation: 'PUT', subpath: subpath, headers: {'Accept' => 'application/json'}, json_params: params})
+      return call(operation: 'PUT', subpath: subpath, headers: {'Accept' => 'application/json'}, json_params: params)
     end
 
     def delete(subpath, params=nil)
-      return call({operation: 'DELETE', subpath: subpath, headers: {'Accept' => 'application/json'}, url_params: params})
+      return call(operation: 'DELETE', subpath: subpath, headers: {'Accept' => 'application/json'}, url_params: params)
     end
 
     def cancel(subpath)
-      return call({operation: 'CANCEL', subpath: subpath, headers: {'Accept' => 'application/json'}})
+      return call(operation: 'CANCEL', subpath: subpath, headers: {'Accept' => 'application/json'})
     end
 
-    # Query by name and returns a single result, else it throws an exception (no or multiple results)
+    # Query entity by general search (read with parameter `q`)
+    # TODO: not generic enough ? move somewhere ? inheritance ?
     # @param subpath path of entity in API
     # @param search_name name of searched entity
-    # @param options additional search options
-    def lookup_by_name(subpath, search_name, options={})
-      # returns entities whose name contains value (case insensitive)
-      matching_items = read(subpath, options.merge({'q' => search_name}))[:data]
+    # @param query additional search query parameters
+    # @returns [Hash] A single entity matching the search, or an exception if not found or multiple found
+    def lookup_by_name(subpath, search_name, query={})
+      # returns entities matching the query (it matches against several fields in case insensitive way)
+      matching_items = read(subpath, query.merge({'q' => search_name}))[:data]
       # API style: {totalcount:, ...} cspell: disable-line
-      # TODO: not generic enough ? move somewhere ? inheritance ?
       matching_items = matching_items[subpath] if matching_items.is_a?(Hash)
-      assert_type(matching_items, Array)
+      Aspera.assert_type(matching_items, Array)
       case matching_items.length
       when 1 then return matching_items.first
       when 0 then raise %Q{#{ENTITY_NOT_FOUND} #{subpath}: "#{search_name}"}

data/lib/aspera/rest_errors_aspera.rb

@@ -15,10 +15,10 @@ module Aspera
         RestErrorAnalyzer.instance.add_simple_handler(name: 'Type 1: error:user_message', path: %w[error user_message], always: true)
         RestErrorAnalyzer.instance.add_simple_handler(name: 'Type 2: error:description', path: %w[error description])
         RestErrorAnalyzer.instance.add_simple_handler(name: 'Type 3: error:internal_message', path: %w[error internal_message])
-        # AoC Automation
-        RestErrorAnalyzer.instance.add_simple_handler(name: 'AoC Automation', path: ['error'])
         RestErrorAnalyzer.instance.add_simple_handler(name: 'Type 5', path: ['error_description'])
         RestErrorAnalyzer.instance.add_simple_handler(name: 'Type 6', path: ['message'])
+        # AoC Automation
+        RestErrorAnalyzer.instance.add_simple_handler(name: 'AoC Automation', path: ['error'])
         RestErrorAnalyzer.instance.add_handler('Type 7: errors[]') do |type, call_context|
           next unless call_context[:data].is_a?(Hash) && call_context[:data]['errors'].is_a?(Hash)
           # special for Shares: false positive ? (update global transfer_settings)
@@ -33,7 +33,7 @@ module Aspera
           d_t_s = call_context[:data]['transfer_specs']
           next unless d_t_s.is_a?(Array)
           d_t_s.each do |res|
-            r_err = res.dig(*%w[transfer_spec error])
+            r_err = res.dig(*%w[transfer_spec error]) || res['error']
             next unless r_err.is_a?(Hash)
             RestErrorAnalyzer.add_error(call_context, type, "#{r_err['code']}: #{r_err['reason']}: #{r_err['user_message']}")
           end