aspera-cli 4.27.5 → 4.28.0

data/lib/aspera/cli/plugins/base.rb

@@ -7,6 +7,7 @@ require 'aspera/cli/result'
 require 'aspera/cli/command_registry'
 require 'aspera/cli/option_declarator'
 require 'aspera/cli/special_values'
+require 'aspera/rest/list'
 require 'aspera/schema/registry'
 
 module Aspera
@@ -104,12 +105,26 @@ module Aspera
           # @param entity     [String, Symbol] REST sub-path, or ctx key Symbol resolved at runtime
           # @param operations [Array<Symbol>]  Verbs to expose; defaults to Operations::ALL
           # @param name       [String, nil]    Singular display name; defaults to last segment of entity (static only)
-          # @param lookup     [Symbol, nil]    Instance method for percent-selector resolution
+          # @param lookup     [Symbol, Proc, Array<String>, nil] Percent-selector resolution: instance method, lambda,
+          #                   or fields with unique values, looked up in the list of entities (plain Array of Hash)
           # @param id_name    [Symbol, nil]    Name of identifier argument; defaults to <name>_id, or id_as_arg field, or :id
+          # @param schema_entity [String, nil] REST sub-path in the API schema (body_component), when entity is a ctx key Symbol
           # @param kwargs     [Hash]           Shared params forwarded to every per-verb method
-          def crud_commands(api:, entity:, operations: nil, name: nil, lookup: nil, id_name: nil, **kwargs)
+          def crud_commands(api:, entity:, operations: nil, name: nil, lookup: nil, id_name: nil, schema_entity: nil, **kwargs)
             name       ||= entity_noun(entity, singular: !kwargs[:is_singleton]) unless entity.is_a?(Symbol)
             operations ||= Operations::ALL
+            schema_entity ||= entity if entity.is_a?(String)
+            if lookup.is_a?(Array)
+              unique_fields = lookup
+              # `%id:<id>` is the id itself (no lookup), other fields are looked up in the list of entities
+              lookup = lambda do |field, value, **ctx|
+                return value if field.eql?('id')
+                resolved_entity = entity.is_a?(Symbol) ? ctx.fetch(entity) : entity
+                label = name || resolved_entity
+                Aspera.assert_values(field, unique_fields, type: Cli::BadArgument) { "#{label} search field" }
+                Rest::List.lookup_entity_generic(field: field, value: value, entity: label) { crud_api(api).read(resolved_entity) }['id']
+              end
+            end
             # Body argument is named after the entity, e.g. <access_key>, and passed as data: to entity_<verb>
             data_name = name ? name.downcase.tr(' ', '_').to_sym : :data
             # Identifier argument is named after the entity, e.g. <access_key_id>, and passed as id: to entity_<verb>
@@ -121,10 +136,10 @@ module Aspera
             operations.each do |verb|
               id_arg = ({name: id_name, type: :identifier, lookup: lookup} if Operations::INSTANCE.include?(verb) && !kwargs[:is_singleton])
               schema_val =
-                if kwargs[:body_component] && entity.is_a?(String)
+                if kwargs[:body_component] && schema_entity
                   case verb
-                  when :create then Schema::Registry.req_body(kwargs[:body_component], "#{entity}.post")
-                  when :modify then Schema::Registry.req_body(kwargs[:body_component], "#{entity}/{id}.put")
+                  when :create then Schema::Registry.req_body(kwargs[:body_component], "#{schema_entity}.post")
+                  when :modify then Schema::Registry.req_body(kwargs[:body_component], "#{schema_entity}/{id}.put")
                   end
                 end
               args =
@@ -139,18 +154,10 @@ module Aspera
                   id_arg ? [id_arg] : nil
                 end
               action_proc = lambda do |**ctx|
-                resolved_api =
-                  if api.is_a?(Symbol)
-                    api.to_s.start_with?('@') ? instance_variable_get(api) : send(api)
-                  elsif api.is_a?(Proc)
-                    instance_exec(&api)
-                  else
-                    api
-                  end
                 resolved_entity = entity.is_a?(Symbol) ? ctx.fetch(entity) : entity
                 ctx = ctx.merge(data: ctx[data_name]) if ctx.key?(data_name)
                 ctx = ctx.merge(id: ctx[id_name]) if ctx.key?(id_name)
