You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by sc...@apache.org on 2026/07/08 23:39:38 UTC
(iceberg-rust) branch main updated: feat(catalog-rest): parse server-advertised endpoints from GET /v1/config (#2692)
This is an automated email from the ASF dual-hosted git repository.
CTTY pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-rust.git
The following commit(s) were added to refs/heads/main by this push:
new 2454d64f8 feat(catalog-rest): parse server-advertised endpoints from GET /v1/config (#2692)
2454d64f8 is described below
commit 2454d64f8ee4fb351d0e917620e5dd1971f7eeb2
Author: Xin Huang <42...@users.noreply.github.com>
AuthorDate: Wed Jul 8 16:39:32 2026 -0700
feat(catalog-rest): parse server-advertised endpoints from GET /v1/config (#2692)
## Which issue does this PR close?
Related to #1690 (server-side scan planning), which relies on endpoint
negotiation. This PR lands the negotiation piece on its own so it can be
reviewed independently.
## What changes are included in this PR?
The REST spec lets a server advertise the routes it supports in the
`endpoints`
field of its `GET /v1/config` response, so clients can negotiate
optional
capabilities instead of assuming every server implements every
operation. The
Rust client currently ignores this field.
This mirrors the capability negotiation the Java client gained in
apache/iceberg#10929 (the `endpoints` field in the config response, the
`Endpoint` type, and the default-endpoint fallback when a server omits
the list).
This PR:
- Adds an `Endpoint` type (HTTP method + path template) parsed from the
`"<method> <path>"` wire form via `FromStr` — which validates the
single-space
shape and the HTTP method — with serde delegating to it. The method is
stored
as a typed `http::Method` (kept out of the public API; `method()`
returns
`&str`).
- Parses the config response's `endpoints` into `Option<Vec<Endpoint>>`
so an
absent field and an explicit empty list are modelled distinctly, and
stores
the negotiated set on the catalog's runtime context.
- Resolves the set following the spec's optional-field semantics: an
absent
field → a standard base set of namespace/table operations is assumed (so
an
older server still resolves its core operations as supported); a present
list
— even an empty one — is used verbatim. Optional endpoints outside the
base
set stay unsupported unless explicitly advertised.
- Exposes `RestCatalog::supports_endpoint(&Endpoint)` to query the
negotiated
set.
No existing behaviour changes for callers that don't consult
`supports_endpoint`.
## Are these changes tested?
Yes:
- Unit tests for `Endpoint`: `FromStr`/serde round-trip, rejection of
malformed
input (no / extra / leading / trailing space, empty), HTTP-method
normalization, and the default endpoint set.
- `mockito` catalog tests: a server that advertises `endpoints`
(asserting
`supports_endpoint` is true/false for listed/unlisted routes), a server
that
omits the field (base operations resolve as supported), and a server
that
sends an explicit empty list (nothing is supported).
---
crates/catalog/rest/public-api.txt | 23 +++++
crates/catalog/rest/src/endpoint.rs | 162 ++++++++++++++++++++++++++++++++++++
crates/catalog/rest/src/lib.rs | 2 +
crates/catalog/rest/src/types.rs | 33 ++++++++
4 files changed, 220 insertions(+)
diff --git a/crates/catalog/rest/public-api.txt b/crates/catalog/rest/public-api.txt
index 027df29b2..13027559d 100644
--- a/crates/catalog/rest/public-api.txt
+++ b/crates/catalog/rest/public-api.txt
@@ -64,6 +64,29 @@ impl serde_core::ser::Serialize for iceberg_catalog_rest::CreateTableRequest
pub fn iceberg_catalog_rest::CreateTableRequest::serialize<__S>(&self, __serializer: __S) -> core::result::Result<<__S as serde_core::ser::Serializer>::Ok, <__S as serde_core::ser::Serializer>::Error> where __S: serde_core::ser::Serializer
impl<'de> serde_core::de::Deserialize<'de> for iceberg_catalog_rest::CreateTableRequest
pub fn iceberg_catalog_rest::CreateTableRequest::deserialize<__D>(__deserializer: __D) -> core::result::Result<Self, <__D as serde_core::de::Deserializer>::Error> where __D: serde_core::de::Deserializer<'de>
+pub struct iceberg_catalog_rest::Endpoint
+impl iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::method(&self) -> &str
+pub fn iceberg_catalog_rest::Endpoint::path(&self) -> &str
+impl core::clone::Clone for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::clone(&self) -> iceberg_catalog_rest::Endpoint
+impl core::cmp::Eq for iceberg_catalog_rest::Endpoint
+impl core::cmp::PartialEq for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::eq(&self, other: &iceberg_catalog_rest::Endpoint) -> bool
+impl core::fmt::Debug for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+impl core::fmt::Display for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+impl core::hash::Hash for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::hash<__H: core::hash::Hasher>(&self, state: &mut __H)
+impl core::marker::StructuralPartialEq for iceberg_catalog_rest::Endpoint
+impl core::str::traits::FromStr for iceberg_catalog_rest::Endpoint
+pub type iceberg_catalog_rest::Endpoint::Err = iceberg::error::Error
+pub fn iceberg_catalog_rest::Endpoint::from_str(s: &str) -> core::result::Result<Self, Self::Err>
+impl serde_core::ser::Serialize for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::serialize<S>(&self, serializer: S) -> core::result::Result<<S as serde_core::ser::Serializer>::Ok, <S as serde_core::ser::Serializer>::Error> where S: serde_core::ser::Serializer
+impl<'de> serde_core::de::Deserialize<'de> for iceberg_catalog_rest::Endpoint
+pub fn iceberg_catalog_rest::Endpoint::deserialize<D>(deserializer: D) -> core::result::Result<Self, <D as serde_core::de::Deserializer>::Error> where D: serde_core::de::Deserializer<'de>
pub struct iceberg_catalog_rest::ErrorModel
pub iceberg_catalog_rest::ErrorModel::code: u16
pub iceberg_catalog_rest::ErrorModel::message: alloc::string::String
diff --git a/crates/catalog/rest/src/endpoint.rs b/crates/catalog/rest/src/endpoint.rs
new file mode 100644
index 000000000..3d2f55f19
--- /dev/null
+++ b/crates/catalog/rest/src/endpoint.rs
@@ -0,0 +1,162 @@
+// 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.
+
+//! Server capability negotiation via the `endpoints` field of `GET /v1/config`.
+//!
+//! A REST server may advertise the set of routes it supports in the `endpoints`
+//! field of its configuration response, letting clients negotiate optional
+//! capabilities instead of assuming every server implements every operation.
+//! Each entry is a `"{method} {path}"` string, for example
+//! `"POST /v1/{prefix}/namespaces/{namespace}/tables"`; parse one through
+//! [`Endpoint`]'s [`FromStr`] implementation.
+//!
+//! Use [`RestCatalog::supports_endpoint`](crate::RestCatalog::supports_endpoint)
+//! to check whether the connected server advertised a given [`Endpoint`].
+
+use std::fmt::{self, Display, Formatter};
+use std::str::FromStr;
+
+use iceberg::{Error, ErrorKind};
+use reqwest::Method;
+use serde::de::{Error as DeError, Visitor};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+/// A single route a REST server advertises support for, parsed from the
+/// `endpoints` field of `GET /v1/config`.
+///
+/// The wire form is `"{method} {path}"` — an HTTP method and a path template
+/// separated by a single space, e.g.
+/// `"POST /v1/{prefix}/namespaces/{namespace}/tables"`. Parse one with
+/// [`str::parse`]: the method is validated and normalized, and the path is the
+/// template the server advertises (with `{prefix}`, `{namespace}`, …
+/// placeholders), compared verbatim.
+#[derive(Clone, Debug, PartialEq, Eq, Hash)]
+pub struct Endpoint {
+ method: Method,
+ path: String,
+}
+
+impl Endpoint {
+ /// The HTTP method, e.g. `GET` or `POST`.
+ pub fn method(&self) -> &str {
+ self.method.as_str()
+ }
+
+ /// The path template, e.g. `/v1/{prefix}/namespaces`.
+ pub fn path(&self) -> &str {
+ &self.path
+ }
+}
+
+impl FromStr for Endpoint {
+ type Err = Error;
+
+ fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
+ // The wire form is exactly `"<method> <path>"` separated by a single
+ // space; paths never contain spaces, so require exactly two non-empty
+ // parts and a valid HTTP method.
+ let mut parts = s.split(' ');
+ match (parts.next(), parts.next(), parts.next()) {
+ (Some(method), Some(path), None) if !method.is_empty() && !path.is_empty() => {
+ let method = Method::from_str(&method.to_ascii_uppercase()).map_err(|_| {
+ Error::new(
+ ErrorKind::DataInvalid,
+ format!("invalid HTTP method in endpoint: {s:?}"),
+ )
+ })?;
+ Ok(Self {
+ method,
+ path: path.to_string(),
+ })
+ }
+ _ => Err(Error::new(
+ ErrorKind::DataInvalid,
+ format!(
+ r#"invalid endpoint {s:?}: expected "<method> <path>" separated by a single space"#
+ ),
+ )),
+ }
+ }
+}
+
+impl Display for Endpoint {
+ fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
+ write!(f, "{} {}", self.method, self.path)
+ }
+}
+
+impl Serialize for Endpoint {
+ fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
+ where S: Serializer {
+ serializer.collect_str(self)
+ }
+}
+
+impl<'de> Deserialize<'de> for Endpoint {
+ fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
+ where D: Deserializer<'de> {
+ struct EndpointVisitor;
+
+ impl Visitor<'_> for EndpointVisitor {
+ type Value = Endpoint;
+
+ fn expecting(&self, f: &mut Formatter<'_>) -> fmt::Result {
+ f.write_str(r#"an endpoint string of the form "<method> <path>""#)
+ }
+
+ fn visit_str<E>(self, v: &str) -> std::result::Result<Endpoint, E>
+ where E: DeError {
+ Endpoint::from_str(v).map_err(E::custom)
+ }
+ }
+
+ deserializer.deserialize_str(EndpointVisitor)
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ #[test]
+ fn parses_and_round_trips() {
+ let ep: Endpoint = "POST /v1/{prefix}/namespaces/{namespace}/tables"
+ .parse()
+ .unwrap();
+ assert_eq!(ep.method(), "POST");
+ assert_eq!(ep.path(), "/v1/{prefix}/namespaces/{namespace}/tables");
+
+ let json = serde_json::to_string(&ep).unwrap();
+ assert_eq!(json, r#""POST /v1/{prefix}/namespaces/{namespace}/tables""#);
+ assert_eq!(serde_json::from_str::<Endpoint>(&json).unwrap(), ep);
+ }
+
+ #[test]
+ fn rejects_malformed_endpoints() {
+ for invalid in ["GET", "GET /v1", " GET /v1", "GET ", " /v1", ""] {
+ assert!(
+ invalid.parse::<Endpoint>().is_err(),
+ "expected {invalid:?} to be rejected"
+ );
+ }
+ }
+
+ #[test]
+ fn normalizes_http_method_to_uppercase() {
+ assert_eq!("get /v1/x".parse::<Endpoint>().unwrap().method(), "GET");
+ }
+}
diff --git a/crates/catalog/rest/src/lib.rs b/crates/catalog/rest/src/lib.rs
index 6bee95097..383728401 100644
--- a/crates/catalog/rest/src/lib.rs
+++ b/crates/catalog/rest/src/lib.rs
@@ -53,7 +53,9 @@
mod catalog;
mod client;
+mod endpoint;
mod types;
pub use catalog::*;
+pub use endpoint::Endpoint;
pub use types::*;
diff --git a/crates/catalog/rest/src/types.rs b/crates/catalog/rest/src/types.rs
index 21749fe0a..390521229 100644
--- a/crates/catalog/rest/src/types.rs
+++ b/crates/catalog/rest/src/types.rs
@@ -25,10 +25,15 @@ use iceberg::{
};
use serde_derive::{Deserialize, Serialize};
+use crate::endpoint::Endpoint;
+
#[derive(Clone, Debug, Serialize, Deserialize)]
pub(super) struct CatalogConfig {
pub(super) overrides: HashMap<String, String>,
pub(super) defaults: HashMap<String, String>,
+ /// Endpoints the server advertises support for; `None` when the field is
+ /// absent.
+ pub(super) endpoints: Option<Vec<Endpoint>>,
}
#[derive(Debug, Serialize, Deserialize)]
@@ -472,4 +477,32 @@ mod tests {
assert_eq!(request.stage_create, None);
assert!(request.properties.is_empty());
}
+
+ #[test]
+ fn config_parses_advertised_endpoints() {
+ let json = r#"{"overrides":{},"defaults":{},
+ "endpoints":["GET /v1/{prefix}/namespaces","POST /v1/{prefix}/namespaces/{namespace}/tables"]}"#;
+ let config: CatalogConfig = serde_json::from_str(json).unwrap();
+ let endpoints = config.endpoints.expect("endpoints should be present");
+ assert_eq!(endpoints.len(), 2);
+ assert!(endpoints.contains(&"GET /v1/{prefix}/namespaces".parse().unwrap()));
+ }
+
+ #[test]
+ fn config_without_endpoints_field_deserializes_to_none() {
+ // `Option<Vec<Endpoint>>` defaults to `None` for a missing field without
+ // an explicit `#[serde(default)]`.
+ let config: CatalogConfig =
+ serde_json::from_str(r#"{"overrides":{},"defaults":{}}"#).unwrap();
+ assert!(config.endpoints.is_none());
+ }
+
+ #[test]
+ fn malformed_endpoint_fails_config_parse() {
+ // A single malformed endpoint string fails the whole config parse,
+ // matching the Java reference (`ConfigResponseParser` rejects it rather
+ // than silently dropping it).
+ let json = r#"{"overrides":{},"defaults":{},"endpoints":["GET_v1/namespaces"]}"#;
+ assert!(serde_json::from_str::<CatalogConfig>(json).is_err());
+ }
}