Make the side-declaring agent entries versionless

Mirrors ably-js#2297, matching the registry entries in ably-common#361:
the side flags are registered versionless (like `browser`), because under
lockstep versioning a side-flag version always duplicates the SDK entry
beside it, and across SDKs a bare version cannot say what it versions.
Identity, version and support status keep travelling on the SDK's own
ably-java/<version> entry. Wire shape:

  ably-java/2.0.0 jre/17 ably-pubsub-server

AgentHeaderCreator already emits a null-valued map entry as a bare token,
so no core change is needed; the doors stamp null and drop their
BuildConfig version plumbing. Tests now assert the flag is present as a
bare token and fail if any /version form regresses.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: umair-ably

device/build.gradle.kts

@@ -8,7 +8,6 @@ android {
     defaultConfig {
         minSdk = 19
         compileSdk = 34
-        buildConfigField("String", "VERSION", "\"${property("VERSION_NAME")}\"")
         testInstrumentationRunner = "android.support.test.runner.AndroidJUnitRunner"
     }
 
@@ -23,10 +22,6 @@ android {
         }
     }
 
-    buildFeatures {
-        buildConfig = true
-    }
-
     lint {
         abortOnError = false
     }

device/src/androidTest/java/io/ably/pubsub/device/PubSubDeviceTest.java

@@ -16,6 +16,9 @@
  * The agent entries asserted here are what the platform reads to classify traffic on
  * MAU-priced accounts, so these tests are deliberately strict: if one fails, billing
  * classification is broken, not just a header.
