aspera-cli 4.25.6 → 4.26.0

data/lib/aspera/cli/plugins/preview.rb

@@ -14,6 +14,7 @@ require 'aspera/api/node'
 require 'aspera/hash_ext'
 require 'aspera/timer_limiter'
 require 'aspera/id_generator'
+require 'aspera/uri_reader'
 require 'aspera/log'
 require 'aspera/assert'
 require 'securerandom'
@@ -22,31 +23,30 @@ module Aspera
   module Cli
     module Plugins
       class Preview < BasicAuth
-        # special tag to identify transfers related to generator
+        # Reserved transfer tag used to identify preview-generation transfers.
         PREV_GEN_TAG = 'preview_generator'
-        # defined by node API: suffix for folder containing previews
+        # Node API suffix for the per-file preview folder.
         PREVIEW_FOLDER_SUFFIX = '.asp-preview'
-        # basename of preview files
+        # Default basename for generated preview files.
         PREVIEW_BASENAME = 'preview'
-        # subfolder in system tmp folder
+        # Prefix for the temporary working directory created under the system temp folder.
         TMP_DIR_PREFIX = 'prev_tmp'
-        # same value as in aspera.conf
+        # Default preview root folder name, aligned with `aspera.conf`.
         DEFAULT_PREVIEWS_FOLDER = 'previews'
-        # mark that this is used by a particular access key
+        # Marker file recording which access key owns a cached preview area.
         AK_MARKER_FILE = '.aspera_access_key'
-        # URL prefix for local storage
-        PVCL_LOCAL_STORAGE = 'file:///'
         LOG_LIMITER_SEC = 30.0
+        REMOTE_ACCESS = 'aspera:'
         private_constant :PREV_GEN_TAG,
           :PREVIEW_FOLDER_SUFFIX,
           :PREVIEW_BASENAME,
           :TMP_DIR_PREFIX,
           :DEFAULT_PREVIEWS_FOLDER,
-          :PVCL_LOCAL_STORAGE,
           :AK_MARKER_FILE,
-          :LOG_LIMITER_SEC
+          :LOG_LIMITER_SEC,
+          :REMOTE_ACCESS
 
-        attr_accessor :option_skip_types, :option_previews_folder, :option_folder_reset_cache, :option_skip_folders, :option_overwrite, :option_file_access
+        attr_accessor :option_skip_types, :option_previews_folder, :option_folder_reset_cache, :option_skip_folders, :option_overwrite
 
         def initialize(**_)
           super
@@ -55,17 +55,19 @@ module Aspera
           @option_previews_folder = nil
           @option_overwrite = nil
           @option_folder_reset_cache = nil
-          # options for generation
+          # Generator configuration populated from CLI options.
           @gen_options = Aspera::Preview::Options.new
-          # used to trigger periodic processing
+          # Used to rate-limit periodic progress logging and checkpoint persistence.
           @periodic = TimerLimiter.new(LOG_LIMITER_SEC)
-          # Proc
+          # Optional callback used to filter entries before generation.
           @filter_block = nil
-          # link CLI options to gen_info attributes
+          @access_remote = true
+          # Bind CLI options directly to generator option attributes.
           options.declare(
             :skip_format, 'Skip this preview format',
             allowed: Aspera::Preview::Generator::PREVIEW_FORMATS
           )
