aspera-cli 4.26.2 → 4.27.1

data/lib/aspera/cli/secret_finder.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'aspera/log'
+
+module Aspera
+  module Cli
+    # Resolves the secret (password) for a given URL + username pair.
+    # Injected into Context as :secret_finder so that any component
+    # (plugins, Api::AoC, ...) can look up secrets without going through Plugins::Config.
+    class SecretFinder
+      # Special value for the :secret option that triggers a preset lookup
+      PRESET_MAGIC = 'PRESET'
+
+      # @param options [Parser]       CLI options manager (provides :secret)
+      # @param presets [PresetManager] preset resolver (provides #lookup_preset)
+      def initialize(options, presets)
+        @options = options
+        @presets = presets
+      end
+
+      # Return the secret for the given URL + username.
+      # If the :secret option equals 'PRESET', the preset store is searched for a
+      # matching url/username entry and its 'password' field is returned.
+      # @param url      [String]
+      # @param username [String]
+      # @return [String, nil]
+      def lookup(url:, username:)
+        secret = @options.get_option(:secret)
+        if secret.eql?(PRESET_MAGIC)
+          conf = @presets.lookup_preset(url: url, username: username)
+          if conf.is_a?(Hash)
+            Log.log.debug { "Found preset #{conf} with URL and username" }
+            secret = conf['password']
+          end
+        end
+        secret
+      end
+    end
+  end
+end

data/lib/aspera/cli/special_values.rb

@@ -9,6 +9,7 @@ module Aspera
       ALL = 'ALL'
       DEF = 'DEF'
       EOA = 'END'
+      LATEST = 'LATEST'
     end
   end
 end

data/lib/aspera/cli/sync_actions.rb

@@ -7,28 +7,51 @@ require 'pathname'
 
 module Aspera
   module Cli
-    # Manage command line arguments to provide to Sync::Operations and Sync::Database
+    # Helpers shared by plugins that expose Aspera Sync (async) operations.
+    # Provides DSL registration, argument-to-sync-info conversion, and action methods.
     module SyncActions
       # Translate state id (int) to string
       STATE_STR = (['Nil'] +
-        (1..18).map{ |i| "P(#{i})"} +
+        (1..18).map { |i| "P(#{i})" } +
         %w[Syncd Error Confl Pconf] +
-        (23..24).map{ |i| "P(#{i})"}).freeze
+        (23..24).map { |i| "P(#{i})" }).freeze
+      # Positional arguments shared by sync transfer commands (push/pull/bidi) and sync admin commands.
+      PATH_AND_INFO_ARGS = [{name: :path, type: String}, {name: :sync_info, type: Hash, mandatory: false, default: {}}].freeze
+      # Names of the leaf commands registered under any `sync admin` node.
+      ADMIN_COMMANDS = %i[find status meta counters file_info overview query].freeze
+      # When a plugin class includes SyncActions, register the :sql option
+      # in that class's DSL registry so Base#initialize auto-declares it.
       class << self
-        def declare_options(options)
-          options.declare(:sql, 'SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)')
+        def included(base)
+          base.option(:sql, description: 'SQL suffix appended to sqlite3 queries for admin subcommands (e.g. WHERE clause)')
+        end
+
+        # DSL helper: register the 7 `sync admin` leaf commands under the given parent path.
+        # Called at class-load time from any plugin that includes SyncActions.
+        # @param base        [Class]          the plugin class (receiver of DSL methods)
+        # @param admin_path  [Symbol, Array<Symbol>]  path relative to current scope, e.g. :admin
+        def register_sync_admin_commands(base, admin_path)
+          base.commands_under(admin_path) do
+            base.command(:find,      description: 'Find sync database files',     arguments: [{name: :path, type: String}], action: :action_sync_admin_find)
+            base.command(:status,    description: 'Show sync session status',     arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_status)
+            base.command(:meta,      description: 'Show sync session metadata',   arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_meta)
+            base.command(:counters,  description: 'Show sync counters',           arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_counters)
+            base.command(:file_info, description: 'Show per-file sync state',     arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_file_info)
+            base.command(:overview,  description: 'Show sync database overview',  arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_overview)
+            base.command(:query,     description: 'Execute a raw SQL query',      arguments: PATH_AND_INFO_ARGS, action: :action_sync_admin_query)
+          end
         end
       end
 
-      # Read 1 or 2 command line arguments and converts to `sync_info` format
+      # Convert path + sync_info to internal `sync_info` format.
       # The resulting sync_info has `args` format only if it contains one of the `sessions` or `instance` keys.
       # It has the `conf` format (default) otherwise.
       # If the `conf` format is detected, then both `local` and `remote` keys are set.
