feat(gax): add resumable upload error classification and retry algorithm

Introduce UploadCommand, UploadErrorClassifier, and UploadResultRetryAlgorithm
to classify HTTP response codes and transport-level exceptions during resumable
upload sessions into protocol error categories (TRANSIENT, RECOVERABLE, FATAL).

Implements the classification order:
1. CancellationException is terminal (FATAL) and never retried.
2. ApiException with StatusCode.Code.UNKNOWN unwraps cause. GAX wraps
   unrecognized runtime throwables into Code.UNKNOWN, which carries a
   synthetic HTTP 500 transport code. Without this explicit step, local bugs
   and NPEs would be misclassified as transient 500s and retried indefinitely.
   Real wire 500 responses arrive with Code.INTERNAL and are TRANSIENT.
3. Table lookup on raw HTTP transport code (408, 429, 500, 502, 503, 504 are
   TRANSIENT; 400, 409, 412, 416 are RECOVERABLE; 401, 403, 404, 405, 410,
   413, 415 are FATAL). Note that wire 408 and 412 both map to FAILED_PRECONDITION
   under HttpJsonStatusCode, but diverge based on raw HTTP transport code.
4. Plain I/O or timeout exceptions that bypassed ApiException wrapping are
   TRANSIENT; anything else unrecognized is FATAL.

Author: whowes

sdk-platform-java/gax-java/gax-httpjson/src/test/java/com/google/api/gax/httpjson/HttpJsonApiExceptionFactoryTest.java

@@ -148,4 +148,17 @@ void testCreate_withoutErrorDetails() {
     assertThat(apiException.getErrorDetails()).isNotNull();
     assertThat(apiException.getErrorDetails().getErrorInfo()).isNull();
   }
+
+  @Test
+  void testCreate_fromHttpJsonStatusRuntimeException() {
+    HttpJsonStatusRuntimeException statusException =
+        new HttpJsonStatusRuntimeException(503, "Failed to upload chunk", null);
+    HttpJsonApiExceptionFactory factory =
+        new HttpJsonApiExceptionFactory(ImmutableSet.of(Code.UNAVAILABLE));
+    ApiException apiException = factory.create(statusException);
+
+    assertThat(apiException.getStatusCode().getTransportCode()).isEqualTo(503);
+    assertThat(apiException.getStatusCode().getCode()).isEqualTo(Code.UNAVAILABLE);
+  }
 }
+

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/UploadCommand.java

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.rpc;
+
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Resumable upload wire commands whose responses and errors are subject to protocol classification
+ * and retries.
+ */
+@NullMarked
+enum UploadCommand {
+  START,
+  UPLOAD,
+  FINALIZE,
+  UPLOAD_FINALIZE,
+  QUERY,
+  CANCEL
+}

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/UploadErrorClassifier.java

