aspera-cli 4.26.0 → 4.26.2

data/lib/aspera/cli/context.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Global objects shared with plugins
+    class Context
+      # @type [Array<Symbol>]
+      MEMBERS = %i[options transfer config formatter persistency man_header presets http_config].freeze
+      # @!attribute [rw] options
+      #   @return [Manager] the command line options manager
+      # @!attribute [rw] transfer
+      #   @return [TransferAgent] the transfer agent, used by transfer plugins
+      # @!attribute [rw] config
+      #   @return [Plugins::Config] the configuration plugin, used by plugins to get configuration values and presets
+      # @!attribute [rw] formatter
+      #   @return [Formatter] the formatter, used by plugins to display results and messages
+      # @!attribute [rw] persistency
+      #   @return [Object] # whatever the type is
+      # @!attribute [rw] man_header
+      #   @return [Boolean] whether to display the manual header in plugin help
+      # @!attribute [rw] presets
+      #   @return [PresetManager] manages the YAML config file and preset resolution
+      # @!attribute [rw] http_config
+      #   @return [Http] manages HTTP/S and TLS runtime options
+      attr_accessor(*MEMBERS)
+
+      # Initialize all members to nil, so that they are defined and can be validated later
+      # @return [nil]
+      def initialize
+        MEMBERS.each{ |i| instance_variable_set(:"@#{i}", nil)}
+      end
+
+      # Validate that all members are set, raise exception if not
+      # @raise [Aspera::AssertionError] if any member is not set
+      # @return [nil]
+      def validate
+        MEMBERS.each do |i|
+          Aspera.assert(instance_variable_defined?(:"@#{i}")){"context member @#{i} is not defined"}
+          Aspera.assert(!instance_variable_get(:"@#{i}").nil?){"context member @#{i} is nil"}
+        end
+      end
+
+      # Check if the context is in manual-only mode
+      # @return [Boolean] true if in manual-only mode
+      def only_manual?
+        transfer.eql?(:only_manual)
+      end
+
+      # Set the context to manual-only mode
+      # @return [Symbol] :only_manual
+      def only_manual!
+        @transfer = :only_manual
+      end
+    end
+  end
+end

data/lib/aspera/cli/extended_value.rb

@@ -15,6 +15,10 @@ require 'singleton'
 module Aspera
   module Cli
     # Command line extended values
+    #
+    # @!method self.instance
+    #   Returns the singleton instance of ExtendedValue
+    #   @return [ExtendedValue] the singleton instance
     class ExtendedValue
       include Singleton
 
@@ -82,6 +86,7 @@ module Aspera
         # Base handlers
         # Other handlers can be set using `on`
         # e.g. `preset` is reader in config plugin
