Integration branch for io.ably.pubsub:* v2 packages

.github/workflows/check.yml

@@ -24,3 +24,23 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
       - run: ./gradlew checkWithCodenarc checkstyleMain checkstyleTest runUnitTests runLiveObjectsUnitTests :uts:runUtsUnitTests
+
+  # Continuously proves the release pre-flight and that every published module
+  # builds a publishable artifact set, so version/coordinate regressions surface
+  # on PRs rather than on release day.
+  release-dry-run:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # v3
+        with:
+          persist-credentials: false
+      - name: Set up the JDK
+        uses: actions/setup-java@17f84c3641ba7b8f6deff6309fc4c864478f5d62 # v3
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+      - name: Set up Gradle
+        uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
+      - run: ./gradlew verifyReleaseArtifacts publishToMavenLocal

.github/workflows/emulate.yml

@@ -50,10 +50,10 @@ jobs:
           arch: ${{ steps.get-avd-arch.outputs.arch }}
           target: default
           # Print emulator logs if tests fail
-          script: ./gradlew :android:connectedAndroidTest ${{ matrix.android-api-level == 19 && '-PhttpURLConnection' || '' }} || (adb logcat -d System.out:I && exit 1)
+          script: ./gradlew :core-android:connectedAndroidTest :device:connectedAndroidTest ${{ matrix.android-api-level == 19 && '-PhttpURLConnection' || '' }} || (adb logcat -d System.out:I && exit 1)
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
-          name: android-build-reports-${{ matrix.android-api-level }}
-          path: android/build/reports/
+          name: core-android-build-reports-${{ matrix.android-api-level }}
+          path: core-android/build/reports/

.github/workflows/integration-test.yml

@@ -27,13 +27,13 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
 
-      - run: ./gradlew :java:testRestSuite -PhttpURLConnection
+      - run: ./gradlew :core:testRestSuite -PhttpURLConnection
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
-          name: java-build-reports-rest
-          path: java/build/reports/
+          name: core-build-reports-rest
+          path: core/build/reports/
 
   check-realtime-httpurlconnection:
     runs-on: ubuntu-latest
@@ -54,13 +54,13 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
 
-      - run: ./gradlew :java:testRealtimeSuite -PhttpURLConnection
+      - run: ./gradlew :core:testRealtimeSuite -PhttpURLConnection
 
       - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
         if: always()
         with:
-          name: java-build-reports-realtime
-          path: java/build/reports/
+          name: core-build-reports-realtime
+          path: core/build/reports/
   check-rest-okhttp:
     runs-on: ubuntu-latest
     permissions:
@@ -80,7 +80,7 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
 
-      - run: ./gradlew :java:testRestSuite
+      - run: ./gradlew :core:testRestSuite
 
   check-realtime-okhttp:
     runs-on: ubuntu-latest
@@ -101,7 +101,7 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
 
-      - run: ./gradlew :java:testRealtimeSuite
+      - run: ./gradlew :core:testRealtimeSuite
 
   check-liveobjects:
     runs-on: ubuntu-latest

.github/workflows/javadoc.yml

@@ -39,6 +39,6 @@ jobs:
       - name: Upload Documentation
         uses: ably/sdk-upload-action@4e694297f208b72b5a9f6b1248a1556f19f821d6 # v2
         with:
-          sourcePath: java/build/docs/javadoc
+          sourcePath: core/build/docs/javadoc
           githubToken: ${{ secrets.GITHUB_TOKEN }}
           artifactName: javadoc

.github/workflows/release.yaml

@@ -46,6 +46,12 @@ jobs:
       - name: Set up Gradle
         uses: gradle/actions/setup-gradle@d9c87d481d55275bb5441eef3fe0e46805f9ef70 # v3
 
+      # Fails before anything is uploaded if the artifact set, group or lockstep
+      # version drifts (core, core-android, device and server release
+      # together on the same version; partial release must be impossible).
+      - name: Release pre-flight
+        run: ./gradlew verifyReleaseArtifacts
+
       - name: Publish and release to Maven Central
         run: ./gradlew publishAndReleaseToMavenCentral
         env:

