aspera-cli 4.0.0.pre1

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

@@ -0,0 +1,169 @@
+require 'aspera/cli/plugins/node'
+require 'xmlsimple'
+
+module Aspera
+  module Cli
+    module Plugins
+      class Orchestrator < BasicAuthPlugin
+        def initialize(env)
+          super(env)
+          self.options.add_opt_simple(:params,"parameters hash table, use @json:{\"param\":\"value\"}")
+          self.options.add_opt_simple(:result,"specify result value as: 'work step:parameter'")
+          self.options.add_opt_boolean(:synchronous,"work step:parameter expected as result")
+          self.options.add_opt_list(:ret_style,[:header,:arg,:ext],'how return type is requested in api')
+          self.options.add_opt_list(:auth_style,[:arg_pass,:head_basic,:apikey],'authentication type')
+          self.options.set_option(:params,{})
+          self.options.set_option(:synchronous,:no)
+          self.options.set_option(:ret_style,:arg)
+          self.options.set_option(:auth_style,:head_basic)
+          self.options.parse_options!
+        end
+
+        ACTIONS=[:info, :workflow, :plugins, :processes]
+
+        # for JSON format: add extension ".json" or add url parameter: format=json or Accept: application/json
+        # id can be: a parameter id=x, or at the end of url /id, for workflows: work_order[workflow_id]=wf_id
+        def call_API_orig(endpoint,id=nil,url_params={:format=>:json},accept=nil)
+          # calls are GET
+          call_args={:operation=>'GET',:subpath=>endpoint}
+          # specify id if necessary
+          call_args[:subpath]=call_args[:subpath]+'/'+id unless id.nil?
+          unless url_params.nil?
+            if url_params.has_key?(:format)
+              call_args[:headers]={'Accept'=>'application/'+url_params[:format].to_s}
+            end
+            call_args[:headers]={'Accept'=>accept} unless accept.nil?
+            # add params if necessary
+            call_args[:url_params]=url_params
+          end
+          return @api_orch.call(call_args)
+        end
+
+        def call_API(endpoint,opt={})
+          opt[:prefix]='api' unless opt.has_key?(:prefix)
+          # calls are GET
+          call_args={:operation=>'GET',:subpath=>endpoint}
+          # specify prefix if necessary
+          call_args[:subpath]="#{opt[:prefix]}/#{call_args[:subpath]}" unless opt[:prefix].nil?
+          # specify id if necessary
+          call_args[:subpath]="#{call_args[:subpath]}/#{opt[:id]}" if opt.has_key?(:id)
+          call_type=self.options.get_option(:ret_style,:mandatory)
+          call_type=opt[:ret_style] if opt.has_key?(:ret_style)
+          format='json'
+          format=opt[:format] if opt.has_key?(:format)
+          call_args[:url_params]=opt[:args] unless opt[:args].nil?
+          unless format.nil?
+            case call_type
+            when :header
+              call_args[:headers]={'Accept'=>'application/'+format}
+            when :arg
+              call_args[:url_params]||={}
+              call_args[:url_params][:format]=format
+            when :ext
+              call_args[:subpath]="#{call_args[:subpath]}.#{format}"
+            else raise "unexpected"
+            end
+          end
+          result=@api_orch.call(call_args)
+          result[:data]=XmlSimple.xml_in(result[:http].body, opt[:xml_opt]||{"ForceArray" => true}) if format.eql?('xml')
+          return result
+        end
+
+        def execute_action
+          rest_params={:base_url       => self.options.get_option(:url,:mandatory)}
+          case self.options.get_option(:auth_style,:mandatory)
+          when :arg_pass
+            rest_params[:auth]={
+              :type      => :url,
+              :url_creds => {
+              'login'      =>self.options.get_option(:username,:mandatory),
+              'password'   =>self.options.get_option(:password,:mandatory) }}
+          when :head_basic
+            rest_params[:auth]={
+              :type      => :basic,
+              :username  =>self.options.get_option(:username,:mandatory),
+              :password  =>self.options.get_option(:password,:mandatory) }
+          when :apikey
+            raise "Not implemented"
+          end
+
+          @api_orch=Rest.new(rest_params)
+
+          command1=self.options.get_next_command(ACTIONS)
+          case command1
+          when :info
+            result=call_API('remote_node_ping',format: 'xml', xml_opt: {"ForceArray" => false})
+            return {:type=>:single_object,:data=>result[:data]}
+            #            result=call_API('workflows',prefix: nil,format: nil)
+            #            version='unknown'
+            #            if m=result[:http].body.match(/\(Orchestrator v([1-9]+\.[\.0-9a-f\-]+)\)/)
+            #              version=m[1]
+            #            end
+            #            return {:type=>:single_object,:data=>{'version'=>version}}
+          when :processes
+            # TODO: Jira ? API has only XML format
+            result=call_API('processes_status',format: 'xml')
+            return {:type=>:object_list,:data=>result[:data]['process']}
+          when :plugins
+            # TODO: Jira ? only json format on url
+            result=call_API('plugin_version')[:data]
+            return {:type=>:object_list,:data=>result['Plugin']}
+          when :workflow
+            command=self.options.get_next_command([:list, :status, :inputs, :details, :start, :export])
+            unless [:list, :status].include?(command)
+              wf_id=self.options.get_option(:id,:mandatory)
+            end
+            case command
+            when :status
+              result=call_API('workflows_status')[:data]
+              return {:type=>:object_list,:data=>result['workflows']['workflow']}
+            when :list
+              result=call_API('workflows_list',id: 0)[:data]
+              return {:type=>:object_list,:data=>result['workflows']['workflow'],:fields=>["id","portable_id","name","published_status","published_revision_id","latest_revision_id","last_modification"]}
+            when :details
+              result=call_API('workflow_details',id: wf_id)[:data]
+              return {:type=>:object_list,:data=>result['workflows']['workflow']['statuses']}
+            when :inputs
+              result=call_API('workflow_inputs_spec',id: wf_id)[:data]
+              return {:type=>:single_object,:data=>result['workflow_inputs_spec']}
+            when :export
+              result=call_API('export_workflow',id: wf_id,format: nil)[:http]
+              return {:type=>:text,:data=>result.body}
+            when :start
+              result={
+                :type=>:single_object,
+                :data=>nil
+              }
+              call_params={:format=>:json}
+              override_accept=nil
+              # set external parameters if any
+              self.options.get_option(:params,:mandatory).each do |name,value|
+                call_params["external_parameters[#{name}]"] = value
+              end
+              # synchronous call ?
+              call_params['synchronous']=true if self.options.get_option(:synchronous,:mandatory)
+              # expected result for synchro call ?
+              expected=self.options.get_option(:result,:optional)
+              unless expected.nil?
+                result[:type] = :status
+                fields=expected.split(/:/)
+                raise "Expects: work_step:result_name format, but got #{expected}" if fields.length != 2
+                call_params['explicit_output_step']=fields[0]
+                call_params['explicit_output_variable']=fields[1]
+                # implicitely, call is synchronous
+                call_params['synchronous']=true
+              end
+              if call_params['synchronous']
+                result[:type]=:text
+                override_accept='text/plain'
+              end
+              result[:data]=call_API('initiate',id: wf_id,args: call_params,accept: override_accept)[:data]
+              return result
+            end # wf command
+          else raise "ERROR, unknown command: [#{command}]"
+          end # case command
+        end # execute_action
+      end # Orchestrator
+    end # Plugins
+  end # Cli
+end # Aspera

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

