aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/schema/registry.rb

@@ -7,6 +7,9 @@ require 'aspera/schema/reader'
 module Aspera
   # base class for plugins modules
   module Schema
+    # @!method self.instance
+    #   Returns the singleton instance of Registry
+    #   @return [Registry] the singleton instance
     class Registry
       include Singleton
 
@@ -15,18 +18,32 @@ module Aspera
           LOCATIONS.key?(sym)
         end
 
+        # Get path to request body schema, no check if it exists
+        # @param component [String] registry key (e.g. 'faspex', 'aoc')
+        # @param endpoint  [String] endpoint path without leading slash (e.g. 'packages.post')
+        # @return [String] schema path usable in schema: keyword
         def req_body(component, endpoint)
           "#{component}:paths./#{endpoint}.requestBody.content.application/json.schema"
         end
+
+        # Get path to query parameters for a GET endpoint
+        # @param component [String] registry key (e.g. 'faspex', 'aoc')
+        # @param endpoint  [String] resource path without leading slash (e.g. 'packages')
+        # @param method    [String] HTTP method (default: 'get')
+        # @return [String] schema path usable in query_schema: keyword
+        def query_params(component, endpoint, method: 'get')
+          "#{component}:paths./#{endpoint}.#{method}#{QUERY_PARAMS_SUFFIX}"
+        end
       end
 
       LOCATIONS = {
-        spec:   'aspera/transfer/spec.schema.yaml',
-        args:   'aspera/sync/args.schema.yaml',
-        conf:   'aspera/sync/conf.schema.yaml',
-        opts:   'aspera/cli/options.schema.yaml',
-        aoc:    'aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml',
-        faspex: 'aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml'
+        spec:         'aspera/transfer/spec.schema.yaml',
+        args:         'aspera/sync/args.schema.yaml',
+        conf:         'aspera/sync/conf.schema.yaml',
+        opts:         'aspera/cli/options.schema.yaml',
+        aoc:          'aspera/schema/IBM Aspera on Cloud API-0.2.6-enhanced.yaml',
+        faspex:       'aspera/schema/IBM Aspera Faspex API-5.0-enhanced.yaml',
+        async_tables: 'aspera/schema/async_tables.yaml'
       }
 
       OPTIONS = 'opts'
@@ -35,18 +52,35 @@ module Aspera
       SYNC_ARGS = 'args'
       AOC = 'aoc'
       FASPEX = 'faspex'
-      TRANSFER_INFO = "#{OPTIONS}:components.schemas.TransferInfo"
+      ASYNC_TABLES = 'async_tables'
+      LOG_OPTIONS             = "#{OPTIONS}:components.schemas.LogOptions"
+      DIRECT_AGENT_OPTIONS    = "#{OPTIONS}:components.schemas.DirectAgentOptions"
+      NODE_AGENT_OPTIONS      = "#{OPTIONS}:components.schemas.NodeAgentOptions"
+      HTTPGW_AGENT_OPTIONS    = "#{OPTIONS}:components.schemas.HttpgwAgentOptions"
+      TRANSFERD_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferdAgentOptions"
+      TRANSFER_AGENT_OPTIONS  = "#{OPTIONS}:components.schemas.TransferAgentOptions"
+      SMTP_OPTIONS            = "#{OPTIONS}:components.schemas.SmtpOptions"
+      HTTP_OPTIONS            = "#{OPTIONS}:components.schemas.HttpOptions"
+      VAULT_OPTIONS           = "#{OPTIONS}:components.schemas.VaultOptions"
+      IMAGE_OPTIONS           = "#{OPTIONS}:components.schemas.ImageOptions"
+      PACKAGE_FOLDER_OPTIONS  = "#{OPTIONS}:components.schemas.PackageFolderOptions"
 
       REQ_BODY = '.requestBody.content.application/json.schema'
+      # Suffix appended to a dotted path to signal query-param extraction in reader()
+      QUERY_PARAMS_SUFFIX = '.parameters'
 
       def initialize
         @cache = {}
         @main_folder = File.expand_path('../..', __dir__)
       end
 
