aspera-cli 4.25.1 → 4.25.3

data/lib/aspera/cli/plugins/preview.rb

@@ -90,8 +90,8 @@ module Aspera
           Aspera::Preview::Options::DESCRIPTIONS.each do |opt|
             values = if opt.key?(:values)
               opt[:values]
-            elsif Cli::Manager::BOOLEAN_SIMPLE.include?(opt[:default])
-              Allowed::TYPES_BOOLEAN
+            elsif BoolValue.symbol?(opt[:default])
+              BoolValue::TYPES
             end
             options.declare(opt[:name], opt[:description].capitalize, allowed: values, handler: {o: @gen_options, m: opt[:name]}, default: opt[:default])
           end
@@ -106,17 +106,12 @@ module Aspera
           Log.log.debug{"tmpdir: #{@tmp_folder}"}
         end
 
-        # /files/id/files is normally cached in redis, but we can discard the cache
+        # /files/id/files is normally cached in Redis, but we can discard the cache
         # but /files/id is not cached
         def get_folder_entries(file_id, request_args = nil)
-          headers = {'Accept' => Rest::MIME_JSON}
+          headers = {'Accept' => Mime::JSON}
           headers['X-Aspera-Cache-Control'] = 'no-cache' if @option_folder_reset_cache.eql?(:header)
-          return @api_node.call(
-            operation: 'GET',
-            subpath:   "files/#{file_id}/files",
-            headers:   headers,
-            query:     request_args
-          )
+          return @api_node.read("files/#{file_id}/files", request_args, headers: headers)
         end
 
         # old version based on folders
@@ -153,7 +148,7 @@ module Aspera
             end
             # log/persist periodically or last one
             next unless @periodic.trigger? || event.equal?(events.last)
-            Log.log.info{"Processed event #{event['id']}"}
+            Log.log.debug{"Processed event #{event['id']}"}
             # save checkpoint to avoid losing processing in case of error
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
@@ -186,7 +181,7 @@ module Aspera
             end
             # log/persist periodically or last one
             next unless @periodic.trigger? || event.equal?(events.last)
-            Log.log.info{"Processing event #{event['id']}"}
+            Log.log.debug{"Processing event #{event['id']}"}
             # save checkpoint to avoid losing processing in case of error
             if !iteration_persistency.nil?
               iteration_persistency.data[0] = event['id'].to_s
@@ -303,7 +298,7 @@ module Aspera
             #  download original file to temp folder
             do_transfer(Transfer::Spec::DIRECTION_RECEIVE, entry['parent_file_id'], entry['name'], @tmp_folder)
           end
-          Log.log.info{"source: #{entry['id']}: #{entry['path']}"}
+          Log.log.debug{"source: #{entry['id']}: #{entry['path']}"}
           gen_infos.each do |gen_info|
             gen_info[:generator].generate rescue nil
           end
@@ -335,7 +330,7 @@ module Aspera
             entry = entries_to_process.shift
             # process this entry only if it is within the top_path
             entry_path_with_slash = entry['path']
-            Log.log.info{"processing entry #{entry_path_with_slash}"} if @periodic.trigger?
+            Log.log.debug{"processing entry #{entry_path_with_slash}"} if @periodic.trigger?
             entry_path_with_slash = "#{entry_path_with_slash}/" unless entry_path_with_slash.end_with?('/')
             if !top_path.nil? && !top_path.start_with?(entry_path_with_slash) && !entry_path_with_slash.start_with?(top_path)
               Log.log.debug{"#{entry['path']} folder (skip start)".bg_red}

data/lib/aspera/cli/plugins/shares.rb

@@ -17,20 +17,21 @@ module Aspera
           # @return [Hash] with version, ping, api
           def health_check(url)
             result = {}
+            # Get version from main page
             result[:version] =
               begin
                 version = nil
                 login_page = Rest
                   .new(base_url: url, redirect_max: 2)
                   .read('', headers: {'Accept'=>'text/html'})
