aspera-cli 4.25.2 → 4.25.3

data/CONTRIBUTING.md

@@ -110,13 +110,14 @@ A few macros and environment variables control certain aspects of the build:
 | `ASPERA_CLI_TEST_CONF_URL`  | URL for configuration file with secrets for tests.  |
 | `ASPERA_CLI_DOC_CHECK_LINKS`| Check links still exist during doc generation.      |
 | `LOG_LEVEL`                 | Change log level in `rake` tasks.                   |
+| `LOG_SECRETS`               | Change log secrets in `rake` tasks.                   |
 | `ENABLE_COVERAGE`           | Enable test coverage analysis when set.             |
 | `SIGNING_KEY`               | Path to the signing key used to build the gem file. |
 | `SIGNING_KEY_PEM`           | PEM of signing key.                                 |
 
 These can be set either as environment variables or directly on the `rake` command line.
 
-Setting `SIGNING_KEY_PEM` creates file `$HOME/.gem/signing_key.pem` and sets `SIGNING_KEY`.
+Setting `SIGNING_KEY_PEM` creates file `$HOME/.gem/signing_key.pem` and sets `SIGNING_KEY` to that path.
 
 > [!NOTE]
 > Environment variables `ASPERA_CLI_*` are typically set in the user’s shell profile for development.
@@ -153,6 +154,12 @@ To check URLs during documentation generation, set the environment variable: `AS
 
 To debug documentation generation, set the environment variable: `ASPERA_CLI_DOC_DEBUG=debug`.
 
+To generate documentation:
+
+```bash
+rake doc:build
+```
+
 ## Test Environment
 
 Refer to <tests/README.md>.
@@ -192,7 +199,7 @@ Update with:
 bundle exec rake tools:grpc
 ```
 
-It downloads the latest `proto` file and then compiles it.
+It downloads the latest `proto` file and then compiles it into ruby sources included in the repo.
 
 ## Container image build
 
@@ -212,7 +219,8 @@ bundle exec rake -T ^binary:
 
 ### Branching Strategy
 
-This project uses a single `main` branch for development. During the development cycle, the version in `lib/aspera/cli/version.rb` uses a `.pre` suffix (e.g., `x.y.z.pre`) to indicate a pre-release state.
+This project uses a single `main` branch for development.
+During the development cycle, the version in `lib/aspera/cli/version.rb` uses a `.pre` suffix (e.g., `x.y.z.pre`) to indicate a pre-release state.
 
 Feature development and bug fixes can be done either:
 
@@ -229,10 +237,10 @@ When preparing for a new release, do the following:
 bundle exec rake test:run
 ```
 
-- Verify that the container builds successfully (using the beta version):
+- Verify that the container builds successfully (using the local gem file):
 
 ```bash
-bundle exec rake container:build
+bundle exec rake container:build'[local]'
 bundle exec rake container:test
 ```
 
@@ -252,16 +260,17 @@ To create a release:
 The workflow automatically:
 
 1. Updates `version.rb` with the release version
-2. Rebuilds documentation (PDF manual, README)
+2. Rebuilds documentation (PDF manual, Markdown README)
 3. Commits the changes
 4. Creates and pushes the release tag
 5. Triggers the `deploy` workflow to publish to [rubygems.org](https://rubygems.org/gems/aspera-cli)
 6. Updates `version.rb` to the next development version with `.pre` suffix
-7. Commits and pushes the version bump
+7. Commits and pushes the version bump in main branch.
 
 ### Manual Release Process (Alternative)
 
-If needed, releases can still be done manually:
+If needed, releases can still be done manually.
+Basically, follow the same procedure as in the GitHub action:
 
 - Update the version in `lib/aspera/cli/version.rb` (remove `.pre` suffix)
 

data/README.md

@@ -9,17 +9,20 @@
 Use it from the terminal or in scripts to:
 
 - Drive **Aspera on Cloud**, **Faspex**, **Shares**, **Node**, **Console**, **Orchestrator**, and **High-Speed Transfer Server**
-- Call REST APIs and run high-speed transfers (FASP)
+- Call REST APIs and run high-speed transfers (**FASP**)
 - Automate workflows with config, presets, and scripting
 
 ## Documentation
 
+Choose what best suits you:
+
 | Resource | Link |
-|----------|------|
+| -------- | ---- |
 | **Online manual** | [docs/README.md](docs/README.md) |
 | **PDF manual** | In [releases](https://github.com/IBM/aspera-cli/releases) |
 | **RubyGems** | [rubygems.org/gems/aspera-cli](https://rubygems.org/gems/aspera-cli) |
 | **RubyDoc** | [rubydoc.info/gems/aspera-cli](https://www.rubydoc.info/gems/aspera-cli) |
+| **Docsify** | [online](https://docsify-this.net/?basePath=https://raw.githubusercontent.com/IBM/aspera-cli/main/docs&homepage=README.md&sidebar=true&browser-tab-title=Aspera%20CLI%20Manual&hide-credits=true&maxLevel=4&externalLinkTarget=_blank&image-captions=true&dark-mode=auto) |
 
 ## Install
 
@@ -30,7 +33,7 @@ gem install aspera-cli
 ascli config transferd install
 ```
 
