feat(rest): respect server-provided endpoints (#406)

Author: HeartLinked

src/iceberg/catalog/rest/CMakeLists.txt

@@ -16,12 +16,13 @@
 # under the License.
 
 set(ICEBERG_REST_SOURCES
-    rest_catalog.cc
     catalog_properties.cc
+    endpoint.cc
     error_handlers.cc
     http_client.cc
     json_internal.cc
     resource_paths.cc
+    rest_catalog.cc
     rest_util.cc)
 
 set(ICEBERG_REST_STATIC_BUILD_INTERFACE_LIBS)

src/iceberg/catalog/rest/endpoint.cc

@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#include "iceberg/catalog/rest/endpoint.h"
+
+#include <format>
+#include <string_view>
+
+namespace iceberg::rest {
+
+constexpr std::string_view ToString(HttpMethod method) {
+  switch (method) {
+    case HttpMethod::kGet:
+      return "GET";
+    case HttpMethod::kPost:
+      return "POST";
+    case HttpMethod::kPut:
+      return "PUT";
+    case HttpMethod::kDelete:
+      return "DELETE";
+    case HttpMethod::kHead:
+      return "HEAD";
+  }
+  return "UNKNOWN";
+}
+
+Result<Endpoint> Endpoint::Make(HttpMethod method, std::string_view path) {
+  if (path.empty()) {
+    return InvalidArgument("Endpoint cannot have empty path");
+  }
+  return Endpoint(method, path);
+}
+
+Result<Endpoint> Endpoint::FromString(std::string_view str) {
+  auto space_pos = str.find(' ');
+  if (space_pos == std::string_view::npos ||
+      str.find(' ', space_pos + 1) != std::string_view::npos) {
+    return InvalidArgument(
+        "Invalid endpoint format (must consist of two elements separated by a single "
+        "space): '{}'",
+        str);
+  }
+
+  auto method_str = str.substr(0, space_pos);
+  auto path_str = str.substr(space_pos + 1);
+
+  if (path_str.empty()) {
+    return InvalidArgument("Invalid endpoint format: path is empty");
+  }
+
+  // Parse HTTP method
+  HttpMethod method;
+  if (method_str == "GET") {
+    method = HttpMethod::kGet;
+  } else if (method_str == "POST") {
+    method = HttpMethod::kPost;
+  } else if (method_str == "PUT") {
+    method = HttpMethod::kPut;
+  } else if (method_str == "DELETE") {
+    method = HttpMethod::kDelete;
+  } else if (method_str == "HEAD") {
+    method = HttpMethod::kHead;
+  } else {
+    return InvalidArgument("Invalid HTTP method: '{}'", method_str);
+  }
+
+  return Make(method, std::string(path_str));
+}
+
+std::string Endpoint::ToString() const {
+  return std::format("{} {}", rest::ToString(method_), path_);
+}
+
+}  // namespace iceberg::rest

src/iceberg/catalog/rest/endpoint.h

@@ -0,0 +1,150 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+#pragma once
+
+#include <string>
+#include <string_view>
+
+#include "iceberg/catalog/rest/iceberg_rest_export.h"
+#include "iceberg/result.h"
+
+/// \file iceberg/catalog/rest/endpoint.h
+/// Endpoint definitions for Iceberg REST API operations.
+
+namespace iceberg::rest {
+
+/// \brief HTTP method enumeration.
+enum class HttpMethod : uint8_t { kGet, kPost, kPut, kDelete, kHead };
+
+/// \brief Convert HttpMethod to string representation.
+constexpr std::string_view ToString(HttpMethod method);
+
+/// \brief An Endpoint is an immutable value object identifying a specific REST API
+/// operation. It consists of:
+/// - HTTP method (GET, POST, DELETE, etc.)
+/// - Path template (e.g., "/v1/{prefix}/namespaces/{namespace}")
+class ICEBERG_REST_EXPORT Endpoint {
+ public:
+  /// \brief Make an endpoint with method and path template.
+  ///
+  /// \param method HTTP method (GET, POST, etc.)
+  /// \param path Path template with placeholders (e.g., "/v1/{prefix}/tables")
+  /// \return Endpoint instance or error if invalid
+  static Result<Endpoint> Make(HttpMethod method, std::string_view path);
+
+  /// \brief Parse endpoint from string representation. "METHOD" have to be all
+  /// upper-cased.
+  ///
+  /// \param str String in format "METHOD /path/template" (e.g., "GET /v1/namespaces")
+  /// \return Endpoint instance or error if malformed.
+  static Result<Endpoint> FromString(std::string_view str);
+
+  /// \brief Get the HTTP method.
+  constexpr HttpMethod method() const { return method_; }
+
+  /// \brief Get the path template.
+  std::string_view path() const { return path_; }
+
+  /// \brief Serialize to "METHOD /path" format.
+  std::string ToString() const;
+
+  constexpr bool operator==(const Endpoint& other) const {
+    return method_ == other.method_ && path_ == other.path_;
+  }
+
+  // Namespace endpoints
+  static Endpoint ListNamespaces() {
+    return {HttpMethod::kGet, "/v1/{prefix}/namespaces"};
+  }
+  static Endpoint GetNamespaceProperties() {
+    return {HttpMethod::kGet, "/v1/{prefix}/namespaces/{namespace}"};
+  }
+  static Endpoint NamespaceExists() {
+    return {HttpMethod::kHead, "/v1/{prefix}/namespaces/{namespace}"};
+  }
+  static Endpoint CreateNamespace() {
+    return {HttpMethod::kPost, "/v1/{prefix}/namespaces"};
+  }
+  static Endpoint UpdateNamespace() {
+    return {HttpMethod::kPost, "/v1/{prefix}/namespaces/{namespace}/properties"};
+  }
+  static Endpoint DropNamespace() {
+    return {HttpMethod::kDelete, "/v1/{prefix}/namespaces/{namespace}"};
+  }
+
+  // Table endpoints
+  static Endpoint ListTables() {
+    return {HttpMethod::kGet, "/v1/{prefix}/namespaces/{namespace}/tables"};
+  }
+  static Endpoint LoadTable() {
+    return {HttpMethod::kGet, "/v1/{prefix}/namespaces/{namespace}/tables/{table}"};
+  }
+  static Endpoint TableExists() {
+    return {HttpMethod::kHead, "/v1/{prefix}/namespaces/{namespace}/tables/{table}"};
+  }
+  static Endpoint CreateTable() {
+    return {HttpMethod::kPost, "/v1/{prefix}/namespaces/{namespace}/tables"};
+  }
+  static Endpoint UpdateTable() {
+    return {HttpMethod::kPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}"};
+  }
+  static Endpoint DeleteTable() {
+    return {HttpMethod::kDelete, "/v1/{prefix}/namespaces/{namespace}/tables/{table}"};
+  }
+  static Endpoint RenameTable() {
+    return {HttpMethod::kPost, "/v1/{prefix}/tables/rename"};
+  }
+  static Endpoint RegisterTable() {
+    return {HttpMethod::kPost, "/v1/{prefix}/namespaces/{namespace}/register"};
+  }
+  static Endpoint ReportMetrics() {
+    return {HttpMethod::kPost,
+            "/v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics"};
+  }
+  static Endpoint TableCredentials() {
+    return {HttpMethod::kGet,
+            "/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials"};
+  }
+
+  // Transaction endpoints
+  static Endpoint CommitTransaction() {
+    return {HttpMethod::kPost, "/v1/{prefix}/transactions/commit"};
+  }
+
+ private:
+  Endpoint(HttpMethod method, std::string_view path) : method_(method), path_(path) {}
+
+  HttpMethod method_;
+  std::string path_;
+};
+
+}  // namespace iceberg::rest
+
+// Specialize std::hash for Endpoint
+namespace std {
+template <>
+struct hash<iceberg::rest::Endpoint> {
+  std::size_t operator()(const iceberg::rest::Endpoint& endpoint) const noexcept {
+    std::size_t h1 = std::hash<int32_t>{}(static_cast<int32_t>(endpoint.method()));
+    std::size_t h2 = std::hash<std::string_view>{}(endpoint.path());
+    return h1 ^ (h2 + 0x9e3779b9 + (h1 << 6) + (h1 >> 2));
+  }
+};
+}  // namespace std

src/iceberg/catalog/rest/json_internal.cc

@@ -73,7 +73,9 @@ nlohmann::json ToJson(const CatalogConfig& config) {
   nlohmann::json json;
   json[kOverrides] = config.overrides;
   json[kDefaults] = config.defaults;
-  SetContainerField(json, kEndpoints, config.endpoints);
+  for (const auto& endpoint : config.endpoints) {
+    json[kEndpoints].emplace_back(endpoint.ToString());
+  }
   return json;
 }
 
@@ -85,8 +87,16 @@ Result<CatalogConfig> CatalogConfigFromJson(const nlohmann::json& json) {
   ICEBERG_ASSIGN_OR_RAISE(
       config.defaults, GetJsonValueOrDefault<decltype(config.defaults)>(json, kDefaults));
   ICEBERG_ASSIGN_OR_RAISE(
-      config.endpoints,
-      GetJsonValueOrDefault<std::vector<std::string>>(json, kEndpoints));
+      auto endpoints, GetJsonValueOrDefault<std::vector<std::string>>(json, kEndpoints));
+  config.endpoints.reserve(endpoints.size());
+  for (const auto& endpoint_str : endpoints) {
+    auto endpoint_result = Endpoint::FromString(endpoint_str);
+    if (!endpoint_result.has_value()) {
+      // Convert to JsonParseError in JSON deserialization context
+      return JsonParseError("{}", endpoint_result.error().message);
+    }
+    config.endpoints.emplace_back(std::move(endpoint_result.value()));
+  }
   ICEBERG_RETURN_UNEXPECTED(config.Validate());
   return config;
 }

src/iceberg/catalog/rest/meson.build

@@ -17,6 +17,7 @@
 
 iceberg_rest_sources = files(
     'catalog_properties.cc',
+    'endpoint.cc',
     'error_handlers.cc',
     'http_client.cc',
     'json_internal.cc',
@@ -58,6 +59,7 @@ install_headers(
     [
         'catalog_properties.h',
         'constant.h',
+        'endpoint.h',
         'error_handlers.h',
         'http_client.h',
         'iceberg_rest_export.h',