+                raise 'not Shares' unless login_page.include?('aspera-Shares')
                 if (m = login_page.match(/\(v([0-9a-f\.]+)\)/))
                   version = m[1]
                   if (m = login_page.match(/Patch level ([0-9]+)/))
-                    version = "#{result[:version]} #{m[0]}"
+                    version = "#{version} #{m[0]}"
                   end
                 end
-                raise 'no version' if version.nil?
-                version
+                version.nil? ? 'no version' : version
               rescue => e
                 e
               end
@@ -45,10 +46,15 @@ module Aspera
               end
             result[:api] =
               begin
-                resp = Rest.new(base_url: url, redirect_max: 1).read("#{NODE_API_PATH}/app", exception: false, ret: :resp)
+                data, resp = Rest
+                  .new(base_url: "#{url}/#{NODE_API_PATH}", redirect_max: 1)
+                  .read('info', exception: false, ret: :both)
                 # shall fail: shares requires auth, but we check error message
-                raise 'not found' unless resp.code.to_s.eql?('401') && resp.body.eql?('{"error":{"user_message":"API user authentication failed"}}')
-                'available'
+                if resp.code.to_s.eql?('401') && data&.dig('error', 'user_message')&.include?('authentication failed')
+                  'available'
+                else
+                  raise "not found (#{resp.code})"
+                end
               rescue => e
                 e
               end
@@ -88,7 +94,7 @@ module Aspera
         SAML_IMPORT_MANDATORY = %w[id name_id].freeze
         SAML_IMPORT_ALLOWED = %w[email given_name surname].concat(SAML_IMPORT_MANDATORY).freeze
 
-        ACTIONS = %i[health files admin].freeze
+        ACTIONS = %i[health info files admin].freeze
         # common to users and groups
         USR_GRP_SETTINGS = %i[transfer_settings app_authorizations share_permissions].freeze
 
@@ -111,6 +117,8 @@ module Aspera
               nagios.add_critical('API', health[:api].to_s)
             end
             Main.result_object_list(nagios.status_list)
+          when :info
+            return Main.result_single_object(basic_auth_api(NODE_API_PATH).read('info', headers: {'Content-Type'=>'application/json'}))
           when :files
             api_shares_node = basic_auth_api(NODE_API_PATH)
             repo_command = options.get_next_command(Node::COMMANDS_SHARES)

data/lib/aspera/cli/transfer_agent.rb

@@ -33,8 +33,8 @@ module Aspera
         :DEFAULT_TRANSFER_NOTIFY_TEMPLATE
 
       class << self
-        # @return :success if all sessions statuses returned by "start" are success
-        # else return the first error exception object
+        # @return [:success]  if all sessions statuses returned by "start" are success
+        # @return [Exception] if one sessions statuses returned by "start" is failed
         def session_status(statuses)
           error_statuses = statuses.reject{ |i| i.eql?(:success)}
           return :success if error_statuses.empty?

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.25.1'
+    VERSION = '4.25.3'
   end
 end

data/lib/aspera/colors.rb

@@ -58,6 +58,13 @@ class String
     end
   end
 
+  # Applies the provided list of string decoration (colors).
+  # @param colors [Array<Symbol>] List of decorations.
+  # @return [String] Enhanced String.
+  def apply(*colors)
+    colors.reduce(self){ |s, c| s.public_send(c)}
+  end
+
   # Transform capitalized to snake case
   def capital_to_snake
     return gsub(/([a-z\d])([A-Z])/, '\1_\2')

data/lib/aspera/environment.rb

@@ -58,8 +58,8 @@ module Aspera
       # @param code [String] Ruby code to execute
       # @param file [String] File name for error reporting
       # @param line [Integer] Line number for error reporting
-      def secure_eval(code, file, line)
-        Kernel.send('lave'.reverse, code, empty_binding, file, line)
+      def secure_eval(code, file, line, user_binding = nil)
+        Kernel.send('lave'.reverse, code, user_binding || empty_binding, file, line)
       end
 
       # Build argv for Process.spawn / Kernel.system (no shell)
@@ -74,26 +74,40 @@ module Aspera
         argv
       end
 