-                send(:"entity_#{verb}", api: resolved_api, entity: resolved_entity, **kwargs, **ctx)
+                send(:"entity_#{verb}", api: crud_api(api), entity: resolved_entity, **kwargs, **ctx)
               end
               cmd_attrs = {description: operation_description(verb, name || entity.inspect), action: action_proc}
               cmd_attrs[:arguments] = args if args
@@ -555,7 +562,8 @@ module Aspera
                   validation:  arg_spec.type,
                   accept_list: arg_spec.allowed,
                   default:     arg_spec.interactive ? nil : arg_spec.default,
-                  schema:      arg_spec.schema
+                  schema:      arg_spec.schema,
+                  raw:         arg_spec.raw
                 )
               end
             end
@@ -603,6 +611,19 @@ module Aspera
           )
         end
 
+        # Resolve the `api:` reference given to `crud_commands`.
+        # @param api [Symbol, Proc, Object] `:@ivar`, method name, Proc (instance_exec), or the API object itself
+        # @return [Rest::Client]
+        def crud_api(api)
+          if api.is_a?(Symbol)
+            api.to_s.start_with?('@') ? instance_variable_get(api) : send(api)
+          elsif api.is_a?(Proc)
+            instance_exec(&api)
+          else
+            api
+          end
+        end
+
         # --- Per-verb entity action methods ---
         # Each method handles exactly one CRUD verb.
         # The resource id (when needed) is received as `id:` from ctx — it must be

data/lib/aspera/cli/plugins/config.rb

@@ -14,6 +14,7 @@ require 'aspera/cli/wizard'
 require 'aspera/cli/sync_actions'
 require 'aspera/cli/ascp_actions'
 require 'aspera/cli/preset_actions'
+require 'aspera/cli/completion_actions'
 require 'aspera/cli/vault_manager'
 require 'aspera/cli/transfer_actions'
 require 'aspera/cli/gem_checker'
@@ -28,7 +29,7 @@ require 'aspera/persistency_action_once'
 require 'aspera/id_generator'
 require 'aspera/data_repository'
 require 'aspera/rest'
-require 'aspera/oauth/jwt'
+require 'aspera/oauth/client/jwt'
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/string_ext'
@@ -48,6 +49,7 @@ module Aspera
         include AscpActions
         include PresetActions
         include TransferActions
+        include CompletionActions
 
         class << self
           # Folder containing plugins in the gem's main folder
@@ -62,11 +64,6 @@ module Aspera
             File.expand_path(Module.nesting[2].to_s.gsub('::', '/').gsub(%r{[^/]+}, '..'), gem_plugins_folder)
           end
 
-          # Deep clone hash so that it does not get modified in case of display and secret hide
-          def deep_clone(val)
-            return Marshal.load(Marshal.dump(val))
-          end
-
           # @return [String] product family folder (~/.aspera)
           def module_family_folder
             user_home_folder = Dir.home
@@ -83,16 +80,13 @@ module Aspera
         end
 
         DEFAULT_CHECK_NEW_VERSION_DAYS = 7
-        # Shells with a completion script in COMPLETION_FOLDER
-        COMPLETION_SHELLS = %i[bash zsh fish].freeze
-        COMPLETION_FOLDER = File.expand_path('../completion', __dir__)
-        private_constant :DEFAULT_CHECK_NEW_VERSION_DAYS, :COMPLETION_SHELLS, :COMPLETION_FOLDER
+        private_constant :DEFAULT_CHECK_NEW_VERSION_DAYS
 
         option :preset,             description: 'Load the named option preset from current config file',             short: 'P', on_set: :load_preset
         option :version_check_days, description: 'Period in days to check new version (zero to disable)',             allowed: Type::INTEGER, default: DEFAULT_CHECK_NEW_VERSION_DAYS
         option :plugin_folder,      description: 'Folder where to find additional plugins',                           on_set: :add_plugin_folders
         option :sdk_url,            description: 'Ascp: URL to get Aspera Transfer Executables',                      default: SpecialValues::DEF
