aspera-cli 4.26.2 → 4.27.0

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.2'
+    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,12 +75,12 @@ 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.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,7 +123,7 @@ 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
@@ -133,7 +134,7 @@ module Aspera
           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)
@@ -160,7 +161,7 @@ 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

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
@@ -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,6 +3,7 @@
 require 'aspera/assert'
 require 'singleton'
 require 'openssl'
+require 'zlib'
 
 module Aspera
   # a simple binary data repository
@@ -23,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

@@ -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

@@ -78,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})
@@ -168,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 ?
@@ -181,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
@@ -195,7 +201,7 @@ 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
@@ -207,7 +213,7 @@ module Aspera
 
       private
 
-      # @return true if the locale charmap resolves to UTF-8
+      # @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?
@@ -291,16 +297,17 @@ module Aspera
       @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

@@ -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}")

data/lib/aspera/graphql.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'aspera/rest_call_error'
+
+module Aspera
+  # Helper to execute GraphQL queries via a Rest object.
+  # Follows the GraphQL-over-HTTP convention: POST {query, variables} to endpoint,
+  # parse top-level `data` key, raise on top-level `errors` array.
+  module GraphQL
+    QUERIES_FOLDER = File.join(__dir__, 'api', 'queries')
+    private_constant :QUERIES_FOLDER
+
+    class << self
+      # Execute a GraphQL query loaded from a .graphql file in lib/aspera/api/queries/
+      # @param rest      [Rest]   API object pointing at the GraphQL endpoint
+      # @param name      [String] Base filename without extension (e.g. 'my_query')
+      # @param variables [Hash]   GraphQL variables
+      # @return [Hash]   The `data` object from the response
+      # @raise [RestCallError] if the response contains GraphQL errors
+      def execute(rest, name, variables = {})
+        query = load_query(name)
+        response = rest.create(nil, {query: query, variables: variables})
+        errors = response['errors']
+        raise RestCallError, errors.map{ |e| e['message']}.join("\n") if errors.is_a?(Array) && !errors.empty?
+        response['data']
+      end
+
+      private
+
+      def load_query(name)
+        File.read(File.join(QUERIES_FOLDER, "#{name}.graphql"))
+      end
+    end
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -1,10 +1,16 @@
 # frozen_string_literal: true
 
 class ::Hash
+  # Recursively merge another hash, with nested hashes merged deeply
+  # @param second [Hash] Hash to merge into self
+  # @return [Hash] New merged hash
   def deep_merge(second)
     merge(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge(v2) : v2}
   end
 
+  # Recursively merge another hash in-place, with nested hashes merged deeply
+  # @param second [Hash] Hash to merge into self
+  # @return [Hash] self
   def deep_merge!(second)
     merge!(second){ |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2}
   end

data/lib/aspera/json_rpc/client.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# cspell:ignore blankslate jsonrpc
+
+require 'aspera/rest_error_analyzer'
+require 'aspera/assert'
+require 'aspera/json_rpc/version'
+require 'blankslate'
+
+Aspera::RestErrorAnalyzer.instance.add_simple_handler(name: 'JSON RPC', path: %w[error message], always: true)
+
+module Aspera
+  module JsonRpc
+    # JSON-RPC 2.0 client over an Aspera::Rest HTTP endpoint.
+    # Methods are dispatched dynamically via method_missing.
+    # Example:
+    #   client = JsonRpc::Client.new(Rest.new(base_url: 'http://127.0.0.1:33024'))
+    #   client.get_info
+    #   client.start_transfer(app_id: '...', transfer_spec: {...})
+    class Client < BlankSlate
+      reveal :instance_variable_get
+      reveal :inspect
+      reveal :to_s
+
+      # @param api       [Rest]   Aspera REST object pointing at the JSON-RPC endpoint
+      # @param namespace [String, nil] optional method prefix, e.g. "myns."
+      def initialize(api, namespace = nil)
+        super()
+        @api        = api
+        @namespace  = namespace
+        @request_id = 0
+      end
+
+      def respond_to_missing?(_sym, _include_private = false)
+        true
+      end
+
+      # Dispatch any Ruby method call as a JSON-RPC request
+      def method_missing(method, *args, &block)
+        args = args.first if args.size == 1 && args.first.is_a?(Hash)
+        data = @api.create('', {
+          jsonrpc: VERSION,
+          method:  "#{@namespace}#{method}",
+          params:  args,
+          id:      @request_id += 1
+        })
+        Aspera.assert_type(data, Hash){'response'}
+        Aspera.assert(data['jsonrpc'] == VERSION, 'bad version in response')
+        Aspera.assert(data.key?('id'), 'missing id in response')
+        Aspera.assert(!(data.key?('error') && data.key?('result')), 'both error and response')
+        Aspera.assert(
+          !data.key?('error') ||
+          data['error'].is_a?(Hash) &&
+          data['error']['code'].is_a?(Integer) &&
+          data['error']['message'].is_a?(String),
+          'bad error response'
+        )
+        return data['result']
+      end
+    end
+  end
+end