-      # Read schema from file or from cache
-      # @param name_path [String] one of the keys in LOCATIONS, with optional :<path> suffix
-      # @return [Reader] schema
+      # Read schema from file or from cache.
+      # When name_path ends with QUERY_PARAMS_SUFFIX, the OAS `parameters` array at that path
+      # is synthesised into an object schema via Reader.from_query_params instead of navigating
+      # into the tree.
+      # @param name_path [String] registry key with optional colon-separated dotted path suffix,
+      #   e.g. "faspex:paths./packages.get.parameters" or "faspex:paths./packages.post.requestBody..."
+      # @return [Reader] schema reader
       def reader(name_path)
         name, path = name_path.split(':', 2)
         sym = name.to_sym
@@ -54,6 +88,12 @@ module Aspera
         spec_file = File.join(@main_folder, LOCATIONS[sym])
         @cache[sym] = Yaml.safe_load(File.read(spec_file)) if spec_file.end_with?('.yaml') && !@cache.key?(sym)
         @cache[sym] = JSON.parse(File.read(spec_file)) if spec_file.end_with?('.json') && !@cache.key?(sym)
+        # Query-params path: strip the suffix, navigate to the operation node, extract parameters
+        if path&.end_with?(QUERY_PARAMS_SUFFIX)
+          parent_path = path.delete_suffix(QUERY_PARAMS_SUFFIX)
+          node = @cache[sym].dig(*parent_path.split('.'))
+          return Reader.from_query_params(node&.fetch('parameters', []) || [])
+        end
         reader = Reader.new(@cache[sym])
         return reader unless path
         reader.dig(*path.split('.'))

data/lib/aspera/secret_hider.rb

@@ -6,6 +6,10 @@ require 'singleton'
 
 module Aspera
   # remove secret from logs and output
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of SecretHider
+  #   @return [SecretHider] the singleton instance
   class SecretHider
     include Singleton
 
@@ -41,7 +45,7 @@ module Aspera
     private_constant :HIDDEN_PASSWORD, :ASCP_ENV_SECRETS, :KEY_SECRETS, :HTTP_SECRETS, :ALL_SECRETS, :KEY_FALSE_POSITIVES, :REGEX_LOG_REPLACES
     attr_accessor :log_secrets
 
-    # @return new log formatter that hides secrets
+    # @return [Proc] new log formatter that hides secrets
     def log_formatter(original_formatter)
       original_formatter ||= Logger::Formatter.new
       # NOTE: that @log_secrets may be set AFTER this init is done, so it's done at runtime
@@ -55,11 +59,16 @@ module Aspera
       end
     end
 
+    # Replace private key content in a string with the hidden password placeholder
+    # @param value [String] Input string possibly containing a private key
+    # @return [String] String with private key replaced by placeholder
     def hide_secrets_in_string(value)
       return value.gsub(REGEX_LOG_REPLACES.first){"#{Regexp.last_match(:begin)}#{HIDDEN_PASSWORD}#{Regexp.last_match(:end)}"}
     end
 
-    # @return true if the key denotes a secret
+    # @param keyword [String, Symbol] Key name to check
+    # @param value   [String]         Associated value (must be a String to be a secret)
+    # @return [Boolean] true if the key denotes a secret
     def secret?(keyword, value)
       keyword = keyword.to_s if keyword.is_a?(Symbol)
       # only Strings can be secrets, not booleans, or hash, arrays

data/lib/aspera/ssl.rb

@@ -12,16 +12,16 @@ module Aspera
       @extra_options = OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options]
       attr_reader :extra_options
 
-      def option_list=(v)
-        Aspera.assert_type(v, Array){'ssl_options'}
-        v.each do |opt|
+      def option_list=(options)
+        Aspera.assert_type(options, Array){'ssl_options'}
+        options.each do |opt|
           Aspera.assert_type(opt, String, Integer){'Expected String or Integer in ssl_options'}
           case opt
           when Integer
             @extra_options = opt
           when String
             name = "OP_#{opt.start_with?('-') ? opt[1..] : opt}".upcase
-            raise Cli::BadArgument, "Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map{ |c| c.to_s.sub(/^OP_/, '')}.join(', ')}" if !OpenSSL::SSL.const_defined?(name)
+            Aspera.assert(OpenSSL::SSL.const_defined?(name), type: Cli::BadArgument){"Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map{ |c| c.to_s.sub(/^OP_/, '')}.join(', ')}"}
             if opt.start_with?('-')
               @extra_options &= ~OpenSSL::SSL.const_get(name)
             else

