aspera-cli 4.26.1 → 4.27.0

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

@@ -48,13 +48,31 @@ module Aspera
 
         attr_accessor :option_skip_types, :option_previews_folder, :option_folder_reset_cache, :option_skip_folders, :option_overwrite
 
+        # DSL option declarations (Pattern 1 and Pattern 2 - handler: Symbol resolved to self)
+        option :skip_format,        description: 'Skip this preview format',                                                                                                      allowed: Aspera::Preview::Generator::PREVIEW_FORMATS
+        # TODO: use the same option as in `node` plugin
+        option :folder_reset_cache, description: 'Force detection of generated preview by refresh cache',                                                                         allowed: %i[no header read], handler: :option_folder_reset_cache, default: :no
+        option :skip_types,         description: 'Skip generation for those types of files',                                                                                      allowed: Allowed::TYPES_SYMBOL_ARRAY + Aspera::Preview::FileTypes::CONVERSION_TYPES, handler: :option_skip_types
+        option :previews_folder,    description: 'Preview folder in storage root',                                                                                                handler: :option_previews_folder, default: DEFAULT_PREVIEWS_FOLDER
+        option :skip_folders,       description: 'List of folder to skip',                                                                                                        allowed: Allowed::TYPES_STRING_ARRAY, handler: :option_skip_folders
+        option :base,               description: 'Basename of output for for test'
+        option :scan_path,          description: 'Subpath in folder id to start scan in (default=/)'
+        option :scan_id,            description: 'Folder id in storage to start scan in, default is access key main folder id'
+        option :mimemagic,          description: 'Use Mime type detection of gem mimemagic',                                                                                      allowed: Allowed::TYPES_BOOLEAN, default: false
+        option :overwrite,          description: 'When to overwrite result file',                                                                                                 allowed: %i[always never mtime], handler: :option_overwrite, default: :mtime
+        option :root_url,           description: "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})", default: ''
+        # Generator-specific options (Category C - bound to @gen_options via set_handler in initialize)
+        Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
+          values = if opt.key?(:values)
+            opt[:values]
+          elsif BoolValue.symbol?(opt[:default])
+            BoolValue::TYPES
+          end
+          option(opt[:name], description: opt[:description].capitalize, allowed: values, default: opt[:default])
+        end
+
         def initialize(**_)
           super
-          @option_skip_types = []
-          @option_skip_folders = []
-          @option_previews_folder = nil
-          @option_overwrite = nil
-          @option_folder_reset_cache = nil
           # Generator configuration populated from CLI options.
           @gen_options = Aspera::Preview::Options.new
           # Used to rate-limit periodic progress logging and checkpoint persistence.
@@ -62,40 +80,9 @@ module Aspera
           # Optional callback used to filter entries before generation.
           @filter_block = nil
           @access_remote = true
-          # Bind CLI options directly to generator option attributes.
-          options.declare(
-            :skip_format, 'Skip this preview format',
-            allowed: Aspera::Preview::Generator::PREVIEW_FORMATS
-          )
-          # TODO: use the same option as in `node` plugin
-          options.declare(
-            :folder_reset_cache, 'Force detection of generated preview by refresh cache',
-            allowed: %i[no header read],
-            handler: {o: self, m: :option_folder_reset_cache},
-            default: :no
-          )
-          options.declare(:skip_types, 'Skip generation for those types of files', handler: {o: self, m: :option_skip_types}, allowed: Allowed::TYPES_SYMBOL_ARRAY + Aspera::Preview::FileTypes::CONVERSION_TYPES)
-          options.declare(:previews_folder, 'Preview folder in storage root', handler: {o: self, m: :option_previews_folder}, default: DEFAULT_PREVIEWS_FOLDER)
-          options.declare(:skip_folders, 'List of folder to skip', handler: {o: self, m: :option_skip_folders}, allowed: Allowed::TYPES_STRING_ARRAY)
-          options.declare(:base, 'Basename of output for for test')
-          options.declare(:scan_path, 'Subpath in folder id to start scan in (default=/)')
-          options.declare(:scan_id, 'Folder id in storage to start scan in, default is access key main folder id')
-          options.declare(:mimemagic, 'Use Mime type detection of gem mimemagic', allowed: Allowed::TYPES_BOOLEAN, default: false)
-          options.declare(:overwrite, 'When to overwrite result file', handler: {o: self, m: :option_overwrite}, allowed: %i[always never mtime], default: :mtime)
-          options.declare(
-            :root_url,
-            "How to read and write files on storage (<empty>, #{REMOTE_ACCESS}, or #{UriReader.file_url('<folder>')})",
-            allowed: Allowed::TYPES_STRING,
-            default: ''
-          )
-          # Declare generator-specific options and apply their default values.
+          # Bind generator-specific options to @gen_options (Category C: set_handler after object creation)
           Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