-      # Execute a process securely (no shell)
-      # mode:
-      #   :execute    -> Kernel.system, return nil
-      #   :background -> Process.spawn, return pid
-      #   :capture    -> Open3.capture3, return stdout
-      # @param cmd       [Array]     Command and arguments
-      # @param env       [Hash, nil] Environment variables
-      # @param mode      [Symbol]    Execution mode (see above)
-      # @param kwargs    [Hash]      Additional arguments to underlying method, includes:
-      #                              :exception [Boolean] for :capture mode, raise error if process fails
-      #                              :close_others [Boolean] for :background mode
-      #                              :env [Hash] for :execute mode
+      # like `Shellwords.shellescape`, but does not escape `=`
+      def shell_escape_pretty(str)
+        # Safe unquoted characters + '=' explicitly allowed
+        return str if str.match?(%r{\A[A-Za-z0-9_.,:/@+=-]+\z})
+        # return str if Shellwords.shellescape(str) == str
+
+        # Otherwise use single quotes
+        "'#{str.gsub("'", %q('\'\''))}'"
+      end
+
+      # Execute a process securely without shell.
+      #
+      # Execution `mode` can be:
+      # - :execute    -> Kernel.system, return nil
+      # - :background -> Process.spawn, return pid
+      # - :capture    -> Open3.capture3, return stdout
+      #
+      # @param cmd [Array<String>] Executable and arguments (mapped "to_s")
+      # @param mode [:execute,:background,:capture] Execution mode
+      # @param kwargs [Hash] Additional arguments to underlying method
+      # @option kwargs [Hash] :env Environment variables
+      # @option kwargs [Boolean] :exception for :capture mode, raise error if process fails
+      # @option kwargs [Boolean] :close_others for :background mode
+      # @return [nil] for :execute mode
+      # @return [Integer] pid for :background mode
+      # @return [String] stdout for :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_values(mode, PROCESS_MODES, type: ArgumentError){'mode'}
         Log.log.debug do
           parts = [mode.to_s, 'command:']
-          kwargs[:env]&.each{ |k, v| parts << "#{k}=#{Shellwords.shellescape(v.to_s)}"}
-          cmd.each{ |a| parts << Shellwords.shellescape(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

data/lib/aspera/faspex_gw.rb

@@ -52,9 +52,9 @@ module Aspera
         operation:    'POST',
         subpath:      "packages/#{package['id']}/transfer_spec/upload",
         query:        {transfer_type: Api::Faspex::TRANSFER_CONNECT},
-        content_type: Rest::MIME_JSON,
+        content_type: Mime::JSON,
         body:         {paths: [{'destination'=>'/'}]},
-        headers:      {'Accept' => Rest::MIME_JSON}
+        headers:      {'Accept' => Mime::JSON}
       )
       transfer_spec.delete('authentication')
       # but we place it in a Faspex package creation response
@@ -80,20 +80,20 @@ module Aspera
               faspex4_send_to_faspex5(faspex_pkg_parameters)
             else Aspera.error_unexpected_value(@app_api.class.name)
             end
-          Log.log.info{"faspex_package_create_result=#{faspex_package_create_result}"}
+          Log.log.debug{"faspex_package_create_result=#{faspex_package_create_result}"}
           response.status = 200
-          response.content_type = Rest::MIME_JSON
+          response.content_type = Mime::JSON
           response.body = JSON.generate(faspex_package_create_result)
         rescue => e
           response.status = 500
-          response['Content-Type'] = Rest::MIME_JSON
+          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")}
         end
       else
         response.status = 400
-        response['Content-Type'] = Rest::MIME_JSON
+        response['Content-Type'] = Mime::JSON
         response.body = {error: 'Unsupported endpoint'}.to_json
       end
     end

data/lib/aspera/faspex_postproc.rb

@@ -27,17 +27,18 @@ module Aspera
     # :reek:UncommunicativeMethodName
     def do_POST(request, response)
       Log.log.debug{"request=#{request.path}"}
+      Log.log.debug{"query=#{request.query}"}
       begin
-        # only accept requests on the root
+        # Only accept requests on the root
         if !request.path.start_with?(@parameters[:root])
           response.status = 400
-          response['Content-Type'] = Rest::MIME_JSON
+          response['Content-Type'] = Mime::JSON
           response.body = {status: 'error', message: 'Request outside domain'}.to_json
           return
         end
         if request.body.nil?
           response.status = 400
-          response['Content-Type'] = Rest::MIME_JSON
+          response['Content-Type'] = Mime::JSON
           response.body = {status: 'error', message: 'Empty request'}.to_json
           return
         end
@@ -48,18 +49,23 @@ module Aspera
         Log.log.debug{"script=#{script_path}"}
         webhook_parameters = JSON.parse(request.body)
         Log.dump(:webhook_parameters, webhook_parameters)
-        # env expects only strings
-        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
-          Process.wait(post_proc_pid)
-          post_proc_pid = 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}
+          post_proc_pid = Environment.secure_execute(script_path, mode: :background, env: environment)
+          Timeout.timeout(@parameters[:timeout_seconds]) do
+            # "wait" for process to avoid zombie
+            Process.wait(post_proc_pid)
+            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]
         end
-        process_status = $CHILD_STATUS
-        raise "script #{script_path} failed with code #{process_status.exitstatus}" if !process_status.success? && @parameters[:fail_on_error]
         response.status = 200
-        response.content_type = Rest::MIME_JSON
+        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'}
       rescue => e
@@ -70,7 +76,7 @@ module Aspera
           Log.log.error("Killed process: #{post_proc_pid}")
         end
         response.status = 500
-        response['Content-Type'] = Rest::MIME_JSON
+        response['Content-Type'] = Mime::JSON
         response.body = {status: 'error', script: script_path, message: e.message}.to_json
       end
     end

data/lib/aspera/hash_ext.rb

@@ -26,6 +26,10 @@ unless Hash.method_defined?(:symbolize_keys)
     def symbolize_keys
       return transform_keys(&:to_sym)
     end
+
+    def symbolize_keys!
+      return transform_keys!(&:to_sym)
+    end
   end
 end
 
@@ -35,5 +39,9 @@ unless Hash.method_defined?(:stringify_keys)
     def stringify_keys
       return transform_keys(&:to_s)
     end
+
+    def stringify_keys!
+      return transform_keys!(&:to_s)
+    end
   end
 end

data/lib/aspera/log.rb

@@ -65,11 +65,8 @@ module Aspera
 
     # Class methods
     class << self
-      # Applies the provided list of string decoration (colors) to the value.
-      # @param value [String]         Value to enhance.
-      # @param colors [Array(Symbol)] List of decorations
-      def apply_colors(value, colors)
-        colors.inject(value){ |s, c| s.send(c)}
+      def short_levl(level)
+        "#{level[0, 3]}#{level[-1]}"
       end
 
       # Get the logger object of singleton
@@ -154,8 +151,8 @@ module Aspera
 
     def formatter=(formatter)
       if formatter.is_a?(String)
-        raise Error, "Unknown formatter #{formatter}, use one of: #{FORMATTERS.keys.join(', ')}" unless FORMATTERS.key?(formatter.to_sym)
-        formatter = FORMATTERS[formatter.to_sym]
+        raise Error, "Unknown formatter #{formatter}, use one of: #{FORMATTERS.join(', ')}" unless FORMATTER_LAMBDAS.key?(formatter.to_sym)
+        formatter = FORMATTER_LAMBDAS[formatter.to_sym]
       elsif !formatter.respond_to?(:call) && !formatter.is_a?(Logger::Formatter)
         raise Error, 'Formatter must be a String, a Logger::Formatter or a Proc'
       end
@@ -174,11 +171,10 @@ module Aspera
       Logger::SEVERITY_LABEL[@logger.level].downcase
     end
 
-    # Change underlying logger, but keep log level
+    # Change underlying logger, but keep log level (default: INFO)
     def logger_type=(new_log_type)
