aspera-cli 4.26.2 → 4.27.0

data/lib/aspera/schema/documentation.rb

@@ -7,6 +7,15 @@ module Aspera
   module Schema
     # Generate documentation from Schema, for Transfer Spec, or async Conf spec
     class Documentation
+      # Map JSON Schema type names to user-friendly display names
+      JSON_TYPE_TO_DOC = {
+        'string'  => 'String',
+        'integer' => 'Integer',
+        'number'  => 'Number',
+        'boolean' => 'Bool',
+        'array'   => 'Array',
+        'object'  => 'Hash'
+      }.freeze
       # @param formatter [Cli::Formatter] Formatter instance with methods: markdown_text, tick, check_row
       # @param schema [Reader]
       # @param include_option [Boolean] `true`: include CLI options (switches, env vars) in descriptions
@@ -18,25 +27,27 @@ module Aspera
         @include_option = include_option
         @agent_columns = agent_columns
         @code_highlight = code_highlight
-        @columns = %i[name type description]
-        @columns.insert(-2, *Agent::Factory::ALL.values.map{ |i| i[:short]}.sort) if @agent_columns
-        # @type [Array<Hash<Symbol,String>>]
-        @rows = []
+        @columns = %w[name type description]
+        @columns.insert(-2, *Agent::Factory::ALL.values.map{ |i| i[:short].to_s}.sort) if @agent_columns
+        # Sections: each entry is {header: row_or_nil, rows: []}
+        # A flat schema produces a single section with no header.
+        @sections = [{header: nil, rows: []}]
       end
 
       def rows
-        @rows.sort_by{ |i| i[:name]}
+        @sections.flat_map do |section|
+          sorted = section[:rows].sort_by{ |i| i['name']}
+          section[:header] ? [section[:header]] + sorted : sorted
+        end
       end
 
       # @return [Array<String>]
-      def columns
-        @columns.map(&:to_s)
-      end
+      attr_reader :columns
 
-      # First row is the titles
+      # First row is the titles (for Markdown table generation)
       # @return [Array<Array<String>>]
       def table
-        [@columns.map(&:to_s)] + @rows.sort_by{ |i| i[:name]}.map{ |row| @columns.map{ |field| row[field]}}
+        [@columns] + rows.map{ |row| @columns.map{ |field| row[field]}}
       end
 
       # Generate a documentation table from a JSON schema for transfer specifications
@@ -49,37 +60,57 @@ module Aspera
       def build(schema = nil)
         code = @code_highlight ? ->(c){"`#{c}`"} : ->(c){c}
         schema ||= @schema
-        schema.each_property do |property_schema, _name, property_full_name|
+        render_title = ->(title){title.gsub(Markdown::FORMATS){@formatter.markdown_text(Regexp.last_match)}}
+        on_variant = ->(variant_reader, discriminant_property, discriminant_value) do
+          title = variant_reader.current['title'] || variant_reader.current['description']
+          header =
+            if discriminant_property && discriminant_value
+              desc = render_title.call("`#{discriminant_value}`")
+              desc += ": #{render_title.call(title)}" if title
+              @formatter.check_row({
+                'name'        => render_title.call("**#{discriminant_property}**"),
+                'type'        => code.call(JSON_TYPE_TO_DOC['string']),
+                'description' => desc
+              })
+            elsif title
+              @formatter.check_row({'name' => "**#{render_title.call(title)}**", 'type' => '&nbsp;', 'description' => '&nbsp;'})
+            end
+          @sections.push({header: header, rows: []})
+        end
+        schema.each_property(on_variant: on_variant) do |property_schema, _name, property_full_name|
           node = property_schema.current
           # Manual table
+          item_type = JSON_TYPE_TO_DOC.fetch(node['type'], node['type'])
+          item_type = "#{item_type}[#{JSON_TYPE_TO_DOC.fetch(node.dig('items', 'type'), node.dig('items', 'type'))}]" if node['type'].eql?('array') && node.dig('items', 'type').is_a?(String)
           item = {
-            name:        code.call(property_full_name),
-            type:        code.call(node['type']),
-            description: []
+            'name'        => code.call(property_full_name),
+            'type'        => code.call(item_type),
+            'description' => []
           }
           # Render Markdown formatting and split lines
