aspera-cli 4.27.5 → 4.28.0

data/docs/test-mcp-with-ai.md

@@ -110,7 +110,9 @@ environment is available.
 ### 4.1 Demo server — browse files
 
 > "Browse the root folder of the Aspera demo server at ssh://demo.asperademo.com:33001
-> using username `asperaweb` and password `demoaspera`."
+> using username `asperaweb` and password `<PASSWORD>`."
+
+`<PASSWORD>` is the public password of the demo server.
 
 **Expected MCP calls**:
 
@@ -118,7 +120,7 @@ environment is available.
 ["server", "browse", "/",
  "--url=ssh://demo.asperademo.com:33001",
  "--username=asperaweb",
- "--password=demoaspera"]
+ "--password=<PASSWORD>"]
 ```
 
 **Pass criterion**: the AI returns a file/folder listing without errors.
@@ -134,7 +136,7 @@ environment is available.
 ["server", "download", "/aspera-test-dir-small/10KB.1",
  "--url=ssh://demo.asperademo.com:33001",
  "--username=asperaweb",
- "--password=demoaspera",
+ "--password=<PASSWORD>",
  "--to-folder=/tmp"]
 ```
 

data/lib/aspera/agent/direct.rb

@@ -4,6 +4,7 @@ require 'aspera/agent/base'
 require 'aspera/ascp/installation'
 require 'aspera/ascp/management'
 require 'aspera/exec_spec'
+require 'aspera/temp_file_manager'
 require 'aspera/transfer/parameters'
 require 'aspera/transfer/error'
 require 'aspera/transfer/spec'
@@ -14,6 +15,7 @@ require 'socket'
 require 'securerandom'
 require 'shellwords'
 require 'English'
+require 'time'
 require 'aspera/rainbow'
 using Rainbow
 
@@ -27,7 +29,7 @@ module Aspera
         # agent_params must contain '_agent_ref' pointing to the live Direct instance.
         # @param transfer_id  [String] job_id returned by start_transfer / last_job_id
         # @param agent_params [Hash]   connection parameters; '_agent_ref' is the live agent
-        # @return [Hash] status hash with at least 'status' key
+        # @return [Hash] status hash with at least 'status' key, and `bytes_transferred`, and `ended_at` when all sessions ended
         def transfer_status(transfer_id, agent_params)
           agent = agent_params['_agent_ref']
           return {'status' => 'unknown', 'note' => 'direct agent not available (different process?)'} if agent.nil?
@@ -35,12 +37,14 @@ module Aspera
           return {'status' => 'unknown', 'note' => "no sessions found for job #{transfer_id}"} if sessions.empty?
           errors  = sessions.filter_map { |s| s[:error] }
           running = sessions.any? { |s| s[:thread]&.alive? }
+          result = {'bytes_transferred' => sessions.sum { |s| s[:last_size].to_i }}
+          result['ended_at'] = sessions.filter_map { |s| s[:ended_at] }.max unless running
           if errors.any?
-            {'status' => 'failed', 'error' => errors.first.message}
+            result.merge('status' => 'failed', 'error' => errors.first.message)
           elsif running
-            {'status' => 'running'}
+            result.merge('status' => 'running')
           else
-            {'status' => 'completed'}
+            result.merge('status' => 'completed')
           end
         end
       end
@@ -171,6 +175,10 @@ module Aspera
           exec_spec:         Transfer::Parameters.new(transfer_spec, **@tr_opts).ascp_args
         }
 
+        # Temporary files of `ascp` (file list) are deleted when the last session ends,
+        # also after the end of the command (asynchronous transfer): hold them once per session, before any session starts
+        (multi_session_info.nil? ? 1 : multi_session_info[:count]).times { TempFileManager.instance.hold(session[:exec_spec].temp_files) }
+
         if multi_session_info.nil?
           Log.log.debug('Starting single session thread')
           # single session for transfer : simple
@@ -266,6 +274,9 @@ module Aspera
         rescue => e
           session[:error] = e
           raise if Log.log.debug? || !e.is_a?(Transfer::Error)
+        ensure
+          session[:ended_at] = Time.now.utc.iso8601
+          TempFileManager.instance.release(session[:exec_spec].temp_files)
         end
         Log.log.debug { "EXIT (#{Thread.current[:name]})" }
       end

data/lib/aspera/agent/factory.rb

