Skip to content

Commit d43a3a9

Browse files
authored
Merge pull request #1233 from ably/integration/split-2-door-packages
[Split 2/3] Add io.ably.pubsub:device and :server door packages with side-declaring agents
2 parents d22cbf0 + 9642ca8 commit d43a3a9

16 files changed

Lines changed: 682 additions & 15 deletions

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: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
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+
testInstrumentationRunner = "android.support.test.runner.AndroidJUnitRunner"
12+
}
13+
14+
compileOptions {
15+
sourceCompatibility = JavaVersion.VERSION_1_8
16+
targetCompatibility = JavaVersion.VERSION_1_8
17+
}
18+
19+
buildTypes {
20+
getByName("release") {
21+
isMinifyEnabled = false
22+
}
23+
}
24+
25+
lint {
26+
abortOnError = false
27+
}
28+
29+
testOptions.targetSdk = 34
30+
31+
sourceSets {
32+
getByName("main") {
33+
// `../shared` holds the side-agent helper shared with the `server` module; it is
34+
// compiled into each door artifact rather than published as an artifact of its own.
35+
java.srcDirs("src/main/java", "../shared/src/main/java")
36+
}
37+
}
38+
}
39+
40+
dependencies {
41+
api(project(":core-android"))
42+
androidTestImplementation(libs.bundles.instrumental.android)
43+
}
44+
45+
configurations {
46+
all {
47+
exclude(group = "org.hamcrest", module = "hamcrest-core")
48+
resolutionStrategy {
49+
force(libs.jetbrains)
50+
}
51+
}
52+
}

‎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: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
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+
* <p>
20+
* The side entry is a versionless flag — a bare token on the wire, registered as such in the ably-common agents registry
21+
* — so the assertions also fail if a version (or any {@code /suffix}) reappears on it.
22+
*/
23+
public class PubSubDeviceTest {
24+
25+
private static final String FAKE_KEY = "fakeAppId.fakeKeyId:fakeKeySecret";
26+
27+
private static ClientOptions offlineOptions(String key) throws Exception {
28+
ClientOptions options = new ClientOptions(key);
29+
options.autoConnect = false;
30+
return options;
31+
}
32+
33+
/** The stamped entry is present as a versionless flag, and the other side's is absent. */
34+
private static void assertDeviceFlag(Map<String, String> agents) {
35+
assertTrue("expected the device side flag", agents.containsKey(Side.DEVICE_AGENT_IDENTIFIER));
36+
assertNull("the side flag is versionless", agents.get(Side.DEVICE_AGENT_IDENTIFIER));
37+
assertFalse("a device client must not carry the server entry",
38+
agents.containsKey(Side.SERVER_AGENT_IDENTIFIER));
39+
}
40+
41+
@Test
42+
public void client_stampsDeviceAgent() throws Exception {
43+
AblyRealtime client = PubSubDevice.clientBuilder(offlineOptions(FAKE_KEY)).build();
44+
assertDeviceFlag(client.options.agents);
45+
}
46+
47+
@Test
48+
public void keyString_isAcceptedAndDisambiguatedAsKey() throws Exception {
49+
ClientOptions builtOptions = PubSubDevice.clientBuilder(FAKE_KEY).build().options;
50+
assertEquals(FAKE_KEY, builtOptions.key);
51+
assertNull(builtOptions.token);
52+
assertDeviceFlag(builtOptions.agents);
53+
}
54+
55+
@Test
56+
public void callerAgentEntries_arePreserved_andCannotOverrideTheSideEntry() throws Exception {
57+
ClientOptions options = offlineOptions(FAKE_KEY);
58+
Map<String, String> callerAgents = new HashMap<>();
59+
callerAgents.put("some-sdk", "1.2.3");
60+
callerAgents.put(Side.DEVICE_AGENT_IDENTIFIER, "not-the-real-form");
61+
options.agents = callerAgents;
62+
63+
AblyRealtime client = PubSubDevice.clientBuilder(options).build();
64+
assertEquals("1.2.3", client.options.agents.get("some-sdk"));
65+
// The stamp replaces the caller's value: the flag is present and back to versionless.
66+
assertDeviceFlag(client.options.agents);
67+
68+
// the caller's own map is untouched
69+
assertTrue(options.agents == callerAgents);
70+
assertEquals("not-the-real-form", callerAgents.get(Side.DEVICE_AGENT_IDENTIFIER));
71+
}
72+
}
Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
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+
// The side entry is a versionless flag — see Side.
66+
final ClientOptions stamped;
67+
if (keyOrToken != null) {
68+
stamped = Side.optionsWithSideAgent(keyOrToken, Side.DEVICE_AGENT_IDENTIFIER);
69+
} else {
70+
stamped = Side.optionsWithSideAgent(options, Side.DEVICE_AGENT_IDENTIFIER);
71+
}
72+
return new AblyRealtime(stamped);
73+
}
74+
}
75+
}