+ * <p>
+ * The side entry is a versionless flag — a bare token on the wire, per ably/ably-common#361
+ * — so the assertions also fail if a version (or any {@code /suffix}) reappears on it.
  */
 public class PubSubDeviceTest {
 
@@ -27,35 +30,43 @@ private static ClientOptions offlineOptions(String key) throws Exception {
         return options;
     }
 
+    /** The stamped entry is present as a versionless flag, and the other side's is absent. */
+    private static void assertDeviceFlag(Map<String, String> agents) {
+        assertTrue("expected the device side flag", agents.containsKey(Side.DEVICE_AGENT_IDENTIFIER));
+        assertNull("the side flag is versionless", agents.get(Side.DEVICE_AGENT_IDENTIFIER));
+        assertFalse("a device client must not carry the server entry",
+            agents.containsKey(Side.SERVER_AGENT_IDENTIFIER));
+    }
+
     @Test
     public void client_stampsDeviceAgent() throws Exception {
         AblyRealtime client = PubSubDevice.clientBuilder(offlineOptions(FAKE_KEY)).build();
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
+        assertDeviceFlag(client.options.agents);
     }
 
     @Test
     public void keyString_isAcceptedAndDisambiguatedAsKey() throws Exception {
         ClientOptions builtOptions = PubSubDevice.clientBuilder(FAKE_KEY).build().options;
         assertEquals(FAKE_KEY, builtOptions.key);
         assertNull(builtOptions.token);
-        assertEquals(BuildConfig.VERSION, builtOptions.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
+        assertDeviceFlag(builtOptions.agents);
     }
 
     @Test
     public void callerAgentEntries_arePreserved_andCannotOverrideTheSideEntry() throws Exception {
         ClientOptions options = offlineOptions(FAKE_KEY);
         Map<String, String> callerAgents = new HashMap<>();
         callerAgents.put("some-sdk", "1.2.3");
-        callerAgents.put(Side.DEVICE_AGENT_IDENTIFIER, "not-the-real-version");
+        callerAgents.put(Side.DEVICE_AGENT_IDENTIFIER, "not-the-real-form");
         options.agents = callerAgents;
 
         AblyRealtime client = PubSubDevice.clientBuilder(options).build();
         assertEquals("1.2.3", client.options.agents.get("some-sdk"));
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
+        // The stamp replaces the caller's value: the flag is present and back to versionless.
+        assertDeviceFlag(client.options.agents);
 
         // the caller's own map is untouched
         assertTrue(options.agents == callerAgents);
-        assertEquals("not-the-real-version", callerAgents.get(Side.DEVICE_AGENT_IDENTIFIER));
-        assertFalse(callerAgents.containsValue(BuildConfig.VERSION));
+        assertEquals("not-the-real-form", callerAgents.get(Side.DEVICE_AGENT_IDENTIFIER));
     }
 }

device/src/main/java/io/ably/pubsub/device/PubSubDevice.java

@@ -62,11 +62,12 @@ private ClientBuilder(ClientOptions options, String keyOrToken) {
          * @throws AblyException if the options, key or token are rejected.
          */
         public AblyRealtime build() throws AblyException {
+            // The side entry is a versionless flag — see Side.
             final ClientOptions stamped;
             if (keyOrToken != null) {
-                stamped = Side.optionsWithSideAgent(keyOrToken, Side.DEVICE_AGENT_IDENTIFIER, BuildConfig.VERSION);
+                stamped = Side.optionsWithSideAgent(keyOrToken, Side.DEVICE_AGENT_IDENTIFIER);
             } else {
-                stamped = Side.optionsWithSideAgent(options, Side.DEVICE_AGENT_IDENTIFIER, BuildConfig.VERSION);
+                stamped = Side.optionsWithSideAgent(options, Side.DEVICE_AGENT_IDENTIFIER);
             }
             return new AblyRealtime(stamped);
         }

server/build.gradle.kts

@@ -1,5 +1,4 @@
 plugins {
-    alias(libs.plugins.build.config)
     alias(libs.plugins.maven.publish)
     checkstyle
     `java-library`
@@ -19,12 +18,6 @@ dependencies {
     testImplementation(libs.bundles.tests)
 }
 
-buildConfig {
-    useJavaOutput()
-    packageName = "io.ably.pubsub.server"
-    buildConfigField("String", "VERSION", "\"${property("VERSION_NAME")}\"")
-}
-
 sourceSets {
     named("main") {
         java {
@@ -35,10 +28,6 @@ sourceSets {
     }
 }
 
-tasks.checkstyleMain.configure {
-    exclude("io/ably/pubsub/server/BuildConfig.java")
-}
-
 tasks.register<Test>("runUnitTests") {
     beforeTest(closureOf<TestDescriptor> { logger.lifecycle("-> $this") })
     outputs.upToDateWhen { false }

server/src/main/java/io/ably/pubsub/server/PubSubServer.java

@@ -64,14 +64,15 @@ public static RealtimeClientBuilder realtimeClientBuilder(String keyOrToken) {
 
     /**
      * Resolves the caller's input exactly as the core constructors would, then stamps the
-     * server-side agent entry. Resolution happens at {@code build()} time so the caller's
-     * input is read once, when the client is constructed.
+     * server-side agent entry (a versionless flag — see {@link Side}). Resolution happens
+     * at {@code build()} time so the caller's input is read once, when the client is
+     * constructed.
      */
     private static ClientOptions stampedOptions(ClientOptions options, String keyOrToken) throws AblyException {
         if (keyOrToken != null) {
-            return Side.optionsWithSideAgent(keyOrToken, Side.SERVER_AGENT_IDENTIFIER, BuildConfig.VERSION);
+            return Side.optionsWithSideAgent(keyOrToken, Side.SERVER_AGENT_IDENTIFIER);
         }
-        return Side.optionsWithSideAgent(options, Side.SERVER_AGENT_IDENTIFIER, BuildConfig.VERSION);
+        return Side.optionsWithSideAgent(options, Side.SERVER_AGENT_IDENTIFIER);
     }
 
     /**

server/src/test/java/io/ably/pubsub/server/PubSubServerTest.java

@@ -15,7 +15,9 @@
 import io.ably.pubsub.internal.Side;
 import java.net.InetSocketAddress;
 import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
 import java.util.HashMap;
+import java.util.List;
 import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;
 import org.junit.Test;
@@ -24,6 +26,9 @@
  * The agent entries asserted here are what the platform reads to classify traffic (and, on
  * MAU-priced accounts, what earns the server exemption), so these tests are deliberately
  * strict: if one fails, billing classification is broken, not just a header.
+ * <p>
+ * The side entry is a versionless flag — a bare token on the wire, per ably/ably-common#361
+ * — so the assertions also fail if a version (or any {@code /suffix}) reappears on it.
  */
 public class PubSubServerTest {
 
@@ -36,32 +41,40 @@ private static ClientOptions offlineOptions(String key) throws AblyException {
         return options;
     }
 
+    /** The stamped entry is present as a versionless flag, and the other side's is absent. */
+    private static void assertServerFlag(Map<String, String> agents) {
+        assertTrue("expected the server side flag", agents.containsKey(Side.SERVER_AGENT_IDENTIFIER));
+        assertNull("the side flag is versionless", agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertFalse("a server client must not carry the device entry",
+            agents.containsKey(Side.DEVICE_AGENT_IDENTIFIER));
+    }
+
     @Test
     public void httpClient_stampsServerAgent() throws AblyException {
         AblyRest client = PubSubServer.httpClientBuilder(offlineOptions(FAKE_KEY)).build();
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertServerFlag(client.options.agents);
     }
 
     @Test
     public void realtimeClient_stampsServerAgent() throws AblyException {
         AblyRealtime client = PubSubServer.realtimeClientBuilder(offlineOptions(FAKE_KEY)).build();
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertServerFlag(client.options.agents);
     }
 
     @Test
     public void keyString_isAcceptedAndDisambiguatedAsKey() throws AblyException {
         AblyRest client = PubSubServer.httpClientBuilder(FAKE_KEY).build();
         assertEquals(FAKE_KEY, client.options.key);
         assertNull(client.options.token);
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertServerFlag(client.options.agents);
     }
 
     @Test
     public void tokenString_isAcceptedAndDisambiguatedAsToken() throws AblyException {
         AblyRest client = PubSubServer.httpClientBuilder(FAKE_TOKEN).build();
         assertEquals(FAKE_TOKEN, client.options.token);
         assertNull(client.options.key);
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertServerFlag(client.options.agents);
     }
 
     @Test
@@ -71,16 +84,17 @@ public void callerAgentEntries_arePreserved() throws AblyException {
         options.agents.put("some-sdk", "1.2.3");
         AblyRest client = PubSubServer.httpClientBuilder(options).build();
         assertEquals("1.2.3", client.options.agents.get("some-sdk"));
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        assertServerFlag(client.options.agents);
     }
 
     @Test
     public void callerCannotOverrideTheSideEntry() throws AblyException {
         ClientOptions options = offlineOptions(FAKE_KEY);
         options.agents = new HashMap<>();
-        options.agents.put(Side.SERVER_AGENT_IDENTIFIER, "not-the-real-version");
+        options.agents.put(Side.SERVER_AGENT_IDENTIFIER, "not-the-real-form");
         AblyRest client = PubSubServer.httpClientBuilder(options).build();
-        assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.SERVER_AGENT_IDENTIFIER));
+        // The stamp replaces the caller's value: the flag is present and back to versionless.
+        assertServerFlag(client.options.agents);
     }
 
     @Test
@@ -107,8 +121,8 @@ public void nullOptions_getTheCoreConstructorsOwnError() {
 
     /**
      * Wire-level assertion: the Ably-Agent header actually sent over HTTP carries the
-     * side-declaring entry alongside the core's base identifier. This is the value billing
-     * classification reads.
+     * side-declaring flag as a bare token alongside the core's base identifier. This is the
+     * value billing classification reads.
      */
     @Test
     public void httpRequests_carryTheServerAgentHeaderOnTheWire() throws Exception {
@@ -133,8 +147,13 @@ public void httpRequests_carryTheServerAgentHeaderOnTheWire() throws Exception {
 
             String agentHeader = observedAgentHeader.get();
             assertNotNull("no Ably-Agent header observed", agentHeader);
-            assertTrue("missing side-declaring entry in: " + agentHeader,
-                agentHeader.contains(Side.SERVER_AGENT_IDENTIFIER + "/" + BuildConfig.VERSION));
+            List<String> tokens = Arrays.asList(agentHeader.split(" "));
+            // The flag must be present as a bare token: `name/anything` means the
+            // versionless stamp regressed (see ably/ably-common#361).
+            assertTrue("missing bare side flag in: " + agentHeader,
+                tokens.contains(Side.SERVER_AGENT_IDENTIFIER));
+            assertFalse("side flag must be versionless in: " + agentHeader,
+                agentHeader.contains(Side.SERVER_AGENT_IDENTIFIER + "/"));
             assertTrue("missing core base identifier in: " + agentHeader,
                 agentHeader.contains("ably-java/"));
         } finally {

shared/src/main/java/io/ably/pubsub/internal/Side.java

@@ -45,6 +45,13 @@ private Side() {}
      * Returns a copy of the caller's options carrying the agent entry that declares this
      * package's side.
      * <p>
+     * The side entry is a <em>versionless flag</em> — a bare token on the wire, like the
+     * platform's own {@code browser} entry — registered as such in the ably-common agents
+     * registry (see ably/ably-common#361). Identity, version and support status keep
+     * travelling on the SDK's own {@code ably-java/<version>} entry alongside it;
+     * {@link io.ably.lib.util.AgentHeaderCreator} emits a map entry with a {@code null}
+     * value as a bare token.
+     * <p>
      * The copy is made with {@link ClientOptions#copy()} and a fresh agents map, so the
      * caller's options and their own {@code agents} map are both left untouched. The
      * caller's {@code agents} entries are preserved alongside the side stamp, so an SDK
@@ -59,10 +66,9 @@ private Side() {}
      *
      * @param options the options the caller passed to the door's builder, or {@code null}.
      * @param identifier the side-declaring agent identifier to stamp.
-     * @param version the version of the package doing the stamping.
      * @return a stamped copy of the options, or {@code null} if {@code options} was {@code null}.
      */
-    public static ClientOptions optionsWithSideAgent(ClientOptions options, String identifier, String version) {
+    public static ClientOptions optionsWithSideAgent(ClientOptions options, String identifier) {
         if (options == null) {
             return null;
         }
@@ -71,28 +77,27 @@ public static ClientOptions optionsWithSideAgent(ClientOptions options, String i
         if (options.agents != null) {
             agents.putAll(options.agents);
         }
-        agents.put(identifier, version);
+        agents.put(identifier, null);
         stamped.agents = agents;
         return stamped;
     }
 
     /**
-     * As {@link #optionsWithSideAgent(ClientOptions, String, String)}, for the API key or
+     * As {@link #optionsWithSideAgent(ClientOptions, String)}, for the API key or
      * token string form the core constructors also accept. Reuses the core's own
      * key-versus-token disambiguation ({@link ClientOptions#ClientOptions(String)}: an Ably
      * API key always contains a colon, an Ably token never does).
      *
      * @param keyOrToken the Ably API key or token string the caller passed to the door's builder.
      * @param identifier the side-declaring agent identifier to stamp.
-     * @param version the version of the package doing the stamping.
      * @return stamped options constructed from the key or token.
      * @throws AblyException if the key or token string is rejected by the core.
      */
-    public static ClientOptions optionsWithSideAgent(String keyOrToken, String identifier, String version)
+    public static ClientOptions optionsWithSideAgent(String keyOrToken, String identifier)
         throws AblyException {
         ClientOptions options = new ClientOptions(keyOrToken);
         options.agents = new LinkedHashMap<>();
-        options.agents.put(identifier, version);
+        options.agents.put(identifier, null);
         return options;
     }
 }