Add exception mappers to convert storage failures to Iceberg REST client exceptions

CHANGELOG.md

@@ -12,6 +12,10 @@ as necessary. Empty sections will not end in the release notes.
 
 ### Breaking changes
 
+- The `throttled-retry-after` advanced configuration property was renamed from
+  `nessie.catalog.service.s3.throttled-retry-after` to
+  `nessie.catalog.error-handling.throttled-retry-after`. The old property name is ignored.
+
 ### New Features
 
 - CLI: New `REVERT CONTENT` command to update one or more tables or views to a previous state.

catalog/files/api/src/main/java/org/projectnessie/catalog/files/api/NonRetryableException.java → catalog/files/api/src/main/java/org/projectnessie/catalog/files/api/BackendErrorCode.java

@@ -15,29 +15,29 @@
  */
 package org.projectnessie.catalog.files.api;
 
-import java.time.Instant;
-import java.util.Optional;
+public enum BackendErrorCode {
+  /**
+   * Treat unknown errors as non-retryable to prevent indefinite retry cycles when the server is not
+   * able to determine a specific failure reason. This may be changed in the future when task
+   * deadlines are supported.
+   */
+  UNKNOWN(false),
+  THROTTLED(true),
+  NOT_FOUND(false),
+  UNAUTHORIZED(false),
+  FORBIDDEN(false),
+  BAD_REQUEST(false),
+  NESSIE_ERROR(false),
+  ICEBERG_ERROR(false),
+  ;
 
-public class NonRetryableException extends ObjectIOException {
-  public NonRetryableException(Throwable cause) {
-    super(cause);
-  }
-
-  public NonRetryableException(String message) {
-    super(message);
-  }
+  private final boolean retryable;
 
-  public NonRetryableException(String message, Throwable cause) {
-    super(message, cause);
+  BackendErrorCode(boolean retryable) {
+    this.retryable = retryable;
   }
 
-  @Override
   public boolean isRetryable() {
-    return false;
-  }
-
-  @Override
-  public Optional<Instant> retryNotBefore() {
-    return Optional.empty();
+    return retryable;
   }
 }

catalog/files/api/src/main/java/org/projectnessie/catalog/files/api/BackendErrorStatus.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (C) 2024 Dremio
+ *
+ * Licensed 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.projectnessie.catalog.files.api;
+
+import static org.projectnessie.catalog.files.api.BackendErrorCode.BAD_REQUEST;
+import static org.projectnessie.catalog.files.api.BackendErrorCode.FORBIDDEN;
+import static org.projectnessie.catalog.files.api.BackendErrorCode.NOT_FOUND;
+import static org.projectnessie.catalog.files.api.BackendErrorCode.THROTTLED;
+import static org.projectnessie.catalog.files.api.BackendErrorCode.UNAUTHORIZED;
+import static org.projectnessie.catalog.files.api.BackendErrorCode.UNKNOWN;
+
+import org.projectnessie.nessie.immutables.NessieImmutable;
+
+@NessieImmutable
+public interface BackendErrorStatus {
+  BackendErrorCode statusCode();
+
+  Throwable cause();
+
+  static BackendErrorStatus of(BackendErrorCode statusCode, Throwable cause) {
+    return ImmutableBackendErrorStatus.of(statusCode, cause);
+  }
+
+  static BackendErrorStatus fromHttpStatusCode(int httpStatusCode, Throwable cause) {
+    switch (httpStatusCode) {
+      case 400:
+        return BackendErrorStatus.of(BAD_REQUEST, cause);
+      case 401:
+        return BackendErrorStatus.of(UNAUTHORIZED, cause);
+      case 403:
+        return BackendErrorStatus.of(FORBIDDEN, cause);
+      case 404:
+        return BackendErrorStatus.of(NOT_FOUND, cause);
+      case 429:
+        return BackendErrorStatus.of(THROTTLED, cause);
+      default:
+        return BackendErrorStatus.of(UNKNOWN, cause);
+    }
+  }
+}

catalog/files/api/src/main/java/org/projectnessie/catalog/files/api/BackendExceptionMapper.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright (C) 2024 Dremio
+ *
+ * Licensed 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.projectnessie.catalog.files.api;
+
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
+import java.util.List;
+import java.util.Optional;
+import org.projectnessie.nessie.immutables.NessieImmutable;
+
+@NessieImmutable
+public abstract class BackendExceptionMapper {
+
+  protected abstract List<Analyzer> analyzers();
+
+  public static Builder builder() {
+    return ImmutableBackendExceptionMapper.builder();
+  }
+
+  public Optional<BackendErrorStatus> analyze(Throwable ex) {
+    for (Throwable th = ex; th != null; th = th.getCause()) {
+      for (Analyzer analyzer : analyzers()) {
+        BackendErrorStatus status = analyzer.analyze(th);
+        if (status != null) {
+          return Optional.of(status);
+        }
+      }
+    }
+
+    return Optional.empty();
+  }
+
+  public interface Analyzer {
+    BackendErrorStatus analyze(Throwable th);
+  }
+
+  public interface Builder {
+    @CanIgnoreReturnValue
+    Builder addAnalyzer(Analyzer analyzer);
+
+    BackendExceptionMapper build();
+  }
+}