aspera-cli 4.20.0 → 4.21.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3fb5a0fc5c22da5479bff1858e9bedd7188e7622c751f7560af1f0ce318fffc9
-  data.tar.gz: 22cb2c17972d50bc198a63cce4c8a29dbb52dc184fa1ffda6a220cd793ef4e28
+  metadata.gz: 3d66238170234ebc23390a21ef7a492ec50c8707200c774ef2f3195fdb13261f
+  data.tar.gz: 47623d1ce5961c1d1050989e36afeb1e008dc24c3b81d34d5b484f39d0826107
 SHA512:
-  metadata.gz: 3e468ed7fae059b54a56402bf4a1e414eb28cfe527325f22f645b9bfe754ba2a2084298186b6a0afceef8698e87a914045132c1126ab39d7b75163dc50d4440f
-  data.tar.gz: 4c774e429d9b364b3e5382873e4926fecd355b2d5504af30a7ce5814cc556c5686c50c309ba10f89ba5e1e6666651fcd195266d043d27be5cc77f9abad4735e3
+  metadata.gz: dfa7a18bfa476bfda979e88017bf643ef181ecd643f53a6872f7b0af833c6e2dc46700d5afc913126942cda6eb0804f7332b5555e8054ab1d9dba97873000e6e
+  data.tar.gz: 2a598cd0d4aab0fb8ec6e2660f590d78fd41a62870f554f96f26069cf0499753dcedb30f807691d8156441340dbbed2910f560b29d1e6e5bbedfd7416f542825

data/CHANGELOG.md

@@ -1,15 +1,53 @@
 # Changes (Release notes)
 
+* 4.21.2
+
+  * New Features:
+    * **container**: Updated Ruby to 3.4.2
+  * Issues Fixed:
+    * **global**: #185 `@val:` shall stop processing extended values
+    * **global**: #186 Removed dependency on openssl 3.3 gem to avoid msys dep on Windows.
+    * `echo`: Display of list (Array) was showing only first element of it.
+    * `transferd`: support for version 1.1.5+
+  * Breaking Changes:
+    * `preview`: Updated Image Magick to v7+
+    * `aoc`: `admin subscription` split into `admin subscription account` and `admin subscription usage`
+    * **agent**: `alpha` renamed to `desktop`
+
+* 4.21.1
+
+  * New Features:
+    * `config`: New command: `transferd` to list and install specific version of `asperatransferd` and `ascp`
+    * `config`: New command: `tokens` with `list`, `show`, `flush` (replace `flush_tokens`)
+    * `faspex5`: New command: `admin contact reset_password`
+    * `aoc`: #178 packages can be browsed, and individual files can be downloaded now.
+  * Issues Fixed:
+    * `config`: #175 `ascli config preset set GLOBAL version_check_days 0` causes a bad `config.yaml` to be written
+    * `config`: #180 problem in `ascp install`
+    * `config`: Soft links in transfer SDK archive are correctly extracted
+    * `aoc`: #184 token cache shall be different per aoc org.
+    * `aoc`: Fix `packages delete` not working.
+    * `direct` agent: #174 Race condition fix with `ascp`: timeout waiting mgt port connect (select not readable)
+    * `preview`: #177 fix bug that prevents preview generation to work.
+  * Breaking Changes:
+    * `transferd`: Use of Aspera Transfer Daemon requires minimum version 1.1.4. agent `trsdk` renamed `transferd`.
+    * `ascp`: Default SDK version is now 1.1.4. Removes support for ascp4.
+    * `node`: Removed deprecated command prefix `exec:`, use `@ruby:` instead.
+    * **global**: Now uses openssl 3.
+    * **global**: Ruby minimum versions is now 3.1 (mainly due to switch to openssl 3). Future minimum is 3.2. Recommended is 3.4. (that removes macOS default ruby support. Newer Ruby version shall be installed on macOS with `brew`)
+    * **global**: Options `transpose_single` and `multi_table` replaced with single option `multi_single` and values: `no`, `yes`, `single`.
+    * **global**: Column name for single object is now `field` instead of `key`.
+
 * 4.20.0
 
