aspera-cli 4.0.0.pre2 → 4.2.0

data/lib/aspera/fasp/installation.rb

@@ -5,6 +5,7 @@ require 'aspera/data_repository'
 require 'xmlsimple'
 require 'zlib'
 require 'base64'
+require 'fileutils'
 
 module Aspera
   module Fasp
@@ -17,14 +18,28 @@ module Aspera
     # Installation.instance.ascp_path=""
     class Installation
       include Singleton
-      # currently used ascp executable
-      attr_accessor :ascp_path
-      # location of SDK files
-      attr_accessor :folder
       PRODUCT_CONNECT='Aspera Connect'
       PRODUCT_CLI_V1='Aspera CLI'
       PRODUCT_DRIVE='Aspera Drive'
       PRODUCT_ENTSRV='Enterprise Server'
+      MAX_REDIRECT_SDK=2
+      private_constant :MAX_REDIRECT_SDK
+      # set ascp executable path
+      def ascp_path=(v)
+        @path_to_ascp=v
+      end
+
+      # filename for ascp with optional extension (Windows)
+      def ascp_filename
+        return 'ascp'+Environment.exe_extension
+      end
+
+      # location of SDK files
+      def folder=(v)
+        @sdk_folder=v
+        folder_path
+      end
+
       # find ascp in named product (use value : FIRST_FOUND='FIRST' to just use first one)
       # or select one from installed_products()
       def use_ascp_from_product(product_name)
@@ -35,33 +50,37 @@ module Aspera
           pl=installed_products.select{|i|i[:name].eql?(product_name)}.first
           raise "no such product installed: #{product_name}" if pl.nil?
         end
-        @ascp_path=pl[:ascp_path]
-        Log.log.debug("ascp_path=#{@ascp_path}")
+        self.ascp_path=pl[:ascp_path]
+        Log.log.debug("ascp_path=#{@path_to_ascp}")
       end
 
       # @return the list of installed products in format of product_locations
       def installed_products
         if @found_products.nil?