-The second command installs the FASP transfer engine (`ascp`).
+The second command installs the **FASP** transfer engine (`ascp`).
 For other install methods (single executable, Docker, Chocolatey, Homebrew), see the [user manual](docs/README.md#installation).
 
 **Quick check:**

data/lib/aspera/api/aoc.rb

@@ -142,11 +142,14 @@ module Aspera
           }
         end
 
-        # Call block with same query using paging and response information.
-        # Block must return an Array with data and http response
-        # @return [Hash] {items: , total: }
-        def call_paging(query: nil, formatter: nil)
-          query = {} if query.nil?
+        # Call `block` with same query using paging and response information.
+        # Block must return a 2 element `Array` with data and http response
+        # @param query    [Hash] Additionnal query parameters
+        # @param progress [nil, Object] Uses methods: `long_operation_running` and `long_operation_terminated`
+        # @return [Hash] Items and total number of items
+        # @option return [Array<Hash>] :items The list of items
+        # @option return [Integer] :total The total number of items
+        def call_paging(query: {}, progress: nil)
           Aspera.assert_type(query, Hash){'query'}
           Aspera.assert(block_given?)
           # set default large page if user does not specify own parameters. AoC Caps to 1000 anyway
@@ -174,9 +177,9 @@ module Aspera
             break if !max_items.nil? && item_list.count >= max_items
             break if !max_pages.nil? && page_count >= max_pages
             break if total_count&.<=(item_list.count)
-            formatter&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
+            progress&.long_operation_running("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
-          formatter&.long_operation_terminated
+          progress&.long_operation_terminated
           item_list = item_list[0..max_items - 1] if !max_items.nil? && item_list.count > max_items
           return {items: item_list, total: total_count}
         end
@@ -229,7 +232,8 @@ module Aspera
         username: nil,
         password: nil,
         workspace: nil,
-        secret_finder: nil
+        secret_finder: nil,
+        progress_disp: nil
       )
         # Test here because link may set url
         Aspera.assert(url, 'Missing mandatory option: url', type: ParameterError)
@@ -240,6 +244,7 @@ module Aspera
         # key: access key
         # value: associated secret
         @secret_finder = secret_finder
+        @progress_disp = progress_disp
         @workspace_name = workspace
         @cache_user_info = nil
         @cache_url_token_info = nil
@@ -299,10 +304,12 @@ module Aspera
           )
       end
 
-      # read using the query and paging
+      # Read using the query and paging
+      # @param subpath [String] Entity path
+      # @param query [nil, Hash] Additional query
       # @return [Hash] {items: , total: }
-      def read_with_paging(subpath, query = nil, formatter: nil)
-        return self.class.call_paging(query: query, formatter: formatter) do |paged_query|
+      def read_with_paging(subpath, query = nil)
+        return self.class.call_paging(query: query, progress: @progress_disp) do |paged_query|
           read(subpath, query: paged_query, ret: :both)
         end
       end
