aspera-cli 4.26.2 → 4.27.0

data/lib/aspera/agent/node.rb

@@ -13,6 +13,38 @@ module Aspera
     # this singleton class is used by the CLI to provide a common interface to start a transfer
     # before using it, the use must set the `node_api` member.
     class Node < Base
+      class << self
+        # Re-query a previously started transfer via the Node REST API.
+        # agent_params must contain 'url', 'username', 'password' (and optionally 'root_id').
+        # @return [Hash] normalized status hash
+        def transfer_status(transfer_id, agent_params)
+          rest_params = {base_url: agent_params['url']}
+          if OAuth::Factory.bearer_auth?(agent_params['password'])
+            rest_params[:headers] = Api::Node.bearer_headers(agent_params['password'], access_key: agent_params['username'])
+          else
+            rest_params[:auth] = {type: :basic, username: agent_params['username'], password: agent_params['password']}
+          end
+          node_api = Rest.new(**rest_params)
+          data = node_api.read("ops/transfers/#{transfer_id}") || {'status' => 'unknown'}
+          normalize_status(data)
+        end
+
+        # Normalize a node API transfer hash into the standard async-transfer fields.
+        def normalize_status(data)
+          result = {'bytes_transferred' => data['bytes_transferred'].to_i}
+          case data['status']
+          when 'completed'
+            result['status'] = 'completed'
+            result['ended_at'] = Time.now.utc.iso8601
+          when 'failed'
+            result.merge!('status' => 'failed', 'ended_at' => Time.now.utc.iso8601, 'error' => data['error_desc'].to_s)
+          else
+            result['status'] = 'running'
+          end
+          result
+        end
+      end
+
       # @param url          [String] the base url of the node api
       # @param username     [String] the username to use for the node api
       # @param password     [String] the password to use for the node api

data/lib/aspera/agent/transferd.rb

@@ -21,6 +21,37 @@ module Aspera
 
       private_constant :LOCAL_SOCKET_ADDR, :PORT_SEP, :AUTO_LOCAL_TCP_PORT
 
+      class << self
+        # Re-query a previously started transfer from a running transferd daemon.
+        # agent_params must contain 'url' (the daemon endpoint, e.g. "127.0.0.1:12345").
+        # @return [Hash] normalized status hash
+        def transfer_status(transfer_id, agent_params)
+          client = ::Transferd::Api::TransferService::Stub.new(agent_params['url'], :this_channel_is_insecure)
+          result = {'bytes_transferred' => 0}
+          client.monitor_transfers(::Transferd::Api::RegistrationRequest.new(transferId: [transfer_id])) do |response|
+            result = case response.status
+            when :COMPLETED
+              {
+                'status' => 'completed', 'ended_at' => Time.now.utc.iso8601,
+                        'bytes_transferred' => response.transferInfo.bytesTransferred
+              }
+            when :FAILED, :CANCELED
+              {
+                'status' => response.status == :FAILED ? 'failed' : 'cancelled',
+                        'ended_at' => Time.now.utc.iso8601, 'bytes_transferred' => 0,
+                        'error' => JSON.parse(response.message.to_s)['Description']
+              }
+            else
+              {'status' => 'running', 'bytes_transferred' => response.transferInfo.bytesTransferred}
+            end
+            break
+          end
+          result
+        rescue StandardError => e
+          {'status' => 'running', 'bytes_transferred' => 0, 'error' => e.message}
+        end
+      end
+
       # @param url   [String]  URL of the transfer manager daemon
       # @param start [Boolean] If `false`, expect that an external daemon is already running
       # @param stop  [Boolean] If `false`, do not shutdown daemon on exit
@@ -35,9 +66,10 @@ module Aspera
         @transfer_id = nil
         @stop = stop
         is_local_auto_port = url.eql?(AUTO_LOCAL_TCP_PORT)
-        raise Error, 'Cannot set options `stop` or `start` to false with port zero' if is_local_auto_port && (!@stop || !start)
+        Aspera.assert(!(is_local_auto_port && (!@stop || !start)), type: Error){'Cannot set options `stop` or `start` to false with port zero'}
         # keep PID for optional shutdown
         @daemon_pid = nil
