Sync query link creation with record identity API (#119)

.github/workflows/ci.yml

@@ -73,7 +73,7 @@ jobs:
             audit_enabled: "false"
           - reductstore_version: "latest"
             exclude_api_version_tag: "~[1_19]"
-            audit_enabled: "true"
+            audit_enabled: "false"
 
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased
 
+## 1.19.1 - 2026-04-21
+
+### Fixed
+
+- Sync query link creation with record identity API: support `record_entry`/`record_timestamp`, keep legacy `record_index` for older APIs, and validate selectors for API v1.19+, [PR-120](https://github.com/reductstore/reduct-cpp/pull/120)
+
 ## 1.19.0 - 2026-04-08
 
 ### Added

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.23)
 
 set(MAJOR_VERSION 1)
 set(MINOR_VERSION 19)
-set(PATCH_VERSION 0)
+set(PATCH_VERSION 1)
 set(REDUCT_CPP_FULL_VERSION ${MAJOR_VERSION}.${MINOR_VERSION}.${PATCH_VERSION})
 
 project(reductcpp VERSION ${REDUCT_CPP_FULL_VERSION} LANGUAGES CXX)

src/reduct/bucket.cc

@@ -535,10 +535,26 @@ class Bucket : public IBucket {
   }
 
   Result<std::string> CreateQueryLink(std::string_view entry_name, QueryLinkOptions options) const noexcept override {
-    auto [json_payload, json_err] = internal::QueryLinkOptionsToJsonString(name_, {std::string(entry_name)}, options);
+    auto [normalized_options, normalize_err] =
+        NormalizeAndValidateQueryLinkOptions({std::string(entry_name)}, std::move(options));
+    if (normalize_err) {
+      return {{}, std::move(normalize_err)};
+    }
+
+    auto [json_payload, json_err] =
+        internal::QueryLinkOptionsToJsonString(name_, {std::string(entry_name)}, normalized_options);
+    if (json_err) {
+      return {{}, std::move(json_err)};
+    }
+
+    const auto selector = normalized_options.record_timestamp
+                              ? std::chrono::duration_cast<std::chrono::microseconds>(
+                                    normalized_options.record_timestamp->time_since_epoch())
+                                    .count()
+                              : static_cast<int64_t>(normalized_options.record_index);
 
     auto file_name =
-        options.file_name ? *options.file_name : fmt::format("{}_{}.bin", entry_name, options.record_index);
+        normalized_options.file_name ? *normalized_options.file_name : fmt::format("{}_{}.bin", entry_name, selector);
     auto [body, err] = client_->PostWithResponse(fmt::format("/links/{}", file_name), json_payload.dump());
     if (err) {
       return {{}, std::move(err)};
@@ -561,9 +577,24 @@ class Bucket : public IBucket {
       return {{}, Error{.code = -1, .message = "At least one entry name is required"}};
     }
 
-    auto [json_payload, json_err] = internal::QueryLinkOptionsToJsonString(name_, entries, options);
+    auto [normalized_options, normalize_err] = NormalizeAndValidateQueryLinkOptions(entries, std::move(options));
+    if (normalize_err) {
+      return {{}, std::move(normalize_err)};
+    }
+
+    auto [json_payload, json_err] = internal::QueryLinkOptionsToJsonString(name_, entries, normalized_options);
+    if (json_err) {
+      return {{}, std::move(json_err)};
+    }
+
+    const auto selector = normalized_options.record_timestamp
+                              ? std::chrono::duration_cast<std::chrono::microseconds>(
+                                    normalized_options.record_timestamp->time_since_epoch())
+                                    .count()
+                              : static_cast<int64_t>(normalized_options.record_index);
 
-    auto file_name = options.file_name ? *options.file_name : fmt::format("{}_{}.bin", name_, options.record_index);
+    auto file_name =
+        normalized_options.file_name ? *normalized_options.file_name : fmt::format("{}_{}.bin", name_, selector);
     auto [body, err] = client_->PostWithResponse(fmt::format("/links/{}", file_name), json_payload.dump());
     if (err) {
       return {{}, std::move(err)};
@@ -770,6 +801,59 @@ class Bucket : public IBucket {
     return api_version && internal::IsCompatible("1.18", *api_version);
   }
 
+  Result<std::string> EnsureApiVersion() const {
+    auto api_version = client_->ApiVersion();
+    if (api_version.has_value()) {
+      return {*api_version, Error::kOk};
+    }
+
+    auto [_, err] = client_->Get("/info");
+    if (err) {
+      return {{}, std::move(err)};
+    }
+
+    api_version = client_->ApiVersion();
+    if (!api_version.has_value()) {
+      return {{}, Error{.code = -1, .message = "Failed to determine ReductStore API version"}};
+    }
+    return {*api_version, Error::kOk};
+  }
+
+  static bool HasWildcard(std::string_view entry) {
+    return entry.find('*') != std::string_view::npos || entry.find('?') != std::string_view::npos ||
+           entry.find('[') != std::string_view::npos;
+  }
+
+  Result<QueryLinkOptions> NormalizeAndValidateQueryLinkOptions(const std::vector<std::string>& entries,
+                                                                QueryLinkOptions options) const {
+    if (options.record_timestamp && !options.record_entry) {
+      if (entries.size() == 1 && !HasWildcard(entries[0])) {
+        options.record_entry = entries[0];
+      } else {
+        return {{}, Error{.code = -1, .message = "record_entry must be provided with record_timestamp"}};
+      }
+    }
+
+    if (options.record_entry && !options.record_timestamp) {
+      return {{}, Error{.code = -1, .message = "record_timestamp must be provided with record_entry"}};
+    }
+
+    auto [api_version, api_err] = EnsureApiVersion();
+    if (api_err) {
+      return {{}, std::move(api_err)};
+    }
+
+    if (internal::IsCompatible("1.19", api_version) && !options.record_entry.has_value()) {
+      return {{},
+              Error{.code = -1,
+                    .message =
+                        "record entry and timestamp must be provided for ReductStore API v1.19+; use "
+                        "record_entry and record_timestamp"}};
+    }
+
+    return {std::move(options), Error::kOk};
+  }
+
   static Error FirstBatchRecordError(const BatchRecordErrors& errors) {
     for (const auto& [entry, record_errors] : errors) {
       (void)entry;

src/reduct/bucket.h

@@ -543,7 +543,9 @@ class IBucket {
     std::optional<Time> start;
     std::optional<Time> stop;
     QueryOptions query_options = {};
-    uint64_t record_index = 0;  // index of record in the query result to return
+    uint64_t record_index = 0;  // legacy index selector (API < 1.19)
+    std::optional<std::string> record_entry = std::nullopt;      // explicit record entry (API >= 1.19)
+    std::optional<Time> record_timestamp = std::nullopt;         // explicit record timestamp (API >= 1.19)
     std::optional<Time> expire_at = std::nullopt;
     std::optional<std::string> file_name = std::nullopt;
     std::optional<std::string> base_url = std::nullopt;

src/reduct/internal/serialisation.cc

@@ -300,7 +300,16 @@ Result<nlohmann::ordered_json> QueryLinkOptionsToJsonString(std::string_view buc
   nlohmann::ordered_json json_data;
 
   json_data["bucket"] = bucket;
-  json_data["index"] = options.record_index;
+  if (!options.record_entry && !options.record_timestamp) {
+    json_data["index"] = options.record_index;
+  }
+  if (options.record_entry) {
+    json_data["record_entry"] = *options.record_entry;
+  }
+  if (options.record_timestamp) {
+    json_data["record_timestamp"] =
+        std::chrono::duration_cast<std::chrono::microseconds>(options.record_timestamp->time_since_epoch()).count();
+  }
   json_data["entry"] = entries.at(0);
   auto [query_json, query_err] =
       QueryOptionsToJsonString("QUERY", entries, options.start, options.stop, options.query_options);

tests/reduct/bucket_api_test.cc

@@ -214,33 +214,34 @@ Result<std::string> download_link(std::string_view link) {
   return http_client->Get(link.substr(link.find("/links/")));
 }
 
-
-TEST_CASE("reduct::IBucket should create a query link", "[bucket_api][1_17]") {
+TEST_CASE("reduct::IBucket should create a query link", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
-  auto [link, err] = bucket->CreateQueryLink("entry-1", IBucket::QueryLinkOptions{});
+  auto [link, err] = bucket->CreateQueryLink(
+      "entry-1", IBucket::QueryLinkOptions{.record_entry = "entry-1", .record_timestamp = IBucket::Time() + s(1)});
   REQUIRE(err == Error::kOk);
 
   auto [data, http_err] = download_link(link);
   REQUIRE(http_err == Error::kOk);
   REQUIRE(data == "data-1");
 }
 
-TEST_CASE("reduct::IBucket should create a query link for multiple entries", "[bucket_api][1_18]") {
+TEST_CASE("reduct::IBucket should create a query link for multiple entries", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
-  auto [link, err] = bucket->CreateQueryLink(std::vector<std::string>{"entry-1", "entry-2"},
-                                             IBucket::QueryLinkOptions{});
+  auto [link, err] = bucket->CreateQueryLink(
+      std::vector<std::string>{"entry-1", "entry-2"},
+      IBucket::QueryLinkOptions{.record_entry = "entry-1", .record_timestamp = IBucket::Time() + s(1)});
   REQUIRE(err == Error::kOk);
 
   auto [data, http_err] = download_link(link);
   REQUIRE(http_err == Error::kOk);
   REQUIRE(data == "data-1");
 }
 
-TEST_CASE("reduct::IBucket should reject empty entry list for query link", "[bucket_api][1_18]") {
+TEST_CASE("reduct::IBucket should reject empty entry list for query link", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
@@ -249,39 +250,76 @@ TEST_CASE("reduct::IBucket should reject empty entry list for query link", "[buc
   REQUIRE(link.empty());
 }
 
-TEST_CASE("reduct::IBucket should create a query link with index", "[bucket_api][1_17]") {
+TEST_CASE("reduct::IBucket should create a query link with file name", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
-  auto [link, err] = bucket->CreateQueryLink("entry-1", IBucket::QueryLinkOptions{.record_index = 1});
-  REQUIRE(err == Error::kOk);
+  IBucket::QueryLinkOptions options{
+      .record_entry = "entry-1",
+      .record_timestamp = IBucket::Time() + s(1),
+      .file_name = "my_file.txt",
+  };
 
-  auto [data, http_err] = download_link(link);
-  REQUIRE(http_err == Error::kOk);
-  REQUIRE(data == "data-2");
+  auto [link, err] = bucket->CreateQueryLink("entry-1", options);
+  REQUIRE(err == Error::kOk);
+  REQUIRE(link.find("/links/my_file.txt") != std::string::npos);
 }
 
-TEST_CASE("reduct::IBucket should create a query link with file name", "[bucket_api][1_17]") {
+TEST_CASE("reduct::IBucket should create a query link with expire time", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
-  auto [link, err] = bucket->CreateQueryLink("entry-1", IBucket::QueryLinkOptions{
-                                                            .file_name = "my_file.txt",
-                                                        });
+  IBucket::QueryLinkOptions options{
+      .record_entry = "entry-1",
+      .record_timestamp = IBucket::Time() + s(1),
+      .expire_at = IBucket::Time::clock::now() - std::chrono::hours(1),
+  };
+
+  auto [link, err] = bucket->CreateQueryLink("entry-1", options);
   REQUIRE(err == Error::kOk);
-  REQUIRE(link.find("/links/my_file.txt") != std::string::npos);
+
+  auto [_data, http_err] = download_link(link);
+  REQUIRE(http_err.code == 422);
 }
 
-TEST_CASE("reduct::IBucket should create a query link with expire time", "[bucket_api][1_17]") {
+TEST_CASE("reduct::IBucket should create a query link with explicit record identity", "[bucket_api][1_19]") {
   Fixture ctx;
   auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
 
-  auto [link, err] =
-      bucket->CreateQueryLink("entry-1", IBucket::QueryLinkOptions{
-                                             .expire_at = IBucket::Time::clock::now() - std::chrono::hours(1),
-                                         });
+  auto [link, err] = bucket->CreateQueryLink(
+      "entry-2", IBucket::QueryLinkOptions{.record_entry = "entry-2", .record_timestamp = IBucket::Time() + s(4)});
   REQUIRE(err == Error::kOk);
 
-  auto [_data, http_err] = download_link(link);
-  REQUIRE(http_err.code == 422);
+  auto [data, http_err] = download_link(link);
+  REQUIRE(http_err == Error::kOk);
+  REQUIRE(data == "data-4");
+}
+
+TEST_CASE("reduct::IBucket should validate query link record identity selector", "[bucket_api][1_19]") {
+  Fixture ctx;
+  auto [bucket, _] = ctx.client->GetBucket("test_bucket_1");
+
+  SECTION("record_entry without record_timestamp") {
+    auto [link, err] = bucket->CreateQueryLink("entry-1", IBucket::QueryLinkOptions{.record_entry = "entry-1"});
+    REQUIRE(link.empty());
+    REQUIRE(err.code == -1);
+    REQUIRE(err.message.find("record_timestamp must be provided") != std::string::npos);
+  }
+
+  SECTION("record_timestamp defaults record_entry for one explicit entry") {
+    auto [link, err] =
+        bucket->CreateQueryLink("entry-2", IBucket::QueryLinkOptions{.record_timestamp = IBucket::Time() + s(4)});
+    REQUIRE(err == Error::kOk);
+    auto [data, http_err] = download_link(link);
+    REQUIRE(http_err == Error::kOk);
+    REQUIRE(data == "data-4");
+  }
+
+  SECTION("record_timestamp with wildcard entry requires record_entry") {
+    auto [link, err] =
+        bucket->CreateQueryLink("entry-*", IBucket::QueryLinkOptions{.record_timestamp = IBucket::Time() + s(4)});
+    REQUIRE(link.empty());
+    REQUIRE(err.code == -1);
+    REQUIRE(err.message.find("record_entry must be provided") != std::string::npos);
+  }
 }