data/lib/aspera/sync/conf.schema.yaml

@@ -637,7 +637,7 @@ properties:
       Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early.
       Note that transfer resumption can only happen if the `reset` option is disabled.
       If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that
-      session will be resumeable, but only if async is then restarted with 'reset' disabled.
+      session will be resumable, but only if async is then restarted with 'reset' disabled.
     type: object
     properties:
       enabled:
@@ -654,7 +654,7 @@ properties:
           Sets the age limit in days for temporary files that will be preserved
           on cleanup (usually at async's start and stop) for potential transfer resume.
           Temp files older than the given value will be removed
-          regardless of whether they might be resumeable.
+          regardless of whether they might be resumable.
         type: integer
         default: "5"
         x-cli-option: --resume-age-days

data/lib/aspera/sync/database.rb

@@ -35,12 +35,12 @@ class SqLite3Wrapper
   end
 
   # The table contains a single row
-  def single_table(table_name)
-    execute("SELECT * FROM #{table_name} LIMIT 1").first
+  def single_table(table_name, sql_suffix = nil)
+    execute(["SELECT * FROM #{table_name}", sql_suffix, 'LIMIT 1'].compact.join(' ')).first
   end
 
-  def full_table(table_name)
-    execute("SELECT * FROM #{table_name}")
+  def full_table(table_name, sql_suffix = nil)
+    execute(["SELECT * FROM #{table_name}", sql_suffix].compact.join(' '))
   end
 
   private
@@ -68,16 +68,20 @@ module Aspera
         end
       end
 
-      def meta
-        @db.single_table('sync_snapmeta_table')
+      def meta(sql_suffix = nil)
+        @db.single_table('sync_snapmeta_table', sql_suffix)
       end
 
-      def counters
-        @db.single_table('sync_snap_counters_table')
+      def counters(sql_suffix = nil)
+        @db.single_table('sync_snap_counters_table', sql_suffix)
       end
 
-      def file_info
-        @db.full_table('sync_snapdb_table')
+      def file_info(sql_suffix = nil)
+        @db.full_table('sync_snapdb_table', sql_suffix)
+      end
+
+      def execute(sql)
+        @db.execute(sql)
       end
     end
   end

data/lib/aspera/sync/operations.rb

@@ -4,6 +4,7 @@
 
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
+require 'aspera/exec_spec'
 require 'aspera/command_line_converter'
 require 'aspera/command_line_builder'
 require 'aspera/log'
@@ -89,11 +90,8 @@ module Aspera
         def start(sync_info, opt_ts = nil)
           Log.dump(:sync_params_initial, sync_info)
           Aspera.assert_type(sync_info, Hash)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, type: Error){'At least one of `local` or `sessions` must be present in async parameters'}
-          env_args = {
-            args: [],
-            env:  {}
-          }
+          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
+          exec_spec = ExecSpec.new(exec: :async)
           if sync_info.key?('local')
             # `conf` format
             Aspera.assert_type(sync_info['local'], Hash){'local'}
@@ -115,10 +113,10 @@ module Aspera
               remote['private_key_paths'].concat(add_certificates)
             end
             # '--exclusive-mgmt-port=12345', '--arg-err-path=-',
-            env_args[:args] = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
+            exec_spec.args = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
             Log.dump(:sync_conf, sync_info)
             agent = Agent::Direct.new
-            agent.start_and_monitor_process(session: {}, name: :async, **env_args)
+            agent.start_and_monitor_process(session: {}, exec_spec: exec_spec)
           else
             # `args` format
             raise StandardError, "Only 'sessions', and optionally 'instance' keys are allowed" unless
@@ -141,16 +139,16 @@ module Aspera
               Aspera.assert_type(sync_info['instance'], Hash)
               instance_builder = CommandLineBuilder.new(sync_info['instance'], ARGS_INSTANCE_SCHEMA, CommandLineConverter)
               instance_builder.process_params