-        option :locations_url,      description: 'Ascp: URL to get download locations of Aspera Transfer Daemon',    default: Ascp::Installation.instance.transferd_urls, on_set: Ascp::Installation.instance.method(:transferd_urls=)
+        option :locations_url,      description: 'Ascp: URLs to get download locations of Aspera Transfer Daemon',   allowed: Type::STRING_ARRAY, default: Ascp::Installation.instance.transferd_urls, on_set: Ascp::Installation.instance.method(:transferd_urls=)
         option :sdk_folder,         description: 'Ascp: Path to folder with ascp (or product with "product:")',      on_set: Ascp::Installation.instance.method(:sdk_folder=)
         option :smtp,               schema: Schema::Registry::SMTP_OPTIONS
         option :notify_to,          description: 'Email: Recipient for notification of transfers'
@@ -244,7 +238,7 @@ module Aspera
           command :delete, description: 'Delete a secret by label (or id)',
             arguments: [{name: :label}, {name: :id, mandatory: false, default: nil}]
           command(
-            :password, description: 'Change the vault password',
+            :password, description: 'Set a new password for the vault',
             arguments: [{name: :new_password}],
             action: lambda do |new_password:, **|
               Aspera.assert(vault_required.respond_to?(:change_password), 'Vault does not support password change')
@@ -335,8 +329,9 @@ module Aspera
             action: ->(version: nil, **) { install_transfer_sdk(version: version) }
           command(
             :spec, description: 'Show the transfer spec schema',
-            action: lambda do |**|
-              builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, include_option: true, agent_columns: true).build
+            arguments: [{name: :agent_name, allowed: Agent::Factory::ALL.keys + [Transfer::Spec::DOC_OVERVIEW], mandatory: false, default: nil}],
+            action: lambda do |agent_name: nil, **|
+              builder = Schema::Documentation.new(TerminalFormatter, Transfer::Spec::SCHEMA, **Transfer::Spec.doc_options(agent_name)).build
               Result::ObjectList.new(builder.rows, fields: builder.columns)
             end
           )
@@ -393,7 +388,7 @@ module Aspera
           command(
             :spec, description: 'Show the sync configuration schema',
             action: lambda do |**|
-              builder = Schema::Documentation.new(TerminalFormatter, Sync::Operations::CONF_SCHEMA, include_option: true).build
+              builder = Schema::Documentation.new(TerminalFormatter, Sync::Operations::CONF_SCHEMA, annotate: CommandLineBuilder.method(:doc_lines)).build
               Result::ObjectList.new(builder.rows, fields: builder.columns)
             end
           )
@@ -429,9 +424,11 @@ module Aspera
 
         # completion sub-commands
         commands_under :completion do
-          command :words, description: 'List words that can follow the given words (used by completion scripts)',
-            arguments: [{name: :words, multiple: true, mandatory: false}]
-          COMPLETION_SHELLS.each do |shell|
+          command :words, description: 'List words that can follow the given words',
+            arguments: [{name: :words, multiple: true, mandatory: false, raw: true}]
+          command :candidates, description: 'Complete the last word, with descriptions and a directive for the shell (used by completion scripts)',
+            arguments: [{name: :words, multiple: true, mandatory: false, raw: true}]
+          COMPLETION_SHELLS.each_key do |shell|
             command shell, description: "Generate #{shell} completion script, to evaluate in shell",
               action: ->(**) { completion_script(shell) }
           end
@@ -635,32 +632,6 @@ module Aspera
           Result::ObjectList.new(rows, fields: %w[option description allowed deprecated replacement])
         end
 
-        def action_completion_words(words: nil, **)
-          if words.nil? || words.empty?
-            # Level 0: propose plugin names
-            Plugins::Factory.instance.plugin_list.each { |p| puts p }
-          else
-            plugin_sym = words.first.to_sym
-            plugin_class = begin
-              Plugins::Factory.instance.plugin_class(plugin_sym)
-            rescue StandardError
-              Process.exit(0)
-            end
-            # Navigate into the registry using remaining words as path
-            path = words[1..].map(&:to_sym)
-            plugin_class.command_registry.children_of(path).each_key { |k| puts k }
-          end
-          Process.exit(0)
-        end
-
-        # Display the completion script for the given shell.
-        # Raw output, not formatted, so that it can be evaluated by the shell.
-        # @param shell [Symbol] One of `COMPLETION_SHELLS`
-        def completion_script(shell)
-          $stdout.write(File.read(File.join(COMPLETION_FOLDER, "#{Info::CMD_NAME}.#{shell}")))
-          Process.exit(0)
-        end
-
         # Folder in $HOME for application files (~/.aspera)
         ASPERA_HOME_FOLDER_NAME = '.aspera'
         # Default config file name

