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/src/main/java/com/google/api/gax/rpc/ResumableUploadCommand.java

@@ -0,0 +1,42 @@
+/*
+ * 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;
+
+/** Enumeration of the supported resumable upload wire commands. */
+@NullMarked
+enum ResumableUploadCommand {
+  START,
+  UPLOAD,
+  FINALIZE,
+  UPLOAD_FINALIZE,
+  QUERY
+}

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

@@ -0,0 +1,136 @@
+/*
+ * 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.Objects;
+import org.jspecify.annotations.NullMarked;
+
+/**
+ * Classifies exceptions encountered during resumable upload commands to determine whether/how to
+ * recover.
+ */
+@NullMarked
+final class ResumableUploadErrorClassifier {
+
+  enum Category {
+    /** An errored command that can be retried directly. */
+    TRANSIENT,
+
+    /** An errored command that requires status from the server before recovery. */
+    RECOVERABLE,
+
+    /** An errored command that immediately fails the upload operation. */
+    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)
+          .build();
+
+  private ResumableUploadErrorClassifier() {}
+
+  /**
+   * Classifies an exception for the given upload command according to resumable upload 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(Throwable t, ResumableUploadCommand command) {
+    Objects.requireNonNull(t, "t must not be null");
+    Objects.requireNonNull(command, "command must not be null");
+
+    if (!(t instanceof ApiException)) {
+      return Category.FATAL;
+    }
+    ApiException apiException = (ApiException) t;
+    StatusCode statusCode = apiException.getStatusCode();
+
+    // HttpJsonApiExceptionFactory wraps non-HTTP errors as UNKNOWN.
+    if (statusCode.getCode() == StatusCode.Code.UNKNOWN) {
+      if (apiException.getCause() instanceof IOException) {
+        return Category.TRANSIENT;
+      }
+      return Category.FATAL;
+    }
+
+    Category category = HTTP_STATUS_MAP.getOrDefault(statusCode.getTransportCode(), Category.FATAL);
+    if (category == Category.RECOVERABLE && !isRecoverableCommand(command)) {
+      return Category.FATAL;
+    }
+    return category;
+  }
+
+  /**
+   * Classifies a missing upload status response header based on the wire command.
+   *
+   * @param command the upload command that received a response lacking the status header
+   * @return the classified error category
+   */
+  static Category classifyMissingStatusHeader(ResumableUploadCommand command) {
+    Objects.requireNonNull(command, "command must not be null");
+    switch (command) {
+      case START:
+        return Category.TRANSIENT;
+      case UPLOAD:
+      case FINALIZE:
+      case UPLOAD_FINALIZE:
+        return Category.RECOVERABLE;
+      case QUERY:
+      default:
+        return Category.FATAL;
+    }
+  }
+
+  private static boolean isRecoverableCommand(ResumableUploadCommand command) {
+    switch (command) {
+      case UPLOAD:
+      case FINALIZE:
+      case UPLOAD_FINALIZE:
+        return true;
+      case START:
+      case QUERY:
+      default:
+        return false;
+    }
+  }
+}

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

@@ -0,0 +1,69 @@
+/*
+ * 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 static com.google.api.gax.rpc.ResumableUploadErrorClassifier.Category.TRANSIENT;
+
+import com.google.api.gax.retrying.BasicResultRetryAlgorithm;
+import com.google.api.gax.rpc.ResumableUploadErrorClassifier.Category;
+import java.util.Objects;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * An adapter that integrates {@link ResumableUploadErrorClassifier} into GAX retrying machinery.
+ *
+ * <p>Only transient errors should retry with an identical request; other recoverable errors will
+ * need to query the upload server to determine the appropriate next request.
+ *
+ * @param <ResponseT> the response type of the upload attempt
+ */
+@NullMarked
+final class ResumableUploadResultRetryAlgorithm<ResponseT>
+    extends BasicResultRetryAlgorithm<ResponseT> {
+
+  private final ResumableUploadCommand command;
+
+  ResumableUploadResultRetryAlgorithm(ResumableUploadCommand command) {
+    this.command = Objects.requireNonNull(command);
+  }
+
+  @Override
+  public boolean shouldRetry(
+      @Nullable Throwable previousThrowable, @Nullable ResponseT previousResponse) {
+    // Successful commands should not retry.
+    if (previousThrowable == null) {
+      return false;
+    }
+    // Transient errors are retried directly with the identical request, others are not.
+    Category category = ResumableUploadErrorClassifier.classify(previousThrowable, command);
+    return category == TRANSIENT;
+  }
+}