feat: add config, error and validation for rest types

Author: HeartLinked

src/iceberg/catalog/rest/CMakeLists.txt

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-set(ICEBERG_REST_SOURCES rest_catalog.cc json_internal.cc)
+set(ICEBERG_REST_SOURCES rest_catalog.cc json_internal.cc validator.cc)
 
 set(ICEBERG_REST_STATIC_BUILD_INTERFACE_LIBS)
 set(ICEBERG_REST_SHARED_BUILD_INTERFACE_LIBS)

src/iceberg/catalog/rest/json_internal.cc

@@ -27,6 +27,7 @@
 #include <nlohmann/json.hpp>
 
 #include "iceberg/catalog/rest/types.h"
+#include "iceberg/catalog/rest/validator.h"
 #include "iceberg/json_internal.h"
 #include "iceberg/table_identifier.h"
 #include "iceberg/util/json_util_internal.h"
@@ -59,9 +60,77 @@ constexpr std::string_view kDestination = "destination";
 constexpr std::string_view kMetadata = "metadata";
 constexpr std::string_view kConfig = "config";
 constexpr std::string_view kIdentifiers = "identifiers";
+constexpr std::string_view kOverrides = "overrides";
+constexpr std::string_view kDefaults = "defaults";
+constexpr std::string_view kEndpoints = "endpoints";
+constexpr std::string_view kMessage = "message";
+constexpr std::string_view kType = "type";
+constexpr std::string_view kCode = "code";
+constexpr std::string_view kStack = "stack";
+constexpr std::string_view kError = "error";
 
 }  // namespace
 
+nlohmann::json ToJson(const CatalogConfig& config) {
+  nlohmann::json json;
+  json[kOverrides] = config.overrides;
+  json[kDefaults] = config.defaults;
+  if (!config.endpoints.empty()) {
+    json[kEndpoints] = config.endpoints;
+  }
+  return json;
+}
+
+Result<CatalogConfig> CatalogConfigFromJson(const nlohmann::json& json) {
+  CatalogConfig config;
+  ICEBERG_ASSIGN_OR_RAISE(
+      config.overrides,
+      GetJsonValueOrDefault<decltype(config.overrides)>(json, kOverrides));
+  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));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(config));
+  return config;
+}
+
+nlohmann::json ToJson(const ErrorModel& error) {
+  nlohmann::json json;
+  json[kMessage] = error.message;
+  json[kType] = error.type;
+  json[kCode] = error.code;
+  if (!error.stack.empty()) {
+    json[kStack] = error.stack;
+  }
+  return json;
+}
+
+Result<ErrorModel> ErrorModelFromJson(const nlohmann::json& json) {
+  ErrorModel error;
+  ICEBERG_ASSIGN_OR_RAISE(error.message, GetJsonValue<std::string>(json, kMessage));
+  ICEBERG_ASSIGN_OR_RAISE(error.type, GetJsonValue<std::string>(json, kType));
+  ICEBERG_ASSIGN_OR_RAISE(error.code, GetJsonValue<uint16_t>(json, kCode));
+  ICEBERG_ASSIGN_OR_RAISE(error.stack,
+                          GetJsonValueOrDefault<std::vector<std::string>>(json, kStack));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(error));
+  return error;
+}
+
+nlohmann::json ToJson(const ErrorResponse& response) {
+  nlohmann::json json;
+  json[kError] = ToJson(response.error);
+  return json;
+}
+
+Result<ErrorResponse> ErrorResponseFromJson(const nlohmann::json& json) {
+  ErrorResponse response;
+  ICEBERG_ASSIGN_OR_RAISE(auto error_json, GetJsonValue<nlohmann::json>(json, kError));
+  ICEBERG_ASSIGN_OR_RAISE(response.error, ErrorModelFromJson(error_json));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(response));
+  return response;
+}
+
 nlohmann::json ToJson(const CreateNamespaceRequest& request) {
   nlohmann::json json;
   json[kNamespace] = request.namespace_.levels;
@@ -77,6 +146,7 @@ Result<CreateNamespaceRequest> CreateNamespaceRequestFromJson(
   ICEBERG_ASSIGN_OR_RAISE(
       request.properties,
       GetJsonValueOrDefault<decltype(request.properties)>(json, kProperties));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(request));
   return request;
 }
 
@@ -94,6 +164,7 @@ Result<UpdateNamespacePropertiesRequest> UpdateNamespacePropertiesRequestFromJso
       request.removals, GetJsonValueOrDefault<std::vector<std::string>>(json, kRemovals));
   ICEBERG_ASSIGN_OR_RAISE(
       request.updates, GetJsonValueOrDefault<decltype(request.updates)>(json, kUpdates));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(request));
   return request;
 }
 
@@ -114,6 +185,7 @@ Result<RegisterTableRequest> RegisterTableRequestFromJson(const nlohmann::json&
                           GetJsonValue<std::string>(json, kMetadataLocation));
   ICEBERG_ASSIGN_OR_RAISE(request.overwrite,
                           GetJsonValueOrDefault<bool>(json, kOverwrite, false));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(request));
   return request;
 }
 
@@ -131,6 +203,7 @@ Result<RenameTableRequest> RenameTableRequestFromJson(const nlohmann::json& json
   ICEBERG_ASSIGN_OR_RAISE(auto dest_json,
                           GetJsonValue<nlohmann::json>(json, kDestination));
   ICEBERG_ASSIGN_OR_RAISE(request.destination, TableIdentifierFromJson(dest_json));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(request));
   return request;
 }
 
@@ -177,6 +250,7 @@ Result<ListNamespacesResponse> ListNamespacesResponseFromJson(
     ICEBERG_ASSIGN_OR_RAISE(auto ns, NamespaceFromJson(ns_json));
     response.namespaces.push_back(std::move(ns));
   }
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(response));
   return response;
 }
 
@@ -232,6 +306,7 @@ Result<UpdateNamespacePropertiesResponse> UpdateNamespacePropertiesResponseFromJ
       response.removed, GetJsonValueOrDefault<std::vector<std::string>>(json, kRemoved));
   ICEBERG_ASSIGN_OR_RAISE(
       response.missing, GetJsonValueOrDefault<std::vector<std::string>>(json, kMissing));
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(response));
   return response;
 }
 
@@ -256,6 +331,7 @@ Result<ListTablesResponse> ListTablesResponseFromJson(const nlohmann::json& json
     ICEBERG_ASSIGN_OR_RAISE(auto identifier, TableIdentifierFromJson(id_json));
     response.identifiers.push_back(std::move(identifier));
   }
+  ICEBERG_RETURN_UNEXPECTED(Validator::Validate(response));
   return response;
 }
 
@@ -265,6 +341,9 @@ Result<ListTablesResponse> ListTablesResponseFromJson(const nlohmann::json& json
     return Model##FromJson(json);                             \
   }
 
+ICEBERG_DEFINE_FROM_JSON(CatalogConfig)
+ICEBERG_DEFINE_FROM_JSON(ErrorModel)
+ICEBERG_DEFINE_FROM_JSON(ErrorResponse)
 ICEBERG_DEFINE_FROM_JSON(ListNamespacesResponse)
 ICEBERG_DEFINE_FROM_JSON(CreateNamespaceRequest)
 ICEBERG_DEFINE_FROM_JSON(CreateNamespaceResponse)

src/iceberg/catalog/rest/json_internal.h

@@ -25,6 +25,9 @@
 #include "iceberg/catalog/rest/types.h"
 #include "iceberg/result.h"
 
