RCBC-558: Add Collection#get_replica by avsej · Pull Request #257 · couchbase/couchbase-ruby-client

avsej · 2026-10-07T18:24:53Z

Implements RCBC-558: Collection#get_replica, defined by RFC-0053.

Problem

Collection#get_any_replica returns whichever copy answers first. An application cannot read one particular replica.

Change

strategy = Couchbase::GetReplicaStrategy.from_index(:second, wrap: true)
res = collection.get_replica("airline_10", strategy, Couchbase::Options::GetReplica(timeout: 2_000))
res.content["name"] #=> "40-Mile Air"

GetReplicaStrategy.from_index accepts :first, :second or :third. Any other index raises Error::InvalidArgument before a request is sent. So does a wrap that is not a Boolean.
Error::ReplicaIndexOutOfBounds: the bucket is configured with fewer replicas than the index asks for, e.g. :third with two.
Error::ReplicaIndexCurrentlyUnavailable: the bucket is configured with that replica, but no node holds it right now.
The SDK raises both errors from the vbucket map it already holds. Neither needs a network round trip.
The index is checked against the bucket's configured replica count, as the C++ core resolves it. During a rebalance, a vbucket whose replica chain is shorter reports Error::ReplicaIndexCurrentlyUnavailable.
Error::DocumentNotFoundOnReplica: the replica does not have the document. It is a subclass of Error::DocumentNotFound, so rescue Error::DocumentNotFound still catches it.
replica? is always true on the result. This read never goes to the active copy.
couchbase2:// raises Error::FeatureNotAvailable. The Couchbase gateway has no single-replica read.

With wrap: true, the read moves on instead of failing:

An index past the bucket's replica count wraps around. :third on a bucket with one replica reads the first replica.
A replica that no node holds is skipped for the next readable one.
A bucket without replicas still raises Error::ReplicaIndexOutOfBounds.
If no replica is readable, it still raises Error::ReplicaIndexCurrentlyUnavailable.

RFC-0053 specifies where the replica comes from:

the SDK will use the vbucket map from the most recent bucket config

Node health is not consulted:

A replica on a node that is down is still chosen until that node is failed over.
The read can then wait for that node until the read times out, with or without wrap.
A read that starts after the failover raises Error::ReplicaIndexCurrentlyUnavailable, or moves to the next replica with wrap.
The GetReplicaStrategy.from_index documentation shows how to bound the wait: a short timeout, then get_any_replica.

Copilot

🔵 Needs a closer look

Replica selection and wrapping depend on C++ core behavior unavailable in this snapshot and require human verification.

No open issues 🎉

_{Review effort: Balanced}

Copilot

🟡 Changes recommended

Native argument validation bypasses C++ cleanup on invalid inputs, leaking a cluster ownership reference.

2 open issues

_{Review effort: Balanced}

Motivation ---------- Collection#get_any_replica returns whichever copy of a document answers first. A caller cannot read a named replica. RFC-0053 adds GetReplica: a single-replica read that takes the document id and a strategy that selects the replica. Modifications ------------- Collection#get_replica takes a GetReplicaStrategy. GetReplicaStrategy.from_index accepts :first, :second or :third and a Boolean wrap flag. Any other value raises Error::InvalidArgument before a request is sent. Three new errors report why a replica read fails: - ReplicaIndexOutOfBounds: the bucket is not configured with the requested replica. - ReplicaIndexCurrentlyUnavailable: the bucket is configured with it, but no node holds that replica right now. - DocumentNotFoundOnReplica: the replica does not hold the document. It subclasses DocumentNotFound, so a rescue of the general condition still matches it. The core resolves the index against the vbucket map it already holds. The read therefore raises either replica-index error without a network round trip. The index is checked against the configured replica count. During a rebalance, a shorter replica chain reports ReplicaIndexCurrentlyUnavailable. With wrap, an index that cannot be read resolves to the next readable replica. A bucket without replicas still raises ReplicaIndexOutOfBounds. If no replica is readable, it still raises ReplicaIndexCurrentlyUnavailable. The replica is chosen from the vbucket map, which RFC-0053 specifies. Node health is not consulted: - A replica on a node that is down is still chosen until that node is failed over. - The read can then wait for that node until the read times out. - A read that starts after the failover raises ReplicaIndexCurrentlyUnavailable, or moves on with wrap. - The from_index documentation shows how to bound the wait: a short timeout, then get_any_replica. couchbase2:// raises FeatureNotAvailable. The gateway does not carry the operation. CI creates a second bucket with three replicas on its three KV nodes. Its third replica has no node. Results ------- Integration tests read every replica the bucket places on a node. They cover each error and both wrap cases. They do not check which node served a read. The tests that need an unplaced replica skip when no bucket has one.

Copilot

🔵 Needs a closer look

Replica routing, wrapping, and availability semantics require validation against C++ core behavior unavailable in this checkout.

No open issues 🎉

2 resolved since last review

_{Review effort: Balanced}

avsej requested a balanced review from Copilot October 7, 2026 18:25

Copilot started reviewing on behalf of avsej October 7, 2026 18:25

View session