@@ -26,7 +26,8 @@ module Aspera
         Dir.children(File.dirname(File.expand_path(__FILE__)))
           .select { |file| file.end_with?(Environment::RB_EXT) }
           .map { |file| File.basename(file, Environment::RB_EXT).to_sym }
-          .reject { |item| IGNORED_ITEMS.include?(item) }.to_h do |agent_sym|
+          .reject { |item| IGNORED_ITEMS.include?(item) }
+          .sort.to_h do |agent_sym|
           [agent_sym, {
             long:  agent_sym.to_s.capitalize,
             short: agent_sym.eql?(:direct) ? :a : agent_sym.to_s[0].to_sym

data/lib/aspera/agent/node.rb

@@ -6,7 +6,7 @@ require 'aspera/transfer/spec'
 require 'aspera/api/node'
 require 'aspera/log'
 require 'aspera/assert'
-require 'aspera/oauth'
+require 'aspera/oauth/client/factory'
 
 module Aspera
   module Agent

data/lib/aspera/api/cos_node.rb

@@ -62,7 +62,7 @@ module Aspera
           ret:       :resp
         ).body
         ats_info = XmlSimple.xml_in(xml_result_text, {'ForceArray' => false})
-        Log.dump(:ats_info, ats_info.reject { |k, _| k == 'AccessKey' })
+        Log.dump(:ats_info, ats_info)
         Aspera.assert_hash_all(ats_info, String, nil) { 'ats_info' }
         Aspera.assert((FASP_INFO_KEYS - ats_info.keys).empty?, 'ats_info missing required keys')
         Aspera.assert_hash_all(ats_info['AccessKey'], String, String) { 'ats_info' }

data/lib/aspera/api/faspex.rb

@@ -2,7 +2,7 @@
 
 require 'aspera/assert'
 require 'aspera/rest'
-require 'aspera/oauth/base'
+require 'aspera/oauth/client/base'
 require 'aspera/rest/list'
 require 'digest'
 

data/lib/aspera/api/node.rb

@@ -3,9 +3,10 @@
 require 'aspera/link_header'
 require 'aspera/transfer/spec'
 require 'aspera/rest'
-require 'aspera/oauth'
+require 'aspera/oauth/client/factory'
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/secret_hider'
 require 'aspera/environment'
 require 'base64'
 require 'openssl'
@@ -173,12 +174,15 @@ module Aspera
           payload['auth_type'] ||= 'access_key'
           payload['expires_at'] ||= (Time.now + expiration_sec).utc.strftime('%FT%TZ')
           payload_json = JSON.generate(payload)
-          return Base64.strict_encode64(Zlib::Deflate.deflate([
+          token = Base64.strict_encode64(Zlib::Deflate.deflate([
             payload_json,
             SIGNATURE_DELIMITER,
             Base64.strict_encode64(private_key.sign(OpenSSL::Digest.new('sha512'), payload_json)).scan(/.{1,60}/).join("\n"),
             ''
           ].join("\n")))
+          # Hidden wherever it appears (logs, results)
+          SecretHider.instance.add_secret_values(token)
+          return token
         end
 
         # Decode an Aspera Node bearer token

data/lib/aspera/ascp/installation.rb

@@ -51,15 +51,24 @@ module Aspera
       end
 
       # Loads YAML from cloud with locations of SDK archives for all platforms
-      # @return [Hash] location structure
+      # Tries each URL of option `locations_url` (default if empty) in order, until one provides a valid list.
+      # All but the last URL are read with a short timeout and no retry, so that fallback is quick.
+      # @return [Array<Hash>] location structure
       def sdk_locations
-        location_url = @transferd_urls
-        transferd_locations = UriReader.read(location_url)
-        Log.log.debug { "Retrieving SDK locations from #{location_url}" }
-        begin
-          return Yaml.safe_load(transferd_locations)
-        rescue Psych::SyntaxError
-          raise "Error when parsing yaml data from: #{location_url}"
+        Aspera.assert_type(@transferd_urls, Array) { 'locations_url' }
+        location_urls = @transferd_urls.empty? ? TRANSFERD_ARCHIVE_LOCATION_URLS : @transferd_urls
+        location_urls.each_with_index do |location_url, index|
+          last = index.eql?(location_urls.length - 1)
+          Log.log.debug { "Retrieving SDK locations from #{location_url}" }
+          begin
+            transferd_locations = last ? UriReader.read(location_url) : read_fail_fast(location_url)
+            locations = Yaml.safe_load(transferd_locations)
+            Aspera.assert_type(locations, Array) { "SDK locations from #{location_url}" }
+            return locations
+          rescue StandardError => e
+            raise if last
+            Log.log.warn { "Failed to retrieve SDK locations from #{location_url}: #{e.message}, trying next" }
+          end
         end
       end
 
@@ -415,6 +424,7 @@ module Aspera
         return sdk_name, sdk_version, folder
       end
 
+      # @return [Array<String>] URLs of SDK locations, tried in order
       attr_accessor :transferd_urls
 
       private
@@ -434,20 +444,46 @@ module Aspera
       EXE_FILES = %i[ascp ascp4 async transferd].freeze
       # IDs of files present in SDK
       SDK_FILES = (EXE_FILES + %i[ssh_private_dsa ssh_private_rsa aspera_license aspera_conf fallback_certificate fallback_private_key]).freeze
-      TRANSFERD_ARCHIVE_LOCATION_URL = 'https://ibm.biz/sdk_location'
+      # Primary URL (ibm.biz short link) with fallback to the canonical GitHub raw source
+      TRANSFERD_ARCHIVE_LOCATION_URLS = [
+        'https://ibm.biz/sdk_location',
+        'https://raw.githubusercontent.com/IBM/aspera-cli/refs/heads/main/docs/sdk_location.yaml'
+      ].freeze
+      # Timeout in seconds when another location URL remains to be tried
+      LOCATION_FAIL_FAST_TIMEOUT = 10
       # filename for ascp with optional extension (Windows)
-      private_constant :DEFAULT_ASPERA_CONF, :EXE_FILES, :SDK_FILES, :TRANSFERD_ARCHIVE_LOCATION_URL
+      private_constant :DEFAULT_ASPERA_CONF, :EXE_FILES, :SDK_FILES, :TRANSFERD_ARCHIVE_LOCATION_URLS, :LOCATION_FAIL_FAST_TIMEOUT
 
       def initialize
         # cache for installed products found
         @found_products = nil
-        @transferd_urls = TRANSFERD_ARCHIVE_LOCATION_URL
+        # URLs of SDK locations, tried in order
+        @transferd_urls = TRANSFERD_ARCHIVE_LOCATION_URLS
         # product selected with option `sdk_folder`, or nil to use SDK folder
         @ascp_product = nil
         # cache for folder of `ascp` of selected product
         @ascp_folder = nil
       end
 
+      # Read URL with a short timeout and no retry (temporarily changes global HTTP parameters)
+      # @param url [String] URL to read
+      # @return [String] content
+      def read_fail_fast(url)
+        parameters = Rest::Parameters.instance
+        session_cb = parameters.session_cb
+        retry_max = parameters.retry_max
+        parameters.retry_max = 0
+        parameters.session_cb = lambda do |http_session|
+          session_cb&.call(http_session)
+          http_session.open_timeout = [http_session.open_timeout, LOCATION_FAIL_FAST_TIMEOUT].compact.min
+          http_session.read_timeout = [http_session.read_timeout, LOCATION_FAIL_FAST_TIMEOUT].compact.min
+        end
+        UriReader.read(url)
+      ensure
+        parameters.session_cb = session_cb
+        parameters.retry_max = retry_max
+      end
+
       # @param file_type [Symbol] one of EXE_FILES
       # @return [String] path to executable in SDK folder
       def sdk_exe_path(file_type)

data/lib/aspera/ascp/management.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/assert'
+require 'aspera/log'
 require 'aspera/string_ext'
 
 module Aspera
@@ -8,16 +9,17 @@ module Aspera
     # processing of ascp management port events
     # Reference: `mgmtmess.c`
     class Management
+      # cspell:ignore asmgmt faspmgmt
       # References:
-      # https://www.google.com/search?q=FASP+error+codes
       # https://www.ibm.com/support/pages/error-code-reference-tables
-      # mgmtmess.c : as_mgmt_err_is_retryable
+      # `asmgmt_err.h` : codes, mnemonics and messages
+      # `mgmtmess.c` : `faspmgmt_err_name_str` (additional info) and `as_mgmt_err_is_retryable`
       # Note that the fact that an error is retry-able is not internally defined by protocol, it's client-side responsibility
       # rubocop:disable-next Layout/FirstHashElementLineBreak
       ERRORS = {
         # id   retry-able    mnemo/code                        message                                              additional info
         0  => {r: false, c: 'UNKNOWN',                     m: 'unknown',                                        a: 'unknown'},
-        1  => {r: false, c: 'FASP_PROTO',                  m: 'Generic fasp(tm) protocol error',                a: 'fasp(tm) error'},
+        1  => {r: false, c: 'FASP_PROTO',                  m: 'Generic fasp(tm) protocol error',                a: 'FASP error'},
         2  => {r: false, c: 'ASCP',                        m: 'Generic SCP error',                              a: 'ASCP error'},
         3  => {r: false, c: 'AMBIGUOUS_TARGET',            m: 'Target incorrectly specified',                   a: 'Ambiguous target'},
         4  => {r: false, c: 'NO_SUCH_FILE',                m: 'No such file or directory',                      a: 'No such file or directory'},
@@ -29,13 +31,13 @@ module Aspera
         10 => {r: false, c: 'LIC_RATE_EXCEEDED',           m: 'Rate exceeds the cap imposed by license',        a: 'Rate exceeds cap imposed by license'},
         11 => {r: false, c: 'INTERNAL_ERROR',              m: 'Internal error (unexpected error)',              a: 'Internal error'},
         12 => {r: true,  c: 'TRANSFER_ERROR',              m: 'Error establishing control connection',
-                                                                a: 'Error establishing SSH connection (check SSH port and firewall)'},
+                                                           a: 'Error establishing SSH connection (check SSH port and firewall)'},
         13 => {r: true,  c: 'TRANSFER_TIMEOUT',            m: 'Timeout establishing control connection',
-                                                                a: 'Timeout establishing SSH connection (check SSH port and firewall)'},
+                                                           a: 'Timeout establishing SSH connection (check SSH port and firewall)'},
         14 => {r: true,  c: 'CONNECTION_ERROR',            m: 'Error establishing data connection',
-                                                                a: 'Error establishing UDP connection (check UDP port and firewall)'},
+                                                           a: 'Error establishing UDP connection (check UDP port and firewall)'},
         15 => {r: true,  c: 'CONNECTION_TIMEOUT',          m: 'Timeout establishing data connection',
-                                                                a: 'Timeout establishing UDP connection (check UDP port and firewall)'},
+                                                           a: 'Timeout establishing UDP connection (check UDP port and firewall)'},
         16 => {r: true,  c: 'CONNECTION_LOST',             m: 'Connection lost',                                a: 'Connection lost'},
         17 => {r: true,  c: 'RCVR_SEND_ERROR',             m: 'Receiver fails to send feedback',                a: 'Network failure (receiver can\'t send feedback)'},
         18 => {r: true,  c: 'RCVR_RECV_ERROR',             m: 'Receiver fails to receive data packets',         a: 'Network failure (receiver can\'t receive UDP data)'},
@@ -67,34 +69,37 @@ module Aspera
         44 => {r: true,  c: 'PMTU_BRTT_ERROR',             m: 'UDP session initiation fatal error',             a: 'UDP session initiation fatal error'},
         45 => {r: true,  c: 'BWMEAS_ERROR',                m: 'Bandwidth measurement fatal error',              a: 'Bandwidth measurement fatal error'},
         46 => {r: false, c: 'VLINK_ERROR',                 m: 'Virtual link error',                             a: 'Virtual link error'},
-        47 => {r: false, c: 'CONNECTION_ERROR_HTTP',       m: 'Error establishing HTTP connection',
-                                                            a: 'Error establishing HTTP connection (check HTTP port and firewall)'},
-        48 => {r: false, c: 'FILE_ENCRYPTION_ERROR',       m: 'File encryption error, e.g. corrupt file',
-                                                            a: 'File encryption/decryption error, e.g. corrupt file'},
-        49 => {r: false, c: 'FILE_DECRYPTION_PASS',        m: 'File encryption/decryption error, e.g. corrupt file', a: 'File decryption error, bad passphrase'},
-        50 => {r: false, c: 'BAD_CONFIGURATION',           m: 'Aspera.conf contains invalid data and was rejected',  a: 'Invalid configuration'},
+        47 => {r: true,  c: 'CONNECTION_ERROR_HTTP',       m: 'Error establishing HTTP connection',
+                                                           a: 'Error establishing HTTP connection (check HTTP port and firewall)'},
+        48 => {r: false, c: 'FILE_ENCRYPTION_ERROR',       m: 'File encryption error, e.g. corrupt file',       a: 'File encryption/decryption error, e.g. corrupt file'},
+        49 => {r: false, c: 'FILE_DECRYPTION_PASS',        m: 'File decryption bad passphrase',                 a: 'File decryption error, bad passphrase'},
+        50 => {r: false, c: 'BAD_CONFIGURATION',           m: 'Aspera.conf contains invalid data and was rejected', a: 'Invalid configuration'},
         51 => {r: false, c: 'INSECURE_CONNECTION',         m: 'Remote-host key check failure',                  a: 'Remote host is not who we expected'},
         52 => {r: false, c: 'START_VALIDATION_FAILED',     m: 'File start validation failed',                   a: 'File start validation failed'},
         53 => {r: false, c: 'STOP_VALIDATION_FAILED',      m: 'File stop validation failed',                    a: 'File stop validation failed'},
         54 => {r: false, c: 'THRESHOLD_VALIDATION_FAILED', m: 'File threshold validation failed',               a: 'File threshold validation failed'},
         55 => {r: false, c: 'FILEPATH_TOO_LONG',           m: 'File path/name too long for underlying file system', a: 'File path exceeds underlying file system limit'},
         56 => {r: false, c: 'ILLEGAL_CHARS_IN_PATH',       m: 'Windows path contains illegal characters',
-                                                                a: 'Path being written to Windows file system contains illegal characters'},
-        57 => {r: false, c: 'CHUNK_MUST_MATCH_ALIGNMENT',  m: 'Chunk size/start must be aligned with storage',  a: 'Chunk size/start must be aligned with storage'},
-        58 => {r: false, c: 'VALIDATION_SESSION_ABORT',    m: 'Session aborted to due to validation error',     a: 'Session aborted to due validation error'},
+                                                           a: 'Path being written to Windows file system contains illegal characters'},
+        57 => {r: false, c: 'CHUNK_MUST_MATCH_ALIGNMENT',  m: 'Chunk size/start must be aligned with storage',
+                                                           a: 'Data size must match storage chunk size and alignment requirements'},
+        58 => {r: false, c: 'VALIDATION_SESSION_ABORT',    m: 'Session aborted due to validation error(s)',     a: 'Session aborted due to validation error(s)'},
         59 => {r: false, c: 'REMOTE_STORAGE_ERROR',        m: 'Remote storage errored',                         a: 'Remote storage errored'},