@@ -0,0 +1,150 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.rpc;
+
+import com.google.common.collect.ImmutableMap;
+import java.io.IOException;
+import java.util.concurrent.CancellationException;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Classifies exceptions encountered during resumable upload commands into protocol error
+ * categories.
+ */
+@NullMarked
+final class UploadErrorClassifier {
+
+  enum Category {
+    TRANSIENT,
+    RECOVERABLE,
+    FATAL
+  }
+
+  private static final ImmutableMap<Integer, Category> HTTP_STATUS_MAP =
+      ImmutableMap.<Integer, Category>builder()
+          .put(408, Category.TRANSIENT)
+          .put(429, Category.TRANSIENT)
+          .put(500, Category.TRANSIENT)
+          .put(502, Category.TRANSIENT)
+          .put(503, Category.TRANSIENT)
+          .put(504, Category.TRANSIENT)
+          .put(400, Category.RECOVERABLE)
+          .put(409, Category.RECOVERABLE)
+          .put(412, Category.RECOVERABLE)
+          .put(416, Category.RECOVERABLE)
+          .put(401, Category.FATAL)
+          .put(403, Category.FATAL)
+          .put(404, Category.FATAL)
+          .put(405, Category.FATAL)
+          .put(410, Category.FATAL)
+          .put(413, Category.FATAL)
+          .put(415, Category.FATAL)
+          .build();
+
+  private UploadErrorClassifier() {}
+
+  /**
+   * Classifies an exception for the given upload command according to protocol rules.
+   *
+   * @param t the error to classify
+   * @param command the upload command that produced the error
+   * @return the classified error category
+   */
+  static Category classify(@Nullable Throwable t, UploadCommand command) {
+    if (t == null) {
+      return Category.FATAL;
+    }
+
+    // Cancellation is terminal and never retryable.
+    if (t instanceof CancellationException) {
+      return Category.FATAL;
+    }
+
+    // Handle ApiExceptions.
+    if (t instanceof ApiException) {
+      ApiException apiException = (ApiException) t;
+
+      // Code.UNKNOWN indicates an unrecognised throwable where synthetic HTTP 500
+      // should be ignored.
+      // Real HTTP 500 responses arrive with Code.INTERNAL.
+      if (apiException.getStatusCode().getCode() == StatusCode.Code.UNKNOWN) {
+        Throwable cause = apiException.getCause();
+        if (cause instanceof IOException) {
+          return Category.TRANSIENT;
+        }
+        return Category.FATAL;
+      }
+
+      // Status table lookup on raw HTTP transport code.
+      Object transportCode = apiException.getStatusCode().getTransportCode();
+      if (transportCode instanceof Integer) {
+        Category category = HTTP_STATUS_MAP.get(transportCode);
+        if (category != null) {
+          // The START command cannot enter recovery since no upload session exists yet.
+          if (command == UploadCommand.START && category == Category.RECOVERABLE) {
+            return Category.FATAL;
+          }
+          return category;
+        }
+      }
+      return Category.FATAL;
+    }
+
+    // Plain I/O or timeout exceptions that bypassed ApiException wrapping.
+    if (t instanceof IOException) {
+      return Category.TRANSIENT;
+    }
+
+    // Unrecognized errors fail the upload immediately. Never default to retryable.
+    return Category.FATAL;
+  }
+
+  /**
+   * Classifies a missing upload status response header according to the wire command.
+   *
+   * @param command the upload command that received a response lacking the status header
+   * @return the classified error category
+   */
+  static Category classifyMissingStatusHeader(UploadCommand command) {
+    switch (command) {
+      case START:
+        return Category.TRANSIENT;
+      case UPLOAD:
+      case FINALIZE:
+      case UPLOAD_FINALIZE:
+        return Category.RECOVERABLE;
+      case QUERY:
+      case CANCEL:
+      default:
+        return Category.FATAL;
+    }
+  }
+}

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/rpc/UploadResultRetryAlgorithm.java

@@ -0,0 +1,76 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are
+ * met:
+ *
+ *     * Redistributions of source code must retain the above copyright
+ * notice, this list of conditions and the following disclaimer.
+ *     * Redistributions in binary form must reproduce the above
+ * copyright notice, this list of conditions and the following disclaimer
+ * in the documentation and/or other materials provided with the
+ * distribution.
+ *     * Neither the name of Google LLC nor the names of its
+ * contributors may be used to endorse or promote products derived from
+ * this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+package com.google.api.gax.rpc;
+
+import com.google.api.gax.retrying.BasicResultRetryAlgorithm;
+import com.google.api.gax.retrying.ResultRetryAlgorithmWithContext;
+import com.google.api.gax.retrying.RetryingContext;
+import java.util.Objects;
+import java.util.concurrent.CancellationException;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * An adapter that integrates {@link UploadErrorClassifier} into GAX retrying machinery via
+ * {@link ResultRetryAlgorithmWithContext}.
+ *
+ * <p>Retries transient errors with the identical request.
+ *
+ * @param <ResponseT> the response type of the upload attempt
+ */
+@NullMarked
+final class UploadResultRetryAlgorithm<ResponseT>
+    extends BasicResultRetryAlgorithm<ResponseT> {
+
+  private final UploadCommand command;
+
+  UploadResultRetryAlgorithm(UploadCommand command) {
+    this.command = Objects.requireNonNull(command);
+  }
+
+  @Override
+  public boolean shouldRetry(
+      @Nullable Throwable previousThrowable, @Nullable ResponseT previousResponse) {
+    if (previousThrowable == null || previousThrowable instanceof CancellationException) {
+      return false;
+    }
+    UploadErrorCategory category = UploadErrorClassifier.classify(previousThrowable, command);
+    // Transient errors are retried directly with the identical request.
+    return category == UploadErrorCategory.TRANSIENT;
+  }
+
+  @Override
+  public boolean shouldRetry(
+      RetryingContext context,
+      @Nullable Throwable previousThrowable,
+      @Nullable ResponseT previousResponse) {
+    return shouldRetry(previousThrowable, previousResponse);
+  }
+}