-          item[:description] =
+          item['description'] =
             node['description']
               .gsub(Markdown::FORMATS){@formatter.markdown_text(Regexp.last_match)}
               .split("\n") if node.key?('description')
-          item[:description].unshift("DEPRECATED: #{node['x-deprecation']}") if node.key?('x-deprecation')
+          item['description'].unshift("DEPRECATED: #{node['x-deprecation']}") if node.key?('x-deprecation')
           # Add flags for supported agents in doc
           agents = []
           Agent::Factory::ALL.each_key do |sym|
             agents.push(sym) if node['x-agents'].nil? || node['x-agents'].include?(sym.to_s)
           end
-          Aspera.assert(agents.include?(:direct)){"#{name}: x-cli-option requires agent direct (or nil)"} if node['x-cli-option']
+          Aspera.assert(agents.include?(:direct)){"#{property_full_name}: x-cli-option requires agent direct (or nil)"} if node['x-cli-option']
           if @agent_columns
             Agent::Factory::ALL.each do |sym, names|
-              item[names[:short]] = @formatter.tick(agents.include?(sym))
+              item[names[:short].to_s] = @formatter.tick(agents.include?(sym))
             end
           else
-            item[:description].push("(#{agents.map{ |i| Agent::Factory::ALL[i][:short].to_s.upcase}.sort.join(', ')})") unless agents.length.eql?(Agent::Factory::ALL.length)
+            item['description'].push("(#{agents.map{ |i| Agent::Factory::ALL[i][:short].to_s.upcase}.sort.join(', ')})") unless agents.length.eql?(Agent::Factory::ALL.length)
           end
           # Only keep lines that are usable in supported agents
-          next false if agents.empty?
-          item[:description].push("Allowed values: #{node['enum'].map{ |v| @formatter.markdown_text("`#{v}`")}.join(', ')}.") if node.key?('enum')
-          item[:description].push("Default: #{code.call(node['default'])}.") if node.key?('default')
+          next if agents.empty?
+          item['description'].push("Allowed values: #{node['enum'].map{ |v| @formatter.markdown_text("`#{v}`")}.join(', ')}.") if node.key?('enum')
+          item['description'].push("Default: #{@formatter.markdown_text("`#{node['default']}`")}.") if node.key?('default')
+          item['description'].push("Example: #{@formatter.markdown_text("`#{node['example']}`")}.") if node.key?('example')
           if @include_option
             envvar_prefix = ''
             cli_option =
@@ -87,18 +118,18 @@ module Aspera
                 envvar_prefix = 'env:'
                 node['x-cli-envvar']
               elsif node['x-cli-switch']
-                node['x-cli-option']
+                false_part = node.key?('x-cli-false') ? " / #{node['x-cli-false']}" : ''
+                "#{node['x-cli-option']}#{false_part}"
               elsif node['x-cli-option']
                 arg_type = node.key?('enum') ? '{enum}' : "{#{[node['type']].flatten.join('|')}}"