-              instance_builder.add_env_args(env_args)
+              instance_builder.add_to_exec_spec(exec_spec)
             end
             sync_info['sessions'].each do |session_params|
               Aspera.assert_type(session_params, Hash)
-              Aspera.assert(session_params.key?('name')){'session must contain at least: name'}
+              Aspera.assert(session_params.key?('name'), 'session must contain at least: name')
               session_builder = CommandLineBuilder.new(session_params, ARGS_SESSION_SCHEMA, CommandLineConverter)
               session_builder.process_params
-              session_builder.add_env_args(env_args)
+              session_builder.add_to_exec_spec(exec_spec)
             end
-            Environment.secure_execute(Ascp::Installation.instance.path(:async), *env_args[:args], env: env_args[:env])
+            Environment.secure_execute(Ascp::Installation.instance.path(:async), *exec_spec.args, env: exec_spec.env)
           end
           return
         end
@@ -177,7 +175,7 @@ module Aspera
         # @param sync_info [Hash] sync parameters in conf or args format
         # @return [Hash] parsed output of asyncadmin
         def admin_status(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, type: Error){'At least one of `local` or `sessions` must be present in async parameters'}
+          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           arguments = [ASYNC_ADMIN_EXECUTABLE, '--quiet']
           if sync_info.key?('local')
             # `conf` format
@@ -209,14 +207,14 @@ module Aspera
         # @param sync_info [Hash] sync parameters in conf or args format
         # @return [String, nil] Path to "local DB dir", i.e. folder that contains folders that contain `snap.db`
         def local_db_folder(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, type: Error){'At least one of `local` or `sessions` must be present in async parameters'}
+          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           if sync_info.key?('local')
             # `conf` format
             if sync_info.key?('local_db_dir')
               return sync_info['local_db_dir']
             elsif (local_path = sync_info.dig('local', 'path'))
               return local_path
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local.path'
             end
           else
@@ -226,15 +224,14 @@ module Aspera
               return session['local_db_dir']
             elsif session.key?('local_dir')
               return session['local_dir']
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local_dir'
             end
           end
-          nil
         end
 
         def session_name(sync_info)
-          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, type: Error){'At least one of `local` or `sessions` must be present in async parameters'}
+          Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
           if sync_info.key?('local')
             # `conf` format
             return sync_info['name']
@@ -325,7 +322,7 @@ module Aspera
               end
             end
             path, props = find_option(CONF_SCHEMA, [], option)
-            raise "Option not found: #{option}" if path.nil?
+            Aspera.assert(!path.nil?){"Option not found: #{option}"}
             last_key = path.pop
             # navigate in the current result to insert the value
             current = result

data/lib/aspera/temp_file_manager.rb

@@ -7,6 +7,10 @@ require 'etc'
 module Aspera
   # create a temp file name for a given folder
   # files can be deleted on process exit by calling cleanup
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of TempFileManager
+  #   @return [TempFileManager] the singleton instance
   class TempFileManager
     include Singleton
 
@@ -48,7 +52,7 @@ module Aspera
     end
 
     # Ensure that provided folder exists, or create it, generate a unique filename
-    # @return path to that unique file
+    # @return [String] path to that unique file
     def new_file_path_in_folder(temp_folder, prefix: nil, suffix: nil)
       FileUtils.mkdir_p(temp_folder)
       new_file = File.join(temp_folder, [prefix, SecureRandom.uuid, suffix].compact.join('-'))

data/lib/aspera/timer_limiter.rb

@@ -3,7 +3,7 @@
 module Aspera
   # trigger returns true only if the delay has passed since the last trigger
   class TimerLimiter
-    # @param delay in seconds (float)
+    # @param delay [Float] delay in seconds
     def initialize(delay)
       @delay = delay
       @last_trigger_time = nil

data/lib/aspera/transfer/faux_file.rb

@@ -11,42 +11,55 @@ module Aspera
       SIZE_UNITS = %w[k m g t p e].freeze
       private_constant :SCHEME, :PREFIX, :SIZE_UNITS
       class << self
