aspera-cli 4.13.0 → 4.14.0

data/lib/aspera/fasp/uri.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# cspell:words httpport targetrate minrate bwcap createpath lockpolicy lockminrate
+
 require 'aspera/log'
 require 'aspera/command_line_builder'
 
@@ -7,8 +9,8 @@ module Aspera
   module Fasp
     # translates a "faspe:" URI (used in Faspex 4) into transfer spec hash
     class Uri
-      def initialize(fasplink)
-        @fasp_uri = URI.parse(fasplink.gsub(' ', '%20'))
+      def initialize(fasp_link)
+        @fasp_uri = URI.parse(fasp_link.gsub(' ', '%20'))
         # TODO: check scheme is faspe
       end
 
@@ -18,32 +20,32 @@ module Aspera
         result_ts['remote_user'] = @fasp_uri.user
         result_ts['ssh_port'] = @fasp_uri.port
         result_ts['paths'] = [{'source' => URI.decode_www_form_component(@fasp_uri.path)}]
-        # faspex does not encode trailing base64 encoded tags, fix that
+        # faspex does not encode trailing base64 padding, fix that to be able to decode properly
         fixed_query = @fasp_uri.query.gsub(/(=+)$/){|x|'%3D' * x.length}
 
         URI.decode_www_form(fixed_query).each do |i|
           name = i[0]
           value = i[1]
           case name
-          when 'cookie' then result_ts['cookie'] = value
-          when 'token' then result_ts['token'] = value
-          when 'sshfp' then result_ts['sshfp'] = value
-          when 'policy' then result_ts['rate_policy'] = value
-          when 'httpport' then result_ts['http_fallback_port'] = value.to_i
-          when 'targetrate' then result_ts['target_rate_kbps'] = value.to_i
-          when 'minrate' then result_ts['min_rate_kbps'] = value.to_i
-          when 'port' then result_ts['fasp_port'] = value.to_i
-          when 'bwcap' then result_ts['target_rate_cap_kbps'] = value.to_i
-          when 'enc' then result_ts['cipher'] = value.gsub(/^aes/, 'aes-').gsub(/cfb$/, '-cfb').gsub(/gcm$/, '-gcm').gsub(/--/, '-')
-          when 'tags64' then result_ts['tags'] = JSON.parse(Base64.strict_decode64(value))
-          when 'createpath' then result_ts['create_dir'] = CommandLineBuilder.yes_to_true(value)
-          when 'fallback' then result_ts['http_fallback'] = CommandLineBuilder.yes_to_true(value)
-          when 'lockpolicy' then result_ts['lock_rate_policy'] = CommandLineBuilder.yes_to_true(value)
+          when 'cookie'      then result_ts['cookie'] = value
+          when 'token'       then result_ts['token'] = value
+          when 'sshfp'       then result_ts['sshfp'] = value
+          when 'policy'      then result_ts['rate_policy'] = value
+          when 'httpport'    then result_ts['http_fallback_port'] = value.to_i
+          when 'targetrate'  then result_ts['target_rate_kbps'] = value.to_i
+          when 'minrate'     then result_ts['min_rate_kbps'] = value.to_i
+          when 'port'        then result_ts['fasp_port'] = value.to_i
+          when 'bwcap'       then result_ts['target_rate_cap_kbps'] = value.to_i
+          when 'enc'         then result_ts['cipher'] = value.gsub(/^aes/, 'aes-').gsub(/cfb$/, '-cfb').gsub(/gcm$/, '-gcm').gsub(/--/, '-')
+          when 'tags64'      then result_ts['tags'] = JSON.parse(Base64.strict_decode64(value))
+          when 'createpath'  then result_ts['create_dir'] = CommandLineBuilder.yes_to_true(value)
+          when 'fallback'    then result_ts['http_fallback'] = CommandLineBuilder.yes_to_true(value)
+          when 'lockpolicy'  then result_ts['lock_rate_policy'] = CommandLineBuilder.yes_to_true(value)
           when 'lockminrate' then result_ts['lock_min_rate'] = CommandLineBuilder.yes_to_true(value)
