aspera-cli 4.21.2 → 4.23.0

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

@@ -21,6 +21,7 @@ module Aspera
     module Plugins
       class Node < Cli::BasicAuthPlugin
         include SyncActions
+
         class << self
           # directory: node, container: shares
           FOLDER_TYPES = %w[directory container].freeze
@@ -47,6 +48,7 @@ module Aspera
               test_endpoint = 'ping'
               result = api.call(operation: 'GET', subpath: test_endpoint)
               next unless result[:http].body.eql?('')
+              # also remove "/"
               url_end = -2 - test_endpoint.length
               return {
                 url:     result[:http].uri.to_s[0..url_end],
@@ -107,7 +109,7 @@ module Aspera
         SEARCH_REMOVE_FIELDS = %w[basename permissions].freeze
 
         # actions in execute_command_gen3
-        COMMANDS_GEN3 = %i[search space mkdir mklink mkfile rename delete browse upload download http_node_download sync transport]
+        COMMANDS_GEN3 = %i[search space mkdir mklink mkfile rename delete browse upload download cat sync transport]
 
         BASE_ACTIONS = %i[api_details].concat(COMMANDS_GEN3).freeze
 
@@ -125,7 +127,7 @@ module Aspera
         NODE4_READ_ACTIONS = %i[bearer_token_node node_info browse find].freeze
 
         # commands for execute_command_gen4
-        COMMANDS_GEN4 = %i[mkdir rename delete upload download sync http_node_download show modify permission thumbnail v3].concat(NODE4_READ_ACTIONS).freeze
+        COMMANDS_GEN4 = %i[mkdir mklink mkfile rename delete upload download sync cat show modify permission thumbnail v3].concat(NODE4_READ_ACTIONS).freeze
 
         # commands supported in ATS for COS
         COMMANDS_COS = %i[upload download info access_keys api_details transfer].freeze
@@ -134,13 +136,16 @@ module Aspera
 
         GEN4_LS_FIELDS = %w[name type recursive_size size modified_time access_level].freeze
 
-        def initialize(api: nil, **env)
+        # @param api [Rest] an existing API object for the Node API
+        # @param prefix_path [String,nil] for Faspex 4, allows browsing a package
+        def initialize(api: nil, prefix_path: nil, **env)
+          @prefix_path = prefix_path
           super(**env, basic_options: api.nil?)
-          Node.declare_options(options) if api.nil?
-          return if only_manual
+          Node.declare_options(options)
+          return if env[:broker].only_manual?
           @api_node =
             if !api.nil?
-              # this can be Api::Node or Rest (shares)
+              # this can be Api::Node or Rest (Shares)
               api
             elsif OAuth::Factory.bearer?(options.get_option(:password, mandatory: true))
               # info is provided like node_info of aoc
@@ -161,23 +166,22 @@ module Aspera
         end
 
         # reduce the path from a result on given named column
-        def c_result_remove_prefix_path(result, column, path_prefix)
-          if !path_prefix.nil?
-            case result[:type]
-            when :object_list
-              result[:data].each do |item|
-                item[column] = item[column][path_prefix.length..-1] if item[column].start_with?(path_prefix)
-              end
-            when :single_object
-              item = result[:data]
-              item[column] = item[column][path_prefix.length..-1] if item[column].start_with?(path_prefix)
+        def c_result_remove_prefix_path(result, column)
+          return result if @prefix_path.nil?
+          case result[:type]
+          when :object_list
+            result[:data].each do |item|
+              item[column] = item[column][@prefix_path.length..-1] if item[column].start_with?(@prefix_path)
             end
+          when :single_object
+            item = result[:data]
+            item[column] = item[column][@prefix_path.length..-1] if item[column].start_with?(@prefix_path)
           end
           return result
         end
 
         # translates paths results into CLI result, and removes prefix
-        def c_result_translate_rem_prefix(response, type, success_msg, path_prefix)
+        def c_result_translate_rem_prefix(response, type, success_msg)
           errors = []
           final_result = {type: :object_list, data: [], fields: [type, 'result']}
           response['paths'].each do |p|
@@ -191,16 +195,16 @@ module Aspera
           end
           # one error make all fail
           unless errors.empty?
-            raise errors.map{|i|"#{i.first}: #{i.last}"}.join(', ')
+            raise errors.map{ |i| "#{i.first}: #{i.last}"}.join(', ')
           end
-          return c_result_remove_prefix_path(final_result, type, path_prefix)
+          return c_result_remove_prefix_path(final_result, type)
         end
 
-        def browse_gen3(prefix_path)
-          folders_to_process = [get_one_argument_with_prefix(prefix_path, 'path')]
+        def browse_gen3
+          folders_to_process = [get_one_argument_with_prefix('path')]
           query = options.get_option(:query, default: {})
           # special parameter: max number of entries in result
-          max_items = query.delete('max')
+          max_items = query.delete(MAX_ITEMS)
           # special parameter: recursive browsing
           recursive = query.delete('recursive')
           # special parameter: only return one entry for the path, even if folder
@@ -209,7 +213,7 @@ module Aspera
           single_call = query.key?('skip')
           # API default is 100, so use 1000 for default
           query['count'] ||= 1000
-          raise Cli::BadArgument, 'options recursive and skip cannot be used together' if recursive && single_call
+          raise Cli::BadArgument, 'options `recursive` and `skip` cannot be used together' if recursive && single_call
           all_items = []
           until folders_to_process.empty?
             path = folders_to_process.shift
@@ -222,7 +226,7 @@ module Aspera
               response = @api_node.create('files/browse', query)
               # 'file','symbolic_link'
               if !Node.gen3_entry_folder?(response['self']) || only_path
-                result = { type: :single_object, data: response['self']}
+                result = {type: :single_object, data: response['self']}
                 break
               end
               items = response['items']
@@ -233,7 +237,7 @@ module Aspera
                 break
               end
               if recursive
-                folders_to_process.concat(items.select{|i|Node.gen3_entry_folder?(i)}.map{|i|i['path']})
+                folders_to_process.concat(items.select{ |i| Node.gen3_entry_folder?(i)}.map{ |i| i['path']})
               end
               if !max_items.nil? && (all_items.count >= max_items)
                 all_items = all_items.slice(0, max_items) if all_items.count > max_items
@@ -248,73 +252,94 @@ module Aspera
           end
           result ||= {type: :object_list, data: all_items}
           formatter.long_operation_terminated
-          return c_result_remove_prefix_path(result, 'path', prefix_path)
+          return c_result_remove_prefix_path(result, 'path')
+        end
+
+        # Create async transfer spec request from direction and folders
+        # @param sync_direction one of push pull bidi
+        # @param local_path local folder to sync
+        # @param remote_path remote folder to sync
+        def sync_spec_request(sync_direction, local_path, remote_path)
+          case sync_direction
+          when :push then {
+            type:  :sync_upload,
+            paths: [{
+              source:      local_path,
+              destination: remote_path
+            }]
+          }
+          when :pull then {
+            type:  :sync_download,
+            paths: [{
+              source:      remote_path,
+              destination: local_path
+            }]
+          }
+          when :bidi then {
+            type:  :sync,
+            paths: [{
+              source:      local_path,
+              destination: remote_path
+            }]
+          }
+          else Aspera.error_unexpected_value(sync_direction)
+          end
         end
 
-        # file and folder related commands
-        def execute_command_gen3(command, prefix_path)
+        # Commands based on Gen3 API for file and folder
+        def execute_command_gen3(command)
           case command
           when :delete
             # TODO: add query for recursive
-            paths_to_delete = get_all_arguments_with_prefix(prefix_path, 'file list')
-            resp = @api_node.create('files/delete', { paths: paths_to_delete.map{|i| {'path' => i.start_with?('/') ? i : "/#{i}"} }})
-            return c_result_translate_rem_prefix(resp, 'file', 'deleted', prefix_path)
+            paths_to_delete = get_all_arguments_with_prefix('file list')
+            resp = @api_node.create('files/delete', {paths: paths_to_delete.map{ |i| {'path' => i.start_with?('/') ? i : "/#{i}"}}})
+            return c_result_translate_rem_prefix(resp, 'file', 'deleted')
           when :search
-            search_root = get_one_argument_with_prefix(prefix_path, 'search root')
+            search_root = get_one_argument_with_prefix('search root')
             parameters = {'path' => search_root}
             other_options = options.get_option(:query)
             parameters.merge!(other_options) unless other_options.nil?
             resp = @api_node.create('files/search', parameters)
-            result = { type: :object_list, data: resp['items']}
+            result = {type: :object_list, data: resp['items']}
             return Main.result_empty if result[:data].empty?
-            result[:fields] = result[:data].first.keys.reject{|i|SEARCH_REMOVE_FIELDS.include?(i)}
+            result[:fields] = result[:data].first.keys.reject{ |i| SEARCH_REMOVE_FIELDS.include?(i)}
             formatter.display_item_count(resp['item_count'], resp['total_count'])
-            formatter.display_status("params: #{resp['parameters'].keys.map{|k|"#{k}:#{resp['parameters'][k]}"}.join(',')}")
-            return c_result_remove_prefix_path(result, 'path', prefix_path)
+            formatter.display_status("params: #{resp['parameters'].keys.map{ |k| "#{k}:#{resp['parameters'][k]}"}.join(',')}")
+            return c_result_remove_prefix_path(result, 'path')
           when :space
-            path_list = get_all_arguments_with_prefix(prefix_path, 'folder path or ext.val. list')
-            resp = @api_node.create('space', { 'paths' => path_list.map {|i| { path: i} } })
-            result = { type: :object_list, data: resp['paths']}
-            # return c_result_translate_rem_prefix(resp,'folder','created',prefix_path)
-            return c_result_remove_prefix_path(result, 'path', prefix_path)
+            path_list = get_all_arguments_with_prefix('folder path or ext.val. list')
+            resp = @api_node.create('space', {'paths' => path_list.map{ |i| {path: i}}})
+            result = {type: :object_list, data: resp['paths']}
+            # return c_result_translate_rem_prefix(resp,'folder','created',@prefix_path)
+            return c_result_remove_prefix_path(result, 'path')
           when :mkdir
-            path_list = get_all_arguments_with_prefix(prefix_path, 'folder path or ext.val. list')
-            resp = @api_node.create('files/create', { 'paths' => path_list.map{|i|{ type: :directory, path: i }}})
-            return c_result_translate_rem_prefix(resp, 'folder', 'created', prefix_path)
+            path_list = get_all_arguments_with_prefix('folder path or ext.val. list')
+            resp = @api_node.create('files/create', {'paths' => path_list.map{ |i| {type: :directory, path: i}}})
+            return c_result_translate_rem_prefix(resp, 'folder', 'created')
           when :mklink
-            target = get_one_argument_with_prefix(prefix_path, 'target')
-            one_path = get_one_argument_with_prefix(prefix_path, 'link path')
-            resp = @api_node.create('files/create', { 'paths' => [{ type: :symbolic_link, path: one_path, target: { path: target} }] })
-            return c_result_translate_rem_prefix(resp, 'folder', 'created', prefix_path)
+            target = get_one_argument_with_prefix('target')
+            one_path = get_one_argument_with_prefix('link path')
+            resp = @api_node.create('files/create', {'paths' => [{type: :symbolic_link, path: one_path, target: {path: target}}]})
+            return c_result_translate_rem_prefix(resp, 'folder', 'created')
           when :mkfile
-            one_path = get_one_argument_with_prefix(prefix_path, 'file path')
+            one_path = get_one_argument_with_prefix('file path')
             contents64 = Base64.strict_encode64(options.get_next_argument('contents'))
-            resp = @api_node.create('files/create', { 'paths' => [{ type: :file, path: one_path, contents: contents64 }] })
-            return c_result_translate_rem_prefix(resp, 'folder', 'created', prefix_path)
+            resp = @api_node.create('files/create', {'paths' => [{type: :file, path: one_path, contents: contents64}]})
+            return c_result_translate_rem_prefix(resp, 'folder', 'created')
           when :rename
             # TODO: multiple ?
-            path_base = get_one_argument_with_prefix(prefix_path, 'path_base')
-            path_src = get_one_argument_with_prefix(prefix_path, 'path_src')
-            path_dst = get_one_argument_with_prefix(prefix_path, 'path_dst')
-            resp = @api_node.create('files/rename', { 'paths' => [{ 'path' => path_base, 'source' => path_src, 'destination' => path_dst }] })
-            return c_result_translate_rem_prefix(resp, 'entry', 'moved', prefix_path)
+            path_base = get_one_argument_with_prefix('path_base')
+            path_src = get_one_argument_with_prefix('path_src')
+            path_dst = get_one_argument_with_prefix('path_dst')
+            resp = @api_node.create('files/rename', {'paths' => [{'path' => path_base, 'source' => path_src, 'destination' => path_dst}]})
+            return c_result_translate_rem_prefix(resp, 'entry', 'moved')
           when :browse
-            return browse_gen3(prefix_path)
+            return browse_gen3
           when :sync
             return execute_sync_action do |sync_direction, local_path, remote_path|
               # Gen3 API
               # empty transfer spec for authorization request
-              request_transfer_spec = {
-                type:  case sync_direction
-                       when :push then :sync_upload
-                       when :pull then :sync_download
-                       when :bidi then :sync
-                       end,
-                paths: [{
-                  source:      remote_path,
-                  destination: local_path
-                }]
-              }
+              request_transfer_spec = sync_spec_request(sync_direction, local_path, remote_path)
               # add fixed parameters if any (for COS)
               @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
               # prepare payload for single request
@@ -322,7 +347,7 @@ module Aspera
               # only one request, so only one answer
               transfer_spec = @api_node.create('files/sync_setup', setup_payload)['transfer_specs'].first['transfer_spec']
               # API returns null tag... but async does not like it
-              transfer_spec.delete_if{ |_k, v| v.nil? }
+              transfer_spec.delete_if{ |_k, v| v.nil?}
               # delete this part, as the returned value contains only destination, and not sources
               # transfer_spec.delete('paths') if command.eql?(:upload)
               Log.log.debug{Log.dump(:ts, transfer_spec)}
@@ -335,7 +360,7 @@ module Aspera
             request_transfer_spec[:paths] = if command.eql?(:download)
               transfer.ts_source_paths
             else
-              [{ destination: transfer.destination_folder(Transfer::Spec::DIRECTION_SEND) }]
+              [{destination: transfer.destination_folder(Transfer::Spec::DIRECTION_SEND)}]
             end
             # add fixed parameters if any (for COS)
             @api_node.add_tspec_info(request_transfer_spec) if @api_node.respond_to?(:add_tspec_info)
@@ -346,32 +371,30 @@ module Aspera
             # delete this part, as the returned value contains only destination, and not sources
             transfer_spec.delete('paths') if command.eql?(:upload)
             return Main.result_transfer(transfer.start(transfer_spec))
-          when :http_node_download
-            remote_path = get_one_argument_with_prefix(prefix_path, 'remote path')
-            file_name = File.basename(remote_path)
-            @api_node.call(
+          when :cat
+            remote_path = get_one_argument_with_prefix('remote path')
+            File.basename(remote_path)
+            result = @api_node.call(
               operation: 'GET',
-              subpath: "files/#{URI.encode_www_form_component(remote_path)}/contents",
-              save_to_file: File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_name))
-            return Main.result_status("downloaded: #{file_name}")
+              subpath: "files/#{URI.encode_www_form_component(remote_path)}/contents")
+            return Main.result_text(result[:http].body)
           when :transport
-            return {type: :single_object, data: @api_node.transport_params}
+            return Main.result_single_object(@api_node.transport_params)
           end
           Aspera.error_unreachable_line
         end
 
         # common API to node and Shares
-        # prefix_path is used to list remote sources in Faspex
-        def execute_simple_common(command, prefix_path)
+        def execute_simple_common(command)
           case command
           when *COMMANDS_GEN3
-            execute_command_gen3(command, prefix_path)
+            execute_command_gen3(command)
           when :access_keys
             ak_command = options.get_next_command(%i[do set_bearer_key].concat(Plugin::ALL_OPS))
             case ak_command
             when *Plugin::ALL_OPS
               return entity_command(ak_command, @api_node, 'access_keys') do |field, value|
-                       raise 'only selector: %id:self' unless field.eql?('id') && value.eql?('self')
+                       raise Cli::BadIdentifier, 'only selector: %id:self' unless field.eql?('id') && value.eql?('self')
                        @api_node.read('access_keys/self')['id']
                      end
             when :do
@@ -410,11 +433,12 @@ module Aspera
             end
             begin
               @api_node.call(
-                operation: 'POST',
-                subpath:   'services/soap/Transfer-201210',
-                headers:   {'Content-Type' => 'text/xml;charset=UTF-8', 'SOAPAction' => 'FASPSessionNET-200911#GetSessionInfo'},
-                body:      CENTRAL_SOAP_API_TEST,
-                body_type: :text)[:http].body
+                operation:    'POST',
+                subpath:      'services/soap/Transfer-201210',
+                content_type: Rest::MIME_TEXT,
+                body:         CENTRAL_SOAP_API_TEST,
+                headers:      {'Content-Type' => 'text/xml;charset=UTF-8', 'SOAPAction' => 'FASPSessionNET-200911#GetSessionInfo'}
+              )[:http].body
               nagios.add_ok('central', 'accessible by node')
             rescue StandardError => e
               nagios.add_critical('central', e.to_s)
@@ -422,22 +446,22 @@ module Aspera
             return nagios.result
           when :events
             events = @api_node.read('events', query_read_delete)
-            return { type: :object_list, data: events, fields: ->(f){!f.start_with?('data')} }
+            return Main.result_object_list(events, fields: ->(f){!f.start_with?('data')})
           when :info
             nd_info = @api_node.read('info')
-            return { type: :single_object, data: nd_info}
+            return Main.result_single_object(nd_info)
           when :slash
             nd_info = @api_node.read('')
-            return { type: :single_object, data: nd_info}
+            return Main.result_single_object(nd_info)
           when :license
             # requires: asnodeadmin -mu <node user> --acl-add=internal --internal
             node_license = @api_node.read('license')
             if node_license['failure'].is_a?(String) && node_license['failure'].include?('ACL')
               Log.log.error('server must have: asnodeadmin -mu <node user> --acl-add=internal --internal')
             end
-            return {type: :single_object, data: node_license}
+            return Main.result_single_object(node_license)
           when :api_details
-            return {type: :single_object, data: {base_url: @api_node.base_url}.merge(@api_node.params)}
+            return Main.result_single_object({base_url: @api_node.base_url}.merge(@api_node.params))
           end
         end
 
@@ -445,7 +469,7 @@ module Aspera
         # @return [Hash] api and main file id for given path or id in next argument
         def apifid_from_next_arg(top_file_id)
           file_path = instance_identifier(description: 'path or %id:<id>') do |attribute, value|
-            raise 'Only selection "id" is supported (file id)' unless attribute.eql?('id')
+            raise Cli::BadIdentifier, 'Only selection "id" is supported (file id)' unless attribute.eql?('id')
             # directly return result for method
             return {api: @api_node, file_id: value}
           end
@@ -456,7 +480,7 @@ module Aspera
         def execute_command_gen4(command_repo, top_file_id)
           override_file_id = options.get_option(:root_id)
           top_file_id = override_file_id unless override_file_id.nil?
-          raise 'Specify root file id with option root_id' if top_file_id.nil?
+          raise Cli::Error, 'Specify root file id with option root_id' if top_file_id.nil?
           case command_repo
           when :v3
             # NOTE: other common actions are unauthorized with user scope
@@ -480,7 +504,7 @@ module Aspera
               result[:password] = apifid[:api].oauth.authorization
             else Aspera.error_unreachable_line
             end
-            return {type: :single_object, data: result} if command_repo.eql?(:node_info)
+            return Main.result_single_object(result) if command_repo.eql?(:node_info)
             # check format of bearer token
             OAuth::Factory.bearer_extract(result[:password])
             return Main.result_status(result[:password])
@@ -489,20 +513,48 @@ module Aspera
             file_info = apifid[:api].read_with_cache("files/#{apifid[:file_id]}")
             unless file_info['type'].eql?('folder')
               # a single file
-              return {type: :object_list, data: [file_info], fields: GEN4_LS_FIELDS}
+              return Main.result_object_list([file_info], fields: GEN4_LS_FIELDS)
             end
-            return {type: :object_list, data: apifid[:api].list_files(apifid[:file_id]), fields: GEN4_LS_FIELDS}
+            return Main.result_object_list(apifid[:api].list_files(apifid[:file_id]), fields: GEN4_LS_FIELDS)
           when :find
             apifid = apifid_from_next_arg(top_file_id)
             find_lambda = Api::Node.file_matcher_from_argument(options)
-            return {type: :object_list, data: @api_node.find_files(apifid[:file_id], find_lambda), fields: ['path']}
-          when :mkdir
+            return Main.result_object_list(@api_node.find_files(apifid[:file_id], find_lambda), fields: ['path'])
+          when :mkdir, :mklink, :mkfile
             containing_folder_path = options.get_next_argument('path').split(Api::Node::PATH_SEPARATOR)
-            new_folder = containing_folder_path.pop
-            # add trailing slash to force last link to be resolved
+            new_item = containing_folder_path.pop
             apifid = @api_node.resolve_api_fid(top_file_id, containing_folder_path.join(Api::Node::PATH_SEPARATOR), true)
-            result = apifid[:api].create("files/#{apifid[:file_id]}/files", {name: new_folder, type: :folder})
-            return Main.result_status("created: #{result['name']} (id=#{result['id']})")
+            query = options.get_option(:query, mandatory: false)
+            check_exists = true
+            payload = {name: new_item}
+            if query
+              check_exists = !query.delete('check').eql?(false)
+              target = query.delete('target')
+              if target
+                target_apifid = @api_node.resolve_api_fid(top_file_id, target, true)
+                payload[:target_id] = target_apifid[:file_id]
+              end
+              payload.merge!(query.symbolize_keys)
+            end
+            if check_exists
+              folder_content = apifid[:api].read("files/#{apifid[:file_id]}/files")
+              link_name = ".#{new_item}.asp-lnk"
+              found = folder_content.find{ |i| i['name'].eql?(new_item) || i['name'].eql?(link_name)}
+              raise "A #{found['type']} already exists with name #{new_item}" if found
+            end
+            case command_repo
+            when :mkdir
+              payload[:type] = :folder
+            when :mklink
+              payload[:type] = :link
+              Aspera.assert(payload[:target_id]){'Missing target_id'}
+              Aspera.assert(payload[:target_node_id]){'Missing target_node_id'}
+            when :mkfile
+              payload[:type] = :file
+              payload[:contents] = Base64.strict_encode64(options.get_next_argument('contents'))
+            end
+            result = apifid[:api].create("files/#{apifid[:file_id]}/files", payload)
+            return Main.result_single_object(result)
           when :rename
             file_path = options.get_next_argument('source path')
             apifid = @api_node.resolve_api_fid(top_file_id, file_path)
@@ -562,11 +614,11 @@ module Aspera
                 # TODO: add this ? , 'destination'=>file_info['name']
                 source_paths = [{'source' => '.'}]
               else
-                raise "Unknown source type: #{file_info['type']}"
+                raise BadArgument, "Unknown source type: #{file_info['type']}"
               end
             end
             return Main.result_transfer(transfer.start(apifid[:api].transfer_spec_gen4(apifid[:file_id], Transfer::Spec::DIRECTION_RECEIVE, {'paths'=>source_paths})))
-          when :http_node_download
+          when :cat
             source_paths = transfer.ts_source_paths
             source_folder = source_paths.shift['source']
             if source_paths.empty?
@@ -577,15 +629,14 @@ module Aspera
             raise Cli::BadArgument, 'one file at a time only in HTTP mode' if source_paths.length > 1
             file_name = source_paths.first['source']
             apifid = @api_node.resolve_api_fid(top_file_id, File.join(source_folder, file_name))
-            apifid[:api].call(
+            result = apifid[:api].call(
               operation: 'GET',
-              subpath: "files/#{apifid[:file_id]}/content",
-              save_to_file: File.join(transfer.destination_folder(Transfer::Spec::DIRECTION_RECEIVE), file_name))
-            return Main.result_status("downloaded: #{file_name}")
+              subpath: "files/#{apifid[:file_id]}/content")
+            return Main.result_text(result[:http].body)
           when :show
             apifid = apifid_from_next_arg(top_file_id)
             items = apifid[:api].read("files/#{apifid[:file_id]}")
-            return {type: :single_object, data: items}
+            return Main.result_single_object(items)
           when :modify
             apifid = apifid_from_next_arg(top_file_id)
             update_param = options.get_next_argument('update data', validation: Hash)
@@ -610,7 +661,7 @@ module Aspera
               list_query['inherited'] = false if list_query.key?('file_id') && !list_query.key?('inherited')
               # NOTE: supports per_page and page and header X-Total-Count
               items = apifid[:api].read('permissions', list_query)
-              return {type: :object_list, data: items}
+              return Main.result_object_list(items)
             when :show
               perm_id = instance_identifier
               return Main.result_single_object(apifid[:api].read("permissions/#{perm_id}"))
@@ -624,7 +675,7 @@ module Aspera
               end
             when :create
               create_param = options.get_next_argument('creation data', validation: Hash)
-              raise 'no file_id' if create_param.key?('file_id')
+              raise Cli::BadArgument, 'no file_id' if create_param.key?('file_id')
               create_param['file_id'] = apifid[:file_id]
               create_param['access_levels'] = Api::Node::ACCESS_LEVELS unless create_param.key?('access_levels')
               # add application specific tags (AoC)
@@ -634,7 +685,7 @@ module Aspera
               created_data = apifid[:api].create('permissions', create_param)
               # notify application of creation
               the_app&.[](:api)&.permissions_send_event(event_data: created_data, app_info: the_app)
-              return { type: :single_object, data: created_data}
+              return Main.result_single_object(created_data)
             else Aspera.error_unreachable_line
             end
           else Aspera.error_unreachable_line
@@ -658,8 +709,8 @@ module Aspera
             else
               async_ids = @api_node.read('async/list')['sync_ids']
               summaries = @api_node.create('async/summary', {'syncs' => async_ids})['sync_summaries']
-              selected = summaries.find{|s|s['name'].eql?(async_name)}
-              raise "no such sync: #{async_name}" if selected.nil?
+              selected = summaries.find{ |s| s['name'].eql?(async_name)}
+              raise Cli::BadIdentifier, "no such sync: #{async_name}" if selected.nil?
               async_id = selected['snid']
               async_ids = [async_id]
             end
@@ -668,22 +719,22 @@ module Aspera
           case command
           when :list
             resp = @api_node.read('async/list')['sync_ids']
-            return { type: :value_list, data: resp, name: 'id' }
+            return Main.result_value_list(resp, name: 'id')
           when :show
             resp = @api_node.create('async/summary', post_data)['sync_summaries']
             return Main.result_empty if resp.empty?
-            return { type: :object_list, data: resp, fields: %w[snid name local_dir remote_dir] } if async_id.eql?(SpecialValues::ALL)
-            return { type: :single_object, data: resp.first }
+            return Main.result_object_list(resp, fields: %w[snid name local_dir remote_dir]) if async_id.eql?(SpecialValues::ALL)
+            return Main.result_single_object(resp.first)
           when :delete
             resp = @api_node.create('async/delete', post_data)
-            return { type: :single_object, data: resp, name: 'id' }
+            return Main.result_single_object(resp)
           when :bandwidth
             post_data['seconds'] = 100 # TODO: as parameter with --value
             resp = @api_node.create('async/bandwidth', post_data)
             data = resp['bandwidth_data']
             return Main.result_empty if data.empty?
             data = data.first[async_id]['data']
-            return { type: :object_list, data: data, name: 'id' }
+            return Main.result_object_list(data)
           when :files
             # count int
             # filename str
@@ -706,17 +757,17 @@ module Aspera
                   options.get_option(:username, mandatory: true),
                   async_id]))
               unless iteration_data.first.nil?
