aspera-cli 4.26.0 → 4.26.2

data/lib/aspera/command_line_builder.rb

@@ -2,6 +2,7 @@
 
 require 'aspera/log'
 require 'aspera/assert'
+require 'aspera/schema/registry'
 require 'yaml'
 module Aspera
   # Helper class to build command line from a parameter list (key-value hash)
@@ -35,9 +36,9 @@ module Aspera
 
     class << self
       # Called by provider of definition before constructor of this class so that schema has all mandatory fields
-      def read_schema(folder, name, ascp: false)
-        schema = YAML.load_file(File.join(folder, "#{name}.schema.yaml"))
-        validate_schema(schema, ascp: ascp)
+      # @return [Aspera::Schema::Reader]
+      def read_schema(name_sym, ascp: false)
+        validate_schema(Schema::Registry.instance.reader(name_sym), ascp: ascp)
       end
 
       # @param agent      [Symbol] Transfer agent name
@@ -49,29 +50,32 @@ module Aspera
 
       private
 
+      DIRECT_PROPERTIES = %w[x-cli-option x-cli-envvar x-cli-special].freeze
+
       # Fill default values for some fields in the schema
-      # @param schema [Hash]    The JSON schema
-      # @param ascp   [Boolean] `true` if ascp
+      # @param schema [Schema::Reader] The JSON schema
+      # @param ascp [Boolean] `true` if `ascp`
+      # @return [Schema::Reader] The JSON schema
       def validate_schema(schema, ascp: false)
-        direct_props = %w[x-cli-option x-cli-envvar x-cli-special].freeze
-        schema['properties'].each do |name, info|
-          Aspera.assert_type(info, Hash){"#{info.class} for #{name}"}
-          unsupported_keys = info.keys - PROPERTY_KEYS
+        Aspera.assert_type(schema, Schema::Reader){'schema'}
+        Aspera.assert(schema.current.key?('properties')){"Schema must have 'properties': #{schema}"}
+        schema.each_property do |property_schema, name, _full_name|
+          node = property_schema.current
+          unsupported_keys = node.keys - PROPERTY_KEYS
           Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          Aspera.assert(info.key?('type') || info.key?('enum')){"Missing type for #{name} in #{schema['description']}"}
