aspera-cli 4.25.4 → 4.25.6

data/lib/aspera/environment.rb

@@ -84,22 +84,31 @@ module Aspera
         "'#{str.gsub("'", %q('\'\''))}'"
       end
 
-      # Execute a process securely without shell.
+      # Executes a command without invoking a shell.
       #
-      # Execution `mode` can be:
-      # - :execute    -> Kernel.system, return nil
-      # - :background -> Process.spawn, return pid
-      # - :capture    -> Open3.capture3, return stdout
+      # The command is provided as an array to avoid shell interpolation and
+      # ensure safer execution.
       #
-      # @param cmd [Array<String>] Executable and arguments (mapped "to_s")
-      # @param mode [:execute,:background,:capture] Execution mode
-      # @param kwargs [Hash] Additional arguments to underlying method
-      # @option kwargs [Hash] :env Environment variables
-      # @option kwargs [Boolean] :exception for :capture mode, raise error if process fails
-      # @option kwargs [Boolean] :close_others for :background mode
-      # @return [nil] for :execute mode
-      # @return [Integer] pid for :background mode
-      # @return [String] stdout for :capture mode
+      # @param cmd [Array<#to_s>] The executable and its arguments.
+      # @param mode [:execute, :background, :capture] The execution strategy:
+      #   - `:execute`    Uses {Kernel.system}. Returns `true`, `false`, or `nil`.
+      #   - `:background` Uses {Process.spawn}. Returns the spawned process PID.
+      #   - `:capture`    Uses {Open3.capture3}. Returns captured output and status.
+      #
+      # @param kwargs [Hash] Additional options forwarded to the underlying call.
+      #
+      # @option kwargs [Hash{String => String}] :env Environment variables to set for the process.
+      # @option kwargs [Boolean] :exception (false) When `true` in `:capture` mode,
+      #   raises an error if the command exits with a non-zero status.
+      # @option kwargs [Boolean] :close_others (true) When `true` in `:background` mode,
+      #   closes all other file descriptors in the child process.
+      #
+      # @return [Boolean, nil] For `:execute` mode (`true`, `false`, or `nil`).
+      # @return [Integer] For `:background` mode (process ID).
+      # @return [Array(String, String, Process::Status)] For `:capture` mode
+      #   (`stdout`, `stderr`, `status`).
+      #
+      # @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'}
@@ -128,11 +137,12 @@ module Aspera
           # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
           argv = [kwargs.delete(:env)].compact + cmd
           exception = kwargs.delete(:exception){true}
-          stdout, stderr, status = Open3.capture3(*argv, **kwargs)
-          Log.log.debug{"status=#{status}, stderr=#{stderr}"}
-          Log.log.trace1{"stdout=#{stdout}"}
-          raise "Process failed: #{status.exitstatus} (#{stderr})" if exception && !status.success?
-          stdout
+          result = Open3.capture3(*argv, **kwargs)
+          Log.dump(:stdout, result[0], level: :trace1)
+          Log.dump(:stderr, result[1], level: :trace1)
+          Log.dump(:status, result[2])
+          raise "Process failed: #{result[2].exitstatus} (#{result[1]})" if exception && !result[2].success?
+          result
         else Aspera.error_unreachable_line
         end
       end

data/lib/aspera/keychain/macos_security.rb

@@ -57,7 +57,7 @@ module Aspera
               command_args.push(v.shellescape) unless v.empty?
             end
             command_args.push(last_opt) unless last_opt.nil?
-            return Environment.secure_execute(*command_args, mode: :capture)
+            Environment.secure_execute(*command_args, mode: :capture).first
           end
 
           def key_chains(output)

data/lib/aspera/log.rb

@@ -26,7 +26,7 @@ class Logger
   # Hash
   # key   [Integer] Log level (e.g. 0 for DEBUG)
   # value [Symbol]  Uppercase log level label (e.g. :DEBUG)
-  SEVERITY_LABEL = Severity.constants.each_with_object({}){ |name, hash| hash[Severity.const_get(name)] = name}
+  SEVERITY_LABEL = Severity.constants.to_h{ |name| [Severity.const_get(name), name]}
 
   # Override
   # @param severity [Integer] Log severity as int

data/lib/aspera/markdown.rb

@@ -33,7 +33,7 @@ module Aspera
 
       # type: NOTE CAUTION WARNING IMPORTANT TIP INFO
       def admonition(lines, type: 'INFO')