-        # @return nil if not a faux: scheme, else a FauxFile instance
+        # Parse a faux URI and return a `FauxFile` instance, or `nil` if the URI does not use the faux scheme.
+        # URI format: `faux:///<path>?<size>`, where `<size>` is a decimal integer with an optional
+        # case-insensitive unit suffix: `k`, `m`, `g`, `t`, `p`, `e` (powers of 1024).
+        # When no suffix is given, the size is interpreted as raw bytes.
+        # Examples: `faux:///file.bin?10` (10 bytes), `faux:///file.bin?10m` (10 MiB)
+        # @param name [String] source file name, possibly a faux URI
+        # @return [FauxFile, nil] `nil` if not a faux scheme, else a `FauxFile` instance
         def create(name)
           return unless name.start_with?(PREFIX)
           name_params = name.delete_prefix(PREFIX).split('?', 2)
-          raise Error, 'Format: #{PREFIX}<file path>?<size>' unless name_params.length.eql?(2)
-          raise Error, "Format: <integer>[#{SIZE_UNITS.join(',')}]" unless (m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}])$/))
-          size = m[1].to_i
-          suffix = m[2]
-          SIZE_UNITS.each do |s|
-            size *= 1024
-            break if s.eql?(suffix)
-          end
+          Aspera.assert(name_params.length.eql?(2), type: Error){"Format: #{PREFIX}<file path>?<size>"}
+          m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}]?)$/)
+          Aspera.assert(m, type: Error){"Format: <integer>[#{SIZE_UNITS.join(',')}]"}
+          size = m[2].empty? ? m[1].to_i : m[1].to_i * (1024**(SIZE_UNITS.index(m[2]) + 1))
           return FauxFile.new(name_params[0], size)
         end
       end
+      # @return [String]  virtual file path
+      # @return [Integer] total size in bytes
       attr_reader :path, :size
 
+      # @param path [String]  virtual file path (from the faux URI)
+      # @param size [Integer] total number of bytes to produce
       def initialize(path, size)
         @path = path
         @size = size
         @offset = 0
-        # we cache large chunks, anyway most of them will be the same size
+        # cache chunks by size so repeated reads of the same chunk length reuse the same buffer
         @chunk_by_size = {}
       end
 
+      # Read up to `chunk_size` bytes from the stream and advance the internal offset.
+      # Returns `nil` when the stream is exhausted.
+      # @param chunk_size [Integer] maximum number of bytes to read
+      # @return [String, nil] null-byte string of the bytes actually read, or `nil` at EOF
       def read(chunk_size)
         return if eof?
         bytes_to_read = [chunk_size, @size - @offset].min
         @offset += bytes_to_read
-        @chunk_by_size[bytes_to_read] = "\x00" * bytes_to_read unless @chunk_by_size.key?(bytes_to_read)
+        @chunk_by_size[bytes_to_read] ||= "\x00" * bytes_to_read
         return @chunk_by_size[bytes_to_read]
       end
 
+      # No-op: required to satisfy the IO-like interface used by transfer agents.
+      # @return [nil]
       def close
       end
 
+      # @return [Boolean] true when all bytes have been read
       def eof?
         return @offset >= @size
       end

data/lib/aspera/transfer/parameters.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/exec_spec'
 require 'aspera/command_line_builder'
 require 'aspera/temp_file_manager'
 require 'aspera/transfer/error'
@@ -38,8 +39,9 @@ module Aspera
           @file_list_folder ||= TempFileManager.instance.new_file_path_global('asession_filelists')
         end
 
-        # File list is provided directly with `ascp` arguments
-        # @columns ascp_args [Array,NilClass] `ascp` arguments
+        # Check whether a file list option is already present in the `ascp` argument list
+        # @param ascp_args [Array, nil] `ascp` arguments
+        # @return [Boolean] true if a file list option is present
         def ascp_args_file_list?(ascp_args)
           ascp_args&.any?{ |i| FILE_LIST_OPTIONS.include?(i)}
         end
@@ -47,7 +49,9 @@ module Aspera
 
       # @param job_spec        [Hash]          Transfer specification
       # @param ascp_args       [Array]         Other `ascp` args
+      # @param wss             [Boolean]       `true`: if both SSH and wss in ts: prefer wss
       # @param quiet           [Boolean]       Remove `ascp` progress bar if `true`