-          Aspera.assert(info['type'].eql?('boolean')){"switch must be bool: #{name}"} if info['x-cli-switch'] && !info['x-cli-special']
-          info['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if info['x-cli-option'].eql?(true) || (info['x-cli-switch'].eql?(true) && !info.key?('x-cli-option'))
-          Aspera.assert(direct_props.any?{ |i| info.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, info)
-          info.freeze
-          validate_schema(info, ascp: ascp) if info['type'].eql?('object') && info['properties']
-          validate_schema(info['items'], ascp: ascp) if info['type'].eql?('array') && info['items'] && info['items']['properties']
+          Aspera.assert(node.key?('type') || node.key?('enum')){"Missing type for #{name} in #{schema.current.dig('description').current}"}
+          Aspera.assert(node['type'].eql?('boolean')){"switch must be bool: #{name}"} if node['x-cli-switch'] && !node['x-cli-special']
+          node['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if node['x-cli-option'].eql?(true) || (node['x-cli-switch'].eql?(true) && !node.key?('x-cli-option'))
+          Aspera.assert(DIRECT_PROPERTIES.any?{ |i| node.key?(i)}, name, type: :warn) if ascp && supported_by_agent(:direct, node)
+          node.freeze
         end
         schema
       end
     end
 
-    # @param [Hash] object with parameters
-    # @param [Hash] schema JSON schema
+    # @param object [Hash] object with parameters
+    # @param schema [Schema::Reader] JSON schema
+    # @param convert [Object] function to convert value
     def initialize(object, schema, convert)
       @object = object # keep reference so that it can be modified by caller before calling `process_params`
       @schema = schema

data/lib/aspera/data_repository.rb

@@ -6,6 +6,10 @@ require 'openssl'
 
 module Aspera
   # a simple binary data repository
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of DataRepository
+  #   @return [DataRepository] the singleton instance
   class DataRepository
     include Singleton
 

data/lib/aspera/dot_container.rb

@@ -39,7 +39,7 @@ module Aspera
       # @param container [Hash, Array]
       # @param index     [String, Integer]
       def array_requires_integer_index!(container, index)
-        Aspera.assert(container.is_a?(Hash) || index.is_a?(Integer)){'Using String index when Integer index used previously'}
+        Aspera.assert(container.is_a?(Hash) || index.is_a?(Integer), 'Using String index when Integer index used previously')
       end
 
       # Create a new `Hash` or `Array` depending on type of `key`

data/lib/aspera/environment.rb

@@ -13,6 +13,10 @@ require 'shellwords'
 
 module Aspera
   # detect OS, architecture, and specific stuff
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of Environment
+  #   @return [Environment] the singleton instance
   class Environment
     include Singleton
 
@@ -111,7 +115,7 @@ module Aspera
       # @raise [RuntimeError] If `:exception` is `true` and the process fails in `:capture` mode.
       def secure_execute(*cmd, mode: :execute, **kwargs)
         cmd = cmd.map(&:to_s)
-        Aspera.assert(cmd.size.positive?, type: ArgumentError){'executable must be present'}
+        Aspera.assert(cmd.size.positive?, 'executable must be present', type: ArgumentError)
         Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError){'mode'}
         Log.log.debug do
           parts = [mode.to_s, 'command:']
@@ -151,9 +155,9 @@ module Aspera
       # @param path [String] the file path
       # @param force [Boolean] if true, overwrite the file
       # @param mode [Integer] the file mode (permissions)
-      # @block [Proc] return the content to write to the file
+      # @yieldreturn [String] The content to write to the file
       def write_file_restricted(path, force: false, mode: nil)
-        Aspera.assert(block_given?, type: Aspera::InternalError)
+        Aspera.assert(block_given?, 'block required for write_file_restricted', type: Aspera::InternalError)
         if force || !File.exist?(path)
           # Windows may give error
           File.unlink(path) rescue nil
@@ -192,10 +196,24 @@ module Aspera
       end
 
       # @return true if we can display Unicode characters
+      # Uses Encoding.locale_charmap for OS-independent detection.
+      # Falls back to locale env vars for systems where charmap is not available.
       # https://www.gnu.org/software/libc/manual/html_node/Locale-Categories.html
       # https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html
       def terminal_supports_unicode?
-        terminal? && I18N_VARS.any?{ |var| ENV[var]&.include?('UTF-8')}
+        return false unless terminal?
+        locale_charmap_utf8? || I18N_VARS.any?{ |var| ENV[var]&.include?('UTF-8')}
+      end
+
+      private
+
+      # @return true if the locale charmap resolves to UTF-8
+      # Unix: nl_langinfo(CODESET) returns "UTF-8"
+      # Windows: GetACP returns "CP65001" which Encoding.find resolves as UTF-8
+      def locale_charmap_utf8?
+        Encoding.find(Encoding.locale_charmap) == Encoding::UTF_8
+      rescue ArgumentError
+        false
       end
     end
     attr_accessor :url_method, :file_illegal_characters
@@ -266,6 +284,7 @@ module Aspera
       return unless @os.eql?(OS_WINDOWS) && ENV.key?('USERPROFILE') && Dir.exist?(ENV.fetch('USERPROFILE', nil))
       ENV['HOME'] = ENV.fetch('USERPROFILE', nil)
       Log.log.debug{"Windows: set HOME to USERPROFILE: #{Dir.home}"}
+      nil
     end
 
     def graphical?
@@ -280,7 +299,7 @@ module Aspera
       when Environment::OS_MACOS then return self.class.secure_execute('open', uri.to_s)
       when Environment::OS_WINDOWS then return self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
       when Environment::OS_LINUX   then return self.class.secure_execute('xdg-open', uri.to_s)
-      else Assert.error_unexpected_value(os){'no graphical open method'}
+      else Aspera.error_unexpected_value(os){'no graphical open method'}
       end
     end
 
@@ -334,7 +353,7 @@ module Aspera
       filename = filename.chop while filename.end_with?(' ', '.')
       if @file_illegal_characters&.size.to_i >= 2
         # replace all illegal characters with safe_char
-        filename = filename.tr(@file_illegal_characters[1..-1], safe_char)
+        filename = filename.tr(@file_illegal_characters[1..], safe_char)
       end
       # ensure only one safe_char is used at a time
       return filename.gsub(/#{Regexp.escape(safe_char)}+/, safe_char).chomp(safe_char)

data/lib/aspera/faspex_gw.rb

@@ -68,7 +68,7 @@ module Aspera
       case request.path
       when '/aspera/faspex/send'
         begin
-          Aspera.assert(!request.body.nil?){'payload missing'}
+          Aspera.assert(!request.body.nil?, 'payload missing')
           faspex_pkg_parameters = JSON.parse(request.body)
           Log.log.debug{"faspex pkg create parameters=#{faspex_pkg_parameters}"}
           # compare string, as class is not yet known here

data/lib/aspera/formatter_interface.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+
+module Aspera
+  # Common interface for documentation formatters
+  # Used by Schema::Documentation to format tables
+  module FormatterInterface
+    Aspera.require_method!(:tick)
+    Aspera.require_method!(:special_format)
+    Aspera.require_method!(:check_row)
+    Aspera.require_method!(:markdown_text)
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -9,6 +9,12 @@ class ::Hash
     merge!(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
   end
 
+  # Recursively iterate through hash and execute block on leaf values
+  # @param memory [Object, nil] Optional memory object passed to block
+  # @yieldparam hash [Hash] The current hash
+  # @yieldparam key [Object] The current key
+  # @yieldparam value [Object] The current value (non-Hash)
+  # @yieldparam memory [Object, nil] The memory object
   def deep_do(memory = nil, &block)
     each do |key, value|
       if value.is_a?(Hash)

data/lib/aspera/json_rpc.rb

@@ -36,15 +36,16 @@ module Aspera
         id:      @request_id += 1
       })
       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['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['error']['message'].is_a?(String)
-      ){'bad error response'}
+        data['error']['message'].is_a?(String),
+        'bad error response'
+      )
       return data['result']
     end
   end

data/lib/aspera/keychain/base.rb

@@ -11,7 +11,7 @@ module Aspera
         options.each_pair do |k, v|
           Aspera.assert_type(v, String){k.to_s}
         end
-        Aspera.assert(options.key?(:label)){'label is required'}
+        Aspera.assert(options.key?(:label), 'label is required')
       end
     end
   end

data/lib/aspera/keychain/encrypted_hash.rb

@@ -28,7 +28,7 @@ module Aspera
           vault_file = File.read(@path)
           if vault_file.start_with?('---')
             vault_info = YAML.parse(vault_file).to_ruby
-            Aspera.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

data/lib/aspera/keychain/factory.rb

@@ -20,7 +20,7 @@ module Aspera
           when 'file'
             info[:file] = name || 'vault.bin'
             info[:file] = File.join(folder, info[:file]) unless File.absolute_path?(info[:file])
-            Aspera.assert(!password.nil?){'please provide password'}
+            Aspera.assert(!password.nil?, 'please provide password')
             info[:password] = password
             # this module requires compilation, so it is optional
             require 'aspera/keychain/encrypted_hash'

data/lib/aspera/keychain/macos_security.rb

@@ -42,7 +42,7 @@ module Aspera
             url = options&.delete(:url)
             if !url.nil?
               uri = URI.parse(url)
-              Aspera.assert(uri.scheme.eql?('https')){'only https'}
+              Aspera.assert(uri.scheme.eql?('https'), 'only https')
               options[:protocol] = 'htps' # cspell: disable-line
               raise Error, 'host required in URL' if uri.host.nil?
               options[:server] = uri.host

data/lib/aspera/log.rb

@@ -54,6 +54,10 @@ $VERBOSE = old_verbose
 
 module Aspera
   # Singleton object for logging
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of Log
+  #   @return [Log] the singleton instance
   class Log
     include Singleton
 
@@ -77,10 +81,10 @@ module Aspera
       # @param name   [String, Symbol]  Name of object dumped
       # @param object [Hash, nil]       Data to dump
       # @param level  [Symbol]          Debug level
-      # @param block  [Proc, nil]       Give computed object
+      # @yieldreturn [Object] Computed object to dump (alternative to object parameter)
       def dump(name, object = nil, level: :debug, &block)
         return unless instance.logger.send(:"#{level}?")
-        Aspera.assert(object.nil? || block.nil?){'Use either object, or block, not both'}
+        Aspera.assert(object.nil? || block.nil?, 'Use either object, or block, not both')
         object = yield if block_given?
         instance.logger.send(level, obj_dump(name, object))
       end
@@ -93,12 +97,13 @@ module Aspera
             JSON.pretty_generate(object) rescue PP.pp(object, +'')
           when :ruby
             PP.pp(object, +'')
-          else error_unexpected_value(instance.dump_format){'dump format'}
+          else Aspera.error_unexpected_value(instance.dump_format){'dump format'}
           end
         "#{name.to_s.green}(#{instance.dump_format})#{object.class}=\n#{dump_text}"
       end
 
       # Capture the output of $stderr and log it at debug level
+      # @yieldreturn [void] Code block whose stderr output will be captured
       def capture_stderr
         real_stderr = $stderr
         $stderr = StringIO.new
@@ -167,7 +172,7 @@ module Aspera
     # Get symbol of debug level of underlying logger
     # @return [Symbol] One of LEVELS
     def level
-      Aspera.assert(Logger::SEVERITY_LABEL.key?(@logger.level))
+      Aspera.assert(Logger::SEVERITY_LABEL.key?(@logger.level), 'unexpected logger level value')
       Logger::SEVERITY_LABEL[@logger.level].downcase
     end
 
@@ -192,7 +197,7 @@ module Aspera
         end
         # Use `local2` facility, like other Aspera components
         @logger = Syslog::Logger.new(@program_name, Syslog::LOG_LOCAL2)
-      else error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
+      else Aspera.error_unexpected_value(new_log_type){"log type (#{LOG_TYPES.join(', ')})"}
       end
       @logger.level = current_severity_integer
       @logger_type = new_log_type

data/lib/aspera/markdown.rb

@@ -8,11 +8,14 @@ module Aspera
     HTML_BREAK = '<br/>'
 
     class << self
+      COL_WIDTH = 80
       # Generate markdown from the provided 2D table
+      # @param table [Array<Array<String>>] 2D array of strings
+      # @return [String] markdown table
       def table(table)
         # get max width of each columns
         col_widths = table.transpose.map do |col|
-          [col.flat_map{ |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size)}.max, 80].min
+          [col.flat_map{ |c| c.to_s.delete('`').split(HTML_BREAK).map(&:size)}.max, COL_WIDTH].min
         end
         headings = table.shift
         table.unshift(col_widths.map{ |col_width| '-' * col_width})