-      current_severity_integer = @logger.level unless @logger.nil?
-      current_severity_integer = ENV.fetch('AS_LOG_LEVEL', nil) if current_severity_integer.nil? && ENV.key?('AS_LOG_LEVEL')
-      current_severity_integer = Logger::Severity::WARN if current_severity_integer.nil?
+      # [Integer]
+      current_severity_integer = @logger&.level || ENV['AS_LOG_LEVEL']&.to_i || Logger::Severity::INFO
       case new_log_type
       when :stderr
         @logger = Logger.new($stderr, progname: @program_name, formatter: DEFAULT_FORMATTER)
@@ -227,18 +223,22 @@ module Aspera
       UNKNOWN: %i{blink}
     }.freeze
 
-    # Short levels with color
-    LVL_COLOR = LVL_DECO.map{ |k, v| [k, apply_colors("#{k[..2]}#{k[-1]}", v)]}.to_h.freeze
+    # Short (4-letters) levels with color
+    LVL_COLOR = LVL_DECO.to_h do |k, v|
+      [k, short_levl(k).apply(*v)]
+    end.freeze
 
     DEFAULT_FORMATTER = ->(s, _d, _p, m){"#{LVL_COLOR[s]} #{m}\n"}
 
     # pre-defined formatters
-    FORMATTERS = {
+    FORMATTER_LAMBDAS = {
       standard: Logger::Formatter.new,
       default:  DEFAULT_FORMATTER,
       caller:   ->(s, _d, _p, m){"#{LVL_COLOR[s]} #{Log.caller_method}\n#{m}\n"}
     }.freeze
 
-    private_constant :LVL_DECO, :LVL_COLOR, :DEFAULT_FORMATTER, :FORMATTERS
+    FORMATTERS = FORMATTER_LAMBDAS.keys
+
+    private_constant :LVL_DECO, :DEFAULT_FORMATTER, :FORMATTER_LAMBDAS
   end
 end

data/lib/aspera/markdown.rb

@@ -26,6 +26,28 @@ module Aspera
       def list(items)
         items.map{ |i| "- #{i}"}.join("\n")
       end
+
+      def heading(title, level: 1)
+        "#{'#' * level} #{title}\n\n"
+      end
+
+      # type: NOTE CAUTION WARNING IMPORTANT TIP INFO
+      def admonition(lines, type: 'INFO')
+        "> [!{type}]\n#{lines.map{ |l| "> #{l}"}.join("\n")}\n\n"
+      end
+
+      def code(lines, type: 'shell')
+        "```#{type}\n#{lines.join("\n")}\n```\n\n"
+      end
+
+      # inline code
+      def icode(text)
+        "`#{text}`"
+      end
+
+      def paragraph(text)
+        "#{text}\n\n"
+      end
     end
   end
 end

data/lib/aspera/node_simulator.rb

@@ -328,7 +328,7 @@ module Aspera
 
     def set_json_response(request, response, json, code: 200)
       response.status = code
-      response['Content-Type'] = Rest::MIME_JSON
+      response['Content-Type'] = Mime::JSON
       response.body = json.to_json
       Log.log.trace1{Log.obj_dump("response for #{request.request_method} #{request.path}", json)}
     end

data/lib/aspera/oauth/base.rb

@@ -53,7 +53,7 @@ module Aspera
       def create_token_call(creation_params)
         Log.log.debug{'Generating a new token'.bg_green}
         return @api.create(@path_token, nil, query: creation_params, ret: :resp) if @use_query
-        return @api.create(@path_token, creation_params, content_type: Rest::MIME_WWW, ret: :resp)
+        return @api.create(@path_token, creation_params, content_type: Mime::WWW, ret: :resp)
       end
 
       # Create base parameters for token creation calls
@@ -99,7 +99,7 @@ module Aspera
             # lets try the existing refresh token
             # NOTE: AoC admin token has no refresh, and lives by default 1800secs
             if !refresh_token.nil?
-              Log.log.info{"refresh token=[#{refresh_token}]".bg_green}
+              Log.log.debug{"refresh token=[#{refresh_token}]"}
               begin
                 http = create_token_call(base_params(add_secret: true).merge(grant_type: 'refresh_token', refresh_token: refresh_token))
                 # Save only if success

data/lib/aspera/oauth/url_json.rb

@@ -24,9 +24,9 @@ module Aspera
           operation:    'POST',
           subpath:      path_token,
           query:        @query.merge(scope: params[:scope]), # scope is here because it may change over time (node)
-          content_type: Rest::MIME_JSON,
+          content_type: Mime::JSON,
           body:         @body,
-          headers:      {'Accept' => Rest::MIME_JSON},
+          headers:      {'Accept' => Mime::JSON},
           ret:          :resp
         )
       end