-                data.select!{|l| l['fnid'].to_i > iteration_data.first}
+                data.select!{ |l| l['fnid'].to_i > iteration_data.first}
               end
               iteration_data[0] = data.last['fnid'].to_i unless data.empty?
             end
             return Main.result_empty if data.empty?
             skip_ids_persistency&.save
-            return { type: :object_list, data: data, name: 'id' }
+            return Main.result_object_list(data)
           when :counters
             resp = @api_node.create('async/counters', post_data)['sync_counters'].first[async_id].last
             return Main.result_empty if resp.nil?
-            return { type: :single_object, data: resp }
+            return Main.result_single_object(resp)
           end
         end
 
@@ -731,7 +782,7 @@ module Aspera
             # name is unique, so we can return
             return id if sync_info[field].eql?(value)
           end
-          raise Cli::BadArgument, "no such sync: #{field}=#{value}"
+          raise Cli::BadIdentifier, "no such sync: #{field}=#{value}"
         end
 
         ACTIONS = %i[
@@ -745,64 +796,60 @@ module Aspera
           asperabrowser
           basic_token
           bearer_token
-          simulator].concat(COMMON_ACTIONS).freeze
+          simulator
+          telemetry
+        ].concat(COMMON_ACTIONS).freeze
 
-        def execute_action(command=nil, prefix_path=nil)
+        def execute_action(command=nil)
           command ||= options.get_next_command(ACTIONS)
           case command
