aspera-cli 4.26.2 → 4.27.0

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

@@ -6,6 +6,7 @@ require 'aspera/cli/plugins/node'
 require 'aspera/cli/extended_value'
 require 'aspera/cli/special_values'
 require 'aspera/cli/transfer_agent'
+require 'aspera/transfer/result'
 require 'aspera/transfer/uri'
 require 'aspera/transfer/spec'
 require 'aspera/persistency_action_once'
@@ -22,6 +23,7 @@ module Aspera
   module Cli
     module Plugins
       class Faspex < BasicAuth
+        application_name 'Faspex v4'
         # required hash key for source in config
         KEY_NODE = 'node' # value must be hash with url, username, password
         KEY_PATH = 'path' # value must be same sub-path as in Faspex's node
@@ -94,7 +96,7 @@ module Aspera
           # get Transfer::Uri::SCHEME URI from entry in xml, and fix problems.
           def get_fasp_uri_from_entry(entry, raise_no_link: true)
             unless entry.key?('link')
-              raise Cli::BadArgument, 'package has no link (deleted?)' if raise_no_link
+              Aspera.assert(!raise_no_link, type: Cli::BadArgument){'package has no link (deleted?)'}
               return
             end
             result = entry['link'].find{ |e| e['rel'].eql?('package')}['href']
@@ -123,16 +125,17 @@ module Aspera
           }
         end
 
+        option :link,          description: 'Public link for specific operation'
+        option :delivery_info, description: 'Package delivery information', allowed: Hash
+        option :remote_source, description: 'Remote source for package send (id or %name:)'
+        option :storage,       description: 'Faspex local storage definition (for browsing source)'
+        option :recipient,     description: 'Use if recipient is a dropbox (with *)'
+        option :box,           description: 'Package box', allowed: ATOM_MAILBOXES, default: :inbox
+
         def initialize(**_)
           super
           @api_v3 = nil
           @api_v4 = nil
-          options.declare(:link, 'Public link for specific operation')
-          options.declare(:delivery_info, 'Package delivery information', allowed: Hash)
-          options.declare(:remote_source, 'Remote source for package send (id or %name:)')
-          options.declare(:storage, 'Faspex local storage definition (for browsing source)')
-          options.declare(:recipient, 'Use if recipient is a dropbox (with *)')
-          options.declare(:box, 'Package box', allowed: ATOM_MAILBOXES, default: :inbox)
           options.parse_options!
         end
 
@@ -242,7 +245,7 @@ module Aspera
           delivery_info = package_create_params['delivery']
           # pub link user
           link_data = self.class.get_link_data(public_link_url)
-          raise Cli::BadArgument, "pub link is #{link_data[:subpath]}, expecting external/submissions/new" if !['external/submissions/new', 'external/dropbox_submissions/new'].include?(link_data[:subpath])
+          Aspera.assert_values(link_data[:subpath], ['external/submissions/new', 'external/dropbox_submissions/new'], type: Cli::BadArgument){'pub link subpath'}
           create_path = link_data[:subpath].split('/')[0..-2].join('/')
           package_create_params[:passcode] = link_data[:query]['passcode']
           delivery_info[:transfer_type] = 'connect'
@@ -273,265 +276,299 @@ module Aspera
           return package_creation_data.first
         end
 