+        # @type [Hash{Symbol => Proc}]
         @handlers = {
           val:    lambda{ |i| i},
           base64: lambda{ |i| Base64.decode64(i)},
@@ -91,12 +96,12 @@ module Aspera
           uri:    lambda{ |i| UriReader.read(i)},
           json:   lambda{ |i| ExtendedValue.JSON_parse(i)},
           lines:  lambda{ |i| i.split("\n")},
-          list:   lambda{ |i| i[1..-1].split(i[0])},
+          list:   lambda{ |i| i[1..].split(i[0])},
           none:   lambda{ |i| ExtendedValue.assert_no_value(i, :none); nil}, # rubocop:disable Style/Semicolon
           path:   lambda{ |i| File.expand_path(i)},
           re:     lambda{ |i| Regexp.new(i, Regexp::MULTILINE)},
           ruby:   lambda{ |i| Environment.secure_eval(i, __FILE__, __LINE__)},
-          s:      lambda{ |i| i.to_s},
+          s:      lambda(&:to_s),
           secret: lambda{ |i| prompt = i.empty? ? 'secret' : i; $stdin.getpass("#{prompt}> ")}, # rubocop:disable Style/Semicolon
           stdin:  lambda{ |i| ExtendedValue.read_stdin(i)},
           yaml:   lambda{ |i| YAML.load(i)},
@@ -133,7 +138,7 @@ module Aspera
       # Add a new handler
       def on(name, &block)
         Aspera.assert_type(name, Symbol){'name'}
-        Aspera.assert(block)
+        Aspera.assert(block){"block required when registering handler for #{name}"}
         Log.log.debug{"Setting handler for #{name}"}
         @handlers[name] = block
         update_regex
@@ -145,7 +150,7 @@ module Aspera
       # @param value   [String] the value to parse
       # @param context [String] Context in which evaluation is done
       # @param allowed [Array<Class>,NilClass] Expected types
-      # @return [Object] Evaluated value
+      # @return [String, Integer, Array, Hash, Boolean] Evaluated value
       def evaluate(value, context:, allowed: nil)
         return value unless value.is_a?(String)
         Aspera.assert_array_all(allowed, Class) unless allowed.nil?

data/lib/aspera/cli/formatter.rb

@@ -2,6 +2,7 @@
 
 # cspell:ignore jsonpp
 require 'aspera/cli/special_values'
+require 'aspera/cli/terminal_formatter'
 require 'aspera/preview/terminal'
 require 'aspera/secret_hider'
 require 'aspera/environment'
@@ -20,70 +21,7 @@ module Aspera
   module Cli
     # Take care of CLI output on terminal
     class Formatter
-      # remove a fields from the list
-      FIELDS_LESS = '-'
-      # supported output formats
-      DISPLAY_FORMATS = %i[text nagios ruby json jsonpp yaml table csv image].freeze
-      # user output levels
-      DISPLAY_LEVELS = %i[info data error].freeze
-      # column names for single object display in table
-      SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
-      # Terminal: vertical separator for list of strings.
-      STR_LST_SEP_VERT = "\n"
-
-      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
-
       class << self
-        # nicer display for boolean
-        # used by `spec_doc`
-        def tick(yes)
-          result =
-            if Environment.terminal_supports_unicode?
-              yes ? "\u2713" : "\u2717"
-            else
-              yes ? 'Y' : ' '
-            end
-          return result.green if yes
-          return result.red
-        end
-
-        # Highlight special values on terminal
-        # empty values are dim
-        # used by `spec_doc`
-        def special_format(what)
-          result = "<#{what}>"
-          return %w[null empty].any?{ |s| what.include?(s)} ? result.dim : result.reverse_color
-        end
-
-        # For transfer spec table, build line for display in terminal
-        # used by `spec_doc`
-        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)
-          end
-        end
-
-        # Give Markdown String, or matched data, return formatted string for terminal
-        # used by `spec_doc`
-        # @param match [MatchData,String]
-        def markdown_text(match)
-          if match.is_a?(String)
-            match = Markdown::FORMATS.match(match)
-            Aspera.assert(match)
-          end
-          Aspera.assert_type(match, MatchData)
-          if match[:entity]
-            Aspera.assert_values(match[:entity], 'bsol')
-            '\\'
-          elsif match[:bold]
-            match[:bold].to_s.blue
-          elsif match[:code]
-            match[:code].to_s.bold
-          else
-            Aspera.error_unexpected_value(match.to_s)
-          end
-        end
-
         # Replace special values with a readable version on terminal
         def replace_specific_for_terminal(input_hash, string_list_separator)
           hash_to_process = [input_hash]
@@ -92,14 +30,14 @@ module Aspera
             current.each do |key, value|
               case value
               when NilClass
-                current[key] = special_format('null')
+                current[key] = TerminalFormatter.special_format('null')
               when String
-                current[key] = special_format('empty string') if value.empty?
+                current[key] = TerminalFormatter.special_format('empty string') if value.empty?
               when Proc
-                current[key] = special_format('lambda')
+                current[key] = TerminalFormatter.special_format('lambda')
               when Array
                 if value.empty?
-                  current[key] = special_format('empty list')
+                  current[key] = TerminalFormatter.special_format('empty list')
                 elsif value.all?(String)
                   current[key] = value.join(string_list_separator)
                 else
@@ -109,7 +47,7 @@ module Aspera
                 end
               when Hash
                 if value.empty?
-                  current[key] = special_format('empty dict')
+                  current[key] = TerminalFormatter.special_format('empty dict')
                 else
                   hash_to_process.push(value)
                 end
