feat: add --wait flag to async Cloud operations that return task IDs

[joshrotenberg]

Summary

Add a --wait flag to all Cloud CLI commands that trigger asynchronous operations and return task IDs. This would allow users to wait for operations to complete without having to manually run separate task commands.

Background

Many Cloud API operations are asynchronous and return task IDs. Currently, users must:

1. Run the operation (e.g., create database)
2. Note the returned task ID
3. Run redisctl cloud task wait <task-id> separately

This enhancement would streamline the workflow by allowing operations to optionally wait for completion.

Operations That Need --wait Flag

Based on analysis of the Cloud API, these operations return TaskStateUpdate or similar responses with task IDs:

Database Operations

• cloud database create - Creating databases is async
• cloud database update - Updates can be async
• cloud database delete - Deletion is async
• cloud database backup - Backup operations are async
• cloud database import - Import operations are async

Subscription Operations

• cloud subscription create - Creating subscriptions
• cloud subscription update - Updating subscriptions
• cloud subscription delete - Deleting subscriptions

Fixed Subscription Operations

• cloud fixed-subscription create - Creating fixed subscriptions
• cloud fixed-subscription update - Updating fixed subscriptions
• cloud fixed-subscription delete - Deleting fixed subscriptions

Fixed Database Operations

• cloud fixed-database create - Creating fixed databases
• cloud fixed-database update - Updating fixed databases
• cloud fixed-database delete - Deleting fixed databases
• cloud fixed-database backup - Backup operations
• cloud fixed-database import - Import operations

ACL Operations

• cloud acl create-redis-rule - Creating ACL rules
• cloud acl update-redis-rule - Updating ACL rules
• cloud acl delete-redis-rule - Deleting ACL rules
• cloud acl create-role - Creating ACL roles
• cloud acl update-role - Updating ACL roles
• cloud acl delete-role - Deleting ACL roles
• cloud acl create-user - Creating ACL users
• cloud acl update-user - Updating ACL users
• cloud acl delete-user - Deleting ACL users

User Operations

• cloud user delete - Deleting users returns task ID

Cloud Provider Account Operations

• cloud provider-account create - Creating cloud accounts
• cloud provider-account update - Updating cloud accounts
• cloud provider-account delete - Deleting cloud accounts

Connectivity Operations (when implemented)

• VPC Peering create/update/delete
• Private Service Connect operations
• Transit Gateway operations

Implementation Approach

1. Add Flag to Commands

Add --wait flag to relevant command enums:

Create {
    // ... existing fields ...
    
    /// Wait for operation to complete
    #[arg(long)]
    wait: bool,
    
    /// Maximum time to wait in seconds (default: 300)
    #[arg(long, default_value = "300", requires = "wait")]
    wait_timeout: u64,
}

2. Extract Task ID from Response

Operations that return ProcessorResponse or TaskStateUpdate should extract task_id:

let response = client.create_database(&request).await?;
if let Some(task_id) = response.task_id {
    if wait {
        wait_for_task(&client, &task_id, wait_timeout).await?;
    }
}

3. Reuse Existing Task Wait Logic

Leverage the existing task wait implementation from task.rs:

use crate::commands::cloud::task::wait_for_task;

4. Show Progress

When waiting, show progress indicator:

$ redisctl cloud database create --data @config.json --wait
Creating database...
⠙ Waiting for task abc-123: processing [00:00:12]
✓ Task completed successfully [00:00:45]
Database created: db-456

Benefits

1. Improved UX - Single command instead of two-step process
2. Script-friendly - Operations can block until complete
3. Error handling - Immediate feedback if operation fails
4. Consistency - Similar to kubectl's --wait flag

Testing Considerations

• Test with operations that complete quickly
• Test with long-running operations (timeout scenarios)
• Test interrupt handling (Ctrl+C during wait)
• Verify non-blocking behavior when --wait is not specified

Documentation Updates

• Update command help text to mention --wait option
• Add examples showing --wait usage
• Document timeout behavior
• Note which operations support --wait

Future Enhancements

• Consider adding --wait-condition for waiting on specific states
• Add --no-wait to override any future default wait behavior
• Support --wait-interval for custom polling intervals