data/lib/aspera/cli/plugins/console.rb

@@ -57,10 +57,12 @@ module Aspera
         # @param app_url [String] Tested URL
         # @return [Hash] :preset_value, :test_args
         def wizard(wizard, app_url)
+          username = options.get_option(:username, mandatory: true)
           return {
+            preset_ids:   [username],
             preset_value: {
               url:      app_url,
-              username: options.get_option(:username, mandatory: true),
+              username: username,
               password: options.get_option(:password, mandatory: true)
             },
             test_args:    'transfer current list'

data/lib/aspera/cli/plugins/factory.rb

@@ -42,7 +42,7 @@ module Aspera
             next unless File.directory?(folder)
             # TODO: add gem root to load path ? and require short folder ?
             # $LOAD_PATH.push(folder) if i[:add_path]
-            Dir.entries(folder).each do |source|
+            Dir.children(folder).each do |source|
               next unless source.end_with?(Environment::RB_EXT)
               path = File.join(folder, source)
               plugin_symbol = File.basename(path, Environment::RB_EXT).to_sym

data/lib/aspera/cli/plugins/faspex5.rb

@@ -69,7 +69,7 @@ module Aspera
             formatter.display_status('Ask the ascli client id and secret to your Administrator.'.red)
             formatter.display_status("Log in as an admin user at: #{app_url}")
             Environment.instance.open_uri(app_url)
-            formatter.display_status('Navigate to: 𓃑  → Admin → Configurations → API clients')
+            wizard.display_navigation(Environment.char('𓃑'), 'Admin', 'Configurations', 'API clients')
             formatter.display_status('Create an API client with:')
             formatter.display_status('- name: ascli')
             formatter.display_status('- JWT: enabled')
@@ -82,9 +82,10 @@ module Aspera
           private_key_path = wizard.ask_private_key(
             user: wiz_username,
             url: app_url,
-            page: '👤 → Account Settings → Preferences → Public Key in PEM'
+            page: [Environment.char('👤'), 'Account Settings', 'Preferences', 'Public Key in PEM']
           )
           return {
+            preset_ids:   [wiz_username, client_id].compact,
             preset_value: {
               url:           app_url,
               username:      wiz_username,
@@ -321,8 +322,7 @@ module Aspera
             )
             # well, we asked a TS for connect, but we actually want a generic one
             transfer_spec.delete('authentication')
-            Runner.result_transfer(transfer.start(transfer_spec))
-            return Result::SingleObject.new(package)
+            return Runner.result_object_transfer(package, transfer.start(transfer_spec))
           else
             # send from remote shared folder
             if (m = Parser.percent_selector(shared_folder))
@@ -529,9 +529,9 @@ module Aspera
         command :user,           description: 'Manage current user'
         command :shared_folders, description: 'Browse shared folders'
         command :gateway,        description: 'Start Faspex 4 gateway emulation',
-          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}, schema: Schema::Registry::GATEWAY_OPTIONS}]
         command :postprocessing, description: 'Start Faspex 4 post-processing server',
-          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}}]
+          arguments: [{name: :parameters, type: Hash, mandatory: false, default: {}, schema: Schema::Registry::POSTPROC_OPTIONS}]
         command :invitations,    description: 'Manage invitations'
 
         commands_under :invitations do
@@ -978,24 +978,14 @@ module Aspera
 
         def action_gateway(parameters: {}, **)
           require 'aspera/faspex_gw'