@@ -710,7 +717,7 @@ module Aspera
         # (optional). The name of the folder to be displayed to the destination user.
         # Use it if its value is different from the "share_as" field.
         event_creation['link_name'] = app_info[:opt_link_name] unless app_info[:opt_link_name].nil?
-        create('events', event_creation)
+        create('events', event_creation, query: {admin: true})
       end
     end
   end

data/lib/aspera/api/faspex.rb

@@ -60,19 +60,32 @@ module Aspera
       PATH_AUTH = 'auth'
       PATH_API_V5 = 'api/v5'
       PATH_HEALTH = 'configuration/ping'
-      private_constant :PATH_API_V5,
-        :PATH_HEALTH,
-        :PATH_AUTH
+      private_constant :PATH_AUTH,
+        :PATH_API_V5,
+        :PATH_HEALTH
       RECIPIENT_TYPES = %w[user workgroup external_user distribution_list shared_inbox].freeze
       PACKAGE_TERMINATED = %w[completed failed].freeze
       # list of supported mailbox types (to list packages)
-      API_LIST_MAILBOX_TYPES = %w[inbox inbox_history inbox_all inbox_all_history outbox outbox_history pending pending_history all].freeze
+      SENT_MAILBOX_TYPES = %w[outbox outbox_history].freeze
+      API_LIST_MAILBOX_TYPES = (%w[inbox inbox_history inbox_all inbox_all_history pending pending_history all] + SENT_MAILBOX_TYPES).freeze
       # PACKAGE_SEND_FROM_REMOTE_SOURCE = 'remote_source'
       # Faspex API v5: get transfer spec for connect
       TRANSFER_CONNECT = 'connect'
       ADMIN_RESOURCES = %i[
-        accounts distribution_lists contacts jobs workgroups shared_inboxes nodes oauth_clients registrations saml_configs
-        metadata_profiles email_notifications alternate_addresses webhooks
+        accounts
+        distribution_lists
+        contacts
+        jobs
+        workgroups
+        shared_inboxes
+        nodes
+        oauth_clients
+        registrations
+        saml_configs
+        metadata_profiles
+        email_notifications
+        alternate_addresses
+        webhooks
       ].freeze
       # states for jobs not in final state
       JOB_RUNNING = %w[queued working].freeze
@@ -114,6 +127,12 @@ module Aspera
         def public_link?(url)
           url.include?('?context=')
         end
+
+        # Depending on box, the package files are either: `received` or `sent`
+        # @return [:sent, :received] the type of mailbox
+        def box_type(box)
+          SENT_MAILBOX_TYPES.include?(box) || box == 'ALL' ? :sent : :received
+        end
       end
       attr_reader :pub_link_context
 

data/lib/aspera/api/node.rb

@@ -65,7 +65,7 @@ module Aspera
         # Adds cache control header, as globally specified to read request
         # Use like this: read(...,**cache_control)
         def cache_control
-          headers = {'Accept' => Rest::MIME_JSON}
+          headers = {'Accept' => Mime::JSON}
           headers[HEADER_X_CACHE_CONTROL] = 'no-cache' unless use_node_cache
           {headers: headers}
         end
@@ -308,7 +308,9 @@ module Aspera
       # @param top_file_id [String] id initial file id
       # @param path [String] file or folder path (end with "/" is like setting process_last_link)
       # @param process_last_link [Boolean] if true, follow the last link
-      # @return [Hash] {.api,.file_id}
+      # @return [Hash] Result data
+      # @option return [Aspera::Rest] :api     REST client instance
+      # @option return [String]       :file_id File identifier
       def resolve_api_fid(top_file_id, path, process_last_link = false)
         Aspera.assert_type(top_file_id, String)
         Aspera.assert_type(path, String)

data/lib/aspera/assert.rb

@@ -93,7 +93,7 @@ module Aspera
     # The value is not one of the expected values
     # @param value  [Object]           The wrong value
     # @param type   [Exception,Symbol] Exception to raise, or Symbol for Log.log