-          when *COMMON_ACTIONS then return execute_simple_common(command, prefix_path)
+          when *COMMON_ACTIONS then return execute_simple_common(command)
           when :async then return execute_async # former API
           when :ssync
             # newer API
             sync_command = options.get_next_command(%i[start stop bandwidth counters files state summary].concat(Plugin::ALL_OPS) - %i[modify])
             case sync_command
-            when *Plugin::ALL_OPS then return entity_command(sync_command, @api_node, 'asyncs', item_list_key: 'ids'){|field, value|ssync_lookup(field, value)}
+            when *Plugin::ALL_OPS then return entity_command(sync_command, @api_node, 'asyncs', item_list_key: 'ids'){ |field, value| ssync_lookup(field, value)}
             else
-              asyncs_id = instance_identifier {|field, value|ssync_lookup(field, value)}
+              asyncs_id = instance_identifier{ |field, value| ssync_lookup(field, value)}
               if %i[start stop].include?(sync_command)
                 @api_node.call(
-                  operation: 'POST',
-                  subpath:   "asyncs/#{asyncs_id}/#{sync_command}",
-                  body:      '',
-                  body_type: :text)[:http].body
+                  operation:    'POST',
+                  subpath:      "asyncs/#{asyncs_id}/#{sync_command}",
+                  content_type: Rest::MIME_TEXT,
+                  body:         ''
+                )[:http].body
                 return Main.result_status('Done')
               end
               parameters = nil
               parameters = options.get_option(:query, default: {}) if %i[bandwidth counters files].include?(sync_command)
-              return { type: :single_object, data: @api_node.read("asyncs/#{asyncs_id}/#{sync_command}", parameters) }
+              return Main.result_single_object(@api_node.read("asyncs/#{asyncs_id}/#{sync_command}", parameters))
             end
           when :stream
             command = options.get_next_command(%i[list create show modify cancel])
             case command
             when :list
               resp = @api_node.read('ops/transfers', query_read_delete)
-              return { type: :object_list, data: resp, fields: %w[id status] } # TODO: useful?
+              return Main.result_object_list(resp, fields: %w[id status]) # TODO: useful?
             when :create
               resp = @api_node.create('streams', value_create_modify(command: command))
-              return { type: :single_object, data: resp }
+              return Main.result_single_object(resp)
             when :show
               resp = @api_node.read("ops/transfers/#{options.get_next_argument('transfer id')}")
-              return { type: :other_struct, data: resp }
+              return Main.result_single_object(resp)
             when :modify
               resp = @api_node.update("streams/#{options.get_next_argument('transfer id')}", value_create_modify(command: command))
-              return { type: :other_struct, data: resp }
+              return Main.result_single_object(resp)
             when :cancel
               resp = @api_node.cancel("streams/#{options.get_next_argument('transfer id')}")
-              return { type: :other_struct, data: resp }
-            else
-              raise 'error'
+              return Main.result_single_object(resp)
+            else Aspera.error_unexpected_value(command)
             end
           when :transfer
             command = options.get_next_command(%i[list cancel show modify bandwidth_average sessions])