data/lib/aspera/nagios.rb

@@ -24,7 +24,7 @@ module Aspera
       # Process results of a analysis and display status and exit with code
       def process(data)
         Aspera.assert_type(data, Array)
-        Aspera.assert(!data.empty?){'data is empty'}
+        Aspera.assert(!data.empty?, 'data is empty')
         %w[status component message].each do |c|
           Aspera.assert(data.first.key?(c)){"result must have #{c}"}
         end
@@ -79,7 +79,7 @@ module Aspera
     # Readable status list
     # @return [Array] of Hash
     def status_list
-      Aspera.assert(!@data.empty?){'missing result'}
+      Aspera.assert(!@data.empty?, 'missing result')
       @data.map{ |i| {'status' => LEVELS[i[:code]].to_s, 'component' => i[:comp], 'message' => i[:msg]}}
     end
   end

data/lib/aspera/oauth/base.rb

@@ -15,15 +15,15 @@ module Aspera
     class Base
       Aspera.require_method!(:create_token)
       # @param params         [Hash]    Parameters for token creation (client_id, client_secret, scope, etc...)
-      # @param use_query      [Boolean] Provide parameters in query instead of body
       # @param path_token     [String]  API end point to create a token from base URL
+      # @param use_query      [Boolean] Provide parameters in query instead of body
       # @param token_field    [String]  Field in result that contains the token
       # @param cache_ids      [Array]   List of unique identifiers for cache id generation
       # @param **rest_params  [Hash]    Parameters for REST
       def initialize(
         params: {},
+        path_token: 'token',
         use_query: false,
-        path_token:  'token',
         token_field: Factory::TOKEN_FIELD,
         cache_ids: [],
         **rest_params
@@ -42,10 +42,10 @@ module Aspera
 
       # The OAuth API Object
       attr_reader :api
-      # Sub path to generate token
-      attr_reader :path_token
       # Parameters to generate token
       attr_reader :params
+      # Sub path to generate token
+      attr_reader :path_token
 
       # Helper method to create token as per RFC
       # @return [HTTPResponse]
@@ -122,7 +122,7 @@ module Aspera
           token_data = JSON.parse(json_data)
           Factory.instance.persist_mgr.put(@token_cache_id, json_data)
         end
-        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"}
+        Aspera.assert(token_data.key?(@token_field)){"API error: No such field in answer: #{@token_field}"} unless token_data.nil?
         # ok we shall have a token here
         return token_data[@token_field]
       end

data/lib/aspera/oauth/boot.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'aspera/oauth/base'
+require 'aspera/assert'
+require 'json'
+
+module Aspera
+  module OAuth
+    # Token provider bootstrapped from an existing cookie (e.g. AoC browser cookie).
+    # Injects the bearer token and optional refresh token directly into the cache.
+    # Never generates a new token from scratch — raises if cache+refresh are both exhausted.
+    class Boot < Base
+      # @param cookie   [String, nil] Raw cookie string (--password), nil to rely on existing cache
+      # @param username [String, nil] Expected subject; if provided, must match token's `sub` claim
+      # @param **base_params          Forwarded to Base (base_url:, params: {client_id:, scope:}, etc.)
+      def initialize(cookie: nil, username: nil, **base_params)
+        if cookie.nil?
+          # No cookie: rely on existing cache, identified by username if provided
+          Aspera.assert(username, 'Provide --password (cookie) on first use, or --username for cache lookup', type: ParameterError)
+          super(**base_params, cache_ids: [username])
+        else
+          cookies = cookie.split('; ').map{ |p| p.split('=', 2)}.to_h
+          Aspera.assert(cookies.key?('aoc.token'), '--password cookie does not contain aoc.token', type: ParameterError)
+          token = cookies['aoc.token']
+          decoded = Factory.instance.decode_token(token)
+          Aspera.assert_type(decoded, Hash){'Boot: token is not a decodable JWT'}
+          sub = decoded['sub']
+          Aspera.assert(username.nil? || username.eql?(sub)){"Boot: --username #{username} does not match token subject #{sub}"}
+          super(**base_params, cache_ids: [sub])
+          token_data = {Factory::TOKEN_FIELD => token}
+          token_data['refresh_token'] = cookies['aoc.refresh'] if cookies.key?('aoc.refresh')
+          Factory.instance.persist_mgr.put(@token_cache_id, JSON.generate(token_data))
+        end
+      end
+
+      # Should never be reached: if cache and refresh are both exhausted, re-authenticate via browser
+      def create_token
+        Aspera.report_error(AssertError, 'Boot: token expired and no refresh available — re-authenticate in browser')
+      end
+    end
+    Factory.instance.register_token_creator(Boot)
+  end
+end

data/lib/aspera/oauth/factory.rb

@@ -7,10 +7,14 @@ require 'base64'
 module Aspera
   module OAuth
     # Factory to create tokens and manage their cache
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of Factory
+    #   @return [Factory] the singleton instance
     class Factory
       include Singleton
 
-      # a prefix for persistency of tokens (simplify garbage collect)
+      # prefix for persistency of tokens (simplify garbage collect)
       PERSIST_CATEGORY_TOKEN = 'token'
       # prefix for bearer authorization when in header
       SPACE_BEARER_AUTH_SCHEME = 'Bearer '
@@ -19,33 +23,40 @@ module Aspera
       private_constant :PERSIST_CATEGORY_TOKEN, :SPACE_BEARER_AUTH_SCHEME
 
       class << self
+        # Format a token for use in Authorization header
         # @param token [String] The token alone
         # @return [String] Value suitable for Authorization header
         def bearer_authorization(token)
           return "#{SPACE_BEARER_AUTH_SCHEME}#{token}"
         end
 
-        # @return true if the authorization contains a bearer token , i.e. auth scheme is bearer
+        # Check if the authorization contains a bearer token
+        # @param authorization [String] The authorization header value
+        # @return [Boolean] true if the authorization contains a bearer token, i.e. auth scheme is bearer
         def bearer_auth?(authorization)
           return authorization.start_with?(SPACE_BEARER_AUTH_SCHEME)
         end
 
         # Extract only token from Authorization (remove scheme)
+        # @param authorization [String] The authorization header value
+        # @return [String] The bearer token without the scheme prefix
         def bearer_token(authorization)
           Aspera.assert(bearer_auth?(authorization)){'not a bearer token, wrong prefix scheme'}
-          return authorization[SPACE_BEARER_AUTH_SCHEME.length..-1]
+          return authorization.delete_prefix(SPACE_BEARER_AUTH_SCHEME)
         end
 
         # Generate a unique cache id for a token creator
         # @param url           [String] Base URL of the OAuth server
         # @param creator_class [Class]  Class of the token creator
         # @param params        [Array]  List of parameters (can be nested) to uniquely identify the token
-        # @return a unique cache identifier
+        # @return [String] a unique cache identifier
         def cache_id(url, creator_class, *params)
           return IdGenerator.from_list(PERSIST_CATEGORY_TOKEN, url, Factory.class_to_id(creator_class), params)
         end
 
-        # @return snake version of class name
+        # Convert a class name to snake_case symbol
+        # @param creator_class [Class] The class to convert
+        # @return [Symbol] snake_case version of class name
         def class_to_id(creator_class)
           return creator_class.name.split('::').last.capital_to_snake.to_sym
         end
@@ -53,6 +64,7 @@ module Aspera
 
       private
 
+      # Initialize the factory with default parameters and empty collections
       def initialize
         # persistency manager
         @persist = nil
@@ -73,12 +85,16 @@ module Aspera
 
       attr_reader :parameters
 
+      # Set the persistence manager for token caching
+      # @param manager [Object] The persistence manager instance
       def persist_mgr=(manager)
         @persist = manager
         # cleanup expired tokens
         @persist.garbage_collect(PERSIST_CATEGORY_TOKEN, @parameters[:token_cache_max_age])
       end
 
+      # Get or initialize the persistence manager
+      # @return [Object] The persistence manager instance
       def persist_mgr
         if @persist.nil?
           # use OAuth::Factory.instance.persist_mgr=PersistencyFolder.new)
@@ -91,11 +107,14 @@ module Aspera
         return @persist
       end
 
-      # delete all existing tokens
+      # Delete all existing tokens in cache
+      # @return [void]
       def flush_tokens
         persist_mgr.garbage_collect(PERSIST_CATEGORY_TOKEN)
       end
 
+      # Retrieve all persisted tokens with their decoded information
+      # @return [Array<Hash>] Array of token information hashes
       def persisted_tokens
         data = persist_mgr.current_items(PERSIST_CATEGORY_TOKEN)
         data.each.map do |k, v|
@@ -134,12 +153,16 @@ module Aspera
         return info
       end
 
-      # register a bearer token decoder, mainly to inspect expiry date
+      # Register a bearer token decoder for inspecting token properties
+      # @param method [Proc] The decoder lambda/proc to register
+      # @return [void]
       def register_decoder(method)
         @decoders.push(method)
       end
 
-      # decode token using all registered decoders
+      # Decode a token using all registered decoders
+      # @param token [String] The token to decode
+      # @return [Hash, nil] Decoded token data or nil if no decoder succeeded
       def decode_token(token)
         @decoders.each do |decoder|
           result = decoder.call(token) rescue nil
@@ -148,10 +171,9 @@ module Aspera
         return
       end
 
-      # register a token creation method
-      # @param id creation type from field :grant_method in constructor
-      # @param lambda_create called to create token
-      # @param id_create called to generate unique id for token, for cache
+      # Register a token creation method
+      # @param creator_class [Class] The token creator class to register
+      # @return [void]
       def register_token_creator(creator_class)
         Aspera.assert_type(creator_class, Class)
         id = Factory.class_to_id(creator_class)
@@ -159,7 +181,9 @@ module Aspera
         @token_type_classes[id] = creator_class
       end
 
-      # @return one of the registered creators for the given create type
+      # Create a token creator instance for the specified grant method
+      # @param parameters [Hash] Parameters including :grant_method and creator-specific options
+      # @return [Object] An instance of the registered token creator class
       def create(**parameters)
         Aspera.assert_type(parameters, Hash)
         id = parameters[:grant_method]
@@ -169,6 +193,6 @@ module Aspera
       end
     end
     # JSON Web Signature (JWS) compact serialization: https://datatracker.ietf.org/doc/html/rfc7515
-    Factory.instance.register_decoder(lambda{ |token| parts = token.split('.'); Aspera.assert(parts.length.eql?(3)){'not JWS token'}; JSON.parse(Base64.decode64(parts[1]))}) # rubocop:disable Style/Semicolon
+    Factory.instance.register_decoder(lambda{ |token| parts = token.split('.'); Aspera.assert_values(parts.length, [3]){'JWS token parts'}; JSON.parse(Base64.decode64(parts[1]))}) # rubocop:disable Style/Semicolon
   end
 end

data/lib/aspera/oauth/web.rb

@@ -22,8 +22,8 @@ module Aspera
         @redirect_uri = redirect_uri
         @path_authorize = path_authorize
         uri = URI.parse(@redirect_uri)
-        Aspera.assert(%w[http https].include?(uri.scheme)){'redirect_uri scheme must be http or https'}
-        Aspera.assert(!uri.port.nil?){'redirect_uri must have a port'}
+        Aspera.assert_values(uri.scheme, %w[http https]){'redirect_uri scheme must be http or https'}
+        Aspera.assert(!uri.port.nil?, 'redirect_uri must have a port')
         # TODO: we could check that host is localhost or local address, as we are going to listen locally
       end
 

data/lib/aspera/oauth.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'aspera/oauth/factory'
+require 'aspera/oauth/boot'
 require 'aspera/oauth/generic'
 require 'aspera/oauth/jwt'
 require 'aspera/oauth/web'

data/lib/aspera/persistency_action_once.rb

@@ -23,9 +23,9 @@ module Aspera
     # @param :merge    Optional  merge data from file to current data
     def initialize(manager:, data:, id:, delete: DELETE_DEFAULT, parse: PARSE_DEFAULT, format: FORMAT_DEFAULT, merge: MERGE_DEFAULT)
       Aspera.assert(MANAGER_METHODS.all?{ |i| manager.respond_to?(i)}){"Manager must answer to #{MANAGER_METHODS}"}
-      Aspera.assert(!data.nil?)
+      Aspera.assert(!data.nil?, 'data must not be nil')
       Aspera.assert_type(id, String)
-      Aspera.assert(!id.empty?)
+      Aspera.assert(!id.empty?, 'id must not be empty')
       Aspera.assert_type(delete, Proc)
       Aspera.assert_type(parse, Proc)
       Aspera.assert_type(format, Proc)

data/lib/aspera/preview/file_types.rb

@@ -8,6 +8,10 @@ require 'marcel'
 module Aspera
   module Preview
     # function conversion_type returns one of the types: CONVERSION_TYPES
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of FileTypes
+    #   @return [FileTypes] the singleton instance
     class FileTypes
       include Singleton