aspera-cli 4.27.5 → 4.28.0

data/lib/aspera/servlet_helpers.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'openssl'
+require 'uri'
+require 'webrick'
+require 'aspera/mime'
+require 'aspera/web_server_simple'
+
+module Aspera
+  # Mixin for WEBrick servlets of local web servers: JSON responses, and check of requests that a web page could send.
+  #
+  # A web page open in the browser of the user can send requests to a server that the browser reaches, also on localhost:
+  # - Cross-site request forgery: a form, or a `fetch` with a CORS-safelisted `Content-Type` (`text/plain`, form), is sent cross-origin without preflight.
+  # - DNS rebinding: a host name of the attacker that resolves to `127.0.0.1` makes the page same-origin with the server, so it also reads responses.
+  module ServletHelpers
+    class << self
+      # @param url [String] URL
+      # @return [String] Origin of the URL, as in header `Origin`, e.g. `https://example.com:8443`
+      def origin(url)
+        uri = URI.parse(url)
+        port = ":#{uri.port}" unless uri.port.eql?(uri.default_port)
+        "#{uri.scheme}://#{uri.host}#{port}".downcase
+      end
+
+      # @param host [String] Value of header `Host`, e.g. `[::1]:8080`
+      # @return [String] Host name, without port and IPv6 brackets
+      def host_name(host)
+        return host[/\A\[([^\]]*)\]/, 1].to_s if host.start_with?('[')
+        host.split(':').first.to_s
+      end
+
+      # Scheme is not compared: header `Host` has none
+      # @param origin [String] Value of header `Origin`, e.g. `http://localhost:8080`
+      # @param host   [String] Value of header `Host`, e.g. `localhost:8080`
+      # @return [Boolean] `true` if the origin is the one of the requested server
+      def same_origin?(origin, host)
+        default_port = origin.start_with?('https://') ? ':443' : ':80'
+        origin.sub(%r{\Ahttps?://}, '').delete_suffix(default_port).eql?(host.delete_suffix(default_port))
+      end
+    end
+
+    # Set a JSON response
+    # @param response [WEBrick::HTTPResponse]
+    # @param status   [Integer]     HTTP status code
+    # @param body     [Hash, Array] Body of the response
+    # @param headers  [Hash{String => String}] Other headers of the response, e.g. `Cache-Control`
+    # @return [nil]
+    def json_response(response, status, body, headers: {})
+      response.status = status
+      response['Content-Type'] = Mime::JSON
+      headers.each { |name, value| response[name] = value }
+      response.body = JSON.generate(body)
+      nil
+    end
+
+    # Set a JSON error response, in the format of OAuth 2.0 (RFC 6749 §5.2)
+    # @param response    [WEBrick::HTTPResponse]
+    # @param status      [Integer]     HTTP status code
+    # @param error       [String]      Error code or message
+    # @param description [String, nil] Details
+    # @param headers     [Hash{String => String}] Other headers of the response, e.g. `WWW-Authenticate`
+    # @return [nil]
+    def json_error(response, status, error, description = nil, headers: {})
+      body = {error: error}
+      body[:error_description] = description unless description.nil?
+      json_response(response, status, body, headers: headers)
+    end
+
+    # @param request [WEBrick::HTTPRequest]
+    # @param scheme  [String] Authentication scheme, e.g. `Basic` or `Bearer`
+    # @return [String, nil] Credentials of header `Authorization` if it has this scheme, else `nil`
+    def authorization(request, scheme)
+      request_scheme, credentials = request['Authorization'].to_s.split(' ', 2)
+      credentials.to_s if request_scheme.to_s.casecmp?(scheme)
+    end
+
+    # Check the credentials of HTTP Basic authentication, in constant time
+    # @param request  [WEBrick::HTTPRequest]
+    # @param expected [String] Expected `username:password`
+    # @return [Boolean] `true` if the request has the expected credentials
+    def basic_authorized?(request, expected)
+      OpenSSL.secure_compare(authorization(request, 'Basic').to_s.unpack1('m').to_s, expected)
+    end
+
+    # Refuse a request that a web page in a browser could send. Clients that are not browsers send no `Origin`, and the `Host` of the URL they call.
+    # - `Host`: when the server listens on loopback, a loopback name or address, or one of `allowed_hosts` (DNS rebinding)
+    # - `Origin`: when present, the origin of the server, or one of `allowed_origins` (cross-site request)
+    # - `Content-Type`: with `json`, a JSON type, which a browser sends cross-origin only after a preflight request `OPTIONS`, not answered (cross-site request)
+    # @param request         [WEBrick::HTTPRequest]
+    # @param json            [Boolean]       `true` if the body, if any, is parsed as JSON
+    # @param allowed_hosts   [Array<String>] Other values accepted in `Host`: host name, or `host:port`
+    # @param allowed_origins [Array<String>] Other values accepted in `Origin`, e.g. `https://example.com`
+    # @raise [WEBrick::HTTPStatus::Forbidden]            if `Host` or `Origin` is refused
+    # @raise [WEBrick::HTTPStatus::UnsupportedMediaType] if the body is not JSON
+    def check_request(request, json: false, allowed_hosts: [], allowed_origins: [])
+      host = request['Host']&.downcase
+      if host && WebServerSimple.loopback?(@server[:BindAddress].to_s)
+        name = ServletHelpers.host_name(host)
+        host_allowed = WebServerSimple.loopback?(name) || allowed_hosts.any? { |allowed_host| [name, host].include?(allowed_host.downcase) }
+        raise WEBrick::HTTPStatus::Forbidden, "Host is not a loopback address: #{host}" unless host_allowed
+      end
+      origin = request['Origin']&.downcase
+      origin_allowed = origin.nil? || (host && ServletHelpers.same_origin?(origin, host)) || allowed_origins.any? { |allowed_origin| allowed_origin.downcase.eql?(origin) }
+      raise WEBrick::HTTPStatus::Forbidden, "Origin is not the one of the server: #{origin}" unless origin_allowed
+      return unless json && !request.body.to_s.empty?
+      media_type = request['Content-Type'].to_s.split(';').first.to_s.strip.downcase
+      raise WEBrick::HTTPStatus::UnsupportedMediaType, "Content-Type shall be #{Mime::JSON}: #{media_type}" unless Mime.json?(media_type)
+    end
+  end
+end

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

@@ -77,8 +77,10 @@ properties:
           type: string
           x-cli-option: true
         target_rate:
-          type: string
+          type: integer
           x-cli-option: true
+          x-ts-name: target_rate_kbps
+          x-ts-convert: kbps_to_bps
         cooloff:
           type: integer
           x-cli-option: true

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

@@ -6,6 +6,7 @@ $comment: >-
   It is modified with special `x-` fields.
   x-ts-name      [Boolean,String] `true` if same name in transfer spec, else real name in transfer spec
   x-ts-convert   [String]         Name of methods to convert value from transfer spec to `conf`
+  x-unit         [String]         Time unit of the integer value (e.g. `ms`), the command line option is a DURATION
   `x-` fields are also documented in `command_line_builder.rb`
 type: object
 required:
@@ -163,14 +164,14 @@ properties:
     x-cli-switch: true
   ignore_mode:
     description:
-      Source files that have had their mode changed after the initial.
+      Source files that have had their mode changed after the initial
       transfer will not update the destination file mode.
     type: boolean
     default: false
     x-cli-option: true
     x-cli-switch: true
   ignore_remote_host_sync_name:
-    description: Do not check that the remote host being used for the current.
+    description: Do not check that the remote host being used for the current
       transfer matches the host used when the local database was created
     type: boolean
     default: false
@@ -260,10 +261,14 @@ properties:
   local_scan_interval_milliseconds:
     description:
       Enable periodic scans on the local host during a continuous sync.
-      `-1` for disabled
+      `-1` for disabled.
+      On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`.
+      A plain number is in seconds.
+      Stored in milliseconds.
     type: integer
     default: -1
     x-cli-option: --scan-interval
+    x-unit: ms
   local_scan_threads:
     description: Number of directory scanning threads on the local host.
       Value must be between 1 and 99
@@ -506,8 +511,8 @@ properties:
             description: Authenticate to the proxy with the specified password.
             type: string
           port:
-            description: Use the specified port, default is 9091 for dnat, 9092.
-              for dnats
+            description: Use the specified port.
+              Default is 9091 for dnat, 9092 for dnats.
             type: integer
           protocol:
             description: The protocol to be used.
@@ -602,10 +607,14 @@ properties:
   remote_scan_interval_milliseconds:
     description: Enable periodic scans on the remote host.
       `-1` for disabled.
+      On the command line, the value is a duration, e.g. `1h 30m`, `2s500ms`, `5:30`, `1d 02:00:00.250`.
+      A plain number is in seconds.
+      Stored in milliseconds.
     type: integer
     default: -1
     x-cli-option: --remote-scan-interval
     x-cli-special: true
+    x-unit: ms
   remote_scan_threads:
     description: Number of directory scanning threads on the remote host.
       Value must be between 1 and 99.
@@ -665,7 +674,7 @@ properties:
     x-cli-option: true
     x-cli-switch: true
   scan_dir_rename:
-    description: Enable the detection of renamed directories and files compared.
+    description: Enable the detection of renamed directories and files compared
       to the previous scan, based on matching inodes
     type: boolean
     default: false
@@ -806,6 +815,7 @@ properties:
         x-cli-short: -X
       target_rate:
         description: Transfer no faster than the specified rate (in bps).
+          A string with suffix `k`, `m` or `g` is converted to bps by `ascli` (e.g. `100m`).
         type: integer
         default: 10000000
         x-ts-name: target_rate_kbps

data/lib/aspera/sync/operations.rb

@@ -4,11 +4,13 @@
 
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
+require 'aspera/transfer/spec'
 require 'aspera/exec_spec'
 require 'aspera/command_line_converter'
 require 'aspera/command_line_builder'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/duration'
 require 'aspera/environment'
 require 'aspera/schema/registry'
 require 'json'
@@ -98,11 +100,13 @@ module Aspera
             remote = sync_info['remote']
             Aspera.assert_type(remote, Hash) { 'remote' }
             Aspera.assert_type(remote['path'], String) { 'remote path' }
+            normalize_target_rate(sync_info['transport'])
             # get transfer spec if possible, and feed back to new structure
             if block_given?
               transfer_spec = yield(direction_sym(sync_info), sync_info['local']['path'], remote['path'])
               Log.dump(:auth_ts, transfer_spec)
               transfer_spec.deep_merge!(opt_ts) unless opt_ts.nil?
+              Transfer::Spec.resolve_target_rate(transfer_spec)
               tspec_to_sync_info(transfer_spec, sync_info, CONF_SCHEMA)
               update_remote_dir(remote, 'path', transfer_spec)
             end
@@ -123,6 +127,7 @@ module Aspera
               sync_info.keys.push('instance').uniq.sort.eql?(CMDLINE_PARAMS_KEYS)
             Aspera.assert_type(sync_info['sessions'], Array)
             Aspera.assert_type(sync_info['sessions'].first, Hash)
+            sync_info['sessions'].each { |session| normalize_target_rate(session) }
             if block_given?
               sync_info['sessions'].each do |session|
                 Aspera.assert_type(session['local_dir'], String) { 'local_dir' }
@@ -130,6 +135,7 @@ module Aspera
                 transfer_spec = yield(direction_sym(session), session['local_dir'], session['remote_dir'])
                 Log.dump(:auth_ts, transfer_spec)
                 transfer_spec.deep_merge!(opt_ts) unless opt_ts.nil?
+                Transfer::Spec.resolve_target_rate(transfer_spec)
                 tspec_to_sync_info(transfer_spec, session, ARGS_SESSION_SCHEMA)
                 session['private_key_paths'] = Ascp::Installation.instance.aspera_token_ssh_key_paths(:rsa) if transfer_spec.key?('token')
                 update_remote_dir(session, 'remote_dir', transfer_spec)
@@ -257,6 +263,12 @@ module Aspera
 
         # private
 
+        # Convert `target_rate` given as a string with optional suffix (e.g. `100m`) into integer bps
+        # @param params [Hash, nil] `transport` (`conf` format) or session (`args` format), modified in place
+        def normalize_target_rate(params)
+          params['target_rate'] = Transfer::Spec.rate_string_to_bps(params['target_rate']) if params.is_a?(Hash) && params['target_rate'].is_a?(String)
+        end
+
         # Transfer specification to synchronization information
         # tag `x-ts-name` in schema is used to map transfer spec parameters to async `sync_info`
         # @param transfer_spec [Hash] transfer specification
@@ -330,7 +342,15 @@ module Aspera
               current[key] ||= {}
               current = current[key]
             end
-            current[last_key] = props['x-cli-switch'] ? true : args.shift
+            current[last_key] =
+              if props['x-cli-switch']
+                # a special switch sets the non-default enum value, e.g. `--continuous` sets `mode` to `continuous`
+                props.key?('enum') ? (props['enum'] - [props['default']]).first : true
+              elsif props.key?('x-unit')
+                Duration.to_unit(args.shift, props['x-unit'])
+              else
+                args.shift
+              end
           end
           return result
         end

data/lib/aspera/temp_file_manager.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'aspera/assert'
+require 'aspera/log'
 require 'singleton'
 require 'fileutils'
 require 'etc'
@@ -15,21 +17,34 @@ module Aspera
   class TempFileManager
     include Singleton
 
-    SEC_IN_DAY = 86_400
-    # assume no transfer last longer than this
-    # (garbage collect file list which were not deleted after transfer)
-    FILE_LIST_AGE_MAX_SEC = SEC_IN_DAY * 5
-    private_constant :SEC_IN_DAY, :FILE_LIST_AGE_MAX_SEC
+    # Assume no transfer lasts longer than this
+    # (garbage collect file lists which were not deleted after transfer)
+    EXPIRY_DEFAULT_SEC = 5 * 86_400
+    private_constant :EXPIRY_DEFAULT_SEC
 
+    # @return [Boolean] `true`: files created by this execution are deleted by `cleanup`
     attr_accessor :cleanup_on_exit
+    # @return [Numeric, nil] Age in seconds of files deleted by `cleanup_expired`, `nil`: never deleted
+    attr_reader :expiry_sec
     attr_reader :global_temp
 
     def initialize
       @created_files = []
+      # Number of holders of a created file: not deleted by cleanup while held
+      @hold_counts = {}
+      # Files are created and released by transfer threads
+      @mutex = Mutex.new
       @cleanup_on_exit = true
+      @expiry_sec = EXPIRY_DEFAULT_SEC
       @global_temp = Etc.systmpdir
     end
 
+    # @param value [Numeric, nil] Age in seconds, `0`: all files, `nil`: never delete
+    def expiry_sec=(value)
+      Aspera.assert(value.nil? || (value.is_a?(Numeric) && !value.negative?), type: ParameterError) { "Expiry must be a positive duration: #{value}" }
+      @expiry_sec = value
+    end
+
     def global_temp=(value)
       @global_temp = case value
       when '@env' then Dir.tmpdir
@@ -39,17 +54,45 @@ module Aspera
     end
 
     def delete_file(filepath)
-      File.delete(filepath) if @cleanup_on_exit
-    rescue => e
-      Log.log.warn { "Problem deleting file: #{filepath}: #{e.message}" }
+      remove_file(filepath) if @cleanup_on_exit
     end
 
-    # Call this on process exit
+    # Call this on process exit, or at the end of a command.
+    # Held files are kept: they are deleted when released.
     def cleanup
-      @created_files.each do |filepath|
-        delete_file(filepath) if File.file?(filepath)
+      @mutex.synchronize do
+        @created_files.each do |filepath|
+          delete_file(filepath) if !@hold_counts.key?(filepath) && File.file?(filepath)
+        end
+        @created_files.select! { |filepath| @hold_counts.key?(filepath) }
+      end
+    end
+
+    # Keep created files after `cleanup`, until released, for example a file list used by a transfer
+    # that ends after the command (asynchronous transfer).
+    # A file can be held several times (multi-session): it is deleted when the last holder releases it.
+    # @param paths [Array<String>] Files created by this manager (others are ignored)
+    def hold(paths)
+      @mutex.synchronize do
+        paths.each do |filepath|
+          @hold_counts[filepath] = @hold_counts.fetch(filepath, 0) + 1 if @created_files.include?(filepath)
+        end
+      end
+    end
+
+    # Release files held with `hold`, and delete those that are no longer held.
+    # @param paths [Array<String>] Files given to `hold`
+    def release(paths)
+      @mutex.synchronize do
+        paths.each do |filepath|
+          next unless @hold_counts.key?(filepath)
+          @hold_counts[filepath] -= 1
+          next if @hold_counts[filepath].positive?
+          @hold_counts.delete(filepath)
+          @created_files.delete(filepath)
+          delete_file(filepath) if File.file?(filepath)
+        end
       end
-      @created_files = []
     end
 
     # Ensure that provided folder exists, or create it, atomically create and reserve a unique file.
@@ -63,7 +106,7 @@ module Aspera
       new_file = Dir::Tmpname.create([basename, suffix ? "-#{suffix}" : ''], temp_folder) do |path|
         File.open(path, File::WRONLY | File::CREAT | File::EXCL, 0o600) { nil }
       end
-      @created_files.push(new_file)
+      @mutex.synchronize { @created_files.push(new_file) }
       new_file
     end
 
@@ -93,17 +136,33 @@ module Aspera
       File.join(@global_temp, dir_name)
     end
 
-    # Garbage collect undeleted files
+    # Garbage collect files not deleted by previous executions (e.g. killed), older than `expiry_sec`.
+    # Not disabled by `cleanup_on_exit`, which applies to files of this execution.
+    # @param temp_folder [String] Folder that contains only temporary files
     def cleanup_expired(temp_folder)
-      Dir.entries(temp_folder).each do |name|
+      return if @expiry_sec.nil?
+      now = Time.now
+      Dir.children(temp_folder).each do |name|
         file_path = File.join(temp_folder, name)
-        age_sec = (Time.now - File.stat(file_path).mtime).to_i
         # check age of file, delete too old
-        if File.file?(file_path) && (age_sec > FILE_LIST_AGE_MAX_SEC)
-          Log.log.debug { "garbage collecting #{name}" }
-          delete_file(file_path)
-        end
+        next unless File.file?(file_path) && (now - File.mtime(file_path)) >= @expiry_sec
+        Log.log.debug { "garbage collecting #{name}" }
+        remove_file(file_path)
+      rescue Errno::ENOENT
+        # deleted meanwhile by another execution
+        nil
       end
     end
+
+    private
+
+    # Delete a file, a failure is logged
+    def remove_file(filepath)
+      File.delete(filepath)
+    rescue Errno::ENOENT
+      nil
+    rescue => e
+      Log.log.warn { "Problem deleting file: #{filepath}: #{e.message}" }
+    end
   end
 end

data/lib/aspera/transfer/parameters.rb

@@ -80,6 +80,8 @@ module Aspera
         Aspera.assert_values(@client_ssh_key, Ascp::Installation::CLIENT_SSH_KEY_OPTIONS)
         @check_ignore_cb = check_ignore_cb
         @builder = CommandLineBuilder.new(@job_spec, Spec::SCHEMA, CommandLineConverter)
+        # temporary files used by `ascp`: given to the agent in the ExecSpec
+        @temp_files = []
       end
 
       # Place source files on command line or in a temp file list, controlled by @file_list and file_list_folder
@@ -112,6 +114,7 @@ module Aspera
               lines = ts_paths_array.map { |i| i['source'] }
             end
             file_list_file = TempFileManager.instance.new_file_path_in_folder(self.class.file_list_folder)
+            @temp_files.push(file_list_file)
             Log.dump(:file_list, lines)
             File.write(file_list_file, lines.join("\n"), encoding: 'UTF-8')
             Log.log.debug { "#{file_list_option}=\n#{File.read(file_list_file)}".red }
@@ -137,6 +140,7 @@ module Aspera
           # ignore cert for wss ?
           if @check_ignore_cb&.call(@job_spec['remote_host'], @job_spec['wss_port'])
             wss_cert_file = TempFileManager.instance.new_file_path_global('wss_cert')
+            @temp_files.push(wss_cert_file)
             wss_url = "https://#{@job_spec['remote_host']}:#{@job_spec['wss_port']}"
             File.write(wss_cert_file, Rest.remote_certificate_chain(wss_url))
             # place in front, as more priority
@@ -213,6 +217,7 @@ module Aspera
         end
         # disable redis in client, only for ascp, this makes ascp4 fail
         exec_spec.env['ASPERA_TEST_REDIS_DISABLE'] = 'true' if exec_spec.exec.eql?(:ascp)
+        exec_spec.temp_files.concat(@temp_files)
         Log.log.debug { "ascp args: #{exec_spec}" }
         return exec_spec
       end

data/lib/aspera/transfer/spec.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/agent/factory'
 require 'aspera/command_line_builder'
 require 'aspera/assert'
 
@@ -27,6 +28,8 @@ module Aspera
       TAG_RESERVED = 'aspera'
       # Specific fields to not display
       SPECIFIC = %w{token paths direction source_root destination_root}.freeze
+      # Value of agent for documentation with one column per agent
+      DOC_OVERVIEW = :overview
       class << self
         # wrong def in transferd
         POLICY_FIX = {
@@ -35,13 +38,13 @@ module Aspera
           'sparse_csum' => 'sparse_checksum',
           'full_csum'   => 'full_checksum'
         }
-        # Multipliers for target_rate suffix (result is in kbps)
-        RATE_SUFFIX_KBPS = {
-          'k' => 1,
-          'm' => 1_000,
-          'g' => 1_000_000
+        # Multipliers for rate suffix (result is in bps)
+        RATE_SUFFIX_BPS = {
+          'k' => 1_000,
+          'm' => 1_000_000,
+          'g' => 1_000_000_000
         }.freeze
-        private_constant :POLICY_FIX, :RATE_SUFFIX_KBPS
+        private_constant :POLICY_FIX, :RATE_SUFFIX_BPS
         # translate upload/download to send/receive
         def transfer_type_to_direction(transfer_type)
           XFER_TYPE_TO_DIR.fetch(transfer_type)
@@ -52,21 +55,58 @@ module Aspera
           XFER_DIR_TO_TYPE.fetch(direction)
         end
 
-        # Parse a human-readable rate string (as accepted by ascp -l) into an integer kbps value.
-        # Accepted: plain integer (kbps), or integer + suffix k/K (kbps), m/M (x1000 kbps), g/G (x1000000 kbps).
-        # @param value [String] e.g. "100m", "500000", "1g"
-        # @return [Integer] value in kbps
-        def rate_string_to_kbps(value)
+        # Parse a human-readable rate (as accepted by async -l) into an integer bps value.
+        # Accepted: plain integer (bps), or integer + suffix k/K (x1000), m/M (x1000000), g/G (x1000000000).
+        # @param value [String, Integer] e.g. "100m", "500000", "1g", 500000
+        # @return [Integer] value in bps
+        def rate_string_to_bps(value)
           m = value.to_s.strip.match(/\A(\d+)([kKmMgG])?\z/)
           Aspera.assert(m) { "Invalid rate value: #{value.inspect}. Expected integer with optional suffix k/K, m/M or g/G." }
-          multiplier = m[2] ? RATE_SUFFIX_KBPS.fetch(m[2].downcase) : 1
+          multiplier = m[2] ? RATE_SUFFIX_BPS.fetch(m[2].downcase) : 1
           return m[1].to_i * multiplier
         end
 
+        # Resolve pseudo-parameter `target_rate` (bps) into `target_rate_kbps` (rounded down), overriding it if both are present.
+        # @param transfer_spec [Hash] Transfer spec, modified in place
+        def resolve_target_rate(transfer_spec)
+          return unless transfer_spec.key?('target_rate')
+          rate = transfer_spec.delete('target_rate')
+          transfer_spec['target_rate_kbps'] = rate_string_to_bps(rate) / 1000 unless rate.nil?
+        end
+
         def fix_transferd_resume_policy(transfer_spec)
           # Fix discrepancy in transfer spec
           transfer_spec['resume_policy'] = POLICY_FIX[transfer_spec['resume_policy']] if transfer_spec.key?('resume_policy')
         end
+
+        # Options of `Schema::Documentation` for the transfer spec: supported agents and `ascp` options
+        # @param agent [Symbol, nil] `nil`: all parameters, name of agent: parameters it supports, `DOC_OVERVIEW`: one column per agent
+        # @return [Hash] Keyword arguments of `Schema::Documentation.new`
+        def doc_options(agent = nil)
+          return {annotate: ->(node, formatter) { doc_lines(node, formatter, agent: agent) }} unless agent.eql?(DOC_OVERVIEW)
+          {
+            annotate:      ->(node, formatter) { doc_lines(node, formatter, agents_line: false) },
+            extra_columns: Agent::Factory::ALL.sort_by { |_, names| names[:short] }.to_h do |sym, names|
+              [names[:short].to_s, ->(node, formatter) { formatter.tick(CommandLineBuilder.supported_by_agent(sym, node)) }]
+            end
+          }
+        end
+
+        private
+
+        # Documentation of supported agents and command line option of a parameter: `annotate` of `Schema::Documentation`
+        # @param node        [Hash]               Schema of the parameter
+        # @param formatter   [FormatterInterface] Formatter of the documentation
+        # @param agent       [Symbol, nil]        Show only parameters supported by this agent, or all if `nil`
+        # @param agents_line [Boolean]            `true`: add a line with supported agents, if not all
+        # @return [Array<String>, nil] Lines added to the description, `nil` to hide the parameter
+        def doc_lines(node, formatter, agent: nil, agents_line: true)
+          agents = Agent::Factory::ALL.keys.select { |sym| CommandLineBuilder.supported_by_agent(sym, node) }
+          return if agents.empty? || (agent && !agents.include?(agent))
+          lines = []
+          lines.push("(#{agents.map { |i| Agent::Factory::ALL[i][:short].to_s.upcase }.sort.join(', ')})") if agents_line && !agents.length.eql?(Agent::Factory::ALL.length)
+          lines.concat(CommandLineBuilder.doc_lines(node, formatter))
+        end
       end
       SCHEMA = CommandLineBuilder.read_schema(Schema::Registry::TRANSFER_SPEC, ascp: true)
       # Define constants for enums of parameters: <parameter>_<enum>, e.g. CIPHER_AES_128, DIRECTION_SEND, ...

data/lib/aspera/transfer/spec.schema.yaml

@@ -757,11 +757,14 @@ properties:
     x-cli-option: -l
   target_rate:
     description: >-
-      Pseudo-parameter: desired transfer rate as a human-readable string with an optional unit suffix.
-      Converted to `target_rate_kbps` before the transfer is started, overriding it if both are present.
-      Accepted formats: plain integer (kbps), or integer followed by `k`/`K` (kbps), `m`/`M` (x1000 kbps), `g`/`G` (x1000000 kbps).
-      Examples: `100000`, `100000k`, `100m`, `1g`.
-    type: string
+      Pseudo-parameter: desired transfer rate in bps, with an optional unit suffix.
+      Converted to `target_rate_kbps` (rounded down) before the transfer is started, overriding it if both are present.
+      Also applies to `async` (sync).
+      Accepted formats: integer (bps), or integer followed by `k`/`K` (x1000), `m`/`M` (x1000000), `g`/`G` (x1000000000).
+      Examples: `100000000`, `100000k`, `100m`, `1g`.
+    type:
+      - string
+      - integer
     x-cli-special: true
   title:
     description: Title of the transfer.

data/lib/aspera/web_auth/index.html.erb

@@ -0,0 +1,16 @@
+<%# Content of the page displayed after authentication, in layout of Aspera::WebPage %>
+        <div class="icon-circle ok">
+            <svg xmlns="http://www.w3.org/2000/svg" width="30" height="30" viewBox="0 0 32 32" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round">
+                <polyline points="6 16 13 23 26 9"/>
+            </svg>
+        </div>
+
+        <h1>Authentication Successful</h1>
+        <p>You can close this window and return to your terminal.</p>
+
+<% unless additional_info.to_s.empty? %>
+        <div class="info-box">
+            <%= h additional_info %>
+        </div>
+<% end %>
+