aspera-cli 4.16.0 → 4.17.0

data/lib/aspera/command_line_builder.rb

@@ -29,20 +29,20 @@ module Aspera
       # Called by provider of definition before constructor of this class so that params_definition has all mandatory fields
       def normalize_description(full_description)
         full_description.each do |name, options|
-          assert_type(options, Hash){name}
+          Aspera.assert_type(options, Hash){name}
           unsupported_keys = options.keys - OPTIONS_KEYS
-          assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          assert(options.key?(:cli)){"Missing key: cli for #{name}"}
-          assert_type(options[:cli], Hash){'Key: cli'}
-          assert(options[:cli].key?(:type)){'Missing key: cli.type'}
-          assert_values(options[:cli][:type], CLI_OPTION_TYPES){"Unsupported processing type for #{name}"}
+          Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
+          Aspera.assert(options.key?(:cli)){"Missing key: cli for #{name}"}
+          Aspera.assert_type(options[:cli], Hash){'Key: cli'}
+          Aspera.assert(options[:cli].key?(:type)){'Missing key: cli.type'}
+          Aspera.assert_values(options[:cli][:type], CLI_OPTION_TYPES){"Unsupported processing type for #{name}"}
           # by default : optional
           options[:mandatory] ||= false
           options[:desc] ||= ''
           options[:desc] = "DEPRECATED: #{options[:deprecation]}\n#{options[:desc]}" if options.key?(:deprecation)
           cli = options[:cli]
           unsupported_cli_keys = cli.keys - CLI_KEYS
-          assert(unsupported_cli_keys.empty?){"Unsupported cli keys: #{unsupported_cli_keys}"}
+          Aspera.assert(unsupported_cli_keys.empty?){"Unsupported cli keys: #{unsupported_cli_keys}"}
           # by default : string, unless it's without arg
           options[:accepted_types] ||= options[:cli][:type].eql?(:opt_without_arg) ? :bool : :string
           # single type is placed in array
@@ -111,7 +111,7 @@ module Aspera
       end
       processing_type = read ? :get_value : options[:cli][:type]
       # check mandatory parameter (nil is valid value)
-      raise Fasp::Error, "Missing mandatory parameter: #{name}" if options[:mandatory] && !@param_hash.key?(name)
+      raise Transfer::Error, "Missing mandatory parameter: #{name}" if options[:mandatory] && !@param_hash.key?(name)
       parameter_value = @param_hash[name]
       # no default setting
       # parameter_value=options[:default] if parameter_value.nil? and options.has_key?(:default)
@@ -123,11 +123,11 @@ module Aspera
         when :hash then Hash
         when :int then Integer
         when :bool then [TrueClass, FalseClass]
-        else error_unexpected_value(type_symbol)
+        else Aspera.error_unexpected_value(type_symbol)
         end
       end.flatten
       # check that value is of expected type
-      raise Fasp::Error, "#{name} is : #{parameter_value.class} (#{parameter_value}), shall be #{options[:accepted_types]}, " \
+      raise Transfer::Error, "#{name} is : #{parameter_value.class} (#{parameter_value}), shall be #{options[:accepted_types]}, " \
         unless parameter_value.nil? || expected_classes.include?(parameter_value.class)
       # special processing will be requested with type get_value
       @used_param_names.push(name) unless processing_type.eql?(:special)
@@ -149,10 +149,10 @@ module Aspera
         # :convert has name of class and encoding method
         conversion_class, conversion_method = options[:cli][:convert].split('.')
         converted_value = Kernel.const_get(conversion_class).send(conversion_method, parameter_value)
-        raise Fasp::Error, "unsupported #{name}: #{parameter_value}" if converted_value.nil?
+        raise Transfer::Error, "unsupported #{name}: #{parameter_value}" if converted_value.nil?
         parameter_value = converted_value
       when NilClass
-      else error_unexpected_value(options[:cli][:convert].class)
+      else Aspera.error_unexpected_value(options[:cli][:convert].class)
       end
 
       case processing_type
@@ -161,14 +161,14 @@ module Aspera
       when :ignore, :special # ignore this parameter or process later
         return
       when :envvar # set in env var
-        assert(options[:cli].key?(:variable)){'missing key: cli.variable'}
+        Aspera.assert(options[:cli].key?(:variable)){'missing key: cli.variable'}
         @result[:env][options[:cli][:variable]] = parameter_value
       when :opt_without_arg # if present and true : just add option without value
         add_param = false
         case parameter_value
         when false then nil # nothing to put on command line, no creation by default
         when true then add_param = true
