aspera-cli 4.26.2 → 4.27.1

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
@@ -57,16 +62,16 @@ module Aspera
       # @param ascp [Boolean] `true` if `ascp`
       # @return [Schema::Reader] The JSON schema
       def validate_schema(schema, ascp: false)
-        Aspera.assert_type(schema, Schema::Reader){'schema'}
-        Aspera.assert(schema.current.key?('properties')){"Schema must have 'properties': #{schema}"}
+        Aspera.assert_type(schema, Schema::Reader) { 'schema' }
+        Aspera.assert(schema.current.key?('properties')) { "Schema must have 'properties': #{schema}" }
         schema.each_property do |property_schema, name, _full_name|
           node = property_schema.current
           unsupported_keys = node.keys - PROPERTY_KEYS
-          Aspera.assert(unsupported_keys.empty?){"Unsupported definition keys: #{unsupported_keys}"}
-          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']
+          Aspera.assert(unsupported_keys.empty?) { "Unsupported definition keys: #{unsupported_keys}" }
+          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)}, name, type: :warn) 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)
+        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
@@ -136,11 +138,11 @@ module Aspera
       properties = @schema['properties'][name]
       # should not happen
       if properties.nil?
-        Log.log.warn{"Unknown parameter #{name}"}
+        Log.log.warn { "Unknown parameter #{name}" }
         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')
@@ -153,7 +155,7 @@ module Aspera
           when 'object' then [Hash]
           when 'integer' then [Integer]
           when 'boolean' then [TrueClass, FalseClass]
-          else Aspera.error_unexpected_value(properties['type']){"Property #{name}"}
+          else Aspera.error_unexpected_value(properties['type']) { "Property #{name}" }
           end
         end.flatten
       # check that value is of expected type
@@ -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'])
@@ -174,9 +176,9 @@ module Aspera
           case convert
           when Hash then convert[parameter_value]
           when String then @convert.send(convert, parameter_value)
-          else Aspera.error_unexpected_value(convert){"Conversion type for #{name} is Hash or String only."}
+          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,23 +192,21 @@ 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
-        else Aspera.error_unexpected_value(parameter_value){name}
+        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)
         parameter_value = [parameter_value] unless parameter_value.is_a?(Array)
         # if transfer_spec value is an array, applies option many times
-        parameter_value.each{ |v| add_command_line_options(properties['x-cli-option'], v)}
+        parameter_value.each { |v| add_command_line_options(properties['x-cli-option'], v) }
       end
     end
   end

data/lib/aspera/command_line_converter.rb

@@ -19,7 +19,7 @@ module Aspera
         case value
         when 'yes' then return true
         when 'no' then return false
-        else Aspera.error_unexpected_value(value){'only: yes or no: '}
+        else Aspera.error_unexpected_value(value) { 'only: yes or no: ' }
         end
       end
 

data/lib/aspera/coverage.rb

@@ -27,12 +27,11 @@ if ENV.key?('ENABLE_COVERAGE')
     # assert usually do not trigger
     add_filter do |source_file|
       source_file.lines.each do |line|
-        line.skipped! if no_cov_functions.any?{ |i| line.src.include?(i)}
+        line.skipped! if no_cov_functions.any? { |i| line.src.include?(i) }
       end
       false
     end
     # no coverage in these files
-    add_filter 'lib/aspera/cli/plugins/faspex.rb'
     add_filter 'lib/aspera/node_simulator.rb'
     add_filter 'lib/aspera/keychain/macos_security.rb'
     add_filter 'lib/aspera/assert.rb'

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

@@ -14,7 +14,7 @@ module Aspera
       def dotted_to_container(path, value, result = nil)
         Aspera.assert_array_all(path, String)
         # Typed keys
-        keys = path.map{ |k| int_or_string(k)}
+        keys = path.map { |k| int_or_string(k) }
         # Create, or re-use first level container
         current = (result ||= new_hash_or_array_from_key(keys.first))
         # walk the path, and create sub-containers if necessary
@@ -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,20 +72,20 @@ module Aspera
           when Hash
             add_elements(path, current)
           when Array
-            # Array has no nested structures -> list of Strings
-            if current.none?{ |i| i.is_a?(Array) || i.is_a?(Hash)}
+            # 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
-            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
-            elsif current.all?{ |i| i.is_a?(Hash) && i.key?('name') && i.key?('value') && i.length <= 3}
+            # 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
+            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})
+              add_elements(path, current.flat_map { |h| h.except('name', 'value').to_a })
               # Insert name/value pairs as Hash