-    # @param block  [Proc]             Additional description in front of message
+    # @param &block [Proc]             Additional description in front of message
     def error_unexpected_value(value, type: InternalError)
       report_error(type, "#{"#{yield}: " if block_given?}unexpected value: #{value.inspect}")
     end

data/lib/aspera/cli/hints.rb

@@ -115,6 +115,13 @@ module Aspera
           remediation: [
             'Check your public key in your AoC user profile.'
           ]
+        },
+        {
+          exception:   Aspera::RestCallError,
+          match:       /Please configure ACLs for this URI/,
+          remediation: [
+            'server must have: asnodeadmin -mu <node user> --acl-add=internal --internal'
+          ]
         }
       ]
       private_constant :ERROR_HINTS

data/lib/aspera/cli/manager.rb

@@ -12,6 +12,37 @@ require 'optparse'
 
 module Aspera
   module Cli
+    module BoolValue
+      # boolean options are set to true/false from the following values
+      YES_SYM = :yes
+      NO_SYM = :no
+      FALSE_VALUES = [NO_SYM, false].freeze
+      TRUE_VALUES = [YES_SYM, true].freeze
+      private_constant :YES_SYM, :NO_SYM, :FALSE_VALUES, :TRUE_VALUES
+      # Boolean values
+      # @return [Array<true, false, :yes, :no>]
+      ALL = (TRUE_VALUES + FALSE_VALUES).freeze
+      TYPES = [FalseClass, TrueClass].freeze
+      SYMBOLS = [NO_SYM, YES_SYM].freeze
+      # @return `true` if value is a value for `true` in ALL
+      def true?(enum)
+        Aspera.assert_values(enum, ALL){'boolean'}
+        return TRUE_VALUES.include?(enum)
+      end
+
+      # @return [:yes, :no]
+      def to_sym(enum)
+        Aspera.assert_values(enum, ALL){'boolean'}
+        return TRUE_VALUES.include?(enum) ? YES_SYM : NO_SYM
+      end
+
+      # @return `true` if value is a value for `true` or `false` in ALL
+      def symbol?(sym)
+        return ALL.include?(sym)
+      end
+      module_function :true?, :to_sym, :symbol?
+    end
+
     # Constants to be used as parameter `allowed:` for `OptionValue`
     module Allowed
       # This option can be set to a single string or array, multiple times, and gives Array of String
@@ -20,7 +51,7 @@ module Aspera
       TYPES_SYMBOL_ARRAY = [Array, Symbol].freeze
       # Value will be coerced to int
       TYPES_INTEGER = [Integer].freeze
-      TYPES_BOOLEAN = [FalseClass, TrueClass].freeze
+      TYPES_BOOLEAN = BoolValue::TYPES
       # no value at all, it's a switch
       TYPES_NONE = [].freeze
       TYPES_ENUM = [Symbol].freeze
@@ -74,7 +105,7 @@ module Aspera
             @values = allowed[Allowed::TYPES_SYMBOL_ARRAY.length..-1]
           elsif allowed.all?(Class)
             @types = allowed
-            @values = Manager::BOOLEAN_VALUES if allowed.eql?(Allowed::TYPES_BOOLEAN)
+            @values = BoolValue::ALL if allowed.eql?(Allowed::TYPES_BOOLEAN)
             # Default value for array
             @object ||= [] if @types.first.eql?(Array) && !@types.include?(NilClass)
             @object ||= {} if @types.first.eql?(Hash) && !@types.include?(NilClass)
@@ -110,7 +141,7 @@ module Aspera
         Aspera.assert(!@deprecation, type: warn){"Option #{@option} is deprecated: #{@deprecation}"}
         new_value = ExtendedValue.instance.evaluate(value, context: "option: #{@option}", allowed: @types)
         Log.log.trace1{"#{where}: #{@option} <- (#{new_value.class})#{new_value}"}
