aspera-cli 4.26.1 → 4.27.0

data/lib/aspera/cli/transfer_progress.rb

@@ -25,9 +25,9 @@ module Aspera
       end
 
       # Called by user of progress bar with a status on a transfer session
-      # @param session_id the unique identifier of a transfer session
+      # @param session_id [String] the unique identifier of a transfer session
       # @param type [Symbol] one of: sessions_init, session_start, session_size, transfer, session_end and end
-      # @param info optional specific additional info for the given event type
+      # @param info [Object, nil] optional specific additional info for the given event type
       def event(type, session_id: nil, info: nil)
         Log.log.trace1{"progress: #{type} #{session_id} #{info}"}
         return if @completed
@@ -43,14 +43,14 @@ module Aspera
         case type
         when :sessions_init
           # Give opportunity to show progress of initialization with multiple status
-          Aspera.assert(session_id.nil?)
+          Aspera.assert(session_id.nil?, 'session_id must be nil for :sessions_init event')
           Aspera.assert_type(info, String)
           # Initialization of progress bar
           @title = info
         when :session_start
           Aspera.assert_type(session_id, String)
-          Aspera.assert(info.nil?)
-          raise "Session #{session_id} already started" if @sessions[session_id]
+          Aspera.assert(info.nil?, 'info must be nil for :session_start event')
+          Aspera.assert(!@sessions[session_id]){"Session #{session_id} already started"}
           @sessions[session_id] = {
             job_size: 0, # Total size of transfer (pre-calc)
             current:  0,
@@ -60,7 +60,7 @@ module Aspera
           @title = nil
         when :session_size
           Aspera.assert_type(session_id, String)
-          Aspera.assert(!info.nil?)
+          Aspera.assert(!info.nil?, 'info must not be nil for :session_size event')
           Aspera.assert_type(@sessions[session_id], Hash)
           @sessions[session_id][:job_size] = info.to_i
           sessions_total = total(:job_size)
@@ -76,12 +76,12 @@ module Aspera
           end
         when :session_end
           Aspera.assert_type(session_id, String)
-          Aspera.assert(info.nil?)
+          Aspera.assert(info.nil?, 'info must be nil for :session_end event')
           # A session may be too short and finish before it has been started
           @sessions[session_id][:running] = false if @sessions[session_id].is_a?(Hash)
         when :end
-          Aspera.assert(session_id.nil?)
-          Aspera.assert(info.nil?)
+          Aspera.assert(session_id.nil?, 'session_id must be nil for :end event')
+          Aspera.assert(info.nil?, 'info must be nil for :end event')
           @progress_bar.finish
         else Aspera.error_unexpected_value(type){'event type'}
         end

data/lib/aspera/cli/vault_manager.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/error'
+require 'aspera/log'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Mixin providing vault/keychain functionality to Plugin::Config.
+    # Depends on `options` and `context.main_folder` being available in the including class.
+    module VaultManager
+      def action_vault_show(label:, **)
+        Result::SingleObject.new(vault.get(label: label))
+      end
+
+      def action_vault_create(info:, **)
+        vault.set(info.symbolize_keys)
+        Result::Status.new('Secret added')
+      end
+
+      def action_vault_delete(label:, **)
+        vault.delete(label: label)
+        Result::Status.new("Secret deleted: #{label}")
+      end
+
+      def action_vault_password(new_password:, **)
+        Aspera.assert(vault.respond_to?(:change_password), 'Vault does not support password change')
+        vault.change_password(new_password)
+        Result::Status.new('Vault password updated')
+      end
+
+      # @return [String] value from vault matching <name>.<param>
+      def vault_value(name)
+        m = name.split('.')
+        Aspera.assert(m.length.eql?(2), type: BadArgument){'vault name shall match <name>.<param>'}
+        info = vault.get(label: m[0])
+        value = info[m[1].to_sym]
+        raise "no such entry value: #{m[1]}" if value.nil?
+        return value
+      end
+
+      # @return [Keychain::Base] vault instance, lazily created from options
+      def vault
+        return @vault_instance unless @vault_instance.nil?
+        info = options.get_option(:vault, mandatory: true).symbolize_keys
+        info[:type] ||= 'file'
+        require 'aspera/keychain/factory'
+        @vault_instance = Keychain::Factory.create(
+          info,
+          Info::CMD_NAME,
+          context.main_folder,
+          options.get_option(:vault_password)
+        )
+      end
+    end
+  end
+end

data/lib/aspera/cli/version.rb

@@ -4,6 +4,6 @@ module Aspera
   module Cli
     # For beta add extension : .beta1
     # For dev version add extension : .pre
-    VERSION = '4.26.1'
+    VERSION = '4.27.0'
   end
 end

data/lib/aspera/cli/wizard.rb

@@ -10,19 +10,25 @@ module Aspera
     class Wizard
       WIZARD_RESULT_KEYS = %i[preset_value test_args].freeze
       DEFAULT_PRIV_KEY_FILENAME = 'my_private_key.pem' # pragma: allowlist secret
-      private_constant :WIZARD_RESULT_KEYS,
-        :DEFAULT_PRIV_KEY_FILENAME
+      private_constant :WIZARD_RESULT_KEYS, :DEFAULT_PRIV_KEY_FILENAME
+
+      class << self
+        # Declare all wizard CLI options (metadata only - no handler binding yet).
+        # @param options [Aspera::Cli::Parser]
+        def declare_options(options)
+          options.declare(:override,  description: 'Wizard: override existing value',                                                    allowed: Allowed::TYPES_BOOLEAN, default: false)
+          options.declare(:default,   description: 'Wizard: set as default configuration for specified plugin (also: update)',           allowed: Allowed::TYPES_BOOLEAN, default: true)
+          options.declare(:key_path,  description: 'Wizard: path to private key for JWT')
+        end
+      end
 
       def initialize(parent, main_folder)
         @parent = parent
         @main_folder = main_folder
-        # Wizard options
-        options.declare(:override, 'Wizard: override existing value', allowed: Allowed::TYPES_BOOLEAN, default: false)
-        options.declare(:default, 'Wizard: set as default configuration for specified plugin (also: update)', allowed: Allowed::TYPES_BOOLEAN, default: true)
-        options.declare(:key_path, 'Wizard: path to private key for JWT')
+        self.class.declare_options(options)
       end
 
-      # @return false if in test mode to avoid interactive input
+      # @return [Boolean] false if in test mode to avoid interactive input
       def required
         !ENV['ASCLI_WIZ_TEST']
       end
@@ -35,20 +41,15 @@ module Aspera
         @parent.formatter
       end
 
-      def config
-        @parent.config
-      end
-
       def check_email(email)
         Aspera.assert(email =~ /\A[\w+\-.]+@[a-z\d\-.]+\.[a-z]+\z/i, type: ParameterError){"Username shall be an email: #{email}"}
       end
 
       # Find a plugin, and issue the "require"
       # @return [Hash] plugin info: { product:, name:, url:, version: }
-      def identify_plugins_for_url
-        app_url = options.get_next_argument('url', mandatory: true)
-        check_only = options.get_next_argument('plugin name', mandatory: false)
-        check_only = check_only.to_sym unless check_only.nil?
+      def identify_plugins_for_url(url:, plugin_name: nil)
+        app_url = url
+        check_only = plugin_name&.to_sym
         found_apps = []
         my_self_plugin_sym = self.class.name.split('::').last.downcase.to_sym
         Plugins::Factory.instance.plugin_list.each do |plugin_name_sym|
@@ -74,13 +75,13 @@ module Aspera
           next if detection_info.nil?
           Aspera.assert_type(detection_info, Hash)
           Aspera.assert_type(detection_info[:url], String) if detection_info.key?(:url)
-          app_name = plugin_klass.respond_to?(:application_name) ? plugin_klass.application_name : plugin_klass.name.split('::').last
+          app_name = plugin_klass.application_name
           # If there is a redirect, then the detector can override the url.
           found_apps.push({product: plugin_name_sym, name: app_name, url: app_url, version: 'unknown'}.merge(detection_info))
         end
         RestParameters.instance.spinner_cb.call(action: :success)
-        raise "No known application found at #{app_url}" if found_apps.empty?
-        Aspera.assert(found_apps.all?{ |a| a.keys.all?(Symbol)})
+        Aspera.assert(!found_apps.empty?){"No known application found at #{app_url}"}
+        Aspera.assert(found_apps.all?{ |a| a.keys.all?(Symbol)}, 'all app info keys must be symbols')
         return found_apps
       end
 
@@ -122,17 +123,18 @@ module Aspera
 
       # Wizard function, creates configuration
       # @param apps [Array] list of detected apps
-      def find(apps)
+      def find(apps, preset_name: '')
         identification = if apps.length.eql?(1)
           Log.log.debug{"Detected: #{identification}"}
           apps.first
         else
           formatter.display_status('Multiple applications detected, please select from:')
-          formatter.display_results(type: :object_list, data: apps, fields: %w[product url version])
+          require 'aspera/cli/result'
+          formatter.display_results(Result::ObjectList.new(apps, fields: %w[product url version]))
           answer = options.prompt_user_input_in_list('product', apps.map{ |a| a[:product]})
           apps.find{ |a| a[:product].eql?(answer)}
         end
-        wiz_preset_name = options.get_next_argument('preset name', default: '')
+        wiz_preset_name = preset_name
         Log.dump(:identification, identification)
         wiz_url = identification[:url]
         formatter.display_status("Using: #{identification[:name]} at #{wiz_url}".bold)
@@ -140,9 +142,7 @@ module Aspera
         options.add_option_preset({url: wiz_url}, 'wizard')
         # Instantiate plugin: command line options will be known, e.g. private_key, and wizard can be called
         plugin_instance = Plugins::Factory.instance.plugin_class(identification[:product]).new(context: @parent.context)
-        Aspera.assert(plugin_instance.respond_to?(:wizard), type: Cli::BadArgument) do
-          "Detected: #{identification[:product]}, but this application has no wizard"
-        end
+        Aspera.assert(plugin_instance.respond_to?(:wizard), type: Cli::BadArgument){"Detected: #{identification[:product]}, but this application has no wizard"}
         # Call the wizard
         wizard_result = plugin_instance.wizard(self, wiz_url)
         Log.log.debug{"wizard result: #{wizard_result}"}
@@ -161,12 +161,12 @@ module Aspera
         # Init defaults if necessary
         option_override = options.get_option(:override, mandatory: true)
         option_default = options.get_option(:default, mandatory: true)
-        config.defaults_set(identification[:product], wiz_preset_name, wizard_result[:preset_value].stringify_keys, option_default, option_override)
+        @parent.context.presets.defaults_set(identification[:product], wiz_preset_name, wizard_result[:preset_value].stringify_keys, option_default, option_override)
         test_args = wizard_result[:test_args]
         test_args = "-P#{wiz_preset_name} #{test_args}" unless option_default
         # TODO: actually test the command
         test_cmd = "#{Info::CMD_NAME} #{identification[:product]} #{test_args}"
-        return Main.result_status("You can test with:\n#{test_cmd.red}")
+        return Result::Status.new("You can test with:\n#{test_cmd.red}")
       end
     end
   end

data/lib/aspera/command_line_builder.rb

@@ -3,12 +3,13 @@
 require 'aspera/log'
 require 'aspera/assert'
 require 'aspera/schema/registry'
+require 'aspera/exec_spec'
 require 'yaml'
 module Aspera
   # Helper class to build command line from a parameter list (key-value hash)
   # Constructor takes hash: `{ 'param1':'value1', ...}`
   # `process_param` is called repeatedly with all known parameters
-  # `add_env_args` is called to get resulting param list and env var (also checks that all params were used)
+  # `add_to_exec_spec` is called to get resulting param list and env var (also checks that all params were used)
   class CommandLineBuilder
     # Supported keys in JSON schema
     PROPERTY_KEYS = [
@@ -22,6 +23,7 @@ module Aspera
       '$comment',       # [String]
       'x-cli-envvar',   # [String]       Name of env var
       'x-cli-option',   # [String]       Command line option (starts with "-")
+      'x-cli-false',    # [String].      Option to use when switch value is false
       'x-cli-short',    # [String]       Command line option (starts with "-")
       'x-cli-switch',   # [Boolean]      `true` if option has no arg, else by default option has a value
       'x-cli-special',  # [Boolean]      `true` if special handling (deferred)
@@ -36,7 +38,9 @@ module Aspera
 
     class << self
       # Called by provider of definition before constructor of this class so that schema has all mandatory fields
-      # @return [Aspera::Schema::Reader]
+      # @param name_sym [Symbol]  name of the schema to read
+      # @param ascp     [Boolean] `true` if `ascp` mode
+      # @return [Aspera::Schema::Reader] validated schema reader
       def read_schema(name_sym, ascp: false)
         validate_schema(Schema::Registry.instance.reader(name_sym), ascp: ascp)
       end
@@ -50,6 +54,7 @@ module Aspera
 
       private
 
+      # `ascp`: mandatory type
       DIRECT_PROPERTIES = %w[x-cli-option x-cli-envvar x-cli-special].freeze
 
       # Fill default values for some fields in the schema
@@ -66,7 +71,7 @@ module Aspera
           Aspera.assert(node.key?('type') || node.key?('enum')){"Missing type for #{name} in #{schema.current.dig('description').current}"}
           Aspera.assert(node['type'].eql?('boolean')){"switch must be bool: #{name}"} if node['x-cli-switch'] && !node['x-cli-special']
           node['x-cli-option'] = "--#{name.to_s.tr('_', '-')}" if node['x-cli-option'].eql?(true) || (node['x-cli-switch'].eql?(true) && !node.key?('x-cli-option'))
-          Aspera.assert(DIRECT_PROPERTIES.any?{ |i| node.key?(i)}, type: :warn){name} if ascp && supported_by_agent(:direct, node)
+          Aspera.assert(DIRECT_PROPERTIES.any?{ |i| node.key?(i)}, name, type: :warn) if ascp && supported_by_agent(:direct, node)
           node.freeze
         end
         schema
@@ -80,10 +85,7 @@ module Aspera
       @object = object # keep reference so that it can be modified by caller before calling `process_params`
       @schema = schema
       @convert = convert
-      @result = {
-        env:  {},
-        args: []
-      }
+      @result = ExecSpec.new
       @processed_parameters = []
     end
 
@@ -97,16 +99,16 @@ module Aspera
     end
 
     # Add processed parameters to env and args, warns about unused parameters
-    # @param [Hash] env_args with :env and :args
-    def add_env_args(env_args)
-      Log.dump(:env_args, @result)
+    # @param exec_spec [ExecSpec]
+    def add_to_exec_spec(exec_spec)
+      Log.dump(:exec_spec, @result)
       # warn about non translated arguments
       @object.each_pair do |name, value|
         Log.log.warn{"Unknown transfer spec parameter: #{name} = \"#{value}\""} unless @processed_parameters.include?(name)
       end
       # set result
-      env_args[:env].merge!(@result[:env])
-      env_args[:args].concat(@result[:args])
+      exec_spec.env.merge!(@result.env)
+      exec_spec.args.concat(@result.args)
       return
     end
 
@@ -114,7 +116,7 @@ module Aspera
     def add_command_line_options(*options)
       options = options.first if options.first.is_a?(Array) && options.length.eql?(1)
       Aspera.assert_type(options, Array)
-      options.each{ |o| @result[:args].push(o.to_s)}
+      options.each{ |o| @result.args.push(o.to_s)}
     end
 
     def process_params
@@ -140,7 +142,7 @@ module Aspera
         return
       end
       # check mandatory parameter (nil is valid value), TODO: change exception ?
-      raise Transfer::Error, "Missing mandatory parameter: #{name}" if @schema['required']&.include?(name) && !properties['x-cli-special'] && !@object.key?(name)
+      Aspera.assert(!(@schema['required']&.include?(name) && !properties['x-cli-special'] && !@object.key?(name)), type: Transfer::Error){"Missing mandatory parameter: #{name}"}
       parameter_value = @object[name]
       # no default setting
       # parameter_value=properties['default'] if parameter_value.nil? and properties.has_key?('default')
@@ -166,7 +168,7 @@ module Aspera
       return if parameter_value.nil?
 
       # check that value is of an accepted type (string, integer, boolean)
-      raise "Enum value #{parameter_value} is not allowed for #{name}" if properties.key?('enum') && !properties['enum'].include?(parameter_value)
+      Aspera.assert(!(properties.key?('enum') && !properties['enum'].include?(parameter_value))){"Enum value #{parameter_value} is not allowed for #{name}"}
 
       # convert some values if value on command line needs processing from value in structure
       if (convert = properties['x-cli-convert'])
@@ -176,7 +178,7 @@ module Aspera
           when String then @convert.send(convert, parameter_value)
           else Aspera.error_unexpected_value(convert){"Conversion type for #{name} is Hash or String only."}
           end
-        raise "No conversion for: #{name}=#{parameter_value}" if converted_value.nil?
+        Aspera.assert(!converted_value.nil?){"No conversion for: #{name}=#{parameter_value}"}
         parameter_value = converted_value
       end
 
@@ -190,17 +192,15 @@ module Aspera
         return
       elsif properties.key?('x-cli-envvar')
         # set in env var
-        @result[:env][properties['x-cli-envvar']] = parameter_value
+        @result.env[properties['x-cli-envvar']] = parameter_value
       elsif properties['x-cli-switch']
-        # if present and true : just add option without value
-        add_param = false
         case parameter_value
-        when false then nil # nothing to put on command line, no creation by default
-        when true then add_param = true
+        when true
+          add_command_line_options(properties['x-cli-option'])
+        when false
+          add_command_line_options(properties['x-cli-false']) if properties.key?('x-cli-false')
         else Aspera.error_unexpected_value(parameter_value){name}
         end
-        # add_param = !add_param if properties[:add_on_false]
-        add_command_line_options(properties['x-cli-option']) if add_param
       else
         # transform into command line option with value
         # parameter_value=parameter_value.to_s if parameter_value.is_a?(Integer)

data/lib/aspera/data_repository.rb

@@ -3,9 +3,14 @@
 require 'aspera/assert'
 require 'singleton'
 require 'openssl'
+require 'zlib'
 
 module Aspera
   # a simple binary data repository
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of DataRepository
+  #   @return [DataRepository] the singleton instance
   class DataRepository
     include Singleton
 
@@ -19,7 +24,7 @@ module Aspera
     # @return [String] decoded data
     def item(name)
       index = ELEMENTS.index(name)
-      raise ParameterError, "Unknown data item #{name} (#{name.class})" unless index
+      Aspera.assert(index, type: ParameterError){"Unknown data item #{name} (#{name.class})"}
       raw_data = data(START_INDEX + index)
       case name
       when :dsa, :rsa

data/lib/aspera/dot_container.rb

@@ -39,7 +39,7 @@ module Aspera
       # @param container [Hash, Array]
       # @param index     [String, Integer]
       def array_requires_integer_index!(container, index)
-        Aspera.assert(container.is_a?(Hash) || index.is_a?(Integer)){'Using String index when Integer index used previously'}
+        Aspera.assert(container.is_a?(Hash) || index.is_a?(Integer), 'Using String index when Integer index used previously')
       end
 
       # Create a new `Hash` or `Array` depending on type of `key`
@@ -48,7 +48,7 @@ module Aspera
       end
     end
 
-    # @param [Hash,Array] Container object
+    # @param container [Hash,Array] Container object
     def initialize(container)
       Aspera.assert_type(container, Hash)
       # tail (pop,push) contains the next element to display
@@ -72,13 +72,13 @@ module Aspera
           when Hash
             add_elements(path, current)
           when Array
-            # Array has no nested structures -> list of Strings
+            # Array has no nested structures: list of Strings
             if current.none?{ |i| i.is_a?(Array) || i.is_a?(Hash)}
               to_insert = current.map(&:to_s)
-            # Array of Hashes with only 'name' keys -> list of Strings
+            # Array of Hashes with only 'name' keys: list of Strings
             elsif current.all?{ |i| i.is_a?(Hash) && i.keys == ['name']}
               to_insert = current.map{ |i| i['name']}
-            # Array of Hashes with only 'name' and 'value' keys -> Hash of key/values
+            # Array of Hashes with only 'name' and 'value' keys: Hash of key/values
             elsif current.all?{ |i| i.is_a?(Hash) && i.key?('name') && i.key?('value') && i.length <= 3}
               # if there is an extra key, other than 'name' and 'value', insert that key as is
               add_elements(path, current.flat_map{ |h| h.except('name', 'value').to_a})

data/lib/aspera/environment.rb

@@ -13,6 +13,10 @@ require 'shellwords'
 
 module Aspera
   # detect OS, architecture, and specific stuff
+  #
+  # @!method self.instance
+  #   Returns the singleton instance of Environment
+  #   @return [Environment] the singleton instance
   class Environment
     include Singleton
 
@@ -74,7 +78,9 @@ module Aspera
         argv
       end
 
-      # like `Shellwords.shellescape`, but does not escape `=`
+      # Like `Shellwords.shellescape`, but does not escape `=`
+      # @param str [String] String to escape for shell usage
+      # @return [String] Shell-safe string
       def shell_escape_pretty(str)
         # Safe unquoted characters + '=' explicitly allowed
         return str if str.match?(%r{\A[A-Za-z0-9_.,:/@+=-]+\z})
@@ -111,7 +117,7 @@ module Aspera
       # @raise [RuntimeError] If `:exception` is `true` and the process fails in `:capture` mode.
       def secure_execute(*cmd, mode: :execute, **kwargs)
         cmd = cmd.map(&:to_s)
-        Aspera.assert(cmd.size.positive?, type: ArgumentError){'executable must be present'}
+        Aspera.assert(cmd.size.positive?, 'executable must be present', type: ArgumentError)
         Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError){'mode'}
         Log.log.debug do
           parts = [mode.to_s, 'command:']
@@ -153,7 +159,7 @@ module Aspera
       # @param mode [Integer] the file mode (permissions)
       # @yieldreturn [String] The content to write to the file
       def write_file_restricted(path, force: false, mode: nil)
-        Aspera.assert(block_given?, type: Aspera::InternalError)
+        Aspera.assert(block_given?, 'block required for write_file_restricted', type: Aspera::InternalError)
         if force || !File.exist?(path)
           # Windows may give error
           File.unlink(path) rescue nil
@@ -164,7 +170,10 @@ module Aspera
         return path
       end
 
-      # restrict access to a file or folder to user only
+      # Restrict access to a file or folder to the current user only (chmod 600/700)
+      # @param path [String]       Path to the file or directory
+      # @param mode [Integer, nil] Octal permission mode; if nil, inferred from path type
+      # @return [nil]
       def restrict_file_access(path, mode: nil)
         if mode.nil?
           # or FileUtils ?
@@ -177,11 +186,12 @@ module Aspera
           end
         end
         File.chmod(mode, path) unless mode.nil?
+        nil
       rescue => e
         Log.log.warn(e.message)
       end
 
-      # @return true if we are in a terminal
+      # @return [Boolean] true if we are in a terminal
       def terminal?
         $stdout.tty?
       end
@@ -191,11 +201,25 @@ module Aspera
         I18N_VARS.each{ |var| ENV[var] = 'C'}
       end
 
-      # @return true if we can display Unicode characters
+      # @return [Boolean] true if we can display Unicode characters
+      # Uses Encoding.locale_charmap for OS-independent detection.
+      # Falls back to locale env vars for systems where charmap is not available.
       # https://www.gnu.org/software/libc/manual/html_node/Locale-Categories.html
       # https://pubs.opengroup.org/onlinepubs/7908799/xbd/envvar.html
       def terminal_supports_unicode?
-        terminal? && I18N_VARS.any?{ |var| ENV[var]&.include?('UTF-8')}
+        return false unless terminal?
+        locale_charmap_utf8? || I18N_VARS.any?{ |var| ENV[var]&.include?('UTF-8')}
+      end
+
+      private
+
+      # @return [Boolean] true if the locale charmap resolves to UTF-8
+      # Unix: nl_langinfo(CODESET) returns "UTF-8"
+      # Windows: GetACP returns "CP65001" which Encoding.find resolves as UTF-8
+      def locale_charmap_utf8?
+        Encoding.find(Encoding.locale_charmap) == Encoding::UTF_8
+      rescue ArgumentError
+        false
       end
     end
     attr_accessor :url_method, :file_illegal_characters
@@ -266,22 +290,24 @@ module Aspera
       return unless @os.eql?(OS_WINDOWS) && ENV.key?('USERPROFILE') && Dir.exist?(ENV.fetch('USERPROFILE', nil))
       ENV['HOME'] = ENV.fetch('USERPROFILE', nil)
       Log.log.debug{"Windows: set HOME to USERPROFILE: #{Dir.home}"}
+      nil
     end
 
     def graphical?
       @default_gui_mode == :graphical
     end
 
-    # Open a URI in a graphical browser
-    # Command must be non blocking
-    # @param uri [String] the URI to open
+    # Open a URI in the system's default graphical browser (non-blocking)
+    # @param uri [String, URI] the URI to open
+    # @return [nil]
     def open_uri_graphical(uri)
       case @os
-      when Environment::OS_MACOS then return self.class.secure_execute('open', uri.to_s)
-      when Environment::OS_WINDOWS then return self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
-      when Environment::OS_LINUX   then return self.class.secure_execute('xdg-open', uri.to_s)
+      when Environment::OS_MACOS then self.class.secure_execute('open', uri.to_s)
+      when Environment::OS_WINDOWS then self.class.secure_execute('start', 'explorer', %Q{"#{uri}"})
+      when Environment::OS_LINUX   then self.class.secure_execute('xdg-open', uri.to_s)
       else Aspera.error_unexpected_value(os){'no graphical open method'}
       end
+      nil
     end
 
     # open a file in an editor

data/lib/aspera/exec_spec.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Aspera
+  # Holds the executable name, environment variables and command line arguments for a spawned process.
+  ExecSpec = Struct.new(:exec, :env, :args, keyword_init: true) do
+    def initialize(exec: nil, env: {}, args: [], **) = super
+
+    # @return [ExecSpec] deep copy with independent :args and :env
+    def deep_clone
+      self.class.new(exec: exec, env: env.dup, args: args.dup)
+    end
+  end
+end

data/lib/aspera/faspex_gw.rb

@@ -68,7 +68,7 @@ module Aspera
       case request.path
       when '/aspera/faspex/send'
         begin
-          Aspera.assert(!request.body.nil?){'payload missing'}
+          Aspera.assert(!request.body.nil?, 'payload missing')
           faspex_pkg_parameters = JSON.parse(request.body)
           Log.log.debug{"faspex pkg create parameters=#{faspex_pkg_parameters}"}
           # compare string, as class is not yet known here
@@ -84,7 +84,7 @@ module Aspera
           response.status = 200
           response.content_type = Mime::JSON
           response.body = JSON.generate(faspex_package_create_result)
-        rescue => e
+        rescue StandardError => e
           response.status = 500
           response['Content-Type'] = Mime::JSON
           response.body = {error: e.message, stacktrace: e.backtrace}.to_json

data/lib/aspera/faspex_postproc.rb

@@ -16,7 +16,7 @@ module Aspera
       @parameters = parameters.symbolize_keys
       Log.dump(:post_proc_parameters, @parameters)
       not_allowed = @parameters.keys - ALLOWED_PARAMETERS
-      raise "unsupported parameters: #{not_allowed.join(', ')}" unless not_allowed.empty?
+      Aspera.assert(not_allowed.empty?){"unsupported parameters: #{not_allowed.join(', ')}"}
       @parameters[:script_folder] ||= '.'
       @parameters[:fail_on_error] ||= false
       @parameters[:timeout_seconds] ||= 60
@@ -49,6 +49,7 @@ module Aspera
         Log.log.debug{"script=#{script_path}"}
         webhook_parameters = JSON.parse(request.body)
         Log.dump(:webhook_parameters, webhook_parameters)
+        process_status = nil
         if request.query.key?('lambda')
           # Code can throw exception, source code must return a lambda
           Environment.secure_eval(File.read(script_path), __FILE__, __LINE__).call(webhook_parameters)
@@ -62,11 +63,11 @@ module Aspera
             post_proc_pid = nil
           end
           process_status = $CHILD_STATUS
-          raise "script #{script_path} failed with code #{process_status.exitstatus}" if !process_status.success? && @parameters[:fail_on_error]
+          Aspera.assert(process_status.success? || !@parameters[:fail_on_error]){"script #{script_path} failed with code #{process_status.exitstatus}"}
         end
         response.status = 200
         response.content_type = Mime::JSON
-        response.body = JSON.generate({status: 'success', script: script_path, exit_code: process_status.exitstatus})
+        response.body = JSON.generate({status: 'success', script: script_path, exit_code: process_status&.exitstatus})
         Log.log.debug{'Script executed successfully'}
       rescue => e
         Log.log.error("Script failed: #{e.class}:#{e.message}")