-              add_elements(path, current.to_h{ |h| h.values_at('name', 'value')})
+              add_elements(path, current.to_h { |h| h.values_at('name', 'value') })
             else
-              add_elements(path, current.each_with_index.map{ |v, i| [i, v]})
+              add_elements(path, current.each_with_index.map { |v, i| [i, v] })
             end
           else
             to_insert = current

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})
@@ -116,11 +118,11 @@ module Aspera
       def secure_execute(*cmd, mode: :execute, **kwargs)
         cmd = cmd.map(&:to_s)
         Aspera.assert(cmd.size.positive?, 'executable must be present', type: ArgumentError)
-        Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError){'mode'}
+        Aspera.assert_values(mode, PROCESS_MODES, type: ArgumentError) { 'mode' }
         Log.log.debug do
           parts = [mode.to_s, 'command:']
-          kwargs[:env]&.each{ |k, v| parts << "#{k}=#{shell_escape_pretty(v.to_s)}"}
-          cmd.each{ |a| parts << shell_escape_pretty(a)}
+          kwargs[:env]&.each { |k, v| parts << "#{k}=#{shell_escape_pretty(v.to_s)}" }
+          cmd.each { |a| parts << shell_escape_pretty(a) }
           parts.join(' ')
         end
         case mode
@@ -140,7 +142,7 @@ module Aspera
           # https://docs.ruby-lang.org/en/master/Open3.html#method-c-capture3
           # https://docs.ruby-lang.org/en/master/Process.html#module-Process-label-Execution+Options
           argv = [kwargs.delete(:env)].compact + cmd
-          exception = kwargs.delete(:exception){true}
+          exception = kwargs.delete(:exception) { true }
           result = Open3.capture3(*argv, **kwargs)
           Log.dump(:stdout, result[0], level: :trace1)
           Log.dump(:stderr, result[1], level: :trace1)
@@ -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 ?
@@ -177,37 +182,38 @@ module Aspera
           elsif File.directory?(path)
             mode = 0o700
           else
-            Log.log.debug{"No restriction can be set for #{path}"}
+            Log.log.debug { "No restriction can be set for #{path}" }
           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
 
       # force locale to C so that unicode characters are not used
       def force_terminal_c
-        I18N_VARS.each{ |var| ENV[var] = 'C'}
+        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?
         return false unless terminal?
-        locale_charmap_utf8? || I18N_VARS.any?{ |var| ENV[var]&.include?('UTF-8')}
+        locale_charmap_utf8? || I18N_VARS.any? { |var| ENV[var]&.include?('UTF-8') }
       end
 
       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?
@@ -235,7 +241,7 @@ module Aspera
           OS_LINUX
         when /aix/
           OS_AIX
-        else Aspera.error_unexpected_value(RbConfig::CONFIG['host_os']){'host_os'}
+        else Aspera.error_unexpected_value(RbConfig::CONFIG['host_os']) { 'host_os' }
         end
       @cpu =
         case RbConfig::CONFIG['host_cpu']
@@ -247,7 +253,7 @@ module Aspera
           CPU_S390
         when /arm/, /aarch64/
           CPU_ARM64
-        else Aspera.error_unexpected_value(RbConfig::CONFIG['host_cpu']){'host_cpu'}
+        else Aspera.error_unexpected_value(RbConfig::CONFIG['host_cpu']) { 'host_cpu' }
         end
       @executable_extension = @os.eql?(OS_WINDOWS) ? '.exe' : nil
       # :text or :graphical depending on the environment
@@ -283,7 +289,7 @@ module Aspera
     def fix_home
       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}"}
+      Log.log.debug { "Windows: set HOME to USERPROFILE: #{Dir.home}" }
       nil
     end
 
@@ -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)
-      else Aspera.error_unexpected_value(os){'no graphical open method'}
+      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
@@ -329,7 +336,7 @@ module Aspera
         else
           puts "USER ACTION: open this:\n#{the_url.to_s.red}\n"
         end
-      else Aspera.error_unexpected_value(@url_method){'URL open method'}
+      else Aspera.error_unexpected_value(@url_method) { 'URL open method' }
       end
     end
 

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