-            res_class_path = 'ops/transfers'
-            if %i[cancel show modify].include?(command)
-              one_res_id = instance_identifier
-              one_res_path = "#{res_class_path}/#{one_res_id}"
-            end
             case command
             when :list
               transfer_filter = query_read_delete(default: {})
-              last_iteration_token = nil
               iteration_persistency = nil
               if options.get_option(:once_only, mandatory: true)
                 iteration_persistency = PersistencyActionOnce.new(
@@ -818,36 +865,10 @@ module Aspera
                   iteration_persistency.save
                   return Main.result_status('Persistency reset')
                 end
-                last_iteration_token = iteration_persistency.data.first
               end
-              raise 'reset only with once_only' if transfer_filter.key?('reset') && iteration_persistency.nil?
+              raise Cli::BadArgument, 'reset only with once_only' if transfer_filter.key?('reset') && iteration_persistency.nil?
               max_items = transfer_filter.delete(MAX_ITEMS)
-              transfers_data = []
-              loop do
-                transfer_filter['iteration_token'] = last_iteration_token unless last_iteration_token.nil?
-                result = @api_node.call(operation: 'GET', subpath: res_class_path, query: transfer_filter)
-                # no data
-                break if result[:data].empty?
-                # get next iteration token from link
-                next_iteration_token = nil
-                link_info = result[:http]['Link']
-                unless link_info.nil?
-                  m = link_info.match(/<([^>]+)>/)
-                  raise "Cannot parse iteration in Link: #{link_info}" if m.nil?
-                  next_iteration_token = CGI.parse(URI.parse(m[1]).query)['iteration_token']&.first
-                end
-                # same as last iteration: stop
-                break if next_iteration_token&.eql?(last_iteration_token)
-                last_iteration_token = next_iteration_token
-                transfers_data.concat(result[:data])
-                if max_items&.<=(transfers_data.length)
-                  # if !max_items.nil? && (transfers_data.length >= max_items)
-                  transfers_data = transfers_data.slice(0, max_items)
-                  break
-                end
-                break if last_iteration_token.nil?
-              end
-              iteration_persistency&.data&.[]=(0, last_iteration_token)
+              transfers_data = call_with_iteration(api: @api_node, operation: 'GET', subpath: 'ops/transfers', max: max_items, query: transfer_filter, iteration: iteration_persistency&.data)
               iteration_persistency&.save
               return {
                 type:   :object_list,
@@ -855,8 +876,8 @@ module Aspera
                 fields: %w[id status start_spec.direction start_spec.remote_user start_spec.remote_host start_spec.destination_path]
               }
             when :sessions
-              transfers_data = @api_node.read(res_class_path, query_read_delete)
-              sessions = transfers_data.map{|t|t['sessions']}.flatten
+              transfers_data = @api_node.read('ops/transfers', query_read_delete)
+              sessions = transfers_data.map{ |t| t['sessions']}.flatten
               sessions.each do |session|
                 session['start_time'] = Time.at(session['start_time_usec'] / 1_000_000.0).utc.iso8601(0)
                 session['end_time'] = Time.at(session['end_time_usec'] / 1_000_000.0).utc.iso8601(0)
@@ -867,16 +888,16 @@ module Aspera
                 fields: %w[id status start_time end_time target_rate_kbps]
               }
             when :cancel
