aspera-cli 4.16.0 → 4.17.0

data/bin/asession

@@ -3,16 +3,18 @@
 
 # Laurent Martin/2017
 $LOAD_PATH.unshift("#{File.dirname(__FILE__)}/../lib")
-require 'aspera/fasp/agent_direct'
+require 'aspera/agent/direct'
 require 'aspera/cli/extended_value'
+require 'aspera/ascp/installation'
 require 'aspera/log'
 require 'json'
 # extended transfer spec parameter (only used in asession)
 # Change log level
-TS_LOG_LEVEL = 'EX_loglevel'
+PARAM_LOG_LEVEL = 'loglevel'
 # by default go to /tmp/username.filelist
-TS_TMP_FILE_LIST_FOLDER = 'EX_file_list_folder'
-
+PARAM_TMP_FILE_LIST_FOLDER = 'file_list_folder'
+# place transfer spec in that
+PARAM_SPEC = 'spec'
 SAMPLE_DEMO = '"remote_host":"demo.asperasoft.com","remote_user":"asperaweb","ssh_port":33001,"remote_password":"demoaspera"'
 SAMPLE_DEMO2 = '"direction":"receive","destination_root":"./test.dir"'
 def assert_usage(assertion, error_message)
@@ -21,25 +23,27 @@ def assert_usage(assertion, error_message)
   $stderr.puts('USAGE')
   $stderr.puts('    asession')
   $stderr.puts('    asession -h|--help')
-  $stderr.puts('    asession <transfer spec extended value>')
+  $stderr.puts('    asession <session spec extended value>')
   $stderr.puts('    ')
   $stderr.puts('    If no argument is provided, default will be used: @json:@stdin')
   $stderr.puts('    -h, --help display this message')
-  $stderr.puts('    <transfer spec extended value> a JSON value for transfer_spec, using the prefix: @json:')
+  $stderr.puts('    <session spec extended value> a dictionary value (Hash)')
   $stderr.puts('    The value can be either:')
   $stderr.puts("       the JSON description itself, e.g. @json:'{\"xx\":\"yy\",...}'")
   $stderr.puts('       @json:@stdin, if the JSON is provided from stdin')
   $stderr.puts('       @json:@file:<path>, if the JSON is provided from a file')
+  $stderr.puts("    Parameter #{PARAM_SPEC} is mandatory, it contains the transfer spec")
   $stderr.puts('    Asynchronous commands can be provided on STDIN, examples:')
   $stderr.puts('       {"type":"START","source":"/aspera-test-dir-tiny/200KB.2"}')
   $stderr.puts('       {"type":"START","source":"xx","destination":"yy"}')
   $stderr.puts('       {"type":"DONE"}')
-  $stderr.puts(%Q(Note: debug information can be placed on STDERR, using the "#{TS_LOG_LEVEL}" parameter in transfer spec (debug=0)))
+  $stderr.puts(%Q(Note: debug information can be placed on STDERR, using the "#{PARAM_LOG_LEVEL}" parameter in session spec (debug=0)))
   $stderr.puts('EXAMPLES')
-  $stderr.puts(%Q(    asession @json:'{#{SAMPLE_DEMO},#{SAMPLE_DEMO2},"paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}'))
-  $stderr.puts(%q(    echo '{"remote_host":...}'|asession @json:@stdin))
+  $stderr.puts(%Q(    asession @json:'{"#{PARAM_SPEC}":{#{SAMPLE_DEMO},#{SAMPLE_DEMO2},"paths":[{"source":"/aspera-test-dir-tiny/200KB.1"}]}}'))
+  $stderr.puts(%Q(    echo '{"#{PARAM_SPEC}":{"remote_host":...}}'|asession @json:@stdin))
   Process.exit(1)
 end
+Aspera::Ascp::Installation.instance.sdk_folder = File.join(Dir.home, '.aspera', 'sdk')
 
 parameter_source_err_msg = ' (argument), did you specify: "@json:" ?'
 # by default assume JSON input on stdin if no argument
