Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(sdk-java): note that the request timeout also bounds the response body (#1830)

Yudhi Armyndharis8ff138f16f70
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 886ce0259..c8c5c79e0 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -166,9 +166,11 @@ WebhookDelivery delivery =
- **Redirects are never followed.** A `3xx` surfaces as an `OpenWAApiError`
rather than being followed, so the API key is never re-sent to a redirect
target.
-- **Default per-request timeout** is 30 s (configurable). Path segments (chat /
- message ids) are percent-encoded; a base-URL path prefix (e.g. behind a proxy
- at `/v1`) is preserved.
+- **Default per-request timeout** is 30 s (configurable). It bounds the whole
+ exchange, response body included, so raise `timeout` for large
+ `messages.media` or `status.media` downloads over a slow link. Path segments
+ (chat / message ids) are percent-encoded; a base-URL path prefix (e.g. behind
+ a proxy at `/v1`) is preserved.
- **Empty and dot ids are refused.** An empty, `.` or `..` id throws
`IllegalArgumentException` and nothing is sent, so a proxy that resolves dot
segments cannot turn the call into one on the parent resource. The raw
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/ClientConfig.java b/sdk/java/src/main/java/com/rmyndharis/openwa/ClientConfig.java
index 8f7dbc7ec..9b1df3197 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/ClientConfig.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/ClientConfig.java
@@ -107,7 +107,7 @@ public final class ClientConfig {
return this;
}
- /** Per-request timeout (default 30s). */
+ /** Per-request timeout (default 30s), covering the whole exchange, response body included, with the default transport. */
public Builder timeout(Duration v) {
this.timeout = v;
return this;
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
index 32fde8e82..ca0e3133e 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/MessagesResource.java
@@ -313,6 +313,7 @@ public final class MessagesResource {
/**
* Fetch a message's stored media bytes: the archived file when one exists, else the inline
* copy on the message row (covers media sent by this account); 404 when neither holds bytes.
+ * The client timeout bounds the whole download.
*/
public BinaryResponse media(String sessionId, String chatId, String messageId) {
return client.requestBytes(
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/StatusResource.java b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/StatusResource.java
index c312d9f53..d2df4af65 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/resources/StatusResource.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/resources/StatusResource.java
@@ -44,7 +44,10 @@ public final class StatusResource {
StatusListResult.class);
}
- /** Fetch the stored media bytes for a status update (404 when there is no stored media). */
+ /**
+ * Fetch the stored media bytes for a status update (404 when there is no stored media).
+ * The client timeout bounds the whole download.
+ */
public BinaryResponse media(String sessionId, String statusId) {
return client.requestBytes(
HttpMethod.GET,
diff --git a/src/common/docs-governance.spec.ts b/src/common/docs-governance.spec.ts
index f40004d66..6325c42ae 100644
--- a/src/common/docs-governance.spec.ts
+++ b/src/common/docs-governance.spec.ts
@@ -264,6 +264,18 @@ describe('governance docs match the repository', () => {
}
});
+ // The Java transport waits on the whole exchange with the client timeout, so a slow media download
+ // can time out where it once finished. Callers size the timeout from these two descriptions.
+ it('says the Java SDK timeout also bounds the response body', () => {
+ const java = 'sdk/java/src/main/java/com/rmyndharis/openwa';
+ expect(read(java, 'http/DefaultHttpTransport.java')).toMatch(/future\.get\(timeoutMs, TimeUnit\.MILLISECONDS\)/);
+ const readme = between(read('sdk/java/README.md'), '- **Default per-request timeout**', '\n- **');
+ expect(readme.replace(/\s+/g, ' ')).toMatch(/bounds the whole exchange, response body included/);
+ expect(read(java, 'ClientConfig.java')).toMatch(
+ /Per-request timeout \(default 30s\), covering the whole exchange, response body included, with the default transport/,
+ );
+ });
+
it('keeps the README non-affiliation disclaimer', () => {
const section = between(read('README.md'), '## Disclaimer', '\n## ');
expect(section).toMatch(/not affiliated/);