-  ATTENTIION: Due to the fact that Faspex version 4 is end of support, the `faspex` command will be deprecated. Use Faspex 5 from now.
+  ATTENTION: [Faspex version 4 is now end of support](https://www.ibm.com/support/pages/lifecycle/search?q=faspex): the `faspex` plugin will be deprecated. Servers shall be upgraded to Faspex 5, and users use plugin `faspex5`.
 
   * New Features:
     * `aoc`: Improved usability for creation of Admin shared folders.
     * `node`: New option `node_cache` (bool) for gen4 operations.
     * `node`: Option `root_id` now works always for node gen4, as well as `%id:` for file selection in addition to path.
-    * `node`: `transfer list` now uses the `iteratin_token` to retrieve all values. Option `once_only` is now supported.
-    * `global` : option `http_options` now include retry options.
+    * `node`: `transfer list` now uses the `iteration_token` to retrieve all values. Option `once_only` is now supported.
+    * **global**: option `http_options` now include retry options.
   * Issues Fixed:
     * `aoc`: Fixed `find` command not working. (undefined variable)
     * `aoc`: #165 aoc mkdir now follows the last link of containing folder

data/CONTRIBUTING.md

@@ -9,34 +9,34 @@ Before you go ahead please search existing issues for your problem.
 To make sure that we can help you quickly please include and check the following information:
 
 - Include the `ascli` version you are running in your report.
-- If you are not running the latest version (please check), update.
+- If you are not running the latest version (please check) then update.
 - Include your `ruby -e "puts RUBY_DESCRIPTION"`.
 
 Thanks!
 
 ## Making Contributions
 
-To fetch & test the gem for development, do:
+To fetch and test the gem for development, do:
 
 ```bash
 git clone https://github.com/IBM/aspera-cli.git
 cd aspera-cli
-bundle install
-make test
 ```
 
+Then see [Running Tests](#running-tests).
+
 If you want to contribute, please:
 
 - Fork the project.
 - Make your feature addition or bug fix.
 - Add tests for it. This is important so I don't break it in a future version unintentionally.
-- **Bonus Points** go out to anyone who also updates `CHANGELOG.md` :)
+- Run `rubocop` to comply for coding standards
+- Update `CHANGELOG.md`
 - Send a pull request on GitHub.
-- run `rubocop` to comply for coding standards
 
 ## Architecture
 
-A list of classes are provided in <docs/ml.png>
+A list of classes are provided in <docs/uml.png>
 
 Architecture:
 
@@ -46,22 +46,49 @@ The entry point is: `lib/aspera/cli/main.rb`.
 
 Plugins are located in: `lib/aspera/cli/plugins`.
 
-Transfer agents, in: `lib/aspera/fasp`.
+Transfer agents, in: `lib/aspera/agent`.
 
 ## Ruby version
 
-Install ruby with [RVM](https://rvm.io).
+Install Ruby using your prefered method.
 
-Cleanup installed gems in `rvm` to start fresh:
+To cleanup installed gems to start fresh:
 
 ```bash
-make cleanup_gems
+make clean_gems
 ```
 
 ## Tool chain
 
 TODO: document installation of tool chain.
 
+Build system uses GNU Make.
+
+### Environment
+
+A few macros/envvars control some aspects:
+
+| macro                       | description                          |
+|-----------------------------|--------------------------------------|
+| `ASPERA_CLI_TEST_CONF_FILE` | Path to configuration file with secrets for tests |
+| `ASPERA_CLI_TEST_MACOS`     | Set to `true` if local HSTS running on macOS      |
+| `ASPERA_CLI_TEST_PRIVATE`   | Path to private folder               |
+| `ENABLE_COVERAGE`           | Tests with coverage analysis if set. |
+| `SIGNING_KEY`               | Path to signing key to build Gem.    |
+| `GEM_VERSION`               | Gem version to build container       |
+
+Those macros can be set either in an env var, or on the `make` command line.
+
+> **Note:** vars `ASPERA_CLI_TEST_` are typically set in user's shell profile.
+
+To use the CLI directly from the development environment, add this to your shell profile:
+
+```bash
+dev_ascli=$HOME/github/aspera-cli
+export PATH=$dev_ascli/bin:$PATH
+export RUBYLIB=$dev_ascli/lib:$RUBYLIB
+```
+
 ### Documentation
 
 Documentation is generated with `pandoc` and `LaTeX`.
@@ -83,7 +110,8 @@ tlmgr install fvextra selnolig lualatex-math
 
 ## Running Tests
 
-First, a testing configuration file must be created, from project top folder:
+First, a testing configuration file must be created.
+From project top folder, execute:
 
 ```bash
 mkdir ~/some_secure_folder
@@ -104,7 +132,7 @@ This project uses a `Makefile` for tests:
 make test
 ```
 
-When new commands are added to the CLI, new tests shall be added to the test suite.
+When new commands are added to the CLI, new tests shall be added to the test suite in `tests/Makefile`.
 
 ### Special tests
 
@@ -121,110 +149,40 @@ To run every test: `make full`
 
 For preparation of a release, do the following:
 
-1. Select a ruby version to test with: `rvm use 3.2.2`
+1. Select a ruby version to test with.
 2. Remove all gems: `make clean_gems`
-3. Starts tests: `make test`
-4. Install optional gems: `make install_optional_gems`
-5. Test remaining cases: `cd tests` and then `make optional` and `make interactive`
-
-This ensures that optional gems do not prevent `ascli` to run.
+3. `cd tests && make full`
 
 To test additional Ruby version, repeat the procedure with other Ruby versions.
 
 ## Coverage
 
 A coverage report can be generated in folder `coverage` using gem `SimpleCov`.
-Enable coverage monitoring using env var `ENABLE_COVERAGE`.
+Enable coverage monitoring using macro/envvar `ENABLE_COVERAGE`.
 
 ```bash
-ENABLE_COVERAGE=1 make test
+cd tests
+make ENABLE_COVERAGE=1
 ```
 
 Once tests are completed, or during test, consult the page: [coverage/index.html](coverage/index.html)
 
 ## Build
 
-By default the gem is built signed: `make`.
-The appropriate signing key is required, and its path must be set to env var `SIGNING_KEY`.
-It is also possible to build a non-signed version for development purpose: `make unsigned_gem`.
-
-### Gem Signature
-
-Refer to:
-
-- <https://guides.rubygems.org/security/>
-- <https://ruby-doc.org/current/stdlibs/rubygems/Gem/Security.html>
-- `gem cert --help`
-
-Then procedure is as follows:
-
-- The maintainer creates the initial certificate and a private key:
-
-  ```bash
-  cd /path/to/vault
-  gem cert --build maintainer@example.com
-  ```
-
-  > **Note:** The email must match the field `spec.email` in `aspera-cli.gemspec`
-
-  This creates two files in folder `/path/to/vault` (e.g. $HOME/.ssh):
-  
-  - `gem-private_key.pem` : This file shall be kept secret in a vault.
-  - `gem-public_cert.pem` : This file is copied to a public place, here in folder `certs`
-
-  > **Note:** Alternatively, use an existing key or generate one, and then `make new-cert`
-
-- The maintainer builds the signed gem.
-
-  The gem is signed with the public certificate found in `certs` and the private key (kept secret by maintainer).
-
-  To build the signed gem:
-
-  ```bash
-  SIGNING_KEY=/path/to/vault/gem-private_key.pem make
-  ```
-
-- The user can activate gem signature verification on installation:
-
-  Add the certificate to gem trusted certificates:
-
-  ```bash
-  curl https://raw.githubusercontent.com/IBM/aspera-cli/main/certs/aspera-cli-public-cert.pem -so aspera-cli-certificate.pem
-  gem cert --add aspera-cli-certificate.pem
-  rm aspera-cli-certificate.pem
-  ```
-
-  - The user installs the gem with `HighSecurity` or `MediumSecurity`: this will succeed only of the gem is trusted.
+By default, the gem is built signed: `make`.
+A private key is required to generate a signed Gem.
+Its path must be set using macro/envvar `SIGNING_KEY`, see below.
+The gem is signed with the public certificate found in `certs` and the private key (kept secret by maintainer).
 
-  ```bash
-  gem install -P HighSecurity aspera-cli
-  ```
-
-  - The maintainer can renew the certificate when it is expired using the same private key:
-
-  ```bash
-  SIGNING_KEY=/path/to/vault/gem-private_key.pem make update-cert
-  ```
-
-  Alternatively, to generate a new certificate with the same key:
-
-  ```bash
-  SIGNING_KEY=/path/to/vault/gem-private_key.pem make new-cert
-  ```
-
-  - Show the current certificate contents
-
-  ```bash
-  make show-cert
-  ```
+```bash
+make SIGNING_KEY=/path/to/vault/gem-private_key.pem
+```
 
-  > Note: to provide a passphrase add argument: `-passin pass:_value_` to `openssl`
+It is also possible to build an unsigned version for development purpose: `make unsigned_gem`.
 
-  - Check that the signing key is the same as used to sign the certificate:
+### Gem Signature
 
-  ```bash
-  SIGNING_KEY=/path/to/vault/gem-private_key.pem make check-cert-key
-  ```
+Refer to <certs/README.md>
 
 ### gRPC stubs for transfer SDK
 
@@ -234,54 +192,16 @@ Update with:
 make grpc
 ```
 
-## Docker image build
-
-The `Dockerfile.tmpl.erb` template allows customization of the optional copying of the `aspera-cli.gem` file, as opposed to installing from rubygems.org. It also supports customizing the retrieval of the SDK.
-
-### Default image build
-
-Build the image:
-
-```bash
-make docker
-```
-
-This does the following:
-
-- Install the official gem version directly from <rubygems.org>.
-- Build the image for the version number in the current repository
-- creates tags for both the version and `latest`
-
-> **Note:** This target creates the `Dockerfile` from an `ERB` (embedded Ruby) template (Makefile target `dockerfile`).
-A template is used as it allows some level of customization to tell where to take the gem from, as as for the SDK file.
-
-Then, to push to the image registry (both tags: version and `latest`):
+It downloads the latest proto file and then compiles it.
 
-```bash
-make docker_push
-```
+## Container image build
 
-### Specific version image build
+See [Container build](./container/README.md).
 
-To build a specific version: override `make` macro `GEM_VERSION`:
+For operations, move to the folder:
 
 ```bash
-make docker GEM_VERSION=4.11.0
-make docker_push GEM_VERSION=4.11.0
-```
-
-> **Note:** This does not use the locally generated gem file.
-Only the local docker file is used.
-The gem is installed from rubygems.org. This also sets the `latest` tag.
-
-### Development version image build
-
-To build/push a beta/development container:
-it does not create the `latest` tag, it uses the gem file generated locally with a special version number.
-
-```bash
-make docker_beta
-make docker_push_beta
+cd container
 ```
 
 ## Single executable build
@@ -293,9 +213,16 @@ Initially, `rubyc` (gem [`ruby-packer`](https://github.com/pmq20/ruby-packer) an
 A modern version of this is now used: [`tebako`](https://github.com/tamatebako/tebako) for which a container is provided.
 
 ```bash
-make single GEM_VERSION=4.11.0
+cd binary
+make GEM_VERSION=4.11.0
 ```
 
+## Development check list for new release
+
+When preparing for a new release do the following:
+
+- TODO
+
 ## Long Term Implementation and delivery improvements
 
 - replace rest and oauth classes with ruby standard gems: