Skip to content

Commit 174a03a

Browse files
committed
feat(gax): add progress listener models and ResumableUploadProgressTracker
1 parent 1c271f8 commit 174a03a

4 files changed

Lines changed: 497 additions & 0 deletions

File tree

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
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.resumable;
31+
32+
import com.google.api.core.BetaApi;
33+
import com.google.auto.value.AutoValue;
34+
import org.jspecify.annotations.NullMarked;
35+
import org.jspecify.annotations.Nullable;
36+
37+
/** Progress snapshot of an ongoing or completed resumable upload session. */
38+
@BetaApi
39+
@NullMarked
40+
@AutoValue
41+
public abstract class ResumableUploadProgress {
42+
43+
/** The state of the resumable upload session. */
44+
public enum State {
45+
/** Session initiation is in progress (acquiring upload session URL). */
46+
STARTING,
47+
48+
/** The session initiation completed successfully. */
49+
STARTED,
50+
51+
/** Transmitting chunk payloads to the server. */
52+
UPLOADING,
53+
54+
/** A recoverable error occurred; querying server status and resynchronizing offset. */
55+
RECOVERING,
56+
57+
/** The server query status succeeded and the committed offset was received. */
58+
OFFSET_RECEIVED,
59+
60+
/** The upload was successfully finalized by the server. */
61+
FINALIZED,
62+
63+
/** The upload failed unrecoverably or was cancelled. */
64+
FAILED
65+
}
66+
67+
/**
68+
* Returns the negotiated upload session URI, or {@code null} if session initiation is pending.
69+
*/
70+
public abstract @Nullable String getUploadUrl();
71+
72+
/** Returns the number of bytes confirmed as uploaded to the server so far. */
73+
public abstract long getBytesUploaded();
74+
75+
/** Returns the current state of the upload session. */
76+
public abstract State getState();
77+
78+
public abstract Builder toBuilder();
79+
80+
public static Builder newBuilder() {
81+
return new AutoValue_ResumableUploadProgress.Builder()
82+
.setBytesUploaded(0L)
83+
.setState(State.STARTING);
84+
}
85+
86+
@AutoValue.Builder
87+
public abstract static class Builder {
88+
public abstract Builder setUploadUrl(@Nullable String uploadUrl);
89+
90+
public abstract Builder setBytesUploaded(long bytesUploaded);
91+
92+
public abstract Builder setState(State state);
93+
94+
public abstract ResumableUploadProgress build();
95+
}
96+
}
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
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.resumable;
31+
32+
import com.google.api.core.BetaApi;
33+
import com.google.api.gax.rpc.ResumableUploadFuture;
34+
import org.jspecify.annotations.NullMarked;
35+
36+
/** A callback listener for observing progress and state transitions of a resumable upload. */
37+
@BetaApi
38+
@FunctionalInterface
39+
@NullMarked
40+
public interface ResumableUploadProgressListener {
41+
42+
/**
43+
* Invoked when upload progress or state changes.
44+
*
45+
* @param progress the current progress snapshot of the upload
46+
*/
47+
void onProgress(ResumableUploadProgress progress);
48+
}
Lines changed: 174 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,174 @@
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.rpc;
31+
32+
import static com.google.common.base.Preconditions.checkNotNull;
33+
34+
import com.google.api.gax.resumable.ResumableUploadProgress;
35+
import com.google.api.gax.resumable.ResumableUploadProgressListener;
36+
import com.google.common.util.concurrent.MoreExecutors;
37+
import com.google.errorprone.annotations.concurrent.GuardedBy;
38+
import java.util.ArrayList;
39+
import java.util.List;
40+
import java.util.concurrent.Executor;
41+
import java.util.function.Consumer;
42+
import org.jspecify.annotations.NullMarked;
43+
44+
/**
45+
* Publishes updates to listeners on resumable upload progress and state transitions.
46+
*/
47+
@NullMarked
48+
class ResumableUploadProgressTracker {
49+
50+
private static final class RegisteredListener {
51+
final ResumableUploadProgressListener listener;
52+
final Executor sequentialExecutor;
53+
54+
RegisteredListener(ResumableUploadProgressListener listener, Executor executor) {
55+
this.listener = listener;
56+
this.sequentialExecutor = MoreExecutors.newSequentialExecutor(executor);
57+
}
58+
}
59+
60+
private final Object lock = new Object();
61+
62+
@GuardedBy("lock")
63+
private final List<RegisteredListener> listeners = new ArrayList<>();
64+
65+
@GuardedBy("lock")
66+
private ResumableUploadProgress currentStatus;
67+
68+
ResumableUploadProgressTracker() {
69+
this.currentStatus =
70+
ResumableUploadProgress.newBuilder()
71+
.setState(ResumableUploadProgress.State.STARTING)
72+
.setBytesUploaded(0L)
73+
.build();
74+
}
75+
76+
void addListener(ResumableUploadProgressListener listener, Executor executor) {
77+
checkNotNull(listener, "listener must not be null");
78+
checkNotNull(executor, "executor must not be null");
79+
RegisteredListener entry = new RegisteredListener(listener, executor);
80+
ResumableUploadProgress snapshot;
81+
synchronized (lock) {
82+
snapshot = this.currentStatus;
83+
if (!isTerminal()) {
84+
listeners.add(entry);
85+
}
86+
}
87+
entry.sequentialExecutor.execute(() -> dispatchSafely(listener, snapshot));
88+
}
89+
90+
ResumableUploadProgress getStatus() {
91+
synchronized (lock) {
92+
return currentStatus;
93+
}
94+
}
95+
96+
void onStarted(String uploadUrl) {
97+
checkNotNull(uploadUrl, "uploadUrl must not be null");
98+
transition(
99+
b ->
100+
b.setState(ResumableUploadProgress.State.STARTED)
101+
.setUploadUrl(uploadUrl));
102+
}
103+
104+
void onChunkUploaded(long bytesUploaded) {
105+
transition(
106+
b ->
107+
b.setState(ResumableUploadProgress.State.UPLOADING)
108+
.setBytesUploaded(bytesUploaded));
109+
}
110+
111+
void onRecovering() {
112+
transition(b -> b.setState(ResumableUploadProgress.State.RECOVERING));
113+
}
114+
115+
void onOffsetReceived(long committedOffset) {
116+
transition(
117+
b ->
118+
b.setState(ResumableUploadProgress.State.OFFSET_RECEIVED)
119+
.setBytesUploaded(committedOffset));
120+
}
121+
122+
void onFinalized(long totalBytes) {
123+
transition(
124+
b ->
125+
b.setState(ResumableUploadProgress.State.FINALIZED)
126+
.setBytesUploaded(totalBytes));
127+
}
128+
129+
void onFailed() {
130+
transition(b -> b.setState(ResumableUploadProgress.State.FAILED));
131+
}
132+
133+
@GuardedBy("lock")
134+
private boolean isTerminal() {
135+
ResumableUploadProgress.State state = currentStatus.getState();
136+
return state == ResumableUploadProgress.State.FINALIZED
137+
|| state == ResumableUploadProgress.State.FAILED;
138+
}
139+
140+
private void transition(Consumer<ResumableUploadProgress.Builder> statusUpdater) {
141+
List<RegisteredListener> snapshot;
142+
ResumableUploadProgress newStatus;
143+
synchronized (lock) {
144+
if (isTerminal()) {
145+
return;
146+
}
147+
ResumableUploadProgress.Builder builder = currentStatus.toBuilder();
148+
statusUpdater.accept(builder);
149+
newStatus = builder.build();
150+
this.currentStatus = newStatus;
151+
snapshot = new ArrayList<>(this.listeners);
152+
if (isTerminal()) {
153+
this.listeners.clear();
154+
}
155+
}
156+
notifyListeners(snapshot, newStatus);
157+
}
158+
159+
private void notifyListeners(
160+
List<RegisteredListener> targetListeners, ResumableUploadProgress status) {
161+
for (RegisteredListener entry : targetListeners) {
162+
entry.sequentialExecutor.execute(() -> dispatchSafely(entry.listener, status));
163+
}
164+
}
165+
166+
private static void dispatchSafely(
167+
ResumableUploadProgressListener listener, ResumableUploadProgress status) {
168+
try {
169+
listener.onProgress(status);
170+
} catch (Throwable ignored) {
171+
// Listener exceptions are isolated from the upload pipeline
172+
}
173+
}
174+
}

0 commit comments

Comments
 (0)