+          # TODO: use the same option as in `node` plugin
           options.declare(
             :folder_reset_cache, 'Force detection of generated preview by refresh cache',
             allowed: %i[no header read],
@@ -81,12 +83,12 @@ module Aspera
           options.declare(:mimemagic, 'Use Mime type detection of gem mimemagic', allowed: Allowed::TYPES_BOOLEAN, default: false)
           options.declare(:overwrite, 'When to overwrite result file', handler: {o: self, m: :option_overwrite}, allowed: %i[always never mtime], default: :mtime)
           options.declare(
-            :file_access, 'How to read and write files in repository',
-            allowed: %i[local remote],
-            handler: {o: self, m: :option_file_access},
-            default: :local
+            :root_url,
+            "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})",
+            allowed: Allowed::TYPES_STRING,
+            default: ''
           )
-          # add other options for generator (and set default values)
+          # Declare generator-specific options and apply their default values.
           Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
             values = if opt.key?(:values)
               opt[:values]
@@ -97,7 +99,8 @@ module Aspera
           end
 
           options.parse_options!
-          # by default generate all supported formats (clone, as altered by options)
+          Api::Node.api_options[:cache] = !@option_folder_reset_cache.eql?(:header)
+          # Start from the full supported format list, then remove any skipped format.
           @preview_formats_to_generate = Aspera::Preview::Generator::PREVIEW_FORMATS.clone
           skip = options.get_option(:skip_format)
           @preview_formats_to_generate.delete(skip) if skip
@@ -106,22 +109,16 @@ module Aspera
           Log.log.debug{"tmpdir: #{@tmp_folder}"}
         end
 
-        # /files/id/files is normally cached in Redis, but we can discard the cache
-        # but /files/id is not cached
-        def get_folder_entries(file_id, request_args = nil)
-          headers = {'Accept' => Mime::JSON}
-          headers['X-Aspera-Cache-Control'] = 'no-cache' if @option_folder_reset_cache.eql?(:header)
-          return @api_node.read("files/#{file_id}/files", request_args, headers: headers)
-        end
-
-        # old version based on folders
-        # @param iteration_persistency can be nil
+        # Process legacy transfer events and trigger preview generation for completed downloads.
+        #
+        # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
+        # @return [void]
         def process_trevents(iteration_persistency)
           events_filter = {
             'access_key' => @access_key_self['id'],
             'type'       => 'download.ended'
           }
-          # optionally add iteration token from persistency
+          # Resume from the last persisted event id when available.
           events_filter['iteration_token'] = iteration_persistency.data.first unless iteration_persistency.nil?
           begin
             events = @api_node.read('events', events_filter)
@@ -146,10 +143,10 @@ module Aspera
                 scan_folder_files(folder_entry) unless folder_entry.nil?
               end
             end
-            # log/persist periodically or last one
+            # Periodically log progress and persist the latest processed event.
             next unless @periodic.trigger? || event.equal?(events.last)
             Log.log.debug{"Processed event #{event['id']}"}
-            # save checkpoint to avoid losing processing in case of error
+            # Save a checkpoint to avoid replaying the full batch after a failure.
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
               iteration_persistency.save
@@ -157,19 +154,22 @@ module Aspera
           end
         end
 
-        # requests recent events on node api and process newly modified folders
+        # Process recent Node API file events since the last persisted checkpoint.
+        #
+        # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
+        # @return [void]
         def process_events(iteration_persistency)
-          # get new file creation by access key (TODO: what if file already existed?)
+          # Restrict the event stream to file-related changes for the current access key.
           events_filter = {
             'access_key' => @access_key_self['id'],
             'type'       => 'file.*'
           }
-          # optionally add iteration token from persistency
+          # Resume from the last persisted event id when available.
           events_filter['iteration_token'] = iteration_persistency.data.first unless iteration_persistency.nil?
           events = @api_node.read('events', events_filter)
           return if events.empty?
           events.each do |event|
-            # process only files
+            # Ignore non-file events such as folder notifications.
             if event.dig('data', 'type').eql?('file')
               file_entry = @api_node.read("files/#{event['data']['id']}") rescue nil
               if !file_entry.nil? &&
@@ -179,10 +179,10 @@ module Aspera
                 generate_preview(file_entry) if event['types'].include?('file.deleted')
               end
             end
-            # log/persist periodically or last one
+            # Periodically log progress and persist the latest processed event.
             next unless @periodic.trigger? || event.equal?(events.last)
             Log.log.debug{"Processing event #{event['id']}"}
-            # save checkpoint to avoid losing processing in case of error
+            # Save a checkpoint to avoid replaying the full batch after a failure.
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
               iteration_persistency.save
@@ -190,21 +190,34 @@ module Aspera
           end
         end
 
+        # Transfer a file to or from the configured Node storage using a tagged transfer spec.
+        #
+        # @param direction [String] transfer direction, typically from [`Transfer::Spec`](lib/aspera/transfer/spec.rb)
+        # @param folder_id [String] Node API identifier of the reference folder
+        # @param source_filename [String] relative source path inside the transfer root
+        # @param destination [String, nil] local destination root for receive operations
+        # @return [Object] transfer result returned by [`Main.result_transfer`](lib/aspera/cli/main.rb)
         def do_transfer(direction, folder_id, source_filename, destination = '/')
           Aspera.assert(!(destination.nil? && direction.eql?(Transfer::Spec::DIRECTION_RECEIVE)))
           t_spec = @api_node.transfer_spec_gen4(folder_id, direction, {
             'paths' => [{'source' => source_filename}],
             'tags'  => {Transfer::Spec::TAG_RESERVED => {PREV_GEN_TAG => true}}
           })
-          # force destination, need to set this in transfer agent else it gets overwritten, do not do: t_spec['destination_root']=destination
+          # Force the destination on the transfer agent object.
+          # Setting `t_spec['destination_root']` directly would later be overwritten.
           transfer.user_transfer_spec['destination_root'] = destination
           Main.result_transfer(transfer.start(t_spec))
         end
 
+        # Populate generation metadata for a source file available on the local filesystem.
+        #
+        # @param gen_infos [Array<Hash>] preview generation descriptors to enrich
+        # @param entry [Hash] file entry containing at least the relative path
+        # @return [String] local directory where previews for this entry are stored
         def get_infos_local(gen_infos, entry)
           local_original_filepath = File.join(@local_storage_root, entry['path'])
           original_mtime = File.mtime(local_original_filepath)
-          # out
+          # Output directory for previews generated from the local source file.
           local_entry_preview_dir = File.join(@local_preview_folder, entry_preview_folder_name(entry))
           gen_infos.each do |gen_info|
             gen_info[:src] = local_original_filepath
@@ -215,41 +228,57 @@ module Aspera
           return local_entry_preview_dir
         end
 
+        # Populate generation metadata for a source file stored remotely on Node.
+        #
+        # @param gen_infos [Array<Hash>] preview generation descriptors to enrich
+        # @param entry [Hash] remote file entry returned by Node API
+        # @return [String] temporary local directory where previews are generated
         def get_infos_remote(gen_infos, entry)
-          # store source directly here
+          # Download the source file into the temporary workspace before generating previews.
           local_original_filepath = File.join(@tmp_folder, entry['name'])
           # require 'date'
           # original_mtime=DateTime.parse(entry['modified_time'])
-          # out: where previews are generated
+          # Local directory where previews are generated before being uploaded back.
           local_entry_preview_dir = File.join(@tmp_folder, entry_preview_folder_name(entry))
           file_info = @api_node.read("files/#{entry['id']}")
-          # TODO: this does not work because previews is hidden in api (gen4)
-          # this_preview_folder_entries=get_folder_entries(@previews_folder_entry['id'],{name: @entry_preview_folder_name})
-          # TODO: use gen3 api to list files and get date
+          # TODO: This does not work with Gen4 because preview folders are hidden by the API.
+          # this_preview_folder_entries=@api_node.read_folder_content(@previews_folder_entry['id'],{name: @entry_preview_folder_name})
+          # TODO: Query Gen3 APIs to list preview files and retrieve timestamps.
           gen_infos.each do |gen_info|
             gen_info[:src] = local_original_filepath
             gen_info[:dst] = File.join(local_entry_preview_dir, gen_info[:base_dest])
-            # TODO: use this_preview_folder_entries (but it's hidden)
+            # TODO: Reuse `this_preview_folder_entries` once preview folders become visible.
             gen_info[:preview_exist] = file_info.key?('preview')
-            # TODO: get change time and compare, useful ?
+            # TODO: Compare source and preview modification times when remote timestamps are available.
             gen_info[:preview_newer_than_original] = gen_info[:preview_exist]
           end
           return local_entry_preview_dir
         end
 
-        # defined by node api
+        # Build the preview folder name for a file entry using the Node API convention.
+        #
+        # @param entry [Hash] file entry containing an `id`
+        # @return [String] preview folder name for the entry
         def entry_preview_folder_name(entry)
           "#{entry['id']}#{PREVIEW_FOLDER_SUFFIX}"
         end
 
-        # Generate a file name based on basename and format (extension)
+        # Build a preview filename from a basename and target format.
+        #
+        # @param preview_format [String, Symbol] preview format used as filename extension
+        # @param base_name [String, nil] basename to use before the extension
+        # @return [String] preview filename
         def preview_filename(preview_format, base_name = nil)
           base_name ||= PREVIEW_BASENAME
           return "#{base_name}.#{preview_format}"
         end
 
-        # generate preview files for one folder entry (file) if necessary
-        # entry must contain "parent_file_id" if remote.
+        # Generate all required previews for a single file entry when regeneration is needed.
+        #
+        # Remote entries must include `parent_file_id`.
+        #
+        # @param entry [Hash] local or remote file entry to preview
+        # @return [void]
         def generate_preview(entry)
           # prepare generic information
           gen_infos = @preview_formats_to_generate.map do |preview_format|
@@ -280,7 +309,7 @@ module Aspera
             end
             begin
               # need generator for further checks
-              gen_info[:generator] = Aspera::Preview::Generator.new(gen_info[:src], gen_info[:dst], @gen_options, @tmp_folder, entry['content_type'])
+              gen_info[:generator] = Aspera::Preview::Generator.new(gen_info[:src], gen_info[:dst], @gen_options, @tmp_folder, mime: entry['content_type'])
             rescue
               # no conversion supported
               next false
@@ -300,7 +329,12 @@ module Aspera
           end
           Log.log.debug{"source: #{entry['id']}: #{entry['path']}"}
           gen_infos.each do |gen_info|
-            gen_info[:generator].generate rescue nil
+            gen_info[:generator].generate
+          rescue => e
+            Log.log.error{"Ignoring: #{e.class} #{e.message}"}
+            Log.log.debug(e.backtrace.join("\n").red)
+            # in case of any error, place a standard error image
+            FileUtils.cp(gen_info[:generator].error_asset, @destination_file_path)
           end
           if @access_remote
             # upload
@@ -316,8 +350,9 @@ module Aspera
           Log.log.debug(e.backtrace.join("\n").red)
         end
 
-        # scan all files in provided folder entry
-        # @param top_path subpath to start folder scan inside
+        # Scan all files in provided folder entry
+        # @param top_entry [Hash] the top entry to scan
+        # @param top_path  [String, nil] subpath to start folder scan inside
         def scan_folder_files(top_entry, top_path = nil)
           unless top_path.nil?
             # canonical path: start with / and ends with /
@@ -353,7 +388,7 @@ module Aspera
                 else
                   Log.log.debug{"#{entry['path']} folder".green}
                   # get folder content
-                  folder_entries = get_folder_entries(entry['id'])
+                  folder_entries = @api_node.read_folder_content(entry['id'])
                   # process all items in current folder
                   folder_entries.each do |folder_entry|
                     # add path for older versions of ES
@@ -376,37 +411,35 @@ module Aspera
         def execute_action
           command = options.get_next_command(ACTIONS)
           unless %i[check test show].include?(command)
-            # this will use node api
+            # This will use node api
             @api_node = Api::Node.new(**basic_auth_params)
             @transfer_server_address = URI.parse(@api_node.base_url).host
-            # get current access key
+            # Get current access key information
             @access_key_self = @api_node.read('access_keys/self')
             # TODO: check events is activated here:
             # note that docroot is good to look at as well
             node_info = @api_node.read('info')
             Log.log.debug{"root: #{node_info['docroot']}"}
-            @access_remote = @option_file_access.eql?(:remote)
+            # Default storage url to local file if not provided
+            option_root_url = options.get_option(:root_url, mandatory: true)
+            option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.empty? && @access_key_self['storage']['type'].eql?('local')
+            @access_remote = !UriReader.file?(option_root_url)
             Log.log.debug{"remote: #{@access_remote}"}
-            Log.log.debug{"access key info: #{@access_key_self}"}
-            # TODO: can the previews folder parameter be read from node api ?
+            # TODO: can the `previews` folder parameter be read from Node API ?
             @option_skip_folders.push("/#{@option_previews_folder}")
             if @access_remote
               # NOTE: the filter "name", it's why we take the first one
-              @previews_folder_entry = get_folder_entries(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
+              @previews_folder_entry = @api_node.read_folder_content(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
               raise Cli::Error, "Folder #{@option_previews_folder} does not exist on node. " \
                 'Please create it in the storage root, or specify an alternate name.' if @previews_folder_entry.nil?
             else
-              Aspera.assert(@access_key_self['storage']['type'].eql?('local')){'only local storage allowed in this mode'}
-              @local_storage_root = @access_key_self['storage']['path']
-              # TODO: option to override @local_storage_root='xxx'
-              @local_storage_root = @local_storage_root[PVCL_LOCAL_STORAGE.length..-1] if @local_storage_root.start_with?(PVCL_LOCAL_STORAGE)
-              # TODO: windows could have "C:" ?
+              @local_storage_root = UriReader.file_path(option_root_url)
+              # TODO: Windows could have "C:" ?
               Aspera.assert(@local_storage_root.start_with?('/')){"not local storage: #{@local_storage_root}"}
               Aspera.assert(File.directory?(@local_storage_root), type: Cli::Error){"Local storage root folder #{@local_storage_root} does not exist."}
               @local_preview_folder = File.join(@local_storage_root, @option_previews_folder)
-              raise Cli::Error, "Folder #{@local_preview_folder} does not exist locally. " \
-                'Please create it, or specify an alternate name.' unless File.directory?(@local_preview_folder)
-              # protection to avoid clash of file id for two different access keys
+              Aspera.assert(File.directory?(@local_preview_folder), type: Cli::Error){"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name."}
+              # Protection to avoid clash of file id for two different access keys
               marker_file = File.join(@local_preview_folder, AK_MARKER_FILE)
               Log.log.debug{"marker file: #{marker_file}"}
               if File.exist?(marker_file)
@@ -459,18 +492,21 @@ module Aspera
             return Main.result_status("#{command} finished")
           when :check
             return Main.result_status('Tools validated')
-          when :test, :show
+          when :test
             source = options.get_next_argument('source file')
             format = options.get_next_argument('format', accept_list: Aspera::Preview::Generator::PREVIEW_FORMATS, default: :png)
             generated_file_path = preview_filename(format, options.get_option(:base))
-            g = Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder, nil)
-            g.generate
-            if command.eql?(:show)
-              terminal_options = (options.get_option(:query) || {}).symbolize_keys
-              Log.log.debug{"preview: #{generated_file_path}"}
-              formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
-            end
+            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
             return Main.result_status("generated: #{generated_file_path}")
+          when :show
+            source = options.get_next_argument('source file')
+            # terminal_options = options.get_next_argument('options', validation: Hash, default: {}).symbolize_keys
+            generated_file_path = preview_filename(:png, options.get_option(:base))
+            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
+            formatter.display_status("generated: #{generated_file_path}")
+            # formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
+            # return Main.result_status("generated: #{generated_file_path}")
+            return Main.result_image(UriReader.file_url(generated_file_path))
           else Aspera.error_unexpected_value(command)
           end
         ensure

data/lib/aspera/cli/plugins/server.rb

@@ -86,21 +86,13 @@ module Aspera
 
         def initialize(**_)
           super
-          @ssh_opts = {}
           @connection_type = :ssh
           options.declare(:ssh_keys, 'SSH key path list', allowed: Allowed::TYPES_STRING_ARRAY)
           options.declare(:passphrase, 'SSH private key passphrase')
-          options.declare(:ssh_options, 'SSH options', allowed: Hash, handler: {o: self, m: :option_ssh_opts})
+          options.declare(:ssh_options, 'SSH options', allowed: Hash, default: {})
           SyncActions.declare_options(options)
           options.parse_options!
-        end
-
-        def option_ssh_opts; @ssh_opts; end
-
-        # multiple option are merged
-        def option_ssh_opts=(value)
-          Aspera.assert_type(value, Hash)
-          @ssh_opts.deep_merge!(value.compact.symbolize_keys)
+          @ssh_opts = options.get_option(:ssh_options).symbolize_keys
         end
 
         # Read command line options

data/lib/aspera/cli/plugins/shares.rb

@@ -135,9 +135,9 @@ module Aspera
             when :node
               return entity_execute(api: api_shares_admin, entity: 'data/nodes')
             when :share
-              share_command = options.get_next_command(%i[user_permissions group_permissions].concat(ALL_OPS))
+              share_command = options.get_next_command(%i[user_permissions group_permissions].concat(Operations::ALL))
               case share_command
-              when *ALL_OPS
+              when *Operations::ALL
                 return entity_execute(
                   api:            api_shares_admin,
                   entity:         'data/shares',
@@ -146,7 +146,7 @@ module Aspera
                   &lookup_share
                 )
               when :user_permissions, :group_permissions
-                share_id = instance_identifier(&lookup_share)
+                share_id = options.instance_identifier(&lookup_share)
                 return entity_execute(api: api_shares_admin, entity: "data/shares/#{share_id}/#{share_command}")
               end
             when :transfer_settings
@@ -181,9 +181,9 @@ module Aspera
               entity_verb = options.get_next_command(entity_commands)
               lookup_block = ->(field, value){RestList.lookup_entity_generic(entity: entity_type, field: field, value: value){api_shares_admin.read(entities_path)}['id']}
               case entity_verb
-              when *ALL_OPS # list, show, delete, create, modify
+              when *Operations::ALL
                 display_fields = entity_type.eql?(:user) ? %w[id user_id username first_name last_name email] : nil
-                display_fields.push(:directory_user) if entity_type.eql?(:user) && entities_location.eql?(:all)
+                display_fields.push('directory_user') if entity_type.eql?(:user) && entities_location.eql?(:all)
                 return entity_execute(
                   api:            api_shares_admin,
                   entity:         entities_path,
@@ -192,7 +192,7 @@ module Aspera
                   &lookup_block
                 )
               when *USR_GRP_SETTINGS # transfer_settings, app_authorizations, share_permissions
-                group_id = instance_identifier(&lookup_block)
+                group_id = options.instance_identifier(&lookup_block)
                 entities_path = "#{entities_path}/#{group_id}/#{entity_verb}"
                 return entity_execute(api: api_shares_admin, entity: entities_path, is_singleton: !entity_verb.eql?(:share_permissions), &lookup_share)
               when :import # saml
@@ -210,7 +210,7 @@ module Aspera
                   api_shares_admin.create(entities_path, {entity_type=>entity_name})
                 end
               when :users # group
-                return entity_execute(api: api_shares_admin, entity: "#{entities_path}/#{instance_identifier(&lookup_block)}/#{entities_prefix}users")
+                return entity_execute(api: api_shares_admin, entity: "#{entities_path}/#{options.instance_identifier(&lookup_block)}/#{entities_prefix}users")
               else Aspera.error_unexpected_value(entity_verb)
               end
             end

data/lib/aspera/cli/version.rb

@@ -4,6 +4,6 @@ module Aspera
   module Cli
     # For beta add extension : .beta1
     # For dev version add extension : .pre
-    VERSION = '4.25.6'
+    VERSION = '4.26.0'
   end
 end

data/lib/aspera/dot_container.rb

@@ -61,6 +61,7 @@ module Aspera
     def to_dotted
       result = {}
       until @stack.empty?
+        # path: Array, current: Array or Hash or other
         path, current = @stack.pop
         to_insert = nil
         # empty things are left intact
@@ -78,8 +79,11 @@ module Aspera
             elsif current.all?{ |i| i.is_a?(Hash) && i.keys == ['name']}
               to_insert = current.map{ |i| i['name']}
             # Array of Hashes with only 'name' and 'value' keys -> Hash of key/values
-            elsif current.all?{ |i| i.is_a?(Hash) && i.keys.sort == %w[name value]}
-              add_elements(path, current.to_h{ |i| [i['name'], i['value']]})
+            elsif current.all?{ |i| i.is_a?(Hash) && i.key?('name') && i.key?('value') && i.length <= 3}
+              # if there is an extra key, other than 'name' and 'value', insert that key as is
+              add_elements(path, current.flat_map{ |h| h.except('name', 'value').to_a})
+              # Insert name/value pairs as Hash
+              add_elements(path, current.to_h{ |h| h.values_at('name', 'value')})
             else
               add_elements(path, current.each_with_index.map{ |v, i| [i, v]})
             end
@@ -97,7 +101,7 @@ module Aspera
     # Add elements of enumerator to the @stack, in reverse order
     def add_elements(path, enum)
       enum.reverse_each do |key, value|
-        @stack.push([path + [key], value])
+        @stack.push([path + [key.to_s], value])
       end
       nil
     end

data/lib/aspera/environment.rb

@@ -91,9 +91,9 @@ module Aspera
       #
       # @param cmd [Array<#to_s>] The executable and its arguments.
       # @param mode [:execute, :background, :capture] The execution strategy:
-      #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`.
+      #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`. (Default)
       #   - `:background` Uses {Process.spawn}. Returns the spawned process PID.
-      #   - `:capture`    Uses {Open3.capture3}. Returns captured output and status.
+      #   - `:capture`    Uses {Open3.capture3}. Returns captured out, err, and status.
       #
       # @param kwargs [Hash] Additional options forwarded to the underlying call.
       #
@@ -316,6 +316,7 @@ module Aspera
 
     # Replacement character for illegal filename characters
     # Can also be used as safe "join" character
+    # @return [String] One character
     def safe_filename_character
       return REPLACE_CHARACTER if @file_illegal_characters.nil? || @file_illegal_characters.empty?
       @file_illegal_characters[0]

data/lib/aspera/log.rb

@@ -95,7 +95,7 @@ module Aspera
             PP.pp(object, +'')
           else error_unexpected_value(instance.dump_format){'dump format'}
           end
-        "#{name.to_s.green} (#{instance.dump_format})=\n#{dump_text}"
+        "#{name.to_s.green}(#{instance.dump_format})#{object.class}=\n#{dump_text}"
       end
 
       # Capture the output of $stderr and log it at debug level

data/lib/aspera/preview/file_types.rb

@@ -14,7 +14,7 @@ module Aspera
       # values for conversion_type : input format
       CONVERSION_TYPES = %i[image office pdf plaintext video].freeze
 
-      # special cases for mime types
+      # Special cases for MIME types
       # spellchecker:disable
       SUPPORTED_MIME_TYPES = {
         'application/json'                   => :plaintext,