-          @found_products=product_locations
-          # add sdk as first search path
-          @found_products.unshift({# SDK
+          scan_locations=product_locations.clone
+          # add SDK as first search path
+          scan_locations.unshift({
             :expected =>'SDK',
-            :app_root =>@folder,
+            :app_root =>folder_path,
             :sub_bin =>''
           })
-          @found_products.select! do |pl|
-            next false unless Dir.exist?(pl[:app_root])
-            Log.log.debug("found #{pl[:app_root]}")
-            sub_bin = pl[:sub_bin] || BIN_SUBFOLDER
-            pl[:ascp_path]=File.join(pl[:app_root],sub_bin,'ascp'+Environment.exe_extension)
-            next false unless File.exist?(pl[:ascp_path])
-            product_info_file="#{pl[:app_root]}/#{PRODUCT_INFO}"
+          # search installed products: with ascp
+          @found_products=scan_locations.select! do |item|
+            # skip if not main folder
+            next false unless Dir.exist?(item[:app_root])
+            Log.log.debug("Found #{item[:app_root]}")
+            sub_bin = item[:sub_bin] || BIN_SUBFOLDER
+            item[:ascp_path]=File.join(item[:app_root],sub_bin,ascp_filename)
+            # skip if no ascp
+            next false unless File.exist?(item[:ascp_path])
+            # read info from product info file if present
+            product_info_file="#{item[:app_root]}/#{PRODUCT_INFO}"
             if File.exist?(product_info_file)
-              res_s=XmlSimple.xml_in(File.read(product_info_file),{"ForceArray"=>false})
-              pl[:name]=res_s['name']
-              pl[:version]=res_s['version']
+              res_s=XmlSimple.xml_in(File.read(product_info_file),{'ForceArray'=>false})
+              item[:name]=res_s['name']
+              item[:version]=res_s['version']
             else
-              pl[:name]=pl[:expected]
+              item[:name]=item[:expected]
             end
             true # select this version
           end
@@ -69,6 +88,7 @@ module Aspera
         return @found_products
       end
 
+      # all ascp files (in SDK)
       FILES=[:ascp,:ascp4,:ssh_bypass_key_dsa,:ssh_bypass_key_rsa,:aspera_license,:aspera_conf,:fallback_cert,:fallback_key]
 
       # get path of one resource file of currently activated product
@@ -76,44 +96,38 @@ module Aspera
       def path(k)
         case k
         when :ascp,:ascp4
-          use_ascp_from_product(FIRST_FOUND) if @ascp_path.nil?
-          file=@ascp_path
+          use_ascp_from_product(FIRST_FOUND) if @path_to_ascp.nil?
+          file=@path_to_ascp
           # note that there might be a .exe at the end
           file=file.gsub('ascp','ascp4') if k.eql?(:ascp4)
         when :ssh_bypass_key_dsa
-          file=File.join(@folder,'aspera_bypass_dsa.pem')
+          file=File.join(folder_path,'aspera_bypass_dsa.pem')
           File.write(file,get_key('dsa',1)) unless File.exist?(file)
           File.chmod(0400,file)
         when :ssh_bypass_key_rsa
-          file=File.join(@folder,'aspera_bypass_rsa.pem')
+          file=File.join(folder_path,'aspera_bypass_rsa.pem')
           File.write(file,get_key('rsa',2)) unless File.exist?(file)
           File.chmod(0400,file)
         when :aspera_license
-          file=File.join(@folder,'aspera-license')
+          file=File.join(folder_path,'aspera-license')
           File.write(file,Base64.strict_encode64("#{Zlib::Inflate.inflate(DataRepository.instance.get_bin(6))}==SIGNATURE==\n#{Base64.strict_encode64(DataRepository.instance.get_bin(7))}")) unless File.exist?(file)
           File.chmod(0400,file)
         when :aspera_conf
-          file=File.join(@folder,'aspera.conf')
+          file=File.join(folder_path,'aspera.conf')
           File.write(file,%Q{<?xml version='1.0' encoding='UTF-8'?>
 <CONF version="2">
 <default>
     <file_system>
-        <storage_rc>
-            <adaptive>
-                true
-            </adaptive>
-        </storage_rc>
         <resume_suffix>.aspera-ckpt</resume_suffix>
         <partial_file_suffix>.partial</partial_file_suffix>
-        <replace_illegal_chars>_</replace_illegal_chars>
     </file_system>
 </default>
 </CONF>
 }) unless File.exist?(file)
           File.chmod(0400,file)
         when :fallback_cert,:fallback_key
-          file_key=File.join(@folder,'aspera_fallback_key.pem')
-          file_cert=File.join(@folder,'aspera_fallback_cert.pem')
+          file_key=File.join(folder_path,'aspera_fallback_key.pem')
+          file_cert=File.join(folder_path,'aspera_fallback_cert.pem')
           if !File.exist?(file_key) or !File.exist?(file_cert)
             require 'openssl'
             # create new self signed certificate for http fallback
@@ -139,7 +153,7 @@ module Aspera
         return file
       end
 
-      # @returns the file path of local connect where API's URI can be read
+      # @return the file path of local connect where API's URI can be read
       def connect_uri
         connect=get_product_folders(PRODUCT_CONNECT)
         folder=File.join(connect[:run_root],VARRUN_SUBFOLDER)
@@ -168,23 +182,67 @@ module Aspera
         return [:ssh_bypass_key_dsa,:ssh_bypass_key_rsa].map{|i|Installation.instance.path(i)}
       end
 
-      def install_sdk
+      # Check that specified path is ascp and get version
+      def get_ascp_version(ascp_path)
+        raise "File basename of #{ascp_path} must be #{ascp_filename}" unless File.basename(ascp_path).eql?(ascp_filename)
+        ascp_version='n/a'
+        raise "error in sdk: no ascp included" if ascp_path.nil?
+        cmd_out=%x{"#{ascp_path}" -A}
+        raise "An error occured when testing #{ascp_filename}: #{cmd_out}" unless $? == 0
+        # get version from ascp, only after full extract, as windows requires DLLs (SSL/TLS/etc...)
+        m=cmd_out.match(/ascp version (.*)/)
+        ascp_version=m[1] unless m.nil?
+      end
+
+      # download aspera SDK or use local file
+      # extracts ascp binary for current system architecture
+      # @return ascp version (from execution)
+      def install_sdk(sdk_url)
         require 'zip'
         sdk_zip_path=File.join(Dir.tmpdir,'sdk.zip')
-        Aspera::Rest.new(base_url: SDK_URL).call(operation: 'GET',save_to_file: sdk_zip_path)
+        if sdk_url.start_with?('file:')
+          # require specific file scheme: the path part is "relative", or absolute if there are 4 slash
+          raise 'use format: file:///<path>' unless sdk_url.start_with?('file:///')
+          sdk_zip_path=sdk_url.gsub(%r{^file:///},'')
+        else
+          redirect_remain=MAX_REDIRECT_SDK
+          begin
+            Aspera::Rest.new(base_url: sdk_url).call(operation: 'GET',save_to_file: sdk_zip_path)
+          rescue Aspera::RestCallError => e
+            if e.response.is_a?(Net::HTTPRedirection)
+              if redirect_remain > 0
+                redirect_remain-=1
+                sdk_url=e.response['location']
+                retry
+              else
+                raise "Too many redirect"
+              end
+            else
+              raise e
+            end
+          end
+        end
+        # SDK is organized by architecture
         filter="/#{Environment.architecture}/"
         ascp_path=nil
+        sdk_path=folder_path
+        # rename old install
+        if File.exist?(File.join(sdk_path,ascp_filename))
+          Log.log.warn("Previous install exists, renaming.")
+          File.rename(sdk_path,"#{sdk_path}.#{Time.now.strftime("%Y%m%d%H%M%S")}")
+        end
         # first ensure license file is here so that ascp invokation for version works
         self.path(:aspera_license)
         self.path(:aspera_conf)
         Zip::File.open(sdk_zip_path) do |zip_file|
           zip_file.each do |entry|
+            # get only specified arch, but not folder, only files
             if entry.name.include?(filter) and !entry.name.end_with?('/')
-              archive_file=File.join(@folder,File.basename(entry.name))
+              archive_file=File.join(sdk_path,File.basename(entry.name))
               File.open(archive_file, 'wb') do |output_stream|
                 IO.copy_stream(entry.get_input_stream, output_stream)
               end
-              if entry.name.include?('ascp')
+              if File.basename(entry.name).eql?(ascp_filename)
                 FileUtils.chmod(0755,archive_file)
                 ascp_path=archive_file
               end
@@ -192,13 +250,8 @@ module Aspera
           end
         end
         File.unlink(sdk_zip_path) rescue nil # Windows may give error
-        ascp_version='n/a'
-        if !ascp_path.nil?
-          # get version from ascp, only after full extract, as windows requires SSL/TLS DLLs
-          m=%x{#{ascp_path} -A}.match(/ascp version (.*)/)
-          ascp_version=m[1] unless m.nil?
-          File.write(File.join(@folder,PRODUCT_INFO),"<product><name>IBM Aspera SDK</name><version>#{ascp_version}</version></product>")
-        end
+        ascp_version=get_ascp_version(ascp_path)
+        File.write(File.join(folder_path,PRODUCT_INFO),"<product><name>IBM Aspera SDK</name><version>#{ascp_version}</version></product>")
         return ascp_version
       end
 
@@ -211,25 +264,31 @@ module Aspera
       PRODUCT_INFO='product-info.mf'
       # policy for product selection
       FIRST_FOUND='FIRST'
-      SDK_URL='https://eudemo.asperademo.com/aspera/faspex/sdk.zip'
 
-      private_constant :BIN_SUBFOLDER,:ETC_SUBFOLDER,:VARRUN_SUBFOLDER,:PRODUCT_INFO,:SDK_URL
+      private_constant :BIN_SUBFOLDER,:ETC_SUBFOLDER,:VARRUN_SUBFOLDER,:PRODUCT_INFO
 
-      # get some specific folder from specific applications: Connect or CLI
+      def initialize
+        @path_to_ascp=nil
+        @sdk_folder=nil
+        @found_products=nil
+      end
+
+      # @return folder paths for specified applications
+      # @param name Connect or CLI
       def get_product_folders(name)
         found=installed_products.select{|i|i[:expected].eql?(name) or i[:name].eql?(name)}
         raise "Product: #{name} not found, please install." if found.empty?
         return found.first
       end
 
-      def initialize
-        @ascp_path=nil
-        @folder='.'
-        @found_products=nil
+      # @return the path to folder where SDK is installed
+      def folder_path
+        raise "Undefined path to SDK" if @sdk_folder.nil?
+        FileUtils.mkdir_p(@sdk_folder) unless Dir.exist?(@sdk_folder)
+        @sdk_folder
       end
 
-      # returns product folders depending on OS
-      # fields
+      # @return product folders depending on OS fields
       # :expected  M app name is taken from the manifest if present, else defaults to this value
       # :app_root  M main folder for the application
       # :log_root  O location of log files (Linux uses syslog)
@@ -271,7 +330,7 @@ module Aspera
             :log_root =>File.join(Dir.home,'Library','Logs','Aspera_Drive'),
             :sub_bin  =>File.join('Contents','Resources'),
             }]
-        else; return [{  # other: Linux and unix family
+        else; return [{  # other: Linux and Unix family
             :expected =>PRODUCT_CONNECT,
             :app_root =>File.join(Dir.home,'.aspera','connect'),
             :run_root =>File.join(Dir.home,'.aspera','connect')
@@ -285,6 +344,9 @@ module Aspera
         end
       end
 
+      # @return a standard bypass key
+      # @param type rsa or dsa
+      # @param id in repository 1 for dsa, 2 for rsa
       def get_key(type,id)
         hf=['begin','end'].map{|t|"-----#{t} #{type} private key-----".upcase}
         bin=Base64.strict_encode64(DataRepository.instance.get_bin(id))

data/lib/aspera/fasp/local.rb

@@ -17,17 +17,33 @@ require 'securerandom'
 
 module Aspera
   module Fasp
-    # default transfer username for access key based transfers
+    # (public) default transfer username for access key based transfers
     ACCESS_KEY_TRANSFER_USER='xfer'
     # executes a local "ascp", connects mgt port, equivalent of "Fasp Manager"
     class Local < Manager
-      # set to false to keep ascp progress bar display (basically: removes ascp's option -q)
+      # options for initialize
+      DEFAULT_OPTIONS = {
+        :spawn_timeout_sec => 3,
+        :spawn_delay_sec   => 2,
+        :wss               => false,
+        :resume            => {}
+      }
+      DEFAULT_UDP_PORT=33001
+      private_constant :DEFAULT_OPTIONS
+      # set to false to keep ascp progress bar display ("true" adds ascp's option -q)
       attr_accessor :quiet
-      # start FASP transfer based on transfer spec (hash table)
-      # note that it is asynchronous
+
+      # start ascp transfer (non blocking), single or multi-session
+      # job information added to @jobs
+      # @param transfer_spec [Hash] aspera transfer specification
+      # @param options [Hash] :resumer, :regenerate_token
       def start_transfer(transfer_spec,options={})
-        raise "option: must be hash (or nil)" unless options.is_a?(Hash)
-        job_id=options[:job_id] || SecureRandom.uuid
+        raise 'option: must be hash (or nil)' unless options.is_a?(Hash)
+        job_options = options.clone
+        job_options[:resumer] ||= @resume_policy
+        job_options[:job_id] ||= SecureRandom.uuid
+        # clone transfer spec because we modify it (first level keys)
+        transfer_spec=transfer_spec.clone
         # if there is aspera tags
         if transfer_spec['tags'].is_a?(Hash) and transfer_spec['tags']['aspera'].is_a?(Hash)
           # TODO: what is this for ? only on local ascp ?
@@ -39,6 +55,7 @@ module Aspera
           transfer_spec['tags']['aspera']['xfer_retry']||=3600
         end
         Log.dump('ts',transfer_spec)
+
         # add bypass keys when authentication is token and no auth is provided
         if transfer_spec.has_key?('token') and
         !transfer_spec.has_key?('remote_password') and
@@ -47,8 +64,28 @@ module Aspera
           transfer_spec['EX_ssh_key_paths'] = Installation.instance.bypass_keys
         end
 
+        # TODO: check if changing fasp(UDP) port is really necessary, not clear from doc
+        # compute this before using transfer spec, even if the var is not used in single session
+        multi_session_udp_port_base=DEFAULT_UDP_PORT
+        multi_session_number=0
+        if transfer_spec.has_key?('multi_session')
+          multi_session_number=transfer_spec['multi_session'].to_i
+          if multi_session_number < 0
+            Log.log.error("multi_session(#{transfer_spec['multi_session']}) shall be integer >= 0")
+            multi_session_number = 0
+          end
+          if multi_session_number > 0
+            # managed here, so delete from transfer spec
+            transfer_spec.delete('multi_session')
+            if transfer_spec.has_key?('fasp_port')
+              multi_session_udp_port_base=transfer_spec['fasp_port']
+              transfer_spec.delete('fasp_port')
+            end
+          end
+        end
+
         # compute known args
-        env_args=Parameters.ts_to_env_args(transfer_spec,wss: @enable_wss)
+        env_args=Parameters.ts_to_env_args(transfer_spec,wss: @options[:wss])
 
         # add fallback cert and key as arguments if needed
         if ['1','force'].include?(transfer_spec['http_fallback'])
@@ -60,118 +97,98 @@ module Aspera
 
         # transfer job can be multi session
         xfer_job={
-          :id            => job_id,
-          :sessions      => []
+          :id            => job_options[:job_id],
+          :sessions      => [] # all sessions as below
         }
 
         # generic session information
         session={
-          :state    => :initial, # :initial, :started, :success, :failed
-          :env_args => env_args,
-          :resumer  => options['resume_policy'] || @resume_policy,
-          :options  => options
+          :thread   => nil,         # Thread object monitoring management port, not nil when pushed to :sessions
+          :error    => nil,         # exception if failed
+          :io       => nil,         # management port server socket
+          :id       => nil,         # SessionId from INIT message in mgt port
+          :env_args => env_args,    # env vars and args to ascp (from transfer spec)
+          :options  => job_options  # [Hash]
         }
 
-        Log.log.debug("starting session thread(s)")
-        if !transfer_spec.has_key?('multi_session')
+        if multi_session_number <= 1
+          Log.log.debug('Starting single session thread')
           # single session for transfer : simple
           session[:thread] = Thread.new(session) {|s|transfer_thread_entry(s)}
           xfer_job[:sessions].push(session)
         else
-          # default value overriden by fasp_port
-          multi_session_udp_port_base=33001
-          multi_session=transfer_spec['multi_session'].to_i
-          raise "multi_session(#{transfer_spec['multi_session']}) shall be integer > 1" unless multi_session >= 1
-          # managed here, so delete from transfer spec
-          transfer_spec.delete('multi_session')
-          # TODO: check if changing fasp(UDP) port is really necessary, not clear from doc
-          if transfer_spec.has_key?('fasp_port')
-            multi_session_udp_port_base=transfer_spec['fasp_port']
-            transfer_spec.delete('fasp_port')
-          end
-          1.upto(multi_session) do |i|
+          Log.log.debug('Starting multi session threads')
+          1.upto(multi_session_number) do |i|
+            sleep(@options[:spawn_delay_sec]) unless i.eql?(1)
             # do deep copy (each thread has its own copy because it is modified here below and in thread)
             this_session=session.clone()
             this_session[:env_args]=this_session[:env_args].clone()
             this_session[:env_args][:args]=this_session[:env_args][:args].clone()
-            this_session[:env_args][:args].unshift("-C#{i}:#{multi_session}")
+            this_session[:env_args][:args].unshift("-C#{i}:#{multi_session_number}")
             # necessary only if server is not linux, i.e. server does not support port re-use
-            this_session[:env_args][:args].unshift("-O","#{multi_session_udp_port_base+i-1}")
+            this_session[:env_args][:args].unshift('-O',"#{multi_session_udp_port_base+i-1}")
             this_session[:thread] = Thread.new(this_session) {|s|transfer_thread_entry(s)}
             xfer_job[:sessions].push(this_session)
           end
         end
-        Log.log.debug("started session thread(s)")
+        Log.log.debug('started session thread(s)')
 
         # add job to list of jobs
-        @jobs[job_id]=xfer_job
-
+        @jobs[job_options[:job_id]]=xfer_job
         Log.log.debug("jobs: #{@jobs.keys.count}")
-        return job_id
+
+        return job_options[:job_id]
       end # start_transfer
 
       # wait for completion of all jobs started
       # @return list of :success or error message
       def wait_for_transfers_completion
-        Log.log.debug("wait_for_sessions: #{@jobs.values.inject(0){|m,j|m+j[:sessions].count}}")
-        @mutex.synchronize do
-          loop do
-            running=0
-            result=[]
-            @jobs.each do |id,job|
-              job[:sessions].each do |session|
-                case session[:state]
-                when :failed; result.push(session[:error])
-                when :success; result.push(:success)
-                else running+=1
-                end
-              end
-            end
-            if running.eql?(0)
-              # since all are finished and we return the result, clear statuses
-              @jobs.clear
-              return result
-            end
-            Log.log.debug("wait for completed: running: #{running}")
-            # wait for session termination
-            @cond_var.wait(@mutex)
-          end # loop
-        end # mutex
-        # never reach here
-        raise "internal error"
+        Log.log.debug('wait_for_transfers_completion')
+        # set to non-nil to exit loop
+        result=[]
+        @jobs.each do |id,job|
+          job[:sessions].each do |session|
+            Log.log.debug("join #{session[:thread]}")
+            session[:thread].join
+            result.push(session[:error] ? session[:error] : :success)
+          end
+        end
+        Log.log.debug('all transfers joined')
+        # since all are finished and we return the result, clear statuses
+        @jobs.clear
+        return result
       end
 
-      # terminates monitor thread
+      # used by asession (to be removed ?)
       def shutdown
-        Log.log.debug("fasp local shutdown")
-        Log.log.debug("send signal to monitor")
-        # tell monitor to stop
-        @mutex.synchronize do
-          @monitor_stop=true
-          @cond_var.broadcast
-        end
-        # wait for thread termination
-        @monitor_thread.join
-        @monitor_thread=nil
-        Log.log.debug("joined monitor")
+        Log.log.debug('fasp local shutdown')
       end
 
-      # This is the low level method to start FASP
+      # This is the low level method to start the "ascp" process
       # currently, relies on command line arguments
       # start ascp with management port.
       # raises FaspError on error
       # if there is a thread info: set and broadcast session id
       # @param env_args a hash containing :args :env :ascp_version
-      # cloud be private method
-      def start_transfer_with_args_env(env_args,session=nil)
+      # @param session this session information
+      # could be private method
+      def start_transfer_with_args_env(env_args,session)
+        raise 'env_args must be Hash' unless env_args.is_a?(Hash)
+        raise 'session must be Hash' unless session.is_a?(Hash)
+        # by default we assume an exception will be raised (for ensure block)
+        exception_raised=true
         begin
           Log.log.debug("env_args=#{env_args.inspect}")
-          ascp_path=Fasp::Installation.instance.path(env_args[:ascp_version])
+          # get location of ascp executable
+          ascp_path=@mutex.synchronize do
+            Fasp::Installation.instance.path(env_args[:ascp_version])
+          end
+          # (optional) check it exists
           raise Fasp::Error.new("no such file: #{ascp_path}") unless File.exist?(ascp_path)
-          ascp_pid=nil
+          # open random local TCP port for listening for ascp management
+          mgt_sock = TCPServer.new('127.0.0.1',0)
+          # clone arguments as we eed to modify with mgt port
           ascp_arguments=env_args[:args].clone
-          # open random local TCP port listening
-          mgt_sock = TCPServer.new('127.0.0.1',0 )
           # add management port
           ascp_arguments.unshift('-M', mgt_sock.addr[1].to_s)
           # start ascp in sub process
@@ -180,8 +197,9 @@ module Aspera
           ascp_pid = Process.spawn(env_args[:env],[ascp_path,ascp_path],*ascp_arguments)
           # in parent, wait for connection to socket max 3 seconds
           Log.log.debug("before accept for pid (#{ascp_pid})")
+          # init management socket
           ascp_mgt_io=nil
-          Timeout.timeout( 3 ) do
+          Timeout.timeout(@options[:spawn_timeout_sec]) do
             ascp_mgt_io = mgt_sock.accept
             # management messages include file names which may be utf8
             # by default socket is US-ASCII
@@ -189,21 +207,13 @@ module Aspera
             ascp_mgt_io.set_encoding(Encoding::UTF_8)
           end
           Log.log.debug("after accept (#{ascp_mgt_io})")
-
-          unless session.nil?
-            @mutex.synchronize do
-              session[:io]=ascp_mgt_io
-              @cond_var.broadcast
-            end
-          end
+          session[:io]=ascp_mgt_io
           # exact text for event, with \n
           current_event_text=''
           # parsed event (hash)
           current_event_data=nil
-
           # this is the last full status
           last_status_event=nil
-
           # read management port
           loop do
             # TODO: timeout here ?
@@ -222,45 +232,44 @@ module Aspera
               # event field
               current_event_data[$1] = $2
             when ''
-              # end event
-              raise "unexpected empty line" if current_event_data.nil?
+              # empty line is separator to end event information
+              raise 'unexpected empty line' if current_event_data.nil?
               current_event_data[Manager::LISTENER_SESSION_ID_B]=ascp_pid
               notify_listeners(current_event_text,current_event_data)
-              # TODO: check if this is always the last event
               case current_event_data['Type']
+              when 'INIT'
+                session[:id]=current_event_data['SessionId']
+                Log.log.debug("session id: #{session[:id]}")
               when 'DONE','ERROR'
+                # TODO: check if this is always the last event
                 last_status_event = current_event_data
-              when 'INIT'
-                unless session.nil?
-                  @mutex.synchronize do
-                    session[:state]=:started
-                    session[:id]=current_event_data['SessionId']
-                    Log.log.debug("session id: #{session[:id]}")
-                    @cond_var.broadcast
-                  end
-                end
               end # event type
             else
               raise "unexpected line:[#{line}]"
             end # case
-          end # loop
+          end # loop (process mgt port lines)
           # check that last status was received before process exit
-          raise "INTERNAL: nil last status" if last_status_event.nil?
-          case last_status_event['Type']
-          when 'DONE'
-            return
-          when 'ERROR'
-            Log.log.error("code: #{last_status_event['Code']}")
-            if last_status_event['Description']  =~ /bearer token/i
-              Log.log.error("need to regenerate token".red)
-              if !session.nil? and session[:options].is_a?(Hash) and session[:options].has_key?(:regenerate_token)
-                # regenerate token here, expired, or error on it
-                env_args[:env]['ASPERA_SCP_TOKEN']=session[:options][:regenerate_token].call(true)
+          if last_status_event.is_a?(Hash)
+            case last_status_event['Type']
+            when 'DONE'
+              # all went well
+              exception_raised=false
+            when 'ERROR'
+              Log.log.error("code: #{last_status_event['Code']}")
+              if last_status_event['Description']  =~ /bearer token/i
+                Log.log.error('need to regenerate token'.red)
+                if session[:options].is_a?(Hash) and session[:options].has_key?(:regenerate_token)
+                  # regenerate token here, expired, or error on it
+                  env_args[:env]['ASPERA_SCP_TOKEN']=session[:options][:regenerate_token].call(true)
+                end
               end
+              raise Fasp::Error.new(last_status_event['Description'],last_status_event['Code'].to_i)
+            else # case
+              raise "unexpected last event type: #{last_status_event['Type']}"
             end
-            raise Fasp::Error.new(last_status_event['Description'],last_status_event['Code'].to_i)
           else
-            raise "INTERNAL ERROR: unexpected last event"
+            exception_raised=false
+            Log.log.debug('no status read from ascp mgt port')
           end
         rescue SystemCallError => e
           # Process.spawn
@@ -270,107 +279,94 @@ module Aspera
         rescue Interrupt => e
           raise Fasp::Error.new('transfer interrupted by user')
         ensure
-          # ensure there is no ascp left running
+          # if ascp was successfully started
           unless ascp_pid.nil?
-            begin
-              Process.kill('INT',ascp_pid)
-            rescue
-            end
-            # avoid zombie
+            # "wait" for process to avoid zombie
             Process.wait(ascp_pid)
+            status=$?
             ascp_pid=nil
             session.delete(:io)
+            if !status.success?
+              message="ascp failed with code #{status.exitstatus}"
+              if exception_raised
+                # just debug, as main exception is already here
+                Log.log.debug(message)
+              else
+                raise Fasp::Error.new(message)
+              end
+            end
           end
         end # begin-ensure
       end # start_transfer_with_args_env
 
-      # send command on mgt port, examples:
+      # send command of management port to ascp session
+      # @param job_id identified transfer process
+      # @param session_index index of session (for multi session)
+      # @param data command on mgt port, examples:
       # {'type'=>'START','source'=>_path_,'destination'=>_path_}
       # {'type'=>'DONE'}
       def send_command(job_id,session_index,data)
-        @mutex.synchronize do
-          job=@jobs[job_id]
-          raise "no such job" if job.nil?
-          session=job[:sessions][session_index]
-          raise "no such session" if session.nil?
-          Log.log.debug("command: #{data}")
-          command=data.
-          keys.
-          map{|k|"#{k.capitalize}: #{data[k]}"}.
-          unshift('FASPMGR 2').
-          push('','').
-          join("\n")
-          session[:io].puts(command)
-        end
+        job=@jobs[job_id]
+        raise 'no such job' if job.nil?
+        session=job[:sessions][session_index]
+        raise 'no such session' if session.nil?
+        Log.log.debug("command: #{data}")
+        # build command
+        command=data.
+        keys.
+        map{|k|"#{k.capitalize}: #{data[k]}"}.
+        unshift('FASPMGR 2').
+        push('','').
+        join("\n")
+        session[:io].puts(command)
       end
 
       private
 
-      def initialize(agent_options=nil)
-        agent_options||={}
+      # @param options : keys(symbol): wss, resume
+      def initialize(options=nil)
         super()
         # by default no interactive progress bar
         @quiet=true
-        # shared data between transfer threads and others: protected by mutex, CV on change
+        # all transfer jobs, key = SecureRandom.uuid, protected by mutex, condvar on change
         @jobs={}
-        # mutex protects jobs data
+        # mutex protects global data accessed by threads
         @mutex=Mutex.new
-        # cond var is waited or broadcast on jobs data change
-        @cond_var=ConditionVariable.new
-        # must be set before starting monitor, set to false to stop thread. also shared and protected by mutex
-        @monitor_stop=false
-        @monitor_thread=Thread.new{monitor_thread_entry}
-        @resume_policy=ResumePolicy.new(agent_options)
-        @enable_wss = agent_options[:wss] || false
+        # manage options
+        @options=DEFAULT_OPTIONS.clone
+        if !options.nil?
+          raise "expecting Hash (or nil), but have #{options.class}" unless options.is_a?(Hash)
+          options.each do |k,v|
+            if DEFAULT_OPTIONS.has_key?(k)
+              @options[k]=v
+            else
+              raise "unknown local agent parameter: #{k}, expect one of #{DEFAULT_OPTIONS.keys.map{|i|i.to_s}.join(",")}"
+            end
+          end
+        end
+        Log.log.debug("local options= #{options}")
+        @resume_policy=ResumePolicy.new(@options[:resume].symbolize_keys)
       end
 
       # transfer thread entry
-      # implements resumable transfer
-      # TODO: extract resume algorithm in a specific object
+      # @param session information
       def transfer_thread_entry(session)
         begin
           # set name for logging
-          Thread.current[:name]="transfer"
-          # update state once in thread
-          session[:state]=:started
+          Thread.current[:name]='transfer'
           Log.log.debug("ENTER (#{Thread.current[:name]})")
           # start transfer with selected resumer policy
-          session[:resumer].process do
+          session[:options][:resumer].process do
             start_transfer_with_args_env(session[:env_args],session)
           end
           Log.log.debug('transfer ok'.bg_green)
-          session[:state]=:success
         rescue => e
-          session[:state]=:failed
           session[:error]=e
-          Log.log.error("#{e.class}:\n#{e.message}:\n#{e.backtrace.join("\n")}".red) if Log.instance.level.eql?(:debug)
-        ensure
-          @mutex.synchronize do
-            # ensure id is set to unblock start procedure
-            session[:id]||=nil
-            @cond_var.broadcast
-          end
+          Log.log.error("Transfer thread error: #{e.class}:\n#{e.message}:\n#{e.backtrace.join("\n")}".red) if Log.instance.level.eql?(:debug)
         end
         Log.log.debug("EXIT (#{Thread.current[:name]})")
       end
 
-      # main thread method for monitor
-      # currently: just joins started threads
-      def monitor_thread_entry
-        Thread.current[:name]="monitor"
-        @mutex.synchronize do
-          until @monitor_stop do
-            # wait for session termination
-            @cond_var.wait(@mutex)
-            @jobs.values do |job|
-              job[:sessions].each do |session|
-                session[:thread].join if [:success,:failed].include?(session[:state])
-              end # sessions
-            end # jobs
-          end # monitor run
-        end # sync
-        Log.log.debug("EXIT (#{Thread.current[:name]})")
-      end # monitor_thread_entry
     end # Local
   end
 end