aspera-cli 4.26.1 → 4.27.0

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'aspera/assert'
 require 'aspera/cli/plugins/basic_auth'
 require 'aspera/nagios'
 
@@ -70,11 +71,114 @@ module Aspera
           super
         end
 
+        # --- DSL ---
+
+        command :health,   description: 'Check Console API health', setup: :setup_api
+        command :transfer, description: 'Manage transfers',         setup: :setup_api
+
+        commands_under(:transfer) do
+          command :current, description: 'Manage current transfers'
+          command :smart,   description: 'Manage smart transfers'
+        end
+
+        commands_under(%i[transfer current]) do
+          command :list,          description: 'List current transfers'
+          command :show,          description: 'Show a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}],
+            action: ->(api_console:, transfer_id:, **){Result::SingleObject.new(api_console.read("transfers/#{transfer_id}"))}
+          command :files,         description: 'List files in a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :start,         description: 'Start a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :pause,         description: 'Pause a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :cancel,        description: 'Cancel a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :resume,        description: 'Resume a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :rerun,         description: 'Rerun a transfer',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :change_rate,   description: 'Change transfer rate',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :change_policy, description: 'Change transfer policy',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :move_forwards, description: 'Move transfer forwards',
+            arguments: [{name: :transfer_id, type: :identifier}]
+          command :move_back,     description: 'Move transfer backwards',
+            arguments: [{name: :transfer_id, type: :identifier}]
+        end
+
+        # Generate one handler per transfer/current action.
+        # Convention: action_transfer_current_<verb>
+        # All share the same REST pattern: PATCH transfers/<id>/<verb>.
+        %i[start pause cancel resume rerun change_rate change_policy move_forwards move_back].each do |verb|
+          define_action_method([:transfer, :current, verb]) do |api_console:, transfer_id:, **|
+            Result::SingleObject.new(api_console.update("transfers/#{transfer_id}/#{verb}", query_read_delete))
+          end
+        end
+
+        commands_under(%i[transfer smart]) do
+          command :list,   description: 'List smart transfers', action: ->(api_console:){Result::ObjectList.new(api_console.read('smart_transfers'))}
+          command :submit, description: 'Submit a smart transfer',
+            arguments: [{name: :smart_id}, {name: :transfer_params, type: Hash}]
+        end
+
+        # --- setup ---
+
+        # Build the Console REST API.
+        # @return [Hash] ctx with :api_console
+        def setup_api(**)
+          {api_console: basic_auth_api('api')}
+        end
+
+        # --- health ---
+
+        def action_health(api_console:)
+          nagios = Nagios.new
+          begin
+            api_console.read('ssh_keys')
+            nagios.add_ok('console api', 'accessible')
+          rescue StandardError => e
+            nagios.add_critical('console api', e.to_s)
+          end
+          Result::ObjectList.new(nagios.status_list)
+        end
+
+        # --- transfer current ---
+
+        def action_transfer_current_list(api_console:)
+          query = query_read_delete(default: {})
+          if query['from'].nil? && query['to'].nil?
+            time_now = Time.now
+            query['from'] = self.class.time_to_string(time_now - DEFAULT_FILTER_AGE_SECONDS)
+            query['to'] = self.class.time_to_string(time_now)
+          end
+          parse_extended_filter(query.delete('filter'), query) if query['filter']
+          Result::ObjectList.new(
+            api_console.read('transfers', query),
+            fields: %w[id contact name status]
+          )
+        end
+
+        def action_transfer_current_files(api_console:, transfer_id:, **)
+          query = query_read_delete(default: {})
+          query['limit'] ||= 100
+          Result::ObjectList.new(api_console.read("transfers/#{transfer_id}/files", query))
+        end
+
+        # --- transfer smart ---
+
+        def action_transfer_smart_submit(api_console:, smart_id:, transfer_params:, **)
+          Result::ObjectList.new(api_console.create("smart_transfers/#{smart_id}", transfer_params))
+        end
+
+        private
+
         def parse_extended_filter(filter, query)
-          raise BadArgument, "Invalid filter syntax: #{filter}, shall be (field op val)and(field op val)..." unless filter.start_with?('(') && filter.end_with?(')')
+          Aspera.assert(filter.start_with?('(') && filter.end_with?(')'), type: BadArgument){"Invalid filter syntax: #{filter}, shall be (field op val)and(field op val)..."}
           filter[1..-2].split(')and(').each_with_index do |expr, i|
             m = expr.match(EXPR_RE)
-            raise BadArgument, "Invalid expression: #{expr}, shall be: <field> <op> <val>" unless m
+            Aspera.assert(m, type: BadArgument){"Invalid expression: #{expr}, shall be: <field> <op> <val>"}
             t = m.captures
             i += 1
             query["filter#{i}"] = t[0]