-        else error_unexpected_value(parameter_value){name}
+        else Aspera.error_unexpected_value(parameter_value){name}
         end
         add_param = !add_param if options[:add_on_false]
         add_command_line_options([options[:cli][:switch]]) if add_param

data/lib/aspera/coverage.rb

@@ -4,8 +4,7 @@
 if ENV.key?('ENABLE_COVERAGE')
   require 'simplecov'
   require 'securerandom'
-  # compute gem source root based on this script location, assuming it is in bin/
-  # use dirname instead of gsub, in case folder separator is not /
+  # compute development top folder based on this source location
   development_root = 3.times.inject(File.realpath(__FILE__)) { |p, _| File.dirname(p) }
   SimpleCov.root(development_root)
   SimpleCov.enable_for_subprocesses if SimpleCov.respond_to?(:enable_for_subprocesses)

data/lib/aspera/data_repository.rb

@@ -30,7 +30,7 @@ module Aspera
         return format('%08x-%04x-%04x-%04x-%04x%08x', *raw_data.unpack('NnnnnN'))
       when :'aspera.global-cli-client', :'aspera.drive'
         return Base64.urlsafe_encode64(raw_data)
-      else error_unexpected_value(name)
+      else Aspera.error_unexpected_value(name)
       end
     end
 

data/lib/aspera/environment.rb

@@ -56,8 +56,7 @@ module Aspera
         when /s390/
           return CPU_S390
         when /arm/, /aarch64/
-          # arm on mac has rosetta 2
-          return CPU_X86_64 if os.eql?(OS_X)
+          return CPU_ARM64
         end
         raise "Unknown CPU: #{RbConfig::CONFIG['host_cpu']}"
       end
@@ -90,7 +89,7 @@ module Aspera
 
       # value is provided in block
       def write_file_restricted(path, force: false, mode: nil)
-        assert(block_given?, exception_class: Aspera::InternalError)
+        Aspera.assert(block_given?, exception_class: Aspera::InternalError)
         if force || !File.exist?(path)
           # Windows may give error
           File.unlink(path) rescue nil

data/lib/aspera/faspex_gw.rb

@@ -8,12 +8,11 @@ require 'json'
 module Aspera
   # Simulate the Faspex 4 /send API and creates a package on Aspera on Cloud or Faspex 5
   class Faspex4GWServlet < WEBrick::HTTPServlet::AbstractServlet
-    # @param app_api [Aspera::AoC]
+    # @param app_api
     # @param app_context [String]
     def initialize(server, app_api, app_context)
-      assert_values(app_api.class.name, ['Aspera::AoC', 'Aspera::Rest'])
+      Aspera.assert_values(app_api.class.name, ['Aspera::Api::AoC', 'Aspera::Rest'])
       super(server)
-      # typed: Aspera::AoC
       @app_api = app_api
       @app_context = app_context
     end
@@ -51,7 +50,7 @@ module Aspera
         operation:   'POST',
         subpath:     "packages/#{package['id']}/transfer_spec/upload",
         headers:     {'Accept' => 'application/json'},
-        url_params:  {transfer_type: Aspera::Cli::Plugins::Faspex5::TRANSFER_CONNECT},
+        url_params:  {transfer_type: Cli::Plugins::Faspex5::TRANSFER_CONNECT},
         json_params: {paths: [{'destination'=>'/'}]}
       )[:data]
       transfer_spec.delete('authentication')
@@ -72,11 +71,11 @@ module Aspera
           # compare string, as class is not yet known here
           faspex_package_create_result =
             case @app_api.class.name
-            when 'Aspera::AoC'
+            when 'Aspera::Api::AoC'
               faspex4_send_to_aoc(faspex_pkg_parameters)
             when 'Aspera::Rest'
               faspex4_send_to_faspex5(faspex_pkg_parameters)
-            else error_unexpected_value(@app_api.class.name)
+            else Aspera.error_unexpected_value(@app_api.class.name)
             end
           Log.log.info{"faspex_package_create_result=#{faspex_package_create_result}"}
           response.status = 200

data/lib/aspera/faspex_postproc.rb

@@ -12,7 +12,7 @@ module Aspera
   class Faspex4PostProcServlet < WEBrick::HTTPServlet::AbstractServlet
     ALLOWED_PARAMETERS = %i[root script_folder fail_on_error timeout_seconds].freeze
     def initialize(server, parameters)