@@ -129,6 +67,17 @@ module Aspera
         @spinner = nil
       end
 
+      # Display item count if total is provided
+      def display_item_count(count, total)
+        return if total.nil?
+        count = count.to_i
+        total = total.to_i
+        return if total.eql?(0) && count.eql?(0)
+        count_msg = "Items: #{count}/#{total}"
+        count_msg = count_msg.bg_red unless count.eql?(total)
+        display_status(count_msg)
+      end
+
       def long_operation(title = nil, action: :spin)
         return unless Environment.terminal?
         return if %i[error data].include?(@options[:display])
@@ -209,10 +158,16 @@ module Aspera
         nil
       end
 
-      # Main output method
-      # data: for requested data, not displayed if level==error
-      # info: additional info, displayed if level==info
-      # error: always displayed on stderr
+      # Main output method for displaying messages to the user
+      # This method is used by Result classes to output formatted data
+      # @param message_level [Symbol] The level of the message - must be one of: :data, :info, :error
+      # @param message [String] The message to display
+      # @param hide_secrets [Boolean] Whether to hide secrets in the message (default: true)
+      # @return [void]
+      # @note Message display behavior depends on the message_level:
+      #   - +:data+ messages are displayed unless display level is +:error+
+      #   - +:info+ messages are only displayed when display level is +:info+
+      #   - +:error+ messages are always displayed on stderr
       def display_message(message_level, message, hide_secrets: true)
         message = SecretHider.instance.hide_secrets_in_string(message) if hide_secrets && message.is_a?(String) && hide_secrets?
         case message_level
@@ -227,129 +182,65 @@ module Aspera
         display_message(:info, status, **kwargs)
       end
 
-      def display_item_count(number, total)
-        number = number.to_i
-        total = total.to_i
-        return if total.eql?(0) && number.eql?(0)
-        count_msg = "Items: #{number}/#{total}"
-        count_msg = count_msg.bg_red unless number.eql?(total)
-        display_status(count_msg)
-      end
-
+      # Check if secrets should be hidden
       def hide_secrets?
         !@options[:show_secrets] && !@options[:display].eql?(:data)
       end
 
-      # hides secrets in Hash or Array
+      # Hides secrets in Hash or Array
       def hide_secrets(data)
         SecretHider.instance.deep_remove_secret(data) if hide_secrets?
       end
 