@@ -82,68 +186,6 @@ module Aspera
             query["val#{i}"]    = t[2]
           end
         end
-
-        ACTIONS = %i[transfer health].freeze
-
-        def execute_action
-          api_console = basic_auth_api('api')
-          command = options.get_next_command(ACTIONS)
-          case command
-          when :health
-            nagios = Nagios.new
-            begin
-              api_console.read('ssh_keys')
-              nagios.add_ok('console api', 'accessible')
-            rescue StandardError => e
-              nagios.add_critical('console api', e.to_s)
-            end
-            Main.result_object_list(nagios.status_list)
-          when :transfer
-            command = options.get_next_command(%i[current smart])
-            case command
-            when :smart
-              command = options.get_next_command(%i[list submit])
-              case command
-              when :list
-                return Main.result_object_list(api_console.read('smart_transfers'))
-              when :submit
-                smart_id = options.get_next_argument('smart_id')
-                params = options.get_next_argument('transfer parameters', validation: Hash)
-                return Main.result_object_list(api_console.create("smart_transfers/#{smart_id}", params))
-              end
-            when :current
-              command = options.get_next_command(%i[list show files start pause cancel resume rerun change_rate change_policy move_forwards move_back])
-              case command
-              when :list
-                # https://developer.ibm.com/apis/catalog/aspera--aspera-console-rest-api/Developer+Guides#transfer-list
-                query = query_read_delete(default: {})
-                if query['from'].nil? && query['to'].nil?
-                  time_now = Time.now
-                  query['from'] = self.class.time_to_string(time_now - DEFAULT_FILTER_AGE_SECONDS)
-                  query['to'] = self.class.time_to_string(time_now)
-                end
-                if (filter = query.delete('filter'))
-                  parse_extended_filter(filter, query)
-                end
-                return Main.result_object_list(
-                  api_console.read('transfers', query),
-                  fields: %w[id contact name status]
-                )
-              when :show
-                transfer_id = options.instance_identifier(description: 'transfer ID')
-                return Main.result_single_object(api_console.read("transfers/#{transfer_id}"))
-              when :files
-                transfer_id = options.instance_identifier(description: 'transfer ID')
-                query = query_read_delete(default: {})
-                query['limit'] ||= 100
-                return Main.result_object_list(api_console.read("transfers/#{transfer_id}/files", query))
-              when :start, :pause, :cancel, :resume, :rerun, :change_rate, :change_policy, :move_forwards, :move_back
-                transfer_id = options.instance_identifier(description: 'transfer ID')
-                return Main.result_single_object(api_console.update("transfers/#{transfer_id}/#{command}", query_read_delete))
-              end
-            end
-          end
-        end
       end
     end
   end

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

@@ -9,44 +9,56 @@ module Aspera
   module Cli
     module Plugins
       class Cos < Base
+        application_name 'IBM Cloud Object Storage'
+
+        command :node, description: 'Execute COS node commands', setup: :setup_cos_node
+
+        commands_under(:node) do
+          Node::COMMANDS_COS.each do |cmd|
+            command(cmd, description: "Node #{cmd} command")
+          end
+        end
+
+        option :bucket,              description: 'Bucket name'
+        option :endpoint,            description: 'Storage endpoint (URL)'
+        option :apikey,              description: 'Storage API key'
+        option :crn,                 description: 'Resource instance id (CRN)'
+        option :service_credentials, description: 'IBM Cloud service credentials', allowed: [Hash, NilClass]
+        option :region,              description: 'Storage region'
+        option :identity,            description: "Authentication URL (#{Api::CosNode::IBM_CLOUD_TOKEN_URL})", default: Api::CosNode::IBM_CLOUD_TOKEN_URL
+
         def initialize(**_)
           super
-          options.declare(:bucket, 'Bucket name')
-          options.declare(:endpoint, 'Storage endpoint (URL)')
-          options.declare(:apikey, 'Storage API key')
-          options.declare(:crn, 'Resource instance id (CRN)')
-          options.declare(:service_credentials, 'IBM Cloud service credentials', allowed: [Hash, NilClass])
-          options.declare(:region, 'Storage region')
-          options.declare(:identity, "Authentication URL (#{Api::CosNode::IBM_CLOUD_TOKEN_URL})", default: Api::CosNode::IBM_CLOUD_TOKEN_URL)
           options.parse_options!
           Node.declare_options(options)
         end
 
