CLI-822: Add --task-wait option to API commands

[danepowell]

Motivation

Fixes CLI-822

Proposed changes

Add a --task-wait option to API commands that return a notification which will cause the command to wait for the notification to complete.

Testing steps

1. Follow the contribution guide to set up your development environment or download a pre-built acli.phar for this PR.
2. Clear the kernel cache to pick up new and changed commands: ./bin/acli ckc
3. Check the help for a command that returns notifications, see it includes the --task-wait option: wacli help api:environments:code-switch
4. Check for regressions: Run a passing command without the --task-wait option, see it behaves like before: wacli api:environments:code-switch pipelinesvalidation2.dev master
5. Check for regressions: Run a failing command without the --task-wait option, see it still fails: wacli api:environments:database-backup-create --task-wait eeepeterson.dev eeepeterson3
6. Check new functionality: Run the command with --task-wait, see it waits for the task to complete: wacli api:environments:code-switch pipelinesvalidation2.dev master --task-wait

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 92.64%. Comparing base (a5acd1d) to head (15f20c3).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1829   +/-   ##
=========================================
  Coverage     92.64%   92.64%           
- Complexity     1833     1837    +4     
=========================================
  Files           123      123           
  Lines          6946     6952    +6     
=========================================
+ Hits           6435     6441    +6     
  Misses          511      511           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[github-actions]

Try the dev build for this PR: https://acquia-cli.s3.amazonaws.com/build/pr/1829/acli.phar

curl -OL https://acquia-cli.s3.amazonaws.com/build/pr/1829/acli.phar
chmod +x acli.phar

[danepowell]

@eporama can you take this for a spin and let me know what you think? Right now you'll get output like this:

{
    "message": "Switching code.",
    "notification": "fd447bb3-35f4-49ce-9ab8-6cc6bdbd4e3a",
    "_links": {
        "self": {
            "href": "https:\/\/cloud.acquia.com\/api\/environments\/32859-2ed281d4-9dec-4cc3-ac63-691c3ba002c2\/code\/actions\/switch"
        },
        "notification": {
            "href": "https:\/\/cloud.acquia.com\/api\/notifications\/fd447bb3-35f4-49ce-9ab8-6cc6bdbd4e3a"
        }
    }
}
    ✔ Waiting for task fd447bb3-35f4-49ce-9ab8-6cc6bdbd4e3a to complete


 [OK] The task with notification uuid fd447bb3-35f4-49ce-9ab8-6cc6bdbd4e3a completed


Progress: 100
Completed: Fri Nov 15 20:27:29 UTC 2024
Task type: Code switched
Duration: 24 seconds

It's a little weird because API commands normally return JSON output. If you add --task-wait, to me it implies you want human-readable output (not JSON). But maybe folks prefer to see the JSON still?

And then the command exit code becomes the notification status (success/failure) rather than the initial API response (202/40x). That seems intuitive to me but I'm not sure if it needs to be documented.

[eporama]

 ./acli.phar api:environments:database-backup-create --task-wait eeepeterson.dev eeepeterson
{
    "message": "Creating the backup.",
    "_links": {
        "self": {
            "href": "https:\/\/cloud.acquia.com\/api\/environments\/5393-3580d1ec-cf2b-1624-5d85-0d28ecd9a69a\/databases\/eeepeterson\/backups"
        },
        "parent": {
            "href": "https:\/\/cloud.acquia.com\/api\/environments\/5393-3580d1ec-cf2b-1624-5d85-0d28ecd9a69a\/databases\/eeepeterson"
        },
        "notification": {
            "href": "https:\/\/cloud.acquia.com\/api\/notifications\/98cfb851-7c94-40e2-a321-27b8dd2924ba"
        }
    }
}
    ✔ Waiting for task 98cfb851-7c94-40e2-a321-27b8dd2924ba to complete


 [OK] The task with notification uuid 98cfb851-7c94-40e2-a321-27b8dd2924ba completed


Progress: 100
Completed: Mon Nov 18 19:07:10 UTC 2024
Task type: Database backup created
Duration: 15 seconds

I agree that the output is a bit odd with the mixture of json and command. Personally, I don't need to see the JSON of a successfully submitted task, but would like to see the failure messages when the submission fails:

 ./acli.phar api:environments:database-backup-create --task-wait eeepeterson.dev eeepeterson3
{
    "error": "validation_failed",
    "message": {
        "database": "The database does not exist in this environment."
    }
}

In CommandBase.php line 1903:

  JSON object must contain the _links.notification.href property


api:environments:database-backup-create [--task-wait] [--] <environmentId> <databaseName>



 [help] You can find Acquia CLI documentation at https://docs.acquia.com/acquia-cli/

        You can submit a support ticket at https://support-acquia.force.com/s/contactsupport
        Re-run the command with the -vvv flag and include the full command output in your support ticket.

I think we should trap for the error and

In CommandBase.php line 1903:

  JSON object must contain the _links.notification.href property

seems like our problem

[eporama]

Easier to read 👍

$ ./acli.phar api:environments:database-backup-create --task-wait eeepeterson.swat eeepeterson
    ✔ Waiting for task f735b1fc-fc14-44fc-bcd2-5767d7e09ccd to complete


 [OK] The task with notification uuid f735b1fc-fc14-44fc-bcd2-5767d7e09ccd completed


Progress: 100
Completed: Tue Nov 19 16:09:46 UTC 2024
Task type: Database backup created
Duration: 28 seconds

I wonder if it would be possible to have a different wait mechanism for scripting which doesn't output the spinner and just finishes with the json of the notification once it's complete. --non-interactive or --format=json or something? Happy to have that be a follow up as well if we want to get this out.

Looks like the error message is more concise as well 👍

$ ./acli.phar api:environments:database-backup-create --task-wait eeepeterson.swat eeepeterson3
{
    "error": "validation_failed",
    "message": {
        "database": "The database does not exist in this environment."
    }
}

[danepowell]

The spinner still behaves gracefully in a non-interactive environment and you could just check the exit code (ignore the output) if that's all you care about. Maybe take this for a spin and if you still think we need different non-interactive behavior we can talk.