-      # @param direction [Symbol,NilClass] One of directions, or `nil` if only for admin command
+      # @param path      [String]          local/remote path
+      # @param sync_info [Hash]            extra sync info (may be empty)
+      # @param direction [Symbol,NilClass] one of DIRECTIONS, or nil for admin commands
       # @return [Hash] sync info
-      def async_info_from_args(direction: nil)
-        path = options.get_next_argument('path')
-        sync_info = options.get_next_argument('sync info', mandatory: false, validation: Hash, default: {}, schema: Schema::Registry::SYNC_CONF)
+      def async_info_from_args(path:, sync_info: {}, direction: nil)
         # is the positional path a remote path ?
         path_is_remote = direction.eql?(:pull)
         if sync_info.key?('sessions') || sync_info.key?('instance')
@@ -37,33 +60,33 @@ module Aspera
           Aspera.assert(sync_info['sessions'].length == 1, 'Only one session is supported')
           session = sync_info['sessions'].first
           dir_key = path_is_remote ? 'remote_dir' : 'local_dir'
-          raise "Parameter #{dir_key} shall not be in sync_info" if session.key?(dir_key)
+          Aspera.assert(!session.key?(dir_key)) { "Parameter #{dir_key} shall not be in sync_info" }
           session[dir_key] = path
           if direction
             dir_key = path_is_remote ? 'local_dir' : 'remote_dir'
-            raise "Parameter #{dir_key} shall not be in sync_info" if session.key?(dir_key)
+            Aspera.assert(!session.key?(dir_key)) { "Parameter #{dir_key} shall not be in sync_info" }
             session[dir_key] = transfer.destination_folder(path_is_remote ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND)
-            local_remote = %w[local remote].map{ |i| session["#{i}_dir"]}
+            local_remote = %w[local remote].map { |i| session["#{i}_dir"] }
           end
         else
           # `conf`
           session = sync_info
           dir_key = path_is_remote ? 'remote' : 'local'
           session[dir_key] ||= {}
-          raise "Parameter #{dir_key}.path shall not be in sync_info" if session[dir_key].key?('path')
+          Aspera.assert(!session[dir_key].key?('path')) { "Parameter #{dir_key}.path shall not be in sync_info" }
           session[dir_key]['path'] = path
           if direction
             dir_key = path_is_remote ? 'local' : 'remote'
             session[dir_key] ||= {}
-            raise "Parameter #{dir_key}.path shall not be in sync_info" if session[dir_key].key?('path')
+            Aspera.assert(!session[dir_key].key?('path')) { "Parameter #{dir_key}.path shall not be in sync_info" }
             session[dir_key]['path'] = transfer.destination_folder(path_is_remote ? Transfer::Spec::DIRECTION_RECEIVE : Transfer::Spec::DIRECTION_SEND)
-            local_remote = %w[local remote].map{ |i| session[i]['path']}
+            local_remote = %w[local remote].map { |i| session[i]['path'] }
           end
           # `conf` is quiet by default
           session['quiet'] = false if !session.key?('quiet') && Environment.terminal?
         end
         if direction
-          raise BadArgument, 'direction shall not be in sync_info' if session.key?('direction')
+          Aspera.assert(!session.key?('direction'), type: BadArgument) { 'direction shall not be in sync_info' }
           session['direction'] = direction.to_s
           # generate name if not provided by user
           if !session.key?('name')
@@ -80,66 +103,68 @@ module Aspera
         sync_info
       end
 
-      # Provide database object from command line arguments for admin ops
-      def db_from_args
-        sync_info = async_info_from_args
+      # Provide database object from path + sync_info for admin ops
+      # @param path      [String] local path
+      # @param sync_info [Hash]   extra sync info (may be empty)
+      def db_from_args(path:, sync_info: {})
+        sync_info = async_info_from_args(path: path, sync_info: sync_info)
         session = sync_info.key?('sessions') ? sync_info['sessions'].first : sync_info
         # if name not provided, check in db folder if there is only one name
         if !session.key?('name')
           local_db_dir = Sync::Operations.local_db_folder(sync_info)
           dbs = Sync::Operations.list_db_files(local_db_dir)
-          raise "#{dbs.length} session found in #{local_db_dir}, please provide a name" unless dbs.length == 1
+          Aspera.assert(dbs.length == 1) { "#{dbs.length} session found in #{local_db_dir}, please provide a name" }
           session['name'] = dbs.keys.first
         end
         Sync::Database.new(Sync::Operations.session_db_file(sync_info))
       end
 
