C++ SDK: add replication prefix setting

[mother-6000]

Parent: reductstore/reductstore#1487
Core implementation: reductstore/reductstore#1486
Original feature request: reductstore/reductstore#1466

ReductStore Core now supports replication prefix in the HTTP API and RS_REPLICATION_<ID>_PREFIX provisioning. The setting prepends only the destination entry path: source camera/front with prefix robot-1 becomes destination robot-1/camera/front.

Scope:

• Add prefix to the C++ replication settings model/API surface.
• Ensure create/update/get/list replication APIs serialize and deserialize the field.
• Update examples/tests/changelog as appropriate.

Acceptance criteria:

• A user can pass prefix when creating or updating a replication task.
• Returned replication settings expose prefix.
• Omitted prefix stays backward compatible.

[mother-6000]

Implementation plan drafted - please review:
@reductstore/maintainers @atimin

Summary

Add support for the ReductStore replication destination entry prefix setting to the C++ SDK. The linked SDK issue says prefix, but the merged ReductStore core model on origin/main now exposes the final API/model field as dst_prefix and provisioning as RS_REPLICATION_<ID>_DST_PREFIX after the naming review on reductstore/reductstore#1486. This plan therefore targets dst_prefix in the C++ API and JSON payload unless maintainers want the C++ SDK issue/API kept on plain prefix instead.

The desired outcome is that C++ callers can create or update a replication task with a destination prefix, then read that value back from GetReplication. Empty or omitted dst_prefix remains backward compatible and keeps existing replication behavior.

Scope

In scope:

• Add destination prefix to the public C++ replication settings type.
• Serialize non-empty destination prefix in create/update replication requests.
• Deserialize returned destination prefix in full replication details.
• Add focused serialization/parser coverage and a version-gated live API regression test.
• Update the changelog.

Out of scope:

• No server-side changes; add replication entry prefix reductstore#1486 owns destination entry rewriting.
• No new replication endpoints or client methods.
• No client-side destination path rewriting or validation beyond passing the setting through.
• No README or example changes unless maintainers explicitly request them; AGENTS.md says not to add feature docs/examples unless the issue asks.

Proposed changes

1. Extend the public C++ settings model

   • Update src/reduct/client.h in IClient::ReplicationSettings.
   • Add a field near entries, because it also controls entry naming:

     std::string dst_prefix;  // Prefix to add to destination entry names

   • Keep the field as std::string, not std::optional<std::string>, to match the Rust/core ReplicationSettings::dst_prefix: String shape and make the default value an empty prefix.
   • Do not add a plain prefix alias in the first pass; that would create two names for the same server field. If maintainers prefer a shorter C++ name, I will update this plan before coding.

2. Serialize create/update settings through the existing path

   • Update src/reduct/internal/serialisation.cc, function ReplicationSettingsToJsonString.
   • Keep existing required fields unchanged:
     • src_bucket
     • dst_bucket
     • dst_host
     • optional dst_token
     • entries
     • mode
     • optional parsed when
   • Add:

     if (!settings.dst_prefix.empty()) {
       json_data["dst_prefix"] = settings.dst_prefix;
     }

   • This intentionally omits empty dst_prefix from request payloads so stable servers that do not know the field continue to receive the same JSON as before.

3. Deserialize full replication details

   • Update ParseFullReplicationInfo in src/reduct/internal/serialisation.cc.
   • Populate info.settings.dst_prefix only when the server response contains a non-null settings.dst_prefix; otherwise leave it as the default empty string.
   • Existing GetReplicationList control flow should stay unchanged unless the server list endpoint starts returning settings. Current SDK list output uses ReplicationInfo, not ReplicationSettings, so there is no prefix field to expose there.

4. Expected before/after usage
   Before:

   reduct::IClient::ReplicationSettings settings{
       .src_bucket = "edge",
       .dst_bucket = "fleet",
       .dst_host = "https://central.example",
       .entries = {"camera/front"},
   };
   auto err = client->CreateReplication("robot-repl", settings);

   After:

   reduct::IClient::ReplicationSettings settings{
       .src_bucket = "edge",
       .dst_bucket = "fleet",
       .dst_host = "https://central.example",
       .entries = {"camera/front"},
       .dst_prefix = "robot-1",
   };
   auto err = client->CreateReplication("robot-repl", settings);

   Expected JSON sent when configured:

   {
     "src_bucket": "edge",
     "dst_bucket": "fleet",
     "dst_host": "https://central.example",
     "entries": ["camera/front"],
     "mode": "enabled",
     "dst_prefix": "robot-1"
   }

   Server behavior: source entry camera/front is written to destination entry robot-1/camera/front.