-        new_value = Manager.enum_to_bool(new_value) if @types.eql?(Allowed::TYPES_BOOLEAN)
+        new_value = BoolValue.true?(new_value) if @types.eql?(Allowed::TYPES_BOOLEAN)
         new_value = Integer(new_value) if @types.eql?(Allowed::TYPES_INTEGER)
         new_value = [new_value] if @types.eql?(Allowed::TYPES_STRING_ARRAY) && new_value.is_a?(String)
         # Setting a Hash to null set an empty hash
@@ -142,20 +173,7 @@ module Aspera
     # arguments options start with '-', others are commands
     # resolves on extended value syntax
     class Manager
-      BOOLEAN_SIMPLE = %i[no yes].freeze
       class << self
-        # @return `true` if value is a value for `true` in BOOLEAN_VALUES
-        def enum_to_bool(enum)
-          Aspera.assert_values(enum, BOOLEAN_VALUES){'boolean'}
-          return TRUE_VALUES.include?(enum)
-        end
-
-        # @return :yes ot :no
-        def enum_to_yes_no(enum)
-          Aspera.assert_values(enum, BOOLEAN_VALUES){'boolean'}
-          return TRUE_VALUES.include?(enum) ? BOOL_YES : BOOL_NO
-        end
-
         # Find shortened string value in allowed symbol list
         def get_from_list(short_value, descr, allowed_values)
           Aspera.assert_type(short_value, String)
@@ -165,7 +183,7 @@ module Aspera
           matching = allowed_values.select{ |i| i.to_s.start_with?(short_value)}
           Aspera.assert(!matching.empty?, multi_choice_assert_msg("unknown value for #{descr}: #{short_value}", allowed_values), type: BadArgument)
           Aspera.assert(matching.length.eql?(1), multi_choice_assert_msg("ambiguous shortcut for #{descr}: #{short_value}", matching), type: BadArgument)
-          return enum_to_bool(matching.first) if allowed_values.eql?(BOOLEAN_VALUES)
+          return BoolValue.true?(matching.first) if allowed_values.eql?(BoolValue::ALL)
           return matching.first
         end
 
@@ -279,11 +297,11 @@ module Aspera
         case option_attrs.types
         when Allowed::TYPES_ENUM, Allowed::TYPES_BOOLEAN
           # This option value must be a symbol (or array of symbols)
-          set_option(option_symbol, Manager.enum_to_bool(default), where: 'default') if option_attrs.values.eql?(BOOLEAN_VALUES) && !default.nil?
+          set_option(option_symbol, BoolValue.true?(default), where: 'default') if option_attrs.values.eql?(BoolValue::ALL) && !default.nil?
           value = get_option(option_symbol)
           help_values =
             if option_attrs.types.eql?(Allowed::TYPES_BOOLEAN)
-              highlight_current_in_list(BOOLEAN_SIMPLE, self.class.enum_to_yes_no(value))
+              highlight_current_in_list(BoolValue::SYMBOLS, BoolValue.to_sym(value))
             else
               highlight_current_in_list(option_attrs.values, value)
             end
@@ -636,12 +654,6 @@ module Aspera
           unprocessed_options.delete(k)
         end
       end
-      # boolean options are set to true/false from the following values
-      BOOL_YES = BOOLEAN_SIMPLE.last
-      BOOL_NO = BOOLEAN_SIMPLE.first
-      FALSE_VALUES = [BOOL_NO, false].freeze
-      TRUE_VALUES = [BOOL_YES, true].freeze
-      BOOLEAN_VALUES = (TRUE_VALUES + FALSE_VALUES).freeze
 
       # Option name separator on command line, e.g. in --option-blah, third "-"
       OPTION_SEP_LINE = '-'
@@ -655,7 +667,7 @@ module Aspera
       OPTIONS_STOP = '--'
       SOURCE_USER = 'cmdline' # cspell:disable-line
 
-      private_constant :BOOL_YES, :BOOL_NO, :FALSE_VALUES, :TRUE_VALUES, :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER
+      private_constant :OPTION_SEP_LINE, :OPTION_SEP_SYMBOL, :OPTION_VALUE_SEPARATOR, :OPTION_PREFIX, :OPTIONS_STOP, :SOURCE_USER
     end
   end
 end