feat(gax): add ResumableUploadClient and supporting classes #14072
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,104 @@ | ||
| /* | ||
| * 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.resumableupload; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.auto.value.AutoValue; | ||
| import com.google.common.base.Preconditions; | ||
| import com.google.protobuf.ByteString; | ||
| import org.jspecify.annotations.NullMarked; | ||
|
|
||
| /** Request parameters for uploading an individual payload chunk. */ | ||
| @InternalApi | ||
| @NullMarked | ||
| @AutoValue | ||
| public abstract class ChunkUploadRequest { | ||
|
|
||
| /** Returns the upload session URI. */ | ||
| public abstract String getUploadUrl(); | ||
|
|
||
| /** Returns the byte payload to transmit in this chunk. */ | ||
| public abstract ByteString getPayload(); | ||
|
|
||
| /** Returns the byte offset within the total stream where this chunk begins. */ | ||
| public abstract long getOffset(); | ||
|
|
||
| /** Returns the total length of the upload payload in bytes, or -1 if unknown. */ | ||
| public abstract long getTotalLength(); | ||
|
|
||
| /** Returns whether this chunk is the final chunk of the upload. */ | ||
| public abstract boolean isFinal(); | ||
|
|
||
| public abstract Builder toBuilder(); | ||
|
|
||
| public static Builder builder() { | ||
| return new AutoValue_ChunkUploadRequest.Builder() | ||
| .setOffset(0L) | ||
| .setTotalLength(-1L) | ||
| .setFinal(false); | ||
| } | ||
|
|
||
| public static ChunkUploadRequest create( | ||
| String uploadUrl, ByteString payload, long offset, long totalLength, boolean isFinal) { | ||
| return builder() | ||
| .setUploadUrl(uploadUrl) | ||
| .setPayload(payload) | ||
| .setOffset(offset) | ||
| .setTotalLength(totalLength) | ||
| .setFinal(isFinal) | ||
| .build(); | ||
| } | ||
|
|
||
| @AutoValue.Builder | ||
| public abstract static class Builder { | ||
| public abstract Builder setUploadUrl(String uploadUrl); | ||
|
|
||
| public abstract Builder setPayload(ByteString payload); | ||
|
|
||
| public abstract Builder setOffset(long offset); | ||
|
|
||
| public abstract Builder setTotalLength(long totalLength); | ||
|
|
||
| public abstract Builder setFinal(boolean isFinal); | ||
|
|
||
| abstract ChunkUploadRequest autoBuild(); | ||
|
|
||
| public ChunkUploadRequest build() { | ||
| ChunkUploadRequest request = autoBuild(); | ||
| Preconditions.checkArgument(request.getOffset() >= 0, "offset must be non-negative"); | ||
| Preconditions.checkArgument(request.getTotalLength() >= -1, "totalLength must be >= -1"); | ||
| if (request.getTotalLength() >= 0) { | ||
| Preconditions.checkArgument( | ||
| request.getOffset() <= request.getTotalLength(), "offset must be <= totalLength"); | ||
| } | ||
| return request; | ||
| } | ||
| } | ||
|
Comment on lines
+68
to
+103
Contributor
There was a problem hiding this comment. To prevent invalid states, we should enforce that the chunk offset and payload size do not exceed the total length when the total length is known. Additionally, if this is the final chunk, the end offset must exactly equal the total length. Please ensure these validation steps are not redundant with checks already performed by upstream callers. public static ChunkUploadRequest create(
String uploadUrl, ByteString payload, long offset, long totalLength, boolean isFinal) {
Preconditions.checkArgument(offset >= 0, "offset must be non-negative");
Preconditions.checkArgument(totalLength >= -1, "totalLength must be >= -1");
if (totalLength != -1) {
Preconditions.checkArgument(
offset + payload.size() <= totalLength,
"offset + payload size (%s) cannot exceed totalLength (%s)",
offset + payload.size(),
totalLength);
if (isFinal) {
Preconditions.checkArgument(
offset + payload.size() == totalLength,
"final chunk end offset (%s) must equal totalLength (%s)",
offset + payload.size(),
totalLength);
}
}
return new AutoValue_ChunkUploadRequest(uploadUrl, payload, offset, totalLength, isFinal);
}References
Contributor
Author
There was a problem hiding this comment. I think this is more appropriately handled and tested on the caller level (the state machine) |
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| /* | ||
| * 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.resumableupload; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.auto.value.AutoValue; | ||
| import com.google.common.base.Preconditions; | ||
| import org.jspecify.annotations.NullMarked; | ||
| import org.jspecify.annotations.Nullable; | ||
|
|
||
| /** Response received after uploading an individual payload chunk. */ | ||
| @InternalApi | ||
| @NullMarked | ||
| @AutoValue | ||
| public abstract class ChunkUploadResponse { | ||
|
|
||
| /** Returns the byte offset confirmed by the server as successfully received. */ | ||
| public abstract long getCommittedOffset(); | ||
|
|
||
| /** Returns whether the entire upload has completed. */ | ||
| public abstract boolean isComplete(); | ||
|
|
||
| /** Returns the raw server response body (present on completion), or {@code null} if ongoing. */ | ||
| public abstract @Nullable String getResponseBody(); | ||
|
|
||
| public static ChunkUploadResponse create( | ||
| long committedOffset, boolean isComplete, @Nullable String responseBody) { | ||
| Preconditions.checkArgument(committedOffset >= 0, "committedOffset must be non-negative"); | ||
| return new AutoValue_ChunkUploadResponse(committedOffset, isComplete, responseBody); | ||
| } | ||
|
whowes marked this conversation as resolved.
|
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| /* | ||
| * 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.resumableupload; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.auto.value.AutoValue; | ||
| import com.google.common.base.Preconditions; | ||
| import org.jspecify.annotations.NullMarked; | ||
|
|
||
| /** Request parameters for querying the current upload status of a session. */ | ||
| @InternalApi | ||
| @NullMarked | ||
| @AutoValue | ||
| public abstract class QueryStatusRequest { | ||
|
|
||
| /** Returns the upload session URI. */ | ||
| public abstract String getUploadUrl(); | ||
|
|
||
| /** Returns the total length of the upload payload in bytes, or -1 if unknown. */ | ||
| public abstract long getTotalLength(); | ||
|
|
||
| public static QueryStatusRequest create(String uploadUrl, long totalLength) { | ||
| Preconditions.checkArgument(totalLength >= -1, "totalLength must be >= -1"); | ||
| return new AutoValue_QueryStatusRequest(uploadUrl, totalLength); | ||
| } | ||
|
whowes marked this conversation as resolved.
|
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,62 @@ | ||
| /* | ||
| * 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.resumableupload; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.auto.value.AutoValue; | ||
| import com.google.common.base.Preconditions; | ||
| import org.jspecify.annotations.NullMarked; | ||
| import org.jspecify.annotations.Nullable; | ||
|
|
||
| /** Response received from querying the server for current upload progress. */ | ||
| @InternalApi | ||
| @NullMarked | ||
| @AutoValue | ||
| public abstract class QueryStatusResponse { | ||
|
|
||
| /** Returns the byte offset confirmed by the server as successfully received. */ | ||
| public abstract long getCommittedOffset(); | ||
|
|
||
| /** Returns whether the entire upload has completed. */ | ||
| public abstract boolean isComplete(); | ||
|
|
||
| /** Returns the raw server response body (present on completion), or {@code null} if ongoing. */ | ||
| public abstract @Nullable String getResponseBody(); | ||
|
|
||
| public static QueryStatusResponse create(long committedOffset) { | ||
| return create(committedOffset, false, null); | ||
| } | ||
|
|
||
| public static QueryStatusResponse create( | ||
| long committedOffset, boolean isComplete, @Nullable String responseBody) { | ||
| Preconditions.checkArgument(committedOffset >= 0, "committedOffset must be non-negative"); | ||
| return new AutoValue_QueryStatusResponse(committedOffset, isComplete, responseBody); | ||
| } | ||
|
whowes marked this conversation as resolved.
|
||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| /* | ||
| * 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.resumableupload; | ||
|
|
||
| import com.google.api.core.InternalApi; | ||
| import com.google.api.gax.rpc.UnaryCallable; | ||
| import org.jspecify.annotations.NullMarked; | ||
|
|
||
| /** An interface for executing low-level resumable upload operations. */ | ||
| @InternalApi | ||
| @NullMarked | ||
| public interface ResumableUploadClient { | ||
|
|
||
| /** Returns a {@link UnaryCallable} to initiate a resumable upload session. */ | ||
| UnaryCallable<StartUploadRequest, ResumableUploadSession> startUploadCallable(); | ||
|
|
||
| /** Returns a {@link UnaryCallable} to transmit an individual chunk. */ | ||
| UnaryCallable<ChunkUploadRequest, ChunkUploadResponse> uploadChunkCallable(); | ||
|
|
||
| /** Returns a {@link UnaryCallable} to query the server for current upload status. */ | ||
| UnaryCallable<QueryStatusRequest, QueryStatusResponse> queryStatusCallable(); | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.