-              resp = @api_node.cancel(one_res_path)
-              return { type: :other_struct, data: resp }
+              resp = @api_node.cancel("ops/transfers/#{instance_identifier}")
+              return Main.result_single_object(resp)
             when :show
-              resp = @api_node.read(one_res_path)
-              return { type: :other_struct, data: resp }
+              resp = @api_node.read("ops/transfers/#{instance_identifier}")
+              return Main.result_single_object(resp)
             when :modify
-              resp = @api_node.update(one_res_path, options.get_next_argument('update value', validation: Hash))
-              return { type: :other_struct, data: resp }
+              resp = @api_node.update("ops/transfers/#{instance_identifier}", options.get_next_argument('update value', validation: Hash))
+              return Main.result_single_object(resp)
             when :bandwidth_average
-              transfers_data = @api_node.read(res_class_path, query_read_delete)
+              transfers_data = @api_node.read('ops/transfers', query_read_delete)
               # collect all key dates
               bandwidth_period = {}
               dir_info = %i[avg_kbps sessions].freeze
@@ -919,9 +940,8 @@ module Aspera
                 end
                 result.push({start: Time.at(start_date / 1_000_000), end: Time.at(end_date / 1_000_000)}.merge(period_bandwidth))
               end
-              return { type: :object_list, data: result }
-            else
-              raise 'error'
+              return Main.result_object_list(result)
+            else Aspera.error_unexpected_value(command)
             end
           when :service
             command = options.get_next_command(%i[list create delete])