+      # @param file_list       [Boolean]       `true`: provide source list via a temp file, `false`: place directly on command line
       # @param client_ssh_key  [:rsa,:dsa]     Type of Aspera Client SSH key to use.
       # @param trusted_certs   [Array<String>] List of path to trusted certificates stores when using WSS
       # @param check_ignore_cb [Proc]          Callback to check if WSS connection shall ignore certificate validity
@@ -56,6 +60,7 @@ module Aspera
         ascp_args:       nil,
         wss:             true,
         quiet:           true,
+        file_list:       true,
         trusted_certs:   nil,
         client_ssh_key:  nil,
         check_ignore_cb: nil
@@ -66,6 +71,7 @@ module Aspera
         Aspera.assert_array_all(@ascp_args, String){'ascp_args'}
         @wss = wss
         @quiet = quiet
+        @file_list = file_list
         @trusted_certs = trusted_certs.nil? ? [] : trusted_certs
         Aspera.assert_type(@trusted_certs, Array){'trusted_certs'}
         @client_ssh_key = client_ssh_key.nil? ? :rsa : client_ssh_key.to_sym
@@ -74,7 +80,7 @@ module Aspera
         @builder = CommandLineBuilder.new(@job_spec, Spec::SCHEMA, CommandLineConverter)
       end
 
-      # either place source files on command line, or add file list file
+      # Place source files on command line or in a temp file list, controlled by @file_list and file_list_folder
       def process_file_list
         # is the file list provided through ascp parameters?
         ascp_file_list_provided = self.class.ascp_args_file_list?(@ascp_args)
@@ -85,12 +91,12 @@ module Aspera
         file_list_option = nil
         # transfer spec contains paths ?
         if !ts_paths_array.nil?
-          Aspera.assert(!ascp_file_list_provided){'file list provided both in transfer spec and ascp file list. Remove one of them.'}
-          Aspera.assert(ts_paths_array.all?{ |i| i.key?('source')}){"All elements of paths must have a 'source' key"}
+          Aspera.assert(!ascp_file_list_provided, 'file list provided both in transfer spec and ascp file list. Remove one of them.')
+          Aspera.assert(ts_paths_array.all?{ |i| i.key?('source')}, "All elements of paths must have a 'source' key")
           is_pair_list = ts_paths_array.any?{ |i| i.key?('destination')}
-          raise "All elements of paths must be consistent with 'destination' key" if is_pair_list && !ts_paths_array.all?{ |i| i.key?('destination')}
-          if self.class.file_list_folder.nil?
-            Aspera.assert(!is_pair_list){'file pair list is not supported when file list folder is not set'}
+          Aspera.assert(!(is_pair_list && !ts_paths_array.all?{ |i| i.key?('destination')})){"All elements of paths must be consistent with 'destination' key"}
+          if !@file_list || self.class.file_list_folder.nil?
+            Aspera.assert(!is_pair_list, 'file pair list is not supported when file list folder is not set')
             # not safe for special characters ? (maybe not, depends on OS)
             Log.log.debug('placing source file list on command line (no file list file)')
             @builder.add_command_line_options(ts_paths_array.map{ |i| i['source']})
@@ -112,7 +118,7 @@ module Aspera
         @builder.add_command_line_options("#{file_list_option}=#{file_list_file}") unless file_list_option.nil?
       end
 
-      # @return the list of certificates (option `-i`) to use when token/ssh or wss are used
+      # @return [Array<String>] the list of certificates (option `-i`) to use when token/ssh or wss are used
       def remote_certificates
         certificates_to_use = []
         # use web socket secure for session ?
@@ -150,22 +156,18 @@ module Aspera
 
       # Translate transfer spec to env vars and command line arguments for `ascp`
       def ascp_args
-        env_args = {
-          args: [],
-          env:  {},
-          name: :ascp
-        }
+        exec_spec = Aspera::ExecSpec.new(exec: :ascp)
 
         # Special cases
         @job_spec.delete('source_root') if @job_spec.key?('source_root') && @job_spec['source_root'].empty?
 
         # Notify multi-session was already used, anyway it was deleted by agent direct
-        Aspera.assert(!@builder.read_param('multi_session'))
+        Aspera.assert(!@builder.read_param('multi_session'), 'multi_session already consumed, must not be set here')
 
         # Add ssh or wss certificates
         # (reverse, to keep order, as we unshift)
         remote_certificates&.reverse_each do |cert|