-        60 => {r: false, c: 'LUA_SCRIPT_ABORTED_SESSION',  m: 'Session aborted due to Lua script abort',        a: 'Session aborted due to Lua script abort'},
+        60 => {r: false, c: 'LUA_SCRIPT_ABORTED_SESSION',  m: 'Session aborted due to Lua script abort',        a: 'Session aborted'},
         61 => {r: true,  c: 'SSEAR_RETRYABLE',             m: 'Transfer failed because of a retryable Encryption at Rest error',
-                                                                a: 'Transfer failed because of a retryable Encryption at Rest error'},
-        62 => {r: false, c: 'SSEAR_FATAL',                 m: 'Transfer failed because of a fatal Encryption at Rest error',
-                                                                a: 'Transfer failed because of a fatal Encryption at Rest error'},
-        63 => {r: false, c: 'LINK_LOOP',                   m: 'Path refers to a symbolic link loop',            a: 'Path refers to a symbolic link loop'},
-        64 => {r: false, c: 'CANNOT_RENAME_PARTIAL_FILES', m: 'Can\'t rename a partial file',                   a: 'Can\'t rename a partial file.'},
-        65 => {r: false, c: 'CIPHER_NON_COMPAT_FIPS',      m: 'Can\'t use this cipher with FIPS mode enabled',  a: 'Can\'t use this cipher with FIPS mode enabled'},
-        66 => {r: false, c: 'PEER_REQUIRES_FIPS',          m: 'Peer rejects cipher due to FIPS mode enabled on peer',
-                                                                a: 'Peer rejects cipher due to FIPS mode enabled on peer'}
+                                                           a: 'Server-side Encryption At Rest unavailable'},
+        62 => {r: false, c: 'SSEAR_FATAL',                 m: 'Transfer failed because of a fatal Encryption at Rest error', a: 'Server-side Encryption At Rest failed'},
+        63 => {r: false, c: 'LINK_LOOP',                   m: 'Path refers to a symbolic link loop',            a: 'Symbolic link loop'},
+        64 => {r: false, c: 'CANNOT_RENAME_PARTIAL',       m: 'Can\'t rename a partial file',                   a: 'Cannot rename partial file'},
+        65 => {r: false, c: 'CIPHER_NON_COMPAT_FIPS',      m: 'Can\'t use this cipher with FIPS mode enabled',  a: 'Cypher not supported in FIPS mode'},
+        66 => {r: false, c: 'PEER_REQUIRES_FIPS',          m: 'Peer rejects cipher due to FIPS mode enabled on peer', a: 'Peer requires FIPS be enabled'},
+        67 => {r: false, c: 'UPLOAD_IN_PROGRESS',          m: 'Conflict between two transfers',                 a: 'File upload already in progress'},
+        68 => {r: false, c: 'MIN_VERSION_CHECK',           m: 'Minimum version check failed',                   a: 'Failed to start due to minimum version check'},
+        69 => {r: true,  c: 'MAX_ASCP',                    m: 'Maximum ascp processes on a node exceeded',
+                                                           a: 'Failed to start session maximum transfer sessions exceeded'}
       }.freeze
       # cspell: disable