+        @daemon_endpoint = nil
         daemon_endpoint = url
         Log.dump(:daemon_endpoint, daemon_endpoint)
         # retry loop
@@ -48,6 +80,7 @@ module Aspera
           @transfer_client = ::Transferd::Api::TransferService::Stub.new(daemon_endpoint, :this_channel_is_insecure)
           # Initiate actual connection
           get_info_response = @transfer_client.get_info(::Transferd::Api::InstanceInfoRequest.new)
+          @daemon_endpoint = daemon_endpoint
           Log.log.debug{"Daemon info: #{get_info_response}"}
           Log.log.warn('Attached to existing daemon') unless @daemon_pid || !start || !@stop
           at_exit{shutdown}
@@ -55,7 +88,7 @@ module Aspera
           # if transferd is external: do not start it, or other error
           raise if !start || !e.message.include?('failed to connect')
           # we already tried to start a daemon, but it failed
-          Aspera.assert(@daemon_pid.nil?){"Daemon started with PID #{@daemon_pid}, but connection failed to #{daemon_endpoint}}"}
+          Aspera.assert(@daemon_pid.nil?){"Daemon started with PID #{@daemon_pid}, but connection failed to #{daemon_endpoint}"}
           Log.log.warn('no daemon present, starting daemon...') if !start
           # transferd only supports local ip and port
           daemon_uri = URI.parse("ipv4://#{daemon_endpoint}")
@@ -105,6 +138,9 @@ module Aspera
         end
       end
 
+      # Actual endpoint the daemon is listening on (resolved after connect, e.g. when port 0 was used)
+      attr_reader :daemon_endpoint
+
       # :reek:UnusedParameters token_regenerator
       def start_transfer(transfer_spec, token_regenerator: nil)
         Transfer::Spec.fix_transferd_resume_policy(transfer_spec)
@@ -116,7 +152,7 @@ module Aspera
         ) # transfer definition
         # send start transfer request to the transfer manager daemon
         start_response = @transfer_client.start_transfer(transfer_request)
-        raise Transfer::Error, start_response.error.description if start_response.status.eql?(:FAILED)
+        Aspera.assert(!start_response.status.eql?(:FAILED), type: Transfer::Error){start_response.error.description}
         Log.log.debug{"start transfer response #{start_response}"}
         @transfer_id = start_response.transferId
         Log.log.debug{"transfer started with id #{@transfer_id}"}

data/lib/aspera/api/alee.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'aspera/api/aoc.rb'
+require 'aspera/api/aoc'
 module Aspera
   module Api
     # Aspera License Entitlement Engine API client

data/lib/aspera/api/aoc.rb

@@ -25,23 +25,23 @@ module Aspera
 
       class AppInfo
         # @return [Aspera::Api::AoC] Rest Api object
-        attr_reader  :api
+        attr_reader :api
         # @return [Hash, nil] Package information, `"files"` or `"packages"`
-        attr_reader  :package
+        attr_reader :package
         # @return [Hash] Result of GET /nodes/:id
-        attr_reader  :node_info
+        attr_reader :node_info
         # @return [String] Workspace id
-        attr_reader  :workspace_id
+        attr_reader :workspace_id
         # @return [String] Workspace name
-        attr_reader  :workspace_name
+        attr_reader :workspace_name
         # @return [String, nil] "Share as" link name
         attr_accessor :opt_link_name
 
         # @param api [Api::Aoc] Rest Api object
         # @param package [Hash,nil] package information or nil
         # @param node_info [Hash] Result of GET /nodes/:id
-        # @param workspace_id [String]
-        # @param workspace_name [String]
+        # @param workspace_id   [String]     Workspace identifier
+        # @param workspace_name [String]     Workspace name
         def initialize(api, package, node_info, workspace_id, workspace_name)
           @api = api
           @package = package
@@ -68,8 +68,8 @@ module Aspera
       GLOBAL_CLIENT_APPS = DataRepository::ELEMENTS.select{ |i| i.to_s.start_with?(CLIENT_ID_PREFIX)}.freeze
       # cookie prefix so that console can decode identity
       COOKIE_PREFIX_CONSOLE_AOC = 'aspera.aoc'
