aspera-cli 4.27.2 → 4.27.4

data/lib/aspera/cli/option_value.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require 'aspera/cli/option_types'
+require 'aspera/cli/extended_value'
+require 'aspera/cli/deprecation'
+require 'aspera/secret_hider'
+require 'aspera/schema/registry'
+require 'aspera/schema/validator'
+require 'aspera/log'
+require 'aspera/assert'
+
+module Aspera
+  module Cli
+    # Declared option: type, value, and where the value is stored.
+    class OptionValue
+      # [Symbol] Name of option
+      attr_reader :option
+      # [Array<Class>, nil] List of allowed types, `nil` for no validation
+      attr_reader :types
+      # [Symbol] How values are converted: :flag, :boolean, :integer, :float, :enum, :enum_list, :string_list, :other
+      attr_reader :kind
+      # [Symbol, nil] `OptionSource` of current value, `nil` if never set
+      attr_reader :source
+      attr_reader :sensitive, :schema, :deprecation
+      # [Array] List of allowed values (Symbols and specific values)
+      attr_accessor :values
+      # [String] Help section group name (set by OptionRegistry)
+      attr_accessor :group
+      # [String, nil] Short option char (set by OptionRegistry)
+      attr_accessor :short
+      # [Proc, nil] Block to call for flag options
+      attr_accessor :block
+
+      # @param option [Symbol] Name of option
+      # @param description [String, nil] Description for help; if nil, derived from schema
+      # @param allowed [nil,Class,Array<Class>,Array<Symbol>] Allowed values
+      # @param on_set [#call, nil] Called with the new value each time the value is set
+      # @param shorthand [String, nil] For a `Hash` option: a `String` value is stored as `{shorthand => value}`
+      # @param deprecation [Hash, Deprecation, nil] Deprecation: `{last:, message:}`, see `Deprecation`
+      # @param schema [String] Declaration of schema
+      # `allowed`:
+      # - `nil` No validation, so just a string
+      # - `Class` The single allowed Class
+      # - `Array<Class>` Multiple allowed classes
+      # - `Array<Symbol>` List of allowed values
+      def initialize(option:, description: nil, allowed: Type::STRING, on_set: nil, shorthand: nil, deprecation: nil, schema: nil)
+        Log.log.trace1 { "option: #{option}, allowed: #{allowed}" }
+        @option = option
+        @description = description
+        @group = nil
+        @short = nil
+        @block = nil
+        # by default passwords and secrets are sensitive, else specify when declaring the option
+        @sensitive = SecretHider.instance.secret?(@option, '')
+        @deprecation = Deprecation.create(deprecation)
+        @schema = schema
+        @shorthand = shorthand
+        @source = nil
+        @value = nil
+        Aspera.assert(on_set.nil? || on_set.respond_to?(:call)) { "#{@option}: on_set callback must respond to call" }
+        @on_set = on_set
+        @types = nil
+        @values = nil
+        @kind = :other
+        allowed = infer_allowed_from_schema(schema, allowed) if schema
+        apply_allowed(allowed) unless allowed.nil?
+      end
+
+      # @return [String] description of the option: explicit one, or first line of schema description
+      def description
+        return @description unless @description.nil?
+        return if @schema.nil?
+        schema_node = Schema::Registry.instance.reader(@schema).current
+        first_line = (schema_node['title'] || schema_node['description'].to_s).lines.first.to_s.strip
+        first_line.end_with?('.') ? first_line[0..-2] : first_line
+      end
+
+      # @return [String, nil] allowed values, or expected types when not plain `String`, e.g. `Hash|String`
+      def allowed_info
+        return @values.join('|') if @values&.any?
+        types = @types&.reject { |t| t.eql?(NilClass) }
+        return if types.nil? || types.empty? || types.eql?(Type::STRING)
+        types.map(&:name).join('|')
+      end
+
+      # @return [Boolean] `true` if option takes no value
+      def flag? = @kind.eql?(:flag)
+
+      # @param value [Object] value given to option
+      # @return [Boolean] `true` if value asks for the schema of option
+      def schema_request?(value) = value.eql?(SchemaRequest::KEYWORD) && @types&.include?(Hash)
+
+      # Reset stored value to nil
+      # @return [nil]
+      def clear
+        store(nil, nil)
+      end
+
+      # Get current option value
+      # @param log [Boolean] whether to log the value retrieval
+      # @return [Object] current value
+      def value(log: true)
+        Log.log.trace1 { "#{@option} -> (#{@value.class})#{@value}" } if log
+        @value
+      end
+
+      # Assign value to option.
+      # Value can be a `String`, then evaluated with `ExtendedValue`, or directly a value.
+      # `Hash` and `Array` values are merged with current value.
+      # @param value [String, Object] Value to assign to option
+      # @param source [Symbol] `OptionSource` of value
+      # @param warn_deprecation [Boolean] Emit deprecation warning (false for internal transfers)
+      # @param merge [Boolean] Merge `Hash` and `Array` with current value (false: value is already complete)
+      # @return [nil]
+      # @raise [SchemaRequest] if value is `help` and schema is known
+      def assign_value(value, source:, warn_deprecation: true, merge: true)
+        # Value from a source with lower priority than current value: only fills containers
+        lower = !@source.nil? && OptionSource.priority(source) < OptionSource.priority(@source)
+        if lower && ![Hash, Array].include?(@types&.first)
+          Log.log.debug { "#{source}: #{@option}: ignored, already set from #{@source}" }
+          return
+        end
+        Aspera.assert(!@deprecation, type: :warn) { "Option #{@option} is #{@deprecation}" } if warn_deprecation
+        if schema_request?(value)
+          return if lower
+          raise SchemaRequest.new(:option, @option, @schema) unless @schema.nil?
+          # Schema depends on command: kept as-is, raised by Parser#get_option(schema:)
+          store(value, source)
+          return
+        end
+        new_value = coerce(ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types))
+        new_value = {@shorthand => new_value} if @shorthand && new_value.is_a?(String)
+        Log.log.trace1 { "#{source}: #{@option} <- (#{new_value.class})#{new_value}" }
+        Aspera.assert_type(new_value, *@types, type: BadArgument) { "Option #{@option}" } if @types
+        if merge && (new_value.is_a?(Hash) || new_value.is_a?(Array))
+          current_value = @value
+          mergeable = current_value.is_a?(new_value.is_a?(Hash) ? Hash : Array) && !current_value.empty?
+          if lower
+            # Current value has priority: merge new value under it, unless explicitly emptied
+            return unless mergeable
+            new_value, current_value = current_value, new_value
+            source = @source
+          end
+          new_value = new_value.is_a?(Hash) ? current_value.deep_merge(new_value) : current_value + new_value if mergeable
+        end
+        validate_schema(new_value) unless %i[code default].include?(source)
+        store(new_value, source)
+        nil
+      end
+
+      private
+
+      # Validate a structured value against the schema of the option.
+      # Value may be partial: completed by other sources or defaults, so `required` is not enforced.
+      # @param value [Object] value to validate
+      # @raise [BadArgument] if value does not match schema
+      def validate_schema(value)
+        return unless @schema && (value.is_a?(Hash) || value.is_a?(Array))
+        errors = Schema::Validator.instance.errors(value, @schema, partial: true)
+        raise BadArgument, "Option #{@option}: #{errors.join('; ')} (use --#{@option.to_s.tr('_', '-')}=#{SchemaRequest::KEYWORD} for schema)" unless errors.empty?
+      end
+
+      # Derive the `allowed:` value from the schema when not explicitly provided.
+      # Returns `allowed` unchanged when the schema provides no usable type information.
+      # @param schema  [String] schema identifier
+      # @param allowed [Object] caller-supplied allowed value (may be nil or Type::STRING)
+      # @return [Object] resolved allowed (Hash, Array, or the original value)
+      def infer_allowed_from_schema(schema, allowed)
+        return allowed unless allowed.nil? || allowed.eql?(Type::STRING)
+
+        schema_reader = Schema::Registry.instance.reader(schema) rescue nil
+        schema_node   = schema_reader&.current
+        return allowed unless schema_node
+
+        case schema_node['type']
+        when 'object' then return Hash
+        when 'array'  then return Array
+        end
+        # No top-level type: inspect oneOf/anyOf branches; if all resolve to 'object', infer Hash
+        composite_key = (%w[oneOf anyOf] & schema_node.keys).first
+        return allowed unless composite_key
+
+        branch_types = schema_node[composite_key].map do |branch|
+          resolved = branch['$ref'] ? schema_reader.resolve_ref(branch['$ref']).current : branch
+          resolved['type']
+        end
+        if branch_types.all?('object')
+          Hash
+        else
+          Aspera.assert(
+            !allowed.nil? && !allowed.eql?(Type::STRING),
+            "option :#{@option}: schema '#{schema}' has mixed-type oneOf branches #{branch_types.uniq}: specify allowed: explicitly"
+          )
+          allowed
+        end
+      end
+
+      # Initialize @types, @values and @kind from the resolved `allowed` specifier.
+      # @param allowed [Class, Array<Class>, Array<Symbol>] resolved allowed value (never nil)
+      def apply_allowed(allowed)
+        allowed = [allowed] if allowed.is_a?(Class)
+        Aspera.assert_type(allowed, Array)
+        if allowed.eql?(Type::NONE)
+          @kind = :flag
+          @types = Type::NONE
+        elsif allowed.take(Type::SYMBOL_ARRAY.length) == Type::SYMBOL_ARRAY
+          # Array of defined symbol values
+          @kind = :enum_list
+          @types = Type::SYMBOL_ARRAY
+          @values = allowed[Type::SYMBOL_ARRAY.length..]
+        elsif allowed.all?(Symbol)
+          @kind = :enum
+          @types = Type::ENUM
+          @values = allowed
+        elsif allowed.all?(Class)
+          @types = allowed
+          @kind =
+            if allowed.sort_by(&:name).eql?(Type::BOOLEAN) then :boolean
+            elsif allowed.eql?(Type::INTEGER) then :integer
+            elsif allowed.eql?(Type::FLOAT) then :float
+            elsif allowed.eql?(Type::STRING_ARRAY) then :string_list
+            else :other
+            end
+          @values = BoolValue::ALL if @kind.eql?(:boolean)
+        else
+          Aspera.error_unexpected_value(allowed)
+        end
+        # Containers start empty, unless nil is allowed
+        default = {Array => [], Hash => {}}[@types.first]
+        store(default, :default) if !default.nil? && !@types.include?(NilClass) && @value.nil?
+      end
+
+      # Convert value from command line, env or preset (String) to the type of option
+      # @param value [Object] evaluated value
+      # @return [Object] converted value
+      def coerce(value)
+        case @kind
+        when :enum
+          # Boolean from dot-path value, e.g. `no` for `%i[no header read]`
+          value = (value ? BoolValue::YES_SYM : BoolValue::NO_SYM).to_s if BoolValue::TYPES.include?(value.class)
+          value.is_a?(String) ? Parser.get_from_list(value, @option, @values) : value
+        when :boolean
+          BoolValue.true?(value.is_a?(String) ? Parser.get_from_list(value, @option, BoolValue::ALL) : value)
+        when :integer
+          # Decimal, also with leading zeros (e.g. `08`)
+          if value.is_a?(String)
+            Integer(value, 10, exception: false).tap { |i| raise BadArgument, "Option #{@option}: invalid integer: #{value}" if i.nil? }
+          else
+            value.nil? ? value : Integer(value)
+          end
+        when :float
+          if value.is_a?(String)
+            Float(value, exception: false).tap { |f| raise BadArgument, "Option #{@option}: invalid number: #{value}" if f.nil? }
+          else
+            value.nil? ? value : Float(value)
+          end
+        when :string_list
+          value.is_a?(String) ? [value] : value
+        when :enum_list
+          value = [value] if value.is_a?(String)
+          Aspera.assert_array_all(value, String, type: BadArgument)
+          value.map { |v| Parser.get_from_list(v, @option, @values) }
+        else
+          # nil on a Hash/Array option resets to empty container
+          value.nil? && [Hash, Array].include?(@types&.first) ? @types.first.new : value
+        end
+      end
+
+      # @param new_value [Object] value to store
+      # @param source [Symbol, nil] `OptionSource` of value
+      def store(new_value, source)
+        @value = new_value
+        @source = source
+        @on_set&.call(new_value)
+      end
+    end
+  end
+end