@@ -52,27 +56,31 @@ assert_usage(ARGV.length.eql?(1), 'exactly one argument is expected')
 assert_usage(!['-h', '--help'].include?(ARGV.first), nil)
 # parse transfer spec
 begin
-  transfer_spec_arg = ARGV.pop
-  transfer_spec = Aspera::Cli::ExtendedValue.instance.evaluate(transfer_spec_arg)
+  session_argument = ARGV.pop
+  session_spec = Aspera::Cli::ExtendedValue.instance.evaluate(session_argument)
 rescue
-  assert_usage(false, "Cannot extract transfer spec from: #{transfer_spec_arg}")
+  assert_usage(false, "Cannot parse argument: #{session_argument}")
 end
 # ensure right type
-assert_usage(transfer_spec.is_a?(Hash), "the value must be a hash table#{parameter_source_err_msg}")
+assert_usage(session_spec.is_a?(Hash), "The value must be a hash table#{parameter_source_err_msg}")
+assert_usage(session_spec[PARAM_SPEC].is_a?(Hash), "the value must contain key #{PARAM_SPEC}")
 # additional debug capability
-if transfer_spec.key?(TS_LOG_LEVEL)
-  Aspera::Log.instance.level = transfer_spec[TS_LOG_LEVEL]
-  transfer_spec.delete(TS_LOG_LEVEL)
+if session_spec.key?(PARAM_LOG_LEVEL)
+  Aspera::Log.instance.level = session_spec[PARAM_LOG_LEVEL]
 end
 # possibly override temp folder
-if transfer_spec.key?(TS_TMP_FILE_LIST_FOLDER)
-  Aspera::Fasp::Parameters.file_list_folder = transfer_spec[TS_TMP_FILE_LIST_FOLDER]
-  transfer_spec.delete(TS_TMP_FILE_LIST_FOLDER)
+if session_spec.key?(PARAM_TMP_FILE_LIST_FOLDER)
+  Aspera::Transfer::Parameters.file_list_folder = session_spec[PARAM_TMP_FILE_LIST_FOLDER]
+end
+session_spec['agent'] = {} unless session_spec.key?('agent')
+session_spec['agent']['quiet'] = true
+session_spec['agent']['management_cb'] = ->(event) do
+  puts JSON.generate(Aspera::Ascp::Management.enhanced_event_format(event))
 end
 # get local agent (ascp), disable ascp output on stdout to not mix with JSON events
-client = Aspera::Fasp::AgentDirect.new({quiet: true})
+client = Aspera::Agent::Direct.new(session_spec['agent'])
 # start transfer (asynchronous)
-job_id = client.start_transfer(transfer_spec)
+job_id = client.start_transfer(session_spec[PARAM_SPEC])
 # async commands
 Thread.new do
   # we assume here a single session

data/lib/aspera/{fasp/agent_alpha.rb → agent/alpha.rb}

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require 'aspera/fasp/agent_base'
+require 'aspera/agent/base'
 require 'aspera/rest'
 require 'aspera/log'
 require 'aspera/json_rpc'
@@ -8,12 +8,14 @@ require 'aspera/open_application'
 require 'securerandom'
 
 module Aspera
-  module Fasp
-    class AgentAlpha < Aspera::Fasp::AgentBase
+  module Agent
+    class Alpha < Base
       # try twice the main init url in sequence
-      START_URIS = ['aspera://']
-      # delay between each try to start connect
-      SLEEP_SEC_BETWEEN_RETRY = 3
+      START_URIS = ['aspera://', 'aspera://', 'aspera://']
+      # delay between each try to start the app
+      SLEEP_SEC_BETWEEN_RETRY = 5
+      APP_IDENTIFIER = 'com.ibm.software.aspera.desktop'
+      APP_NAME = 'Aspera Desktop Alpha Client'
       private_constant :START_URIS, :SLEEP_SEC_BETWEEN_RETRY
       def initialize(options)
         @application_id = SecureRandom.uuid
