fix(couchbase): improve readiness timeout

adapter/couchbase.go

@@ -93,7 +93,7 @@ func (a *couchbaseAdapter) Connect(ctx context.Context) error {
 	}
 	b := cluster.Bucket(a.bucket)
 	if err := b.WaitUntilReady(a.readyTimeout, &gocb.WaitUntilReadyOptions{Context: ctx}); err != nil {
-		return err
+		return a.bucketReadyError(err)
 	}
 	if err := a.ensureScopeAndCollection(ctx, b); err != nil {
 		return err

adapter/couchbase_initialization.go

@@ -9,7 +9,16 @@ import (
 	"github.com/couchbase/gocb/v2"
 )
 
-const defaultCouchbaseReadyTimeout = 30 * time.Second
+const defaultCouchbaseReadyTimeout = 2 * time.Minute
+
+func (a *couchbaseAdapter) bucketReadyError(err error) error {
+	return fmt.Errorf(
+		"bucket %q was not ready after %s: %w; check bucket_name, connection_string, database user permissions, and Capella allowed IP/network access; increase ready_timeout if the cluster or bucket was just created",
+		a.bucket,
+		a.readyTimeout,
+		err,
+	)
+}
 
 func (a *couchbaseAdapter) ensureBucket(ctx context.Context, cluster *gocb.Cluster) error {
 	if a.bucketRAMQuotaMB == 0 {

adapter/couchbase_test.go

@@ -1,6 +1,8 @@
 package adapter
 
 import (
+	"errors"
+	"strings"
 	"testing"
 	"time"
 )
@@ -29,6 +31,25 @@ func TestCouchbaseFactoryParsesInitializationOptions(t *testing.T) {
 	}
 }
 
+func TestCouchbaseFactoryUsesHostedReadyTimeoutDefault(t *testing.T) {
+	a, err := New("couchbase", Config{
+		"connection_string": "couchbases://cb.example.com",
+		"username":          "user",
+		"password":          "pass",
+		"bucket_name":       "keepalive",
+		"scope_name":        "scope",
+		"collection_name":   "collection",
+	})
+	if err != nil {
+		t.Fatalf("New returned error: %v", err)
+	}
+
+	got := a.(*couchbaseAdapter)
+	if got.readyTimeout != 2*time.Minute {
+		t.Fatalf("readyTimeout = %s, want 2m", got.readyTimeout)
+	}
+}
+
 func TestCouchbaseFactoryRejectsInvalidReadyTimeout(t *testing.T) {
 	_, err := New("couchbase", Config{
 		"connection_string": "couchbases://cb.example.com",
@@ -43,3 +64,18 @@ func TestCouchbaseFactoryRejectsInvalidReadyTimeout(t *testing.T) {
 		t.Fatal("New returned nil error")
 	}
 }
+
+func TestCouchbaseBucketReadyErrorAddsActionableContext(t *testing.T) {
+	cause := errors.New("unambiguous timeout")
+	a := couchbaseAdapter{bucket: "keepalive", readyTimeout: 2 * time.Minute}
+
+	err := a.bucketReadyError(cause)
+	if !errors.Is(err, cause) {
+		t.Fatalf("bucketReadyError does not wrap cause: %v", err)
+	}
+	for _, want := range []string{"keepalive", "2m0s", "Capella allowed IP", "ready_timeout"} {
+		if !strings.Contains(err.Error(), want) {
+			t.Fatalf("bucketReadyError() = %q, want it to contain %q", err, want)
+		}
+	}
+}