data/lib/aspera/cli/options.schema.yaml

@@ -102,7 +102,10 @@ components:
           default: true
         quiet:
           type: boolean
-          description: Suppress the `ascp` progress bar display.
+          description: >-
+            Suppress the `ascp` progress bar display.
+
+            If `false`, the progress bar of option `progress_bar` is not displayed, unless that option is set.
           default: true
         file_list:
           type: boolean
@@ -323,7 +326,7 @@ components:
         HTTP/S connection parameters for REST calls (not `ascp` WSS).
 
         Keys are dispatched at startup to three targets:
-        `RestParameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
+        `Rest::Parameters` (`user_agent`, `download_partial_suffix`, `retry_*`),
         `SSL` (`ssl_options`), and `OAuth` (`token_cache_max_age`, `token_refresh_threshold`).
         Any remaining key is forwarded as a setter to the `Net::HTTP` session
         (e.g. `ca_file`, `verify_mode`) — the list below covers the common ones.
@@ -595,18 +598,20 @@ components:
             Token expiry timestamp in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`).
             Computed automatically from `_validity` when absent.
           example: "2030-01-01T00:00:00Z"
-    NodeSimulatorOptions:
+    NodeEmulatorOptions:
       type: object
       description: >-
-        Configuration for the embedded Node API simulator (`node simulator`).
-        The simulator starts a local WEBrick server that answers `/ops/transfers`,
-        `/ops/transfers/{id}`, `/files/browse`, and `/info` — sufficient to test
-        CLI commands against a live Node API without a real HSTS instance.
+        Configuration for the embedded Node API emulator (`node emulator`), for testing without HSTS.
+        The emulator starts a local web server that answers a subset of the Node API:
+        `/info`, `/ops/transfers` (list, start), `/ops/transfers/{id}` (show, modify, cancel) and `/files/browse`.
+        Transfers are executed by the Transfer Daemon (`transferd`), started by the emulator.
+        Clients authenticate with HTTP Basic when `username` and `password` are set.
+      additionalProperties: false
       properties:
         url:
           type: string
           description: >-
