Skip to content

Commit a6995e8

Browse files
committed
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.
1 parent ddf430f commit a6995e8

5 files changed

Lines changed: 700 additions & 0 deletions

File tree

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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 org.jspecify.annotations.NullMarked;
33+
34+
/** Enumeration of the supported resumable upload wire commands. */
35+
@NullMarked
36+
enum ResumableUploadCommand {
37+
START,
38+
UPLOAD,
39+
FINALIZE,
40+
UPLOAD_FINALIZE,
41+
QUERY,
42+
CANCEL
43+
}
Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
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 com.google.common.collect.ImmutableMap;
33+
import java.io.IOException;
34+
import java.util.Objects;
35+
import java.util.concurrent.CancellationException;
36+
import org.jspecify.annotations.NullMarked;
37+
38+
/**
39+
* Classifies exceptions encountered during resumable upload commands to determine whether/how to
40+
* recover.
41+
*/
42+
@NullMarked
43+
final class ResumableUploadErrorClassifier {
44+
45+
enum Category {
46+
TRANSIENT,
47+
RECOVERABLE,
48+
FATAL
49+
}
50+
51+
private static final ImmutableMap<Integer, Category> HTTP_STATUS_MAP =
52+
ImmutableMap.<Integer, Category>builder()
53+
.put(408, Category.TRANSIENT)
54+
.put(429, Category.TRANSIENT)
55+
.put(500, Category.TRANSIENT)
56+
.put(502, Category.TRANSIENT)
57+
.put(503, Category.TRANSIENT)
58+
.put(504, Category.TRANSIENT)
59+
.put(400, Category.RECOVERABLE)
60+
.put(409, Category.RECOVERABLE)
61+
.put(412, Category.RECOVERABLE)
62+
.put(416, Category.RECOVERABLE)
63+
.put(401, Category.FATAL)
64+
.put(403, Category.FATAL)
65+
.put(404, Category.FATAL)
66+
.put(405, Category.FATAL)
67+
.put(410, Category.FATAL)
68+
.put(413, Category.FATAL)
69+
.put(415, Category.FATAL)
70+
.build();
71+
72+
private ResumableUploadErrorClassifier() {}
73+
74+
/**
75+
* Classifies an exception for the given upload command according to protocol rules.
76+
*
77+
* @param t the error to classify
78+
* @param command the upload command that produced the error
79+
* @return the classified error category
80+
*/
81+
static Category classify(Throwable t, ResumableUploadCommand command) {
82+
Objects.requireNonNull(t, "t must not be null");
83+
Objects.requireNonNull(command, "command must not be null");
84+
85+
// Cancellation is terminal and never retryable.
86+
if (t instanceof CancellationException) {
87+
return Category.FATAL;
88+
}
89+
90+
if (t instanceof ApiException) {
91+
ApiException apiException = (ApiException) t;
92+
93+
// GAX assigns a synthetic HTTP 500 to Code.UNKNOWN. Only retry if caused
94+
// by an IOException; client bugs (NPE, etc.) must remain FATAL.
95+
// Actual 500s from the wire arrive with Code.INTERNAL.
96+
if (apiException.getStatusCode().getCode() == StatusCode.Code.UNKNOWN) {
97+
Throwable cause = apiException.getCause();
98+
if (cause instanceof IOException) {
99+
return Category.TRANSIENT;
100+
}
101+
return Category.FATAL;
102+
}
103+
104+
// Server rejections (final/cancelled on non-2xx) and protocol violations map to
105+
// FAILED_PRECONDITION and are terminal. HTTP 408 and 412 also map to FAILED_PRECONDITION in
106+
// HttpJsonStatusCode but have distinct protocol categories.
107+
Object transportCode = apiException.getStatusCode().getTransportCode();
108+
if (apiException.getStatusCode().getCode() == StatusCode.Code.FAILED_PRECONDITION
109+
&& !Integer.valueOf(408).equals(transportCode)
110+
&& !Integer.valueOf(412).equals(transportCode)) {
111+
return Category.FATAL;
112+
}
113+
114+
// Status table lookup on raw HTTP transport code.
115+
if (transportCode instanceof Integer) {
116+
Category category = HTTP_STATUS_MAP.get(transportCode);
117+
if (category == Category.RECOVERABLE && !isRecoverableCommand(command)) {
118+
return Category.FATAL;
119+
}
120+
if (category != null) {
121+
return category;
122+
}
123+
}
124+
return Category.FATAL;
125+
}
126+
127+
// Plain I/O or timeout exceptions that bypassed ApiException wrapping are transient.
128+
if (t instanceof IOException) {
129+
return Category.TRANSIENT;
130+
}
131+
132+
// Unrecognized errors fail the upload immediately.
133+
return Category.FATAL;
134+
}
135+
136+
/**
137+
* Classifies a missing upload status response header according to the wire command.
138+
*
139+
* @param command the upload command that received a response lacking the status header
140+
* @return the classified error category
141+
*/
142+
static Category classifyMissingStatusHeader(ResumableUploadCommand command) {
143+
Objects.requireNonNull(command, "command must not be null");
144+
switch (command) {
145+
case START:
146+
return Category.TRANSIENT;
147+
case UPLOAD:
148+
case FINALIZE:
149+
case UPLOAD_FINALIZE:
150+
return Category.RECOVERABLE;
151+
case QUERY:
152+
case CANCEL:
153+
default:
154+
return Category.FATAL;
155+
}
156+
}
157+
158+
private static boolean isRecoverableCommand(ResumableUploadCommand command) {
159+
switch (command) {
160+
case UPLOAD:
161+
case FINALIZE:
162+
case UPLOAD_FINALIZE:
163+
return true;
164+
case START:
165+
case QUERY:
166+
case CANCEL:
167+
default:
168+
return false;
169+
}
170+
}
171+
}
Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
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.api.gax.rpc.ResumableUploadErrorClassifier.Category.TRANSIENT;
33+
34+
import com.google.api.gax.retrying.BasicResultRetryAlgorithm;
35+
import com.google.api.gax.rpc.ResumableUploadErrorClassifier.Category;
36+
import java.util.Objects;
37+
import java.util.concurrent.CancellationException;
38+
import org.jspecify.annotations.NullMarked;
39+
import org.jspecify.annotations.Nullable;
40+
41+
/**
42+
* An adapter that integrates {@link ResumableUploadErrorClassifier} into GAX retrying machinery.
43+
*
44+
* <p>Only transient errors should retry with an identical request; other recoverable errors will
45+
* need to query the upload server to determine the appropriate next request.
46+
*
47+
* @param <ResponseT> the response type of the upload attempt
48+
*/
49+
@NullMarked
50+
final class ResumableUploadResultRetryAlgorithm<ResponseT>
51+
extends BasicResultRetryAlgorithm<ResponseT> {
52+
53+
private final ResumableUploadCommand command;
54+
55+
ResumableUploadResultRetryAlgorithm(ResumableUploadCommand command) {
56+
this.command = Objects.requireNonNull(command);
57+
}
58+
59+
@Override
60+
public boolean shouldRetry(
61+
@Nullable Throwable previousThrowable, @Nullable ResponseT previousResponse) {
62+
// Successful commands (null throwable) and cancellations should not retry.
63+
if (previousThrowable == null || previousThrowable instanceof CancellationException) {
64+
return false;
65+
}
66+
Category category = ResumableUploadErrorClassifier.classify(previousThrowable, command);
67+
// Transient errors are retried directly with the identical request.
68+
return category == TRANSIENT;
69+
}
70+
}

0 commit comments

Comments
 (0)