@@ -0,0 +1,464 @@
+require 'aspera/cli/basic_auth_plugin'
+require 'aspera/preview/generator'
+require 'aspera/preview/options'
+require 'aspera/preview/utils'
+require 'aspera/preview/file_types'
+require 'aspera/persistency_action_once'
+require 'aspera/hash_ext'
+require 'date'
+require 'securerandom'
+
+module Aspera
+  module Cli
+    module Plugins
+      class Preview < BasicAuthPlugin
+        # special tag to identify transfers related to generator
+        PREV_GEN_TAG='preview_generator'
+        # defined by node API: suffix for folder containing previews
+        PREVIEW_FOLDER_SUFFIX='.asp-preview'
+        # basename of preview files
+        PREVIEW_BASENAME='preview'
+        # subfolder in system tmp folder
+        TMP_DIR_PREFIX='prev_tmp'
+        DEFAULT_PREVIEWS_FOLDER='previews'
+        AK_MARKER_FILE='.aspera_access_key'
+        LOCAL_STORAGE_PCVL='file:///'
+        private_constant :PREV_GEN_TAG, :PREVIEW_FOLDER_SUFFIX, :PREVIEW_BASENAME, :TMP_DIR_PREFIX, :DEFAULT_PREVIEWS_FOLDER, :LOCAL_STORAGE_PCVL, :AK_MARKER_FILE
+
+        # option_skip_format has special accessors
+        attr_accessor :option_previews_folder
+        attr_accessor :option_folder_reset_cache
+        attr_accessor :option_skip_folders
+        attr_accessor :option_overwrite
+        attr_accessor :option_file_access
+        def initialize(env)
+          super(env)
+          @skip_types=[]
+          @default_transfer_spec=nil
+          # by default generate all supported formats (clone, as altered by options)
+          @preview_formats_to_generate=Aspera::Preview::Generator::PREVIEW_FORMATS.clone
+          # options for generation
+          @gen_options=Aspera::Preview::Options.new
+          # link CLI options to gen_info attributes
+          self.options.set_obj_attr(:skip_format,self,:option_skip_format,[]) # no skip
+          self.options.set_obj_attr(:folder_reset_cache,self,:option_folder_reset_cache,:no)
+          self.options.set_obj_attr(:skip_types,self,:option_skip_types)
+          self.options.set_obj_attr(:previews_folder,self,:option_previews_folder,DEFAULT_PREVIEWS_FOLDER)
+          self.options.set_obj_attr(:skip_folders,self,:option_skip_folders,[]) # no skip
+          self.options.set_obj_attr(:overwrite,self,:option_overwrite,:mtime)
+          self.options.set_obj_attr(:file_access,self,:option_file_access,:local)
+          self.options.add_opt_list(:skip_format,Aspera::Preview::Generator::PREVIEW_FORMATS,'skip this preview format (multiple possible)')
+          self.options.add_opt_list(:folder_reset_cache,[:no,:header,:read],'force detection of generated preview by refresh cache')
+          self.options.add_opt_simple(:skip_types,'skip types in comma separated list')
+          self.options.add_opt_simple(:previews_folder,'preview folder in storage root')
+          self.options.add_opt_simple(:temp_folder,'path to temp folder')
+          self.options.add_opt_simple(:skip_folders,'list of folder to skip')
+          self.options.add_opt_simple(:case,'basename of output for for test')
+          self.options.add_opt_simple(:scan_path,'subpath in folder id to start scan in (default=/)')
+          self.options.add_opt_simple(:scan_id,'forder id in storage to start scan in, default is access key main folder id')
+          self.options.add_opt_list(:overwrite,[:always,:never,:mtime],'when to overwrite result file')
+          self.options.add_opt_list(:file_access,[:local,:remote],'how to read and write files in repository')
+          self.options.set_option(:temp_folder,Dir.tmpdir)
+
+          # add other options for generator (and set default values)
+          Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
+            self.options.set_obj_attr(opt[:name],@gen_options,opt[:name],opt[:default])
+            if opt.has_key?(:values)
+              self.options.add_opt_list(opt[:name],opt[:values],opt[:description])
+            elsif [:yes,:no].include?(opt[:default])
+              self.options.add_opt_boolean(opt[:name],opt[:description])
+            else
+              self.options.add_opt_simple(opt[:name],opt[:description])
+            end
+          end
+
+          self.options.parse_options!
+          raise 'skip_folder shall be an Array, use @json:[...]' unless @option_skip_folders.is_a?(Array)
+          @tmp_folder=File.join(self.options.get_option(:temp_folder,:mandatory),"#{TMP_DIR_PREFIX}.#{SecureRandom.uuid}")
+          FileUtils.mkdir_p(@tmp_folder)
+          Log.log.debug("tmpdir: #{@tmp_folder}")
+        end
+
+        def option_skip_types=(value)
+          @skip_types=[]
+          value.split(',').each do |v|
+            s=v.to_sym
+            raise "not supported: #{v}" unless Aspera::Preview::FileTypes::CONVERSION_TYPES.include?(s)
+            @skip_types.push(s)
+          end
+        end
+
+        def option_skip_types
+          return @skip_types.map{|i|i.to_s}.join(',')
+        end
+
+        def option_skip_format=(value)
+          @preview_formats_to_generate.delete(value)
+        end
+
+        def option_skip_format
+          return @preview_formats_to_generate.map{|i|i.to_s}.join(',')
+        end
+
+        ACTIONS=[:scan,:events,:trevents,:check,:test]
+
+        # /files/id/files is normally cached in redis, but we can discard the cache
+        # but /files/id is not cached
+        def get_folder_entries(file_id,request_args=nil)
+          headers={'Accept'=>'application/json'}
+          headers.merge!({'X-Aspera-Cache-Control'=>'no-cache'}) if @option_folder_reset_cache.eql?(:header)
+          return @api_node.call({:operation=>'GET',:subpath=>"files/#{file_id}/files",:headers=>headers,:url_params=>request_args})[:data]
+          #return @api_node.read("files/#{file_id}/files",request_args)[:data]
+        end
+
+        # old version based on folders
+        def process_transfer_events(iteration_token)
+          events_filter={
+            'access_key'=>@access_key_self['id'],
+            'type'=>'download.ended'
+          }
+          # optionally by iteration token
+          events_filter['iteration_token']=iteration_token unless iteration_token.nil?
+          events=@api_node.read('events',events_filter)[:data]
+          return if events.empty?
+          events.each do |event|
+            next unless event['data']['direction'].eql?('receive')
+            next unless event['data']['status'].eql?('completed')
+            next unless event['data']['error_code'].eql?(0)
+            next unless event['data'].dig('tags','aspera',PREV_GEN_TAG).nil?
+            folder_id=event.dig('data','tags','aspera','node','file_id')
+            folder_id||=event.dig('data','file_id')
+            next if folder_id.nil?
+            folder_entry=@api_node.read("files/#{folder_id}")[:data] rescue nil
+            next if folder_entry.nil?
+            scan_folder_files(folder_entry)
+          end
+          return events.last['id'].to_s
+        end
+
+        # requests recent events on node api and process newly modified folders
+        def process_file_events(iteration_token)
+          # get new file creation by access key (TODO: what if file already existed?)
+          events_filter={
+            'access_key'=>@access_key_self['id'],
+            'type'=>'file.*'
+          }
+          # and optionally by iteration token
+          events_filter['iteration_token']=iteration_token unless iteration_token.nil?
+          events=@api_node.read('events',events_filter)[:data]
+          return if events.empty?
+          events.each do |event|
+            # process only files
+            next unless event.dig('data','type').eql?('file')
+            file_entry=@api_node.read("files/#{event['data']['id']}")[:data] rescue nil
+            next if file_entry.nil?
+            next unless @option_skip_folders.select{|d|file_entry['path'].start_with?(d)}.empty?
+            file_entry['parent_file_id']=event['data']['parent_file_id']
+            if event['types'].include?('file.deleted')
+              Log.log.error('TODO'.red)
+            end
+            if event['types'].include?('file.deleted')
+              generate_preview(file_entry)
+            end
+          end
+          # write new iteration file
+          return events.last['id'].to_s
+        end
+
+        def do_transfer(direction,folder_id,source_filename,destination='/')
+          raise "error" if destination.nil? and direction.eql?('receive')
+          if @default_transfer_spec.nil?
+            # make a dummy call to get some default transfer parameters
+            res=@api_node.create('files/upload_setup',{'transfer_requests'=>[{'transfer_request'=>{'paths'=>[{}],'destination_root'=>'/'}}]})
+            sample_transfer_spec=res[:data]['transfer_specs'].first['transfer_spec']
+            # get ports, anyway that should be 33001 for both. add remote_user ?
+            @default_transfer_spec=['ssh_port','fasp_port'].inject({}){|h,e|h[e]=sample_transfer_spec[e];h}
+            # note: we use the same address for ascp than for node api instead of the one from upload_setup
+            @default_transfer_spec.merge!({
+              'token'            => "Basic #{Base64.strict_encode64("#{@access_key_self['id']}:#{self.options.get_option(:password,:mandatory)}")}",
+              'remote_host'      => @transfer_server_address,
+              'remote_user'      => Fasp::ACCESS_KEY_TRANSFER_USER
+            })
+          end
+          tspec=@default_transfer_spec.merge({
+            'direction'  => direction,
+            'paths'      => [{'source'=>source_filename}],
+            'tags'       => { 'aspera' => {
+            PREV_GEN_TAG   => true,
+            'node'         => {
+            'access_key'     => @access_key_self['id'],
+            'file_id'        => folder_id }}}
+          })
+          # force destination
+          # tspec['destination_root']=destination
+          self.transfer.option_transfer_spec_deep_merge({'destination_root'=>destination})
+          Main.result_transfer(self.transfer.start(tspec,{:src=>:node_gen4}))
+        end
+
+        def get_infos_local(gen_infos,entry,local_entry_preview_dir)
+          local_original_filepath=File.join(@local_storage_root,entry['path'])
+          original_mtime=File.mtime(local_original_filepath)
+          # out
+          local_entry_preview_dir.replace(File.join(@local_preview_folder, entry_preview_folder_name(entry)))
+          gen_infos.each do |gen_info|
+            gen_info[:src]=local_original_filepath
+            gen_info[:dst]=File.join(local_entry_preview_dir, gen_info[:base_dest])
+            gen_info[:preview_exist]=File.exist?(gen_info[:dst])
+            gen_info[:preview_newer_than_original] = (gen_info[:preview_exist] and (File.mtime(gen_info[:dst])>original_mtime))
+          end
+        end
+
+        def get_infos_remote(gen_infos,entry,local_entry_preview_dir)
+          #Log.log.debug(">>>> get_infos_remote #{entry}".red)
+          # store source directly here
+          local_original_filepath=File.join(@tmp_folder,entry['name'])
+          #original_mtime=DateTime.parse(entry['modified_time'])
+          # out: where previews are generated
+          local_entry_preview_dir.replace(File.join(@tmp_folder,entry_preview_folder_name(entry)))
+          file_info=@api_node.read("files/#{entry['id']}")[:data]
+          #TODO: this does not work because previews is hidden in api (gen4)
+          #this_preview_folder_entries=get_folder_entries(@previews_folder_entry['id'],{:name=>@entry_preview_folder_name})
+          # TODO: use gen3 api to list files and get date
+          gen_infos.each do |gen_info|
+            gen_info[:src]=local_original_filepath
+            gen_info[:dst]=File.join(local_entry_preview_dir, gen_info[:base_dest])
+            # TODO: use this_preview_folder_entries (but it's hidden)
+            gen_info[:preview_exist]=file_info.has_key?('preview')
+            # TODO: get change time and compare, useful ?
+            gen_info[:preview_newer_than_original] = gen_info[:preview_exist]
+          end
+        end
+
+        # defined by node api
+        def entry_preview_folder_name(entry)
+          "#{entry['id']}#{PREVIEW_FOLDER_SUFFIX}"
+        end
+
+        def preview_filename(preview_format,filename=nil)
+          filename||=PREVIEW_BASENAME
+          return "#{filename}.#{preview_format.to_s}"
+        end
+
+        # generate preview files for one folder entry (file) if necessary
+        # entry must contain "parent_file_id" if remote.
+        def generate_preview(entry)
+          #Log.log.debug(">>>> #{entry}".red)
+          # folder where previews will be generated for this particular entry
+          local_entry_preview_dir=String.new
+          # prepare generic information
+          gen_infos=@preview_formats_to_generate.map do |preview_format|
+            {
+              :preview_format => preview_format,
+              :base_dest      => preview_filename(preview_format)
+            }
+          end
+          # lets gather some infos on possibly existing previews
+          # it depends if files access locally or remotely
+          if @access_remote
+            get_infos_remote(gen_infos,entry,local_entry_preview_dir)
+          else # direct local file system access
+            get_infos_local(gen_infos,entry,local_entry_preview_dir)
+          end
+          # here we have the status on preview files
+          # let's find if they need generation
+          gen_infos.select! do |gen_info|
+            # if it exists, what about overwrite policy ?
+            if gen_info[:preview_exist]
+              case @option_overwrite
+              when :always
+                # continue: generate
+              when :never
+                # never overwrite
+                next false
+              when :mtime
+                # skip if preview is newer than original
+                next false if gen_info[:preview_newer_than_original]
+              end
+            end
+            # need generator for further checks
+            gen_info[:generator]=Aspera::Preview::Generator.new(@gen_options,gen_info[:src],gen_info[:dst],@tmp_folder,entry['content_type'],false)
+            # get conversion_type (if known) and check if supported
+            next false unless gen_info[:generator].supported?
+            # shall we skip it ?
+            next false if @skip_types.include?(gen_info[:generator].conversion_type)
+            # ok we need to generate
+            true
+          end
+          return if gen_infos.empty?
+          # create folder if needed
+          FileUtils.mkdir_p(local_entry_preview_dir)
+          if @access_remote
+            raise 'missing parent_file_id in entry' if entry['parent_file_id'].nil?
+            #  download original file to temp folder
+            do_transfer('receive',entry['parent_file_id'],entry['name'],@tmp_folder)
+          end
+          Log.log.info("source: #{entry['id']}: #{entry['path']})")
+          gen_infos.each do |gen_info|
+            gen_info[:generator].generate rescue nil
+          end
+          if @access_remote
+            # upload
+            do_transfer('send',@previews_folder_entry['id'],local_entry_preview_dir)
+            # cleanup after upload
+            FileUtils.rm_rf(local_entry_preview_dir)
+            File.delete(File.join(@tmp_folder,entry['name']))
+          end
+          # force read file updated previews
+          if @option_folder_reset_cache.eql?(:read)
+            @api_node.read("files/#{entry['id']}")
+          end
+        rescue => e
+          Log.log.error("#{e.message}")
+          Log.log.debug(e.backtrace.join("\n").red)
+        end # generate_preview
+
+        # scan all files in provided folder entry
+        def scan_folder_files(top_entry,scan_start=nil)
+          if !scan_start.nil?
+            # canonical path: start with / and ends with /
+            scan_start='/'+scan_start.split('/').select{|i|!i.empty?}.join('/')
+            scan_start="#{scan_start}/" #unless scan_start.end_with?('/')
+          end
+          Log.log.debug("scan: #{top_entry} : #{scan_start}".green)
+          # don't use recursive call, use list instead
+          entries_to_process=[top_entry]
+          while !entries_to_process.empty?
+            entry=entries_to_process.shift
+            # process this entry only if it is within the scan_start
+            entry_path_with_slash=entry['path']
+            entry_path_with_slash="#{entry_path_with_slash}/" unless entry_path_with_slash.end_with?('/')
+            if !scan_start.nil? and !scan_start.start_with?(entry_path_with_slash) and !entry_path_with_slash.start_with?(scan_start)
+              Log.log.debug("#{entry['path']} folder (skip start)".bg_red)
+              next
+            end
+            Log.log.debug("item:#{entry}")
+            case entry['type']
+            when 'file'
+              generate_preview(entry)
+            when 'link'
+              Log.log.debug('Ignoring link.')
+            when 'folder'
+              if @option_skip_folders.include?(entry['path'])
+                Log.log.debug("#{entry['path']} folder (skip list)".bg_red)
+              else
+                Log.log.debug("#{entry['path']} folder".green)
+                # get folder content
+                folder_entries=get_folder_entries(entry['id'])
+                # process all items in current folder
+                folder_entries.each do |folder_entry|
+                  # add path for older versions of ES
+                  if !folder_entry.has_key?('path')
+                    folder_entry['path']=entry_path_with_slash+folder_entry['name']
+                  end
+                  folder_entry['parent_file_id']=entry['id']
+                  entries_to_process.push(folder_entry)
+                end
+              end
+            else
+              Log.log.warn("unknown entry type: #{entry['type']}")
+            end
+          end
+        end
+
+        def execute_action
+          command=self.options.get_next_command(ACTIONS)
+          unless [:check,:test].include?(command)
+            # this will use node api
+            @api_node=basic_auth_api
+            @transfer_server_address=URI.parse(@api_node.params[:base_url]).host
+            # get current access key
+            @access_key_self=@api_node.read('access_keys/self')[:data]
+            # TODO: check events is activated here:
+            # note that docroot is good to look at as well
+            node_info=@api_node.read('info')[:data]
+            Log.log.debug("root: #{node_info['docroot']}")
+            @access_remote=@option_file_access.eql?(:remote)
+            Log.log.debug("remote: #{@access_remote}")
+            Log.log.debug("access key info: #{@access_key_self}")
+            #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=get_folder_entries(@access_key_self['root_file_id'],{:name=>@option_previews_folder}).first
+              raise CliError,"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
+              raise "only local storage allowed in this mode" unless @access_key_self['storage']['type'].eql?('local')
+              @local_storage_root=@access_key_self['storage']['path']
+              #TODO: option to override @local_storage_root='xxx'
+              @local_storage_root=@local_storage_root[LOCAL_STORAGE_PCVL.length..-1] if @local_storage_root.start_with?(LOCAL_STORAGE_PCVL)
+              #TODO: windows could have "C:" ?
+              raise "not local storage: #{@local_storage_root}" unless @local_storage_root.start_with?('/')
+              raise CliError,"Local storage root folder #{@local_storage_root} does not exist." unless File.directory?(@local_storage_root)
+              @local_preview_folder=File.join(@local_storage_root,@option_previews_folder)
+              raise CliError,"Folder #{@local_preview_folder} does not exist locally. Please create it, or specify an alternate name." unless File.directory?(@local_preview_folder)
+              # 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)
+                raise "mismatch access key in #{marker_file}: contains #{ak}, using #{@access_key_self['id']}" unless @access_key_self['id'].eql?(ak)
+              else
+                File.write(marker_file,@access_key_self['id'])
+              end
+            end
+          end
+          case command
+          when :scan
+            scan_path=self.options.get_option(:scan_path,:optional)
+            scan_id=self.options.get_option(:scan_id,:optional)
+            # 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}")[:data]
+            end
+            scan_folder_files(folder_info,scan_path)
+            return Main.result_status('scan finished')
+          when :events
+            iteration_data=[]
+            iteration_persistency=nil
+            if self.options.get_option(:once_only,:mandatory)
+              iteration_persistency=PersistencyActionOnce.new(
+              manager: @agents[:persistency],
+              data: iteration_data,
+              ids:  ['preview_iteration_events',self.options.get_option(:url,:mandatory),self.options.get_option(:username,:mandatory)])
+            end
+            iteration_data[0]=process_file_events(iteration_data[0])
+            iteration_persistency.save unless iteration_persistency.nil?
+            return Main.result_status('events finished')
+          when :trevents
+            iteration_data=[]
+            iteration_persistency=nil
+            if self.options.get_option(:once_only,:mandatory)
+              iteration_persistency=PersistencyActionOnce.new(
+              manager: @agents[:persistency],
+              data: iteration_data,
+              ids:  ['preview_iteration_transfer',self.options.get_option(:url,:mandatory),self.options.get_option(:username,:mandatory)])
+            end
+            iteration_data[0]=process_transfer_events(iteration_data[0])
+            iteration_persistency.save unless iteration_persistency.nil?
+            return Main.result_status('trevents finished')
+          when :check
+            Aspera::Preview::Utils.check_tools(@skip_types)
+            return Main.result_status('tools validated')
+          when :test
+            format = self.options.get_next_argument('format',Aspera::Preview::Generator::PREVIEW_FORMATS)
+            source = self.options.get_next_argument('source file')
+            dest=preview_filename(format,self.options.get_option(:case,:optional))
+            g=Aspera::Preview::Generator.new(@gen_options,source,dest,@tmp_folder)
+            raise "format not supported: #{format}" unless g.supported?
+            g.generate
+            return Main.result_status("generated: #{dest}")
+          else
+            raise "error"
+          end
+        ensure
+          FileUtils.rm_rf(@tmp_folder)
+        end # execute_action
+      end # Preview
+    end # Plugins
+  end # Cli
+end # Aspera