CONTRIBUTING.md

@@ -5,13 +5,13 @@
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Ensure you have added suitable tests and the test suite is passing(`./gradlew java:testRestSuite java:testRealtimeSuite android:connectedAndroidTest`)
+4. Ensure you have added suitable tests and the test suite is passing(`./gradlew core:testRestSuite core:testRealtimeSuite core-android:connectedAndroidTest`)
 5. Push to the branch (`git push origin my-new-feature`)
 6. Create a new Pull Request
 
 ### Building
 
-The library consists of JRE-specific library (in `java/`) and an Android-specific library (in `android/`). The libraries are largely common-sourced; the `lib/` directory contains the common parts.
+The library consists of JRE-specific library (in `core/`) and an Android-specific library (in `core-android/`). The libraries are largely common-sourced; the `lib/` directory contains the common parts.
 
 A gradle wrapper is included so these tasks can run without any prior installation of gradle. The Linux/OSX form of the commands, given below, is:
 
@@ -23,11 +23,11 @@ but on Windows there is a batch file:
 
 The JRE-specific library JAR is built with:
 
-    ./gradlew java:jar
+    ./gradlew core:jar
 
 The Android-specific library AAR is built with:
 
-    ./gradlew android:assemble
+    ./gradlew core-android:assemble
 
 (The `ANDROID_HOME` environment variable must be set appropriately.)
 