@@ -21,35 +23,32 @@ module Aspera
         raise 'Using client requires a graphical environment' if !OpenApplication.default_gui_mode.eql?(:graphical)
         method_index = 0
         begin
+          # curl 'http://127.0.0.1:33024/' -X POST -H 'content-type: application/json' --data-raw '{"jsonrpc":"2.0","params":[],"id":999999,"method":"rpc.discover"}'
+          # https://playground.open-rpc.org/?schemaUrl=http://127.0.0.1:33024
           @client_app_api = Aspera::JsonRpcClient.new(Aspera::Rest.new(base_url: aspera_client_api_url))
           client_info = @client_app_api.get_info
           Log.log.debug{Log.dump(:client_version, client_info)}
-          # my_transfer_id = '0513fe85-65cf-465b-ad5f-18fd40d8c69f'
-          # @client_app_api.get_all_transfers({app_id: @application_id})
-          # @client_app_api.get_transfer(app_id: @application_id, transfer_id: my_transfer_id)
-          # @client_app_api.start_transfer(app_id: @application_id,transfer_spec: {})
-          # @client_app_api.remove_transfer
-          # @client_app_api.stop_transfer
-          # @client_app_api.modify_transfer
-          # @client_app_api.show_directory({app_id: @application_id, transfer_id: my_transfer_id})
-          # @client_app_api.get_files_list({app_id: @application_id, transfer_id: my_transfer_id})
           Log.log.info('Client was reached') if method_index > 0
-        rescue StandardError => e # Errno::ECONNREFUSED
+        rescue Errno::ECONNREFUSED => e
           start_url = START_URIS[method_index]
           method_index += 1
-          raise StandardError, "Unable to start connect #{method_index} times" if start_url.nil?
-          Log.log.warn{"Aspera Connect is not started (#{e}). Trying to start it ##{method_index}..."}
+          raise StandardError, "Unable to start #{APP_NAME} #{method_index} times" if start_url.nil?
+          Log.log.warn{"#{APP_NAME} is not started (#{e}). Trying to start it ##{method_index}..."}
           if !OpenApplication.uri_graphical(start_url)
-            OpenApplication.uri_graphical('https://downloads.asperasoft.com/connect2/')
-            raise StandardError, 'Connect is not installed'
+            OpenApplication.uri_graphical('https://www.ibm.com/aspera/connect/')
+            raise StandardError, "#{APP_NAME} is not installed"
           end
           sleep(SLEEP_SEC_BETWEEN_RETRY)
           retry
         end
       end
 
+      def sdk_log_file
+        File.join(Dir.home, 'Library', 'Logs', APP_IDENTIFIER, 'ibm-aspera-desktop.log')
+      end
+
       def aspera_client_api_url
-        log_file = File.join(Dir.home, 'Library', 'Logs', 'IBM Aspera', 'ibm-aspera-desktop.log')
+        log_file = sdk_log_file
         url = nil
         File.open(log_file, 'r') do |file|
           file.each_line do |line|
@@ -59,12 +58,14 @@ module Aspera
             end
           end
         end
+        url = 'http://127.0.0.1:33024' if url.nil?
+        raise StandardError, "Unable to find the JSON-RPC server URL in #{log_file}" if url.nil?
         return url
       end
 
       def start_transfer(transfer_spec, token_regenerator: nil)
         @request_id = SecureRandom.uuid
-        # if there is a token, we ask connect client to use well known ssh private keys
+        # if there is a token, we ask the client app to use well known ssh private keys
         # instead of asking password
         transfer_spec['authentication'] = 'token' if transfer_spec.key?('token')
         result = @client_app_api.start_transfer(app_id: @application_id, desktop_spec: {}, transfer_spec: transfer_spec)
