Auth Manager API part 1: HTTPRequest, HTTPHeader

core/src/main/java/org/apache/iceberg/rest/HTTPHeaders.java

@@ -0,0 +1,168 @@
+/*
+ * 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.
+ */
+package org.apache.iceberg.rest;
+
+import java.util.List;
+import java.util.Locale;
+import java.util.Map;
+import java.util.stream.Collectors;
+import org.apache.iceberg.relocated.com.google.common.collect.ImmutableListMultimap;
+import org.apache.iceberg.relocated.com.google.common.collect.ListMultimap;
+import org.apache.iceberg.relocated.com.google.common.collect.Multimap;
+import org.immutables.value.Value;
+
+/**
+ * Represents a group of HTTP headers.
+ *
+ * <p>Header name comparison in this class is always case-insensitive, in accordance with RFC 2616.
+ *
+ * <p>This class exposes methods to convert to and from different representations such as maps and
+ * multimap, for easier access and manipulation – especially when dealing with multiple headers with
+ * the same name.
+ */
+@Value.Style(depluralize = true)
+@Value.Immutable
+@SuppressWarnings({"ImmutablesStyle", "SafeLoggingPropagation"})
+public interface HTTPHeaders {
+
+  HTTPHeaders EMPTY = of();
+
+  /** Returns all the header entries in this group. */
+  List<HTTPHeader> entries();
+
+  /**
+   * Returns a map representation of the headers where each header name is mapped to a list of its
+   * values. Header names are case-insensitive.
+   */
+  @Value.Lazy
+  default Map<String, List<String>> asMap() {
+    return entries().stream()
+        .collect(Collectors.groupingBy(h -> h.name().toLowerCase(Locale.ROOT)))
+        .values()
+        .stream()
+        .collect(
+            Collectors.toMap(
+                headers -> headers.get(0).name(),
+                headers -> headers.stream().map(HTTPHeader::value).collect(Collectors.toList())));
+  }
+
+  /**
+   * Returns a simple map representation of the headers where each header name is mapped to its
+   * first value. If a header has multiple values, only the first value is used. Header names are
+   * case-insensitive.
+   */
+  @Value.Lazy
+  default Map<String, String> asSimpleMap() {
+    return entries().stream()
+        .collect(Collectors.groupingBy(h -> h.name().toLowerCase(Locale.ROOT)))
+        .values()
+        .stream()
+        .collect(
+            Collectors.toMap(headers -> headers.get(0).name(), headers -> headers.get(0).value()));
+  }
+
+  /**
+   * Returns a {@link ListMultimap} representation of the headers. Header names are
+   * case-insensitive.
+   */
+  @Value.Lazy
+  default ListMultimap<String, String> asMultiMap() {
+    return entries().stream()
+        .collect(Collectors.groupingBy(h -> h.name().toLowerCase(Locale.ROOT)))
+        .values()
+        .stream()
+        .collect(
+            ImmutableListMultimap.flatteningToImmutableListMultimap(
+                headers -> headers.get(0).name(),
+                headers -> headers.stream().map(HTTPHeader::value)));
+  }
+
+  /** Returns all the entries in this group for the given name (case-insensitive). */
+  default List<HTTPHeader> entries(String name) {
+    return entries().stream()
+        .filter(header -> header.name().equalsIgnoreCase(name))
+        .collect(Collectors.toList());
+  }
+
+  /** Returns whether this group contains an entry with the given name (case-insensitive). */
+  default boolean contains(String name) {
+    return entries().stream().anyMatch(header -> header.name().equalsIgnoreCase(name));
+  }
+
+  /**
+   * Adds the given header to the current group if no entry with the same name is already present.
+   * Returns a new instance with the added header, or the current instance if the header is already
+   * present.
+   */
+  default HTTPHeaders addIfAbsent(HTTPHeader header) {
+    return contains(header.name())
+        ? this
+        : ImmutableHTTPHeaders.builder().from(this).addEntry(header).build();
+  }
+
+  /**
+   * Adds the given headers to the current group if no entries with same names are already present.
+   * Returns a new instance with the added headers, or the current instance if all headers are
+   * already present.
+   */
+  default HTTPHeaders addIfAbsent(HTTPHeaders headers) {
+    List<HTTPHeader> newHeaders =
+        headers.entries().stream().filter(e -> !contains(e.name())).collect(Collectors.toList());
+    return newHeaders.isEmpty()
+        ? this
+        : ImmutableHTTPHeaders.builder().from(this).addAllEntries(newHeaders).build();
+  }
+
+  static HTTPHeaders of(HTTPHeader... headers) {
+    return ImmutableHTTPHeaders.builder().addEntries(headers).build();
+  }
+
+  static HTTPHeaders fromMap(Map<String, ? extends Iterable<String>> headers) {
+    ImmutableHTTPHeaders.Builder builder = ImmutableHTTPHeaders.builder();
+    headers.forEach(
+        (name, values) -> values.forEach(value -> builder.addEntry(HTTPHeader.of(name, value))));
+    return builder.build();
+  }
+
+  static HTTPHeaders fromSimpleMap(Map<String, String> headers) {
+    ImmutableHTTPHeaders.Builder builder = ImmutableHTTPHeaders.builder();
+    headers.forEach((name, value) -> builder.addEntry(HTTPHeader.of(name, value)));
+    return builder.build();
+  }
+
+  static HTTPHeaders fromMultiMap(Multimap<String, String> headers) {
+    return fromMap(headers.asMap());
+  }
+
+  /** Represents an HTTP header as a name-value pair. */
+  @Value.Style(redactedMask = "****", depluralize = true)
+  @Value.Immutable
+  @SuppressWarnings({"ImmutablesStyle", "SafeLoggingPropagation"})
+  interface HTTPHeader {
+
+    String name();
+
+    @Value.Redacted
+    String value();
+
+    static HTTPHeader of(String name, String value) {
+      return ImmutableHTTPHeader.builder().name(name).value(value).build();
+    }
+  }
+}

