[avsej]

Fixes RCBC-304.

Problem

The SDK has no way to wait for a cluster or bucket to become fully usable. Cluster.connect and Cluster#bucket return after bootstrap. Sessions to the other nodes and services may still be opening.

Change

The first commit makes the backend raise Error::ClusterClosed as a C++ exception, so a closed cluster no longer skips the calling binding's destructors.

The second commit adds Cluster#wait_until_ready and Bucket#wait_until_ready, through the C++ core's wait_until_ready.

cluster = Couchbase::Cluster.connect("couchbase://127.0.0.1", "Administrator", "password")
options = Couchbase::Options::WaitUntilReady.new(service_types: [:kv])
cluster.bucket("travel-sample").wait_until_ready(10_000, options)

• desired_state: :online waits for every endpoint the ping reports for each requested service. :degraded waits for at least one.
• For a bucket, :online also waits until every vbucket has its active copy and each placeable replica assigned to a node.
• With no service_types, every service in the ping report counts. A requested service that no node runs is never ready.
• The wait raises:
  • Error::UnambiguousTimeout when the timeout elapses;
  • Error::ClusterClosed once the cluster is disconnected;
  • Error::InvalidArgument for an unknown state or service type, or for a timeout that is negative or longer than 365 days.

The third commit makes the test helper wait for the test bucket under CAVES. On CI, a test's first operation sometimes fails with UnambiguousTimeout and retry_attempts: 0.

Known gaps

• Over couchbase2:// both methods raise Error::FeatureNotAvailable. That client is implemented in Ruby, not over the core.
• Thread#raise and Timeout.timeout do not interrupt the wait, because the binding blocks without an unblocking function. Cluster#disconnect from another thread ends it with Error::ClusterClosed.
• The rate of the CAVES timeouts on CI before and after the third commit has not been measured.

[Copilot]

🔵 Needs a closer look

Native exception handling and concurrent-disconnect behavior require human integration validation.

No open issues 🎉

1 resolved since last review

• Bound KV wait and disconnect cluster during cleanup

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Upper-bound timeout safety remains unresolved, and native deadline and concurrent-disconnect behavior require validation against the unavailable C++ core.

1 open issue

• Use conservative timeout limit to prevent deadline overflow · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Native exception unwinding, timeout boundaries, and concurrent disconnect behavior need human integration validation against the C++ core.

No open issues 🎉

1 resolved since last review

• Use conservative timeout limit to prevent deadline overflow

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Native exception handling and concurrent disconnect behavior need human review supported by integration-test results.

No open issues 🎉

_{Review effort: Balanced}