-        ACTIONS = %i[health package source me dropbox v4 address_book login_methods].freeze
+        # --- DSL ---
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          case command
-          when :health
-            nagios = Nagios.new
-            begin
-              api_v3.read('me')
-              nagios.add_ok('faspex api', 'accessible')
-            rescue StandardError => e
-              nagios.add_critical('faspex api', e.to_s)
+        command :health,       description: 'Check Faspex 4 API health'
+        command :package,      description: 'Manage packages'
+        command :source,       description: 'Manage sources'
+        command :me,           description: 'Show current user information', action: ->{Result::SingleObject.new(api_v3.read('me'))}
+        command :dropbox,      description: 'Manage dropboxes'
+        command :v4,           description: 'Faspex v4 admin commands'
+        command :address_book, description: 'Show address book'
+        command :login_methods, description: 'Show login methods'
+
+        commands_under(:package) do
+          command :send,    description: 'Send a package'
+          command :receive, description: 'Receive a package', aliases: [:recv]
+          command :list,    description: 'List packages', action: ->{Result::ObjectList.new(mailbox_filtered_entries, fields: [PACKAGE_MATCH_FIELD, 'title', 'items'])}
+          command :show,    description: 'Show a package'
+        end
+
+        commands_under(:source) do
+          command :list, description: 'List sources', action: ->{Result::ObjectList.new(api_v3.read('source_shares')['items'])}
+          command :info, description: 'Show source info', setup: :setup_source_selected, action: ->(source_info:){Result::SingleObject.new(source_info)}
+          command :node, description: 'Execute node commands on source', setup: :setup_source_selected
+        end
+
+        commands_under(%i[source node]) do
+          Node::COMMANDS_FASPEX.each do |cmd|
+            command(cmd, description: "Node #{cmd} command", setup: :setup_source_node)
+          end
+        end
+
+        commands_under(:dropbox) do
+          command :list, description: 'List dropboxes'
+        end
+
+        commands_under(:v4) do
+          entity_command :dropbox, description: 'Manage v4 dropboxes', api: :api_v4, entity: 'admin/dropboxes', display_fields: %w[id e_wg_name e_wg_desc created_at]
+          entity_command :dmembership, description: 'Manage dropbox memberships', api: :api_v4, entity: 'dropbox_memberships'
+          entity_command :workgroup, api: :api_v4, entity: 'admin/workgroups', display_fields: %w[id e_wg_name e_wg_desc created_at]
+          entity_command :wmembership, description: 'Manage workgroup memberships', api: :api_v4, entity: 'workgroup_memberships'
+          entity_command :user, api: :api_v4, entity: 'users', display_fields: %w[id name first_name last_name]
+          entity_command :metadata_profile, description: 'Manage metadata profiles', api: :api_v4, entity: 'metadata_profiles'
+          command :package, description: 'List packages for a box'
+        end
+
+        commands_under(%i[v4 package]) do
+          command :users, description: 'List packages for users'
+        end
+
+        # --- handlers ---
+
+        def action_health
+          nagios = Nagios.new
+          begin
+            api_v3.read('me')
+            nagios.add_ok('faspex api', 'accessible')
+          rescue StandardError => e
+            nagios.add_critical('faspex api', e.to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # package sub-handlers
+
+        def action_package_show
+          delivery_id = options.instance_identifier
+          Result::SingleObject.new(mailbox_filtered_entries(stop_at_id: delivery_id).find{ |p| p[PACKAGE_MATCH_FIELD].eql?(delivery_id)})
+        end
+
+        def action_package_send
+          delivery_info = options.get_option(:delivery_info, mandatory: true)
+          Aspera.assert_type(delivery_info, Hash, type: Cli::BadArgument){'delivery_info'}
+          # actual parameter to faspex API
+          package_create_params = {'delivery' => delivery_info}
+          public_link_url = options.get_option(:link)
+          if public_link_url.nil?
+            # authenticated user
+            delivery_info['sources'] ||= [{'paths' => []}]
+            first_source = delivery_info['sources'].first
+            first_source['paths'].concat(transfer.source_list)
+            source_id = options.get_option(:remote_source)
+            if source_id && (m = Parser.percent_selector(source_id))
+              Aspera.assert_values(m[:field], ['name'], type: Cli::BadArgument){'selector field'}
+              source_list = api_v3.read('source_shares')['items']
+              source_id = self.class.get_source_id_by_name(m[:value], source_list)
             end
-            Result::ObjectList.new(nagios.status_list)
-          when :package
-            command_pkg = options.get_next_command(%i[send receive list show], aliases: {recv: :receive})
-            case command_pkg
-            when :show
-              delivery_id = options.instance_identifier
-              return Result::SingleObject.new(mailbox_filtered_entries(stop_at_id: delivery_id).find{ |p| p[PACKAGE_MATCH_FIELD].eql?(delivery_id)})
-            when :list
-              return Result::ObjectList.new(mailbox_filtered_entries, fields: [PACKAGE_MATCH_FIELD, 'title', 'items'])
-            when :send
-              delivery_info = options.get_option(:delivery_info, mandatory: true)
-              Aspera.assert_type(delivery_info, Hash, type: Cli::BadArgument){'delivery_info'}
-              # actual parameter to faspex API
-              package_create_params = {'delivery' => delivery_info}
-              public_link_url = options.get_option(:link)
-              if public_link_url.nil?
-                # authenticated user
-                delivery_info['sources'] ||= [{'paths' => []}]
-                first_source = delivery_info['sources'].first
-                first_source['paths'].concat(transfer.source_list)
-                source_id = options.get_option(:remote_source)
-                if source_id && (m = Manager.percent_selector(source_id))
-                  Aspera.assert_values(m[:field], ['name'], type: Cli::BadArgument){'selector field'}
-                  source_list = api_v3.read('source_shares')['items']
-                  source_id = self.class.get_source_id_by_name(m[:value], source_list)
-                end
-                first_source['id'] = source_id.to_i unless source_id.nil?
-                pkg_created = api_v3.create('send', package_create_params)
-                if first_source.key?('id')
-                  # no transfer spec if remote source: handled by faspex
-                  return Result::ValueList.new([pkg_created['links']['status']], name: 'link')
-                end
-                raise Cli::BadArgument, 'expecting one session exactly' if pkg_created['xfer_sessions'].length != 1
-                transfer_spec = pkg_created['xfer_sessions'].first
-                # use source from cmd line, this one only contains destination (already in dest root)
-                transfer_spec.delete('paths')
-              else # public link
-                transfer_spec = send_public_link_to_ts(public_link_url, package_create_params)
-              end
-              # Log.dump(:transfer_spec,transfer_spec)
-              return Runner.result_transfer(transfer.start(transfer_spec))
-            when :receive
-              link_url = options.get_option(:link)
-              # list of faspex ID/URI to download
-              pkg_id_uri = nil
-              skip_ids_data = []
-              skip_ids_persistency = nil
-              case link_url
-              when nil # usual case: no link
-                if options.get_option(:once_only, mandatory: true)
-                  skip_ids_persistency = PersistencyActionOnce.new(
-                    manager: persistency,
-                    data:    skip_ids_data,
-                    id:      IdGenerator.from_list(
-                      'faspex_recv',
-                      options.get_option(:url, mandatory: true),
-                      options.get_option(:username, mandatory: true),
-                      options.get_option(:box, mandatory: true).to_s
-                    )
-                  )
-                end
-                # get command line parameters
-                delivery_id = options.instance_identifier
-                Aspera.assert(!delivery_id.empty?, 'empty id')
-                recipient = options.get_option(:recipient)
-                if delivery_id.eql?(SpecialValues::ALL)
-                  pkg_id_uri = mailbox_filtered_entries.map{ |i| {id: i[PACKAGE_MATCH_FIELD], uri: self.class.get_fasp_uri_from_entry(i, raise_no_link: false)}}
-                elsif delivery_id.eql?(SpecialValues::INIT)
-                  Aspera.assert(skip_ids_persistency, 'Only with option once_only')
-                  skip_ids_persistency.data.clear.concat(mailbox_filtered_entries.map{ |i| {id: i[PACKAGE_MATCH_FIELD]}})
-                  skip_ids_persistency.save
-                  return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
-                elsif !recipient.nil? && recipient.start_with?('*')
-                  found_package_link = mailbox_filtered_entries(stop_at_id: delivery_id).find{ |p| p[PACKAGE_MATCH_FIELD].eql?(delivery_id)}['link'].first['href']
-                  raise "Not Found. Dropbox and Workgroup packages can use the link option with #{Transfer::Uri::SCHEME}" if found_package_link.nil?
-                  pkg_id_uri = [{id: delivery_id, uri: found_package_link}]
-                else
-                  # TODO: delivery id is the right one if package was receive by workgroup
-                  endpoint =
-                    case options.get_option(:box, mandatory: true)
-                    when :inbox, :archive then'received'
-                    when :sent then 'sent'
-                    end
-                  entry_xml = api_v3.call(operation: 'GET', subpath: "#{endpoint}/#{delivery_id}", headers: {'Accept' => 'application/xml'}, ret: :resp).body
-                  package_entry = XmlSimple.xml_in(entry_xml, {'ForceArray' => true})
-                  pkg_id_uri = [{id: delivery_id, uri: self.class.get_fasp_uri_from_entry(package_entry)}]
-                end
-              when /^#{Transfer::Uri::SCHEME}:/o
-                pkg_id_uri = [{id: 'package', uri: link_url}]
-              else
-                link_data = self.class.get_link_data(link_url)
-                raise Cli::BadArgument, "Pub link is #{link_data[:subpath]}. Expecting #{PUB_LINK_EXTERNAL_MATCH}" if !link_data[:subpath].start_with?(PUB_LINK_EXTERNAL_MATCH)
-                # NOTE: unauthenticated API (authorization is in url params)
-                api_public_link = Rest.new(base_url: link_data[:base_url])
-                pkg_xml = api_public_link.call(
-                  operation: 'GET',
-                  subpath:   link_data[:subpath],
-                  headers:   {'Accept' => 'application/xml'},
-                  query:     {passcode: link_data[:query]['passcode']},
-                  ret:       :resp
-                ).body
-                if !pkg_xml.start_with?('<?xml ')
-                  Environment.instance.open_uri(link_url)
-                  raise Cli::Error, 'Unexpected response: package not found ?'
-                end
-                package_entry = XmlSimple.xml_in(pkg_xml, {'ForceArray' => false})
-                Log.dump(:package_entry, package_entry)
-                transfer_uri = self.class.get_fasp_uri_from_entry(package_entry)
-                pkg_id_uri = [{id: package_entry['id'], uri: transfer_uri}]
-              end
-              # prune packages already downloaded
-              # TODO : remove ids from skip not present in inbox to avoid growing too big
-              # skip_ids_data.select!{|id|pkg_id_uri.select{|p|p[:id].eql?(id)}}
-              pkg_id_uri.reject!{ |i| skip_ids_data.include?(i[:id])}
-              Log.dump(:pkg_id_uri, pkg_id_uri)
-              return Result::Status.new('no new package') if pkg_id_uri.empty?
-              result_transfer = []
-              pkg_id_uri.each do |id_uri|
-                if id_uri[:uri].nil?
-                  # skip package with no link: empty or content deleted
-                  statuses = [:success]
-                else
-                  transfer_spec = Transfer::Uri.new(id_uri[:uri]).transfer_spec
-                  # NOTE: only external users have token in Transfer::Uri::SCHEME link !
-                  if !transfer_spec.key?('token')
-                    sanitized = id_uri[:uri].gsub('&', '&amp;')
-                    xml_payload =
-                      %Q(<?xml version="1.0" encoding="UTF-8"?><url-list xmlns="http://schemas.asperasoft.com/xml/url-list"><url href="#{sanitized}"/></url-list>)
-                    transfer_spec['token'] = api_v3.call(
-                      operation:    'POST',
-                      subpath:      'issue-token',
-                      query:        {'direction' => 'down'},
-                      content_type: Mime::TEXT,
-                      body:         xml_payload,
-                      headers:      {'Accept' => Mime::TEXT, 'Content-Type' => 'application/vnd.aspera.url-list+xml'},
-                      ret:          :resp
-                    ).body
-                  end
-                  transfer_spec['direction'] = Transfer::Spec::DIRECTION_RECEIVE
-                  statuses = transfer.start(transfer_spec)
-                end
-                result_transfer.push({'package' => id_uri[:id], Runner::STATUS_FIELD => statuses})
-                # skip only if all sessions completed
-                skip_ids_data.push(id_uri[:id]) if TransferAgent.session_status(statuses).eql?(:success)
-              end
-              skip_ids_persistency&.save
-              return Runner.result_transfer_multiple(result_transfer)
+            first_source['id'] = source_id.to_i unless source_id.nil?
+            pkg_created = api_v3.create('send', package_create_params)
+            if first_source.key?('id')
+              # no transfer spec if remote source: handled by faspex
+              return Result::ValueList.new([pkg_created['links']['status']], name: 'link')
             end
-          when :source
-            command_source = options.get_next_command(%i[list info node])
-            source_list = api_v3.read('source_shares')['items']
-            case command_source
-            when :list
-              return Result::ObjectList.new(source_list)
-            else # :info :node
-              source_id = options.instance_identifier do |field, value|
-                Aspera.assert_values(field, ['name'], type: Cli::BadArgument){'selector field'}
-                self.class.get_source_id_by_name(value, source_list)
-              end.to_i
-              selected_source = source_list.find{ |i| i['id'].eql?(source_id)}
-              raise BadArgument, 'No such source' if selected_source.nil?
-              source_name = selected_source['name']
-              source_hash = options.get_option(:storage, mandatory: true)
-              # check value of option
-              Aspera.assert_type(source_hash, Hash, type: Cli::Error){'storage option'}
-              source_hash.each do |name, storage|
-                Aspera.assert_type(storage, Hash, type: Cli::Error){"storage '#{name}'"}
-                [KEY_NODE, KEY_PATH].each do |key|
-                  Aspera.assert(storage.key?(key), type: Cli::Error){"storage '#{name}' must have a '#{key}'"}
-                end
-              end
-              raise Cli::Error, "No such storage in config file: \"#{source_name}\" in [#{source_hash.keys.join(', ')}]" if !source_hash.key?(source_name)
-              source_info = source_hash[source_name]
-              Log.dump(:source_info, source_info)
-              case command_source
-              when :info
-                return Result::SingleObject.new(source_info)
-              when :node
-                node_config = ExtendedValue.instance.evaluate(source_info[KEY_NODE], context: 'faspex node')
-                Log.log.debug{"node=#{node_config}"}
-                Aspera.assert_type(node_config, Hash, type: Cli::Error){source_info[KEY_NODE]}
-                api_node = Rest.new(
-                  base_url: node_config['url'],
-                  auth:     {
-                    type:     :basic,
-                    username: node_config['username'],
-                    password: node_config['password']
-                  }
+            Aspera.assert(pkg_created['xfer_sessions'].length == 1, type: Cli::BadArgument){'expecting one session exactly'}
+            transfer_spec = pkg_created['xfer_sessions'].first
+            # use source from cmd line, this one only contains destination (already in dest root)
+            transfer_spec.delete('paths')
+          else # public link
+            transfer_spec = send_public_link_to_ts(public_link_url, package_create_params)
+          end
+          # Log.dump(:transfer_spec,transfer_spec)
+          return Runner.result_transfer(transfer.start(transfer_spec))
+        end
+
+        def action_package_receive
+          link_url = options.get_option(:link)
+          # list of faspex ID/URI to download
+          pkg_id_uri = nil
+          skip_ids_data = []
+          skip_ids_persistency = nil
+          case link_url
+          when nil # usual case: no link
+            if options.get_option(:once_only, mandatory: true)
+              skip_ids_persistency = PersistencyActionOnce.new(
+                manager: persistency,
+                data:    skip_ids_data,
+                id:      IdGenerator.from_list(
+                  'faspex_recv',
+                  options.get_option(:url, mandatory: true),
+                  options.get_option(:username, mandatory: true),
+                  options.get_option(:box, mandatory: true).to_s
                 )
-                command = options.get_next_command(Node::COMMANDS_FASPEX)
-                return Node.new(context: context, api: api_node, prefix_path: source_info[KEY_PATH]).execute_action(command)
-              end
+              )
             end
-          when :me
-            my_info = api_v3.read('me')
-            return Result::SingleObject.new(my_info)
-          when :dropbox
-            command_pkg = options.get_next_command([:list])
-            case command_pkg
-            when :list
-              dropbox_list = api_v3.read('dropboxes')
-              return Result::ObjectList.new(dropbox_list['items'], fields: %w[name id description can_read can_write])
+            # get command line parameters
+            delivery_id = options.instance_identifier
+            Aspera.assert(!delivery_id.empty?, 'empty id')
+            recipient = options.get_option(:recipient)
+            if delivery_id.eql?(SpecialValues::ALL)
+              pkg_id_uri = mailbox_filtered_entries.map{ |i| {id: i[PACKAGE_MATCH_FIELD], uri: self.class.get_fasp_uri_from_entry(i, raise_no_link: false)}}
+            elsif delivery_id.eql?(SpecialValues::INIT)
+              Aspera.assert(skip_ids_persistency, 'Only with option once_only')
+              skip_ids_persistency.data.clear.concat(mailbox_filtered_entries.map{ |i| {id: i[PACKAGE_MATCH_FIELD]}})
+              skip_ids_persistency.save
+              return Result::Status.new("Initialized skip for #{skip_ids_persistency.data.count} package(s)")
+            elsif !recipient.nil? && recipient.start_with?('*')
+              found_package_link = mailbox_filtered_entries(stop_at_id: delivery_id).find{ |p| p[PACKAGE_MATCH_FIELD].eql?(delivery_id)}['link'].first['href']
+              raise "Not Found. Dropbox and Workgroup packages can use the link option with #{Transfer::Uri::SCHEME}" if found_package_link.nil?
+              pkg_id_uri = [{id: delivery_id, uri: found_package_link}]
+            else
+              # TODO: delivery id is the right one if package was receive by workgroup
+              endpoint =
+                case options.get_option(:box, mandatory: true)
+                when :inbox, :archive then 'received'
+                when :sent then 'sent'
+                end
+              entry_xml = api_v3.call(operation: 'GET', subpath: "#{endpoint}/#{delivery_id}", headers: {'Accept' => 'application/xml'}, ret: :resp).body
+              package_entry = XmlSimple.xml_in(entry_xml, {'ForceArray' => true})
+              pkg_id_uri = [{id: delivery_id, uri: self.class.get_fasp_uri_from_entry(package_entry)}]
             end
-          when :v4
-            command = options.get_next_command(%i[package dropbox dmembership workgroup wmembership user metadata_profile])
-            case command
-            when :dropbox
-              return entity_execute(api: api_v4, entity: 'admin/dropboxes', display_fields: %w[id e_wg_name e_wg_desc created_at])
-            when :dmembership
-              return entity_execute(api: api_v4, entity: 'dropbox_memberships')
-            when :workgroup
-              return entity_execute(api: api_v4, entity: 'admin/workgroups', display_fields: %w[id e_wg_name e_wg_desc created_at])
-            when :wmembership
-              return entity_execute(api: api_v4, entity: 'workgroup_memberships')
-            when :user
-              return entity_execute(api: api_v4, entity: 'users', display_fields: %w[id name first_name last_name])
-            when :metadata_profile
-              return entity_execute(api: api_v4, entity: 'metadata_profiles')
-            when :package
-              pkg_box_type = options.get_next_command([:users])
-              pkg_box_id = options.instance_identifier
-              return entity_execute(api: api_v4, entity: "#{pkg_box_type}/#{pkg_box_id}/packages")
+          when /^#{Transfer::Uri::SCHEME}:/o
+            pkg_id_uri = [{id: 'package', uri: link_url}]
+          else
+            link_data = self.class.get_link_data(link_url)
+            Aspera.assert(link_data[:subpath].start_with?(PUB_LINK_EXTERNAL_MATCH), type: Cli::BadArgument){"Pub link is #{link_data[:subpath]}. Expecting #{PUB_LINK_EXTERNAL_MATCH}"}
+            # NOTE: unauthenticated API (authorization is in url params)
+            api_public_link = Rest.new(base_url: link_data[:base_url])
+            pkg_xml = api_public_link.call(
+              operation: 'GET',
+              subpath:   link_data[:subpath],
+              headers:   {'Accept' => 'application/xml'},
+              query:     {passcode: link_data[:query]['passcode']},
+              ret:       :resp
+            ).body
+            if !pkg_xml.start_with?('<?xml ')
+              Environment.instance.open_uri(link_url)
+              raise Cli::Error, 'Unexpected response: package not found ?'
             end
-          when :address_book
-            result = api_v3.read('address-book', {'format' => 'json', 'count' => 100_000})
-            formatter.display_status("users: #{result['itemsPerPage']}/#{result['totalResults']}, start:#{result['startIndex']}")
-            users = result['entry']
-            # add missing entries
-            users.each do |u|
-              unless u['emails'].nil?
-                email = u['emails'].find{ |i| i['primary'].eql?('true')}
-                u['email'] = email['value'] unless email.nil?
-              end
-              if u['email'].nil?
-                Log.log.warn{"Skip user without email: #{u}"}
-                next
+            package_entry = XmlSimple.xml_in(pkg_xml, {'ForceArray' => false})
+            Log.dump(:package_entry, package_entry)
+            transfer_uri = self.class.get_fasp_uri_from_entry(package_entry)
+            pkg_id_uri = [{id: package_entry['id'], uri: transfer_uri}]
+          end
+          # prune packages already downloaded
+          # TODO : remove ids from skip not present in inbox to avoid growing too big
+          # skip_ids_data.select!{|id|pkg_id_uri.select{|p|p[:id].eql?(id)}}
+          pkg_id_uri.reject!{ |i| skip_ids_data.include?(i[:id])}
+          Log.dump(:pkg_id_uri, pkg_id_uri)
+          return Result::Status.new('no new package') if pkg_id_uri.empty?
+          result_transfer = []
+          pkg_id_uri.each do |id_uri|
+            if id_uri[:uri].nil?
+              # skip package with no link: empty or content deleted
+              statuses = Transfer::Result.success
+            else
+              transfer_spec = Transfer::Uri.new(id_uri[:uri]).transfer_spec
+              # NOTE: only external users have token in Transfer::Uri::SCHEME link !
+              if !transfer_spec.key?('token')
+                sanitized = id_uri[:uri].gsub('&', '&amp;')
+                xml_payload =
+                  %Q(<?xml version="1.0" encoding="UTF-8"?><url-list xmlns="http://schemas.asperasoft.com/xml/url-list"><url href="#{sanitized}"/></url-list>)
+                transfer_spec['token'] = api_v3.call(
+                  operation:    'POST',
+                  subpath:      'issue-token',
+                  query:        {'direction' => 'down'},
+                  content_type: Mime::TEXT,
+                  body:         xml_payload,
+                  headers:      {'Accept' => Mime::TEXT, 'Content-Type' => 'application/vnd.aspera.url-list+xml'},
+                  ret:          :resp
+                ).body
               end
-              u['first_name'], u['last_name'] = u['displayName'].split(' ', 2)
-              u['x'] = true
+              transfer_spec['direction'] = Transfer::Spec::DIRECTION_RECEIVE
+              statuses = transfer.start(transfer_spec)
             end
-            return Result::ObjectList.new(users)
-          when :login_methods
-            login_meths = api_v3.call(operation: 'GET', subpath: 'login/new', headers: {'Accept' => 'application/xrds+xml'}, ret: :resp).body
-            login_methods = XmlSimple.xml_in(login_meths, {'ForceArray' => false})
-            return Result::ObjectList.new(login_methods['XRD']['Service'])
+            result_transfer.push({'package' => id_uri[:id], Runner::STATUS_FIELD => statuses})
+            # skip only if all sessions completed
+            skip_ids_data.push(id_uri[:id]) if statuses.is_a?(Transfer::Result::Success)
           end
+          skip_ids_persistency&.save
+          return Runner.result_transfer_multiple(result_transfer)
+        end
+
+        # Resolve a source by id/name and validate the storage option.
+        # @return [Hash] ctx with :source_info and :source_node_plugin
+        def setup_source_selected(**)
+          source_list = api_v3.read('source_shares')['items']
+          source_id = options.instance_identifier do |field, value|
+            Aspera.assert_values(field, ['name'], type: Cli::BadArgument){'selector field'}
+            self.class.get_source_id_by_name(value, source_list)
+          end.to_i
+          selected_source = source_list.find{ |i| i['id'].eql?(source_id)}
+          Aspera.assert(!selected_source.nil?, type: BadArgument){'No such source'}
+          source_name = selected_source['name']
+          source_hash = options.get_option(:storage, mandatory: true)
+          Aspera.assert_type(source_hash, Hash, type: Cli::Error){'storage option'}
+          source_hash.each do |name, storage|
+            Aspera.assert_type(storage, Hash, type: Cli::Error){"storage '#{name}'"}
+            [KEY_NODE, KEY_PATH].each do |key|
+              Aspera.assert(storage.key?(key), type: Cli::Error){"storage '#{name}' must have a '#{key}'"}
+            end
+          end
+          Aspera.assert(source_hash.key?(source_name), type: Cli::Error){"No such storage in config file: \"#{source_name}\" in [#{source_hash.keys.join(', ')}]"}
+          {source_info: source_hash[source_name]}
+        end
+
+        # source > node sub-handlers: one per COMMANDS_FASPEX
+        # setup_source_selected injects :source_info; setup_source_node builds the Node plugin.
+        def setup_source_node(source_info:, **)
+          Log.dump(:source_info, source_info)
+          node_config = ExtendedValue.instance.evaluate(source_info[KEY_NODE], context: 'faspex node')
+          Log.log.debug{"node=#{node_config}"}
+          Aspera.assert_type(node_config, Hash, type: Cli::Error){source_info[KEY_NODE]}
+          api_node = Rest.new(
+            base_url: node_config['url'],
+            auth:     {
+              type:     :basic,
+              username: node_config['username'],
+              password: node_config['password']
+            }
+          )
+          {source_node_plugin: Node.new(context: context, api: api_node, prefix_path: source_info[KEY_PATH])}
+        end
+
+        Node::COMMANDS_FASPEX.each do |cmd|
+          define_action_method([:source, :node, cmd]) do |source_node_plugin:, **|
+            source_node_plugin.dispatch_v3_command(cmd)
+          end
+        end
+
+        # dropbox sub-handler
+
+        def action_dropbox_list
+          dropbox_list = api_v3.read('dropboxes')
+          Result::ObjectList.new(dropbox_list['items'], fields: %w[name id description can_read can_write])
+        end
+
+        def action_v4_package_users
+          pkg_box_id = options.instance_identifier
+          entity_execute(api: api_v4, entity: "users/#{pkg_box_id}/packages", command: :list)
+        end
+
+        def action_address_book
+          result = api_v3.read('address-book', {'format' => 'json', 'count' => 100_000})
+          formatter.display_status("users: #{result['itemsPerPage']}/#{result['totalResults']}, start:#{result['startIndex']}")
+          users = result['entry']
+          # add missing entries
+          users.each do |u|
+            unless u['emails'].nil?
+              email = u['emails'].find{ |i| i['primary'].eql?('true')}
+              u['email'] = email['value'] unless email.nil?
+            end
+            if u['email'].nil?
+              Log.log.warn{"Skip user without email: #{u}"}
+              next
+            end
+            u['first_name'], u['last_name'] = u['displayName'].split(' ', 2)
+            u['x'] = true
+          end
+          return Result::ObjectList.new(users)
+        end
+
+        def action_login_methods
+          login_meths = api_v3.call(operation: 'GET', subpath: 'login/new', headers: {'Accept' => 'application/xrds+xml'}, ret: :resp).body
+          login_methods = XmlSimple.xml_in(login_meths, {'ForceArray' => false})
+          return Result::ObjectList.new(login_methods['XRD']['Service'])
         end
       end
     end