+/// \file iceberg/catalog/rest/json_internal.h
+/// JSON serialization and deserialization for Iceberg REST Catalog API types.
+
 namespace iceberg::rest {
 
 template <typename Model>
@@ -40,6 +43,9 @@ Result<Model> FromJson(const nlohmann::json& json);
 
 /// \note Don't forget to add `ICEBERG_DEFINE_FROM_JSON` to the end of
 /// `json_internal.cc` to define the `FromJson` function for the model.
+ICEBERG_DECLARE_JSON_SERDE(CatalogConfig)
+ICEBERG_DECLARE_JSON_SERDE(ErrorModel)
+ICEBERG_DECLARE_JSON_SERDE(ErrorResponse)
 ICEBERG_DECLARE_JSON_SERDE(ListNamespacesResponse)
 ICEBERG_DECLARE_JSON_SERDE(CreateNamespaceRequest)
 ICEBERG_DECLARE_JSON_SERDE(CreateNamespaceResponse)

src/iceberg/catalog/rest/meson.build

@@ -15,7 +15,11 @@
 # specific language governing permissions and limitations
 # under the License.
 
-iceberg_rest_sources = files('json_internal.cc', 'rest_catalog.cc')
+iceberg_rest_sources = files(
+    'json_internal.cc',
+    'rest_catalog.cc',
+    'validator.cc',
+)
 # cpr does not export symbols, so on Windows it must
 # be used as a static lib
 cpr_needs_static = (
@@ -46,4 +50,7 @@ iceberg_rest_dep = declare_dependency(
 meson.override_dependency('iceberg-rest', iceberg_rest_dep)
 pkg.generate(iceberg_rest_lib)
 
-install_headers(['rest_catalog.h', 'types.h'], subdir: 'iceberg/catalog/rest')
+install_headers(
+    ['rest_catalog.h', 'types.h', 'json_internal.h', 'validator.h'],
+    subdir: 'iceberg/catalog/rest',
+)

src/iceberg/catalog/rest/types.h

@@ -20,7 +20,6 @@
 #pragma once
 
 #include <memory>
-#include <optional>
 #include <string>
 #include <unordered_map>
 #include <vector>
@@ -34,6 +33,26 @@
 
 namespace iceberg::rest {
 
+/// \brief Server-provided configuration for the catalog.
+struct ICEBERG_REST_EXPORT CatalogConfig {
+  std::unordered_map<std::string, std::string> overrides;  // required
+  std::unordered_map<std::string, std::string> defaults;   // required
+  std::vector<std::string> endpoints;
+};
+
+/// \brief JSON error payload returned in a response with further details on the error.
+struct ICEBERG_REST_EXPORT ErrorModel {
+  std::string message;  // required
+  std::string type;     // required
+  uint16_t code;        // required
+  std::vector<std::string> stack;
+};
+
+/// \brief Error response body returned in a response.
+struct ICEBERG_REST_EXPORT ErrorResponse {
+  ErrorModel error;  // required
+};
+
 /// \brief Request to create a namespace.
 struct ICEBERG_REST_EXPORT CreateNamespaceRequest {
   Namespace namespace_;  // required

src/iceberg/catalog/rest/validator.cc

@@ -0,0 +1,139 @@
+/*
+ * 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/validator.h"
+
+#include <format>
+#include <ranges>
+#include <unordered_set>
+#include <utility>
+
+#include "iceberg/catalog/rest/types.h"
+#include "iceberg/result.h"
+
+namespace iceberg::rest {
+
+// Configuration and Error types
+
+Status Validator::Validate(const CatalogConfig& config) {
+  // TODO(Li Feiyang): Add an invalidEndpoint test that validates endpoint format.
+  // See:
+  // https://github.com/apache/iceberg/blob/main/core/src/test/java/org/apache/iceberg/rest/responses/TestConfigResponseParser.java#L164
+  // for reference.
+  return {};
+}
+
+Status Validator::Validate(const ErrorModel& error) {
+  if (error.message.empty() || error.type.empty()) [[unlikely]] {
+    return Invalid("Invalid error model: missing required fields");
+  }
+
+  if (error.code < 400 || error.code > 600) [[unlikely]] {
+    return Invalid("Invalid error model: code must be between 400 and 600");
+  }
+
+  // stack is optional, no validation needed
+  return {};
+}
+
+Status Validator::Validate(const ErrorResponse& response) { return {}; }
+
+// Namespace operations
+
+Status Validator::Validate(const ListNamespacesResponse& response) { return {}; }
+
+Status Validator::Validate(const CreateNamespaceRequest& request) { return {}; }
+
+Status Validator::Validate(const CreateNamespaceResponse& response) { return {}; }
+
+Status Validator::Validate(const GetNamespaceResponse& response) { return {}; }
+
+Status Validator::Validate(const UpdateNamespacePropertiesRequest& request) {
+  // keys in updates and removals must not overlap
+  if (request.removals.empty() || request.updates.empty()) [[unlikely]] {
+    return {};
+  }
+
+  std::unordered_set<std::string> remove_set(request.removals.begin(),
+                                             request.removals.end());
+  std::vector<std::string> common;
+
+  for (const std::string& k : request.updates | std::views::keys) {
+    if (remove_set.contains(k)) {
+      common.push_back(k);
+    }
+  }
+
+  if (!common.empty()) {
+    std::string keys;
+    bool first = true;
+    for (const std::string& s : common) {
+      if (!std::exchange(first, false)) keys += ", ";
+      keys += s;
+    }
+
+    return Invalid(
+        "Invalid namespace properties update: cannot simultaneously set and remove keys: "
+        "[{}]",
+        keys);
+  }
+  return {};
+}
+
+Status Validator::Validate(const UpdateNamespacePropertiesResponse& response) {
+  return {};
+}
+
+// Table operations
+
+Status Validator::Validate(const ListTablesResponse& response) { return {}; }
+
+Status Validator::Validate(const LoadTableResult& result) {
+  if (!result.metadata) [[unlikely]] {
+    return Invalid("Invalid metadata: null");
+  }
+  return {};
+}
+
+Status Validator::Validate(const RegisterTableRequest& request) {
+  if (request.name.empty()) [[unlikely]] {
+    return Invalid("Invalid table name: empty");
+  }
+
+  if (request.metadata_location.empty()) [[unlikely]] {
+    return Invalid("Invalid metadata location: empty");
+  }
+
+  return {};
+}
+
+Status Validator::Validate(const RenameTableRequest& request) {
+  if (request.source.ns.levels.empty() || request.source.name.empty()) [[unlikely]] {
+    return Invalid("Invalid source identifier");
+  }
+
+  if (request.destination.ns.levels.empty() || request.destination.name.empty())
+      [[unlikely]] {
+    return Invalid("Invalid destination identifier");
+  }
+
+  return {};
+}
+
+}  // namespace iceberg::rest