feat: add config, error and validation for rest types (#292)

Author: HeartLinked

meson.build

@@ -30,6 +30,10 @@ project(
     ],
 )
 
+cpp = meson.get_compiler('cpp')
+args = cpp.get_supported_arguments(['/bigobj'])
+add_project_arguments(args, language: 'cpp')
+
 subdir('src')
 
 install_data(

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

@@ -20,13 +20,13 @@
 #include "iceberg/catalog/rest/json_internal.h"
 
 #include <string>
-#include <unordered_map>
 #include <utility>
 #include <vector>
 
 #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 +59,76 @@ 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;
+  SetContainerField(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;
+  SetContainerField(json, kStack, error.stack);
+  return json;
+}
+
+Result<ErrorModel> ErrorModelFromJson(const nlohmann::json& json) {
+  ErrorModel error;
+  // NOTE: Iceberg's Java implementation allows missing required fields (message, type,
+  // code) during deserialization, which deviates from the REST spec. We enforce strict
+  // validation here.
+  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<uint32_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 +144,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 +162,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 +183,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 +201,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 +248,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 +304,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 +329,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 +339,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> defaults;   // required
+  std::unordered_map<std::string, std::string> overrides;  // 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
+  uint32_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,142 @@
+/*
+ * 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 <algorithm>
+#include <format>
+
+#include "iceberg/catalog/rest/types.h"
+#include "iceberg/result.h"
+#include "iceberg/util/formatter_internal.h"
+#include "iceberg/util/macros.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()) {
+    return Invalid("Invalid error model: missing required fields");
+  }
+
+  if (error.code < 400 || error.code > 600) {
+    return Invalid("Invalid error model: code {} is out of range [400, 600]", error.code);
+  }
+
+  // stack is optional, no validation needed
+  return {};
+}
+
+// We don't validate the error field because ErrorModel::Validate has been called in the
+// FromJson.
+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()) {
+    return {};
+  }
+
+  auto extract_and_sort = [](const auto& container, auto key_extractor) {
+    std::vector<std::string_view> result;
+    result.reserve(container.size());
+    for (const auto& item : container) {
+      result.push_back(std::string_view{key_extractor(item)});
+    }
+    std::ranges::sort(result);
+    return result;
+  };
+
+  auto sorted_removals =
+      extract_and_sort(request.removals, [](const auto& s) -> const auto& { return s; });
+  auto sorted_update_keys = extract_and_sort(
+      request.updates, [](const auto& pair) -> const auto& { return pair.first; });
+
+  std::vector<std::string_view> common;
+  std::ranges::set_intersection(sorted_removals, sorted_update_keys,
+                                std::back_inserter(common));
+
+  if (!common.empty()) {
+    return Invalid(
+        "Invalid namespace update: cannot simultaneously set and remove keys: {}",
+        common);
+  }
+  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) {
+    return Invalid("Invalid metadata: null");
+  }
+  return {};
+}
+
+Status Validator::Validate(const RegisterTableRequest& request) {
+  if (request.name.empty()) {
+    return Invalid("Missing table name");
+  }
+
+  if (request.metadata_location.empty()) {
+    return Invalid("Empty metadata location");
+  }
+
+  return {};
+}
+
+Status Validator::Validate(const RenameTableRequest& request) {
+  ICEBERG_RETURN_UNEXPECTED(Validate(request.source));
+  ICEBERG_RETURN_UNEXPECTED(Validate(request.destination));
+  return {};
+}
+
+Status Validator::Validate(const TableIdentifier& identifier) {
+  if (identifier.name.empty()) {
+    return Invalid("Invalid table identifier: missing table name");
+  }
+  return {};
+}
+
+}  // namespace iceberg::rest