data/lib/aspera/oauth/web.rb

@@ -35,7 +35,7 @@ module Aspera
           base_params.merge(response_type: 'code', redirect_uri: @redirect_uri, state: random_state)
         )
         # here, we need a human to authorize on a web page
-        Log.log.info{"login_page_url=#{login_page_url}".bg_red.gray}
+        Log.log.debug{"login_page_url=#{login_page_url}"}
         # start a web server to receive request code
         web_server = WebAuth.new(@redirect_uri, self.class.additional_info)
         # start browser on login page

data/lib/aspera/preview/generator.rb

@@ -23,18 +23,18 @@ module Aspera
       # one of CONVERSION_TYPES
       attr_reader :conversion_type
 
-      # node API mime types are from: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
-      # the resulting preview file type is taken from destination file extension.
-      # conversion methods are provided by private methods: convert_<conversion_type>_to_<preview_format>
+      # Node API MIME types are from: http://svn.apache.org/repos/asf/httpd/httpd/trunk/docs/conf/mime.types
+      # The resulting preview file type is taken from destination file extension.
+      # Conversion methods are provided by private methods: convert_<conversion_type>_to_<preview_format>
       #   -> conversion_type is one of FileTypes::CONVERSION_TYPES
       #   -> preview_format is one of Generator::PREVIEW_FORMATS
-      # the conversion video->mp4 is implemented in methods: convert_video_to_mp4_using_<video_conversion>
+      # The conversion video->mp4 is implemented in methods: convert_video_to_mp4_using_<video_conversion>
       #  -> conversion method is one of Generator::VIDEO_CONVERSION_METHODS
       # @param src           [String]  source file path
       # @param dst           [String]  destination file path
       # @param options       [Options] All conversion options
       # @param main_temp_dir [String]  Main temp folder, sub folder will be created for generation
-      # @param api_mime_type [String,nil] Optional mime type as provided by node api (or nil)
+      # @param api_mime_type [String,nil] Optional MIME type as provided by node api (or nil)
       def initialize(src, dst, options, main_temp_dir, api_mime_type)
         @source_file_path = src
         @destination_file_path = dst
@@ -57,9 +57,9 @@ module Aspera
         Aspera.assert(respond_to?(@processing_method, true)){"no processing known for #{conversion_type} -> #{@preview_format_sym}"}
       end
 
-      # create preview as specified in constructor
+      # Create preview as specified in constructor.
       def generate
-        Log.log.info{"#{@source_file_path}->#{@destination_file_path} (#{@processing_method})"}
+        Log.log.debug{"#{@source_file_path}->#{@destination_file_path} (#{@processing_method})"}
         begin
           send(@processing_method)
           # check that generated size does not exceed maximum
@@ -76,17 +76,17 @@ module Aspera
 
       private
 
-      # creates a unique temp folder for file
+      # Creates a unique temp folder for file.
       def this_tmpdir
         FileUtils.mkdir_p(@temp_folder)
         return @temp_folder
       end
 
-      # @return offset in seconds suitable for ffmpeg -ss option
       # @param duration of video
       # @param start_offset of parts
       # @param total_count of parts
       # @param index of part (start at 1)
+      # @return [Integer] offset in seconds suitable for ffmpeg -ss option
       def get_offset(duration, start_offset, total_count, index)
         Aspera.assert_type(duration, Float){'duration'}
         return start_offset + ((index - 1) * (duration - start_offset) / total_count)