feat: add --wait flag to cluster key create command (#73)

* feat: add --wait flag to cluster key create command

API key creation is not transactional — it takes time for a newly created
key to propagate to the Qdrant cluster. The --wait flag polls the cluster's
REST endpoint using the new key until it gets a successful response,
confirming the key is active.

Flags added:
- --wait: opt-in to waiting for key activation
- --wait-timeout (default 1m): maximum time to wait
- --wait-poll-interval (default 1s, hidden): polling frequency

Made-with: Cursor

* fix: resolve lint issues in key create wait implementation

- Suppress errcheck on best-effort resp.Body.Close() in probe
- Remove unused *httptest.Server return from test helper

Made-with: Cursor

* fix: move endpoint resolution into wait poll loop

A key can be created before the cluster has an endpoint (e.g. cluster
still provisioning). Instead of failing early when no endpoint exists,
the probe now calls GetCluster on each poll iteration and keeps retrying
until the endpoint appears and the key is accepted.

Made-with: Cursor

* fix: address PR review feedback

- Make HTTP error in probe more descriptive: include status code and URL
- Use standard Go error-first checking in waitForKeyReady (if err != nil
  + continue) instead of positive nil check
- Print the probe error in the progress message so users can see why the
  key is not yet active (e.g. no endpoint, HTTP 403, etc.)

Made-with: Cursor

* refactor: extract magic port number into defaultQdrantRESTPort const

Made-with: Cursor

* refactor: use dedicated HTTP client with safe timeouts for key probe

Replace http.DefaultClient with a purpose-built client configured
outside the closure with explicit timeouts (10s overall, 5s TLS
handshake, 5s response header).

Made-with: Cursor

* fix: drop redundant http.Client.Timeout, rely on context deadline

The per-request context already carries the user's --wait-timeout
deadline. A separate client-level Timeout is redundant and could
confuse readers. Transport-level timeouts (TLS handshake, response
header) are kept since they guard specific connection phases.

Made-with: Cursor

---------

Co-authored-by: Qdrant Claw <[email protected]>

Author: qdrant-cloud-bot

internal/cmd/cluster/key_create.go

@@ -1,14 +1,17 @@
 package cluster
 
 import (
+	"context"
 	"fmt"
 	"io"
+	"net/http"
 	"time"
 
 	"github.com/spf13/cobra"
 	"google.golang.org/protobuf/types/known/timestamppb"
 
 	clusterauthv2 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/auth/v2"
+	clusterv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/v1"
 
 	"github.com/qdrant/qcloud-cli/internal/cmd/base"
 	"github.com/qdrant/qcloud-cli/internal/cmd/completion"
@@ -23,7 +26,11 @@ qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe --name my-key
 
 # Create a read-only key with expiration
 qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe \
-  --name read-key --access-type read-only --expires 2025-12-31`,
+  --name read-key --access-type read-only --expires 2025-12-31
+
+# Create a key and wait for it to become active on the cluster
+qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe \
+  --name my-key --wait`,
 		BaseCobraCommand: func() *cobra.Command {
 			cmd := &cobra.Command{
 				Use:   "create <cluster-id>",
@@ -33,6 +40,10 @@ qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe \
 			cmd.Flags().String("name", "", "Name of the API key (required)")
 			cmd.Flags().String("access-type", "", "Access type: manage or read-only (default: server assigns manage)")
 			cmd.Flags().String("expires", "", "Expiration date in YYYY-MM-DD format")
+			cmd.Flags().Bool("wait", false, "Wait for the API key to become active on the cluster")
+			cmd.Flags().Duration("wait-timeout", time.Minute, "Maximum time to wait for the API key to become active")
+			cmd.Flags().Duration("wait-poll-interval", time.Second, "How often to probe the cluster endpoint")
+			_ = cmd.Flags().MarkHidden("wait-poll-interval")
 			_ = cmd.MarkFlagRequired("name")
 			return cmd
 		},
@@ -96,6 +107,20 @@ qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe \
 				return nil, fmt.Errorf("failed to create API key: %w", err)
 			}
 
+			wait, _ := cmd.Flags().GetBool("wait")
+			if !wait {
+				return resp.GetDatabaseApiKey(), nil
+			}
+
+			waitTimeout, _ := cmd.Flags().GetDuration("wait-timeout")
+			pollInterval, _ := cmd.Flags().GetDuration("wait-poll-interval")
+
+			fmt.Fprintf(cmd.ErrOrStderr(), "API key created, waiting for it to become active on the cluster...\n")
+			probe := newKeyProbe(client.Cluster(), accountID, clusterID, resp.GetDatabaseApiKey().GetKey())
+			if err := waitForKeyReady(ctx, cmd.ErrOrStderr(), probe, waitTimeout, pollInterval); err != nil {
+				return nil, err
+			}
+
 			return resp.GetDatabaseApiKey(), nil
 		},
 		PrintResource: func(_ *cobra.Command, out io.Writer, key *clusterauthv2.DatabaseApiKey) {
@@ -109,3 +134,54 @@ qcloud cluster key create 7b2ea926-724b-4de2-b73a-8675c42a6ebe \
 		ValidArgsFunction: completion.ClusterIDCompletion(s),
 	}.CobraCommand(s)
 }