-      assert_type(parameters, Hash)
+      Aspera.assert_type(parameters, Hash)
       @parameters = parameters.symbolize_keys
       Log.log.debug{Log.dump(:post_proc_parameters, @parameters)}
       raise "unexpected key in parameters config: only: #{ALLOWED_PARAMETERS.join(', ')}" if @parameters.keys.any?{|k|!ALLOWED_PARAMETERS.include?(k)}

data/lib/aspera/id_generator.rb

@@ -17,10 +17,10 @@ module Aspera
             i.is_a?(String) && i.start_with?('https://') ? URI.parse(i).host : i.to_s
           end.join(ID_SEPARATOR)
         end
-        assert_type(object_id, String)
+        Aspera.assert_type(object_id, String)
         return object_id
             .gsub(WINDOWS_PROTECTED_CHAR, PROTECTED_CHAR_REPLACE) # remove windows forbidden chars
-            .gsub('.', PROTECTED_CHAR_REPLACE)  # keep dot for extension only (nicer)
+            .gsub('.', PROTECTED_CHAR_REPLACE) # keep dot for extension only (nicer)
             .downcase
       end
     end

data/lib/aspera/json_rpc.rb

@@ -35,11 +35,11 @@ module Aspera
         params:  args,
         id:      @request_id += 1
       })[:data]