-        "> [!{type}]\n#{lines.map{ |l| "> #{l}"}.join("\n")}\n\n"
+        "> [!#{type}]\n#{lines.map{ |l| "> #{l}"}.join("\n")}\n\n"
       end
 
       def code(lines, type: 'shell')

data/lib/aspera/persistency_folder.rb

@@ -79,7 +79,7 @@ module Aspera
     end
 
     def current_items(persist_category)
-      current_files(persist_category).each_with_object({}){ |i, h| h[File.basename(i, FILE_SUFFIX)] = File.read(i)}
+      current_files(persist_category).to_h{ |i| [File.basename(i, FILE_SUFFIX), File.read(i)]}
     end
 
     private

data/lib/aspera/preview/utils.rb

@@ -51,11 +51,11 @@ module Aspera
           Environment.secure_execute(command_sym.to_s, *command_args.map(&:to_s), out: File::NULL, err: File::NULL)
         end
 
-        # Execute external command and capture output
+        # Execute external command and get stdout
         # @return [String]
         def external_capture(command_sym, command_args)
           Aspera.assert_values(command_sym, EXTERNAL_TOOLS){'command'}
-          return Environment.secure_execute(command_sym.to_s, *command_args.map(&:to_s), mode: :capture)
+          Environment.secure_execute(command_sym.to_s, *command_args.map(&:to_s), mode: :capture).first
         end
 
         def ffmpeg(gl_p: FFMPEG_DEFAULT_PARAMS, in_p: [], in_f:, out_p: [], out_f:)

data/lib/aspera/rest.rb

@@ -72,11 +72,6 @@ module Aspera
   # rest call errors are raised as exception RestCallError
   # and error are analyzed in RestErrorAnalyzer
   class Rest
-    # Special query parameter: max number of items for list command
-    MAX_ITEMS = 'max'
-    # Special query parameter: max number of pages for list command
-    MAX_PAGES = 'pmax'
-
     class << self
       # @return [String] Basic auth token
       def basic_authorization(user, pass); return "Basic #{Base64.strict_encode64("#{user}:#{pass}")}"; end
@@ -155,6 +150,37 @@ module Aspera
         end
       end
 
+      # Parse Link header according to RFC 8288 to extract a specific relation
+      # @param link_header [String, nil] The Link header value
+      # @param rel [String] The relation to look for (default: 'next')
+      # @return [String, nil] The URL of the link with the specified relation, or nil
+      def parse_link_header(link_header, rel: 'next')
+        return if link_header.nil? || link_header.empty?
+        # RFC 8288: Link header format is: <URI>; param1=value1; param2=value2, <URI2>; ...
+        # We look for the link with the specified rel
+        link_header.split(',').each do |link_part|
+          link_part = link_part.strip
+          # Extract URL between < and >
+          url_match = link_part.match(/<([^>]+)>/)
+          next unless url_match
+          url = url_match[1]
+          # Extract parameters after the URL
+          params_str = link_part[url_match.end(0)..-1]
+          # Check if this link has the specified rel (with or without quotes, case insensitive)
+          next unless /;\s*rel\s*=\s*"?#{Regexp.escape(rel)}"?/i.match?(params_str)
+          return url
+        end
+        # Fallback: if no rel found and looking for 'next', try the first link (backward compatibility)
+        if rel.eql?('next')
+          first_link = link_header.split(',').first&.strip
+          if first_link
+            url_match = first_link.match(/<([^>]+)>/)
+            return url_match[1] if url_match
+          end
+        end
+        nil
+      end
+
       # Start a HTTP/S session, also used for web sockets
       # @param base_url [String] Base url of HTTP/S session
       # @return [Net::HTTP] A started HTTP session
@@ -174,6 +200,8 @@ module Aspera
       # get Net::HTTP underlying socket i/o
       # little hack, handy because HTTP debug, proxy, etc... will be available
       # used implement web sockets after `start_http_session`
+      # @param http_session [Net::HTTP] the session object
+      # @return [Net::BufferedIO] The underlying socket i/o
       def io_http_session(http_session)
         Aspera.assert_type(http_session, Net::HTTP)
         # Net::BufferedIO in net/protocol.rb
@@ -371,8 +399,11 @@ module Aspera
       end
       result_http = nil
       result_data = nil
+      # initialize with number of initial retries allowed, nil gives zero
+      tries_remain_redirect = @redirect_max
       # start a block to be able to retry the actual HTTP request in case of OAuth token expiration
       begin
+        Log.log.debug("send request (retries=#{tries_remain_redirect})")
         # TODO: shall we percent encode subpath (spaces) test with access key delete with space in id
         # URI.escape()
         separator = ['', '/'].include?(subpath) ? '' : '/'