@@ -44,7 +44,7 @@ module Aspera
       package_data = {
         'title'      => faspex_pkg_delivery['title'],
         'note'       => faspex_pkg_delivery['note'],
-        'recipients' => faspex_pkg_delivery['recipients'].map{ |name| {'name'=>name}}
+        'recipients' => faspex_pkg_delivery['recipients'].map { |name| {'name'=>name} }
       }
       package = @app_api.create('packages', package_data)
       # TODO: option to send from remote source or httpgw
@@ -70,7 +70,7 @@ module Aspera
         begin
           Aspera.assert(!request.body.nil?, 'payload missing')
           faspex_pkg_parameters = JSON.parse(request.body)
-          Log.log.debug{"faspex pkg create parameters=#{faspex_pkg_parameters}"}
+          Log.dump(:faspex_pkg_parameters, faspex_pkg_parameters)
           # compare string, as class is not yet known here
           faspex_package_create_result =
             case @app_api.class.name
@@ -80,16 +80,16 @@ module Aspera
               faspex4_send_to_faspex5(faspex_pkg_parameters)
             else Aspera.error_unexpected_value(@app_api.class.name)
             end
-          Log.log.debug{"faspex_package_create_result=#{faspex_package_create_result}"}
+          Log.dump(:faspex_package_create_result, faspex_package_create_result)
           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
           Log.log.error(e.message)
-          Log.log.debug{e.backtrace.join("\n")}
+          Log.log.debug { e.backtrace.join("\n") }
         end
       else
         response.status = 400

data/lib/aspera/faspex_postproc.rb

@@ -16,18 +16,18 @@ 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
       super(server)
-      Log.log.debug{'Faspex4PostProcServlet initialized'}
+      Log.log.debug { 'Faspex4PostProcServlet initialized' }
     end
 
     # :reek:UncommunicativeMethodName
     def do_POST(request, response)
-      Log.log.debug{"request=#{request.path}"}
-      Log.log.debug{"query=#{request.query}"}
+      Log.log.debug { "request=#{request.path}" }
+      Log.dump(:query, request.query)
       begin
         # Only accept requests on the root
         if !request.path.start_with?(@parameters[:root])
@@ -44,17 +44,23 @@ module Aspera
         end
         # build script path by removing domain and adding script folder
         script_file = request.path[@parameters[:root].size..]
-        Log.log.debug{"script file=#{script_file}"}
+        Log.log.debug { "script file=#{script_file}" }
         script_path = File.join(@parameters[:script_folder], script_file)
-        Log.log.debug{"script=#{script_path}"}
+        # Resolve the real path and ensure it stays within script_folder (prevents path traversal)
+        resolved_script_folder = File.realpath(@parameters[:script_folder])
+        resolved_script_path = File.realpath(script_path)
+        Aspera.assert(resolved_script_path.start_with?("#{resolved_script_folder}/")) { 'Script path traversal attempt detected' }
+        script_path = resolved_script_path
+        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)
         else
           # env expects only strings
-          environment = webhook_parameters.each_with_object({}){ |(k, v), h| h[k] = v.to_s}
+          environment = webhook_parameters.each_with_object({}) { |(k, v), h| h[k] = v.to_s }
           post_proc_pid = Environment.secure_execute(script_path, mode: :background, env: environment)
           Timeout.timeout(@parameters[:timeout_seconds]) do
             # "wait" for process to avoid zombie
@@ -62,12 +68,12 @@ 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})
-        Log.log.debug{'Script executed successfully'}
+        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}")
         if !post_proc_pid.nil?

data/lib/aspera/graphql.rb

@@ -0,0 +1,37 @@
+# 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)
+        candidate = File.realpath(File.join(QUERIES_FOLDER, "#{name}.graphql"))
+        Aspera.assert(candidate.start_with?("#{QUERIES_FOLDER}/")) { "Invalid GraphQL query name: #{name}" }
+        File.read(candidate)
+      end
+    end
+  end
+end

data/lib/aspera/hash_ext.rb

@@ -1,12 +1,18 @@
 # 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}
+    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}
+    merge!(second) { |_key, v1, v2| v1.is_a?(Hash) && v2.is_a?(Hash) ? v1.deep_merge!(v2) : v2 }
   end
 
   # Recursively iterate through hash and execute block on leaf values