-          parameters = parameters.symbolize_keys
-          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
-          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-          Aspera.assert(parameters.except(*WebServerSimple::PARAMS).empty?) { "unexpected parameters: #{parameters.except(*WebServerSimple::PARAMS).keys}" }
-          server.mount(uri.path, Faspex4GWServlet, api_v5, nil)
-          server.start
+          Faspex4GWServlet.serve(parameters.symbolize_keys, type: Cli::BadArgument) { [api_v5, nil] }
           Result::Status.new('Gateway terminated')
         end
 
         def action_postprocessing(parameters: {}, **)
           require 'aspera/faspex_postproc' # cspell:disable-line
-          parameters = parameters.symbolize_keys
-          uri = URI.parse(parameters.delete(:url) { WebServerSimple::DEFAULT_URL })
-          parameters[:root] = uri.path
-          server = WebServerSimple.new(uri, **parameters.slice(*WebServerSimple::PARAMS))
-          server.mount(uri.path, Faspex4PostProcServlet, parameters.except(*WebServerSimple::PARAMS))
-          server.start
-          Result::Status.new('Gateway terminated')
+          Faspex4PostProcServlet.serve(parameters.symbolize_keys, type: Cli::BadArgument)
+          Result::Status.new('Post-processing terminated')
         end
         ACCOUNT_TYPES = %w{local_user saml_user self_registered_user external_user}.freeze
         WORKGROUP_TYPES = %w{workgroup shared_inbox}.freeze

data/lib/aspera/cli/plugins/faspio.rb

@@ -29,23 +29,48 @@ module Aspera
         # @param app_url [String] Tested URL
         # @return [Hash] :preset_value, :test_args
         def wizard(wizard, app_url)
+          auth_type = options.get_option(:auth, mandatory: wizard.required) || :basic
+          preset_value = {
+            url:  app_url,
+            auth: auth_type.to_s
+          }
+          preset_ids = []
+          case auth_type
+          when :none
+            # No credentials needed
+          when :basic
+            username = options.get_option(:username, mandatory: true)
+            preset_value[:username] = username
+            preset_value[:password] = options.get_option(:password, mandatory: true)
+            preset_ids.push(username)
+          when :jwt
+            client_id = options.get_option(:client_id, mandatory: true)
+            preset_value[:client_id] = client_id
+            key_path = options.get_option(:key_path)
+            preset_value[:private_key] = key_path ? "@file:#{key_path}" : options.get_option(:private_key, mandatory: true)
+            passphrase = options.get_option(:passphrase)
+            preset_value[:passphrase] = passphrase unless passphrase.nil?
+            preset_ids.push(client_id)
+          end
           return {
-            preset_value: {
-              url: app_url
-            },
+            preset_ids:   preset_ids,
+            preset_value: preset_value,
             test_args:    'bridges list'
           }
         end
 
-        command :health, description: 'Check faspio Gateway health'
+        command :health,  description: 'Check faspio Gateway health'
+        command :metrics, description: 'Get Prometheus metrics'
 
         commands_under :bridges do
           crud_commands entity: 'bridges',
             api: :build_api,
+            operations: %i[create list show delete],
+            lookup: %w[name],
             body_component: Schema::Registry::FASPIO
         end
 
-        option :auth,        description: 'OAuth type of authentication', allowed: %i[jwt basic]
+        option :auth,        description: 'Type of authentication', allowed: %i[basic jwt none]
         option :client_id,   description: 'OAuth client identifier'
         option :private_key, description: 'OAuth JWT RSA private key PEM **value**'
         option :passphrase,  description: 'OAuth JWT RSA private key passphrase'
@@ -55,6 +80,8 @@ module Aspera
         def build_api
           base_url = options.get_option(:url, mandatory: true)
           case options.get_option(:auth, mandatory: true)
+          when :none
+            Rest::Client.new(base_url: base_url)
           when :basic
             basic_auth_api
           when :jwt
@@ -94,6 +121,10 @@ module Aspera
           end
           Result::ObjectList.new(nagios.status_list)
         end
+
+        def action_metrics(**)
+          Result::Text.new(build_api.read('metrics', headers: {'Accept' => 'text/plain'}))
+        end
       end
     end
   end

data/lib/aspera/cli/plugins/httpgw.rb

@@ -29,6 +29,7 @@ module Aspera
         # @return [Hash] :preset_value, :test_args
         def wizard(wizard, app_url)
           return {
+            preset_ids:   [],
             preset_value: {
               url: app_url
             },