[Split 2/3] Add io.ably.pubsub:device and :server door packages with side-declaring agents

[umair-ably]

Second PR in the PDR-091b split stack (stacked on #1232; diff shows only this PR's changes). Reference: ably-js#2293, whose packages/shared/side.ts contract this ports.

What this PR does

• io.ably.pubsub:server (jar → depends on :core): PubSubServer.httpClientBuilder(...) / PubSubServer.realtimeClientBuilder(...), per the door names agreed in PDR-091b2. Builders accept everything the core constructors accept (ClientOptions, API key string, token string — reusing the core's colon-rule disambiguation) and stamp the side at build().
• io.ably.pubsub:device (aar → depends on :core-android): PubSubDevice.clientBuilder(...) — one door, per PDR-091 (device-side connectionless ops stay available on the one client).
• Side-agent contract in a shared source dir (shared/, compiled into both door artifacts, not published — the Java analogue of ably-js's packages/shared/side.ts):
  • identifiers ably-pubsub-device / ably-pubsub-server, with the load-bearing-suffix warning comment (the -server suffix is what earns the MAU exemption on API-key auth);
  • caller agents entries preserved; the side entry is applied last and cannot be overridden; the caller's ClientOptions is never mutated; null passes through to the core's own initialization error.
  • The core keeps its ably-java/<version> base identifier — unchanged, already in the ably-common registry.
• Fixes ClientOptions.copy(), which silently dropped headers, fallbackHosts, transportParams and agents. The doors rely on copy() for non-mutating stamping; the pre-existing internal callers of copy() also benefit. Unit-tested.

Tests (what billing reads — they fail loudly)

• server: unit tests for stamping/preservation/override/no-mutation/null, plus a wire-level test that spins a local HTTP server and asserts the actual Ably-Agent header contains ably-pubsub-server/2.0.0 and ably-java/. Runs in check.yml via the existing unqualified runUnitTests invocation.
• device: instrumentation tests asserting the same contract, added to the emulate.yml matrix (:device:connectedAndroidTest).

Open items flagged for review

• ably-pubsub-device / ably-pubsub-server are not yet in the ably-common agents registry (checked protocol/agents.json on main, 2026-09-01) — needs an ably-common PR before any release; identifiers here match the ably-js branch exactly.
• Builder surface is deliberately minimal (no fluent option setters yet) pending sign-off on the door surface with the chat-kotlin owner.
• Both door artifacts bundle an identical io.ably.pubsub.internal.Side class — same pattern as the existing lib/ source shared between the two cores; harmless if both artifacts ever meet on a classpath.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added dedicated device and server SDK entry points for building authenticated REST and realtime clients.
  • Device and server clients now identify their SDK side in connection and request metadata.
  • Added published device and server library modules with streamlined builder APIs.

• Bug Fixes

  • Client option copies now retain headers, fallback hosts, transport settings, and agent information.
  • Caller-provided agent metadata is preserved while SDK-specific side identifiers are applied consistently.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: 4dd7b496-025f-44a1-8197-7445cf5c1c27

📥 Commits

Reviewing files that changed from the base of the PR and between d22cbf0 and 9642ca8.

📒 Files selected for processing (16)

• .github/workflows/emulate.yml
• device/build.gradle.kts
• device/gradle.properties
• device/src/androidTest/java/io/ably/pubsub/device/PubSubDeviceTest.java
• device/src/main/java/io/ably/pubsub/device/PubSubDevice.java
• lib/src/main/java/io/ably/lib/transport/Defaults.java
• lib/src/main/java/io/ably/lib/types/ClientOptions.java
• lib/src/test/java/io/ably/lib/test/realtime/RealtimeHttpHeaderTest.java
• lib/src/test/java/io/ably/lib/types/ClientOptionsTest.java
• pubsub-adapter/src/test/kotlin/com/ably/pubsub/SdkWrapperAgentHeaderTest.kt
• server/build.gradle.kts
• server/gradle.properties
• server/src/main/java/io/ably/pubsub/server/PubSubServer.java
• server/src/test/java/io/ably/pubsub/server/PubSubServerTest.java
• settings.gradle.kts
• shared/src/main/java/io/ably/pubsub/internal/Side.java

Disabled knowledge base sources:

• Jira integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

Walkthrough

The change adds device and server SDK modules, side-specific agent stamping, shared option handling, publication metadata, tests, and Gradle integration. The base agent identifier changes from ably-java to ably-pubsub-java.

Changes

SDK entry points and agent stamping

Layer / File(s)	Summary
Agent identity and option propagation lib/src/main/java/..., shared/src/main/java/..., lib/src/test/..., pubsub-adapter/src/test/...	The base agent identifier changes to ably-pubsub-java. ClientOptions.copy() retains additional option fields. Side stamps device or server agents while preserving caller agents and the original options.
Server SDK builders and validation server/build.gradle.kts, server/gradle.properties, server/src/main/java/..., server/src/test/...	The server module adds publication metadata, HTTP and realtime builders, credential handling, server-agent stamping, and tests for construction and wire headers.
Device SDK builder and instrumentation device/build.gradle.kts, device/gradle.properties, device/src/main/java/..., device/src/androidTest/...	The device module adds Android configuration, publication metadata, a realtime builder, device-agent stamping, and instrumented tests.
Module registration and emulator coverage settings.gradle.kts, .github/workflows/emulate.yml	The Gradle build registers the new modules. The emulator workflow runs :device:connectedAndroidTest in addition to the existing Android test task.

Estimated code review effort: 4 (Complex) | ~45 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant PubSubServer
  participant Side
  participant AblyRealtime
  Caller->>PubSubServer: provide options or key/token
  PubSubServer->>Side: resolve and stamp server agent
  Side-->>PubSubServer: return stamped options
  PubSubServer->>AblyRealtime: construct realtime client
  AblyRealtime-->>Caller: return client

Loading

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch integration/split-2-door-packages

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{A rabbit reads each line,
The patch grows clear beneath the moon,
Small changes hop in place,
Tests guard the garden path,
Reviews bloom before the dawn.}

_{Comment @coderabbitai help to get the list of available commands.}

[umair-ably]

Updated for ably/ably-common#361, mirroring ably/ably-js#2297: the side-declaring agent entries are now versionless flags — bare tokens on the wire, like browser — with identity/version continuing to travel on the SDK's own ably-java/<version> entry:

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

Unlike ably-js (which needed a getAgentString fix for name/undefined), our AgentHeaderCreator already emits a null-valued map entry as a bare token, so no core change was needed — the doors stamp null and drop their BuildConfig version plumbing. Tests now assert the flag appears as a bare token and fail if any /version form regresses, and that each side's client doesn't carry the other side's flag.

[umair-ably]

Added the family-identifier half of the agent convention (mirrors ably-js#2297): Defaults.ABLY_AGENT_VERSION now stamps ably-pubsub-java/<version>, with the four identifier assertions updated (RealtimeHttpHeaderTest canary, PubSubServerTest, Side javadoc). Verified locally: :server:test and :core:test --tests '*RealtimeHttpHeader*' pass on JDK 17. Registry entries for both the family identifier and the versionless side flags are in ably-common#361, which should merge before any release from this branch.