@@ -96,13 +97,13 @@ module Aspera
               break
             when 'failed'
               notify_progress(type: :end, session_id: @xfer_id)
-              raise Fasp::Error, transfer['error_desc']
+              raise Transfer::Error, transfer['error_desc']
             when 'cancelled'
               notify_progress(type: :end, session_id: @xfer_id)
-              raise Fasp::Error, 'Transfer cancelled by user'
+              raise Transfer::Error, 'Transfer cancelled by user'
             else
               notify_progress(type: :end, session_id: @xfer_id)
-              raise Fasp::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
+              raise Transfer::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
             end
             sleep(1)
           end

data/lib/aspera/{fasp/agent_base.rb → agent/base.rb}

@@ -3,16 +3,17 @@
 require 'aspera/log'
 require 'aspera/assert'
 module Aspera
-  module Fasp
+  module Agent
     # Base class for transfer agents
-    class AgentBase
+    class Base
+      RUBY_EXT = '.rb'
       class << self
         # compute options from user provided and default options
         def options(default:, options:)
           result = options.symbolize_keys
           available = default.map{|k, v|"#{k}(#{v})"}.join(', ')
-          result.each do |k, _v|
-            assert_values(k, default.keys){"transfer agent parameter: #{k}"}
+          result.each_key do |k|
+            Aspera.assert_values(k, default.keys){"transfer agent parameter: #{k}"}
             # check it is the expected type: too limiting, as we can have an Integer or Float, or symbol and string
             # raise "Invalid value for transfer agent parameter: #{k}, expect #{default[k].class.name}" unless default[k].nil? || v.is_a?(default[k].class)
           end
@@ -23,18 +24,20 @@ module Aspera
           return result
         end
 
+        # discover available agents
         def agent_list
+          base_class = File.basename(__FILE__)
           Dir.entries(File.dirname(File.expand_path(__FILE__))).select do |file|
-            file.start_with?('agent_') && !file.eql?('agent_base.rb')
-          end.map{|file|file.sub(/^agent_/, '').sub(/\.rb$/, '').to_sym}
+            file.end_with?(RUBY_EXT) && !file.eql?(base_class)
+          end.map{|file|file[0..(-1 - RUBY_EXT.length)].to_sym}
         end
-    end
+      end
       def wait_for_completion
         # list of: :success or "error message string"
         statuses = wait_for_transfers_completion
         @progress&.reset
-        assert_type(statuses, Array)
-        assert(statuses.select{|i|!i.eql?(:success) && !i.is_a?(StandardError)}.empty?){"bad statuses content: #{statuses}"}
+        Aspera.assert_type(statuses, Array)
+        Aspera.assert(statuses.none?{|i|!i.eql?(:success) && !i.is_a?(StandardError)}){"bad statuses content: #{statuses}"}
         return statuses
       end
 
@@ -42,9 +45,9 @@ module Aspera
 
       def initialize(options)
         # method `shutdown` is optional
-        assert(respond_to?(:start_transfer))
-        assert(respond_to?(:wait_for_transfers_completion))
-        assert_type(options, Hash){'transfer agent options'}
+        Aspera.assert(respond_to?(:start_transfer))
+        Aspera.assert(respond_to?(:wait_for_transfers_completion))
+        Aspera.assert_type(options, Hash){'transfer agent options'}
         Log.log.debug{Log.dump(:agent_options, options)}
         @progress = options[:progress]
         options.delete(:progress)

data/lib/aspera/{fasp/agent_connect.rb → agent/connect.rb}

@@ -1,17 +1,17 @@
 # frozen_string_literal: true
 
-require 'aspera/fasp/agent_base'
+require 'aspera/agent/base'
 require 'aspera/rest'
 require 'aspera/open_application'
 require 'securerandom'
 
 module Aspera