@@ -406,9 +437,6 @@ module Aspera
         Log.dump(:req_body, req.body, level: :trace1)
         # we try the call, and will retry on some error types
         error_tries ||= 1 + RestParameters.instance.retry_max
-        # initialize with number of initial retries allowed, nil gives zero
-        tries_remain_redirect = @redirect_max if tries_remain_redirect.nil?
-        Log.log.debug("send request (retries=#{tries_remain_redirect})")
         result_mime = nil
         file_saved = false
         # make http request (pipelined)
@@ -458,6 +486,9 @@ module Aspera
         # Log.log.debug{"result: body=#{result_http.body}"}
         result_data = result_http.body
         Log.dump(:result_data_raw, result_data, level: :trace1)
+        # TODO: Remove next 2 lines when bug in async node api is fixed. (Aspera/core/issues/4490)
+        node_api_bug = result_data&.index('}HTTP/1.1 400 Bad Request') if result_data.is_a?(String)
+        result_data = result_data[0..node_api_bug] if node_api_bug
         result_data = JSON.parse(result_data) if Mime.json?(result_mime) && !result_data.nil? && !result_data.empty?
         Log.dump(:result_data, result_data)
         RestErrorAnalyzer.instance.raise_on_error(req, result_data, result_http)
@@ -572,34 +603,6 @@ module Aspera
       return call(operation: 'CANCEL', subpath: subpath, **kwargs)
     end
 
