Skip to content

Commit c158e70

Browse files
committed
feat(gax): wire-level changes for resuming uploads
1 parent 1bc507f commit c158e70

7 files changed

Lines changed: 139 additions & 52 deletions

File tree

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

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,9 @@
2929
*/
3030
package com.google.api.gax.httpjson;
3131

32+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_COMMAND_HEADER;
33+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_OFFSET_HEADER;
34+
3235
import com.google.api.client.http.HttpMethods;
3336
import com.google.api.core.ApiFuture;
3437
import com.google.api.gax.resumable.ChunkUploadRequest;
@@ -55,10 +58,6 @@
5558
class ResumableUploadChunkCallable<ResponseT>
5659
extends UnaryCallable<ChunkUploadRequest, ChunkUploadResponse<ResponseT>> {
5760

58-
private static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
59-
private static final String UPLOAD_OFFSET_HEADER = "X-Goog-Upload-Offset";
60-
private static final String UPLOAD_STATUS_HEADER = "X-Goog-Upload-Status";
61-
6261
private static final String COMMAND_UPLOAD = "upload";
6362
private static final String COMMAND_FINALIZE = "finalize";
6463
private static final String COMMAND_UPLOAD_FINALIZE = "upload, finalize";
@@ -175,10 +174,7 @@ private ChunkUploadResponseListener(
175174

176175
@Override
177176
public void onHeaders(HttpJsonMetadata responseHeaders) {
178-
Map<String, Object> headers = responseHeaders.getHeaders();
179-
this.uploadStatus =
180-
ResumableUploadStatus.fromHeader(
181-
HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER));
177+
this.uploadStatus = ResumableUploadHeaders.parseUploadStatus(responseHeaders);
182178
}
183179

184180
@Override
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
/*
2+
* Copyright 2026 Google LLC
3+
*
4+
* Redistribution and use in source and binary forms, with or without
5+
* modification, are permitted provided that the following conditions are
6+
* met:
7+
*
8+
* * Redistributions of source code must retain the above copyright
9+
* notice, this list of conditions and the following disclaimer.
10+
* * Redistributions in binary form must reproduce the above
11+
* copyright notice, this list of conditions and the following disclaimer
12+
* in the documentation and/or other materials provided with the
13+
* distribution.
14+
* * Neither the name of Google LLC nor the names of its
15+
* contributors may be used to endorse or promote products derived from
16+
* this software without specific prior written permission.
17+
*
18+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
19+
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
20+
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
21+
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
22+
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23+
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
24+
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25+
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26+
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27+
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28+
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29+
*/
30+
package com.google.api.gax.httpjson;
31+
32+
import com.google.api.gax.resumable.ResumableUploadSession;
33+
import com.google.api.gax.resumable.ResumableUploadStatus;
34+
import com.google.api.gax.rpc.ApiExceptionFactory;
35+
import com.google.api.gax.rpc.StatusCode;
36+
import com.google.common.base.Strings;
37+
import org.jspecify.annotations.NullMarked;
38+
39+
/** Shared header constants and parsing utilities for HTTP/JSON resumable upload wire calls. */
40+
@NullMarked
41+
final class ResumableUploadHeaders {
42+
43+
static final String UPLOAD_PROTOCOL_HEADER = "X-Goog-Upload-Protocol";
44+
static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
45+
static final String UPLOAD_URL_HEADER = "X-Goog-Upload-URL";
46+
static final String UPLOAD_GRANULARITY_HEADER = "X-Goog-Upload-Chunk-Granularity";
47+
static final String UPLOAD_OFFSET_HEADER = "X-Goog-Upload-Offset";
48+
static final String UPLOAD_STATUS_HEADER = "X-Goog-Upload-Status";
49+
static final String UPLOAD_SIZE_RECEIVED_HEADER = "X-Goog-Upload-Size-Received";
50+
51+
private ResumableUploadHeaders() {}
52+
53+
static ResumableUploadStatus parseUploadStatus(HttpJsonMetadata responseHeaders) {
54+
return ResumableUploadStatus.fromHeader(
55+
HttpHeadersUtils.getSingleHeader(responseHeaders.getHeaders(), UPLOAD_STATUS_HEADER));
56+
}
57+
58+
static int parseChunkGranularity(HttpJsonMetadata responseHeaders) {
59+
String granularityStr =
60+
HttpHeadersUtils.getSingleHeader(responseHeaders.getHeaders(), UPLOAD_GRANULARITY_HEADER);
61+
if (Strings.isNullOrEmpty(granularityStr)) {
62+
return ResumableUploadSession.DEFAULT_CHUNK_GRANULARITY;
63+
}
64+
try {
65+
int parsed = Integer.parseInt(granularityStr);
66+
if (parsed <= 0) {
67+
throw ApiExceptionFactory.createException(
68+
"Response contained non-positive "
69+
+ UPLOAD_GRANULARITY_HEADER
70+
+ " header: "
71+
+ granularityStr,
72+
/* cause= */ null,
73+
HttpJsonStatusCode.of(StatusCode.Code.INTERNAL),
74+
/* retryable= */ false);
75+
}
76+
return parsed;
77+
} catch (NumberFormatException e) {
78+
throw ApiExceptionFactory.createException(
79+
"Response contained invalid " + UPLOAD_GRANULARITY_HEADER + " header: " + granularityStr,
80+
e,
81+
HttpJsonStatusCode.of(StatusCode.Code.INTERNAL),
82+
/* retryable= */ false);
83+
}
84+
}
85+
}

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

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -29,10 +29,14 @@
2929
*/
3030
package com.google.api.gax.httpjson;
3131

32+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_COMMAND_HEADER;
33+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_SIZE_RECEIVED_HEADER;
34+
3235
import com.google.api.client.http.HttpMethods;
3336
import com.google.api.core.ApiFuture;
3437
import com.google.api.gax.resumable.QueryStatusRequest;
3538
import com.google.api.gax.resumable.QueryStatusResponse;
39+
import com.google.api.gax.resumable.ResumableUploadSession;
3640
import com.google.api.gax.resumable.ResumableUploadStatus;
3741
import com.google.api.gax.rpc.ApiCallContext;
3842
import com.google.api.gax.rpc.ApiExceptionFactory;
@@ -61,9 +65,6 @@
6165
class ResumableUploadQueryStatusCallable<ResponseT>
6266
extends UnaryCallable<QueryStatusRequest, QueryStatusResponse<ResponseT>> {
6367

64-
private static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
65-
private static final String UPLOAD_STATUS_HEADER = "X-Goog-Upload-Status";
66-
private static final String UPLOAD_SIZE_RECEIVED_HEADER = "X-Goog-Upload-Size-Received";
6768
private static final String COMMAND_QUERY = "query";
6869

6970
private static final Map<String, List<String>> QUERY_STATUS_HEADERS =
@@ -183,6 +184,7 @@ private static class QueryStatusResponseListener<ResponseT>
183184
private final ResumableUploadHttpJsonFuture<QueryStatusResponse<ResponseT>> future;
184185
private final HttpResponseParser<ResponseT> responseParser;
185186
private ResumableUploadStatus uploadStatus = ResumableUploadStatus.UNKNOWN;
187+
private int chunkGranularity = ResumableUploadSession.DEFAULT_CHUNK_GRANULARITY;
186188
@Nullable private Long committedOffset = null;
187189
@Nullable private Throwable headerParsingException;
188190
private String responseBody = "";
@@ -196,12 +198,10 @@ private QueryStatusResponseListener(
196198

197199
@Override
198200
public void onHeaders(HttpJsonMetadata responseHeaders) {
199-
Map<String, Object> headers = responseHeaders.getHeaders();
200-
this.uploadStatus =
201-
ResumableUploadStatus.fromHeader(
202-
HttpHeadersUtils.getSingleHeader(headers, UPLOAD_STATUS_HEADER));
201+
this.uploadStatus = ResumableUploadHeaders.parseUploadStatus(responseHeaders);
203202
try {
204203
this.committedOffset = parseSizeReceived(responseHeaders);
204+
this.chunkGranularity = ResumableUploadHeaders.parseChunkGranularity(responseHeaders);
205205
} catch (Throwable t) {
206206
this.headerParsingException = t;
207207
}
@@ -228,13 +228,16 @@ public void onClose(int statusCode, HttpJsonMetadata trailers) {
228228
future.set(
229229
QueryStatusResponse.<ResponseT>newBuilder()
230230
.setUploadStatus(uploadStatus)
231+
.setCommittedOffset(committedOffset)
231232
.setResponse(responseParser.parse(stream))
233+
.setChunkGranularity(chunkGranularity)
232234
.build());
233235
} else if (committedOffset != null) {
234236
future.set(
235237
QueryStatusResponse.<ResponseT>newBuilder()
236238
.setCommittedOffset(committedOffset)
237239
.setUploadStatus(uploadStatus)
240+
.setChunkGranularity(chunkGranularity)
238241
.build());
239242
} else {
240243
future.setException(

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

Lines changed: 10 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,10 @@
2929
*/
3030
package com.google.api.gax.httpjson;
3131

32+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_COMMAND_HEADER;
33+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_PROTOCOL_HEADER;
34+
import static com.google.api.gax.httpjson.ResumableUploadHeaders.UPLOAD_URL_HEADER;
35+
3236
import com.google.api.core.ApiFuture;
3337
import com.google.api.gax.resumable.ResumableUploadSession;
3438
import com.google.api.gax.rpc.ApiCallContext;
@@ -52,11 +56,6 @@
5256
class ResumableUploadStartCallable<RequestT>
5357
extends UnaryCallable<RequestT, ResumableUploadSession> {
5458

55-
private static final String UPLOAD_PROTOCOL_HEADER = "X-Goog-Upload-Protocol";
56-
private static final String UPLOAD_COMMAND_HEADER = "X-Goog-Upload-Command";
57-
private static final String UPLOAD_URL_HEADER = "X-Goog-Upload-URL";
58-
private static final String UPLOAD_GRANULARITY_HEADER = "X-Goog-Upload-Chunk-Granularity";
59-
6059
private static final Map<String, List<String>> START_UPLOAD_HEADERS =
6160
ImmutableMap.of(
6261
UPLOAD_PROTOCOL_HEADER, ImmutableList.of("resumable"),
@@ -108,7 +107,7 @@ static <RequestT> UnaryCallable<RequestT, ResumableUploadSession> create(
108107
/** A listener that parses HTTP response headers to produce a {@link ResumableUploadSession}. */
109108
private static class StartUploadResponseListener extends HttpJsonClientCall.Listener<String> {
110109
private final ResumableUploadHttpJsonFuture<ResumableUploadSession> future;
111-
private int chunkGranularity = 1;
110+
private int chunkGranularity = ResumableUploadSession.DEFAULT_CHUNK_GRANULARITY;
112111
@Nullable private String uploadUrl;
113112
@Nullable private Throwable headerParsingException;
114113

@@ -119,39 +118,16 @@ private StartUploadResponseListener(
119118

120119
@Override
121120
public void onHeaders(HttpJsonMetadata responseHeaders) {
122-
Map<String, Object> headers = responseHeaders.getHeaders();
123-
124-
String url = HttpHeadersUtils.getSingleHeader(headers, UPLOAD_URL_HEADER);
121+
String url =
122+
HttpHeadersUtils.getSingleHeader(responseHeaders.getHeaders(), UPLOAD_URL_HEADER);
125123
if (!Strings.isNullOrEmpty(url)) {
126124
this.uploadUrl = url;
127125
}
128126

129-
String granularityStr = HttpHeadersUtils.getSingleHeader(headers, UPLOAD_GRANULARITY_HEADER);
130-
if (Strings.isNullOrEmpty(granularityStr)) {
131-
return;
132-
}
133-
134127
try {
135-
int parsed = Integer.parseInt(granularityStr);
136-
if (parsed <= 0) {
137-
this.headerParsingException =
138-
ApiExceptionFactory.createException(
139-
"Start upload response contained non-positive chunk granularity header: "
140-
+ granularityStr,
141-
/* cause= */ null,
142-
HttpJsonStatusCode.of(StatusCode.Code.INTERNAL),
143-
/* retryable= */ false);
144-
} else {
145-
this.chunkGranularity = parsed;
146-
}
147-
} catch (NumberFormatException e) {
148-
this.headerParsingException =
149-
ApiExceptionFactory.createException(
150-
"Start upload response contained invalid chunk granularity header: "
151-
+ granularityStr,
152-
e,
153-
HttpJsonStatusCode.of(StatusCode.Code.INTERNAL),
154-
/* retryable= */ false);
128+
this.chunkGranularity = ResumableUploadHeaders.parseChunkGranularity(responseHeaders);
129+
} catch (Throwable t) {
130+
this.headerParsingException = t;
155131
}
156132
}
157133

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -161,7 +161,7 @@ void startUpload_nonPositiveChunkGranularityHeader_throwsException() {
161161
assertThat(exception.getCause()).isInstanceOf(InternalException.class);
162162
assertThat(exception.getCause())
163163
.hasMessageThat()
164-
.contains("Start upload response contained non-positive chunk granularity header: -256");
164+
.contains("Response contained non-positive X-Goog-Upload-Chunk-Granularity header: -256");
165165
}
166166

167167
@Test
@@ -514,6 +514,24 @@ void queryStatus_activeUpload_returnsCommittedOffset() {
514514
assertThat(transport.capturedHeaders.get("x-goog-upload-command")).containsExactly("query");
515515
}
516516

517+
@Test
518+
void queryStatus_withChunkGranularity_returnsGranularity() {
519+
MockLowLevelHttpResponse httpResponse = new MockLowLevelHttpResponse();
520+
httpResponse.setStatusCode(200);
521+
httpResponse.addHeader("X-Goog-Upload-Status", "active");
522+
httpResponse.addHeader("X-Goog-Upload-Size-Received", "524288");
523+
httpResponse.addHeader("X-Goog-Upload-Chunk-Granularity", "262144");
524+
525+
HttpJsonResumableUploadClient<TestRequest, String> client = createClient(httpResponse);
526+
QueryStatusRequest request = QueryStatusRequest.create(TEST_UPLOAD_URL);
527+
528+
QueryStatusResponse<String> response = client.queryStatusCallable().call(request);
529+
530+
assertThat(response.getCommittedOffset()).isEqualTo(524288L);
531+
assertThat(response.getChunkGranularity()).isEqualTo(262144);
532+
assertThat(response.getUploadStatus()).isEqualTo(ResumableUploadStatus.ACTIVE);
533+
}
534+
517535
@Test
518536
void queryStatus_finalUpload_returnsCompleteAndResponseBody() {
519537
MockLowLevelHttpResponse httpResponse = new MockLowLevelHttpResponse();

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

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,11 +65,18 @@ public abstract class QueryStatusResponse<ResponseT> {
6565
/** Returns the status of the upload session returned by the server. */
6666
public abstract ResumableUploadStatus getUploadStatus();
6767

68+
/**
69+
* Returns the byte alignment granularity required by the server for chunk uploads, or {@code 1}
70+
* if no alignment restriction was returned.
71+
*/
72+
public abstract int getChunkGranularity();
73+
6874
public abstract Builder<ResponseT> toBuilder();
6975

7076
public static <ResponseT> Builder<ResponseT> newBuilder() {
7177
return new AutoValue_QueryStatusResponse.Builder<ResponseT>()
72-
.setUploadStatus(ResumableUploadStatus.ACTIVE);
78+
.setUploadStatus(ResumableUploadStatus.ACTIVE)
79+
.setChunkGranularity(ResumableUploadSession.DEFAULT_CHUNK_GRANULARITY);
7380
}
7481

7582
@AutoValue.Builder
@@ -80,6 +87,8 @@ public abstract static class Builder<ResponseT> {
8087

8188
public abstract Builder<ResponseT> setUploadStatus(ResumableUploadStatus uploadStatus);
8289

90+
public abstract Builder<ResponseT> setChunkGranularity(int chunkGranularity);
91+
8392
public abstract QueryStatusResponse<ResponseT> build();
8493
}
8594
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@
4141
@AutoValue
4242
public abstract class ResumableUploadSession {
4343

44-
private static final int DEFAULT_CHUNK_GRANULARITY = 1;
44+
public static final int DEFAULT_CHUNK_GRANULARITY = 1;
4545

4646
/** Returns the server-provided URL to which data uploads are directed. */
4747
public abstract String getUploadUrl();

0 commit comments

Comments
 (0)