@@ -931,7 +951,7 @@ module Aspera
             case command
             when :list
               resp = @api_node.read('rund/services')
-              return { type: :object_list, data: resp['services'] }
+              return Main.result_object_list(resp['services'])
             when :create
               # @json:'{"type":"WATCHFOLDERD","run_as":{"user":"user1"}}'
               params = options.get_next_argument('creation data', validation: Hash)
@@ -957,9 +977,9 @@ module Aspera
               return Main.result_status("#{resp['id']} created")
             when :list
               resp = @api_node.read(res_class_path, query_read_delete)
-              return { type: :value_list, data: resp['ids'], name: 'id' }
+              return Main.result_value_list(resp['ids'], name: 'id')
             when :show
-              return { type: :single_object, data: @api_node.read(one_res_path)}
+              return Main.result_single_object(@api_node.read(one_res_path))
             when :modify
               @api_node.update(one_res_path, options.get_option(:query, mandatory: true))
               return Main.result_status("#{one_res_id} updated")
@@ -967,7 +987,7 @@ module Aspera
               @api_node.delete(one_res_path)
               return Main.result_status("#{one_res_id} deleted")
             when :state
-              return { type: :single_object, data: @api_node.read("#{one_res_path}/state") }
+              return Main.result_single_object(@api_node.read("#{one_res_path}/state"))
             end
           when :central
             command = options.get_next_command(%i[session file])
@@ -997,7 +1017,7 @@ module Aspera
                 resp = @api_node.create('services/rest/transfers/v1/files', request_data)
                 resp = JSON.parse(resp) if resp.is_a?(String)
                 Log.log.debug{Log.dump(:resp, resp)}
-                return { type: :object_list, data: resp['file_transfer_info_result']['file_transfer_info'], fields: %w[session_uuid file_id status path]}
+                return Main.result_object_list(resp['file_transfer_info_result']['file_transfer_info'], fields: %w[session_uuid file_id status path])
               when :modify
                 request_data = options.get_next_argument('request data', mandatory: false, validation: Hash, default: {})
                 request_data.deep_merge!(validation) unless validation.nil?
@@ -1024,32 +1044,143 @@ module Aspera
             return Main.result_status(Api::Node.bearer_token(payload: token_info, access_key: access_key, private_key: private_key))
           when :simulator
             require 'aspera/node_simulator'