+      # Same as `as_mgmt_cmd_name_str` (`NOTIFICATION` is twice there too)
       OPERATIONS = %w[
         NOP
         START
@@ -117,8 +122,9 @@ module Aspera
         CLOSE
         SKIP
         ARGSTOP
-      ]
+      ].freeze
 
+      # Same as `as_mgmt_arg_name_str`
       PARAMETERS = %w[
         Type
         File
@@ -241,7 +247,7 @@ module Aspera
         FilesEncrypt
         FilesDecrypt
         DatagramSize
-        PrepostCommand
+        Stalled
         XoptFlags
         VLinkVersion
         PeerVLinkVersion
@@ -273,23 +279,36 @@ module Aspera
         PostTransferValidation
         OverwritePolicyCap
         ExtraCreatePolicy
-      ]
+        FipsModeEnabled
+      ].freeze
       # Management port start message
       PROT_VERSION = '2'
       MGT_HEADER = "FASPMGR #{PROT_VERSION}"
       # empty line is separator to end event information
       MGT_FRAME_SEPARATOR = ''
       # fields description for JSON generation
-      # cspell: disable
-      INTEGER_FIELDS = %w[Bytescont FaspFileArgIndex StartByte Rate MinRate Port Priority RateCap MinRateCap TCPPort CreatePolicy TimePolicy
+      # Integer fields may also be a percentage (e.g. `Rate: 50%`): kept as String
+      INTEGER_FIELDS = %w[Bytescont FaspFileArgIndex StartByte EndByte Rate MinRate Port Priority RateCap MinRateCap PriorityCap TCPPort CreatePolicy TimePolicy
                           DatagramSize XoptFlags VLinkVersion PeerVLinkVersion DSPipelineDepth PeerDSPipelineDepth ReadBlockSize WriteBlockSize
-                          ClusterNumNodes ClusterNodeId Size Written Loss FileBytes PreTransferBytes TransferBytes PMTU Elapsedusec ArgScansAttempted
-                          ArgScansCompleted PathScansAttempted FileScansCompleted TransfersAttempted TransfersPassed Delay].freeze
+                          ClusterNumNodes ClusterNodeId Size Written Loss FileBytes PreTransferBytes PartialPreTransferBytes TransferBytes PMTU Elapsedusec Delay
+                          Code RetryTimeout XferRetry MoveRangeLow MoveRangeHigh
+                          PreTransferFiles PreTransferDirs PreTransferSpecial PreTransferFailed PreTransferExcluded
+                          ArgScansAttempted ArgScansCompleted PathScansAttempted PathScansFailed PathScansIrregular PathScansExcluded
+                          DirScansCompleted FileScansCompleted DirCreatesAttempted DirCreatesFailed DirCreatesPassed
+                          TransfersAttempted TransfersFailed TransfersPassed TransfersSkipped
+                          ArgTransfersAttempted ArgTransfersFailed ArgTransfersPassed ArgTransfersSkipped].freeze
       BOOLEAN_FIELDS = %w[Encryption Remote RateLock MinRateLock PolicyLock FilesEncrypt FilesDecrypt VLinkLocalEnabled VLinkRemoteEnabled
-                          MoveRange Keepalive TestLogin UseProxy Precalc RTTAutocorrect].freeze
+                          MoveRange Keepalive TestLogin UseProxy Precalc RTTAutocorrect Stalled PostTransferValidation FipsModeEnabled].freeze
       BOOLEAN_TRUE = 'Yes'