-          env_args[:args].unshift('-i', cert)
+          exec_spec.args.unshift('-i', cert)
         end
 
         case (delete_source = @builder.read_param('delete_source'))
@@ -183,9 +185,9 @@ module Aspera
         base64_destination = false
         # symbol must be index of Ascp::Installation.paths
         if @builder.read_param('use_ascp4')
-          env_args[:name] = :ascp4
+          exec_spec.exec = :ascp4
         else
-          env_args[:name] = :ascp
+          exec_spec.exec = :ascp
           base64_destination = true
         end
         # destination will be base64 encoded, put this before source path arguments
@@ -200,17 +202,17 @@ module Aspera
         destination_folder = Base64.strict_encode64(destination_folder) if base64_destination
         # destination MUST be last command line argument to ascp
         @builder.add_command_line_options(destination_folder)
-        @builder.add_env_args(env_args)
-        env_args[:args].unshift('-q') if @quiet
+        @builder.add_to_exec_spec(exec_spec)
+        exec_spec.args.unshift('-q') if @quiet
         # add fallback cert and key as arguments if needed
         if HTTP_FALLBACK_ACTIVATION_VALUES.include?(@job_spec['http_fallback'])
-          env_args[:args].unshift('-Y', Ascp::Installation.instance.path(:fallback_private_key))
-          env_args[:args].unshift('-I', Ascp::Installation.instance.path(:fallback_certificate))
+          exec_spec.args.unshift('-Y', Ascp::Installation.instance.path(:fallback_private_key))
+          exec_spec.args.unshift('-I', Ascp::Installation.instance.path(:fallback_certificate))
         end
         # disable redis in client, only for ascp, this makes ascp4 fail
-        env_args[:env]['ASPERA_TEST_REDIS_DISABLE'] = 'true' if env_args[:name].eql?(:ascp)
-        Log.log.debug{"ascp args: #{env_args}"}
-        return env_args
+        exec_spec.env['ASPERA_TEST_REDIS_DISABLE'] = 'true' if exec_spec.exec.eql?(:ascp)
+        Log.log.debug{"ascp args: #{exec_spec}"}
+        return exec_spec
       end
       DELETE_EQUIV = %w[remove_after_transfer remove_empty_directories remove_empty_source_directory]
       # `ascp` options to provide a file list

data/lib/aspera/transfer/result.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Aspera
+  module Transfer
+    # Typed result of a transfer operation.
+    # Replaces the ad-hoc Array polymorphism previously returned by agents.
+    #
+    # Agents return one of the three concrete sub-classes:
+    #   Transfer::Result::Success  — all sessions completed successfully
+    #   Transfer::Result::Error    — at least one session failed
+    #   Transfer::Result::Async    — transfer submitted to a daemon; not yet complete
+    class Result
+      # All sessions completed successfully.
+      class Success < Result
+        def to_s
+          'success'
+        end
+      end
+
+      # At least one session failed.
+      class Error < Result
+        # @return [StandardError]
+        attr_reader :exception
+
+        def initialize(exception)
+          super()
+          @exception = exception
+        end
+
+        def to_s
+          "error: #{@exception.message}"
+        end
+      end
+
+      # Transfer submitted to an external daemon; status not yet known.
+      class Async < Result
+        # @return [String] UUID assigned to this background job
+        attr_reader :job_id
+        # @return [String] initial status string (e.g. 'running')
+        attr_reader :status
+
+        def initialize(job_id:, status: 'running')
+          super()
+          @job_id = job_id
+          @status = status
+        end
+
+        # Convenience: export as a plain Hash for serialization / display
+        def to_h
+          {'job_id' => @job_id, 'status' => @status}
+        end
+
+        def to_s
+          "async job_id=#{@job_id} status=#{@status}"
+        end
+      end
+
+      # Factory helpers
+      class << self
+        def success
+          Success.new
+        end
+
+        def error(exception)
+          Error.new(exception)
+        end
+
+        def async(job_id:, status: 'running')
+          Async.new(job_id: job_id, status: status)
+        end
+      end
+    end
+  end
+end