‎lib/src/main/java/io/ably/lib/transport/Defaults.java‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,14 @@ public class Defaults {
1414
*/
1515
public static final String ABLY_PROTOCOL_VERSION = "6";
1616

17-
public static final String ABLY_AGENT_VERSION = String.format("%s/%s", "ably-java", BuildConfig.VERSION);
17+
/**
18+
* The SDK family identifier. It renamed from {@code ably-java} with the per-side package
19+
* split, so the identifier alone partitions the fleet: {@code ably-java/*} is legacy-package
20+
* traffic, {@code ably-pubsub-java/*} is new-package traffic. It names the family rather than
21+
* any one published artifact; the side a client declares travels as a separate versionless
22+
* agent entry (see io.ably.pubsub.internal.Side and the agents registry in ably-common).
23+
*/
24+
public static final String ABLY_AGENT_VERSION = String.format("%s/%s", "ably-pubsub-java", BuildConfig.VERSION);
1825

1926
/* realtime params */
2027
public static final String ABLY_PROTOCOL_VERSION_PARAM = "v";

‎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/test/realtime/RealtimeHttpHeaderTest.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ public void realtime_websocket_param_test() {
8888
* Defaults.ABLY_AGENT_PARAM, as ultimately the request param has been derived from those values.
8989
*/
9090
assertEquals("Verify correct lib version", requestParameters.get("agent"),
91-
Collections.singletonList("ably-java/2.0.0 jre/" + System.getProperty("java.version")));
91+
Collections.singletonList("ably-pubsub-java/2.0.0 jre/" + System.getProperty("java.version")));
9292

9393
/* Spec RTN2a */
9494
assertEquals("Verify correct format", requestParameters.get("format"),

‎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
}

‎pubsub-adapter/src/test/kotlin/com/ably/pubsub/SdkWrapperAgentHeaderTest.kt‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -27,23 +27,23 @@ class SdkWrapperAgentHeaderTest {
2727
server.servedRequests.test {
2828
wrapperSdkClient.time()
2929
assertEquals(
30-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
30+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
3131
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
3232
)
3333
}
3434

3535
server.servedRequests.test {
3636
realtimeClient.time()
3737
assertEquals(
38-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
38+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
3939
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
4040
)
4141
}
4242

4343
server.servedRequests.test {
4444
wrapperSdkClient.request("/time")
4545
assertEquals(
46-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
46+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
4747
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
4848
)
4949
}
@@ -59,23 +59,23 @@ class SdkWrapperAgentHeaderTest {
5959
server.servedRequests.test {
6060
wrapperSdkClient.time()
6161
assertEquals(
62-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
62+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
6363
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
6464
)
6565
}
6666

6767
server.servedRequests.test {
6868
restClient.time()
6969
assertEquals(
70-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
70+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
7171
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
7272
)
7373
}
7474

7575
server.servedRequests.test {
7676
wrapperSdkClient.request("/time")
7777
assertEquals(
78-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
78+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
7979
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
8080
)
8181
}
@@ -91,23 +91,23 @@ class SdkWrapperAgentHeaderTest {
9191
server.servedRequests.test {
9292
wrapperSdkClient.channels.get("test").history()
9393
assertEquals(
94-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
94+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
9595
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
9696
)
9797
}
9898

9999
server.servedRequests.test {
100100
restClient.channels.get("test").history()
101101
assertEquals(
102-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
102+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
103103
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
104104
)
105105
}
106106

107107
server.servedRequests.test {
108108
wrapperSdkClient.channels.get("test").presence.history()
109109
assertEquals(
110-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
110+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
111111
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
112112
)
113113
}
@@ -123,23 +123,23 @@ class SdkWrapperAgentHeaderTest {
123123
server.servedRequests.test {
124124
wrapperSdkClient.channels.get("test").history()
125125
assertEquals(
126-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
126+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
127127
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
128128
)
129129
}
130130

131131
server.servedRequests.test {
132132
realtimeClient.channels.get("test").history()
133133
assertEquals(
134-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
134+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}"),
135135
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
136136
)
137137
}
138138

139139
server.servedRequests.test {
140140
wrapperSdkClient.channels.get("test").presence.history()
141141
assertEquals(
142-
setOf("ably-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
142+
setOf("ably-pubsub-java/${BuildConfig.VERSION}", "jre/${System.getProperty("java.version")}", "chat-android/0.1.0"),
143143
awaitItem().headers["ably-agent"]?.split(" ")?.toSet(),
144144
)
145145
}

0 commit comments

Comments
 (0)