-            Address and port the simulator listens on.
+            Address and port the emulator listens on.
             Use `https://` with `cert`/`key` for TLS.
           default: http://localhost:8080
         cert:
@@ -624,13 +629,29 @@ components:
           type: string
           description: Path to the PEM certificate chain file (appended as extra chain certificates).
           example: /path/to/chain.pem
-        browse_root:
+        docroot:
           type: string
           description: >-
-            Root directory the simulator is allowed to expose via `/files/browse`.
-            Requests for paths outside this directory are rejected.
+            Local folder of the node files.
+            Paths of `/files/browse` and local paths of transfers (sources of `send`, destination of `receive`) are relative to it, and confined in it.
             Defaults to the current working directory.
           example: /data/aspera
+        retention_sec:
+          type: integer
+          minimum: 1
+          description: Time in seconds a transfer stays in the list of transfers after it ended (completed, failed or canceled, and no more retried).
+          default: 86400
+        username:
+          type: string
+          description: >-
+            Username expected from clients in HTTP Basic authentication.
+            Set together with `password`.
+            When not set, requests are accepted without authentication.
+          example: node_user
+        password:
+          type: string
+          description: Password expected from clients in HTTP Basic authentication, for the above `username`.
+          example: my_password
     NodeTelemetryOptions:
       type: object
       description: >-