+      INTEGER_VALUE = /\A-?\d+\z/
+      # Fields with path values, escaped on management port (`as_mgmt_escape_path`)
+      PATH_FIELDS = %w[Source Destination File].freeze
+      # Characters escaped in path values: `ESC` followed by the replacement
+      PATH_ESCAPE = "\e"
+      PATH_ESCAPES = {"\n" => 'n', "\r" => 'r', PATH_ESCAPE => PATH_ESCAPE}.freeze
 
-      private_constant :OPERATIONS, :PARAMETERS, :MGT_HEADER, :MGT_FRAME_SEPARATOR, :INTEGER_FIELDS, :BOOLEAN_FIELDS, :BOOLEAN_TRUE
+      private_constant :OPERATIONS, :PARAMETERS, :MGT_HEADER, :MGT_FRAME_SEPARATOR, :INTEGER_FIELDS, :BOOLEAN_FIELDS, :BOOLEAN_TRUE, :INTEGER_VALUE,
+        :PATH_FIELDS, :PATH_ESCAPE, :PATH_ESCAPES
       # cspell: enable
 
       class << self
@@ -305,7 +324,7 @@ module Aspera
         # Translate snake case event name to native
         # @param name [String] Field name
         def field_snake_to_native(name)
-          field = name.delete('_')
+          field = name.to_s.delete('_')
           result = PARAMETERS.find { |w| w.casecmp?(field) }
           Aspera.assert(!result.nil?) { "No such field: #{name}" }
           result