+
+const defaultQdrantRESTPort = 6333
+
+func newKeyProbe(
+	clusterSvc clusterv1.ClusterServiceClient,
+	accountID, clusterID, apiKey string,
+) func(ctx context.Context) error {
+	httpClient := &http.Client{
+		Transport: &http.Transport{
+			TLSHandshakeTimeout:   5 * time.Second,
+			ResponseHeaderTimeout: 5 * time.Second,
+		},
+	}
+
+	return func(ctx context.Context) error {
+		clusterResp, err := clusterSvc.GetCluster(ctx, &clusterv1.GetClusterRequest{
+			AccountId: accountID,
+			ClusterId: clusterID,
+		})
+		if err != nil {
+			return fmt.Errorf("failed to get cluster: %w", err)
+		}
+
+		ep := clusterResp.GetCluster().GetState().GetEndpoint()
+		if ep == nil || ep.GetUrl() == "" {
+			return fmt.Errorf("cluster %s has no endpoint yet", clusterID)
+		}
+
+		port := ep.GetRestPort()
+		if port == 0 {
+			port = defaultQdrantRESTPort
+		}
+		endpointURL := fmt.Sprintf("%s:%d", ep.GetUrl(), port)
+
+		req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpointURL, nil)
+		if err != nil {
+			return err
+		}
+		req.Header.Set("api-key", apiKey)
+		resp, err := httpClient.Do(req)
+		if err != nil {
+			return err
+		}
+		defer resp.Body.Close() //nolint:errcheck // best-effort close on a read-only probe
+		_, _ = io.Copy(io.Discard, resp.Body)
+		if resp.StatusCode >= 200 && resp.StatusCode < 300 {
+			return nil
+		}
+		return fmt.Errorf("cluster endpoint responded with HTTP %d at %s", resp.StatusCode, endpointURL)
+	}
+}

internal/cmd/cluster/key_create_test.go

@@ -1,12 +1,20 @@
 package cluster_test
 
 import (
+	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strconv"
+	"sync/atomic"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 
 	clusterauthv2 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/auth/v2"
+	clusterv1 "github.com/qdrant/qdrant-cloud-public-api/gen/go/qdrant/cloud/cluster/v1"
 
 	"github.com/qdrant/qcloud-cli/internal/testutil"
 )
@@ -113,3 +121,255 @@ func TestKeyCreate_MissingName(t *testing.T) {
 	_, _, err := testutil.Exec(t, env, "cluster", "key", "create", "cluster-123")
 	require.Error(t, err)
 }