-          when 'auth' then Log.log.debug{"ignoring auth #{name}=#{value}"} # TODO: translate into transfer spec ? yes/no
-          when 'v' then Log.log.debug{"ignoring v #{name}=#{value}"} # TODO: translate into transfer spec ? 2
-          when 'protect' then Log.log.debug{"ignoring protect #{name}=#{value}"} # TODO: translate into transfer spec ?
-          else Log.log.warn{"URI parameter ignored: #{name} = #{value}"}
+          when 'auth'        then Log.log.debug{"ignoring #{name}=#{value}"} # Not used (yes/no)
+          when 'v'           then Log.log.debug{"ignoring #{name}=#{value}"} # rubocop:disable Lint/DuplicateBranch Not used (2)
+          when 'protect'     then Log.log.debug{"ignoring #{name}=#{value}"} # rubocop:disable Lint/DuplicateBranch TODO: what is this ?
+          else                    Log.log.warn{"URI parameter ignored: #{name} = #{value}"}
           end
         end
         return result_ts

data/lib/aspera/faspex_postproc.rb

@@ -13,7 +13,7 @@ module Aspera
     def initialize(server, parameters)
       raise 'parameters must be Hash' unless parameters.is_a?(Hash)
       @parameters = parameters.symbolize_keys
-      Log.dump(:postproc_parameters, @parameters)
+      Log.dump(:post_proc_parameters, @parameters)
       raise "unexpected key in parameters config: only: #{ALLOWED_PARAMETERS.join(', ')}" if @parameters.keys.any?{|k|!ALLOWED_PARAMETERS.include?(k)}
       @parameters[:script_folder] ||= '.'
       @parameters[:fail_on_error] ||= false

data/lib/aspera/hash_ext.rb

@@ -2,11 +2,21 @@
 
 class ::Hash
   def deep_merge(second)
-    merge(second){|_key, v1, v2|Hash === v1 && Hash === v2 ? v1.deep_merge(v2) : v2}
+    merge(second){|_key, v1, v2|v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge(v2) : v2}
   end
 
   def deep_merge!(second)
