Skip to content

Commit 9a4750e

Browse files
FyuselFyusel
committed
feature(core): Add wait handler structure
Signed-off-by: Alexander Dahmen <[email protected]>
1 parent 6bbe05b commit 9a4750e

File tree

9 files changed

+833
-18
lines changed

9 files changed

+833
-18
lines changed

‎CONTRIBUTION.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ We greatly value your feedback, feature requests, additions to the code, bug rep
77

88
- [Developer Guide](#developer-guide)
99
- [Repository structure](#repository-structure)
10+
- [Implementing a module waiter](#implementing-a-module-waiter)
11+
- [Waiter structure](#waiter-structure)
12+
- [Notes](#notes)
1013
- [Code Contributions](#code-contributions)
1114
- [Bug Reports](#bug-reports)
1215

@@ -39,6 +42,29 @@ The files located in `services/[service]` are automatically generated from the [
3942

4043
Inside the `core` submodule you can find several classes that are used by all service modules. Examples of usage of the SDK are located in the `examples` directory.
4144

45+
### Implementing a service waiter
46+
47+
Waiters are routines that wait for the completion of asynchronous operations. They are located in a folder named `wait` inside each service folder.
48+
49+
Let's suppose you want to implement the waiters for the `Create`, `Update` and `Delete` operations of a resource `bar` of service `foo`:
50+
51+
1. Start by creating a new folder `wait/` inside `services/foo/`, if it doesn't exist yet
52+
2. Create a file `FooWait.java` inside your new Java package `cloud.stackit.sdk.resourcemanager.wait`, if it doesn't exist yet. The class should be named `FooWait`.
53+
3. Refer to the [Waiter structure](./CONTRIBUTION.md/#waiter-structure) section for details on the structure of the file and the methods
54+
4. Add unit tests to the wait functions
55+
56+
#### Waiter structure
57+
58+
You can find a typical waiter structure here: [Example](./services/resourcemanager/src/main/java/cloud/stackit/sdk/resourcemanager/wait/ResourcemanagerWait.java)
59+
60+
#### Notes
61+
62+
- The success condition may vary from service to service. In the example above we wait for the field `Status` to match a successful or failed message, but other services may have different fields and/or values to represent the state of the create, update or delete operations.
63+
- The `id` and the `state` might not be present on the root level of the API response, this also varies from service to service. You must always match the resource `id` and the resource `state` to what is expected.
64+
- The timeout values included above are just for reference, each resource takes different amounts of time to finish the create, update or delete operations. You should account for some buffer, e.g. 15 minutes, on top of normal execution times.
65+
- For some resources, after a successful delete operation the resource can't be found anymore, so a call to the `Get` method would result in an error. In those cases, the waiter can be implemented by calling the `List` method and check that the resource is not present.
66+
- The main objective of the waiter functions is to make sure that the operation was successful, which means any other special cases such as intermediate error states should also be handled.
67+
4268
## Code Contributions
4369

4470
To make your contribution, follow these steps:

‎core/src/main/java/cloud/stackit/sdk/core/exception/ApiException.java‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,12 +7,9 @@
77
public class ApiException extends Exception {
88
private static final long serialVersionUID = 1L;
99

10-
private int code = 0;
11-
private Map<String, List<String>> responseHeaders = null;
12-
private String responseBody = null;
13-
14-
/** Constructor for ApiException. */
15-
public ApiException() {}
10+
private int code;
11+
private Map<String, List<String>> responseHeaders;
12+
private String responseBody;
1613

1714
/**
1815
* Constructor for ApiException.
@@ -162,6 +159,7 @@ public String getResponseBody() {
162159
*
163160
* @return The exception message
164161
*/
162+
@Override
165163
public String getMessage() {
166164
return String.format(
167165
"Message: %s%nHTTP response code: %s%nHTTP response body: %s%nHTTP response headers: %s",

‎core/src/main/java/cloud/stackit/sdk/core/exception/GenericOpenAPIException.java‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
package cloud.stackit.sdk.core.exception;
2+
3+
import java.nio.charset.StandardCharsets;
4+
import java.util.Arrays;
5+
6+
public class GenericOpenAPIException extends ApiException {
7+
private static final long serialVersionUID = 1L;
8+
// When a response has a bad status, this limits the number of characters that are shown from
9+
// the response Body
10+
public int apiErrorMaxCharacterLimit = 500;
11+
12+
private final int statusCode;
13+
private byte[] body;
14+
private final String errorMessage;
15+
16+
public GenericOpenAPIException(ApiException apiException) {
17+
super(apiException.getMessage());
18+
this.statusCode = apiException.getCode();
19+
this.errorMessage = apiException.getMessage();
20+
}
21+
22+
public GenericOpenAPIException(int statusCode, String errorMessage) {
23+
this(statusCode, errorMessage, null);
24+
}
25+
26+
public GenericOpenAPIException(int statusCode, String errorMessage, byte[] body) {
27+
super(errorMessage);
28+
this.statusCode = statusCode;
29+
this.errorMessage = errorMessage;
30+
if (body != null) {
31+
this.body = Arrays.copyOf(body, body.length);
32+
}
33+
}
34+
35+
@Override
36+
public String getMessage() {
37+
// Prevent negative values
38+
if (apiErrorMaxCharacterLimit < 0) {
39+
apiErrorMaxCharacterLimit = 500;
40+
}
41+
42+
if (body == null) {
43+
return String.format("%s, status code %d", errorMessage, statusCode);
44+
}
45+
46+
String bodyStr = new String(body, StandardCharsets.UTF_8);
47+
48+
if (bodyStr.length() <= apiErrorMaxCharacterLimit) {
49+
return String.format("%s, status code %d, Body: %s", errorMessage, statusCode, bodyStr);
50+
}
51+
52+
int indexStart = apiErrorMaxCharacterLimit / 2;
53+
int indexEnd = bodyStr.length() - apiErrorMaxCharacterLimit / 2;
54+
int numberTruncatedCharacters = indexEnd - indexStart;
55+
56+
return String.format(
57+
"%s, status code %d, Body: %s [...truncated %d characters...] %s",
58+
errorMessage,
59+
statusCode,
60+
bodyStr.substring(0, indexStart),
61+
numberTruncatedCharacters,
62+
bodyStr.substring(indexEnd));
63+
}
64+
65+
public int getStatusCode() {
66+
return statusCode;
67+
}
68+
69+
public byte[] getBody() {
70+
if (body == null) {
71+
return new byte[0];
72+
}
73+
return Arrays.copyOf(body, body.length);
74+
}
75+
}

‎core/src/main/java/cloud/stackit/sdk/core/wait/AsyncActionHandler.java‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
package cloud.stackit.sdk.core.wait;
2+
3+
import cloud.stackit.sdk.core.exception.ApiException;
4+
import cloud.stackit.sdk.core.exception.GenericOpenAPIException;
5+
6+
import java.net.HttpURLConnection;
7+
import java.util.Arrays;
8+
import java.util.HashSet;
9+
import java.util.Set;
10+
import java.util.concurrent.CompletableFuture;
11+
import java.util.concurrent.Executors;
12+
import java.util.concurrent.ScheduledExecutorService;
13+
import java.util.concurrent.ScheduledFuture;
14+
import java.util.concurrent.TimeUnit;
15+
import java.util.concurrent.TimeoutException;
16+
import java.util.concurrent.atomic.AtomicInteger;
17+
18+
public class AsyncActionHandler<T> {
19+
public static final Set<Integer> RETRY_HTTP_ERROR_STATUS_CODES =
20+
new HashSet<>(
21+
Arrays.asList(
22+
HttpURLConnection.HTTP_BAD_GATEWAY,
23+
HttpURLConnection.HTTP_GATEWAY_TIMEOUT));
24+
25+
public static final String TEMPORARY_ERROR_MESSAGE =
26+
"Temporary error was found and the retry limit was reached.";
27+
public static final String TIMEOUT_ERROR_MESSAGE = "WaitWithContextAsync() has timed out.";
28+
public static final String NON_GENERIC_API_ERROR_MESSAGE = "Found non-GenericOpenAPIError.";
29+
30+
private final CheckFunction<AsyncActionResult<T>> checkFn;
31+
32+
private long sleepBeforeWaitMillis;
33+
private long throttleMillis;
34+
private long timeoutMillis;
35+
private int tempErrRetryLimit;
36+
37+
// The linter is complaining about this but since we are using Java 8 the
38+
// possibilities are restricted.
39+
@SuppressWarnings("PMD.DoNotUseThreads")
40+
private final ScheduledExecutorService scheduler = Executors.newScheduledThreadPool(1);
41+
42+
public AsyncActionHandler(CheckFunction<AsyncActionResult<T>> checkFn) {
43+
this.checkFn = checkFn;
44+
this.sleepBeforeWaitMillis = 0;
45+
this.throttleMillis = TimeUnit.SECONDS.toMillis(5);
46+
this.timeoutMillis = TimeUnit.MINUTES.toMillis(30);
47+
this.tempErrRetryLimit = 5;
48+
}
49+
50+
/**
51+
* SetThrottle sets the time interval between each check of the async action.
52+
*
53+
* @param duration
54+
* @param unit
55+
*/
56+
public void setThrottle(long duration, TimeUnit unit) {
57+
this.throttleMillis = unit.toMillis(duration);
58+
}
59+
60+
/**
61+
* SetTimeout sets the duration for wait timeout.
62+
*
63+
* @param duration
64+
* @param unit
65+
*/
66+
public void setTimeout(long duration, TimeUnit unit) {
67+
this.timeoutMillis = unit.toMillis(duration);
68+
}
69+
70+
/**
71+
* SetSleepBeforeWait sets the duration for sleep before wait.
72+
*
73+
* @param duration
74+
* @param unit
75+
*/
76+
public void setSleepBeforeWait(long duration, TimeUnit unit) {
77+
this.sleepBeforeWaitMillis = unit.toMillis(duration);
78+
}
79+
80+
/**
81+
* SetTempErrRetryLimit sets the retry limit if a temporary error is found. The list of
82+
* temporary errors is defined in the RetryHttpErrorStatusCodes variable.
83+
*
84+
* @param limit
85+
*/
86+
public void setTempErrRetryLimit(int limit) {
87+
this.tempErrRetryLimit = limit;
88+
}
89+
90+
/**
91+
* Runnable task which is executed periodically.
92+
*
93+
* @param future
94+
* @param startTime
95+
* @param retryTempErrorCounter
96+
*/
97+
private void executeCheckTask(CompletableFuture<T> future, long startTime, AtomicInteger retryTempErrorCounter) {
98+
if (future.isDone()) {
99+
return;
100+
}
101+
if (System.currentTimeMillis() - startTime >= timeoutMillis) {
102+
future.completeExceptionally(new TimeoutException(TIMEOUT_ERROR_MESSAGE));
103+
}
104+
try {
105+
AsyncActionResult<T> result = checkFn.execute();
106+
if (result != null && result.isFinished()) {
107+
future.complete(result.getResponse());
108+
}
109+
} catch (ApiException e) {
110+
GenericOpenAPIException oapiErr = new GenericOpenAPIException(e);
111+
// Some APIs may return temporary errors and the request should be retried
112+
if (!RETRY_HTTP_ERROR_STATUS_CODES.contains(oapiErr.getStatusCode())) {
113+
return;
114+
}
115+
if (retryTempErrorCounter.incrementAndGet() == tempErrRetryLimit) {
116+
// complete the future with corresponding exception
117+
future.completeExceptionally(new Exception(TEMPORARY_ERROR_MESSAGE, oapiErr));
118+
}
119+
} catch (IllegalStateException e) {
120+
future.completeExceptionally(e);
121+
}
122+
}
123+
124+
/**
125+
* WaitWithContextAsync starts the wait until there's an error or wait is done
126+
*
127+
* @return
128+
*/
129+
@SuppressWarnings("PMD.DoNotUseThreads")
130+
public CompletableFuture<T> waitWithContextAsync() {
131+
if (throttleMillis <= 0) {
132+
throw new IllegalArgumentException("Throttle can't be 0 or less");
133+
}
134+
135+
CompletableFuture<T> future = new CompletableFuture<>();
136+
long startTime = System.currentTimeMillis();
137+
AtomicInteger retryTempErrorCounter = new AtomicInteger(0);
138+
139+
// This runnable is called periodically.
140+
Runnable checkTask =
141+
() -> executeCheckTask(future, startTime, retryTempErrorCounter);
142+
143+
// start the periodic execution
144+
ScheduledFuture<?> scheduledFuture =
145+
scheduler.scheduleAtFixedRate(
146+
checkTask, sleepBeforeWaitMillis, throttleMillis, TimeUnit.MILLISECONDS);
147+
148+
// stop task when future is completed
149+
future.whenComplete(
150+
(result, error) -> {
151+
scheduledFuture.cancel(true);
152+
scheduler.shutdown();
153+
});
154+
155+
return future;
156+
}
157+
158+
// Helper class to encapsulate the result of the checkFn
159+
public static class AsyncActionResult<T> {
160+
private final boolean finished;
161+
private final T response;
162+
163+
public AsyncActionResult(boolean finished, T response) {
164+
this.finished = finished;
165+
this.response = response;
166+
}
167+
168+
public boolean isFinished() {
169+
return finished;
170+
}
171+
172+
public T getResponse() {
173+
return response;
174+
}
175+
}
176+
177+
/**
178+
* Helper function to check http status codes during deletion of a resource.
179+
* @param e ApiException to check
180+
* @return true if resource is gone otherwise false
181+
*/
182+
public static boolean checkResourceGoneStatusCodes(ApiException apiException) {
183+
GenericOpenAPIException oapiErr = new GenericOpenAPIException(apiException);
184+
return oapiErr.getStatusCode() == HttpURLConnection.HTTP_NOT_FOUND
185+
|| oapiErr.getStatusCode() == HttpURLConnection.HTTP_FORBIDDEN;
186+
}
187+
}

‎core/src/main/java/cloud/stackit/sdk/core/wait/CheckFunction.java‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
package cloud.stackit.sdk.core.wait;
2+
3+
import cloud.stackit.sdk.core.exception.ApiException;
4+
5+
// Since the Callable FunctionalInterface throws a generic Exception
6+
// and the linter complains about catching a generic Exception this
7+
// FunctionalInterface is needed.
8+
@FunctionalInterface
9+
public interface CheckFunction<V> {
10+
V execute() throws ApiException;
11+
}

0 commit comments

Comments
 (0)