feat(gax): include upload-status header in resumable upload command response objects (#14420)

This is needed to meet the requirement that the protocol implementation
inspect responses for the presence of this header, responding
differently in its absence depending on the command (e.g. treat as
transient error for start commands, recoverable error for upload, fatal
error for query)

Author: whowes

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/ResumableUploadChunkCallable.java

@@ -33,10 +33,9 @@
 import com.google.api.core.ApiFuture;
 import com.google.api.gax.resumable.ChunkUploadRequest;
 import com.google.api.gax.resumable.ChunkUploadResponse;
+import com.google.api.gax.resumable.ResumableUploadStatus;
 import com.google.api.gax.rpc.ApiCallContext;
-import com.google.api.gax.rpc.ApiExceptionFactory;
 import com.google.api.gax.rpc.ClientContext;
-import com.google.api.gax.rpc.StatusCode;
 import com.google.api.gax.rpc.UnaryCallable;
 import com.google.api.pathtemplate.PathTemplate;
 import com.google.common.base.Preconditions;
@@ -59,7 +58,6 @@ class ResumableUploadChunkCallable<ResponseT>
   private static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
   private static final String UPLOAD_OFFSET_HEADER = "X-Goog-Upload-Offset";
   private static final String UPLOAD_STATUS_HEADER = "X-Goog-Upload-Status";
-  private static final String STATUS_FINAL = "final";
 
   private static final String COMMAND_UPLOAD = "upload";
   private static final String COMMAND_FINALIZE = "finalize";
@@ -165,7 +163,7 @@ private static class ChunkUploadResponseListener<ResponseT>
 
     private final ResumableUploadHttpJsonFuture<ChunkUploadResponse<ResponseT>> future;
     private final HttpResponseParser<ResponseT> responseParser;
-    @Nullable private String uploadStatus = null;
+    private ResumableUploadStatus uploadStatus = ResumableUploadStatus.UNKNOWN;
     private String responseBody = "";
 
     private ChunkUploadResponseListener(
@@ -178,7 +176,9 @@ private ChunkUploadResponseListener(
     @Override
     public void onHeaders(HttpJsonMetadata responseHeaders) {
       Map<String, Object> headers = responseHeaders.getHeaders();
-      this.uploadStatus = HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER);
+      this.uploadStatus =
+          ResumableUploadStatus.fromHeader(
+              HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER));
     }
 
     @Override
@@ -192,21 +192,9 @@ public void onMessage(@Nullable String message) {
     public void onClose(int statusCode, HttpJsonMetadata trailers) {
       try {
         if (statusCode >= 200 && statusCode < 300) {
-          if (uploadStatus == null) {
-            future.setException(
-                ApiExceptionFactory.createException(
-                    "Upload chunk response did not contain valid "
-                        + UPLOAD_STATUS_HEADER
-                        + " header",
-                    /* cause= */ null,
-                    HttpJsonStatusCode.of(StatusCode.Code.INTERNAL),
-                    /* retryable= */ false));
-            return;
-          }
-          boolean isComplete = STATUS_FINAL.equalsIgnoreCase(uploadStatus);
           ChunkUploadResponse.Builder<ResponseT> chunkResponseBuilder =
-              ChunkUploadResponse.<ResponseT>newBuilder().setComplete(isComplete);
-          if (isComplete) {
+              ChunkUploadResponse.<ResponseT>newBuilder().setUploadStatus(uploadStatus);
+          if (uploadStatus == ResumableUploadStatus.FINAL) {
             InputStream stream =
                 new ByteArrayInputStream(responseBody.getBytes(StandardCharsets.UTF_8));
             chunkResponseBuilder.setResponse(responseParser.parse(stream));

sdk-platform-java/gax-java/gax-httpjson/src/main/java/com/google/api/gax/httpjson/ResumableUploadQueryStatusCallable.java

@@ -33,6 +33,7 @@
 import com.google.api.core.ApiFuture;
 import com.google.api.gax.resumable.QueryStatusRequest;
 import com.google.api.gax.resumable.QueryStatusResponse;
+import com.google.api.gax.resumable.ResumableUploadStatus;
 import com.google.api.gax.rpc.ApiCallContext;
 import com.google.api.gax.rpc.ApiExceptionFactory;
 import com.google.api.gax.rpc.ClientContext;
@@ -63,7 +64,6 @@ class ResumableUploadQueryStatusCallable<ResponseT>
   private static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
   private static final String UPLOAD_STATUS_HEADER = "X-Goog-Upload-Status";
   private static final String UPLOAD_SIZE_RECEIVED_HEADER = "X-Goog-Upload-Size-Received";
-  private static final String STATUS_FINAL = "final";
   private static final String COMMAND_QUERY = "query";
 
   private static final Map<String, List<String>> QUERY_STATUS_HEADERS =
@@ -182,7 +182,7 @@ private static class QueryStatusResponseListener<ResponseT>
 
     private final ResumableUploadHttpJsonFuture<QueryStatusResponse<ResponseT>> future;
     private final HttpResponseParser<ResponseT> responseParser;
-    @Nullable private String uploadStatus = null;
+    private ResumableUploadStatus uploadStatus = ResumableUploadStatus.UNKNOWN;
     @Nullable private Long committedOffset = null;
     @Nullable private Throwable headerParsingException;
     private String responseBody = "";
@@ -197,7 +197,9 @@ private QueryStatusResponseListener(
     @Override
     public void onHeaders(HttpJsonMetadata responseHeaders) {
       Map<String, Object> headers = responseHeaders.getHeaders();
-      this.uploadStatus = HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER);
+      this.uploadStatus =
+          ResumableUploadStatus.fromHeader(
+              HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER));
       try {
         this.committedOffset = parseSizeReceived(responseHeaders);
       } catch (Throwable t) {
@@ -220,19 +222,19 @@ public void onClose(int statusCode, HttpJsonMetadata trailers) {
             future.setException(headerParsingException);
             return;
           }
-          boolean isComplete = STATUS_FINAL.equalsIgnoreCase(uploadStatus);
-          if (isComplete) {
-            QueryStatusResponse.Builder<ResponseT> queryResponseBuilder =
-                QueryStatusResponse.<ResponseT>newBuilder().setComplete(true);
+          if (uploadStatus == ResumableUploadStatus.FINAL) {
             InputStream stream =
                 new ByteArrayInputStream(responseBody.getBytes(StandardCharsets.UTF_8));
-            queryResponseBuilder.setResponse(responseParser.parse(stream));
-            future.set(queryResponseBuilder.build());
+            future.set(
+                QueryStatusResponse.<ResponseT>newBuilder()
+                    .setUploadStatus(uploadStatus)
+                    .setResponse(responseParser.parse(stream))
+                    .build());
           } else if (committedOffset != null) {
             future.set(
                 QueryStatusResponse.<ResponseT>newBuilder()
-                    .setComplete(false)
                     .setCommittedOffset(committedOffset)
+                    .setUploadStatus(uploadStatus)
                     .build());
           } else {
             future.setException(

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

@@ -45,9 +45,9 @@
 import com.google.api.gax.resumable.QueryStatusRequest;
 import com.google.api.gax.resumable.QueryStatusResponse;
 import com.google.api.gax.resumable.ResumableUploadSession;
+import com.google.api.gax.resumable.ResumableUploadStatus;
 import com.google.api.gax.rpc.AbortedException;
 import com.google.api.gax.rpc.ApiCallContext;
-import com.google.api.gax.rpc.ApiException;
 import com.google.api.gax.rpc.ClientContext;
 import com.google.api.gax.rpc.InternalException;
 import com.google.api.gax.rpc.NotFoundException;
@@ -260,8 +260,8 @@ void uploadChunk_intermediateChunk_sendsUploadCommandAndReturnsActiveStatus() {
 
     ChunkUploadResponse<String> response = client.uploadChunkCallable().call(request);
 
-    assertThat(response.isComplete()).isFalse();
     assertThat(response.getResponse()).isNull();
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.ACTIVE);
 
     assertThat(transport.capturedUrl).isEqualTo(TEST_UPLOAD_URL);
     assertThat(transport.capturedHeaders.get("x-goog-upload-command")).containsExactly("upload");
@@ -289,9 +289,9 @@ void uploadChunk_finalChunk_sendsUploadFinalizeAndReturnsResponseBody() {
 
     ChunkUploadResponse<String> response = client.uploadChunkCallable().call(request);
 
-    assertThat(response.isComplete()).isTrue();
     assertThat(response.getResponse())
         .isEqualTo("{\"name\":\"uploaded-file.txt\",\"size\":524288}");
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.FINAL);
 
     assertThat(transport.capturedHeaders.get("x-goog-upload-command"))
         .containsExactly("upload, finalize");
@@ -318,9 +318,9 @@ void uploadChunk_emptyPayloadFinal_sendsFinalizeCommandAndReturnsResponseBody()
 
     ChunkUploadResponse<String> response = client.uploadChunkCallable().call(request);
 
-    assertThat(response.isComplete()).isTrue();
     assertThat(response.getResponse())
         .isEqualTo("{\"name\":\"uploaded-file.txt\",\"size\":1048576}");
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.FINAL);
 
     assertThat(transport.capturedHeaders.get("x-goog-upload-command")).containsExactly("finalize");
     assertThat(transport.capturedHeaders).doesNotContainKey("x-goog-upload-offset");
@@ -379,7 +379,7 @@ void uploadChunk_serverReturnsConflictOrError_throwsException() {
   }
 
   @Test
-  void uploadChunk_missingUploadStatusHeader_throwsInternalException() {
+  void uploadChunk_missingUploadStatusHeader_returnsUnknownUploadStatusOnHttp200() {
     MockLowLevelHttpResponse httpResponse = new MockLowLevelHttpResponse();
     httpResponse.setStatusCode(200);
 
@@ -391,39 +391,10 @@ void uploadChunk_missingUploadStatusHeader_throwsInternalException() {
             .setOffset(0L)
             .build();
 
-    ExecutionException exception =
-        assertThrows(
-            ExecutionException.class, () -> client.uploadChunkCallable().futureCall(request).get());
-
-    assertThat(exception.getCause()).isInstanceOf(InternalException.class);
-    assertThat(exception.getCause())
-        .hasMessageThat()
-        .contains("Upload chunk response did not contain valid X-Goog-Upload-Status header");
-  }
-
-  @Test
-  void uploadChunk_serverReturnsFinalStatusOnNon200_marksExceptionNonRetryable() {
-    MockLowLevelHttpResponse httpResponse = new MockLowLevelHttpResponse();
-    httpResponse.setStatusCode(503);
-    httpResponse.addHeader("X-Goog-Upload-Status", "final");
-    httpResponse.setContent("{\"error\":{\"message\":\"Upload rejected by backend\"}}");
-
-    HttpJsonResumableUploadClient<TestRequest, String> client = createClient(httpResponse);
-    ChunkUploadRequest request =
-        ChunkUploadRequest.newBuilder()
-            .setUploadUrl(TEST_UPLOAD_URL)
-            .setPayload("data".getBytes(StandardCharsets.UTF_8))
-            .setOffset(0L)
-            .build();
-
-    ExecutionException exception =
-        assertThrows(
-            ExecutionException.class, () -> client.uploadChunkCallable().futureCall(request).get());
+    ChunkUploadResponse<String> response = client.uploadChunkCallable().call(request);
 
-    assertThat(exception.getCause()).isInstanceOf(ApiException.class);
-    ApiException apiException = (ApiException) exception.getCause();
-    assertThat(apiException.isRetryable()).isFalse();
-    assertThat(apiException.getStatusCode().getCode()).isEqualTo(StatusCode.Code.UNAVAILABLE);
+    assertThat(response.getResponse()).isNull();
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.UNKNOWN);
   }
 
   @Test
@@ -439,9 +410,9 @@ void queryStatus_activeUpload_returnsCommittedOffset() {
 
     QueryStatusResponse<String> response = client.queryStatusCallable().call(request);
 
-    assertThat(response.isComplete()).isFalse();
     assertThat(response.getCommittedOffset()).isEqualTo(524288L);
     assertThat(response.getResponse()).isNull();
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.ACTIVE);
 
     assertThat(transport.capturedHeaders.get("x-goog-upload-command")).containsExactly("query");
   }
@@ -458,10 +429,10 @@ void queryStatus_finalUpload_returnsCompleteAndResponseBody() {
 
     QueryStatusResponse<String> response = client.queryStatusCallable().call(request);
 
-    assertThat(response.isComplete()).isTrue();
     assertThat(response.getCommittedOffset()).isNull();
     assertThat(response.getResponse())
         .isEqualTo("{\"name\":\"uploaded-file.txt\",\"size\":1048576}");
+    assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.FINAL);
   }
 
   @Test

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/ChunkUploadResponse.java

@@ -46,35 +46,36 @@
 @AutoValue
 public abstract class ChunkUploadResponse<ResponseT> {
 
-  /** Whether the overall resumable upload stream has finalized and completed on the server. */
-  public abstract boolean isComplete();
-
   /**
    * The response object returned by the server upon final completion (e.g. metadata of the uploaded
    * resource), or {@code null} if the upload is still in progress.
    */
   public abstract @Nullable ResponseT getResponse();
 
+  /** Returns the status of the upload session returned by the server. */
+  public abstract ResumableUploadStatus getUploadStatus();
+
   public abstract Builder<ResponseT> toBuilder();
 
   public static <ResponseT> Builder<ResponseT> newBuilder() {
-    return new AutoValue_ChunkUploadResponse.Builder<ResponseT>().setComplete(false);
+    return new AutoValue_ChunkUploadResponse.Builder<ResponseT>()
+        .setUploadStatus(ResumableUploadStatus.ACTIVE);
   }
 
   public static <ResponseT> ChunkUploadResponse<ResponseT> create(
-      boolean isComplete, @Nullable ResponseT response) {
+      ResumableUploadStatus uploadStatus, @Nullable ResponseT response) {
     return new AutoValue_ChunkUploadResponse.Builder<ResponseT>()
-        .setComplete(isComplete)
+        .setUploadStatus(uploadStatus)
         .setResponse(response)
         .build();
   }
 
   @AutoValue.Builder
   public abstract static class Builder<ResponseT> {
-    public abstract Builder<ResponseT> setComplete(boolean isComplete);
-
     public abstract Builder<ResponseT> setResponse(@Nullable ResponseT response);
 
+    public abstract Builder<ResponseT> setUploadStatus(ResumableUploadStatus uploadStatus);
+
     public abstract ChunkUploadResponse<ResponseT> build();
   }
 }

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/QueryStatusResponse.java

@@ -51,34 +51,35 @@ public abstract class QueryStatusResponse<ResponseT> {
    * null} if the server did not return a committed offset (e.g. if the upload is already
    * finalized).
    *
-   * <p>When {@link #isComplete()} is {@code false}, this value is guaranteed to be non-null and
-   * represents the starting offset for resuming the upload.
+   * <p>When {@link #getUploadStatus()} is {@link ResumableUploadStatus#ACTIVE}, this value is
+   * guaranteed to be non-null and represents the starting offset for resuming the upload.
    */
   public abstract @Nullable Long getCommittedOffset();
 
-  /** Whether the resumable upload session has finalized and completed on the server. */
-  public abstract boolean isComplete();
-
   /**
    * The response object returned by the server upon final completion (e.g. metadata of the uploaded
    * resource), or {@code null} if the upload is still in progress.
    */
   public abstract @Nullable ResponseT getResponse();
 
+  /** Returns the status of the upload session returned by the server. */
+  public abstract ResumableUploadStatus getUploadStatus();
+
   public abstract Builder<ResponseT> toBuilder();
 
   public static <ResponseT> Builder<ResponseT> newBuilder() {
-    return new AutoValue_QueryStatusResponse.Builder<ResponseT>().setComplete(false);
+    return new AutoValue_QueryStatusResponse.Builder<ResponseT>()
+        .setUploadStatus(ResumableUploadStatus.ACTIVE);
   }
 
   @AutoValue.Builder
   public abstract static class Builder<ResponseT> {
     public abstract Builder<ResponseT> setCommittedOffset(@Nullable Long committedOffset);
 
-    public abstract Builder<ResponseT> setComplete(boolean isComplete);
-
     public abstract Builder<ResponseT> setResponse(@Nullable ResponseT response);
 
+    public abstract Builder<ResponseT> setUploadStatus(ResumableUploadStatus uploadStatus);
+
     public abstract QueryStatusResponse<ResponseT> build();
   }
 }

sdk-platform-java/gax-java/gax/src/main/java/com/google/api/gax/resumable/ResumableUploadStatus.java

@@ -0,0 +1,61 @@
+/*
+ * 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.resumable;
+
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
+import org.jspecify.annotations.NullMarked;
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Represents the session status returned by the server in the {@code X-Goog-Upload-Status} header.
+ */
+@NullMarked
+@BetaApi
+@InternalApi
+public enum ResumableUploadStatus {
+  ACTIVE,
+  FINAL,
+  UNKNOWN;
+
+  /**
+   * Parses the {@code X-Goog-Upload-Status} header value into a {@link ResumableUploadStatus},
+   * returning {@link #UNKNOWN} if the header is absent or unrecognized.
+   */
+  public static ResumableUploadStatus fromHeader(@Nullable String headerValue) {
+    if ("active".equalsIgnoreCase(headerValue)) {
+      return ACTIVE;
+    }
+    if ("final".equalsIgnoreCase(headerValue)) {
+      return FINAL;
+    }
+    return UNKNOWN;
+  }
+}