aspera-cli 4.25.2 → 4.25.4

data/CONTRIBUTING.md

@@ -2,22 +2,23 @@
 
 ## Reporting Issues and Vulnerabilities
 
-If you encounter a problem or a security vulnerability, please report it on [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
+If you encounter a bug or a security vulnerability, please report it via [GitHub Issues](https://github.com/IBM/aspera-cli/issues).
 
-Before submitting a new issue:
+Before submitting a new report:
 
-- Search existing issues to see if your problem has already been reported or resolved.
+- **Search existing issues** to determine if the problem has already been documented or resolved.
 
-To help us assist you efficiently, include the following in your report:
+To help us diagnose and resolve the issue efficiently, please include the following in your report:
 
-- The version of `ascli` you are using:
+- The `ascli` version you are using:
 
   ```bash
-  ascli version
+  ascli -v
   ```
 
-- Confirmation that you are using the latest version (update it if needed).
-- Your Ruby version information:
+- **Update confirmation**: Verify that you are running the latest version.
+
+- **Your Ruby environment details**:
 
   ```bash
   ruby -v
@@ -29,7 +30,7 @@ We welcome contributions to improve the `aspera-cli` project!
 
 ### Getting Started
 
-Clone the repository and navigate to the project's root directory:
+Clone the repository to initialize the development environment:
 
 ```bash
 git clone https://github.com/IBM/aspera-cli.git
@@ -38,55 +39,55 @@ bundle install
 bundle exec rake -T
 ```
 
-For testing instructions, refer to [Running Tests](#running-tests).
+For detailed testing instructions, please refer to [Running Tests](#running-tests).
 
 ### How to Contribute
 
-To submit a contribution:
+To submit a contribution, follow these steps:
 
 1. **Fork** the repository on GitHub.
 
-1. **Create a feature branch** for your changes.
+1. **Create a feature branch** specifically for your changes.
 
 1. **Implement** your feature or bug fix.
 
 1. **Write tests** to ensure your changes are robust and prevent regressions.
 
-1. Run `rubocop` to ensure your code follows the Ruby style guide.
+1. **Run** `rubocop` to ensure your code adheres to the Ruby style guide.
 
-1. Update `CHANGELOG.md` with a summary of your changes.
+1. **Update** `CHANGELOG.md` with a concise summary of your changes.
 
-1. Submit a **pull request** with a clear description of your contribution.
+1. **Submit a pull request** with a detailed description of your work.
 
 > [!TIP]
-> Make sure your pull request is focused and includes only relevant changes.
+> Keep pull requests focused; include only changes relevant to the specific feature or fix.
 
 ## Architecture
 
-The overall architecture of `aspera-cli` is modular and extensible.
+The `aspera-cli` architecture is designed to be modular and extensible.
 
 ![Architecture](docs/architecture.png)
 
 ### Structure Highlights
 
-- Entry Point:
+- **Entry Point**:
 
-  `lib/aspera/cli/main.rb`, CLI startup logic.
+  `lib/aspera/cli/main.rb` contains the core CLI startup logic.
 
-- Plugins:
+- **Plugins**:
 
-  Located in `lib/aspera/cli/plugins`; plugins extend CLI functionality and encapsulate specific features.
+  Located in `lib/aspera/cli/plugins`, these extend CLI functionality and encapsulate specific features.
 
-- Transfer Agents:
+- **Transfer Agents**:
 
-  Found in `lib/aspera/agent`, these handle data transfer operations.
+  Located in `lib/aspera/agent`, these components manage data transfer operations.
 
-Class diagrams are provided in <docs/uml.png>
+Detailed class diagrams are available in <docs/uml.png>
 
 ## Ruby Environment
 
-`aspera-cli` is written in Ruby.
-You can install Ruby using any method you prefer (e.g., `rbenv`, `rvm`, system package manager).
+`aspera-cli` is built with Ruby.
+You can manage your Ruby installation using your preferred tool (e.g., `rbenv`, `rvm`, or a system package manager).
 
 To start with a clean state and remove all installed gems:
 
@@ -95,34 +96,34 @@ bundle exec rake tools:clean_gems
 ```
 
 > [!TIP]
-> This is especially useful before testing across different Ruby versions or preparing for a release.
+> This is particularly useful when testing across different Ruby versions or preparing for a new release.
 
 ## Toolchain
 
-The build system uses Ruby's `rake`.
+The build system is powered by Ruby's `rake`.
 
-### Environment
+### Environment Configuration
 
-A few macros and environment variables control certain aspects of the build:
+The following environment variables and macros control specific build behaviors:
 
-| Environment variable        | Description                                         |
-|-----------------------------|-----------------------------------------------------|
-| `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.                   |
-| `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.                                 |
+| Environment variable        | Contents   | Description                                                  |
+|-----------------------------|------------| -------------------------------------------------------------|
+| `ASPERA_CLI_TEST_CONF_URL`  | URL        | URL for the configuration file containing secrets for tests. |
+| `ASPERA_CLI_DOC_CHECK_LINKS`| yes/no     | Validates that links exist during documentation generation.  |
+| `LOG_SECRETS`               | yes/no     | Toggles the logging of secrets in `rake` tasks.              |
+| `LOG_LEVEL`                 | debug, ... | Sets the logging verbosity for `rake` tasks.                 |
+| `ENABLE_COVERAGE`           | set/unset  | Enables test coverage analysis when defined.                 |
+| `SIGNING_KEY`               | File path  | Path to the signing key used for building the gem file.      |
+| `SIGNING_KEY_PEM`           | PEM Value  | The PEM content of the signing key.                          |
 
-These can be set either as environment variables or directly on the `rake` command line.
+These values can be set as standard environment variables or passed directly to the `rake` command.
 
-Setting `SIGNING_KEY_PEM` creates file `$HOME/.gem/signing_key.pem` and sets `SIGNING_KEY`.
+Setting `SIGNING_KEY_PEM` automatically generates a file at `$HOME/.gem/signing_key.pem` and sets the `SIGNING_KEY` variable accordingly.
 
 > [!NOTE]
-> Environment variables `ASPERA_CLI_*` are typically set in the user’s shell profile for development.
-> Others are intended for use on the command line.
+> `ASPERA_CLI_*` variables are typically defined in your shell profile for development, while others are intended for ad-hoc command-line use.
 
-To use the CLI directly from the development environment, add this to your shell profile (adapt the real path):
+To run the CLI directly from your source directory, add the following to your shell profile (adjust the path as necessary):
 
 ```bash
 dev_ascli=$HOME/github/aspera-cli
@@ -134,39 +135,46 @@ export RUBYLIB=$dev_ascli/lib:$RUBYLIB
 
 Documentation is generated with `pandoc` and `LaTeX`.
 
-The IBM `Plex` font is used; for installation instructions, see [IBM Plex](https://www.ibm.com/plex/).
+The project utilizes the **IBM Plex font**.
+Installation instructions can be found at [IBM Plex](https://www.ibm.com/plex/).
 
-On macOS, to install `lualatex` and all packages:
+On macOS, install `lualatex` and required packages via Homebrew:
 
 ```bash
 brew install texlive
 ```
 
-If `lualatex` is installed using another method, ensure that the following packages are installed:
+If using an alternative installation method, ensure the following packages are present:
 
 ```bash
 tlmgr update --self
 tlmgr install fvextra selnolig lualatex-math
 ```
 
-To check URLs during documentation generation, set the environment variable: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
+- To validate URLs during generation: `ASPERA_CLI_DOC_CHECK_LINKS=1`.
+
+- To debug the generation process: `ASPERA_CLI_DOC_DEBUG=debug`.
 
-To debug documentation generation, set the environment variable: `ASPERA_CLI_DOC_DEBUG=debug`.
+- To build the documentation:
+
+```bash
+rake doc:build
+```
 
 ## Test Environment
 
-Refer to <tests/README.md>.
+Detailed testing information can be found in <tests/README.md>.
 
 ## Build
 
-The unsigned gem is built with:
+To build an unsigned gem:
 
 ```bash
 bundle install
 bundle exec rake unsigned
 ```
 
-If you don't want to install optional gems:
+To exclude optional gems from the installation:
 
 ```bash
 bundle config set without optional
@@ -174,35 +182,34 @@ bundle config set without optional
 
 ### Signed gem
 
-A private key is required to generate a signed gem.
-Its path must be set using environment variable `SIGNING_KEY`.
-The gem is signed with the public certificate found in `certs` and the private key specified by `SIGNING_KEY` (kept secret by the maintainer).
+Generating a signed gem requires a **private key**, specified via the `SIGNING_KEY` environment variable.
+The gem is signed using the public certificate in `certs` and the **private key**.
 
 ```bash
 bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
-Refer to <certs/README.md>.
+For more details, see <certs/README.md>.
 
-### gRPC stubs for transfer SDK
+### gRPC stubs for Transfer SDK
 
-Update with:
+To update the stubs:
 
 ```bash
 bundle exec rake tools:grpc
 ```
 
-It downloads the latest `proto` file and then compiles it.
+This task downloads the latest `.proto` files and compiles them into the Ruby source files included in the repository.
 
 ## Container image build
 
-See [Container build](./container/README.md).
+Refer to the [Container build guide](./container/README.md).
 
 ## Single executable build
 
-See [Executable build](build/binary/README.md).
+Refer to the [Executable build guide](build/binary/README.md).
 
-To list operations:
+To list related `rake` tasks:
 
 ```bash
 bundle exec rake -T ^binary:
@@ -212,85 +219,89 @@ 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 maintains a single `main` branch.
+During development, the version in `lib/aspera/cli/version.rb` includes a `.pre` suffix (e.g., `x.y.z.pre`).
+
+Contributions are handled as follows:
 
-Feature development and bug fixes can be done either:
+- **Direct commits** to `main`: Permitted for minor changes.
 
-- Directly on `main` for small changes
-- Via feature branches with pull requests for larger changes
+- **Feature branches**: Required for significant changes via pull requests.
 
-### Checklist Before a New Release
+### Pre-Release Checklist
 
-When preparing for a new release, do the following:
+Before a new release, ensure the following:
 
-- Run the test suite:
+- **Pass all tests**:
 
 ```bash
 bundle exec rake test:run
 ```
 
-- Verify that the container builds successfully (using the beta version):
+- **Verify container builds** (using the local gem):
 
 ```bash
-bundle exec rake container:build
+bundle exec rake container:build'[local]'
 bundle exec rake container:test
 ```
 
 ### Automated Release Process
 
-Releases are triggered via the GitHub Actions UI using the **Release** workflow (`.github/workflows/release.yml`).
+Releases are managed through the GitHub Actions UI via the **New Release on GitHub** workflow (`.github/workflows/release.yml`).
+
+1. Navigate to **Actions** > **New Release on GitHub**
+2. Select **Run workflow**
+3. (Optionally) Specify:
+   - **Release version**: Defaults to the current `version.rb` value (minus the `.pre` suffix).
 
-To create a release:
+     e.g. current `a.b.c.pre` &rarr; `a.b.c`.
+   - **Next development version**: Defaults to an incremented minor version with the `.pre` suffix.
 
-1. Navigate to **Actions** > **Release** in the GitHub repository
-2. Click **Run workflow**
-3. Optionally specify:
-   - **Release version**: The version to release. If left empty, uses the current version from `version.rb` without the `.pre` suffix.
-   - **Next development version**: The next version to prepare for. If left empty, auto-increments the minor version. The `.pre` suffix is added automatically.
+     e.g. release `a.b.c` &rarr; `a.(b+1).0.pre`.
 4. Click **Run workflow**
 
-The workflow automatically:
+The automated workflow performs the following:
 
-1. Updates `version.rb` with the release version
-2. Rebuilds documentation (PDF manual, README)
+1. Updates `version.rb` to the release version
+2. Rebuilds all documentation (PDF and Markdown)
 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
+6. Increments `version.rb` to the next development version.
+7. Commits and pushes the version bump to `main`.
 
 ### Manual Release Process (Alternative)
 
-If needed, releases can still be done manually:
+If necessary, you can mirror the automated process manually:
 
 - Update the version in `lib/aspera/cli/version.rb` (remove `.pre` suffix)
 
-- Build the PDF manual in `pkg`:
+- Build the PDF manual:
 
 ```shell
 bundle exec rake doc:build
 ```
 
-- Build the signed `.gem` in `pkg`:
+- Build the signed gem:
 
 ```shell
 bundle exec rake SIGNING_KEY=/path/to/vault/gem-private_key.pem
 ```
 
-- Create the release version tag and push it to GitHub:
+- Tag the release and push to GitHub:
 
 ```shell
 bundle exec rake release_tag
 ```
 
-This will trigger the action `.github/workflows/deploy.yml`, which builds the gem file and pushes it to RubyGems.
+This triggers the `.github/workflows/deploy.yml` action to publish to RubyGems.
 
-- After release, update `version.rb` to the next development version with `.pre` suffix
+- Update `version.rb` to the next `.pre` development version.
 
 ## Future Improvements
 
-- Replace custom REST and OAuth classes with standard Ruby gems ?
-  - <https://github.com/rest-client/rest-client>
-  - <https://github.com/oauth-xx/oauth2>
-- Use the `thor` gem <http://whatisthor.com/> (or other standard Ruby CLI manager)
-- Look at <https://github.com/phusion/traveling-ruby>
+- Evaluate replacing custom REST and OAuth implementations with standard gems:
+  - [rest-client](https://github.com/rest-client/rest-client)
+  - [oauth2](https://github.com/oauth-xx/oauth2)
+- Integrate `thor` <http://whatisthor.com/> or another standard Ruby CLI framework.
+- Explore [Traveling Ruby](https://github.com/phusion/traveling-ruby) for distribution.

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,13 @@ 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
+        # @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: {})
           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 +176,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)
+            RestParameters.instance.spinner_cb.call("#{item_list.count} / #{total_count}") unless total_count.eql?(item_list.count.to_s)
           end
-          formatter&.long_operation_terminated
+          RestParameters.instance.spinner_cb.call(action: :success)
           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
@@ -299,10 +301,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) do |paged_query|
           read(subpath, query: paged_query, ret: :both)
         end
       end
@@ -710,7 +714,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/cos_node.rb

@@ -10,6 +10,7 @@ module Aspera
     class CosNode < Node
       IBM_CLOUD_TOKEN_URL = 'https://iam.cloud.ibm.com/identity'
       TOKEN_FIELD = 'delegated_refresh_token'
+      FASP_INFO_KEYS = %w[ATSEndpoint AccessKey].freeze
       class << self
         def parameters_from_svc_credentials(service_credentials, bucket_region)
           # check necessary contents
@@ -60,6 +61,9 @@ module Aspera
         ).body
         ats_info = XmlSimple.xml_in(xml_result_text, {'ForceArray' => false})
         Log.dump(:ats_info, ats_info)
+        Aspera.assert_hash_all(ats_info, String, nil){'ats_info'}
+        Aspera.assert((FASP_INFO_KEYS - ats_info.keys).empty?){'ats_info missing required keys'}
+        Aspera.assert_hash_all(ats_info['AccessKey'], String, String){'ats_info'}
         @storage_credentials = {
           'type'  => 'token',
           'token' => {TOKEN_FIELD => nil}

data/lib/aspera/api/faspex.rb

@@ -60,25 +60,38 @@ 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
       PATH_STANDARD_ROOT = '/aspera/faspex'
       PATH_API_DETECT = "#{PATH_API_V5}/#{PATH_HEALTH}"
-      HEADER_ITERATION_TOKEN = 'X-Aspera-Next-Iteration-Token'
+      HEADER_X_NEXT_ITER_TOKEN = 'X-Aspera-Next-Iteration-Token'
       HEADER_FASPEX_VERSION = 'X-IBM-Aspera'
       EMAIL_NOTIF_LIST = %w[
         welcome_email
@@ -114,9 +127,24 @@ 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
 
+      # @param url             Faspex URL, can be a public link
+      # @param auth            Authentication method: :boot (token in header), :web (open browser), :jwt (client_id + private key), :public_link (context in URL)
+      # @param password        For :boot auth, the token copied directly from browser in developer mode
+      # @param client_id       For :web and :jwt auth, the client_id of web UI application
+      # @param client_secret   For :web auth, the client_secret of web UI application (not needed for :jwt)
+      # @param redirect_uri    For :web auth, the redirect_uri of web UI application (must be the same as in application configuration)
+      # @param username        For :jwt auth, the username of the user to impersonate
+      # @param private_key     For :jwt auth, the private key to sign JWT token
+      # @param passphrase      For :jwt auth, the passphrase of the private key
       def initialize(
         url:,
         auth:,