Add C/C++ API for getting REST data protocol (#5697)

Adds a new API that can be used to tell which Server/data model
the REST client is configured to reach out to. This is needed as there
are differences in the data model between legacy and new TileDB Server,
especially when it comes to group operations, so a user needs to be able
to tell in an easy way to which server she is talking to.

---
TYPE: C_API
DESC: Add C API for getting REST data protocol

TYPE: CPP_API
DESC: Add C++ API for getting REST data protocol

Author: ypatia

test/src/unit-ctx.cc

@@ -33,6 +33,7 @@
 
 #include <test/support/tdb_catch.h>
 #include "test/support/src/helpers.h"
+#include "test/support/src/vfs_helpers.h"
 #include "tiledb/api/c_api/context/context_api_internal.h"
 #include "tiledb/sm/c_api/tiledb_struct_def.h"
 #include "tiledb/sm/cpp_api/tiledb"
@@ -103,3 +104,58 @@ TEST_CASE("C++ API: Test context tags", "[cppapi][ctx-tags]") {
     }
   }
 }
+
+TEST_CASE(
+    "C API: Test context data protocol", "[capi][ctx][data-protocol][rest]") {
+  tiledb::test::VFSTestSetup vfs_test_setup{};
+  tiledb_ctx_t* ctx = vfs_test_setup.ctx_c;
+
+  tiledb_data_protocol_t data_protocol;
+
+  SECTION("tiledb:// URI") {
+    if (vfs_test_setup.is_rest()) {
+      auto rc = tiledb_ctx_get_data_protocol(
+          ctx, "tiledb://workspace/teamspace/array", &data_protocol);
+      REQUIRE(rc == TILEDB_OK);
+      if (vfs_test_setup.is_legacy_rest()) {
+        REQUIRE(data_protocol == TILEDB_DATA_PROTOCOL_v2);
+      } else {
+        REQUIRE(data_protocol == TILEDB_DATA_PROTOCOL_v3);
+      }
+    }
+  }
+
+  SECTION("non-tiledb:// URI") {
+    auto rc = tiledb_ctx_get_data_protocol(
+        ctx, "azure://bucket/array", &data_protocol);
+    REQUIRE(rc == TILEDB_OK);
+    REQUIRE(data_protocol == TILEDB_DATA_PROTOCOL_v2);
+  }
+}
+
+TEST_CASE(
+    "C++ API: Test context data protocol",
+    "[cppapi][ctx][data-protocol][rest]") {
+  tiledb::test::VFSTestSetup vfs_test_setup{};
+  tiledb::Context ctx{vfs_test_setup.ctx()};
+
+  SECTION("tiledb:// URI") {
+    if (vfs_test_setup.is_rest()) {
+      if (vfs_test_setup.is_legacy_rest()) {
+        REQUIRE(
+            ctx.data_protocol("tiledb://workspace/teamspace/array") ==
+            tiledb::Context::DataProtocol::v2);
+      } else {
+        REQUIRE(
+            ctx.data_protocol("tiledb://workspace/teamspace/array") ==
+            tiledb::Context::DataProtocol::v3);
+      }
+    }
+  }
+
+  SECTION("non-tiledb:// URI") {
+    REQUIRE(
+        ctx.data_protocol("s3://bucket/array") ==
+        tiledb::Context::DataProtocol::v2);
+  }
+}

tiledb/api/c_api/context/context_api.cc

@@ -142,6 +142,34 @@ capi_return_t tiledb_ctx_set_tag(
   return TILEDB_OK;
 }
 
+capi_return_t tiledb_ctx_get_data_protocol(
+    tiledb_ctx_t* ctx, const char* uri, tiledb_data_protocol_t* data_protocol) {
+  ensure_context_is_valid(ctx);
+  ensure_output_pointer_is_valid(data_protocol);
+
+  auto uri_to_check = tiledb::sm::URI(uri);
+  if (uri_to_check.is_invalid()) {
+    throw CAPIException("Cannot get data protocol; Invalid URI");
+  }
+
+  if (tiledb::sm::URI::is_tiledb(uri)) {
+    if (!ctx->has_rest_client()) {
+      throw CAPIException(
+          "Cannot get data protocol; REST client not configured");
+    }
+
+    if (ctx->rest_client().rest_legacy()) {
+      *data_protocol = TILEDB_DATA_PROTOCOL_v2;
+    } else {
+      *data_protocol = TILEDB_DATA_PROTOCOL_v3;
+    }
+  } else {
+    *data_protocol = TILEDB_DATA_PROTOCOL_v2;
+  }
+
+  return TILEDB_OK;
+}
+
 }  // namespace tiledb::api
 
 using tiledb::api::api_entry_with_context;