data/lib/aspera/json_rpc/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Aspera
+  module JsonRpc
+    VERSION = '2.0'
+  end
+end

data/lib/aspera/keychain/encrypted_hash.rb

@@ -64,7 +64,7 @@ module Aspera
       def set(options)
         validate_set(options)
         label = options.delete(:label)
-        raise "secret #{label} already exist, delete first" if @all_secrets.key?(label)
+        Aspera.assert(!@all_secrets.key?(label)){"secret #{label} already exist, delete first"}
         @all_secrets[label] = options.symbolize_keys
         save
       end

data/lib/aspera/keychain/factory.rb

@@ -24,19 +24,19 @@ module Aspera
             info[:password] = password
             # this module requires compilation, so it is optional
             require 'aspera/keychain/encrypted_hash'
-            @vault = Keychain::EncryptedHash.new(**info)
+            Keychain::EncryptedHash.new(**info)
           when 'system'
             case Environment.instance.os
             when Environment::OS_MACOS
               info[:name] ||= name
-              @vault = Keychain::MacosSystem.new(**info)
+              Keychain::MacosSystem.new(**info)
             else
               raise Error, 'not implemented for this OS'
             end
           when 'vault'
             require 'aspera/keychain/hashicorp_vault'
             info[:token] ||= password
-            @vault = Keychain::HashicorpVault.new(**info)
+            Keychain::HashicorpVault.new(**info)
           else Aspera.error_unexpected_value(vault_type)
           end
         end

data/lib/aspera/keychain/macos_security.rb

@@ -44,7 +44,7 @@ module Aspera
               uri = URI.parse(url)
               Aspera.assert(uri.scheme.eql?('https'), 'only https')
               options[:protocol] = 'htps' # cspell: disable-line
-              raise Error, 'host required in URL' if uri.host.nil?
+              Aspera.assert(!uri.host.nil?, type: Error){'host required in URL'}
               options[:server] = uri.host
               options[:path] = uri.path unless ['', '/'].include?(uri.path)
               options[:port] = uri.port unless uri.port.eql?(443) && !url.include?(':443/')
@@ -128,7 +128,7 @@ module Aspera
         super()
         @keychain_name = name.nil? ? 'default keychain' : name
         @keychain = name.nil? ? MacosSecurity::Keychain.default : MacosSecurity::Keychain.by_name(name)
-        raise "no such keychain #{name}" if @keychain.nil?
+        Aspera.assert(!@keychain.nil?){"no such keychain #{name}"}
       end
 
       def info
@@ -155,7 +155,7 @@ module Aspera
         unsupported = options.keys - %i[label]
         Aspera.assert(unsupported.empty?){"unsupported options: #{unsupported}"}
         info = @keychain.password(:find, :generic, label: options[:label])
-        raise Error, 'not found' if info.nil?
+        Aspera.assert(!info.nil?, type: Error){'not found'}
         result = options.clone
         result[:secret] = info['password']
         result[:description] = info['icmt'] # cspell: disable-line