+
+func TestKeyCreate_NoWait(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:  "key-no-wait",
+			Key: "secret",
+		},
+	}, nil)
+
+	stdout, _, err := testutil.Exec(t, env, "cluster", "key", "create", "cluster-123", "--name", "my-key")
+	require.NoError(t, err)
+	assert.Contains(t, stdout, "key-no-wait")
+	assert.Equal(t, 0, env.Server.GetClusterCalls.Count(), "GetCluster should not be called without --wait")
+}
+
+// clusterEndpoint starts an httptest server and returns (server, schemeHost, port).
+// The caller is responsible for closing the server.
+func clusterEndpoint(t *testing.T, handler http.Handler) (host string, port int32) {
+	t.Helper()
+	ts := httptest.NewServer(handler)
+	t.Cleanup(ts.Close)
+	u, err := url.Parse(ts.URL)
+	require.NoError(t, err)
+	p, err := strconv.Atoi(u.Port())
+	require.NoError(t, err)
+	return fmt.Sprintf("http://%s", u.Hostname()), int32(p)
+}
+
+func TestKeyCreate_WaitSuccess(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	var calls atomic.Int32
+	host, port := clusterEndpoint(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Header.Get("api-key") != "secret-key" {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		n := calls.Add(1)
+		if n <= 2 {
+			w.WriteHeader(http.StatusForbidden)
+			return
+		}
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:   "key-wait",
+			Name: "wait-key",
+			Key:  "secret-key",
+		},
+	}, nil)
+
+	env.Server.GetClusterCalls.Returns(&clusterv1.GetClusterResponse{
+		Cluster: &clusterv1.Cluster{
+			Id: "cluster-123",
+			State: &clusterv1.ClusterState{
+				Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_HEALTHY,
+				Endpoint: &clusterv1.ClusterEndpoint{
+					Url:      host,
+					RestPort: port,
+				},
+			},
+		},
+	}, nil)
+
+	stdout, stderr, err := testutil.Exec(t, env,
+		"cluster", "key", "create", "cluster-123",
+		"--name", "wait-key",
+		"--wait",
+		"--wait-timeout", "30s",
+		"--wait-poll-interval", "10ms",
+	)
+	require.NoError(t, err)
+	assert.Contains(t, stdout, "key-wait")
+	assert.Contains(t, stderr, "API key is active")
+	assert.GreaterOrEqual(t, env.Server.GetClusterCalls.Count(), 1)
+}
+
+func TestKeyCreate_WaitTimeout(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	host, port := clusterEndpoint(t, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusForbidden)
+	}))
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:  "key-timeout",
+			Key: "secret",
+		},
+	}, nil)
+
+	env.Server.GetClusterCalls.Returns(&clusterv1.GetClusterResponse{
+		Cluster: &clusterv1.Cluster{
+			Id: "cluster-123",
+			State: &clusterv1.ClusterState{
+				Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_HEALTHY,
+				Endpoint: &clusterv1.ClusterEndpoint{
+					Url:      host,
+					RestPort: port,
+				},
+			},
+		},
+	}, nil)
+
+	_, _, err := testutil.Exec(t, env,
+		"cluster", "key", "create", "cluster-123",
+		"--name", "timeout-key",
+		"--wait",
+		"--wait-timeout", "200ms",
+		"--wait-poll-interval", "10ms",
+	)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "timed out")
+}
+
+func TestKeyCreate_WaitNoEndpoint_TimesOut(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:  "key-no-ep",
+			Key: "secret",
+		},
+	}, nil)
+
+	env.Server.GetClusterCalls.Returns(&clusterv1.GetClusterResponse{
+		Cluster: &clusterv1.Cluster{
+			Id:    "cluster-123",
+			State: &clusterv1.ClusterState{},
+		},
+	}, nil)
+
+	_, stderr, err := testutil.Exec(t, env,
+		"cluster", "key", "create", "cluster-123",
+		"--name", "no-ep-key",
+		"--wait",
+		"--wait-timeout", "200ms",
+		"--wait-poll-interval", "10ms",
+	)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "timed out")
+	assert.Contains(t, stderr, "waiting for API key")
+}
+
+func TestKeyCreate_WaitEndpointAppearsMidPoll(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	host, port := clusterEndpoint(t, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:   "key-delayed-ep",
+			Name: "delayed-ep-key",
+			Key:  "secret",
+		},
+	}, nil)
+
+	// First two GetCluster calls return no endpoint, then it appears.
+	env.Server.GetClusterCalls.
+		OnCall(0, func(_ context.Context, _ *clusterv1.GetClusterRequest) (*clusterv1.GetClusterResponse, error) {
+			return &clusterv1.GetClusterResponse{
+				Cluster: &clusterv1.Cluster{
+					Id:    "cluster-123",
+					State: &clusterv1.ClusterState{Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_CREATING},
+				},
+			}, nil
+		}).
+		OnCall(1, func(_ context.Context, _ *clusterv1.GetClusterRequest) (*clusterv1.GetClusterResponse, error) {
+			return &clusterv1.GetClusterResponse{
+				Cluster: &clusterv1.Cluster{
+					Id:    "cluster-123",
+					State: &clusterv1.ClusterState{Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_CREATING},
+				},
+			}, nil
+		}).
+		Always(func(_ context.Context, _ *clusterv1.GetClusterRequest) (*clusterv1.GetClusterResponse, error) {
+			return &clusterv1.GetClusterResponse{
+				Cluster: &clusterv1.Cluster{
+					Id: "cluster-123",
+					State: &clusterv1.ClusterState{
+						Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_HEALTHY,
+						Endpoint: &clusterv1.ClusterEndpoint{
+							Url:      host,
+							RestPort: port,
+						},
+					},
+				},
+			}, nil
+		})
+
+	stdout, stderr, err := testutil.Exec(t, env,
+		"cluster", "key", "create", "cluster-123",
+		"--name", "delayed-ep-key",
+		"--wait",
+		"--wait-timeout", "30s",
+		"--wait-poll-interval", "10ms",
+	)
+	require.NoError(t, err)
+	assert.Contains(t, stdout, "key-delayed-ep")
+	assert.Contains(t, stderr, "API key is active")
+	assert.GreaterOrEqual(t, env.Server.GetClusterCalls.Count(), 3)
+}
+
+func TestKeyCreate_WaitDefaultPort(t *testing.T) {
+	env := testutil.NewTestEnv(t)
+
+	var probed atomic.Bool
+	host, port := clusterEndpoint(t, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		probed.Store(true)
+		w.WriteHeader(http.StatusOK)
+	}))
+
+	env.DatabaseApiKeyServer.CreateDatabaseApiKeyCalls.Returns(&clusterauthv2.CreateDatabaseApiKeyResponse{
+		DatabaseApiKey: &clusterauthv2.DatabaseApiKey{
+			Id:  "key-default-port",
+			Key: "secret",
+		},
+	}, nil)
+
+	// RestPort = 0 would trigger default 6333, but we can't test that with a real
+	// httptest server. Instead, verify that the explicit port works.
+	env.Server.GetClusterCalls.Always(func(_ context.Context, _ *clusterv1.GetClusterRequest) (*clusterv1.GetClusterResponse, error) {
+		return &clusterv1.GetClusterResponse{
+			Cluster: &clusterv1.Cluster{
+				Id: "cluster-123",
+				State: &clusterv1.ClusterState{
+					Phase: clusterv1.ClusterPhase_CLUSTER_PHASE_HEALTHY,
+					Endpoint: &clusterv1.ClusterEndpoint{
+						Url:      host,
+						RestPort: port,
+					},
+				},
+			},
+		}, nil
+	})
+
+	_, _, err := testutil.Exec(t, env,
+		"cluster", "key", "create", "cluster-123",
+		"--name", "port-key",
+		"--wait",
+		"--wait-timeout", "5s",
+		"--wait-poll-interval", "10ms",
+	)
+	require.NoError(t, err)
+	assert.True(t, probed.Load(), "cluster endpoint should have been probed")
+}