-  module Fasp
-    class AgentConnect < Aspera::Fasp::AgentBase
+  module Agent
+    class Connect < Base
       # try twice the main init url in sequence
       CONNECT_START_URIS = ['fasp://initialize', 'fasp://initialize', 'aspera-drive://initialize', 'https://test-connect.ibmaspera.com/']
       # delay between each try to start connect
-      SLEEP_SEC_BETWEEN_RETRY = 3
+      SLEEP_SEC_BETWEEN_RETRY = 5
       private_constant :CONNECT_START_URIS, :SLEEP_SEC_BETWEEN_RETRY
       def initialize(options)
         super(options)
@@ -21,9 +21,11 @@ module Aspera
         raise 'Using connect requires a graphical environment' if !OpenApplication.default_gui_mode.eql?(:graphical)
         method_index = 0
         begin
-          connect_url = Products.connect_uri
+          connect_url = Ascp::Products.connect_uri
           Log.log.debug{"found: #{connect_url}"}
-          @connect_api = Rest.new({base_url: "#{connect_url}/v5/connect", headers: {'Origin' => Rest.user_agent}}) # could use v6 also now
+          @connect_api = Rest.new(
+            base_url: "#{connect_url}/v5/connect", # could use v6 also now
+            headers: {'Origin' => Rest.user_agent})
           connect_info = @connect_api.read('info/version')[:data]
           Log.log.info('Connect was reached') if method_index > 0
           Log.log.debug{Log.dump(:connect_version, connect_info)}
@@ -33,7 +35,7 @@ module Aspera
           raise StandardError, "Unable to start connect #{method_index} times" if start_url.nil?
           Log.log.warn{"Aspera Connect is not started (#{e}). Trying to start it ##{method_index}..."}
           if !OpenApplication.uri_graphical(start_url)
-            OpenApplication.uri_graphical('https://downloads.asperasoft.com/connect2/')
+            OpenApplication.uri_graphical('https://www.ibm.com/aspera/connect/')
             raise StandardError, 'Connect is not installed'
           end
           sleep(SLEEP_SEC_BETWEEN_RETRY)
@@ -67,7 +69,7 @@ module Aspera
           }]}
         # asynchronous anyway
         res = @connect_api.create('transfers/start', connect_transfer_args)[:data]
-        @xfer_id = res['transfer_specs'].first['transfer_spec']['tags'][Fasp::TransferSpec::TAG_RESERVED]['xfer_id']
+        @xfer_id = res['transfer_specs'].first['transfer_spec']['tags'][Transfer::Spec::TAG_RESERVED]['xfer_id']
       end
 
       def wait_for_transfers_completion
@@ -105,13 +107,13 @@ module Aspera
                 break
               when 'failed'
                 notify_progress(type: :end, session_id: session_id)
-                raise Fasp::Error, transfer['error_desc']
+                raise Transfer::Error, transfer['error_desc']
               when 'cancelled'
                 notify_progress(type: :end, session_id: session_id)
-                raise Fasp::Error, 'Transfer cancelled by user'
+                raise Transfer::Error, 'Transfer cancelled by user'
               else
                 notify_progress(type: :end, session_id: session_id)
-                raise Fasp::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
+                raise Transfer::Error, "unknown status: #{transfer['status']}: #{transfer['error_desc']}"
               end
             end
             sleep(1)

data/lib/aspera/{fasp/agent_direct.rb → agent/direct.rb}

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
-require 'aspera/fasp/agent_base'
-require 'aspera/fasp/error'
-require 'aspera/fasp/parameters'
-require 'aspera/fasp/installation'
-require 'aspera/fasp/resume_policy'
-require 'aspera/fasp/transfer_spec'
-require 'aspera/fasp/management'
+require 'aspera/agent/base'
+require 'aspera/ascp/installation'
+require 'aspera/ascp/management'
+require 'aspera/transfer/parameters'
+require 'aspera/transfer/error'
+require 'aspera/transfer/spec'
+require 'aspera/resumer'
 require 'aspera/log'
 require 'aspera/assert'
 require 'socket'
@@ -15,27 +15,28 @@ require 'shellwords'
 require 'English'
 
 module Aspera
-  module Fasp
+  module Agent
     # executes a local "ascp", connects mgt port, equivalent of "Fasp Manager"
-    class AgentDirect < Aspera::Fasp::AgentBase
+    class Direct < Base
       # options for initialize (same as values in option transfer_info)
       DEFAULT_OPTIONS = {
+        wss:               true, # true: if both SSH and wss in ts: prefer wss
+        ascp_args:         [],
         spawn_timeout_sec: 2,
         spawn_delay_sec:   2, # optional delay to start between sessions
-        wss:               true, # true: if both SSH and wss in ts: prefer wss
         multi_incr_udp:    true,
+        trusted_certs:     [], # list of files with trusted certificates (stores)
         resume:            {},
-        ascp_args:         [],
-        check_ignore:      nil, # callback with host,port
         quiet:             true, # by default no native ascp progress bar
-        trusted_certs:     [] # list of files with trusted certificates (stores)
+        check_ignore_cb:   nil, # callback with host,port
+        management_cb:     nil # callback for management events
       }.freeze
-      LISTEN_ADDRESS = '127.0.0.1'
-      LISTEN_AVAILABLE_PORT = 0 # 0 means any available port
+      LISTEN_LOCAL_ADDRESS = '127.0.0.1'
+      ANY_AVAILABLE_PORT = 0 # 0 means any available port
       # spellchecker: enable
-      private_constant :DEFAULT_OPTIONS, :LISTEN_ADDRESS
+      private_constant :DEFAULT_OPTIONS, :LISTEN_LOCAL_ADDRESS, :ANY_AVAILABLE_PORT
 
-      # method of Aspera::Fasp::AgentBase
+      # method of Base
       # start ascp transfer(s) (non blocking), single or multi-session
       # session information added to @sessions
       # @param transfer_spec [Hash] aspera transfer specification
@@ -44,15 +45,15 @@ module Aspera
         # clone transfer spec because we modify it (first level keys)
         transfer_spec = transfer_spec.clone
         # if there are aspera tags
-        if transfer_spec['tags'].is_a?(Hash) && transfer_spec['tags'][Fasp::TransferSpec::TAG_RESERVED].is_a?(Hash)
+        if transfer_spec.dig('tags', Transfer::Spec::TAG_RESERVED).is_a?(Hash)
           # TODO: what is this for ? only on local ascp ?
           # NOTE: important: transfer id must be unique: generate random id
           # using a non unique id results in discard of tags in AoC, and a package is never finalized
           # all sessions in a multi-session transfer must have the same xfer_id (see admin manual)
-          transfer_spec['tags'][Fasp::TransferSpec::TAG_RESERVED]['xfer_id'] ||= SecureRandom.uuid
+          transfer_spec['tags'][Transfer::Spec::TAG_RESERVED]['xfer_id'] ||= SecureRandom.uuid
           Log.log.debug{"xfer id=#{transfer_spec['xfer_id']}"}
           # TODO: useful ? node only ? seems to be a timeout for retry in node
-          transfer_spec['tags'][Fasp::TransferSpec::TAG_RESERVED]['xfer_retry'] ||= 3600
+          transfer_spec['tags'][Transfer::Spec::TAG_RESERVED]['xfer_retry'] ||= 3600
         end
         Log.log.debug{Log.dump('ts', transfer_spec)}
         # Compute this before using transfer spec because it potentially modifies the transfer spec
@@ -72,7 +73,7 @@ module Aspera
             multi_session_info = nil
           elsif @options[:multi_incr_udp] # multi_session_info[:count] > 0
             # if option not true: keep default udp port for all sessions
