Skip to content

Commit 60aabae

Browse files
umair-ablyclaude
andcommitted
Add the device and server door packages with side-declaring agents
Adds the two public artifacts of the PDR-091b split, following the ably-js reference implementation (ably-js#2293): - io.ably.pubsub:server (jar, on :core): PubSubServer.httpClientBuilder() and PubSubServer.realtimeClientBuilder(), each accepting everything the core constructors accept (ClientOptions, API key or token string). - io.ably.pubsub:device (aar, on :core-android): PubSubDevice.clientBuilder(), one door per PDR-091. - A shared side helper (shared/src/main/java, compiled into both door artifacts rather than published) owns the ably-pubsub-device and ably-pubsub-server agent identifiers and the stamping rules: caller entries preserved, side entry applied last and unoverridable, caller's options never mutated, null passing through to the core's own error. The -device/-server suffixes are load-bearing for MAU billing classification and documented as such. - Fixes ClientOptions.copy() to carry headers, fallbackHosts, transportParams and agents, which it previously dropped; the doors rely on copy() for non-mutating stamping. Covered by a new unit test. - Server tests include a wire-level assertion that the Ably-Agent HTTP header carries ably-pubsub-server/<version> alongside the ably-java base identifier; device instrumentation tests assert the same contract and run in the emulator matrix. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent acb8e2e commit 60aabae

13 files changed

Lines changed: 640 additions & 1 deletion

File tree

‎.github/workflows/emulate.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,7 @@ jobs:
5050
arch: ${{ steps.get-avd-arch.outputs.arch }}
5151
target: default
5252
# Print emulator logs if tests fail
53-
script: ./gradlew :core-android:connectedAndroidTest ${{ matrix.android-api-level == 19 && '-PhttpURLConnection' || '' }} || (adb logcat -d System.out:I && exit 1)
53+
script: ./gradlew :core-android:connectedAndroidTest :device:connectedAndroidTest ${{ matrix.android-api-level == 19 && '-PhttpURLConnection' || '' }} || (adb logcat -d System.out:I && exit 1)
5454

5555
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
5656
if: always()

‎device/build.gradle.kts‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
plugins {
2+
alias(libs.plugins.android.library)
3+
alias(libs.plugins.maven.publish)
4+
}
5+
6+
android {
7+
namespace = "io.ably.pubsub.device"
8+
defaultConfig {
9+
minSdk = 19
10+
compileSdk = 34
11+
buildConfigField("String", "VERSION", "\"${property("VERSION_NAME")}\"")
12+
testInstrumentationRunner = "android.support.test.runner.AndroidJUnitRunner"
13+
}
14+
15+
compileOptions {
16+
sourceCompatibility = JavaVersion.VERSION_1_8
17+
targetCompatibility = JavaVersion.VERSION_1_8
18+
}
19+
20+
buildTypes {
21+
getByName("release") {
22+
isMinifyEnabled = false
23+
}
24+
}
25+
26+
buildFeatures {
27+
buildConfig = true
28+
}
29+
30+
lint {
31+
abortOnError = false
32+
}
33+
34+
testOptions.targetSdk = 34
35+
36+
sourceSets {
37+
getByName("main") {
38+
// `../shared` holds the side-agent helper shared with the `server` module; it is
39+
// compiled into each door artifact rather than published as an artifact of its own.
40+
java.srcDirs("src/main/java", "../shared/src/main/java")
41+
}
42+
}
43+
}
44+
45+
dependencies {
46+
api(project(":core-android"))
47+
androidTestImplementation(libs.bundles.instrumental.android)
48+
}
49+
50+
configurations {
51+
all {
52+
exclude(group = "org.hamcrest", module = "hamcrest-core")
53+
resolutionStrategy {
54+
force(libs.jetbrains)
55+
}
56+
}
57+
}

‎device/gradle.properties‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
POM_ARTIFACT_ID=device
2+
POM_NAME=Ably Pub/Sub device SDK
3+
POM_DESCRIPTION=Ably Pub/Sub client for devices: Android apps and other end-user runtimes. The recommended entry point is PubSubDevice.clientBuilder(...).
4+
POM_PACKAGING=aar
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
package io.ably.pubsub.device;
2+
3+
import static org.junit.Assert.assertEquals;
4+
import static org.junit.Assert.assertFalse;
5+
import static org.junit.Assert.assertNull;
6+
import static org.junit.Assert.assertTrue;
7+
8+
import io.ably.lib.realtime.AblyRealtime;
9+
import io.ably.lib.types.ClientOptions;
10+
import io.ably.pubsub.internal.Side;
11+
import java.util.HashMap;
12+
import java.util.Map;
13+
import org.junit.Test;
14+
15+
/**
16+
* The agent entries asserted here are what the platform reads to classify traffic on
17+
* MAU-priced accounts, so these tests are deliberately strict: if one fails, billing
18+
* classification is broken, not just a header.
19+
*/
20+
public class PubSubDeviceTest {
21+
22+
private static final String FAKE_KEY = "fakeAppId.fakeKeyId:fakeKeySecret";
23+
24+
private static ClientOptions offlineOptions(String key) throws Exception {
25+
ClientOptions options = new ClientOptions(key);
26+
options.autoConnect = false;
27+
return options;
28+
}
29+
30+
@Test
31+
public void client_stampsDeviceAgent() throws Exception {
32+
AblyRealtime client = PubSubDevice.clientBuilder(offlineOptions(FAKE_KEY)).build();
33+
assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
34+
}
35+
36+
@Test
37+
public void keyString_isAcceptedAndDisambiguatedAsKey() throws Exception {
38+
ClientOptions builtOptions = PubSubDevice.clientBuilder(FAKE_KEY).build().options;
39+
assertEquals(FAKE_KEY, builtOptions.key);
40+
assertNull(builtOptions.token);
41+
assertEquals(BuildConfig.VERSION, builtOptions.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
42+
}
43+
44+
@Test
45+
public void callerAgentEntries_arePreserved_andCannotOverrideTheSideEntry() throws Exception {
46+
ClientOptions options = offlineOptions(FAKE_KEY);
47+
Map<String, String> callerAgents = new HashMap<>();
48+
callerAgents.put("some-sdk", "1.2.3");
49+
callerAgents.put(Side.DEVICE_AGENT_IDENTIFIER, "not-the-real-version");
50+
options.agents = callerAgents;
51+
52+
AblyRealtime client = PubSubDevice.clientBuilder(options).build();
53+
assertEquals("1.2.3", client.options.agents.get("some-sdk"));
54+
assertEquals(BuildConfig.VERSION, client.options.agents.get(Side.DEVICE_AGENT_IDENTIFIER));
55+
56+
// the caller's own map is untouched
57+
assertTrue(options.agents == callerAgents);
58+
assertEquals("not-the-real-version", callerAgents.get(Side.DEVICE_AGENT_IDENTIFIER));
59+
assertFalse(callerAgents.containsValue(BuildConfig.VERSION));
60+
}
61+
}
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
package io.ably.pubsub.device;
2+
3+
import io.ably.lib.realtime.AblyRealtime;
4+
import io.ably.lib.types.AblyException;
5+
import io.ably.lib.types.ClientOptions;
6+
import io.ably.pubsub.internal.Side;
7+
8+
/**
9+
* The door into Ably Pub/Sub for devices: Android apps and other end-user runtimes.
10+
* <p>
11+
* Clients built here declare themselves device-side to Ably: every connection and request
12+
* they make carries the {@code ably-pubsub-device} agent entry, which is how the platform
13+
* classifies the traffic (on MAU-priced accounts, device traffic is what is counted). The
14+
* side is the package's to declare — a caller-supplied agent entry cannot override it.
15+
* <p>
16+
* There is one door: a device holds one live client. Connectionless operations (history,
17+
* presence reads, token requests) are all available on it.
18+
* <p>
19+
* This builder is the only recommended entry point of this artifact; the classes it
20+
* constructs come from {@code io.ably.pubsub:core-android}, which is an internal
21+
* implementation artifact not intended for direct use.
22+
*/
23+
public final class PubSubDevice {
24+
private PubSubDevice() {}
25+
26+
/**
27+
* Returns a builder for the device's client.
28+
*
29+
* @param options a {@link ClientOptions} object to configure the client.
30+
* @return the builder.
31+
*/
32+
public static ClientBuilder clientBuilder(ClientOptions options) {
33+
return new ClientBuilder(options, null);
34+
}
35+
36+
/**
37+
* Returns a builder for the device's client.
38+
*
39+
* @param keyOrToken an Ably API key or token string.
40+
* @return the builder.
41+
*/
42+
public static ClientBuilder clientBuilder(String keyOrToken) {
43+
return new ClientBuilder(null, keyOrToken);
44+
}
45+
46+
/**
47+
* Builds the device client. Accepts everything the core constructor accepts.
48+
*/
49+
public static final class ClientBuilder {
50+
private final ClientOptions options;
51+
private final String keyOrToken;
52+
53+
private ClientBuilder(ClientOptions options, String keyOrToken) {
54+
this.options = options;
55+
this.keyOrToken = keyOrToken;
56+
}
57+
58+
/**
59+
* Constructs the client, declaring the device side on it.
60+
*
61+
* @return the client.
62+
* @throws AblyException if the options, key or token are rejected.
63+
*/
64+
public AblyRealtime build() throws AblyException {
65+
final ClientOptions stamped;
66+
if (keyOrToken != null) {
67+
stamped = Side.optionsWithSideAgent(keyOrToken, Side.DEVICE_AGENT_IDENTIFIER, BuildConfig.VERSION);
68+
} else {
69+
stamped = Side.optionsWithSideAgent(options, Side.DEVICE_AGENT_IDENTIFIER, BuildConfig.VERSION);
70+
}
71+
return new AblyRealtime(stamped);
72+
}
73+
}
74+
}

‎lib/src/main/java/io/ably/lib/types/ClientOptions.java‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -372,6 +372,10 @@ public ClientOptions copy() {
372372
copied.authParams = authParams;
373373
copied.queryTime = queryTime;
374374
copied.useTokenAuth = useTokenAuth;
375+
copied.headers = headers;
376+
copied.fallbackHosts = fallbackHosts;
377+
copied.transportParams = transportParams;
378+
copied.agents = agents;
375379
return copied;
376380
}
377381

‎lib/src/test/java/io/ably/lib/types/ClientOptionsTest.java‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
11
package io.ably.lib.types;
22

3+
import static org.junit.Assert.assertArrayEquals;
4+
import static org.junit.Assert.assertSame;
35
import static org.junit.Assert.assertTrue;
46

7+
import java.util.HashMap;
8+
59
import org.junit.Test;
610

711
public class ClientOptionsTest {
@@ -13,4 +17,24 @@ public void should_support_idempotent_rest_publishing() {
1317
// Then
1418
assertTrue(clientOptions.idempotentRestPublishing);
1519
}
20+
21+
@Test
22+
public void copy_carries_headers_fallbackHosts_transportParams_and_agents() {
23+
// Given
24+
clientOptions.headers = new HashMap<>();
25+
clientOptions.headers.put("X-Custom", "value");
26+
clientOptions.fallbackHosts = new String[]{"a.example.com", "b.example.com"};
27+
clientOptions.transportParams = new Param[]{new Param("remainPresentFor", "1000")};
28+
clientOptions.agents = new HashMap<>();
29+
clientOptions.agents.put("some-sdk", "1.2.3");
30+
31+
// When
32+
ClientOptions copied = clientOptions.copy();
33+
34+
// Then
35+
assertSame(clientOptions.headers, copied.headers);
36+
assertArrayEquals(clientOptions.fallbackHosts, copied.fallbackHosts);
37+
assertSame(clientOptions.transportParams, copied.transportParams);
38+
assertSame(clientOptions.agents, copied.agents);
39+
}
1640
}

‎server/build.gradle.kts‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
plugins {
2+
alias(libs.plugins.build.config)
3+
alias(libs.plugins.maven.publish)
4+
checkstyle
5+
`java-library`
6+
}
7+
8+
java {
9+
sourceCompatibility = JavaVersion.VERSION_1_8
10+
targetCompatibility = JavaVersion.VERSION_1_8
11+
}
12+
13+
tasks.withType<Jar> {
14+
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
15+
}
16+
17+
dependencies {
18+
api(project(":core"))
19+
testImplementation(libs.bundles.tests)
20+
}
21+
22+
buildConfig {
23+
useJavaOutput()
24+
packageName = "io.ably.pubsub.server"
25+
buildConfigField("String", "VERSION", "\"${property("VERSION_NAME")}\"")
26+
}
27+
28+
sourceSets {
29+
named("main") {
30+
java {
31+
// `../shared` holds the side-agent helper shared with the `device` module; it is
32+
// compiled into each door artifact rather than published as an artifact of its own.
33+
srcDirs("src/main/java", "../shared/src/main/java")
34+
}
35+
}
36+
}
37+
38+
tasks.checkstyleMain.configure {
39+
exclude("io/ably/pubsub/server/BuildConfig.java")
40+
}
41+
42+
tasks.register<Test>("runUnitTests") {
43+
beforeTest(closureOf<TestDescriptor> { logger.lifecycle("-> $this") })
44+
outputs.upToDateWhen { false }
45+
}

‎server/gradle.properties‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
POM_ARTIFACT_ID=server
2+
POM_NAME=Ably Pub/Sub server SDK
3+
POM_DESCRIPTION=Ably Pub/Sub client for servers and other trusted backend environments. The recommended entry points are PubSubServer.httpClientBuilder(...) and PubSubServer.realtimeClientBuilder(...).
4+
POM_PACKAGING=jar

0 commit comments

Comments
 (0)