5. Add focused tests

   • Extend tests/reduct/replication_api_test.cc, matching the existing replication test location.
   • Add low-level serialization/parser assertions using reduct/internal/serialisation.h and nlohmann::json:
     • non-empty settings.dst_prefix = "robot-1" serializes as JSON field "dst_prefix":"robot-1";
     • empty/default dst_prefix does not serialize a dst_prefix field;
     • ParseFullReplicationInfo reads settings.dst_prefix from a full replication-detail response;
     • older response JSON without dst_prefix leaves settings.dst_prefix == "".
   • Extend live replication API coverage with a dev-server-only test:
     • create test_replication_prefix with dst_prefix = "robot-1";
     • fetch it with GetReplication and assert replication.settings.dst_prefix == "robot-1";
     • update it to "line-a" and assert the fetched value changes.
   • Tag that live test with the repo's current latest-exclusion tag bucket, likely [replication_api][1_20], so it runs against reduct/store:main but remains excluded from reduct/store:latest by the current CI matrix. If maintainers want a precise new [1_21] API tag, I will also update .github/workflows/ci.yml and AGENTS.md latest-test examples to exclude the new tag for stable-server runs.

6. Update changelog

   • Add an ## Unreleased / ### Added entry in CHANGELOG.md:

     - Add replication destination prefix support, [PR-<NN>](https://github.com/reductstore/reduct-cpp/pull/<NN>)

   • The PR number can be filled by the create-PR workflow after opening the PR, following existing ReductStore changelog style.

Files/modules/components expected to change

• src/reduct/client.h
  • add IClient::ReplicationSettings::dst_prefix
• src/reduct/internal/serialisation.cc
  • serialize non-empty dst_prefix
  • parse optional returned settings.dst_prefix
• tests/reduct/replication_api_test.cc
  • serializer/parser regression tests
  • live create/update/get round-trip test for destination prefix
• CHANGELOG.md
  • user-visible SDK API addition
• Possibly .github/workflows/ci.yml and AGENTS.md only if maintainers prefer a new exact API-version tag such as [1_21] instead of reusing the current [1_20] stable-exclusion bucket.

Data flow

• User sets IClient::ReplicationSettings::dst_prefix.
• IClient::CreateReplication / IClient::UpdateReplication call internal::ReplicationSettingsToJsonString.
• The SDK sends dst_prefix in POST /replications/{name} or PUT /replications/{name} only when non-empty.
• ReductStore applies the prefix only to destination entry names.
• IClient::GetReplication calls ParseFullReplicationInfo, which fills FullReplicationInfo.settings.dst_prefix from the server response.

Backward compatibility

• The C++ API change is additive: no existing methods, fields, enum values, or endpoints are removed or renamed.
• Empty dst_prefix produces the same create/update payload shape as today.
• Older server responses without settings.dst_prefix deserialize to dst_prefix == "".
• The live test that sends a non-empty prefix will be excluded from stable-server CI until reduct/store:latest supports the field.

Local validation before PR

Repository-required commands from AGENTS.md / CI:

• pip install "cpplint<2"
• find src/ \( -name "*.cc" -o -name "*.h" \) -print0 | xargs -0 cpplint
• find tests/ \( -name "*.cc" -o -name "*.h" \) -print0 | xargs -0 cpplint
• find examples/ \( -name "*.cc" -o -name "*.h" \) -print0 | xargs -0 cpplint
• cmake -S . -B build -DREDUCT_CPP_USE_FETCHCONTENT=ON -DREDUCT_CPP_ENABLE_TESTS=ON
• cmake --build build
• Against reduct/store:main: REDUCT_CPP_TOKEN_API=TOKEN ./build/bin/reduct-tests
• Against reduct/store:latest: REDUCT_CPP_TOKEN_API=TOKEN ./build/bin/reduct-tests "~[1_20]" or the updated stable exclusion expression if a new [1_21] tag is introduced.

Focused checks during development:

• ./build/bin/reduct-tests "[replication_api]"
• ./build/bin/reduct-tests "[replication_api][1_20]" for the prefix round-trip against reduct/store:main.

Risks and open questions

• Naming mismatch: the SDK issue and parent tracker still say prefix, but merged core code uses dst_prefix. Please confirm dst_prefix is the desired C++ public and wire field before implementation.
• Version tagging: the repo currently excludes [1_20] tests from reduct/store:latest. If this feature belongs under a new API version tag, I will update CI/docs in the same PR instead of relying on the older exclusion bucket.
• Stable-server compatibility: the implementation must avoid sending empty dst_prefix to older servers; otherwise create/update requests could become incompatible despite users not configuring the new feature.
• Non-goal reminder: dst_prefix is destination-only and does not replace or modify entries source filtering.

[atimin]

approved

[mother-6000]

Implemented in #135.

Local validation is green:

• .venv/bin/cpplint over src/, tests/, and examples/
• cmake -S . -B build -DREDUCT_CPP_USE_FETCHCONTENT=ON -DREDUCT_CPP_ENABLE_TESTS=ON
• cmake --build build
• REDUCT_CPP_TOKEN_API=TOKEN ./build/bin/reduct-tests against reduct/store:main
• REDUCT_CPP_TOKEN_API=TOKEN ./build/bin/reduct-tests "~[1_20]" against reduct/store:latest

CI is running on the PR.