-                # conversion_tag = node['x-cli-convert']
                 conversion_tag = node.key?('x-cli-convert') ? 'conversion' : nil
                 sep = node['x-cli-option'].start_with?('--') ? '=' : ' '
                 "#{node['x-cli-option']}#{sep}#{"(#{conversion_tag})" if conversion_tag}#{arg_type}"
               end
             short = node.key?('x-cli-short') ? "(#{node['x-cli-short']})" : nil
-            item[:description].push("(#{'special:' if node['x-cli-special']}#{envvar_prefix}#{@formatter.markdown_text("`#{cli_option}`")})#{short}") if cli_option
+            item['description'].push("(#{'special:' if node['x-cli-special']}#{envvar_prefix}#{@formatter.markdown_text("`#{cli_option}`")})#{short}") if cli_option
           end
-          @rows.push(@formatter.check_row(item))
+          @sections.last[:rows].push(@formatter.check_row(item))
         end
         self
       end

data/lib/aspera/schema/reader.rb

@@ -7,11 +7,34 @@ module Aspera
     class Reader
       attr_reader :current
 
+      class << self
+        # Build a synthetic Reader from an OAS `parameters` array (entries with `in: query`).
+        # Produces a JSON Schema object whose `properties` map each query param name to its schema,
+        # with the OAS-level `description` and `required` merged in.
+        # @param params [Array<Hash>] raw OAS parameter objects (may contain path/header params too)
+        # @return [Reader]
+        def from_query_params(params)
+          properties = {}
+          required_names = []
+          params.each do |param|
+            next unless param['in'] == 'query'
+            name = param['name']
+            prop = (param['schema'] || {}).dup
+            prop['description'] = param['description'] if param['description'] && !prop.key?('description')
+            properties[name] = prop
+            required_names << name if param['required']
+          end
+          synthetic = {'type' => 'object', 'properties' => properties}
+          synthetic['required'] = required_names unless required_names.empty?
+          new(synthetic)
+        end
+      end
+
       # Shortcut to access current value at path
-      # @param x [String] path element
+      # @param key [String] path element
       # @return [Hash, Array, String, Integer] current value at path
-      def [](x)
-        @current[x]
+      def [](key)
+        @current[key]
       end
 
       # Find sub path relative to current
@@ -31,6 +54,12 @@ module Aspera
         Reader.new(@root, current)
       end
 
+      # Resolve a $ref string to a Reader
+      def resolve_ref(ref)
+        Aspera.assert(ref.start_with?('#/')){"schema $ref must start with '#/': #{ref}"}
+        Reader.new(@root, @root.dig(*ref[2..].split('/')))
+      end
+
       # Read schema from file or from cache
       # @param root [Hash] root schema
       # @param current [Hash, nil] current position in
@@ -40,15 +69,35 @@ module Aspera
         @current = current || root
       end
 
-      # Recursively traverse schema properties with a block
-      # Handles nested objects and arrays automatically
-      # @param prefix [String] Prefix for property names (e.g., 'parent.child.')
+      # Recursively traverse schema properties with a block.
+      # If the current node has `oneOf`, each variant is traversed in turn and
+      # `on_variant` is called (if given) before each variant's properties.
+      # @param prefix     [String] Prefix for property names (e.g., 'parent.child.')
+      # @param on_variant [Proc, nil] Called with the variant Reader before its properties
       # @yield [property_schema, name, full_name] Yields property info to block
-      # @yieldparam property_schema [Reader] Schema reader for this property (use .current to get node hash)
+      # @yieldparam property_schema [Reader] Schema reader for this property
       # @yieldparam name [String] Property name
       # @yieldparam full_name [String] Full property name with prefix
       # @return [nil]
-      def each_property(prefix = '', &block)
+      def each_property(prefix = '', on_variant: nil, &block)
+        if @current.key?('oneOf')
+          # Build reverse map: $ref -> discriminant value, from discriminator.mapping if present
+          discriminant_by_ref = {}
+          if @current.dig('discriminator', 'mapping').is_a?(Hash)
+            @current['discriminator']['mapping'].each do |value, ref|
+              discriminant_by_ref[ref] = value
+            end
+          end
+          discriminant_property = @current.dig('discriminator', 'propertyName')
+          @current['oneOf'].each do |variant_node|
+            ref = variant_node['$ref']
+            variant_reader = ref ? resolve_ref(ref) : Reader.new(@root, variant_node)
+            discriminant_value = ref ? discriminant_by_ref[ref] : nil
+            on_variant&.call(variant_reader, discriminant_property, discriminant_value)
+            variant_reader.each_property(prefix, on_variant: on_variant, &block)
+          end
+          return
+        end
         properties = dig('properties')
         properties.current.each_key do |name|
           property_full_name = "#{prefix}#{name}"
@@ -61,11 +110,11 @@ module Aspera
           # Recursively process nested structures
           case node['type']
           when 'object'
-            property_schema.each_property("#{property_full_name}.", &block) if node['properties']
+            property_schema.each_property("#{property_full_name}.", on_variant: on_variant, &block) if node['properties']
           when 'array'
             if node['items']
               array_item_schema = property_schema.dig('items')
-              array_item_schema.each_property("#{property_full_name}[].", &block) if array_item_schema.current['properties']
+              array_item_schema.each_property("#{property_full_name}[].", on_variant: on_variant, &block) if array_item_schema.current['properties']
             end
           end
         end

data/lib/aspera/schema/registry.rb

@@ -18,11 +18,22 @@ module Aspera
           LOCATIONS.key?(sym)
         end
 
-        # Get path to request body, no check if it exists
-        # @return [String] path to request body
+        # Get path to request body schema, no check if it exists
+        # @param component [String] registry key (e.g. 'faspex', 'aoc')
+        # @param endpoint  [String] endpoint path without leading slash (e.g. 'packages.post')
+        # @return [String] schema path usable in schema: keyword
         def req_body(component, endpoint)
           "#{component}:paths./#{endpoint}.requestBody.content.application/json.schema"
         end
+
+        # Get path to query parameters for a GET endpoint
+        # @param component [String] registry key (e.g. 'faspex', 'aoc')
+        # @param endpoint  [String] resource path without leading slash (e.g. 'packages')
+        # @param method    [String] HTTP method (default: 'get')
+        # @return [String] schema path usable in query_schema: keyword
+        def query_params(component, endpoint, method: 'get')
+          "#{component}:paths./#{endpoint}.#{method}#{QUERY_PARAMS_SUFFIX}"
+        end
       end
 
       LOCATIONS = {
@@ -42,18 +53,34 @@ module Aspera
       AOC = 'aoc'
       FASPEX = 'faspex'
       ASYNC_TABLES = 'async_tables'
-      TRANSFER_INFO = "#{OPTIONS}:components.schemas.TransferInfo"
+      LOG_OPTIONS             = "#{OPTIONS}:components.schemas.LogOptions"
+      DIRECT_AGENT_OPTIONS    = "#{OPTIONS}:components.schemas.DirectAgentOptions"
+      NODE_AGENT_OPTIONS      = "#{OPTIONS}:components.schemas.NodeAgentOptions"
+      HTTPGW_AGENT_OPTIONS    = "#{OPTIONS}:components.schemas.HttpgwAgentOptions"
+      TRANSFERD_AGENT_OPTIONS = "#{OPTIONS}:components.schemas.TransferdAgentOptions"
+      TRANSFER_AGENT_OPTIONS  = "#{OPTIONS}:components.schemas.TransferAgentOptions"
+      SMTP_OPTIONS            = "#{OPTIONS}:components.schemas.SmtpOptions"
+      HTTP_OPTIONS            = "#{OPTIONS}:components.schemas.HttpOptions"
+      VAULT_OPTIONS           = "#{OPTIONS}:components.schemas.VaultOptions"
+      IMAGE_OPTIONS           = "#{OPTIONS}:components.schemas.ImageOptions"
+      PACKAGE_FOLDER_OPTIONS  = "#{OPTIONS}:components.schemas.PackageFolderOptions"
 
       REQ_BODY = '.requestBody.content.application/json.schema'
+      # Suffix appended to a dotted path to signal query-param extraction in reader()
+      QUERY_PARAMS_SUFFIX = '.parameters'
 
       def initialize
         @cache = {}
         @main_folder = File.expand_path('../..', __dir__)
       end
 
-      # Read schema from file or from cache
-      # @param name_path [String] one of the keys in LOCATIONS, with optional :<path> suffix
-      # @return [Reader] schema
+      # Read schema from file or from cache.
+      # When name_path ends with QUERY_PARAMS_SUFFIX, the OAS `parameters` array at that path
+      # is synthesised into an object schema via Reader.from_query_params instead of navigating
+      # into the tree.
+      # @param name_path [String] registry key with optional colon-separated dotted path suffix,
+      #   e.g. "faspex:paths./packages.get.parameters" or "faspex:paths./packages.post.requestBody..."
+      # @return [Reader] schema reader
       def reader(name_path)
         name, path = name_path.split(':', 2)
         sym = name.to_sym
@@ -61,6 +88,12 @@ module Aspera
         spec_file = File.join(@main_folder, LOCATIONS[sym])
         @cache[sym] = Yaml.safe_load(File.read(spec_file)) if spec_file.end_with?('.yaml') && !@cache.key?(sym)
         @cache[sym] = JSON.parse(File.read(spec_file)) if spec_file.end_with?('.json') && !@cache.key?(sym)
+        # Query-params path: strip the suffix, navigate to the operation node, extract parameters
+        if path&.end_with?(QUERY_PARAMS_SUFFIX)
+          parent_path = path.delete_suffix(QUERY_PARAMS_SUFFIX)
+          node = @cache[sym].dig(*parent_path.split('.'))
+          return Reader.from_query_params(node&.fetch('parameters', []) || [])
+        end
         reader = Reader.new(@cache[sym])
         return reader unless path
         reader.dig(*path.split('.'))

data/lib/aspera/secret_hider.rb

@@ -45,7 +45,7 @@ module Aspera
     private_constant :HIDDEN_PASSWORD, :ASCP_ENV_SECRETS, :KEY_SECRETS, :HTTP_SECRETS, :ALL_SECRETS, :KEY_FALSE_POSITIVES, :REGEX_LOG_REPLACES
     attr_accessor :log_secrets
 
-    # @return new log formatter that hides secrets
+    # @return [Proc] new log formatter that hides secrets
     def log_formatter(original_formatter)
       original_formatter ||= Logger::Formatter.new
       # NOTE: that @log_secrets may be set AFTER this init is done, so it's done at runtime
@@ -59,11 +59,16 @@ module Aspera
       end
     end
 
+    # Replace private key content in a string with the hidden password placeholder
+    # @param value [String] Input string possibly containing a private key
+    # @return [String] String with private key replaced by placeholder
     def hide_secrets_in_string(value)
       return value.gsub(REGEX_LOG_REPLACES.first){"#{Regexp.last_match(:begin)}#{HIDDEN_PASSWORD}#{Regexp.last_match(:end)}"}
     end
 
-    # @return true if the key denotes a secret
+    # @param keyword [String, Symbol] Key name to check
+    # @param value   [String]         Associated value (must be a String to be a secret)
+    # @return [Boolean] true if the key denotes a secret
     def secret?(keyword, value)
       keyword = keyword.to_s if keyword.is_a?(Symbol)
       # only Strings can be secrets, not booleans, or hash, arrays

data/lib/aspera/ssl.rb

@@ -12,16 +12,16 @@ module Aspera
       @extra_options = OpenSSL::SSL::SSLContext::DEFAULT_PARAMS[:options]
       attr_reader :extra_options
 
-      def option_list=(v)
-        Aspera.assert_type(v, Array){'ssl_options'}
-        v.each do |opt|
+      def option_list=(options)
+        Aspera.assert_type(options, Array){'ssl_options'}
+        options.each do |opt|
           Aspera.assert_type(opt, String, Integer){'Expected String or Integer in ssl_options'}
           case opt
           when Integer
             @extra_options = opt
           when String
             name = "OP_#{opt.start_with?('-') ? opt[1..] : opt}".upcase
-            raise Cli::BadArgument, "Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map{ |c| c.to_s.sub(/^OP_/, '')}.join(', ')}" if !OpenSSL::SSL.const_defined?(name)
+            Aspera.assert(OpenSSL::SSL.const_defined?(name), type: Cli::BadArgument){"Unknown ssl_option: #{name}, use one of: #{OpenSSL::SSL.constants.grep(/^OP_/).map{ |c| c.to_s.sub(/^OP_/, '')}.join(', ')}"}
             if opt.start_with?('-')
               @extra_options &= ~OpenSSL::SSL.const_get(name)
             else

data/lib/aspera/sync/conf.schema.yaml

@@ -637,7 +637,7 @@ properties:
       Partial transfers may exist if communication disruptions caused the underlying ascp processes to terminate early.
       Note that transfer resumption can only happen if the `reset` option is disabled.
       If an async session starts with `reset` enabled and resume enabled, transfers interrupted during that
-      session will be resumeable, but only if async is then restarted with 'reset' disabled.
+      session will be resumable, but only if async is then restarted with 'reset' disabled.
     type: object
     properties:
       enabled:
@@ -654,7 +654,7 @@ properties:
           Sets the age limit in days for temporary files that will be preserved
           on cleanup (usually at async's start and stop) for potential transfer resume.
           Temp files older than the given value will be removed
-          regardless of whether they might be resumeable.
+          regardless of whether they might be resumable.
         type: integer
         default: "5"
         x-cli-option: --resume-age-days

data/lib/aspera/sync/operations.rb

@@ -4,6 +4,7 @@
 
 require 'aspera/ascp/installation'
 require 'aspera/agent/direct'
+require 'aspera/exec_spec'
 require 'aspera/command_line_converter'
 require 'aspera/command_line_builder'
 require 'aspera/log'
@@ -90,10 +91,7 @@ module Aspera
           Log.dump(:sync_params_initial, sync_info)
           Aspera.assert_type(sync_info, Hash)
           Aspera.assert(PARAM_KEYS.any?{ |k| sync_info.key?(k)}, 'At least one of `local` or `sessions` must be present in async parameters', type: Error)
-          env_args = {
-            args: [],
-            env:  {}
-          }
+          exec_spec = ExecSpec.new(exec: :async)
           if sync_info.key?('local')
             # `conf` format
             Aspera.assert_type(sync_info['local'], Hash){'local'}
@@ -115,10 +113,10 @@ module Aspera
               remote['private_key_paths'].concat(add_certificates)
             end
             # '--exclusive-mgmt-port=12345', '--arg-err-path=-',
-            env_args[:args] = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
+            exec_spec.args = ["--conf64=#{Base64.strict_encode64(JSON.generate(sync_info))}"]
             Log.dump(:sync_conf, sync_info)
             agent = Agent::Direct.new
-            agent.start_and_monitor_process(session: {}, name: :async, **env_args)
+            agent.start_and_monitor_process(session: {}, exec_spec: exec_spec)
           else
             # `args` format
             raise StandardError, "Only 'sessions', and optionally 'instance' keys are allowed" unless
@@ -141,16 +139,16 @@ module Aspera
               Aspera.assert_type(sync_info['instance'], Hash)
               instance_builder = CommandLineBuilder.new(sync_info['instance'], ARGS_INSTANCE_SCHEMA, CommandLineConverter)
               instance_builder.process_params
-              instance_builder.add_env_args(env_args)
+              instance_builder.add_to_exec_spec(exec_spec)
             end
             sync_info['sessions'].each do |session_params|
               Aspera.assert_type(session_params, Hash)
               Aspera.assert(session_params.key?('name'), 'session must contain at least: name')
               session_builder = CommandLineBuilder.new(session_params, ARGS_SESSION_SCHEMA, CommandLineConverter)
               session_builder.process_params
-              session_builder.add_env_args(env_args)
+              session_builder.add_to_exec_spec(exec_spec)
             end
-            Environment.secure_execute(Ascp::Installation.instance.path(:async), *env_args[:args], env: env_args[:env])
+            Environment.secure_execute(Ascp::Installation.instance.path(:async), *exec_spec.args, env: exec_spec.env)
           end
           return
         end
@@ -216,7 +214,7 @@ module Aspera
               return sync_info['local_db_dir']
             elsif (local_path = sync_info.dig('local', 'path'))
               return local_path
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local.path'
             end
           else
@@ -226,11 +224,10 @@ module Aspera
               return session['local_db_dir']
             elsif session.key?('local_dir')
               return session['local_dir']
-            elsif exception
+            else
               raise Error, 'Missing either local_db_dir or local_dir'
             end
           end
-          nil
         end
 
         def session_name(sync_info)
@@ -325,7 +322,7 @@ module Aspera
               end
             end
             path, props = find_option(CONF_SCHEMA, [], option)
-            raise "Option not found: #{option}" if path.nil?
+            Aspera.assert(!path.nil?){"Option not found: #{option}"}
             last_key = path.pop
             # navigate in the current result to insert the value
             current = result

data/lib/aspera/temp_file_manager.rb

@@ -52,7 +52,7 @@ module Aspera
     end
 
     # Ensure that provided folder exists, or create it, generate a unique filename
-    # @return path to that unique file
+    # @return [String] path to that unique file
     def new_file_path_in_folder(temp_folder, prefix: nil, suffix: nil)
       FileUtils.mkdir_p(temp_folder)
       new_file = File.join(temp_folder, [prefix, SecureRandom.uuid, suffix].compact.join('-'))

data/lib/aspera/timer_limiter.rb

@@ -3,7 +3,7 @@
 module Aspera
   # trigger returns true only if the delay has passed since the last trigger
   class TimerLimiter
-    # @param delay in seconds (float)
+    # @param delay [Float] delay in seconds
     def initialize(delay)
       @delay = delay
       @last_trigger_time = nil

data/lib/aspera/transfer/faux_file.rb

@@ -11,42 +11,55 @@ module Aspera
       SIZE_UNITS = %w[k m g t p e].freeze
       private_constant :SCHEME, :PREFIX, :SIZE_UNITS
       class << self
-        # @return nil if not a faux: scheme, else a FauxFile instance
+        # Parse a faux URI and return a `FauxFile` instance, or `nil` if the URI does not use the faux scheme.
+        # URI format: `faux:///<path>?<size>`, where `<size>` is a decimal integer with an optional
+        # case-insensitive unit suffix: `k`, `m`, `g`, `t`, `p`, `e` (powers of 1024).
+        # When no suffix is given, the size is interpreted as raw bytes.
+        # Examples: `faux:///file.bin?10` (10 bytes), `faux:///file.bin?10m` (10 MiB)
+        # @param name [String] source file name, possibly a faux URI
+        # @return [FauxFile, nil] `nil` if not a faux scheme, else a `FauxFile` instance
         def create(name)
           return unless name.start_with?(PREFIX)
           name_params = name.delete_prefix(PREFIX).split('?', 2)
-          raise Error, 'Format: #{PREFIX}<file path>?<size>' unless name_params.length.eql?(2)
-          raise Error, "Format: <integer>[#{SIZE_UNITS.join(',')}]" unless (m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}])$/))
-          size = m[1].to_i
-          suffix = m[2]
-          SIZE_UNITS.each do |s|
-            size *= 1024
-            break if s.eql?(suffix)
-          end
+          Aspera.assert(name_params.length.eql?(2), type: Error){"Format: #{PREFIX}<file path>?<size>"}
+          m = name_params[1].downcase.match(/^(\d+)([#{SIZE_UNITS.join('')}]?)$/)
+          Aspera.assert(m, type: Error){"Format: <integer>[#{SIZE_UNITS.join(',')}]"}
+          size = m[2].empty? ? m[1].to_i : m[1].to_i * (1024**(SIZE_UNITS.index(m[2]) + 1))
           return FauxFile.new(name_params[0], size)
         end
       end
+      # @return [String]  virtual file path
+      # @return [Integer] total size in bytes
       attr_reader :path, :size
 
+      # @param path [String]  virtual file path (from the faux URI)
+      # @param size [Integer] total number of bytes to produce
       def initialize(path, size)
         @path = path
         @size = size
         @offset = 0
-        # we cache large chunks, anyway most of them will be the same size
+        # cache chunks by size so repeated reads of the same chunk length reuse the same buffer
         @chunk_by_size = {}
       end
 
+      # Read up to `chunk_size` bytes from the stream and advance the internal offset.
+      # Returns `nil` when the stream is exhausted.
+      # @param chunk_size [Integer] maximum number of bytes to read
+      # @return [String, nil] null-byte string of the bytes actually read, or `nil` at EOF
       def read(chunk_size)
         return if eof?
         bytes_to_read = [chunk_size, @size - @offset].min
         @offset += bytes_to_read
-        @chunk_by_size[bytes_to_read] = "\x00" * bytes_to_read unless @chunk_by_size.key?(bytes_to_read)
+        @chunk_by_size[bytes_to_read] ||= "\x00" * bytes_to_read
         return @chunk_by_size[bytes_to_read]
       end
 
+      # No-op: required to satisfy the IO-like interface used by transfer agents.
+      # @return [nil]
       def close
       end
 
+      # @return [Boolean] true when all bytes have been read
       def eof?
         return @offset >= @size
       end