-      # Display results, especially the table format
-      # @param type [Symbol] Type of data
-      # @param data [Object] Data to display
-      # @param fields [Array<String>] List of fields to display
-      # @param total [Integer] Total number of items
-      # @param name [String] Name of the column to display
-      def display_results(type:, data: nil, fields: nil, total: nil, name: nil)
-        Log.log.debug{"display_results: type=#{type}"}
-        Log.dump(:data, data, level: :trace1)
-        Log.dump(:fields, fields, level: :trace1)
-        Aspera.assert_type(type, Symbol){'result must have type'}
-        Aspera.assert(!data.nil? || %i[empty nothing].include?(type)){'result must have data'}
-        display_item_count(data.length, total) unless total.nil?
-        hide_secrets(data)
-        data = SecretHider.instance.hide_secrets_in_string(data) if data.is_a?(String) && hide_secrets?
-        @options[:format] = :image if type.eql?(:image)
-        case @options[:format]
-        when :text
-          display_message(:data, data.to_s)
-        when :nagios
-          Nagios.process(data)
-        when :ruby
-          display_message(:data, PP.pp(filter_list_on_fields(data), +''))
-        when :json
-          display_message(:data, JSON.generate(filter_list_on_fields(data)))
-        when :jsonpp
-          display_message(:data, JSON.pretty_generate(filter_list_on_fields(data)))
-        when :yaml
-          display_message(:data, YAML.dump(filter_list_on_fields(data)))
-        when :image
-          # if object or list, then must be a single
-          case type
-          when :single_object, :object_list
-            data = [data] if type.eql?(:single_object)
-            raise BadArgument, 'image display requires a single result' unless data.length == 1
-            fields = compute_fields(data, fields)
-            raise BadArgument, 'select a single field to display' unless fields.length == 1
-            data = data.first
-            raise BadArgument, 'no such field' unless data.key?(fields.first)
-            data = data[fields.first]
-          end
-          Aspera.assert_type(data, String){'URL or blob for image'}
-          # Check if URL
-          data =
-            begin
-              # just validate
-              URI.parse(data)
-              if Environment.instance.url_method.eql?(:text)
-                UriReader.read(data)
-              else
-                Environment.instance.open_uri(data)
-                display_message(:info, "Opened URL in browser: #{data}")
-                :done
-              end
-            rescue URI::InvalidURIError
-              data
-            end
-          # try base64
-          data = begin
-            Base64.strict_decode64(data)
-          rescue
-            data
-          end
-          # here, data is the image blob
-          display_message(:data, Preview::Terminal.build(data, **@options[:image].symbolize_keys)) unless data.eql?(:done)
-        when :table, :csv
-          case type
-          when :single_object
-            # :single_object is a Hash, where key=column name
-            Aspera.assert_type(data, Hash){'result'}
-            if data.empty?
-              display_message(:data, self.class.special_format('empty dict'))
-            else
-              data = DotContainer.new(data).to_dotted if @options[:flat_hash]
-              display_table([data], compute_fields([data], fields), single: true)
-            end
-          when :object_list
-            # :object_list is an Array of Hash, where key=column name
-            Aspera.assert_array_all(data, Hash){'result'}
-            data = data.map{ |obj| DotContainer.new(obj).to_dotted} if @options[:flat_hash]
-            display_table(data, compute_fields(data, fields), single: type.eql?(:single_object))
-          when :value_list
-            # :value_list is a simple array of values, name of column provided in `name`
-            display_table(data.map{ |i| {name => i}}, [name])
-          when :special # no table
-            if data.eql?(:nothing)
-              Log.log.debug('no result expected')
-              return
-            end
-            display_message(:info, self.class.special_format(data.to_s))
-            return
-          when :status # no table
-            # :status displays a simple message
-            display_message(:info, data)
-          when :text # no table
-            # :status displays a simple message
-            display_message(:data, data)
-          else Aspera.error_unexpected_value(type){'data type'}
-          end
-        else Aspera.error_unexpected_value(@options[:format]){'format'}
-        end
+      # Display results using the Visitor pattern
+      # Each Result subclass knows how to format itself by calling the appropriate
+      # formatter method, eliminating the need for type checking in the formatter.
+      # @param result [Result] Result object to display
+      def display_results(result)
+        require 'aspera/cli/result'
+        Aspera.assert_type(result, Cli::Result){'result must be a Result object'}
+
+        Log.log.debug{"display_results: result class=#{result.class.name}"}
+        Log.dump(:data, result.data, level: :trace1)
+        Log.dump(:fields, result.fields, level: :trace1)
+
+        # Hide secrets in data
+        hide_secrets(result.data)
+
+        # Use the Visitor pattern: delegate formatting to the result object
+        result.format(self)
       end
-      #==========================================================================================
+      # Public methods exposed to Result classes for formatting
 
-      private
+      # Get the current format type
+      def format_type
+        @options[:format]
+      end
+
+      # Set the format type (used by Image result)
+      def set_format_type(format)
+        @options[:format] = format
+      end
+
+      # Hide secrets in a string
+      def hide_secrets_in_string(string)
+        SecretHider.instance.hide_secrets_in_string(string)
+      end
+
+      # Get special format string
+      def special_format(text)
+        TerminalFormatter.special_format(text)
+      end
+
+      # Check if flat_hash option is enabled
+      def flat_hash?
+        @options[:flat_hash]
+      end
+
+      # Get image options
+      def image_options
+        @options[:image].symbolize_keys
+      end
 
       # @return all fields of all objects in list of objects
       def all_fields(data)
@@ -379,7 +270,7 @@ module Aspera
           removal = false
           if item[0].eql?(FIELDS_LESS)
             removal = true
-            item = item[1..-1]
+            item = item.delete_prefix(FIELDS_LESS)
           end
           case item
           when SpecialValues::ALL
@@ -439,7 +330,7 @@ module Aspera
         Aspera.assert_array_all(fields, String)
         if object_array.empty?
           # no  display for csv
