PCBC-1074: Replica Read from Specific Replica

[Matt-Woz]

No description provided.

[Copilot]

🟡 Changes recommended

Unresolved critical and moderate findings affect native error handling and test reliability.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds specific-replica document reads to the Couchbase PHP API, including native bindings, strategies, options, exceptions, and integration tests.

Changes:

• Adds the getReplica() API and replica-related types.
• Wires native request handling and exception mapping.
• Adds integration coverage and Protostellar unsupported handling.

File summaries

File	Reviewed change / final review notes
tests/KeyValueGetReplicaTest.php	Adds replica-read tests. Moderate: wait for asynchronous replica propagation; skip Protostellar runs; ensure the invalid index remains out of bounds when three replicas exist.
src/wrapper/connection_handle.hxx	Declares the native replica-read operation.
src/wrapper/connection_handle.cxx	Implements native replica reads. Critical: preserve and return unmapped response errors instead of falling through to result creation.
src/wrapper/common.cxx	Registers and maps replica exceptions.
src/php_couchbase.cxx	Exposes the native PHP function.
Couchbase/ReplicaIndex.php	Defines replica index constants.
Couchbase/Protostellar/Collection.php	Marks replica reads unsupported. Moderate: tests need a Protostellar guard; nit: use a scheme-neutral unsupported-operation message.
Couchbase/GetReplicaStrategy.php	Defines replica selection behavior. Nit: add coverage for wrap(true) fallback and exhausted-search behavior.
Couchbase/GetReplicaOptions.php	Defines replica-read options.
Couchbase/Exception/ReplicaIndexOutOfBoundsException.php	Adds the invalid-index exception.
Couchbase/Exception/ReplicaIndexCurrentlyUnavailableException.php	Adds the unavailable-replica exception.
Couchbase/Exception/DocumentNotFoundOnReplicaException.php	Adds the missing-document exception.
Couchbase/CollectionInterface.php	Adds the public method contract.
Couchbase/Collection.php	Implements the public getReplica() API.

Review details

Suppressed comments (3)

Couchbase/Protostellar/Collection.php:312

• This backend deliberately throws UnsupportedOperationException for getReplica, but skipIfReplicasAreNotConfigured() returns without skipping on Protostellar. Consequently the three new getReplica tests invoke this method and fail in Protostellar runs instead of being skipped. Add a Protostellar guard to those tests, or implement the operation for this backend.

    public function getReplica(string $key, GetReplicaStrategy $strategy, ?GetReplicaOptions $options = null): GetReplicaResult
    {
        throw new UnsupportedOperationException("getReplica is not supported with the couchbase2 scheme yet");

tests/KeyValueGetReplicaTest.php:90

• skipIfReplicasAreNotConfigured() returns immediately for Protostellar, while Protostellar\Collection::getReplica() always throws UnsupportedOperationException. Consequently this test fails in Protostellar test runs instead of asserting the intended exception; add the Protostellar skip before the replica configuration check.

        $this->skipIfReplicasAreNotConfigured();

tests/KeyValueGetReplicaTest.php:100

• Unlike the other new tests, this test has no Protostellar skip, and Protostellar\Collection::getReplica() always throws UnsupportedOperationException. It therefore fails in Protostellar test runs before reaching the expected out-of-bounds assertion; skip Protostellar connections for this unsupported operation.

        $id = $this->uniqueId();
        $collection = $this->defaultCollection();

• Files reviewed: 15/15 changed files
• Comments generated: 6
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Wrapping behavior is not actually exercised, and the new observability path lacks coverage.

Review effort: Balanced
Findings: 2

Open (2)

• Add getReplica observability coverage · New
• Test replica selection with wrapping enabled · New

Resolved since last review (6)

• key_value_execute returns a non-empty err whenever resp.ctx.ec() is set, but this branch only…
• The replica check only verifies that the bucket has at least one replica, so it also permits a…
• The upsert is acknowledged by the active node only, while replica propagation is asynchronous.…
• skipIfReplicasAreNotConfigured() returns immediately for Protostellar, while…
• This implementation is used for both protostellar:// and couchbase2:// connections, so the…
• The new wrap(true) behavior is not exercised by any of the added integration tests; all calls use…