-        ACTIONS = %i[node].freeze
-
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          case command
-          when :node
-            # get service credentials, Hash, e.g. @json:@file:...
-            service_credentials = options.get_option(:service_credentials)
-            cos_node_params = {
-              auth_url: options.get_option(:identity, mandatory: true),
-              bucket:   options.get_option(:bucket, mandatory: true),
-              endpoint: options.get_option(:endpoint)
-            }
-            if service_credentials.nil?
-              Aspera.assert(!cos_node_params[:endpoint].nil?, type: Cli::BadArgument){'endpoint required when service credentials not provided'}
-              cos_node_params[:api_key] = options.get_option(:apikey, mandatory: true)
-              cos_node_params[:instance_id] = options.get_option(:crn, mandatory: true)
-            else
-              Aspera.assert(cos_node_params[:endpoint].nil?, type: Cli::BadArgument){'endpoint not allowed when service credentials provided'}
-              cos_node_params.merge!(Api::CosNode.parameters_from_svc_credentials(service_credentials, options.get_option(:region, mandatory: true)))
-            end
-            api_node = Api::CosNode.new(**cos_node_params)
-            node_plugin = Node.new(context: context, api: api_node)
-            command = options.get_next_command(Node::COMMANDS_COS)
-            return node_plugin.execute_action(command)
+        # Build the COS Node API and plugin from CLI options.
+        # @return [Hash] context hash containing :node_plugin
+        def setup_cos_node(**)
+          # get service credentials, Hash, e.g. @json:@file:...
+          service_credentials = options.get_option(:service_credentials)
+          cos_node_params = {
+            auth_url: options.get_option(:identity, mandatory: true),
+            bucket:   options.get_option(:bucket, mandatory: true),
+            endpoint: options.get_option(:endpoint)
+          }
+          if service_credentials.nil?
+            Aspera.assert(!cos_node_params[:endpoint].nil?, 'endpoint required when service credentials not provided', type: Cli::BadArgument)
+            cos_node_params[:api_key] = options.get_option(:apikey, mandatory: true)
+            cos_node_params[:instance_id] = options.get_option(:crn, mandatory: true)
+          else
+            Aspera.assert(cos_node_params[:endpoint].nil?, 'endpoint not allowed when service credentials provided', type: Cli::BadArgument)
+            cos_node_params.merge!(Api::CosNode.parameters_from_svc_credentials(service_credentials, options.get_option(:region, mandatory: true)))
+          end
+          api_node = Api::CosNode.new(**cos_node_params)
+          {node_plugin: Node.new(context: context, api: api_node)}
+        end
+
+        # One handler per COMMANDS_COS command - delegates to the Node plugin's dispatch_v3_command.
+        Node::COMMANDS_COS.each do |cmd|
+          define_action_method([:node, cmd]) do |node_plugin:|
+            node_plugin.dispatch_v3_command(cmd)
           end
         end
       end

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

@@ -9,6 +9,9 @@ module Aspera
   module Cli
     # Instantiate plugin from well-known locations
     module Plugins
+      # @!method self.instance
+      #   Returns the singleton instance of Factory
+      #   @return [Factory] the singleton instance
       class Factory
         include Singleton
 
@@ -27,7 +30,7 @@ module Aspera
 
         # add a folder to the list of folders to look for plugins
         def add_lookup_folder(folder)
-          @lookup_folders.unshift(folder)
+          @lookup_folders.unshift(folder) unless @lookup_folders.include?(folder)
         end
 
         # find plugins in defined paths
@@ -42,19 +45,19 @@ module Aspera
               plugin_symbol = File.basename(path, Environment::RB_EXT).to_sym
               next if IGNORE_PLUGINS.include?(plugin_symbol)
               req = path.sub(/#{Environment::RB_EXT}$/o, '')
-              Aspera.assert(!@plugins.key?(plugin_symbol), type: :warn){"Plugin already registered: #{plugin_symbol}"}
+              next if @plugins.key?(plugin_symbol)
               @plugins[plugin_symbol] = {source: path, require_stanza: req}
             end
           end
         end
 
-        # @return path to source file of plugin
+        # @return [String] path to source file of plugin
         def plugin_source(plugin_name_sym)
           Aspera.assert(@plugins.key?(plugin_name_sym), type: NoSuchElement){"plugin not found: #{plugin_name_sym}"}
           @plugins[plugin_name_sym][:source]
         end
 
-        # @return Class object for plugin
+        # @return [Class] class object for plugin
         def plugin_class(plugin_name_sym)
           Aspera.assert(@plugins.key?(plugin_name_sym), type: NoSuchElement){"plugin not found: #{plugin_name_sym}"}
           require @plugins[plugin_name_sym][:require_stanza]