-          display_message(:info, self.class.special_format('empty')) if @options[:format].eql?(:table)
+          display_message(:info, TerminalFormatter.special_format('empty')) if @options[:format].eql?(:table)
           return
         end
         filter_columns_on_select(object_array)
@@ -501,6 +392,19 @@ module Aspera
         end
         nil
       end
+
+      # remove a fields from the list
+      FIELDS_LESS = '-'
+      # supported output formats
+      DISPLAY_FORMATS = %i[text nagios ruby json jsonpp yaml table csv image].freeze
+      # user output levels
+      DISPLAY_LEVELS = %i[info data error].freeze
+      # column names for single object display in table
+      SINGLE_OBJECT_COLUMN_NAMES = %i[field value].freeze
+      # Terminal: vertical separator for list of strings.
+      STR_LST_SEP_VERT = "\n"
+
+      private_constant :FIELDS_LESS, :DISPLAY_FORMATS, :DISPLAY_LEVELS, :SINGLE_OBJECT_COLUMN_NAMES, :STR_LST_SEP_VERT
     end
   end
 end

data/lib/aspera/cli/http.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/special_values'
+require 'aspera/log'
+require 'aspera/assert'
+require 'aspera/line_logger'
+require 'openssl'
+
+module Aspera
+  module Cli
+    # Encapsulates all HTTP/S and TLS runtime configuration options.
+    # Extracted from Plugins::Config so it can be referenced independently
+    # via Context#http_config without coupling to the plugin machinery.
+    class Http
+      # Certificate file extensions recognized when scanning a folder
+      CERT_EXT = %w[crt cer pem der].freeze
+      # OpenSSL constant that disables peer verification (VERIFY_NONE)
+      SELF_SIGNED_CERT = OpenSSL::SSL.const_get(:enon_yfirev.to_s.upcase.reverse) # cspell: disable-line
+
+      private_constant :CERT_EXT, :SELF_SIGNED_CERT
+
+      def initialize
+        @insecure              = false
+        @warn_insecure         = true
+        @ignore_cert_host_port = []
+        @http_options          = {}
+        @ssl_warned_urls       = []
+        @certificate_store     = nil
+        @certificate_paths     = nil
+      end
+
+      attr_accessor :insecure, :warn_insecure, :http_options
+      attr_reader   :ignore_cert_host_port
+
+      # Declare all HTTP/S CLI options, with handlers pointing to self.
+      # Called once from Config#initialize after this object is instantiated.
+      # @param options [Aspera::Cli::Manager]
+      def declare_options(options)
+        options.declare(:insecure, 'HTTP/S: Do not validate any certificate', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :insecure}, default: false)
+        options.declare(:ignore_certificate, 'HTTP/S: Do not validate certificate for these URLs', allowed: [Array, NilClass], handler: {o: self, m: :ignore_cert_host_port})
+        options.declare(:warn_insecure, 'HTTP/S: Issue a warning if certificate is ignored', allowed: Allowed::TYPES_BOOLEAN, handler: {o: self, m: :warn_insecure}, default: true)
+        options.declare(:cert_stores, 'HTTP/S: List of folder with trusted certificates', allowed: Allowed::TYPES_STRING_ARRAY, handler: {o: self, m: :trusted_cert_locations})
+        options.declare(:http_options, 'HTTP/S: Options for HTTP/S socket', allowed: Hash, handler: {o: self, m: :http_options}, default: {})
+        options.declare(:http_proxy, 'HTTP/S: URL for proxy with optional credentials', handler: {o: self, m: :http_proxy})
+      end
+
+      # ------------------------------------------------------------------
+      # Proxy
+      # ------------------------------------------------------------------
+
+      def http_proxy
+        ENV['http_proxy']
+      end
+
+      def http_proxy=(value)
+        URI.parse(value)
+        ENV['http_proxy'] = value
+      end
+
+      # ------------------------------------------------------------------
+      # Per-URL certificate ignore list
+      # ------------------------------------------------------------------
+
+      def ignore_cert_host_port=(url_list)
+        url_list.each do |url|
+          uri = URI.parse(url)
+          raise "Expecting https scheme: #{url}" unless uri.scheme.eql?('https')
+          @ignore_cert_host_port.push([uri.host, uri.port].freeze)
+        end
+      end
+
+      # Should the certificate be ignored for this host/port?
+      # Also logs a warning the first time (if warn_insecure is set).
+      def ignore_cert?(address, port)
+        endpoint    = [address, port].freeze
+        ignore_cert = @insecure || @ignore_cert_host_port.any?(endpoint)
+        if ignore_cert && @warn_insecure
+          base_url = "https://#{address}:#{port}"
+          unless @ssl_warned_urls.include?(base_url)
+            Log.log.warn{"Ignoring certificate for: #{base_url}. Do not deactivate certificate verification in production."}
+            @ssl_warned_urls.push(base_url)
+          end
+        end
+        Log.log.debug{"ignore cert? #{endpoint} -> #{ignore_cert}"}
+        ignore_cert
+      end
+
+      # ------------------------------------------------------------------
+      # Trusted certificate store / paths
+      # ------------------------------------------------------------------
+
+      # Add files, folders or the default OS locations to the cert store.
+      # @param path_list [Array<String>]
+      def trusted_cert_locations=(path_list)
+        Aspera.assert_type(path_list, Array){'cert locations'}
+        if @certificate_store.nil?
+          Log.log.debug('Creating SSL Cert store')
+          @certificate_store = OpenSSL::X509::Store.new
+          @certificate_paths = []
+        end
+        path_list.each do |path|
+          Aspera.assert_type(path, String){'Expecting a String for certificate location'}
+          paths_to_add = [path]
+          Log.log.debug{"Adding cert location: #{path}"}
+          if path.eql?(SpecialValues::DEF)
+            @certificate_store.set_default_paths
+            paths_to_add = [OpenSSL::X509::DEFAULT_CERT_DIR]
+            paths_to_add.push(OpenSSL::X509::DEFAULT_CERT_FILE) unless defined?(JRUBY_VERSION)
+            paths_to_add.select!{ |f| File.exist?(f)}
+          elsif File.file?(path)
+            @certificate_store.add_file(path)
+          elsif File.directory?(path)
+            @certificate_store.add_path(path)
+          else
+            raise "No such file or folder: #{path}"
+          end
+          paths_to_add.each do |p|
+            pp = [File.realpath(p)]
+            if File.directory?(p)
+              pp = Dir.entries(p)
+                .map{ |e| File.realpath(File.join(p, e))}
+                .select{ |entry| File.file?(entry)}
+                .select{ |entry| CERT_EXT.any?{ |ext| entry.end_with?(ext)}}
+            end
+            @certificate_paths.concat(pp)
+          end
+        end
+        @certificate_paths.uniq!
+      end
+
+      # Return cert file paths (computes OS defaults lazily if never set).
+      def trusted_cert_locations
+        if @certificate_paths.nil?
+          self.trusted_cert_locations = [SpecialValues::DEF]
+          locations = @certificate_paths
+          # Restore to "lazy" state so next call recomputes if store was reset
+          @certificate_paths = @certificate_store = nil
+          return locations
+        end
+        @certificate_paths
+      end
+
+      # ------------------------------------------------------------------
+      # HTTP session callback
+      # Called every time a new Net::HTTP session is opened.
+      # ------------------------------------------------------------------
+
+      # @param http_session [Net::HTTP]
+      def update_session(http_session)
+        http_session.set_debug_output(LineLogger.new(:trace2)) if Log.instance.logger.trace2?
+        if http_session.use_ssl? && ignore_cert?(http_session.address, http_session.port)
+          http_session.verify_mode = SELF_SIGNED_CERT
+        end
+        http_session.cert_store = @certificate_store if @certificate_store
+        Log.log.debug{"Using cert store #{http_session.cert_store} (#{@certificate_store})"} unless http_session.cert_store.nil?
+        @http_options.each do |k, v|
+          method = "#{k}=".to_sym
+          if http_session.respond_to?(method)
+            http_session.send(method, v)
+          else
+            Log.log.error{"Unknown HTTP session attribute: #{k}"}
+          end
+        end
+      end
+    end
+  end
+end