@@ -315,7 +334,7 @@ module Aspera
         def event_native_to_snake(event)
           event.each_with_object({}) do |(key, value), h|
             h[field_native_to_snake(key)] =
-              if INTEGER_FIELDS.include?(key) then value.to_i
+              if INTEGER_FIELDS.include?(key) && INTEGER_VALUE.match?(value) then value.to_i
               elsif BOOLEAN_FIELDS.include?(key) then value.eql?(BOOLEAN_TRUE)
               else
                 value
@@ -323,12 +342,36 @@ module Aspera
           end
         end
 
+        # Escape path value for management port: line breaks and escape char
+        # @param value [String] Path
+        # @return [String] Escaped path
+        def escape_path(value)
+          value.gsub(/[\n\r\e]/) { |char| "#{PATH_ESCAPE}#{PATH_ESCAPES[char]}" }
+        end
+
+        # Reverse of `escape_path`
+        # @param value [String] Escaped path
+        # @return [String] Path
+        def unescape_path(value)
+          value.gsub(/\e([nr\e])/) { PATH_ESCAPES.key(Regexp.last_match(1)) }
+        end
+
         # Build command to send on management port
+        # Frame: header, one line per field, empty line (last empty element adds the final line break)
         # @param data [Hash] keys are snake case: e.g. {'type'=>'START','source'=>_path_,'destination'=>_path_}
         # @return [String] frame to send on management port
         def command_to_stream(data)
           data
