Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(sdk): decode unknown enum values to UNKNOWN in the Java SDK

Yudhi Armyndharisca75c85c01cc
diff --git a/scripts/check-contract-shapes.mjs b/scripts/check-contract-shapes.mjs
index ec518a3d6..511a5fc8b 100644
--- a/scripts/check-contract-shapes.mjs
+++ b/scripts/check-contract-shapes.mjs
@@ -19,7 +19,8 @@
* and optionality only, so the literal sets themselves are ungated on the TS clients. Everywhere
* else the vocabulary IS compared member by member: Python Literals, Go const blocks and Java
* enum constants (by their `@SerializedName`, or the constant's own name when it has none, which
- * is what Gson emits), whether the field carries one member or a list of them.
+ * is what Gson emits; a bare `UNKNOWN` is the decode-only sentinel and is skipped), whether the
+ * field carries one member or a list of them.
*
* One exception, in Java only: Gson serializes an enum constant by name, i.e. as a JSON string, so
* a NUMERIC enum cannot be modelled as a Java enum without a custom adapter: the wire would carry
@@ -1010,7 +1011,9 @@ export function parseJavaTypes(sources) {
continue;
}
const bare = part.replace(/@\w+\([^)]*\)/g, '').trim().match(/^([A-Z][A-Z0-9_]*)$/);
- if (bare) members.push(bare[1]);
+ // A bare UNKNOWN is the client-side sentinel the SDK decodes an unrecognised token to, not
+ // a wire member. An annotated @SerializedName("unknown") is a real member and counts above.
+ if (bare && bare[1] !== 'UNKNOWN') members.push(bare[1]);
}
if (members.length) enums[m[1]] = `enum(${sortEnumMembers([...new Set(members)]).join(',')})`;
}
diff --git a/scripts/check-contract-shapes.spec.mjs b/scripts/check-contract-shapes.spec.mjs
index 87f19fb2b..3c26da3a8 100644
--- a/scripts/check-contract-shapes.spec.mjs
+++ b/scripts/check-contract-shapes.spec.mjs
@@ -242,6 +242,24 @@ test('parseJavaTypes: enum constants resolve to their wire values, annotated or
assert.equal(s.shades.token, 'array<enum(BLUE,RED)>');
});
+test('parseJavaTypes: a bare UNKNOWN sentinel is not a wire member, an annotated "unknown" is', () => {
+ const src = [
+ 'public enum Status {',
+ ' @SerializedName("ready") READY,',
+ ' /** Decoded when the gateway sends a newer value. */',
+ ' UNKNOWN',
+ '}',
+ 'public enum Kind {',
+ ' @SerializedName("chat") CHAT,',
+ ' @SerializedName("unknown") UNKNOWN',
+ '}',
+ 'public record Sample(Status status, Kind kind) {}',
+ ].join('\n');
+ const s = parseJavaTypes([src]).Sample;
+ assert.equal(s.status.token, 'enum(ready)');
+ assert.equal(s.kind.token, 'enum(chat,unknown)');
+});
+
test('isSimpleToken-gated diffing reaches inside an array of enum members', () => {
const hand = { events: { optional: false, token: 'array<enum(a,b)>' } };
const schema = { type: 'object', required: ['events'], properties: { events: { type: 'array', items: { enum: ['a', 'c'] } } } };
diff --git a/sdk/java/README.md b/sdk/java/README.md
index 9bceffe51..e6f7f43e1 100644
--- a/sdk/java/README.md
+++ b/sdk/java/README.md
@@ -82,6 +82,12 @@ intentionally not exposed; all user-facing resources are.
webhook's filters unchanged. To remove every filter, pass
`new WebhookFilters(List.of())` instead.
+A response enum value newer than this SDK decodes to that enum's `UNKNOWN`
+constant (for example `SessionStatus.UNKNOWN`) rather than `null`, so give a
+`switch` over one a `default` branch. `WebhookEvent`, `ProxyType` and
+`MessageDirection` are also sent in requests and have no `UNKNOWN`: an
+unrecognised value there still decodes to `null`.
+
## Error handling
Errors are a typed, unchecked hierarchy — branch with `instanceof` or on
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.java b/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.java
new file mode 100644
index 000000000..9150ce8c0
--- /dev/null
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/LenientEnumTypeAdapterFactory.java
@@ -0,0 +1,53 @@
+package com.rmyndharis.openwa;
+
+import com.google.gson.Gson;
+import com.google.gson.TypeAdapter;
+import com.google.gson.TypeAdapterFactory;
+import com.google.gson.reflect.TypeToken;
+import com.google.gson.stream.JsonReader;
+import com.google.gson.stream.JsonToken;
+import com.google.gson.stream.JsonWriter;
+import java.io.IOException;
+
+/**
+ * Decodes a wire token this SDK does not know to the enum's {@code UNKNOWN} constant instead of
+ * null, so a value the gateway added later is not mistaken for an absent field. Enums without an
+ * {@code UNKNOWN} constant keep Gson's default, and writing is unchanged.
+ */
+final class LenientEnumTypeAdapterFactory implements TypeAdapterFactory {
+ @Override
+ @SuppressWarnings("unchecked")
+ public <T> TypeAdapter<T> create(Gson gson, TypeToken<T> type) {
+ Class<? super T> raw = type.getRawType();
+ if (!raw.isEnum()) {
+ return null;
+ }
+ T unknown = null;
+ for (Object constant : raw.getEnumConstants()) {
+ if (((Enum<?>) constant).name().equals("UNKNOWN")) {
+ unknown = (T) constant;
+ }
+ }
+ if (unknown == null) {
+ return null;
+ }
+ TypeAdapter<T> delegate = gson.getDelegateAdapter(this, type);
+ T fallback = unknown;
+ return new TypeAdapter<T>() {
+ @Override
+ public void write(JsonWriter out, T value) throws IOException {
+ delegate.write(out, value);
+ }
+
+ @Override
+ public T read(JsonReader in) throws IOException {
+ if (in.peek() == JsonToken.NULL) {
+ in.nextNull();
+ return null;
+ }
+ T value = delegate.read(in);
+ return value != null ? value : fallback;
+ }
+ };
+ }
+}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java
index f1063a1b5..212f2851d 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/OpenWAClient.java
@@ -53,7 +53,10 @@ import java.util.Map;
* }</pre>
*/
public final class OpenWAClient {
- private final Gson gson = new Gson();
+ // An unrecognised enum token decodes to that enum's UNKNOWN constant rather than null.
+ private final Gson gson = new GsonBuilder()
+ .registerTypeAdapterFactory(new LenientEnumTypeAdapterFactory())
+ .create();
// Used for the two body types listed in bodySerializer(), never the shared default. Emitting an
// explicit null needs two things that pull in opposite directions: a serializer that decides
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java
index 5e878f401..d193b6fde 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/AccountRestrictionKind.java
@@ -6,5 +6,7 @@ import com.google.gson.annotations.SerializedName;
public enum AccountRestrictionKind {
@SerializedName("reachout_timelock") REACHOUT_TIMELOCK,
@SerializedName("tos_block") TOS_BLOCK,
- @SerializedName("proxy_block") PROXY_BLOCK
+ @SerializedName("proxy_block") PROXY_BLOCK,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java
index 9052d2601..2c21da0a9 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchLifecycleStatus.java
@@ -8,5 +8,7 @@ public enum BatchLifecycleStatus {
@SerializedName("processing") PROCESSING,
@SerializedName("completed") COMPLETED,
@SerializedName("failed") FAILED,
- @SerializedName("cancelled") CANCELLED
+ @SerializedName("cancelled") CANCELLED,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java
index dedf6a551..0c48207d9 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/BatchMessageStatus.java
@@ -7,5 +7,7 @@ public enum BatchMessageStatus {
@SerializedName("pending") PENDING,
@SerializedName("sent") SENT,
@SerializedName("failed") FAILED,
- @SerializedName("cancelled") CANCELLED
+ @SerializedName("cancelled") CANCELLED,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java
index deb852ee7..e8d12bd38 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/DeliveryStatus.java
@@ -13,5 +13,7 @@ public enum DeliveryStatus {
@SerializedName("read")
READ,
@SerializedName("failed")
- FAILED
+ FAILED,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java
index 00c424368..89b33ec8a 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MemberAddMode.java
@@ -5,5 +5,7 @@ import com.google.gson.annotations.SerializedName;
/** Who may add participants to a group. */
public enum MemberAddMode {
@SerializedName("all") ALL,
- @SerializedName("admins") ADMINS
+ @SerializedName("admins") ADMINS,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java
index 83d5e1117..d105d6af5 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/MembershipRequestMethod.java
@@ -12,5 +12,7 @@ public enum MembershipRequestMethod {
@SerializedName("linked_group_join")
LINKED_GROUP_JOIN,
@SerializedName("non_admin_add")
- NON_ADMIN_ADD
+ NON_ADMIN_ADD,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java
index f5014a195..88bb49e1f 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/PresenceState.java
@@ -8,5 +8,7 @@ public enum PresenceState {
@SerializedName("unavailable") UNAVAILABLE,
@SerializedName("composing") COMPOSING,
@SerializedName("recording") RECORDING,
- @SerializedName("paused") PAUSED
+ @SerializedName("paused") PAUSED,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java
index 6fa2cf8d8..3cb0bd32f 100644
--- a/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java
+++ b/sdk/java/src/main/java/com/rmyndharis/openwa/model/SessionStatus.java
@@ -22,5 +22,7 @@ public enum SessionStatus {
@SerializedName("action_required")
ACTION_REQUIRED,
@SerializedName("failed")
- FAILED
+ FAILED,
+ /** Decoded when the gateway sends a value newer than this SDK; not a wire value itself. */
+ UNKNOWN
}
diff --git a/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java b/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java
index 03583fd20..af812f50e 100644
--- a/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java
+++ b/sdk/java/src/test/java/com/rmyndharis/openwa/EnumWireTest.java
@@ -1,20 +1,26 @@
package com.rmyndharis.openwa;
import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;
+import com.rmyndharis.openwa.http.HttpMethod;
+import com.rmyndharis.openwa.model.AccountRestriction;
import com.rmyndharis.openwa.model.AccountRestrictionKind;
import com.rmyndharis.openwa.model.BatchLifecycleStatus;
import com.rmyndharis.openwa.model.BatchMessageResult;
import com.rmyndharis.openwa.model.BatchMessageStatus;
import com.rmyndharis.openwa.model.ChatHistoryMessage;
import com.rmyndharis.openwa.model.ChatKind;
+import com.rmyndharis.openwa.model.GroupInfo;
import com.rmyndharis.openwa.model.MemberAddMode;
import com.rmyndharis.openwa.model.MessageType;
+import com.rmyndharis.openwa.model.ParticipantPresence;
import com.rmyndharis.openwa.model.PresenceState;
import com.rmyndharis.openwa.model.SessionResponse;
import com.rmyndharis.openwa.model.SessionStatus;
+import com.rmyndharis.openwa.support.MockTransport;
import org.junit.jupiter.api.Test;
/**
@@ -88,4 +94,42 @@ class EnumWireTest {
assertEquals(MemberAddMode.ADMINS, g.memberAddMode());
}
+
+ @Test
+ void clientDecodesAnUnrecognisedTokenToUnknownNotNull() {
+ MockTransport tx = new MockTransport();
+ OpenWAClient client = new OpenWAClient(
+ ClientConfig.builder().baseUrl("https://h").apiKey("owa_k1_x").transport(tx).build());
+
+ tx.respond(200, "{\"id\":\"s\",\"name\":\"n\",\"status\":\"brand_new_state\",\"engineLoaded\":true,"
+ + "\"createdAt\":\"t\",\"updatedAt\":\"t\"}");
+ assertEquals(SessionStatus.UNKNOWN, client.sessions.get("s").status());
+
+ tx.respond(200, "{\"chatId\":\"c\",\"status\":\"later\"}");
+ assertEquals(BatchMessageStatus.UNKNOWN,
+ client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());
+ tx.respond(200, "{\"state\":\"later\"}");
+ assertEquals(PresenceState.UNKNOWN,
+ client.request(HttpMethod.GET, "/x", null, null, ParticipantPresence.class).state());
+ tx.respond(200, "{\"kind\":\"later\"}");
+ assertEquals(AccountRestrictionKind.UNKNOWN,
+ client.request(HttpMethod.GET, "/x", null, null, AccountRestriction.class).kind());
+ tx.respond(200, "{\"memberAddMode\":\"later\"}");
+ assertEquals(MemberAddMode.UNKNOWN,
+ client.request(HttpMethod.GET, "/x", null, null, GroupInfo.class).memberAddMode());
+ tx.respond(200, "{\"type\":\"future_type\",\"kind\":\"unknown\"}");
+ ChatHistoryMessage m = client.request(HttpMethod.GET, "/x", null, null, ChatHistoryMessage.class);
+ assertEquals(MessageType.UNKNOWN, m.type());
+ assertEquals(ChatKind.UNKNOWN, m.kind());
+
+ // A null or absent value is still null, and a known token still decodes to its constant.
+ tx.respond(200, "{\"chatId\":\"c\",\"status\":null}");
+ assertNull(client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());
+ tx.respond(200, "{\"chatId\":\"c\",\"status\":\"sent\"}");
+ assertEquals(BatchMessageStatus.SENT,
+ client.request(HttpMethod.GET, "/x", null, null, BatchMessageResult.class).status());
+ tx.respond(200, "{\"id\":\"s\"}");
+ assertNull(client.sessions.get("s").status());
+ }
+
}