core/src/main/java/org/apache/iceberg/rest/HTTPRequest.java

@@ -0,0 +1,91 @@
+/*
+ * 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.
+ */
+package org.apache.iceberg.rest;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import java.net.URI;
+import java.util.Map;
+import javax.annotation.Nullable;
+import org.immutables.value.Value;
+
+/** Represents an HTTP request. */
+@Value.Style(redactedMask = "****", depluralize = true)
+@Value.Immutable
+@SuppressWarnings({"ImmutablesStyle", "SafeLoggingPropagation"})
+public interface HTTPRequest {
+
+  enum HTTPMethod {
+    GET,
+    HEAD,
+    POST,
+    DELETE
+  }
+
+  /**
+   * Returns the base URI configured at the REST client level. The base URI is used to construct the
+   * full {@link #requestUri()}.
+   */
+  URI baseUri();
+
+  /**
+   * Returns the full URI of this request. The URI is constructed from the base URI, path, and query
+   * parameters. It cannot be modified directly.
+   */
+  @Value.Lazy
+  default URI requestUri() {
+    return RESTUtil.buildRequestUri(this);
+  }
+
+  /** Returns the HTTP method of this request. */
+  HTTPMethod method();
+
+  /** Returns the path of this request. */
+  String path();
+
+  /** Returns the query parameters of this request. */
+  Map<String, String> queryParameters();
+
+  /** Returns the headers of this request. */
+  @Value.Default
+  default HTTPHeaders headers() {
+    return HTTPHeaders.EMPTY;
+  }
+
+  /** Returns the raw, unencoded request body. */
+  @Nullable
+  @Value.Redacted
+  Object body();
+
+  /** Returns the encoded request body as a string. */
+  @Value.Lazy
+  @Nullable
+  @Value.Redacted
+  default String encodedBody() {
+    return RESTUtil.encodeRequestBody(this);
+  }
+
+  /**
+   * Returns the {@link ObjectMapper} to use for encoding the request body. The default is {@link
+   * RESTObjectMapper#mapper()}.
+   */
+  @Value.Default
+  default ObjectMapper mapper() {
+    return RESTObjectMapper.mapper();
+  }
+}

core/src/main/java/org/apache/iceberg/rest/RESTUtil.java

@@ -18,13 +18,18 @@
  */
 package org.apache.iceberg.rest;
 
+import com.fasterxml.jackson.core.JsonProcessingException;
 import java.io.UncheckedIOException;
 import java.io.UnsupportedEncodingException;
+import java.net.URI;
+import java.net.URISyntaxException;
 import java.net.URLDecoder;
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
 import java.util.Map;
+import org.apache.hc.core5.net.URIBuilder;
 import org.apache.iceberg.catalog.Namespace;
+import org.apache.iceberg.exceptions.RESTException;
 import org.apache.iceberg.relocated.com.google.common.base.Joiner;
 import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
 import org.apache.iceberg.relocated.com.google.common.base.Splitter;
@@ -215,4 +220,45 @@ public static Namespace decodeNamespace(String encodedNs) {
 
     return Namespace.of(levels);
   }
+
+  /** Builds a request URI from a base URI and an {@link HTTPRequest}. */
+  public static URI buildRequestUri(HTTPRequest request) {
+    // if full path is provided, use the input path as path
+    String path = request.path();
+    if (path.startsWith("/")) {
+      throw new RESTException(
+          "Received a malformed path for a REST request: %s. Paths should not start with /", path);
+    }
+    String fullPath =
+        (path.startsWith("https://") || path.startsWith("http://"))
+            ? path
+            : String.format("%s/%s", request.baseUri(), path);
+    try {
+      URIBuilder builder = new URIBuilder(stripTrailingSlash(fullPath));
+      request.queryParameters().forEach(builder::addParameter);
+      return builder.build();
+    } catch (URISyntaxException e) {
+      throw new RESTException(
+          "Failed to create request URI from base %s, params %s",
+          fullPath, request.queryParameters());
+    }
+  }
+
+  /**
+   * Encodes the body of an HTTP request as a String. By convention, maps are encoded as form data
+   * and other objects are encoded as JSON.
+   */
+  public static String encodeRequestBody(HTTPRequest request) {
+    Object body = request.body();
+    if (body instanceof Map) {
+      return encodeFormData((Map<?, ?>) body);
+    } else if (body != null) {
+      try {
+        return request.mapper().writeValueAsString(body);
+      } catch (JsonProcessingException e) {
+        throw new RESTException(e, "Failed to encode request body: %s", body);
+      }
+    }
+    return null;
+  }
 }