-      assert_type(data, Hash){'response'}
-      assert(data['jsonrpc'] == JSON_RPC_VERSION){'bad version in response'}
-      assert(data.key?('id')){'missing id in response'}
-      assert(!(data.key?('error') && data.key?('result'))){'both error and response'}
-      assert(
+      Aspera.assert_type(data, Hash){'response'}
+      Aspera.assert(data['jsonrpc'] == JSON_RPC_VERSION){'bad version in response'}
+      Aspera.assert(data.key?('id')){'missing id in response'}
+      Aspera.assert(!(data.key?('error') && data.key?('result'))){'both error and response'}
+      Aspera.assert(
         !data.key?('error') ||
         data['error'].is_a?(Hash) &&
         data['error']['code'].is_a?(Integer) &&

data/lib/aspera/keychain/encrypted_hash.rb

@@ -17,7 +17,7 @@ module Aspera
       CONTENT_KEYS = %i[label username password url description].freeze
       FILE_KEYS = %w[version type cipher data].sort.freeze
       def initialize(path, current_password)
-        assert_type(path, String){'path to vault file'}
+        Aspera.assert_type(path, String){'path to vault file'}
         @path = path
         @all_secrets = {}
         vault_encrypted_data = nil
@@ -25,7 +25,7 @@ module Aspera
           vault_file = File.read(@path)
           if vault_file.start_with?('---')
             vault_info = YAML.parse(vault_file).to_ruby
-            assert(vault_info.keys.sort == FILE_KEYS){'Invalid vault file'}
+            Aspera.assert(vault_info.keys.sort == FILE_KEYS){'Invalid vault file'}
             @cipher_name = vault_info['cipher']
             vault_encrypted_data = vault_info['data']
           else
@@ -65,11 +65,11 @@ module Aspera
       # set a secret
       # @param options [Hash] with keys :label, :username, :password, :url, :description
       def set(options)
-        assert_type(options, Hash){'options'}
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - CONTENT_KEYS
-        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         options.each_pair do |k, v|
-          assert_type(v, String){k.to_s}
+          Aspera.assert_type(v, String){k.to_s}
         end
         label = options.delete(:label)
         raise "secret #{label} already exist, delete first" if @all_secrets.key?(label)
@@ -94,7 +94,7 @@ module Aspera
       end
 
       def get(label:, exception: true)
-        assert(@all_secrets.key?(label)){"Label not found: #{label}"} if exception
+        Aspera.assert(@all_secrets.key?(label)){"Label not found: #{label}"} if exception
         result = @all_secrets[label].clone
         result[:label] = label if result.is_a?(Hash)
         return result

data/lib/aspera/keychain/macos_security.rb

@@ -4,6 +4,7 @@
 require 'aspera/cli/info'
 require 'aspera/log'
 require 'aspera/assert'
+require 'open3'
 
 # enhance the gem to support other key chains
 module Aspera
@@ -11,6 +12,8 @@ module Aspera
     module MacosSecurity
       # keychain based on macOS keychain, using `security` command line
       class Keychain
+        # https://www.unix.com/man-page/osx/1/security/
+        SECURITY_UTILITY = 'security'
         DOMAINS = %i[user system common dynamic].freeze
         LIST_OPTIONS = {
           domain: :c
@@ -38,25 +41,27 @@ module Aspera
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
-              assert(uri.scheme.eql?('https')){'only https'}
+              Aspera.assert(uri.scheme.eql?('https')){'only https'}
               options[:protocol] = 'htps' # cspell: disable-line
               raise 'host required in URL' if uri.host.nil?
               options[:server] = uri.host
               options[:path] = uri.path unless ['', '/'].include?(uri.path)
               options[:port] = uri.port unless uri.port.eql?(443) && !url.include?(':443/')
             end
-            cmd = ['security', command]
+            command_line = [SECURITY_UTILITY, command]
             options&.each do |k, v|
-              assert(supported.key?(k)){"unknown option: #{k}"}
+              Aspera.assert(supported.key?(k)){"unknown option: #{k}"}
               next if v.nil?
-              cmd.push("-#{supported[k]}")
-              cmd.push(v.shellescape) unless v.empty?
+              command_line.push("-#{supported[k]}")
+              command_line.push(v.shellescape) unless v.empty?
             end
-            cmd.push(last_opt) unless last_opt.nil?
-            Log.log.debug{"executing>>#{cmd.join(' ')}"}
-            result = %x(#{cmd.join(' ')} 2>&1)
-            Log.log.debug{"result>>[#{result}]"}
-            return result
+            command_line.push(last_opt) unless last_opt.nil?
+            Log.log.debug{"executing>>#{command_line.join(' ')}"}
+            stdout, stderr, status = Open3.capture3(*command_line)
+            Log.log.debug{"status=#{status}, stderr=#{stderr}"}
+            Log.log.trace1{"stdout=#{stdout}"}
+            raise "#{SECURITY_UTILITY} failed: #{status.exitstatus} : #{stderr}" unless status.success?
+            return stdout
           end
 
           def key_chains(output)
@@ -72,7 +77,7 @@ module Aspera
           end
 
           def list(options={})
-            assert_values(options[:domain], DOMAINS, exception_class: ArgumentError){'domain'} unless options[:domain].nil?
+            Aspera.assert_values(options[:domain], DOMAINS, exception_class: ArgumentError){'domain'} unless options[:domain].nil?
             key_chains(execute('list-key_chains', options, LIST_OPTIONS))
           end
 
@@ -91,15 +96,15 @@ module Aspera
         end
 
         def password(operation, pass_type, options)
-          assert_values(operation, %i[add find delete]){'operation'}
-          assert_values(pass_type, %i[generic internet]){'pass_type'}
-          assert_type(options, Hash)
+          Aspera.assert_values(operation, %i[add find delete]){'operation'}
+          Aspera.assert_values(pass_type, %i[generic internet]){'pass_type'}
+          Aspera.assert_type(options, Hash)
           missing = (operation.eql?(:add) ? %i[account service password] : %i[label]) - options.keys
-          assert(missing.empty?){"missing options: #{missing}"}
+          Aspera.assert(missing.empty?){"missing options: #{missing}"}
           options[:getpass] = '' if operation.eql?(:find)
           output = self.class.execute("#{operation}-#{pass_type}-password", options, ADD_PASS_OPTIONS, @path)
           raise output.gsub(/^.*: /, '') if output.start_with?('security: ')
-          return nil unless operation.eql?(:find)
+          return unless operation.eql?(:find)
           attributes = {}
           output.split("\n").each do |line|
             case line
@@ -129,18 +134,18 @@ module Aspera
       end
 
       def set(options)
-        assert_type(options, Hash){'options'}
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label username password url description]
-        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         @keychain.password(
           :add, :generic, service: options[:label],
           account: options[:username] || 'none', password: options[:password], comment: options[:description])
       end
 
       def get(options)
-        assert_type(options, Hash){'options'}
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         info = @keychain.password(:find, :generic, label: options[:label])
         raise 'not found' if info.nil?
         result = options.clone
@@ -155,9 +160,9 @@ module Aspera
       end
 
       def delete(options)
-        assert_type(options, Hash){'options'}
+        Aspera.assert_type(options, Hash){'options'}
         unsupported = options.keys - %i[label]
-        assert(unsupported.empty?){"unsupported options: #{unsupported}"}
+        Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         raise 'delete not implemented, use macos keychain app'
       end
     end

data/lib/aspera/log.rb

@@ -14,7 +14,7 @@ class Logger
   TRACE_MAX = 2
   # add custom level to logger severity
   module Severity
-    1.upto(TRACE_MAX).each { |level| const_set("TRACE#{level}", - level)}
+    1.upto(TRACE_MAX).each { |level| const_set(:"TRACE#{level}", - level)}
   end
   # quick access to label
   SEVERITY_LABEL = Severity.constants.each_with_object({}) { |name, hash| hash[Severity.const_get(name)] = name}
@@ -99,7 +99,7 @@ module Aspera
       Logger::Severity.constants.each do |name|
         return name.downcase.to_sym if @logger.level.eql?(Logger::Severity.const_get(name))
       end
-      error_unexpected_value(@logger.level){'log level'}
+      Aspera.error_unexpected_value(@logger.level){'log level'}
     end
 
     # change underlying logger, but keep log level

data/lib/aspera/nagios.rb

@@ -23,10 +23,10 @@ module Aspera
     class << self
       # process results of a analysis and display status and exit with code
       def process(data)
-        assert_type(data, Array)
-        assert(!data.empty?){'data is empty'}
+        Aspera.assert_type(data, Array)
+        Aspera.assert(!data.empty?){'data is empty'}
         %w[status component message].each do |c|
-          assert(data.first.key?(c)){"result must have #{c}"}
+          Aspera.assert(data.first.key?(c)){"result must have #{c}"}
         end
         res_errors = data.reject{|s|s['status'].eql?('ok')}
         # keep only errors in case of problem, other ok are assumed so

data/lib/aspera/node_simulator.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
+require 'aspera/ascp/installation'
+require 'aspera/agent/direct'
 require 'aspera/log'
-require 'aspera/fasp/installation'
-require 'aspera/fasp/agent_direct'
 require 'webrick'
 require 'json'
 
@@ -11,12 +11,12 @@ module Aspera
   class NodeSimulatorServlet < WEBrick::HTTPServlet::AbstractServlet
     PATH_TRANSFERS = '/ops/transfers'
     PATH_ONE_TRANSFER = %r{/ops/transfers/(.+)$}
-    # @param app_api [Aspera::AoC]
+    # @param app_api [Api::AoC]
     # @param app_context [String]
     def initialize(server, credentials, transfer)
       super(server)
       @credentials = credentials
-      @xfer_manager = Aspera::Fasp::AgentDirect.new
+      @xfer_manager = Agent::Direct.new
     end
 
     def do_POST(request, response)
@@ -27,7 +27,6 @@ module Aspera
         result = session[:ts].clone
         result['id'] = job_id
         set_json_response(response, result)
-        Log.log.debug{">>> transfer started: #{job_id}"}
       else
         set_json_response(response, [{error: 'Bad request'}], code: 400)
       end
@@ -36,7 +35,7 @@ module Aspera
     def do_GET(request, response)
       case request.path
       when '/info'
-        info = Aspera::Fasp::Installation.instance.ascp_info
+        info = Ascp::Installation.instance.ascp_info
         set_json_response(response, {
           application:                           'node',
           current_time:                          Time.now.utc.iso8601(0),

data/lib/aspera/oauth/base.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'aspera/oauth/factory'
+require 'aspera/log'
+require 'aspera/assert'
+require 'aspera/id_generator'
+require 'date'
+
+module Aspera
+  module OAuth
+    # Implement OAuth 2 for the REST client and generate a bearer token
+    # call get_authorization() to get a token.
+    # bearer tokens are kept in memory and also in a file cache for later re-use
+    # if a token is expired (api returns 4xx), call again get_authorization(refresh: true)
+    # https://tools.ietf.org/html/rfc6749
+    class Base
+      # scope can be modified after creation
+      attr_writer :scope
+
+      # [M]=mandatory [D]=has default value [O]=Optional/nil
+      # @param base_url            [M] URL of authentication API
+      # @param auth                [O] basic auth parameters
+      # @param client_id           [O]
+      # @param client_secret       [O]
+      # @param scope               [O]
+      # @param path_token          [D] API end point to create a token
+      # @param token_field         [D] field in result that contains the token
+      def initialize(
+        base_url:,
+        auth: nil,
+        client_id: nil,
+        client_secret: nil,
+        scope: nil,
+        path_token:  'token',       # default endpoint for /token to generate token
+        token_field: 'access_token' # field with token in result of call to path_token
+      )
+        Aspera.assert_type(base_url, String)
+        Aspera.assert(respond_to?(:create_token), 'create_token method must be defined', exception_class: InternalError)
+        @base_url = base_url
+        @path_token = path_token
+        @token_field = token_field
+        @client_id = client_id
+        @client_secret = client_secret
+        @scope = scope
+        @identifiers = []
+        @identifiers.push(auth[:username]) if auth.is_a?(Hash) && auth.key?(:username)
+        # this is the OAuth API
+        @api = Rest.new(
+          base_url:     @base_url,
+          redirect_max: 2,
+          auth:         auth)
+      end
+
+      # helper method to create token as per RFC
+      def create_token_call(www_params)
+        Log.log.debug{'Generating a new token'.bg_green}
+        return @api.call(
+          operation:       'POST',
+          subpath:         @path_token,
+          headers:         {'Accept' => 'application/json'},
+          www_body_params: www_params)
+      end
+
+      # @return Hash with optional general parameters
+      def optional_scope_client_id(add_secret: false)
+        call_params = {}
+        call_params[:scope] = @scope unless @scope.nil?
+        call_params[:client_id] = @client_id unless @client_id.nil?
+        call_params[:client_secret] = @client_secret if add_secret && !@client_id.nil?
+        return call_params
+      end
+
+      # OAuth v2 token generation
+      # @param use_refresh_token set to true to force refresh or re-generation (if previous failed)
+      def get_authorization(use_refresh_token: false, use_cache: true)
+        # generate token unique identifier for persistency (memory/disk cache)
+        token_id = IdGenerator.from_list(Factory.id(
+          @base_url,
+          @grant_method,
+          @identifiers,
+          @scope
+        ))
+
+        # get token_data from cache (or nil), token_data is what is returned by /token
+        token_data = Factory.instance.persist_mgr.get(token_id) if use_cache
+        token_data = JSON.parse(token_data) unless token_data.nil?
+        # Optional optimization: check if node token is expired based on decoded content then force refresh if close enough
+        # might help in case the transfer agent cannot refresh himself
+        # `direct` agent is equipped with refresh code
+        if !use_refresh_token && !token_data.nil?
+          decoded_token = OAuth::Factory.instance.decode_token(token_data[@token_field])
+          Log.log.debug{Log.dump('decoded_token', decoded_token)} unless decoded_token.nil?
+          if decoded_token.is_a?(Hash)
+            expires_at_sec =
+              if    decoded_token['expires_at'].is_a?(String) then DateTime.parse(decoded_token['expires_at']).to_time
+              elsif decoded_token['exp'].is_a?(Integer)       then Time.at(decoded_token['exp'])
+              end
+            # force refresh if we see a token too close from expiration
+            use_refresh_token = true if expires_at_sec.is_a?(Time) && (expires_at_sec - Time.now) < OAuth::Factory.instance.globals[:token_expiration_guard_sec]
+            Log.log.debug{"Expiration: #{expires_at_sec} / #{use_refresh_token}"}
+          end
+        end
+
+        # an API was already called, but failed, we need to regenerate or refresh
+        if use_refresh_token
+          if token_data.is_a?(Hash) && token_data.key?('refresh_token') && !token_data['refresh_token'].eql?('not_supported')
+            # save possible refresh token, before deleting the cache
+            refresh_token = token_data['refresh_token']
+          end
+          # delete cache
+          Factory.instance.persist_mgr.delete(token_id)
+          token_data = nil
+          # lets try the existing refresh token
+          if !refresh_token.nil?
+            Log.log.info{"refresh=[#{refresh_token}]".bg_green}
+            # try to refresh
+            # note: AoC admin token has no refresh, and lives by default 1800secs
+            resp = create_token_call(optional_scope_client_id.merge(grant_type: 'refresh_token', refresh_token: refresh_token))
+            if resp[:http].code.start_with?('2')
+              # save only if success
+              json_data = resp[:http].body
+              token_data = JSON.parse(json_data)
+              Factory.instance.persist_mgr.put(token_id, json_data)
+            else
+              Log.log.debug{"refresh failed: #{resp[:http].body}".bg_red}
+            end
+          end
+        end
+
+        # no cache, nor refresh: generate a token
+        if token_data.nil?
+          resp = create_token
+          json_data = resp[:http].body
+          token_data = JSON.parse(json_data)
+          Factory.instance.persist_mgr.put(token_id, json_data)
+        end # if ! in_cache
+        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"}
+        # ok we shall have a token here
+        return OAuth::Factory.bearer_build(token_data[@token_field])
+      end
+    end # OAuth
+  end
+end