@@ -85,7 +85,7 @@ Once done, your custom network engine will be available for use within `ably-jav
 
 We use [Checkstyle](https://checkstyle.org/) to enforce code style and spot for transgressions and illogical constructs
 in our Java source files.
-The Gradle build has been configured to run these on `java:assembleRelease`.
+The Gradle build has been configured to run these on `core:assembleRelease`.
 It does not run for the Android build yet.
 
 You can run just the Checkstyle rules on their own using:
@@ -123,53 +123,53 @@ The gradle project files can be imported to create projects in IntelliJ IDEA, Ec
 
 #### Importing into IntelliJ
 
-The top-level ably-java project can be imported into IntelliJ IDEA, enabling development of both the java and android projects. This has been tested with IntelliJ IDEA Ultimate 2017.2. To import into IDEA:
+The top-level ably-java project can be imported into IntelliJ IDEA, enabling development of both the core and core-android projects. This has been tested with IntelliJ IDEA Ultimate 2017.2. To import into IDEA:
 
 - do File->New->Project from Existing Sources...
 - select ably-java/settings.gradle
 - in the import dialog, check "Use auto-import" and uncheck "Create separate module per source set"
 - select "ok"
 
-This will create a project with separate java and android modules.
+This will create a project with separate core and core-android modules.
 
 Interactive run/debug configurations to execute the unit tests can be created as follows:
 - select Run->Edit configurations ...
-- for the java project, create a new "JUnit" run configuration; or for the android project create a new "Android Instrumented Tests" configuration;
+- for the core project, create a new "JUnit" run configuration; or for the core-android project create a new "Android Instrumented Tests" configuration;
 - select the Class as RealtimeSuite or RestSuite;
 - select the relevant module for the classpath.
 
 In order to run the Android configuration it is necessary to set up the Android SDK path by selecting a project of module and opening the module settings. The Android SDK needs to be added under Platform Settings->SDKs.
 
 #### Importing into Eclipse
 
-The top-level ably-java project can be imported into Eclipse, enabling development of the java project only. The Eclipse Android development plugin (ADT) is no longer supported. This has been tested with Eclipse Oxygen.2
+The top-level ably-java project can be imported into Eclipse, enabling development of the core project only. The Eclipse Android development plugin (ADT) is no longer supported. This has been tested with Eclipse Oxygen.2
 
 To import into Eclipse:
 
 - do File->Import->Gradle->Existing Gradle project;
 - follow the wizard steps, selecting the ably-java root directory.
 
-This will create two projects in the workspace; one for the top-level ably-java project, and one for the java project.
+This will create two projects in the workspace; one for the top-level ably-java project, and one for the core project.
 
-Interactive run/debug configurations for the java project can be created as follows:
+Interactive run/debug configurations for the core project can be created as follows:
 - select Run->Run configurations ...
 - create a new JUnit configuration
-- select the java project;
+- select the core project;
 - select the Class as RealtimeSuite or RestSuite;
 - select JUnit 4 as the test runner.
 
 #### Importing into Android studio
 
-Android studio does not include the components required to support development of the java project, it is not capable of importing the multi-level ably-java gradle project. It is possible to import the android project as a standalone project into Android Studio by deleting the top-level settings.gradle file, which effectively decouples the android and java projects.
+Android studio does not include the components required to support development of the core project, it is not capable of importing the multi-level ably-java gradle project. It is possible to import the core-android project as a standalone project into Android Studio by deleting the top-level settings.gradle file, which effectively decouples the core-android and core projects.
 
 This has been tested with Android Studio 3.0.1.
 
 To import into Android Studio:
 - do Import project (Gradle, Eclipse ADT, etc);
-- select ably-java/android/build.gradle;
+- select ably-java/core-android/build.gradle;
 - select OK to Gradle Sync.
 
-This creates a single android project and module.
+This creates a single core-android project and module.
 
 Configuration of Run/Debug configurations for running the unit tests on Android is the same as for IntelliJ IDEA (above).
 
@@ -186,9 +186,9 @@ but on Windows there is a batch file:
 Tests are based on JUnit, and there are separate suites for the REST and Realtime libraries, with gradle tasks
 for the JRE-specific library:
 
-    ./gradlew java:testRestSuite
+    ./gradlew core:testRestSuite
 
-    ./gradlew java:testRealtimeSuite
+    ./gradlew core:testRealtimeSuite
 
 To run tests against a specific host, specify in the environment:
 
@@ -199,12 +199,12 @@ Tests will run against the sandbox environment by default.
 Tests can be run on the Android-specific library. An Android device must be connected,
 either a real device or the Android emulator.
 
-    ./gradlew android:connectedAndroidTest
+    ./gradlew core-android:connectedAndroidTest
 
 We also have a small, fledgling set of unit tests which do not communicate with Ably's servers.
 The plan is to expand this collection of tests in due course:
 
-    ./gradlew java:runUnitTests
+    ./gradlew core:runUnitTests
 
 ### Interactive push tests
 
@@ -225,7 +225,7 @@ signing.keyId=XXXXXXXX
 signing.password=ably-debug-key
 signing.secretKeyRingFile=/Users/username/.ably/ably-java-secring.gpg
 ```
-- Run `./gradlew android:assembleRelease` or `./gradlew android:assembleDebug`.
+- Run `./gradlew core-android:assembleRelease` or `./gradlew core-android:assembleDebug`.
 
 ## Using `ably-java` / `ably-android` locally in other projects
 
@@ -262,7 +262,7 @@ This library uses [semantic versioning](http://semver.org/). For each release, t
 
 If you've not configured the signing key in your [Gradle properties](https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_configuration_properties) then release builds will complain:
 
-    Cannot perform signing task ':java:signArchives' because it has no configured signatory
+    Cannot perform signing task ':core:signArchives' because it has no configured signatory
 
 You need to [configure Signatory credentials](https://docs.gradle.org/current/userguide/signing_plugin.html#sec:signatory_credentials), for example via the `gradle.properties` file in your `GRADLE_USER_HOME` folder (usually `~/.gradle`).
 

README.md

@@ -15,6 +15,23 @@ Find out more:
 
 ---
 
+> [!NOTE]
+> **This branch carries the in-development 2.0 device/server package split.** The SDK is being
+> restructured into new artifacts that declare which side of the network they run on, so that
+> traffic classifies correctly on MAU-priced accounts:
+>
+> | Artifact | For | Entry point |
+> |----------|-----|-------------|
+> | `io.ably.pubsub:device` (aar) | Devices: Android apps and other end-user runtimes | `PubSubDevice.clientBuilder(...)` |
+> | `io.ably.pubsub:server` (jar) | Servers and other trusted backend environments | `PubSubServer.httpClientBuilder(...)` / `PubSubServer.realtimeClientBuilder(...)` |
+> | `io.ably.pubsub:core`, `io.ably.pubsub:core-android` | Internal implementation artifacts — do not depend on these directly | — |
+>
+> Nothing from this branch is published yet. The `io.ably:ably-java` and `io.ably:ably-android`
+> 1.x artifacts continue to work and will receive security and critical fixes from a maintenance
+> branch for one year after the 2.0 release. The installation instructions below still describe 1.x.
+
+---
+
 ## Getting started
 
 Everything you need to get started with Ably:

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
 }
 
@@ -30,6 +31,56 @@ subprojects {
     }
 }
 