-            .map { |key, value| "#{field_snake_to_native(key)}: #{value}" }
+            .map do |key, value|
+              name = field_snake_to_native(key)
+              value = value.to_s
+              if PATH_FIELDS.include?(name)
+                value = escape_path(value)
+              else
+                Aspera.assert(!value.match?(/[\r\n]/)) { "mgt port: line break in value of #{name}" }
+              end
+              "#{name}: #{value}"
+            end
             .unshift(MGT_HEADER)
             .push(MGT_FRAME_SEPARATOR, '')
             .join("\n")
@@ -347,21 +390,24 @@ module Aspera
       # @param line [String] line of mgt port event
       # @return [Hash] event hash or nil if event is not yet complete
       def process_line(line)
-        # Log.log.debug{"line=[#{line}]"}
         case line
         when MGT_HEADER
           # begin event
+          Log.log.warn { "mgt port: incomplete event discarded: #{@event_build}" } unless @event_build.nil?
           @event_build = {}
-        when /^([^:]+): (.*)$/
-          Aspera.assert_type(@event_build, Hash) { 'mgt port: unexpected line: data without header' }
-          # event field
-          @event_build[Regexp.last_match(1)] = Regexp.last_match(2)
         when MGT_FRAME_SEPARATOR
           Aspera.assert_type(@event_build, Hash) { 'mgt port: unexpected line: end frame without header' }
           @last_event = @event_build
           @event_build = nil
           return @last_event