-    merge!(second){|_key, v1, v2|Hash === v1 && Hash === v2 ? v1.deep_merge!(v2) : v2}
+    merge!(second){|_key, v1, v2|v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
+  end
+
+  def deep_do(memory=nil, &block)
+    each do |key, value|
+      if value.is_a?(Hash)
+        value.deep_do(memory, &block)
+      else
+        yield(self, key, value, memory)
+      end
+    end
   end
 end
 

data/lib/aspera/keychain/macos_security.rb

@@ -3,11 +3,11 @@
 # https://github.com/fastlane-community/security
 require 'aspera/cli/info'
 
-# enhance the gem to support other keychains
+# enhance the gem to support other key chains
 module Aspera
   module Keychain
     module MacosSecurity
-      # keychain based on macOS keychain, using `security` cmmand line
+      # keychain based on macOS keychain, using `security` command line
       class Keychain
         DOMAINS = %i[user system common dynamic].freeze
         LIST_OPTIONS = {
@@ -32,12 +32,12 @@ module Aspera
           getpass:  :g
         }.freeze
         class << self
-          def execute(command, options=nil, supported=nil, lastopt=nil)
+          def execute(command, options=nil, supported=nil, last_opt=nil)
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
               raise 'only https' unless uri.scheme.eql?('https')
-              options[:protocol] = 'htps'
+              options[:protocol] = 'htps' # cspell: disable-line
               raise 'host required in URL' if uri.host.nil?
               options[:server] = uri.host
               options[:path] = uri.path unless ['', '/'].include?(uri.path)
@@ -50,28 +50,28 @@ module Aspera
               cmd.push("-#{supported[k]}")
               cmd.push(v.shellescape) unless v.empty?
             end
-            cmd.push(lastopt) unless lastopt.nil?
+            cmd.push(last_opt) unless last_opt.nil?
             Log.log.debug{"executing>>#{cmd.join(' ')}"}
             result = %x(#{cmd.join(' ')} 2>&1)
             Log.log.debug{"result>>[#{result}]"}
             return result
           end
 
-          def keychains(output)
+          def key_chains(output)
             output.split("\n").collect { |line| new(line.strip.gsub(/^"|"$/, '')) }
           end
 
           def default
-            keychains(execute('default-keychain')).first
+            key_chains(execute('default-keychain')).first
           end
 
           def login
-            keychains(execute('login-keychain')).first
+            key_chains(execute('login-keychain')).first
           end
 
           def list(options={})
             raise ArgumentError, "Invalid domain #{options[:domain]}, expected one of: #{DOMAINS}" unless options[:domain].nil? || DOMAINS.include?(options[:domain])
-            keychains(execute('list-keychains', options, LIST_OPTIONS))
+            key_chains(execute('list-key_chains', options, LIST_OPTIONS))
           end
 
           def by_name(name)
@@ -88,14 +88,14 @@ module Aspera
           [string].pack('H*').force_encoding('UTF-8')
         end
 
-        def password(operation, passtype, options)
+        def password(operation, pass_type, options)
           raise "wrong operation: #{operation}" unless %i[add find delete].include?(operation)
-          raise "wrong passtype: #{passtype}" unless %i[generic internet].include?(passtype)
+          raise "wrong pass_type: #{pass_type}" unless %i[generic internet].include?(pass_type)
           raise 'options shall be Hash' unless options.is_a?(Hash)
           missing = (operation.eql?(:add) ? %i[account service password] : %i[label]) - options.keys
           raise "missing options: #{missing}" unless missing.empty?
           options[:getpass] = '' if operation.eql?(:find)
-          output = self.class.execute("#{operation}-#{passtype}-password", options, ADD_PASS_OPTIONS, @path)
+          output = self.class.execute("#{operation}-#{pass_type}-password", options, ADD_PASS_OPTIONS, @path)
           raise output.gsub(/^.*: /, '') if output.start_with?('security: ')
           return nil unless operation.eql?(:find)
           attributes = {}
@@ -143,7 +143,7 @@ module Aspera
         raise 'not found' if info.nil?
         result = options.clone
         result[:secret] = info['password']
-        result[:description] = info['icmt']
+        result[:description] = info['icmt'] # cspell: disable-line
         return result
       end
 

data/lib/aspera/log.rb

@@ -39,6 +39,7 @@ module Aspera
         end
       end
 
+      # Capture the output of $stderr and log it at debug level
       def capture_stderr
         real_stderr = $stderr
         $stderr = StringIO.new

data/lib/aspera/node.rb

@@ -17,6 +17,7 @@ module Aspera
     MATCH_EXEC_PREFIX = 'exec:'
     HEADER_X_ASPERA_ACCESS_KEY = 'X-Aspera-AccessKey'
     PATH_SEPARATOR = '/'
+    TS_FIELDS_TO_COPY = %w[remote_host remote_user ssh_port fasp_port wss_enabled wss_port].freeze
 
     # register node special token decoder
     Oauth.register_decoder(lambda{|token|JSON.parse(Zlib::Inflate.inflate(Base64.decode64(token)).partition('==SIGNATURE==').first)})
@@ -84,15 +85,16 @@ module Aspera
       return nil
     end
 
-    # recursively browse in a folder (with non-recursive method)
+    # Recursively browse in a folder (with non-recursive method)
     # sub folders are processed if the processing method returns true
     # @param state [Object] state object sent to processing method
-    # @param method [Symbol] processing method name
     # @param top_file_id [String] file id to start at (default = access key root file id)
     # @param top_file_path [String] path of top folder (default = /)
-    def process_folder_tree(state:, method:, top_file_id:, top_file_path: '/')
+    # @param block [Proc] processing method, args: entry, path, state
+    def process_folder_tree(state:, top_file_id:, top_file_path: '/', &block)
       raise 'INTERNAL ERROR: top_file_path not set' if top_file_path.nil?
-      raise "INTERNAL ERROR: Missing method #{method}" unless respond_to?(method)
+      raise 'INTERNAL ERROR: Missing block' unless block
+      # start at top folder
       folders_to_explore = [{id: top_file_id, path: top_file_path}]
       Log.dump(:folders_to_explore, folders_to_explore)
       until folders_to_explore.empty?
@@ -109,9 +111,9 @@ module Aspera
         Log.dump(:folder_contents, folder_contents)
         folder_contents.each do |entry|
           relative_path = File.join(current_item[:path], entry['name'])
-          Log.log.debug{"looking #{relative_path}".bg_green}
+          Log.log.debug{"process_folder_tree checking #{relative_path}"}
           # continue only if method returns true
-          next unless send(method, entry, relative_path, state)
+          next unless yield(entry, relative_path, state)
           # entry type is file, folder or link
           case entry['type']
           when 'folder'
@@ -119,85 +121,74 @@ module Aspera
           when 'link'
             node_id_to_node(entry['target_node_id'])&.process_folder_tree(
               state:         state,
-              method:        method,
               top_file_id:   entry['target_id'],
-              top_file_path: relative_path)
+              top_file_path: relative_path,
+              &block)
           end
         end
       end
     end # process_folder_tree
 
-    # processing method to resolve a file path to id
-    # @returns true if processing need to continue
-    def process_resolve_node_path(entry, _path, state)
-      # stop digging here if not in right path
-      return false unless entry['name'].eql?(state[:path].first)
-      # ok it matches, so we remove the match
-      state[:path].shift
-      case entry['type']
-      when 'file'
-        # file must be terminal
-        raise "#{entry['name']} is a file, expecting folder to find: #{state[:path]}" unless state[:path].empty?
-        # it's terminal, we found it
-        state[:result] = {api: self, file_id: entry['id']}
-        return false
-      when 'folder'
-        if state[:path].empty?
-          # we found it
-          state[:result] = {api: self, file_id: entry['id']}
-          return false
-        end
-      when 'link'
-        if state[:path].empty?
-          # we found it
-          other_node = node_id_to_node(entry['target_node_id'])
-          raise 'cannot resolve link' if other_node.nil?
-          state[:result] = {api: other_node, file_id: entry['target_id']}
-          return false
-        end
-      else
-        Log.log.warn{"Unknown element type: #{entry['type']}"}
-      end
-      # continue to dig folder
-      return true
-    end
-
     # Navigate the path from given file id
     # @param top_file_id [String] id initial file id
     # @param path [String]  file path
     # @return [Hash] {.api,.file_id}
     def resolve_api_fid(top_file_id, path)
       raise 'file id shall be String' unless top_file_id.is_a?(String)
+      process_last_link = path.end_with?(PATH_SEPARATOR)
       path_elements = path.split(PATH_SEPARATOR).reject(&:empty?)
       return {api: self, file_id: top_file_id} if path_elements.empty?
       resolve_state = {path: path_elements, result: nil}
-      process_folder_tree(state: resolve_state, method: :process_resolve_node_path, top_file_id: top_file_id)
-      raise "entry not found: #{resolve_state[:path]}" if resolve_state[:result].nil?
-      return resolve_state[:result]
-    end
-
-    # add entry to list if test block is success
-    # @return [TrueClass,FalseClass]
-    def process_find_files(entry, path, state)
-      begin
-        # add to result if match filter
-        state[:found].push(entry.merge({'path' => path})) if state[:test_block].call(entry)
-        # process link
-        if entry[:type].eql?('link')
-          other_node = node_id_to_node(entry['target_node_id'])
-          other_node.process_folder_tree(state: state, method: process_find_files, top_file_id: entry['target_id'], top_file_path: path)
+      process_folder_tree(state: resolve_state, top_file_id: top_file_id) do |entry, _path, state|
+        # this block is called recursively for each entry in folder
+        # stop digging here if not in right path
+        next false unless entry['name'].eql?(state[:path].first)
+        # ok it matches, so we remove the match
+        state[:path].shift
+        case entry['type']
+        when 'file'
+          # file must be terminal
+          raise "#{entry['name']} is a file, expecting folder to find: #{state[:path]}" unless state[:path].empty?
+          # it's terminal, we found it
+          state[:result] = {api: self, file_id: entry['id']}
+          next false
+        when 'folder'
+          if state[:path].empty?
+            # we found it
+            state[:result] = {api: self, file_id: entry['id']}
+            next false
+          end
+        when 'link'
+          if state[:path].empty?
+            if process_last_link
+              # we found it
+              other_node = node_id_to_node(entry['target_node_id'])
+              raise 'cannot resolve link' if other_node.nil?
+              state[:result] = {api: other_node, file_id: entry['target_id']}
+            else
+              # we found it but we do not process the link
+              state[:result] = {api: self, file_id: entry['id']}
+            end
+            next false
+          end
+        else
+          Log.log.warn{"Unknown element type: #{entry['type']}"}
         end
-      rescue StandardError => e
-        Log.log.error{"#{path}: #{e.message}"}
+        # continue to dig folder
+        next true
       end
-      # process all folders
-      return true
+      raise "entry not found: #{resolve_state[:path]}" if resolve_state[:result].nil?
+      return resolve_state[:result]
     end
 
     def find_files(top_file_id, test_block)
       Log.log.debug{"find_files: file id=#{top_file_id}"}
       find_state = {found: [], test_block: test_block}
-      process_folder_tree(state: find_state, method: :process_find_files, top_file_id: top_file_id)
+      process_folder_tree(state: find_state, top_file_id: top_file_id) do |entry, path, state|
+        state[:found].push(entry.merge({'path' => path})) if state[:test_block].call(entry)
+        # test all files deeply
+        true
+      end
       return find_state[:found]
     end
 
@@ -212,6 +203,8 @@ module Aspera
       case params[:auth][:type]
       when :basic
         ak_name = params[:auth][:username]
+        raise 'ERROR: no secret in node object' unless params[:auth][:password]
+        ak_token = Rest.basic_creds(params[:auth][:username], params[:auth][:password])
       when :oauth2
         ak_name = params[:headers][HEADER_X_ASPERA_ACCESS_KEY]
         # TODO: token_generation_lambda = lambda{|do_refresh|oauth_token(force_refresh: do_refresh)}
@@ -235,12 +228,7 @@ module Aspera
       add_tspec_info(transfer_spec)
       transfer_spec.deep_merge!(ts_merge) unless ts_merge.nil?
       # add application specific tags (AoC)
-      the_app = app_info
-      the_app[:api].add_ts_tags(transfer_spec: transfer_spec, app_info: the_app) unless the_app.nil?
-      # add basic token
-      if transfer_spec['token'].nil?
-        ts_basic_token(transfer_spec)
-      end
+      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
         # get default TCP/UDP ports and transfer user
@@ -251,23 +239,17 @@ module Aspera
           transfer_spec['remote_host'] = @app_info[:node_info]['transfer_url']
         end
       else
-        # retrieve values from API
-        std_t_spec = create(
+        # retrieve values from API (and keep a copy/cache)
+        @std_t_spec_cache ||= create(
           'files/download_setup',
           {transfer_requests: [{ transfer_request: {paths: [{'source' => '/'}] } }] }
         )[:data]['transfer_specs'].first['transfer_spec']
         # copy some parts
-        %w[remote_host remote_user ssh_port fasp_port wss_enabled wss_port].each {|i| transfer_spec[i] = std_t_spec[i] if std_t_spec.key?(i)}
+        TS_FIELDS_TO_COPY.each {|i| transfer_spec[i] = @std_t_spec_cache[i] if @std_t_spec_cache.key?(i)}
       end
+      Log.log.warn{"Expected transfer user: #{Fasp::TransferSpec::ACCESS_KEY_TRANSFER_USER}, but have #{transfer_spec['remote_user']}"} \
+        unless transfer_spec['remote_user'].eql?(Fasp::TransferSpec::ACCESS_KEY_TRANSFER_USER)
       return transfer_spec
     end
-
-    # set basic token in transfer spec
-    def ts_basic_token(ts)
-      Log.log.warn{"Expected transfer user: #{Fasp::TransferSpec::ACCESS_KEY_TRANSFER_USER}, but have #{ts['remote_user']}"} \
-        unless ts['remote_user'].eql?(Fasp::TransferSpec::ACCESS_KEY_TRANSFER_USER)
-      raise 'ERROR: no secret in node object' unless params[:auth][:password]
-      ts['token'] = Rest.basic_creds(params[:auth][:username], params[:auth][:password])
-    end
   end
 end

data/lib/aspera/oauth.rb

@@ -192,7 +192,7 @@ module Aspera
       # replace default values
       @generic_parameters = DEFAULT_CREATE_PARAMS.deep_merge(a_params)
       # legacy
-      @generic_parameters[:grant_method] ||= @generic_parameters.delete(:crtype) if @generic_parameters.key?(:crtype)
+      @generic_parameters[:grant_method] ||= @generic_parameters.delete(:crtype) if @generic_parameters.key?(:crtype) # cspell: disable-line
       # check that type is known
       self.class.token_creator(@generic_parameters[:grant_method])
       # specific parameters for the creation type

data/lib/aspera/persistency_action_once.rb

@@ -8,7 +8,7 @@ module Aspera
   class PersistencyActionOnce
     # @param :manager  Mandatory Database
     # @param :data     Mandatory object to persist, must be same object from begin to end (assume array by default)
-    # @param :id      Mandatory identifiers
+    # @param :id       Mandatory identifiers
     # @param :delete   Optional  delete persistency condition
     # @param :parse    Optional  parse method (default to JSON)
     # @param :format   Optional  dump method (default to JSON)

data/lib/aspera/preview/terminal.rb

@@ -1,34 +1,80 @@
 # frozen_string_literal: true
 
+# cspell:words Magick MAGICKCORE ITERM mintty winsize termcap
+
 require 'rmagick' # https://rmagick.github.io/index.html
 require 'rainbow'
 require 'io/console'
 module Aspera
   module Preview
-    # function conversion_type returns one of the types: CONVERSION_TYPES
+    # Generates a string that can display an image in a terminal
     class Terminal
+      # quantum depth is 8 or 16: convert xc: -format "%q" info:
+      # Rainbow only supports 8-bit colors
+      SHIFT_FOR_8_BIT = Magick::MAGICKCORE_QUANTUM_DEPTH - 8
+      ITERM_NAMES = %w[iTerm WezTerm mintty].freeze
+      TERM_ENV_VARS = %w[TERM_PROGRAM LC_TERMINAL].freeze
+      private_constant :SHIFT_FOR_8_BIT, :ITERM_NAMES, :TERM_ENV_VARS
       class << self
-        def build(blob, reserved_lines: 0)
-          # TODO: retrieve terminal ratio using
-          font_ratio = 1.7
+        def build(blob, reserved_lines: 0, double_precision: true)
+          return iterm_display_image(blob) if iterm_supported?
+          image = Magick::ImageList.new.from_blob(blob)
           (term_rows, term_columns) = IO.console.winsize
           term_rows -= reserved_lines
-          image = Magick::ImageList.new.from_blob(blob)
-          chosen_factor = [term_rows / image.rows.to_f, term_columns / image.columns.to_f].min
-          image = image.scale((image.columns * chosen_factor * font_ratio).to_i, (image.rows * chosen_factor).to_i)
-          text_pixels = []
+          # compute scaling to fit terminal
+          fit_term_ratio = [term_rows / image.rows.to_f, term_columns / image.columns.to_f].min
+          # TODO: retrieve terminal font ratio using some termcap ?
+          font_ratio = 1.7
+          height_ratio = double_precision ? 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)
+          # get all pixel colors, adjusted for Rainbow
+          pixel_colors = []
           image.each_pixel do |pixel, col, row|
-            text_pixels.push("\n") if col.eql?(0) && !row.eql?(0)
-            pixel_rgb = [pixel.red, pixel.green, pixel.blue].map do |color|
-              # quantum depth is 8 or 16: convert xc: -format "%q" info:
-              # Rainbow only supports 8-bit colors
-              color >> (Magick::MAGICKCORE_QUANTUM_DEPTH - 8)
+            pixel_rgb = [pixel.red, pixel.green, pixel.blue]
+            pixel_rgb = pixel_rgb.map { |color| color >> SHIFT_FOR_8_BIT } unless SHIFT_FOR_8_BIT.eql?(0)
+            # init 2-dim array
+            pixel_colors[row] ||= []
+            pixel_colors[row][col] = pixel_rgb
+          end
+          # now generate text
+          text_pixels = []
+          pixel_colors.each_with_index do |row_data, row|
+            next if double_precision && row.odd?
+            row_data.each_with_index do |pixel_rgb, col|
+              text_pixels.push("\n") if col.eql?(0) && !row.eql?(0)
+              if double_precision
+                text_pixels.push(Rainbow('▄').background(pixel_rgb).foreground(pixel_colors[row + 1][col]))
+              else
+                text_pixels.push(Rainbow(' ').background(pixel_rgb))
+              end
             end
-            text_pixels.push(Rainbow(' ').background(pixel_rgb))
           end
           return text_pixels.join
         end
-    end # class << self
+
+        # display image in iTerm2
+        def iterm_display_image(blob)
+          # image = Magick::ImageList.new.from_blob(blob)
+          arguments = {
+            inline:              1,
+            preserveAspectRatio: 1,
+            size:                blob.length
+            # width:               image.columns,
+            # height:              image.rows
+          }.map { |k, v| "#{k}=#{v}" }.join(';')
+          # \a is BEL, \e is ESC : https://github.com/ruby/ruby/blob/master/doc/syntax/literals.rdoc#label-Strings
+          # https://iterm2.com/documentation-images.html
+          return "\e]1337;File=#{arguments}:#{Base64.encode64(blob)}\a"
+        end
+
+        # @return [Boolean] true if the terminal supports iTerm2 image display
+        def iterm_supported?
+          TERM_ENV_VARS.each do |env_var|
+            return true if ITERM_NAMES.any? { |term| ENV[env_var]&.include?(term) }
+          end
+          false
+        end
+      end # class << self
     end # class Terminal
   end # module Preview
 end # module Aspera

data/lib/aspera/preview/utils.rb

@@ -19,7 +19,7 @@ module Aspera
       private_constant :BASH_SPECIAL_CHARACTERS, :BASH_EXIT_NOT_FOUND, :EXTERNAL_TOOLS, :TEMP_FORMAT
 
       class << self
-        # returns string with single quotes suitable for bash if there is any bash metacharacter
+        # returns string with single quotes suitable for bash if there is any bash meta-character
         def shell_quote(argument)
           return argument unless argument.chars.any?{|c|BASH_SPECIAL_CHARACTERS.include?(c)}
           return "'" + argument.gsub(/'/){|_s| "'\"'\"'"} + "'"
@@ -55,7 +55,7 @@ module Aspera
             raise "Error: #{command_symb} is not in the PATH"
           end
           unless exit_status.success?
-            Log.log.error{"commandline: #{command}"}
+            Log.log.error{"command line: #{command}"}
             Log.log.error{"Error code: #{exit_status}"}
             Log.log.error{"stdout: #{stdout}"}
             Log.log.error{"stderr: #{stderr}"}
@@ -82,7 +82,7 @@ module Aspera
           result = external_command(:ffprobe, [
             '-loglevel', 'error',
             '-show_entries', 'format=duration',
-            '-print_format', 'default=noprint_wrappers=1:nokey=1',
+            '-print_format', 'default=noprint_wrappers=1:nokey=1', # cspell:disable-line
             input_file])
           return result[:stdout].to_f
         end

data/lib/aspera/proxy_auto_config.js

@@ -70,7 +70,7 @@ function shExpMatch(str, shell_expr) {
 }
 function weekdayRange(wd1, wd2, gmt) {
 	var today = new Date();
-	var days = 'SUNMONTUEWEDTHUFRISAT';
+	var days = 'SUNMONTUEWEDTHUFRISAT'; // cspell: disable-line
 	wd1 = wd1.toUpperCase();
 	if (wd2 == undefined)
 		wd2 = wd1;
@@ -138,7 +138,7 @@ function dateRange() {
 			else
 				return false;
 		} else if (typeof arg == 'string') {
-			var months = 'JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC';
+			var months = 'JANFEBMARAPRMAYJUNJULAUGSEPOCTNOVDEC'; // cspell: disable-line
 			arg = arg.toUpperCase();
 			arg = months.indexOf(arg);
 			if (arg == -1)

data/lib/aspera/rest.rb

@@ -38,6 +38,11 @@ module Aspera
 
     ARRAY_PARAMS = '[]'
 
+    private_constant :ARRAY_PARAMS
+
+    # error message when entity not found
+    ENTITY_NOT_FOUND = 'No such'
+
     class << self
       # define accessors
       @@global.each_key do |p|
@@ -50,6 +55,12 @@ module Aspera
 
       def basic_creds(user, pass); return "Basic #{Base64.strict_encode64("#{user}:#{pass}")}"; end
 
+      # used to build a parameter list prefixed with "[]"
+      # @param values [Array] list of values
+      def array_params(values)
+        return [ARRAY_PARAMS].concat(values)
+      end
+
       # build URI from URL and parameters and check it is http or https
       def build_uri(url, params=nil)
         uri = URI.parse(url)
@@ -337,5 +348,31 @@ module Aspera
     def cancel(subpath)
       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)
+    # @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' => CGI.escape(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)
+      raise "Internal error: expecting array, have #{matching_items.class}" unless matching_items.is_a?(Array)
+      case matching_items.length
+      when 1 then return matching_items.first
+      when 0 then raise %Q{#{ENTITY_NOT_FOUND} #{subpath}: "#{search_name}"}
+      else
+        # multiple case insensitive partial matches, try case insensitive full match
+        # (anyway AoC does not allow creation of 2 entities with same case insensitive name)
+        name_matches = matching_items.select{|i|i['name'].casecmp?(search_name)}
+        case name_matches.length
+        when 1 then return name_matches.first
+        when 0 then raise %Q(#{subpath}: multiple case insensitive partial match for: "#{search_name}": #{matching_items.map{|i|i['name']}} but no case insensitive full match. Please be more specific or give exact name.) # rubocop:disable Layout/LineLength
+        else raise "Two entities cannot have the same case insensitive name: #{name_matches.map{|i|i['name']}}"
+        end
+      end
+    end
   end
 end # module Aspera