-    # Query entity by general search (read with parameter `q`)
-    # TODO: not generic enough ? move somewhere ? inheritance ?
-    # @param subpath     [String] Path of entity in API
-    # @param search_name [String] Name of searched entity
-    # @param query       [Hash]   Additional search query parameters
-    # @returns [Hash] A single entity matching the search, or an exception if not found or multiple found
-    def lookup_by_name(subpath, search_name, query: nil)
-      query = {} if query.nil?
-      # returns entities matching the query (it matches against several fields in case insensitive way)
-      matching_items = read(subpath, query.merge({'q' => search_name}))
-      # API style: {totalcount:, ...} cspell: disable-line
-      matching_items = matching_items[subpath] if matching_items.is_a?(Hash)
-      Aspera.assert_type(matching_items, Array)
-      case matching_items.length
-      when 1 then return matching_items.first
-      when 0 then raise EntityNotFound, %Q{No such #{subpath}: "#{search_name}"}
-      else
-        # multiple case insensitive partial matches, try case insensitive full match
-        # (anyway AoC does not allow creation of 2 entities with same case insensitive name)
-        name_matches = matching_items.select{ |i| i['name'].casecmp?(search_name)}
-        case name_matches.length
-        when 1 then return name_matches.first
-        when 0 then raise %Q(#{subpath}: Multiple case insensitive partial match for: "#{search_name}": #{matching_items.map{ |i| i['name']}} but no case insensitive full match. Please be more specific or give exact name.)
-        else raise "Two entities cannot have the same case insensitive name: #{name_matches.map{ |i| i['name']}}"
-        end
-      end
-    end
-
     UNAVAILABLE_CODES = ['503']
 
     private_constant :UNAVAILABLE_CODES

data/lib/aspera/rest_list.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Aspera
+  # List and lookup methods for Rest
+  # To be included in classes inheriting Rest that require those methods.
+  module RestList
+    # `max`: special query parameter: max number of items for list command
+    MAX_ITEMS = 'max'
+    # `pmax`: special query parameter: max number of pages for list command
+    MAX_PAGES = 'pmax'
+
+    # Query entity by general search (read with parameter `q`)
+    #
+    # @param subpath     [String] Path of entity in API
+    # @param search_name [String] Name of searched entity
+    # @param query       [Hash]   Optional additional search query parameters
+    # @returns [Hash] A single entity matching the search, or an exception if not found or multiple found
+    def lookup_by_name(subpath, search_name, query: nil)
+      query = {} if query.nil?
+      # returns entities matching the query (it matches against several fields in case insensitive way)
+      matching_items = read(subpath, query.merge({'q' => search_name}))
+      # API style: {totalcount:, ...} cspell: disable-line
+      matching_items = matching_items[subpath] if matching_items.is_a?(Hash)
+      Aspera.assert_type(matching_items, Array)
+      case matching_items.length
+      when 1 then return matching_items.first
+      when 0 then raise EntityNotFound, %Q{No such #{subpath}: "#{search_name}"}
+      else
+        # multiple case insensitive partial matches, try case insensitive full match
+        # (anyway AoC does not allow creation of 2 entities with same case insensitive name)
+        name_matches = matching_items.select{ |i| i['name'].casecmp?(search_name)}
+        case name_matches.length
+        when 1 then return name_matches.first
+        when 0 then raise %Q(#{subpath}: Multiple case insensitive partial match for: "#{search_name}": #{matching_items.map{ |i| i['name']}} but no case insensitive full match. Please be more specific or give exact name.)
+        else raise "Two entities cannot have the same case insensitive name: #{name_matches.map{ |i| i['name']}}"
+        end
+      end
+    end
+
+    # Get a (full or partial) list of all entities of a given type with query: offset/limit
+    # @param entity    [String,Symbol] API endpoint of entity to list
+    # @param items_key [String]        Key in the result to get the list of items (Default: same as `entity`)
+    # @param query     [Hash,nil]      Additional query parameters
+    # @return [Array<(Array<Hash>, Integer)>] items, total_count
+    def list_entities_limit_offset_total_count(
+      entity:,
+      items_key: nil,
+      query: nil
+    )
+      entity = entity.to_s if entity.is_a?(Symbol)
+      items_key = entity.split('/').last if items_key.nil?
+      query = {} if query.nil?
+      Aspera.assert_type(entity, String)
+      Aspera.assert_type(items_key, String)
+      Aspera.assert_type(query, Hash)
+      Log.log.debug{"list_entities t=#{entity} k=#{items_key} q=#{query}"}
+      result = []
+      offset = 0
+      max_items = query.delete(MAX_ITEMS)
+      remain_pages = query.delete(MAX_PAGES)
+      # Merge default parameters, by default 100 per page
+      query = {'limit'=> PER_PAGE_DEFAULT}.merge(query)
+      total_count = nil
+      loop do
+        query['offset'] = offset
+        page_result = read(entity, query)
+        Aspera.assert_type(page_result[items_key], Array)
+        result.concat(page_result[items_key])
+        # Reach the limit set by user ?
+        if !max_items.nil? && (result.length >= max_items)
+          result = result.slice(0, max_items)
+          break
+        end
+        total_count ||= page_result['total_count']
+        break if result.length >= total_count
+        remain_pages -= 1 unless remain_pages.nil?
+        break if remain_pages == 0
+        offset += page_result[items_key].length
+        RestParameters.instance.spinner_cb.call("#{result.length} / #{total_count || '?'}")
+      end
+      RestParameters.instance.spinner_cb.call(action: :success)
+      return result, total_count
+    end
+
+    # Lookup an entity id from its name.
+    # Uses query `q` if `query` is `:default` and `field` is `name`.
+    # @param entity    [String] Type of entity to lookup, by default it is the path, and it is also the field name in result
+    # @param value     [String] Value to lookup
+    # @param field     [String] Field to match, by default it is `'name'`
+    # @param items_key [String] Key in the result to get the list of items (override entity)
+    # @param query     [Hash]   Additional query parameters (Default: `:default`)
+    def lookup_entity_by_field(entity:, value:, field: 'name', items_key: nil, query: :default)
+      if query.eql?(:default)
+        Aspera.assert(field.eql?('name')){'Default query is on name only'}
+        query = {'q'=> value}
+      end
+      lookup_entity_generic(entity: entity, field: field, value: value){list_entities_limit_offset_total_count(entity: entity, items_key: items_key, query: query).first}
+    end
+
+    # Lookup entity by field and value.
+    # Extracts a single result from the list returned by the block.
+    #
+    # @param entity [String] Type of entity to lookup (path, and by default it is also the field name in result)
+    # @param value  [String] Value to match against the field.
+    # @param field  [String] Field to match in the hashes (defaults to 'name').
+    # @yield []              A mandatory block that returns an Array of Hashes.
+    # @return [Hash] The unique matching object.
+    # @raise  [Cli::BadIdentifier] If 0 or >1 matches are found.
+    def lookup_entity_generic(entity:, value:, field: 'name')
+      Aspera.assert(block_given?)
+      found = yield
+      Aspera.assert_array_all(found, Hash)
+      found = found.select{ |i| i[field].eql?(value)}
+      return found.first if found.length.eql?(1)
+      raise Cli::BadIdentifier.new(entity, value, field: field, count: found.length)
+    end
+    PER_PAGE_DEFAULT = 1000
+    private_constant :PER_PAGE_DEFAULT
+    module_function :lookup_entity_generic
+  end
+end

data/lib/aspera/sync/operations.rb

@@ -197,7 +197,7 @@ module Aspera
               raise Error, 'Missing either local_db_dir or local_dir'
             end
           end
-          stdout = Environment.secure_execute(*arguments, mode: :capture)
+          stdout = Environment.secure_execute(*arguments, mode: :capture).first
           return parse_status(stdout)
         end
 
@@ -342,7 +342,7 @@ module Aspera
       CONF_SCHEMA = CommandLineBuilder.read_schema(__dir__, 'conf')
       CMDLINE_PARAMS_KEYS = %w[instance sessions].freeze
       ASYNC_ADMIN_EXECUTABLE = 'asyncadmin'
-      PRIVATE_FOLDER = '.private-asp'
+      PRIVATE_FOLDER = "#{Environment.instance.os.eql?(Environment::OS_WINDOWS) ? '~' : '.'}private-asp"
       ASYNC_DB = 'snap.db'
       PARAM_KEYS = %w[local sessions].freeze
 

data/lib/aspera/transfer/parameters.rb

@@ -38,19 +38,19 @@ module Aspera
           @file_list_folder ||= TempFileManager.instance.new_file_path_global('asession_filelists')
         end
 
-        # File list is provided directly with ascp arguments
-        # @columns ascp_args [Array,NilClass] ascp arguments
+        # File list is provided directly with `ascp` arguments
+        # @columns ascp_args [Array,NilClass] `ascp` arguments
         def ascp_args_file_list?(ascp_args)
           ascp_args&.any?{ |i| FILE_LIST_OPTIONS.include?(i)}
         end
       end
 
-      # @param job_spec        [Hash]    Transfer spec
-      # @param ascp_args       [Array]   Other ascp args
-      # @param quiet           [Boolean] Remove ascp output
-      # @param trusted_certs   [Array]   Trusted certificates
-      # @param client_ssh_key  [:rsa,:dsa] :rsa or :dsa
-      # @param check_ignore_cb [Proc]    Callback
+      # @param job_spec        [Hash]          Transfer specification
+      # @param ascp_args       [Array]         Other `ascp` args
+      # @param quiet           [Boolean]       Remove `ascp` progress bar if `true`
+      # @param client_ssh_key  [:rsa,:dsa]     Type of Aspera Client SSH key to use.
+      # @param trusted_certs   [Array<String>] List of path to trusted certificates stores when using WSS
+      # @param check_ignore_cb [Proc]          Callback to check if WSS connection shall ignore certificate validity
       def initialize(
         job_spec,
         ascp_args:       nil,

data/lib/aspera/yaml.rb

@@ -25,7 +25,7 @@ module Aspera
         counts.each do |key_str, count|
           next if count <= 1
           path = (parent_path + [key_str]).join('.')
-          occurrences = key_nodes[key_str].map{ |kn| kn.start_line ? kn.start_line + 1 : 'unknown'}.map(&:to_s).join(', ')
+          occurrences = key_nodes[key_str].map{ |kn| kn.start_line ? kn.start_line + 1 : 'unknown'}.join(', ')
           duplicate_keys << "#{path}: #{occurrences}"
         end
       else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: aspera-cli
 version: !ruby/object:Gem::Version
-  version: 4.25.4
+  version: 4.25.6
 platform: ruby
 authors:
 - Laurent Martin
@@ -424,6 +424,7 @@ files:
 - lib/aspera/rest_call_error.rb
 - lib/aspera/rest_error_analyzer.rb
 - lib/aspera/rest_errors_aspera.rb
+- lib/aspera/rest_list.rb
 - lib/aspera/secret_hider.rb
 - lib/aspera/ssh.rb
 - lib/aspera/ssl.rb
@@ -456,7 +457,7 @@ metadata:
   source_code_uri: https://github.com/IBM/aspera-cli/tree/main/lib/aspera
   changelog_uri: https://github.com/IBM/aspera-cli/blob/main/CHANGELOG.md
   rubygems_uri: https://rubygems.org/gems/aspera-cli
-  documentation_uri: https://www.rubydoc.info/gems/aspera-cli
+  documentation_uri: https://ibm.biz/ascli-doc
 rdoc_options: []
 require_paths:
 - lib
@@ -472,7 +473,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - Read the manual for any requirement
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: 'Execute actions using command line on IBM Aspera Server products: Aspera
   on Cloud, Faspex, Shares, Node, Console, Orchestrator, High Speed Transfer Server'