-            multi_session_info[:udp_base] = transfer_spec.key?('fasp_port') ? transfer_spec['fasp_port'] : TransferSpec::UDP_PORT
+            multi_session_info[:udp_base] = transfer_spec.key?('fasp_port') ? transfer_spec['fasp_port'] : Transfer::Spec::UDP_PORT
             # delete from original transfer spec, as we will increment values
             transfer_spec.delete('fasp_port')
             # override if specified, else use default value
@@ -89,7 +90,7 @@ module Aspera
           io:                nil,               # management port server socket
           token_regenerator: token_regenerator, # regenerate bearer token with oauth
           # env vars and args to ascp (from transfer spec)
-          env_args:          Parameters.new(transfer_spec, @options).ascp_args
+          env_args:          Transfer::Parameters.new(transfer_spec, @options).ascp_args
         }
 
         if multi_session_info.nil?
@@ -141,12 +142,6 @@ module Aspera
         Log.log.debug('fasp local shutdown')
       end
 
-      # cspell:disable
-      # begin 'Type' => 'NOTIFICATION', 'PreTransferBytes' => size
-      # progress 'Type' => 'STATS', 'Bytescont' => size
-      # end 'Type' => 'DONE'
-      # cspell:enable
-
       # @param event management port event
       def process_progress(event)
         session_id = event['SessionId']
@@ -194,25 +189,25 @@ module Aspera
       # @param session this session information
       # could be private method
       def start_transfer_with_args_env(env_args, session)
-        assert_type(env_args, Hash)
-        assert_type(session, Hash)
+        Aspera.assert_type(env_args, Hash)
+        Aspera.assert_type(session, Hash)
         Log.log.debug{"env_args=#{env_args.inspect}"}
         notify_progress(session_id: nil, type: :pre_start, info: 'starting')
         begin
-          # we use Socket directly, instead of TCPServer, s it gives access to lower level options
-          mgt_server_socket = Socket.new(Socket::AF_INET, Socket::SOCK_STREAM, 0)
-          # open an available (0) local TCP port as ascp management
-          # Socket.pack_sockaddr_in(LISTEN_AVAILABLE_PORT, LISTEN_ADDRESS)
-          mgt_server_socket.bind(Addrinfo.tcp(LISTEN_ADDRESS, LISTEN_AVAILABLE_PORT))
-          # clone arguments and add mgt port
+          ascp_pid = nil
+          # we use Socket directly, instead of TCPServer, as it gives access to lower level options
+          socket_class = RUBY_ENGINE.eql?('jruby') ? ServerSocket : Socket
+          mgt_server_socket = socket_class.new(Socket::AF_INET, Socket::SOCK_STREAM, 0)
+          # open any available (0) local TCP port for use as ascp management port
+          mgt_server_socket.bind(Addrinfo.tcp(LISTEN_LOCAL_ADDRESS, ANY_AVAILABLE_PORT))
+          # build arguments and add mgt port
           ascp_arguments = ['-M', mgt_server_socket.local_address.ip_port.to_s].concat(env_args[:args])
-          # mgt_server_socket.addr[1]
           # get location of ascp executable
