pubsub: add device and server packages per PDR-091

android/src/main/java/io/ably/lib/push/ActivationContext.java

@@ -60,6 +60,7 @@ public void setAbly(AblyRest ably) {
         this.clientId = ably.auth.clientId;
     }
 
+    @SuppressWarnings("deprecation") // internal push-registration client, not an application entry point
     AblyRest getAbly() throws AblyException {
         if(ably != null) {
             Log.v(TAG, "getAbly(): returning existing Ably instance");
@@ -84,6 +85,7 @@ AblyRest getAbly() throws AblyException {
      * @return AblyRest instance with device identity token auth. We use this instance to perform
      * deregistration calls in push activation flow.
      */
+    @SuppressWarnings("deprecation") // internal push-registration client, not an application entry point
     AblyRest getDeviceIdentityTokenBasedAblyClient(String deviceIdentityToken) throws AblyException {
         ClientOptions clientOptions = ably.options.copy();
         clientOptions.clearAuthOptions();

android/src/main/java/io/ably/lib/rest/AblyRest.java

@@ -20,7 +20,11 @@ public class AblyRest extends AblyBase {
      * Spec: RSC1
      * @param key The Ably API key or token string used to validate the client.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.device.PubSubDevice#clientBuilder()} from the
+     *             {@code io.ably.pubsub:device} artifact instead, which names the side of the
+     *             connection your code runs on.
      */
+    @Deprecated
     public AblyRest(String key) throws AblyException {
         super(key, new AndroidPlatformAgentProvider());
     }
@@ -31,7 +35,11 @@ public AblyRest(String key) throws AblyException {
      * Spec: RSC1
      * @param options A {@link ClientOptions} object to configure the client connection to Ably.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.device.PubSubDevice#clientBuilder()} from the
+     *             {@code io.ably.pubsub:device} artifact instead, which names the side of the
+     *             connection your code runs on.
      */
+    @Deprecated
     public AblyRest(ClientOptions options) throws AblyException {
         super(options, new AndroidPlatformAgentProvider());
     }

build.gradle.kts

@@ -10,6 +10,7 @@ plugins {
     alias(libs.plugins.test.retry) apply false
     alias(libs.plugins.android.application) apply false
     alias(libs.plugins.kotlin.android) apply false
+    alias(libs.plugins.kotlin.multiplatform) apply false
     alias(libs.plugins.kotlin.compose) apply false
 }
 

gradle/libs.versions.toml

@@ -91,4 +91,5 @@ lombok = { id = "io.freefair.lombok", version.ref = "lombok" }
 test-retry = { id = "org.gradle.test-retry", version.ref = "test-retry" }
 android-application = { id = "com.android.application", version.ref = "agp" }
 kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+kotlin-multiplatform = { id = "org.jetbrains.kotlin.multiplatform", version.ref = "kotlin" }
 kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }

java/src/main/java/io/ably/lib/rest/AblyRest.java

@@ -17,7 +17,11 @@ public class AblyRest extends AblyBase {
      * Spec: RSC1
      * @param key The Ably API key or token string used to validate the client.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.server.PubSubServer#httpClientBuilder()} from the
+     *             {@code io.ably.pubsub:server} artifact instead, which names the side of the
+     *             connection your code runs on.
      */
+    @Deprecated
     public AblyRest(String key) throws AblyException {
         super(key, new JavaPlatformAgentProvider());
     }
@@ -28,7 +32,11 @@ public AblyRest(String key) throws AblyException {
      * Spec: RSC1
      * @param options A {@link ClientOptions} object to configure the client connection to Ably.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.server.PubSubServer#httpClientBuilder()} from the
+     *             {@code io.ably.pubsub:server} artifact instead, which names the side of the
+     *             connection your code runs on.
      */
+    @Deprecated
     public AblyRest(ClientOptions options) throws AblyException {
         super(options, new JavaPlatformAgentProvider());
     }

lib/src/main/java/io/ably/lib/realtime/AblyRealtime.java

@@ -56,7 +56,12 @@ public class AblyRealtime extends AblyRest {
      * Spec: RSC1
      * @param key The Ably API key or token string used to validate the client.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.device.PubSubDevice#clientBuilder()} from the
+     *             {@code io.ably.pubsub:device} artifact if this code runs on an end-user device, or
+     *             {@code io.ably.pubsub.server.PubSubServer#realtimeClientBuilder()} from the
+     *             {@code io.ably.pubsub:server} artifact if it runs on infrastructure you control.
      */
+    @Deprecated
     public AblyRealtime(String key) throws AblyException {
         this(new ClientOptions(key));
     }
@@ -67,7 +72,12 @@ public AblyRealtime(String key) throws AblyException {
      * Spec: RSC1
      * @param options A {@link ClientOptions} object.
      * @throws AblyException
+     * @deprecated use {@code io.ably.pubsub.device.PubSubDevice#clientBuilder()} from the
+     *             {@code io.ably.pubsub:device} artifact if this code runs on an end-user device, or
+     *             {@code io.ably.pubsub.server.PubSubServer#realtimeClientBuilder()} from the
+     *             {@code io.ably.pubsub:server} artifact if it runs on infrastructure you control.
      */
+    @Deprecated
     public AblyRealtime(ClientOptions options) throws AblyException {
         super(options);
         final InternalChannels channels = new InternalChannels();

pubsub-device/build.gradle.kts

@@ -0,0 +1,89 @@
+import com.vanniktech.maven.publish.JavadocJar
+import com.vanniktech.maven.publish.KotlinMultiplatform
+import org.jetbrains.kotlin.gradle.dsl.JvmTarget
+
+plugins {
+    alias(libs.plugins.kotlin.multiplatform)
+    alias(libs.plugins.android.library)
+    alias(libs.plugins.maven.publish)
+}
+
+kotlin {
+    explicitApi()
+
+    androidTarget {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_1_8)
+        }
+        publishLibraryVariants("release")
+    }
+
+    jvm {
+        compilerOptions {
+            jvmTarget.set(JvmTarget.JVM_1_8)
+        }
+    }
+
+    sourceSets {
+        commonMain.dependencies {
+            /*
+             * The two platform artifacts publish the same io.ably.lib.* types, so common code
+             * compiles against either one. ably-java is the arbitrary pick; each target below
+             * brings the real one.
+             */
+            compileOnly(project(":java"))
+        }
+        androidMain.dependencies {
+            api(project(":android"))
+        }
+        jvmMain.dependencies {
+            api(project(":java"))
+        }
+        commonTest.dependencies {
+            compileOnly(project(":java"))
+            implementation(kotlin("test"))
+        }
+    }
+}
+
+android {
+    namespace = "io.ably.pubsub.device"
+    compileSdk = 34
+
+    defaultConfig {
+        minSdk = 19
+    }
+
+    compileOptions {
+        sourceCompatibility = JavaVersion.VERSION_1_8
+        targetCompatibility = JavaVersion.VERSION_1_8
+    }
+
+    buildTypes {
+        getByName("release") {
+            isMinifyEnabled = false
+        }
+    }
+
+    lint {
+        abortOnError = false
+    }
+
+    testOptions {
+        targetSdk = 34
+        /*
+         * AndroidPlatformAgentProvider reads android.os.Build.VERSION.SDK_INT, which is an unmocked
+         * stub in local unit tests. Without this it throws instead of returning a default.
+         */
+        unitTests.isReturnDefaultValues = true
+    }
+}
+
+mavenPublishing {
+    configure(KotlinMultiplatform(javadocJar = JavadocJar.Empty(), androidVariantsToPublish = listOf("release")))
+}
+
+/* check.yml invokes `runUnitTests` unqualified across all projects. */
+tasks.register("runUnitTests") {
+    dependsOn("jvmTest", "testDebugUnitTest")
+}

pubsub-device/gradle.properties

@@ -0,0 +1,4 @@
+GROUP=io.ably.pubsub
+POM_ARTIFACT_ID=device
+POM_NAME=Ably Pub/Sub SDK for devices
+POM_DESCRIPTION=Ably Pub/Sub SDK for applications running on end-user devices, for Android and the JVM.

pubsub-device/src/androidMain/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>