@@ -206,3 +234,12 @@ CAPI_INTERFACE(
   return api_entry_with_context<tiledb::api::tiledb_ctx_set_tag>(
       ctx, key, value);
 }
+
+CAPI_INTERFACE(
+    ctx_get_data_protocol,
+    tiledb_ctx_t* ctx,
+    const char* uri,
+    tiledb_data_protocol_t* data_protocol) {
+  return api_entry_with_context<tiledb::api::tiledb_ctx_get_data_protocol>(
+      ctx, uri, data_protocol);
+}

tiledb/api/c_api/context/context_api_external.h

@@ -46,6 +46,16 @@ extern "C" {
  */
 typedef struct tiledb_ctx_handle_t tiledb_ctx_t;
 
+/**
+ * REST data model version.
+ */
+typedef enum {
+  /** REST API v2 (legacy) */
+  TILEDB_DATA_PROTOCOL_v2 = 0,
+  /** REST API v3 (Tiledb 3.0+) */
+  TILEDB_DATA_PROTOCOL_v3 = 1
+} tiledb_data_protocol_t;
+
 /**
  * Creates a TileDB context, which contains the TileDB storage manager
  * that manages everything in the TileDB library.
@@ -227,6 +237,27 @@ TILEDB_EXPORT capi_return_t tiledb_ctx_cancel_tasks(tiledb_ctx_t* ctx)
 TILEDB_EXPORT capi_return_t tiledb_ctx_set_tag(
     tiledb_ctx_t* ctx, const char* key, const char* value) TILEDB_NOEXCEPT;
 
+/**
+ * Returns the REST data model version for the given context.
+ *
+ * **Example:**
+ *
+ * @code{.c}
+ * tiledb_data_protocol_t data_protocol;
+ * tiledb_ctx_get_data_protocol(ctx, "tiledb://workspace/teamspace/array",
+ * &data_protocol);
+ * @endcode
+ *
+ * @param ctx The TileDB context.
+ * @param uri The URI to check.
+ * @param data_protocol Set to the data protocol version.
+ * @return `TILEDB_OK` for success and `TILEDB_ERR` for error.
+ */
+TILEDB_EXPORT capi_return_t tiledb_ctx_get_data_protocol(
+    tiledb_ctx_t* ctx,
+    const char* uri,
+    tiledb_data_protocol_t* data_protocol) TILEDB_NOEXCEPT;
+
 #ifdef __cplusplus
 }
 #endif

tiledb/sm/cpp_api/context.h

@@ -221,6 +221,35 @@ class Context {
     handle_error(tiledb_ctx_set_tag(ctx_.get(), key.c_str(), value.c_str()));
   }
 
+  /**
+   * Data protocol version enum.
+   */
+  enum class DataProtocol : uint8_t {
+    /** Data protocol v2 (legacy) */
+    v2 = TILEDB_DATA_PROTOCOL_v2,
+    /** Data protocol v3 (TileDB 3.0+) */
+    v3 = TILEDB_DATA_PROTOCOL_v3
+  };
+
+  /**
+   * Returns the data protocol version for the given URI.
+   *
+   * **Example:**
+   * @code{.cpp}
+   * tiledb::Context ctx;
+   * auto data_protocol = ctx.data_protocol("tiledb://namespace/array");
+   * @endcode
+   *
+   * @param uri The URI to check.
+   * @return The data protocol version.
+   */
+  DataProtocol data_protocol(const std::string& uri) const {
+    tiledb_data_protocol_t protocol;
+    handle_error(
+        tiledb_ctx_get_data_protocol(ctx_.get(), uri.c_str(), &protocol));
+    return static_cast<DataProtocol>(protocol);
+  }
+
   /** Returns a JSON-formatted string of the stats. */
   std::string stats() {
     char* c_str;