-            parameters = value_create_modify(command: command)
-            parameters = parameters.symbolize_keys
-            raise 'Missing key: url' unless parameters.key?(:url)
-            uri = URI.parse(parameters[:url])
-            server = WebServerSimple.new(uri, certificate: parameters[:certificate])
-            server.mount(uri.path, NodeSimulatorServlet, parameters[:credentials], NodeSimulator.new)
+            parameters = value_create_modify(command: command, default: {}).symbolize_keys
+            uri = URI.parse(parameters.delete(:url){WebServerSimple::DEFAULT_URL})
+            server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
+            server.mount(uri.path, NodeSimulatorServlet, parameters.except(*WebServerSimple::PARAMS), NodeSimulator.new)
             server.start
             return Main.result_status('Simulator terminated')
+          when :telemetry
+            parameters = value_create_modify(command: command, default: {}).symbolize_keys
+            %i[url key].each do |psym|
+              raise Cli::BadArgument, "Missing parameter: #{psym}" unless parameters.key?(psym)
+            end
+            require 'socket'
+            parameters[:interval] = 10 unless parameters.key?(:interval)
+            parameters[:hostname] = Socket.gethostname unless parameters.key?(:hostname)
+            interval = parameters[:interval].to_f
+            raise Cli::BadArgument, 'Interval must be a positive number in seconds' if interval <= 0
+            otel_api = Rest.new(
+              base_url: "#{parameters[:url]}/v1",
+              headers: {
+                # 'Authorization'  => "apiToken #{parameters[:key]}",
+                'x-instana-key'  => parameters[:key],
+                'x-instana-host' => parameters[:hostname]
+              }
+            )
+            datapoint = {
+              attributes:   [
+                {
+                  key:   'server.name',
+                  value: {
+                    stringValue: 'HSTS1'
+                  }
+                }
+              ],
+              asInt:        nil,
+              timeUnixNano: nil
+            }
+            # https://opentelemetry.io/docs/specs/otel/metrics/data-model/#gauge
+            metrics = {
+              resourceMetrics: [
+                {
+                  resource:     {
+                    attributes: [
+                      {
+                        key:   'service.name',
+                        value: {
+                          stringValue: 'IBMAspera'
+                        }
+                      }
+                    ]
+                  },
+                  scopeMetrics: [
+                    {
+                      metrics: [
+                        {
+                          name:        'active.transfers',
+                          description: 'Number of active transfers',
+                          unit:        '1',
+                          gauge:       {
+                            dataPoints: [
+                              datapoint
+                            ]
+                          }
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+            loop do
+              timestamp = Time.now
+              transfers_data = call_with_iteration(api: @api_node, operation: 'GET', subpath: 'ops/transfers', query: {active_only: true})
+              datapoint[:asInt] = transfers_data.length
+              datapoint[:timeUnixNano] = timestamp.to_i * 1_000_000_000 + timestamp.nsec
+              Log.log.info("#{datapoint[:asInt]} active transfers")
+              # https://www.ibm.com/docs/en/instana-observability/current?topic=instana-backend
+              otel_api.create('metrics', metrics)
+              break if interval.eql?(0.0)
+              sleep([0.0, interval - (Time.now - timestamp)].max)
+            end
           end
-          raise 'ERROR: shall not reach this line'
+          Aspera.error_unreachable_line
         end
 
         private
 
         # get remaining path arguments from command line, and add prefix
-        def get_all_arguments_with_prefix(path_prefix, name)
+        def get_all_arguments_with_prefix(name)
           path_args = options.get_next_argument(name, multiple: true)
-          return path_args if path_prefix.nil?
-          return path_args.map {|p| File.join(path_prefix, p)}
+          return path_args if @prefix_path.nil?
+          return path_args.map{ |p| File.join(@prefix_path, p)}
         end
 
         # get next path argument from command line, and add prefix
-        def get_one_argument_with_prefix(path_prefix, name)
+        def get_one_argument_with_prefix(name)
           path_arg = options.get_next_argument(name, validation: String)
-          return path_arg if path_prefix.nil?
-          return File.join(path_prefix, path_arg)
+          return path_arg if @prefix_path.nil?
+          return File.join(@prefix_path, path_arg)
+        end
+
+        # Executes the provided API call in loop
+        # @param api [Rest]  the API to call
+        # @param iteration [Array] a single element array with the iteration token or nil
+        # @param max [Integer] maximum number of items to return, or nil for no limit
+        # @param query [Hash] query parameters to use for the API call
+        # @param call_args [Hash] additional arguments to pass to the API call
+        # @return [Array] list of items returned by the API call
+        def call_with_iteration(api:, iteration: nil, max: nil, query: nil, **call_args)
+          query_token = query.clone || {}
+          item_list = []
+          query_token[:iteration_token] = iteration.first if iteration.is_a?(Array)
+          loop do
+            result = api.call(**call_args, query: query_token)
+            Aspera.assert_type(result[:data], Array){"Expected data to be an Array, got: #{result[:data].class}"}
+            # no data
+            break if result[:data].empty?
+            # get next iteration token from link
+            next_iteration_token = nil
+            link_info = result[:http]['Link']
+            unless link_info.nil?
+              m = link_info.match(/<([^>]+)>/)
+              Aspera.assert(m){"Cannot parse iteration in Link: #{link_info}"}
+              next_iteration_token = CGI.parse(URI.parse(m[1]).query)['iteration_token']&.first
+            end
+            # same as last iteration: stop
+            break if next_iteration_token&.eql?(query_token[:iteration_token])
+            query_token[:iteration_token] = next_iteration_token
+            item_list.concat(result[:data])
+            if max&.<=(item_list.length)
+              item_list = item_list.slice(0, max)
+              break
+            end
+            break if next_iteration_token.nil?
+          end
+          # save iteration token if needed
+          iteration[0] = query_token[:iteration_token] unless iteration.nil?
+          item_list
         end
       end
     end