+/*
+ * Release pre-flight: the split ships core, core-android, device and server in lockstep
+ * (one version, one run), so the set of published artifacts and their
+ * coordinates are asserted here and the release workflow fails before anything is
+ * uploaded if they drift. If you add or remove a published module, update this list
+ * deliberately.
+ */
+val expectedReleaseArtifacts = sortedSetOf(
+    "io.ably.pubsub:core:jar",
+    "io.ably.pubsub:core-android:aar",
+    "io.ably.pubsub:device:jar",
+    "io.ably.pubsub:server:jar",
+    "io.ably.pubsub:liveobjects:jar",
+    "io.ably.pubsub:pubsub-adapter:jar",
+    "io.ably.pubsub:network-client-core:jar",
+    "io.ably.pubsub:network-client-default:jar",
+    "io.ably.pubsub:network-client-okhttp:jar",
+)
+
+tasks.register("verifyReleaseArtifacts") {
+    description = "Asserts the published artifact set, group and lockstep version before a release."
+    doLast {
+        val rootVersion = project.property("VERSION_NAME") as String
+        val actual = sortedSetOf<String>()
+        subprojects.filter { it.pluginManager.hasPlugin("com.vanniktech.maven.publish") }.forEach { p ->
+            val artifactId = p.findProperty("POM_ARTIFACT_ID")
+                ?: error("${p.path} applies maven-publish but has no POM_ARTIFACT_ID")
+            val packaging = p.findProperty("POM_PACKAGING") ?: "jar"
+            // The version each module publishes at comes from its effective VERSION_NAME
+            // (a module-local gradle.properties can override the root's — exactly the
+            // lockstep drift this guards against).
+            val moduleVersion = p.findProperty("VERSION_NAME")
+            if (moduleVersion != rootVersion) {
+                error("Lockstep violation: ${p.path} has VERSION_NAME $moduleVersion, expected $rootVersion")
+            }
+            val group = p.findProperty("GROUP")
+            actual.add("$group:$artifactId:$packaging")
+        }
+        if (actual != expectedReleaseArtifacts) {
+            error(
+                "Published artifact set does not match the expected release set.\n" +
+                    "  expected: $expectedReleaseArtifacts\n" +
+                    "  actual:   $actual\n" +
+                    "If this change is deliberate, update expectedReleaseArtifacts in build.gradle.kts."
+            )
+        }
+        logger.lifecycle("Release pre-flight OK: ${actual.size} artifacts at $rootVersion: $actual")
+    }
+}
+
 configure(subprojects) {
     pluginManager.withPlugin("com.vanniktech.maven.publish") {
         extensions.configure<MavenPublishBaseExtension> {

core-android/gradle.properties

@@ -0,0 +1,4 @@
+POM_ARTIFACT_ID=core-android
+POM_NAME=Ably Pub/Sub core (Android)
+POM_DESCRIPTION=Internal implementation artifact for Ably's own Pub/Sub device/server packages. Not intended for direct use: depend on io.ably.pubsub:device instead.
+POM_PACKAGING=aar

android/src/main/java/io/ably/lib/push/ActivationContext.java → core-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 → core-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());
     }