-        else Aspera.error_unexpected_value(line) { 'mgt port' }
+        else
+          # event field: name up to first colon, optional single space (as `as_mgmt_buffered_read_msg`)
+          name, value = line.split(':', 2)
+          Aspera.error_unexpected_value(line) { 'mgt port' } if value.nil?
+          Aspera.assert_type(@event_build, Hash) { 'mgt port: unexpected line: data without header' }
+          value = value.delete_prefix(' ')
+          value = self.class.unescape_path(value) if PATH_FIELDS.include?(name)
+          @event_build[name] = value
         end
         return
       end

data/lib/aspera/cli/ascp_actions.rb

@@ -3,6 +3,7 @@
 require 'aspera/agent/factory'
 require 'aspera/schema/registry'
 require 'aspera/schema/reader'
+require 'aspera/schema/documentation'
 
 module Aspera
   module Cli
@@ -101,33 +102,18 @@ module Aspera
       def action_agents_show(agent_name:, **)
         names = Agent::Factory::ALL[agent_name]
         schema_key = AGENT_SCHEMA_KEY[agent_name]
-        agent_info = {
+        Result::SingleObject.new({
           'name'        => agent_name.to_s,
           'short'       => names[:short].to_s,
           'description' => schema_key ? Schema::Registry.instance.reader(schema_key).current['description'].to_s : '(no configurable parameters)'
-        }
-        if schema_key
-          properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
-          rows = properties.map do |pname, pdef|
-            row = {'parameter' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
-            row['required'] = (Schema::Registry.instance.reader(schema_key).current['required'] || []).include?(pname) ? 'yes' : 'no'
-            row['default']  = pdef.key?('default') ? pdef['default'].inspect : ''
-            row['enum']     = pdef.key?('enum')    ? pdef['enum'].join(', ') : ''
-            row
-          end
-          return Result::ObjectList.new(rows, fields: %w[parameter required type default enum description])
-        end
-        Result::SingleObject.new(agent_info)
+        })
       end
 
       def action_agents_parameters(agent_name:, **)
         schema_key = AGENT_SCHEMA_KEY[agent_name]
         return Result::Nothing.new if schema_key.nil?
-        properties = Schema::Registry.instance.reader(schema_key).current['properties'] || {}
-        rows = properties.map do |pname, pdef|
-          {'name' => pname, 'type' => pdef['type'].to_s, 'description' => pdef['description'].to_s}
-        end
-        Result::ObjectList.new(rows, fields: %w[name type description])
+        builder = Schema::Documentation.new(TerminalFormatter, Schema::Registry.instance.reader(schema_key)).build
+        Result::ObjectList.new(builder.rows, fields: builder.columns)
       end
     end
   end

data/lib/aspera/cli/bootstrapper.rb

@@ -16,7 +16,7 @@ require 'aspera/persistency_folder'
 require 'aspera/rest'
 require 'aspera/log'
 require 'aspera/assert'
-require 'aspera/oauth'
+require 'aspera/oauth/client/web'
 require 'aspera/ssl'
 require 'aspera/schema/registry'
 
@@ -174,7 +174,6 @@ module Aspera
         OAuth::Web.additional_info = "#{Info::CMD_NAME} v#{Cli::VERSION}"
         Transfer::Parameters.file_list_folder = File.join(@context.main_folder, FILE_LIST_FOLDER_NAME)
         Rest::ErrorAnalyzer.instance.log_file = File.join(@context.main_folder, REST_EXCEPTIONS_LOG_FILENAME)
-        Rest::AsperaErrors.register_handlers
       end
 
       # @return [String] ~/.aspera