-            values = if opt.key?(:values)
-              opt[:values]
-            elsif BoolValue.symbol?(opt[:default])
-              BoolValue::TYPES
-            end
-            options.declare(opt[:name], opt[:description].capitalize, allowed: values, handler: {o: @gen_options, m: opt[:name]}, default: opt[:default])
+            options.set_handler(opt[:name], object: @gen_options, method: opt[:name])
           end
 
           options.parse_options!
@@ -112,7 +99,7 @@ module Aspera
         # Process legacy transfer events and trigger preview generation for completed downloads.
         #
         # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
-        # @return [void]
+        # @return [nil]
         def process_trevents(iteration_persistency)
           events_filter = {
             'access_key' => @access_key_self['id'],
@@ -152,12 +139,13 @@ module Aspera
               iteration_persistency.save
             end
           end
+          nil
         end
 
         # Process recent Node API file events since the last persisted checkpoint.
         #
         # @param iteration_persistency [PersistencyActionOnce, nil] stores the last processed event id
-        # @return [void]
+        # @return [nil]
         def process_events(iteration_persistency)
           # Restrict the event stream to file-related changes for the current access key.
           events_filter = {
@@ -188,6 +176,7 @@ module Aspera
               iteration_persistency.save
             end
           end
+          nil
         end
 
         # Transfer a file to or from the configured Node storage using a tagged transfer spec.
@@ -198,7 +187,7 @@ module Aspera
         # @param destination [String, nil] local destination root for receive operations
         # @return [Object] transfer result returned by [`Main.result_transfer`](lib/aspera/cli/main.rb)
         def do_transfer(direction, folder_id, source_filename, destination = '/')
-          Aspera.assert(!(destination.nil? && direction.eql?(Transfer::Spec::DIRECTION_RECEIVE)))
+          Aspera.assert(!(destination.nil? && direction.eql?(Transfer::Spec::DIRECTION_RECEIVE)), 'destination must be set for receive direction')
           t_spec = @api_node.transfer_spec_gen4(folder_id, direction, {
             'paths' => [{'source' => source_filename}],
             'tags'  => {Transfer::Spec::TAG_RESERVED => {PREV_GEN_TAG => true}}
@@ -206,7 +195,7 @@ module Aspera
           # Force the destination on the transfer agent object.
           # Setting `t_spec['destination_root']` directly would later be overwritten.
           transfer.user_transfer_spec['destination_root'] = destination
-          Main.result_transfer(transfer.start(t_spec))
+          Runner.result_transfer(transfer.start(t_spec))
         end
 
         # Populate generation metadata for a source file available on the local filesystem.
@@ -278,7 +267,7 @@ module Aspera
         # Remote entries must include `parent_file_id`.
         #
         # @param entry [Hash] local or remote file entry to preview
-        # @return [void]
+        # @return [nil]
         def generate_preview(entry)
           # prepare generic information
           gen_infos = @preview_formats_to_generate.map do |preview_format|
@@ -323,7 +312,7 @@ module Aspera
           # create folder if needed
           FileUtils.mkdir_p(local_entry_preview_dir)
           if @access_remote
-            Aspera.assert(!entry['parent_file_id'].nil?){'missing parent_file_id in entry'}
+            Aspera.assert(!entry['parent_file_id'].nil?, 'missing parent_file_id in entry')
             #  download original file to temp folder
             do_transfer(Transfer::Spec::DIRECTION_RECEIVE, entry['parent_file_id'], entry['name'], @tmp_folder)
           end
@@ -406,113 +395,165 @@ module Aspera
           end
         end
 
-        ACTIONS = %i[scan events trevents check test show].freeze
+        # --- DSL ---
+
+        # Commands that connect to the Node API share a common setup.
+        # :check, :test and :show work without Node API authentication.
+        command :scan,     description: 'Scan all files and generate previews', setup: :setup_node_api
+        command :events,   description: 'Process file events and generate previews', setup: :setup_node_api
+        command :trevents, description: 'Process transfer events and generate previews', setup: :setup_node_api
+        command :check,    description: 'Check required tools are installed'
+        command :test,     description: 'Test preview generation for a source file',
+          arguments: [{name: :source_file, type: String}, {name: :format, allowed: Aspera::Preview::Generator::PREVIEW_FORMATS, mandatory: false, default: :png}]
+        command :show,     description: 'Generate and display preview of a source file',
+          arguments: [{name: :source_file, type: String}]
+
+        # --- setup ---
 
-        def execute_action
-          command = options.get_next_command(ACTIONS)
-          unless %i[check test show].include?(command)
-            # This will use node api
-            @api_node = Api::Node.new(**basic_auth_params)
-            @transfer_server_address = URI.parse(@api_node.base_url).host
-            # Get current access key information
-            @access_key_self = @api_node.read('access_keys/self')
-            # TODO: check events is activated here:
-            # note that docroot is good to look at as well
-            node_info = @api_node.read('info')
-            Log.log.debug{"root: #{node_info['docroot']}"}
-            # Default storage url to local file if not provided
-            option_root_url = options.get_option(:root_url, mandatory: true)
-            option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.empty? && @access_key_self['storage']['type'].eql?('local')
-            @access_remote = !UriReader.file?(option_root_url)
-            Log.log.debug{"remote: #{@access_remote}"}
-            # TODO: can the `previews` folder parameter be read from Node API ?
-            @option_skip_folders.push("/#{@option_previews_folder}")
-            if @access_remote
-              # NOTE: the filter "name", it's why we take the first one
-              @previews_folder_entry = @api_node.read_folder_content(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
-              raise Cli::Error, "Folder #{@option_previews_folder} does not exist on node. " \
-                'Please create it in the storage root, or specify an alternate name.' if @previews_folder_entry.nil?
+        # Build the Node API and set up storage references for scan/events/trevents.
+        # @return [Hash] empty ctx (state stored in instance variables)
+        def setup_node_api(**)
+          @api_node = Api::Node.new(**basic_auth_params)
+          @transfer_server_address = URI.parse(@api_node.base_url).host
+          # Get current access key information
+          @access_key_self = @api_node.read('access_keys/self')
+          # TODO: check events is activated here:
+          # note that docroot is good to look at as well
+          node_info = @api_node.read('info')
+          Log.log.debug{"root: #{node_info['docroot']}"}
+          # Default storage url to local file if not provided
+          option_root_url = options.get_option(:root_url, mandatory: true)
+          option_root_url = UriReader.file_url(@access_key_self['storage']['path']) if option_root_url.empty? && @access_key_self['storage']['type'].eql?('local')
+          @access_remote = !UriReader.file?(option_root_url)
+          Log.log.debug{"remote: #{@access_remote}"}
+          # TODO: can the `previews` folder parameter be read from Node API ?
+          @option_skip_folders.push("/#{@option_previews_folder}")
+          if @access_remote
+            # NOTE: the filter "name", it's why we take the first one
+            @previews_folder_entry = @api_node.read_folder_content(@access_key_self['root_file_id'], {name: @option_previews_folder}).first
+            raise Cli::Error, "Folder #{@option_previews_folder} does not exist on node. " \
+              'Please create it in the storage root, or specify an alternate name.' if @previews_folder_entry.nil?
+          else
+            @local_storage_root = UriReader.file_path(option_root_url)
+            # TODO: Windows could have "C:" ?
+            Aspera.assert(@local_storage_root.start_with?('/')){"not local storage: #{@local_storage_root}"}
+            Aspera.assert(File.directory?(@local_storage_root), type: Cli::Error){"Local storage root folder #{@local_storage_root} does not exist."}
+            @local_preview_folder = File.join(@local_storage_root, @option_previews_folder)
+            Aspera.assert(File.directory?(@local_preview_folder), type: Cli::Error){"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name."}
+            # Protection to avoid clash of file id for two different access keys
+            marker_file = File.join(@local_preview_folder, AK_MARKER_FILE)
+            Log.log.debug{"marker file: #{marker_file}"}
+            if File.exist?(marker_file)
+              ak = File.read(marker_file).chomp
+              Aspera.assert(@access_key_self['id'].eql?(ak)){"mismatch access key in #{marker_file}: contains #{ak}, using #{@access_key_self['id']}"}
             else
-              @local_storage_root = UriReader.file_path(option_root_url)
-              # TODO: Windows could have "C:" ?
-              Aspera.assert(@local_storage_root.start_with?('/')){"not local storage: #{@local_storage_root}"}
-              Aspera.assert(File.directory?(@local_storage_root), type: Cli::Error){"Local storage root folder #{@local_storage_root} does not exist."}
-              @local_preview_folder = File.join(@local_storage_root, @option_previews_folder)
-              Aspera.assert(File.directory?(@local_preview_folder), type: Cli::Error){"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name."}
-              # Protection to avoid clash of file id for two different access keys
-              marker_file = File.join(@local_preview_folder, AK_MARKER_FILE)
-              Log.log.debug{"marker file: #{marker_file}"}
-              if File.exist?(marker_file)
-                ak = File.read(marker_file).chomp
-                Aspera.assert(@access_key_self['id'].eql?(ak)){"mismatch access key in #{marker_file}: contains #{ak}, using #{@access_key_self['id']}"}
-              else
-                File.write(marker_file, @access_key_self['id'])
-              end
+              File.write(marker_file, @access_key_self['id'])
             end
           end
-          Aspera::Preview::FileTypes.instance.use_mimemagic = options.get_option(:mimemagic, mandatory: true)
-          # check tools that are anyway required for all cases
-          Aspera::Preview::Utils.check_tools(@option_skip_types)
-          case command
-          when :scan
-            scan_path = options.get_option(:scan_path)
-            scan_id = options.get_option(:scan_id)
-            # by default start at root
-            folder_info =
-              if scan_id.nil?
-                {
-                  'id'   => @access_key_self['root_file_id'],
-                  'name' => '/',
-                  'type' => 'folder',
-                  'path' => '/'
-                }
-              else
-                @api_node.read("files/#{scan_id}")
-              end
-            @filter_block = Api::Node.file_matcher_from_argument(options)
-            scan_folder_files(folder_info, scan_path)
-            return Main.result_status('scan finished')
-          when :events, :trevents
-            @filter_block = Api::Node.file_matcher_from_argument(options)
-            iteration_persistency = nil
-            if options.get_option(:once_only, mandatory: true)
-              iteration_persistency = PersistencyActionOnce.new(
-                manager: persistency,
-                data:    [],
-                id:      IdGenerator.from_list(
-                  'preview_iteration',
-                  command.to_s,
-                  options.get_option(:url, mandatory: true),
-                  options.get_option(:username, mandatory: true)
-                )
-              )
+          {}
+        end
+
+        # --- handlers ---
+
+        def action_scan
+          check_tools_and_mimemagic
+          scan_path = options.get_option(:scan_path)
+          scan_id = options.get_option(:scan_id)
+          folder_info =
+            if scan_id.nil?
+              {
+                'id'   => @access_key_self['root_file_id'],
+                'name' => '/',
+                'type' => 'folder',
+                'path' => '/'
+              }
+            else
+              @api_node.read("files/#{scan_id}")
             end
-            # call processing method specified by command line command
-            send(:"process_#{command}", iteration_persistency)
-            return Main.result_status("#{command} finished")
-          when :check
-            return Main.result_status('Tools validated')
-          when :test
-            source = options.get_next_argument('source file')
-            format = options.get_next_argument('format', accept_list: Aspera::Preview::Generator::PREVIEW_FORMATS, default: :png)
-            generated_file_path = preview_filename(format, options.get_option(:base))
-            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
-            return Main.result_status("generated: #{generated_file_path}")
-          when :show
-            source = options.get_next_argument('source file')
-            # terminal_options = options.get_next_argument('options', validation: Hash, default: {}).symbolize_keys
-            generated_file_path = preview_filename(:png, options.get_option(:base))
-            Aspera::Preview::Generator.new(source, generated_file_path, @gen_options, @tmp_folder).generate
-            formatter.display_status("generated: #{generated_file_path}")
-            # formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
-            # return Main.result_status("generated: #{generated_file_path}")
-            return Main.result_image(UriReader.file_url(generated_file_path))
-          else Aspera.error_unexpected_value(command)
-          end
+          @filter_block = Api::Node.file_matcher_from_argument(options)
+          scan_folder_files(folder_info, scan_path)
+          Result::Status.new('scan finished')
         ensure
+          cleanup_tmp_folder
+        end
+
+        def action_events
+          check_tools_and_mimemagic
+          run_event_loop(:events)
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_trevents
+          check_tools_and_mimemagic
+          run_event_loop(:trevents)
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_check
+          check_tools_and_mimemagic
+          Result::Status.new('Tools validated')
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_test(source_file:, format:, **)
+          check_tools_and_mimemagic
+          generated_file_path = preview_filename(format, options.get_option(:base))
+          Aspera::Preview::Generator.new(source_file, generated_file_path, @gen_options, @tmp_folder).generate
+          Result::Status.new("generated: #{generated_file_path}")
+        ensure
+          cleanup_tmp_folder
+        end
+
+        def action_show(source_file:, **)
+          check_tools_and_mimemagic
+          # terminal_options = options.get_next_argument('options', validation: Hash, default: {}).symbolize_keys
+          generated_file_path = preview_filename(:png, options.get_option(:base))
+          Aspera::Preview::Generator.new(source_file, generated_file_path, @gen_options, @tmp_folder).generate
+          formatter.display_status("generated: #{generated_file_path}")
+          # formatter.display_status(Aspera::Preview::Terminal.build(File.read(generated_file_path), **terminal_options))
+          # Result::Status.new("generated: #{generated_file_path}")
+          Result::Image.new(UriReader.file_url(generated_file_path))
+        ensure
+          cleanup_tmp_folder
+        end
+
+        private
+
+        # Check tools and set mimemagic flag (required for all commands).
+        def check_tools_and_mimemagic
+          Aspera::Preview::FileTypes.instance.use_mimemagic = options.get_option(:mimemagic, mandatory: true)
+          Aspera::Preview::Utils.check_tools(@option_skip_types)
+        end
+
+        # Clean up the temporary folder after each command.
+        def cleanup_tmp_folder
           Log.log.debug{"cleaning up temp folder #{@tmp_folder}"}
           FileUtils.rm_rf(@tmp_folder)
         end
+
+        # Shared event-loop body for :events and :trevents.
+        # @param command [:events, :trevents]
+        def run_event_loop(command)
+          @filter_block = Api::Node.file_matcher_from_argument(options)
+          iteration_persistency = nil
+          if options.get_option(:once_only, mandatory: true)
+            iteration_persistency = PersistencyActionOnce.new(
+              manager: persistency,
+              data:    [],
+              id:      IdGenerator.from_list(
+                'preview_iteration',
+                command.to_s,
+                options.get_option(:url, mandatory: true),
+                options.get_option(:username, mandatory: true)
+              )
+            )
+          end
+          send(:"process_#{command}", iteration_persistency)
+          Result::Status.new("#{command} finished")
+        end
       end
     end
   end