-          ascp_path = Fasp::Installation.instance.path(env_args[:ascp_version])
+          ascp_path = Ascp::Installation.instance.path(env_args[:ascp_version])
           # display ascp command line
           Log.log.debug do
             [
-              'execute:',
+              'execute:'.red,
               env_args[:env].map{|k, v| "#{k}=#{Shellwords.shellescape(v)}"},
               Shellwords.shellescape(ascp_path),
               ascp_arguments.map{|a|Shellwords.shellescape(a)}
@@ -220,14 +215,14 @@ module Aspera
           end
           # start ascp in separate process
           ascp_pid = Process.spawn(env_args[:env], [ascp_path, ascp_path], *ascp_arguments, close_others: true)
-          Log.log.debug{"spawned pid #{ascp_pid}"}
+          Log.log.debug{"spawned ascp pid #{ascp_pid}"}
           notify_progress(session_id: nil, type: :pre_start, info: 'waiting for ascp')
           mgt_server_socket.listen(1)
           # TODO: timeout does not work when Process.spawn is used... until process exits, then it works
           Log.log.debug{"before select, timeout: #{@options[:spawn_timeout_sec]}"}
           readable, _, _ = IO.select([mgt_server_socket], nil, nil, @options[:spawn_timeout_sec])
           Log.log.debug('after select, before accept')
-          assert(readable, exception_class: Fasp::Error){'timeout waiting mgt port connect (select not readable)'}
+          Aspera.assert(readable, exception_class: Transfer::Error){'timeout waiting mgt port connect (select not readable)'}
           # There is a connection to accept
           client_socket, _client_addrinfo = mgt_server_socket.accept
           Log.log.debug('after accept')
@@ -237,14 +232,14 @@ module Aspera
           # TODO: use same value as Encoding.default_external
           ascp_mgt_io.set_encoding(Encoding::UTF_8)
           session[:io] = ascp_mgt_io
-          processor = Management.new
+          processor = Ascp::Management.new
           # read management port, until socket is closed (gets returns nil)
           while (line = ascp_mgt_io.gets)
             event = processor.process_line(line.chomp)
             next unless event
             # event is ready
             Log.log.trace1{Log.dump(:management_port, event)}
-            # Log.log.trace1{"event: #{JSON.generate(Management.enhanced_event_format(event))}"}
+            @options[:management_cb]&.call(event)
             process_progress(event)
             Log.log.error((event['Description']).to_s) if event['Type'].eql?('FILEERROR') # cspell:disable-line
           end
@@ -261,7 +256,7 @@ module Aspera
                 Log.log.warn('Regenerating token for transfer')
                 env_args[:env]['ASPERA_SCP_TOKEN'] = session[:token_regenerator].refreshed_transfer_token
               end
-              raise Fasp::Error.new(last_event['Description'], last_event['Code'].to_i)
+              raise Transfer::Error.new(last_event['Description'], last_event['Code'].to_i)
             when 'DONE'
               nil
             else
@@ -269,23 +264,24 @@ module Aspera
             end # case
           end
         rescue SystemCallError => e
-          # Process.spawn
-          raise Fasp::Error, e.message
+          # Process.spawn failed, or socket error
+          raise Transfer::Error, e.message
         rescue Interrupt
-          raise Fasp::Error, 'transfer interrupted by user'
+          raise Transfer::Error, 'transfer interrupted by user'
         ensure
           mgt_server_socket.close
-          # if ascp was successfully started
+          # if ascp was successfully started, check its status
           unless ascp_pid.nil?
             # "wait" for process to avoid zombie
             Process.wait(ascp_pid)
             status = $CHILD_STATUS
             ascp_pid = nil
             session.delete(:io)
-            if !status.success?
-              message = "ascp failed: #{status}"
+            # status is nil if an exception occurred before starting ascp
+            if !status&.success?
+              message = status.nil? ? 'ascp not started' : "ascp failed (#{status})"
               # raise error only if there was not already an exception (ERROR_INFO)
-              raise Fasp::Error, message unless $ERROR_INFO
+              raise Transfer::Error, message unless $ERROR_INFO
               # else display this message also, as main exception is already here
               Log.log.error(message)
             end
@@ -332,9 +328,9 @@ module Aspera
       def initialize(options={})
         super(options)
         # set default options and override if specified
-        @options = AgentBase.options(default: DEFAULT_OPTIONS, options: options)
+        @options = Base.options(default: DEFAULT_OPTIONS, options: options)
         Log.log.debug{Log.dump(:agent_options, @options)}
-        @resume_policy = ResumePolicy.new(@options[:resume].symbolize_keys)
+        @resume_policy = Resumer.new(@options[:resume].symbolize_keys)
         # all transfer jobs, key = SecureRandom.uuid, protected by mutex, cond var on change
         @sessions = []
         # mutex protects global data accessed by threads