@@ -661,15 +682,93 @@ components:
             Value sent in the `x-instana-host` header.
             Defaults to the local machine's hostname.
           example: hsts-prod-01
+    OrchestratorWorkflowStart:
+      type: object
+      description: >-
+        Execution of the work order created by `orchestrator workflows start`.
+        By default, the call is asynchronous and returns the work order information.
+        A synchronous call returns the value of the output variable, if specified.
+      additionalProperties: false
+      properties:
+        synchronous:
+          type: boolean
+          description: Wait for completion of the work order.
+          default: false
+        step:
+          type: string
+          description: >-
+            Name of the work step providing the result.
+            Requires `variable`, and implies `synchronous`.
+          example: ResultStep
+        variable:
+          type: string
+          description: >-
+            Name of the output variable of `step` returned as result.
+            Requires `step`, and implies `synchronous`.
+          example: Complete_status_message
+    OrchestratorInitiateParameters:
+      type: object
+      description: >-
+        Input parameters for the workflow (key-value pairs).
+        Valid keys are defined by the workflow's input specification.
+        Use `orchestrator workflows inputs WORKFLOW_ID` to discover required parameters.
+      additionalProperties: true
+    OrchestratorImportWorkflow:
+      type: object
+      description: Workflow definition to import into Orchestrator.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          description: Workflow name.
+          example: My Workflow
+        description:
+          type: string
+          description: Workflow description.
+          example: This is a sample workflow
+        workflow_data:
+          type: object
+          description: Complete workflow definition.
+    OrchestratorImportWithConstraints:
+      type: object
+      description: Workflow definition to import with constraint resolution mappings.
+      required:
+        - workflow_data
+        - constraints
+      properties:
+        workflow_data:
+          type: object
+          description: Complete workflow definition to import.
+        constraints:
+          type: object
+          description: Constraint resolution mappings for conflicting resources.
+          example:
+            resource_pools: {}
+            queues: {}
+            monitors: {}
+    OrchestratorReloadPluginSet:
+      type: object
+      description: Set of plugins to reload.
+      required:
+        - plugin_names
+      properties:
+        plugin_names:
+          type: array
+          description: List of plugin names to reload.
+          items:
+            type: string
+          example:
+            - soap_requests
+            - frameio_operations
     TableOptions:
       type: object
       description: Terminal table rendering options.
       properties:
         pivot:
-          type: string
-          description: Control how an object list is displayed (no/yes/single).
-          enum: ['no', 'yes', 'single']
-          default: 'no'
+          description: Control how an object list is displayed (false/true/single).
+          enum: [false, true, single]
+          default: false
     OutOptions:
       type: object
       description: Output rendering options (dot-notation sub-properties).
@@ -705,5 +804,15 @@ components:
           type: boolean
           description: Show secrets in command output.
           default: false
+        colors:
+          type: boolean
+          description: >-
+            Use ANSI colors and styles in terminal output and logs.
+            Default is auto-detected: enabled if both stdout and stderr are terminals and `TERM` is not `dumb`, or if `CLICOLOR_FORCE=1`.
+        utf8:
+          type: boolean
+          description: >-
+            Use Unicode characters in terminal output (e.g. table borders, check marks).
+            Default is auto-detected: enabled if stdout is a terminal and the locale is UTF-8.
         img:
           $ref: "#/components/schemas/ImageOptions"