-      def execute_sync_admin
-        command2 = options.get_next_command(%i[status find meta counters file_info overview query])
-        require 'aspera/sync/database' unless command2.eql?(:status)
-        sql_suffix = options.get_option(:sql)
-        case command2
-        when :status
-          return Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args))
-        when :find
-          folder = options.get_next_argument('path')
-          dbs = Sync::Operations.list_db_files(folder)
-          return Result::ObjectList.new(dbs.keys.map{ |n| {name: n, path: dbs[n]}})
-        when :meta, :counters
-          return Result::SingleObject.new(db_from_args.send(command2, sql_suffix))
-        when :file_info
-          result = db_from_args.file_info(sql_suffix)
-          result.each do |r|
-            r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
-          end
-          return Result::ObjectList.new(
-            result,
-            fields: %w[sstate record_id f_meta_path message]
-          )
-        when :overview
-          return Result::ObjectList.new(
-            db_from_args.overview,
-            fields: %w[table name type]
-          )
-        when :query
-          return Result.auto(db_from_args.execute(options.get_option(:sql, mandatory: true)))
-        else Aspera.error_unexpected_value(command2)
-        end
+      def action_sync_admin_status(path:, sync_info: {}, **)
+        Result::SingleObject.new(Sync::Operations.admin_status(async_info_from_args(path: path, sync_info: sync_info)))
+      end
+
+      def action_sync_admin_find(path:, **)
+        dbs = Sync::Operations.list_db_files(path)
+        Result::ObjectList.new(dbs.keys.map { |n| {name: n, path: dbs[n]} })
+      end
+
+      def action_sync_admin_meta(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).meta(options.get_option(:sql)))
       end
 
-      # Execute sync action
-      # @param &block [nil, Proc] block to generate transfer spec, takes: `direction` (one of DIRECTIONS), `local_dir`, `remote_dir`
-      def execute_sync_action(&block)
-        command = options.get_next_command(%i[admin] + Sync::Operations::DIRECTIONS)
-        # try to get 3 arguments as simple arguments
-        case command
-        when *Sync::Operations::DIRECTIONS
-          Sync::Operations.start(async_info_from_args(direction: command), transfer.user_transfer_spec, &block)
-          return Result::Success.new
-        when :admin
-          return execute_sync_admin
-        else Aspera.error_unexpected_value(command)
+      def action_sync_admin_counters(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::SingleObject.new(db_from_args(path: path, sync_info: sync_info).counters(options.get_option(:sql)))
+      end
+
+      def action_sync_admin_file_info(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        result = db_from_args(path: path, sync_info: sync_info).file_info(options.get_option(:sql))
+        result.each do |r|
+          r['sstate'] = SyncActions::STATE_STR[r['state']] if r['state']
         end
+        Result::ObjectList.new(result, fields: %w[sstate record_id f_meta_path message])
+      end
+
+      def action_sync_admin_overview(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result::ObjectList.new(db_from_args(path: path, sync_info: sync_info).overview, fields: %w[table name type])
+      end
+
+      def action_sync_admin_query(path:, sync_info: {}, **)
+        require 'aspera/sync/database'
+        Result.auto(db_from_args(path: path, sync_info: sync_info).execute(options.get_option(:sql, mandatory: true)))
+      end
+
+      # Execute a sync transfer for a given direction.
+      # @param direction [Symbol]    one of Sync::Operations::DIRECTIONS (:push, :pull, :bidi)
+      # @param path      [String]    local or remote path (depends on direction)
+      # @param sync_info [Hash]      extra sync configuration (may be empty)
+      # @param block     [Proc, nil] block to generate transfer spec; receives (direction, local_dir, remote_dir)
+      def run_sync_transfer(direction, path:, sync_info: {}, &block)
+        Sync::Operations.start(async_info_from_args(path: path, sync_info: sync_info, direction: direction), transfer.user_transfer_spec, &block)
+        Result::Success.new
       end
     end
   end

data/lib/aspera/cli/terminal_formatter.rb

@@ -14,7 +14,7 @@ module Aspera
       HINT = 'HINT:'.bg_green.gray.blink.freeze
       include FormatterInterface
 
-      # Format boolean with colored symbol (✓/✗ or Y/ )
+      # Format boolean with colored symbol (+/- or Y/ )
       def tick(yes)
         result =
           if Environment.terminal_supports_unicode?
@@ -29,13 +29,13 @@ module Aspera
       # Format special values with colors (dim for empty, reverse for others)
       def special_format(what)
         result = "<#{what}>"
-        return %w[null empty].any?{ |s| what.include?(s)} ? result.dim : result.reverse_color
+        return %w[null empty].any? { |s| what.include?(s) } ? result.dim : result.reverse_color
       end
 
       # Prepare table row for terminal display (word wrap arrays)
       def check_row(row)
         row.each_key do |k|
-          row[k] = row[k].map{ |i| WordWrap.ww(i.to_s, 120).chomp}.join("\n") if row[k].is_a?(Array)
+          row[k] = row[k].map { |i| WordWrap.ww(i.to_s, 120).chomp }.join("\n") if row[k].is_a?(Array)
         end
       end
 

data/lib/aspera/cli/transfer_actions.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/async_transfer_store'
+require 'aspera/agent/factory'
+require 'aspera/log'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Mixin for Config plugin: async transfer management actions.
+    # Exposes three sub-commands under `config transfer`:
+    #   status  --id=<job_id>   Re-query a running/completed transfer
+    #   list                    List all persisted async transfer entries
+    #   cleanup                 Remove completed/failed/cancelled entries
+    #
+    # Architecture:
+    #   - remote-daemon agents (desktop, node, connect, transferd): transfer_id + agent_params
+    #     are persisted in AsyncTransferStore; status is re-queried via Agent::Xxx.transfer_status
+    #   - direct agent: transfers live in Ruby threads - store is the agent's @sessions;
+    #     status is not persistable across process restarts (returns an informational message)
+    module TransferActions
+      # Re-query the status of a single async transfer job.
+      # @param job_id [String] UUID returned at submission time
+      def action_transfer_status(job_id:, **)
+        store = async_transfer_store
+        entry = store.read(job_id)
+        Aspera.assert(!entry.nil?, type: Cli::BadArgument) { "Unknown job_id: #{job_id}" }
+        # Inject the in-process agent reference (direct/httpgw) if still alive in this process.
+        ref = store.agent_ref(job_id)
+        entry['agent_params']['_agent_ref'] = ref if ref
+        live = query_live_status(entry)
+        if live
+          entry.merge!(live)
+          store.write(job_id, entry)
+        end
+        Result::SingleObject.new(entry)
+      end
+
+      # List all persisted async transfer entries.
+      def action_transfer_list(**)
+        rows = async_transfer_store.list
+        Result::ObjectList.new(rows, fields: %w[job_id agent_type status started_at ended_at bytes_transferred transfer_id])
+      end
+
+      TERMINAL_STATUSES = %w[completed failed cancelled].freeze
+      private_constant :TERMINAL_STATUSES
+
+      # Delete completed, failed, and cancelled entries from the store.
+      def action_transfer_cleanup(**)
+        store = async_transfer_store
+        deleted = store.list
+          .select { |e| TERMINAL_STATUSES.include?(e['status']) }
+          .map do |e|
+          store.delete(e['job_id'])
+          e['job_id']
+        end
+        Result::Status.new("Deleted #{deleted.size} completed transfer(s)#{": #{deleted.join(', ')}" unless deleted.empty?}")
+      end
+
+      private
+
+      # Lazy accessor - requires context.persistency (available in all Base sub-classes).
+      # Delegate to the TransferAgent's store so that the in-memory agent-ref
+      # registry is shared between the two components in the same process.
+      def async_transfer_store
+        context.transfer.async_store
+      end
+
+      # Delegate to the appropriate agent class method.
+      # All agent types are supported:
+      # - in-process agents (direct, httpgw): re-queryable while the same process lives
+      #   (e.g. MCP mode); '_agent_ref' in agent_params points to the live instance.
+      #   When the process has restarted, '_agent_ref' is nil and transfer_status returns
+      #   {'status' => 'unknown'} — which is the correct and safe answer.
+      # - daemon agents (node, desktop, connect, transferd): re-query via their REST/IPC API.
+      def query_live_status(entry)
+        agent_type   = entry['agent_type']
+        transfer_id  = entry['transfer_id']
+        agent_params = entry['agent_params'] || {}
+
+        require "aspera/agent/#{agent_type}"
+        agent_class = Aspera::Agent.const_get(agent_type.capitalize)
+        agent_class.transfer_status(transfer_id, agent_params)
+      rescue StandardError => e
+        Log.log.warn { "Could not re-query #{entry['agent_type']} agent for job #{entry['job_id']}: #{e}" }
+        nil
+      end
+    end
+  end
+end