-      # path in URL of public links
-      PUBLIC_LINK_PATHS = %w[/packages/public/receive /packages/public/send /files/public /public/files /public/package /public/send].freeze
+      # path in URL of public links (warning if not in list)
+      PUBLIC_LINK_PATHS = %w[/packages/public/receive /packages/public/send /files/public /public/files /public/files/ /public/package /public/send /public/send/package].freeze
       JWT_AUDIENCE = 'https://api.asperafiles.com/api/v1/oauth2/token'
       OAUTH_API_SUBPATH = 'api/v1/oauth2'
       # minimum fields for user info if retrieval fails
@@ -269,7 +269,6 @@ module Aspera
       attr_accessor :ws_ids
 
       # By default: no workspace
-      # @param
       def initialize(
         scope: nil,
         subpath: API_V1,
@@ -298,8 +297,7 @@ module Aspera
         # default values for client id
         client_id, client_secret = self.class.get_client_info if client_id.nil?
         # access key secrets are provided out of band to get node api access
-        # key: access key
-        # value: associated secret
+        # maps access key (String) to its associated secret (String)
         @secret_finder = secret_finder
         @cache_user_info = nil
         @cache_url_token_info = nil
@@ -480,14 +478,14 @@ module Aspera
       # @param workspace_name [String,nil] workspace name
       # @param scope          [String,nil] e.g. Node::Scope::USER, or Node::Scope::ADMIN, or nil (requires secret)
       # @param package_info   [Hash,nil] created package information
-      # @returns [Node] a node API for access key
+      # @return [Node] a node API for access key
       def node_api_from(node_id:, workspace_id: nil, workspace_name: nil, scope: Node::Scope::USER, package_info: nil)
         Aspera.assert_type(node_id, String)
         node_info = read("nodes/#{node_id}")
         workspace_name = read("workspaces/#{workspace_id}")['name'] if workspace_name.nil? && !workspace_id.nil?
         app_info = AppInfo.new(self, package_info, node_info, workspace_id, workspace_name)
         node_params = {base_url: node_info['url']}
-        ak_secret = @secret_finder&.lookup_secret(url: node_info['url'], username: node_info['access_key'])
+        ak_secret = @secret_finder&.lookup(url: node_info['url'], username: node_info['access_key'])
         # If secret is available, or no scope, use basic auth
         if scope.nil? || ak_secret
           Aspera.assert(ak_secret, type: Error){"Secret not found for access key #{node_info['access_key']}@#{node_info['url']}"}
@@ -545,7 +543,7 @@ module Aspera
       # @param package_data    [Hash]   The whole package creation payload
       # @param rcpt_lst_field  [String] The field in structure, i.e. recipients or bcc_recipients
       # @param new_user_option [Hash]   Additional fields for contact creation
-      # @return nil, `package_data` is modified
+      # @return [nil] `package_data` is modified in place
       def resolve_package_recipients(package_data, rcpt_lst_field, new_user_option)
         return unless package_data.key?(rcpt_lst_field)
         Aspera.assert_type(package_data[rcpt_lst_field], Array){rcpt_lst_field}
@@ -609,7 +607,7 @@ module Aspera
       # @param package_data [Hash] package creation (with extensions...)
       # @param validate_meta [TrueClass,FalseClass] true to validate parameters locally
       # @param new_user_option [Hash,NilClass] options if an unknown user is specified
-      # @return transfer spec, node api and package information
+      # @return [Array] transfer spec, node api and package information
       def create_package_simple(package_data, validate_meta, new_user_option)
         update_package_metadata_for_api(package_data)
         # list of files to include in package, optional

data/lib/aspera/api/cos_node.rb

@@ -24,7 +24,7 @@ module Aspera
           endpoints = Aspera::Rest.new(base_url: service_credentials['endpoints']).read('')
           Log.dump(:endpoints, endpoints)
           endpoint = endpoints.dig('service-endpoints', 'regional', bucket_region, 'public', bucket_region)
-          raise "no such region: #{bucket_region}" if endpoint.nil?
+          Aspera.assert(!endpoint.nil?){"no such region: #{bucket_region}"}
           return {
             instance_id: service_credentials['resource_instance_id'],
             api_key:     service_credentials['apikey'],

data/lib/aspera/api/faspex.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/assert'
 require 'aspera/rest'
 require 'aspera/oauth/base'
 require 'aspera/rest_list'
@@ -11,9 +12,9 @@ module Aspera
     class << self
       attr_accessor :additional_info
     end
-    # @param context         The `context` query parameter in public link
-    # @param redirect_uri    URI of web UI login
-    # @param path_authorize  Path to provide passcode
+    # @param context        [String] The `context` query parameter in public link
+    # @param redirect_uri   [String] URI of web UI login
+    # @param path_authorize [String] Path to provide passcode
     def initialize(
       context:,
       redirect_uri:,
@@ -125,7 +126,7 @@ module Aspera
         mfa_code
       ]
       class << self
-        # @return true if the URL is a public link
+        # @return [Boolean] true if the URL is a public link
         def public_link?(url)
           url.include?('?context=')
         end
@@ -138,15 +139,15 @@ module Aspera
       end
       attr_reader :pub_link_context
 
-      # @param url             Faspex URL, can be a public link
-      # @param auth            Authentication method: :boot (token in header), :web (open browser), :jwt (client_id + private key), :public_link (context in URL)
-      # @param password        For :boot auth, the token copied directly from browser in developer mode
-      # @param client_id       For :web and :jwt auth, the client_id of web UI application
-      # @param client_secret   For :web auth, the client_secret of web UI application (not needed for :jwt)
-      # @param redirect_uri    For :web auth, the redirect_uri of web UI application (must be the same as in application configuration)
-      # @param username        For :jwt auth, the username of the user to impersonate
-      # @param private_key     For :jwt auth, the private key to sign JWT token
-      # @param passphrase      For :jwt auth, the passphrase of the private key
+      # @param url            [String] Faspex URL, can be a public link
+      # @param auth           [Symbol] Authentication method: :boot (token in header), :web (open browser), :jwt (client_id + private key), :public_link (context in URL)
+      # @param password       [String, nil] For :boot auth, the token copied directly from browser in developer mode
+      # @param client_id      [String, nil] For :web and :jwt auth, the client_id of web UI application
+      # @param client_secret  [String, nil] For :web auth, the client_secret of web UI application (not needed for :jwt)
+      # @param redirect_uri   [String, nil] For :web auth, the redirect_uri of web UI application (must be the same as in application configuration)
+      # @param username       [String, nil] For :jwt auth, the username of the user to impersonate
+      # @param private_key    [String, nil] For :jwt auth, the private key to sign JWT token
+      # @param passphrase     [String, nil] For :jwt auth, the passphrase of the private key
       def initialize(
         url:,
         auth:,
@@ -169,7 +170,7 @@ module Aspera
             Log.dump(:final_url, final_url, level: :trace1)
             # Get context from query
             encoded_context = Rest.query_to_h(URI.parse(final_url).query)['context']
-            raise ParameterError, 'Bad faspex5 public link, missing context in query' if encoded_context.nil?
+            Aspera.assert(!encoded_context.nil?, type: ParameterError){'Bad faspex5 public link, missing context in query'}
             # public link information (contains passcode and allowed usage)
             @pub_link_context = JSON.parse(Base64.decode64(encoded_context))
             Log.dump(:pub_link_context, @pub_link_context, level: :trace1)

data/lib/aspera/api/httpgw.rb

@@ -81,7 +81,7 @@ module Aspera
       end
 
       # Check header ourself and give precise error message, as websocket will only throw error without details
-      # @param [String] Response Header
+      # @param header [String] Response Header
       # @return [String] Response Header
       def validated_ws_response_header(header)
         first_line = header.split("\r\n").first
@@ -210,7 +210,7 @@ module Aspera
             fileIndex:    file_index
           }
           file = file_to_send[:file]
-          file = File.open(file) unless file.is_a?(Transfer::FauxFile)
+          file = File.open(file) unless file.is_a?(Transfer::FauxFile) # rubocop:disable Style/FileOpen
           begin
             until file.eof?
               slice_bin_data = file.read(@upload_chunk_size)
@@ -291,7 +291,7 @@ module Aspera
         return @api_info
       end
 
-      # @return the base url of the gateway
+      # @return [String] the base url of the gateway
       def base_url
         return @gw_root_url
       end
@@ -308,7 +308,7 @@ module Aspera
         Log.dump(:gw_url, url)
         # add scheme if missing
         url = "https://#{url}" unless url.match?(%r{^[a-z]{1,6}://})
-        raise Error, 'GW URL shall be with scheme https' unless url.start_with?('https://')
+        Aspera.assert(url.start_with?('https://'), type: Error){'GW URL shall be with scheme https'}
         # remove trailing slash and version (o=only once) if present
         # TODO: issue warning ?
         url = url.chomp('/').gsub(%r{/#{API_V1}$}o, '')

data/lib/aspera/api/node.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/link_header'
 require 'aspera/transfer/spec'
 require 'aspera/rest'
 require 'aspera/oauth'
@@ -78,12 +79,12 @@ module Aspera
         attr_reader :api_options
         attr_reader :use_dynamic_key
 
-        def api_options=(h)
-          Aspera.assert_type(h, Hash)
-          h.each do |k, v|
-            Aspera.assert(@api_options.key?(k.to_sym)){"unknown api option: #{k} (#{OPTIONS.join(', ')})"}
-            Aspera.assert_type(v, TrueClass, FalseClass){"api options value for #{k} should be boolean"}
-            @api_options[k.to_sym] = v
+        def api_options=(options_hash)
+          Aspera.assert_type(options_hash, Hash)
+          options_hash.each do |key, val|
+            Aspera.assert(@api_options.key?(key.to_sym)){"unknown api option: #{key} (#{OPTIONS.join(', ')})"}
+            Aspera.assert_type(val, TrueClass, FalseClass){"api options value for #{key} should be boolean"}
+            @api_options[key.to_sym] = val
           end
         end
 
@@ -105,30 +106,30 @@ module Aspera
         end
 
         # Adds fields `public_keys` in provided Hash, if dynamic key is set.
-        # @param h [Hash] Hash to add public key to
+        # @param parameters [Hash] Hash to add public key to
         # @return [Hash] Hash with public key added
-        def add_public_key(h)
+        def add_public_key(parameters)
           if @dynamic_key
             ssh_key = Net::SSH::Buffer.from(:key, @dynamic_key)
             # Get pub key in OpenSSH public key format (authorized_keys)
-            h['public_keys'] = [
+            parameters['public_keys'] = [
               ssh_key.read_string,
               Base64.strict_encode64(ssh_key.to_s)
             ].join(' ')
           end
-          return h
+          return parameters
         end
 
         # Adds fields `ssh_private_key` in provided Hash, if dynamic key is set.
-        # @param h [Hash] Hash to add private key to
-        def add_private_key(h)
-          h['ssh_private_key'] = @dynamic_key.to_pem if @dynamic_key
-          return h
+        # @param parameters [Hash] Hash to add private key to
+        def add_private_key(parameters)
+          parameters['ssh_private_key'] = @dynamic_key.to_pem if @dynamic_key
+          return parameters
         end
 
         # For access keys: provide expression to match entry in folder
-        # @param match_expression one of supported types
-        # @return lambda function
+        # @param match_expression [Proc, Regexp, String] one of supported types
+        # @return [Proc] lambda function
         def file_matcher(match_expression)
           case match_expression
           when Proc then return match_expression
@@ -146,7 +147,8 @@ module Aspera
         end
 
         # Split path into folder + filename
-        # @return [Array] containing folder + inside folder/file
+        # @param path [String] file path to split
+        # @return [Array(String, String)] containing folder + inside folder/file
         def split_folder(path)
           folder = path.split(PATH_SEPARATOR)
           inside = folder.pop
@@ -160,7 +162,8 @@ module Aspera
         end
 
         # Decode node scope into access key and scope
-        # @return [Hash]
+        # @param scope [String] scope string to decode
+        # @return [Hash] decoded scope with access key and scope parts
         def decode_scope(scope)
           items = scope.split(Scope::SEPARATOR, 2)
           Aspera.assert(items.length.eql?(2)){"invalid scope: #{scope}"}
@@ -240,7 +243,7 @@ module Aspera
         return tspec
       end
 
-      # @returns [Node, nil] a Node Api object or nil if no App defined
+      # @return [Node, nil] a Node Api object or nil if no App defined
       def node_id_to_node(node_id)
         if !@app_info.nil?
           return self if node_id.eql?(@app_info.node_info['id'])
@@ -390,7 +393,7 @@ module Aspera
         return NodeFileId.new(self, top_file_id) if path_elements.empty?
         resolve_state = {path: path_elements, consumed: [], result: nil, process_last_link: process_last_link}
         process_folder_tree(method_sym: :process_api_fid, state: resolve_state, top_file_id: top_file_id)
-        raise ParameterError, "Entry not found: #{resolve_state[:path].first} in /#{resolve_state[:consumed].join(PATH_SEPARATOR)}" if resolve_state[:result].nil?
+        Aspera.assert(!resolve_state[:result].nil?, type: ParameterError){"Entry not found: #{resolve_state[:path].first} in /#{resolve_state[:consumed].join(PATH_SEPARATOR)}"}
         Log.log.debug{"resolve_api_fid: #{path} -> #{resolve_state[:result].node_api.base_url} #{resolve_state[:result].file_id}"}
         return resolve_state[:result]
       end
@@ -572,7 +575,7 @@ module Aspera
           # Update progress spinner
           RestParameters.instance.spinner_cb.call(item_list.length)
           # Parse Link header according to RFC 8288 to extract next iteration token
-          next_url = Rest.parse_link_header(http['Link'], rel: 'next')
+          next_url = LinkHeader.parse(http['Link']).find_href(rel: 'next')
           next_iteration_token = nil
           if next_url
             begin
@@ -629,7 +632,7 @@ module Aspera
       private
 
       # Method called in loop for each entry for `resolve_api_fid`
-      # @return `true` to continue digging, `false` to stop processing: set state[:result] if found
+      # @return [Boolean] `true` to continue digging, `false` to stop processing: set state[:result] if found
       def process_api_fid(entry, path, state)
         # Stop digging here if not in right path
         return false unless entry['name'].eql?(state[:path].first)
@@ -656,7 +659,7 @@ module Aspera
               # We found it
               other_node = nil
               other_node = node_id_to_node(entry['target_node_id']) if entry_has_link_information(entry)
-              raise Error, 'Cannot resolve link' if other_node.nil?
+              Aspera.assert(!other_node.nil?, type: Error){'Cannot resolve link'}
               state[:result] = NodeFileId.new(other_node, entry['target_id'])
             else
               # We found it but we do not process the link

data/lib/aspera/api/queries/bss_subscription_account.graphql

@@ -0,0 +1,18 @@
+query ($organization_id: ID!) {
+  aoc (organization_id: $organization_id) {
+    bssSubscription {
+      aocVersion endDate startDate termMonths plan trial termType
+      aocOrganizations { id }
+      additionalStorageVolumeGb additionalEgressVolumeGb
+      term { startDate endDate transferVolumeGb egressVolumeGb storageVolumeGb transferVolumeOffsetGb }
+      paygoRate { transferRate storageRate currency }
+      aocPlanData {
+        tier trial
+        workspaces { max }
+        users { planAmount max }
+        samlIntegration activity sharedInboxes uniqueUrls support watermarking byok
+        automation { planAmount, max }
+      }
+    }
+  }
+}

data/lib/aspera/api/queries/bss_subscription_usage.graphql

@@ -0,0 +1,18 @@
+query ($organization_id: ID!, $startDate: Date!, $endDate: Date!, $aggregate: TransferUsageAggregateOption!) {
+  aoc (organization_id: $organization_id) {
+    bssSubscription {
+      aocOrganizations { id }
+      additionalStorageVolumeGb additionalEgressVolumeGb
+      aocPlanData { tier trial }
+      term { transferVolumeGb egressVolumeGb storageVolumeGb startDate endDate transferVolumeOffsetGb }
+      termMonths
+      transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+      egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+    }
+    subscriptionEntitlements {
+      id
+      transferUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { mbTotal }
+      egressUsages (startDate: $startDate, endDate: $endDate, aggregate: $aggregate) { usageMb }
+    }
+  }
+}

data/lib/aspera/ascmd.rb

@@ -28,18 +28,18 @@ module Aspera
     ENUM_START = 1
 
     # Description of result structures (see ascmdtypes.h).
-    # Base types are big endian
-    # key = name of type
-    # index in array `fields` is: the numerical type of TLV - `ENUM_START`. i.e. add `ENUM_START` to index, to get `T`
-    # decoding always start at `result`
-    # some fields have special handling indicated by `special`
-    # field_list, list_tlv_list, list_tlv_restart are composed with a list of TLV
-    # decode:
-    # - :base : value
-    # - :buffer_list : an array of {btype,buffer}
-    # - :field_list : a hash, or array
-    # :check: ???
-    # rubocop:disable Layout/FirstHashElementLineBreak
+    # Base types are big endian.
+    # Keys are type names; the index in each `fields` array equals (TLV numerical type - `ENUM_START`).
+    # Decoding always starts at `result`.
+    # Some fields have special handling indicated by `special`:
+    #   - `:field_list`       : a Hash or Array of child TLVs
+    #   - `:list_tlv_list`    : a list of TLV sub-lists (Array of Hash)
+    #   - `:list_tlv_restart` : same but restarted per entry
+    # `decode` values:
+    #   - `:base`        : a single scalar value (unpack with `unpack`)
+    #   - `:buffer_list` : an Array of `{btype, buffer}` entries
+    #   - `:field_list`  : a Hash or Array built from child TLVs
+    # rubocop:disable-next Layout/FirstHashElementLineBreak
     TYPES_DESCR = {
       result: {decode: :field_list,
                fields: [{name: :file, is_a: :stat}, {name: :dir, is_a: :stat, special: :list_tlv_list}, {name: :size, is_a: :size}, {name: :error, is_a: :error},
@@ -73,7 +73,6 @@ module Aspera
       zstr:   {decode: :base, unpack: 'Z*'},
       blist:  {decode: :buffer_list}
     }.freeze
-    # rubocop:enable Layout/FirstHashElementLineBreak
 
     private_constant :TYPES_DESCR, :ENUM_START, :OPS_ARGS
 
@@ -87,8 +86,8 @@ module Aspera
 
     # execute an "as" command on a remote server
     # Version 2 allows use of reverse proxy with multiple addresses.
-    # @param [Symbol] one of OPERATIONS
-    # @param [Array] parameters for "as" command
+    # @param action_sym [Symbol] one of OPERATIONS
+    # @param arguments  [Array]  parameters for "as" command
     # @return [Boolean,Array,Hash] result of command, type depends on command
     def execute_single(action_sym, arguments, version: 1, host: nil)
       arguments = [] if arguments.nil?
@@ -169,19 +168,22 @@ module Aspera
     end
 
     class << self
-      # Get description of structure's field, @param struct_name, @param typed_buffer provides field name
+      # Get description of structure's field
+      # @param struct_name   [Symbol] name of the structure type
+      # @param typed_buffer  [Hash]   typed buffer providing the field name via `:btype`
+      # @return [Hash] field description
       def field_description(struct_name, typed_buffer)
         result = TYPES_DESCR[struct_name][:fields][typed_buffer[:btype] - ENUM_START]
-        raise "Unrecognized field for #{struct_name}: #{typed_buffer[:btype]}\n#{typed_buffer[:buffer]}" if result.nil?
+        Aspera.assert(!result.nil?){"Unrecognized field for #{struct_name}: #{typed_buffer[:btype]}\n#{typed_buffer[:buffer]}"}
         return result
       end
 
       # Decodes the provided buffer as provided type name
-      # @return a decoded type: single, Array, or Hash
+      # @return [Boolean, Array, Hash] a decoded type: single, Array, or Hash
       def parse(buffer, type_name, indent_level = nil)
         indent_level = (indent_level || -1) + 1
         type_descr = TYPES_DESCR[type_name]
-        raise "Unexpected type #{type_name}" if type_descr.nil?
+        Aspera.assert(!type_descr.nil?){"Unexpected type #{type_name}"}
         Log.log.trace1{"#{'   .' * indent_level}parse:#{type_name}:#{type_descr[:decode]}:#{buffer[0, 16]}...".red}
         result = nil
         case type_descr[:decode]