Skip to content

Commit b874a86

Browse files
authored
Merge pull request #1256 from ably/integration/v2-review-fixes
Address integration/v2 review findings: server-leg UTS conformance, migration guide, door options
2 parents ce61a1b + 25a3f80 commit b874a86

36 files changed

Lines changed: 1444 additions & 479 deletions

File tree

‎.claude/skills/uts-to-kotlin/SKILL.md‎

Lines changed: 47 additions & 47 deletions
Large diffs are not rendered by default.

‎.claude/skills/uts-to-kotlin/references/objects-mapping.md‎

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -41,12 +41,12 @@ different things**, and a third *internal* layer underneath. Keep them straight:
4141

4242
| Layer | Spec name | ably-js | ably-java | Package |
4343
|---|---|---|---|---|
44-
| **Creation value type** — immutable blueprint you pass *into* `set` | `LiveMap` / `LiveCounter` (the `RTLMV*` / `RTLCV*` classes) | `LiveMap.create()` / `LiveCounter.create()` | `LiveMap` / `LiveCounter` | `io.ably.lib.liveobjects.value` |
45-
| **Public read/write view** — what you navigate & subscribe on | `PathObject`, `Instance` | `PathObject`, `Instance` | typed hierarchy (§4, §5) | base in `io.ably.lib.liveobjects.path` / `.instance`; **typed subtypes in `.path.types` / `.instance.types`** |
46-
| **Internal graph object** — the live CRDT node | `InternalLiveMap` / `InternalLiveCounter` (`RTLM*` / `RTLC*`), `ObjectsPool` | internal | `InternalLiveMap` / `InternalLiveCounter` / `ObjectsPool` — **same names as the spec** (`internal` classes, `:liveobjects` module) | `io.ably.lib.liveobjects[.value.livemap/.value.livecounter]` — not public; access rules §13, full symbol map §17 |
44+
| **Creation value type** — immutable blueprint you pass *into* `set` | `LiveMap` / `LiveCounter` (the `RTLMV*` / `RTLCV*` classes) | `LiveMap.create()` / `LiveCounter.create()` | `LiveMap` / `LiveCounter` | `io.ably.pubsub.liveobjects.value` |
45+
| **Public read/write view** — what you navigate & subscribe on | `PathObject`, `Instance` | `PathObject`, `Instance` | typed hierarchy (§4, §5) | base in `io.ably.pubsub.liveobjects.path` / `.instance`; **typed subtypes in `.path.types` / `.instance.types`** |
46+
| **Internal graph object** — the live CRDT node | `InternalLiveMap` / `InternalLiveCounter` (`RTLM*` / `RTLC*`), `ObjectsPool` | internal | `InternalLiveMap` / `InternalLiveCounter` / `ObjectsPool` — **same names as the spec** (`internal` classes, `:liveobjects` module) | `io.ably.pubsub.liveobjects[.value.livemap/.value.livecounter]` — not public; access rules §13, full symbol map §17 |
4747

4848
So when a spec says `counter = LiveCounter.create(5)` and passes it to `set`, that's the **value type**
49-
(`io.ably.lib.liveobjects.value.LiveCounter`). When a spec says "the resolved value is an
49+
(`io.ably.pubsub.liveobjects.value.LiveCounter`). When a spec says "the resolved value is an
5050
`InternalLiveCounter` with `.data == 5`", that's the **internal graph node** (§13). When a spec navigates
5151
`root.get("counter").value()`, that's the **public view** (`PathObject`).
5252

@@ -97,10 +97,10 @@ In the spec/ably-js a `PathObject` is polymorphic: `get`, `at`, `value`, `set`,
9797
all hang off the one object. In ably-java the base `PathObject` exposes **only** the type-agnostic methods;
9898
everything type-specific is moved onto a sub-interface you reach via an `as*` cast.
9999

100-
**Base `PathObject`** (`io.ably.lib.liveobjects.path.PathObject`) — always available. The typed sub-types
100+
**Base `PathObject`** (`io.ably.pubsub.liveobjects.path.PathObject`) — always available. The typed sub-types
101101
returned by the `as*` casts (`LiveMapPathObject`, `LiveCounterPathObject`, `NumberPathObject`,
102102
`StringPathObject`, `BooleanPathObject`, `BinaryPathObject`, `JsonObjectPathObject`, `JsonArrayPathObject`)
103-
live in **`io.ably.lib.liveobjects.path.types`** (not `.path`) — import them from there.
103+
live in **`io.ably.pubsub.liveobjects.path.types`** (not `.path`) — import them from there.
104104

105105
| Spec / ably-js | ably-java |
106106
|---|---|
@@ -207,7 +207,7 @@ Same partition as `PathObject`, with two differences: the base is **abstract / n
207207
directly (`RTTS7e`), and the casts **throw** on mismatch instead of degrading (`RTTS9d`) — because an
208208
`Instance` wraps an already-resolved value of known type.
209209

210-
**Base `Instance`** (`io.ably.lib.liveobjects.instance.Instance`):
210+
**Base `Instance`** (`io.ably.pubsub.liveobjects.instance.Instance`):
211211

212212
| Spec / ably-js | ably-java |
213213
|---|---|
@@ -254,7 +254,7 @@ immutable creation value types.
254254

255255
| Spec / ably-js | ably-java |
256256
|---|---|
257-
| `LiveCounter.create()` | `LiveCounter.create(): LiveCounter` (`io.ably.lib.liveobjects.value`) |
257+
| `LiveCounter.create()` | `LiveCounter.create(): LiveCounter` (`io.ably.pubsub.liveobjects.value`) |
258258
| `LiveCounter.create(5)` | `LiveCounter.create(5)` (arg is `Number`) |
259259
| `LiveMap.create()` | `LiveMap.create(): LiveMap` |
260260
| `LiveMap.create({ a: 1, b: "x" })` | `LiveMap.create(mapOf("a" to LiveMapValue.of(1), "b" to LiveMapValue.of("x")))` — entries are `Map<String, LiveMapValue>` |
@@ -370,13 +370,13 @@ depth (`RTPO19c1`).
370370
| remove all | `` channel.`object`.offAll() `` |
371371

372372
Listener: `ObjectStateChange.Listener.onStateChanged(ObjectStateEvent)`. Enum `ObjectStateEvent { SYNCING,
373-
SYNCED }` (`io.ably.lib.liveobjects.state`).
373+
SYNCED }` (`io.ably.pubsub.liveobjects.state`).
374374

375375
---
376376

377377
## 10. `ValueType` & type discrimination <a id="10-valuetype"></a>
378378

379-
ably-js uses string-literal type tags; ably-java has an enum `io.ably.lib.liveobjects.ValueType`:
379+
ably-js uses string-literal type tags; ably-java has an enum `io.ably.pubsub.liveobjects.ValueType`:
380380

381381
| Spec value category | `ValueType` |
382382
|---|---|
@@ -394,7 +394,7 @@ non-null. Use `getType()` for "what is it" assertions and the matching `as*` cas
394394

395395
The spec's `PublicAPI::ObjectMessage` / `PublicAPI::ObjectOperation` (the `PAOM*` / `PAOOP*` types,
396396
delivered to subscription listeners) map to ably-java interfaces with getters (package
397-
`io.ably.lib.liveobjects.message`). The `PublicAPI::` prefix is dropped — ably-java exposes them as
397+
`io.ably.pubsub.liveobjects.message`). The `PublicAPI::` prefix is dropped — ably-java exposes them as
398398
`ObjectMessage` / `ObjectOperation`.
399399

400400
> **Getter-only, no *public* constructor — use the `buildPublicObjectMessage` helper.** In normal use you
@@ -520,10 +520,10 @@ Several **unit** specs assert on the **internal CRDT graph**, not the public API
520520
that is otherwise `internal`. Build the source with the op builders and assert the public getters (§11).
521521

522522
In ably-java these are **not public**. They live in the `:liveobjects` module as `Internal*` / `Default*` / `Wire*` /
523-
`ResolvedValue` / `Leaf` / `MapRef` / `CounterRef` classes (package `io.ably.lib.liveobjects.*`,
523+
`ResolvedValue` / `Leaf` / `MapRef` / `CounterRef` classes (package `io.ably.pubsub.liveobjects.*`,
524524
implementation source set), visible only to that module's own tests. Because of this, **all objects tiers
525525
translate into `:liveobjects`'s own test source set** —
526-
`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/{unit,integration,proxy}/` — so the unit tier
526+
`liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/{unit,integration,proxy}/` — so the unit tier
527527
sees module internals directly, and the integration/proxy tiers reach the plugin through the same module.
528528
Consequences when translating:
529529

@@ -548,8 +548,8 @@ Consequences when translating:
548548

549549
Every objects unit spec opens with `setup_synced_channel` and constructs protocol/object messages with the
550550
`build_*` helpers. These are implemented in
551-
`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/unit/Helpers.kt` (package
552-
`io.ably.lib.liveobjects.uts.unit`; transport bootstrap via the shared `io.ably.lib.uts.infra.*` infra helpers,
551+
`liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/unit/Helpers.kt` (package
552+
`io.ably.pubsub.liveobjects.uts.unit`; transport bootstrap via the shared `io.ably.pubsub.uts.infra.*` infra helpers,
553553
message construction via the typed `Wire*` DTOs — §17.10) — **call them; don't hand-roll the mock setup or
554554
message wire forms.**
555555

@@ -599,8 +599,8 @@ wire `action` / `semantics` are integer enum codes — the builders emit the cod
599599
Some objects **integration** specs (tier `integration/standard`) seed object state over REST *before* the
600600
realtime client connects, via the spec's `## REST Fixture Provisioning` helper `provision_objects_via_rest`.
601601
Its ably-java translation lives in
602-
`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/integration/Helpers.kt` (package
603-
`io.ably.lib.liveobjects.uts.integration`) — **call it; don't hand-roll the REST request or payload
602+
`liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/integration/Helpers.kt` (package
603+
`io.ably.pubsub.liveobjects.uts.integration`) — **call it; don't hand-roll the REST request or payload
604604
JSON.** (Currently only `objects/integration/RTPO15` uses it.) It lives inside `:liveobjects`'s own tests
605605
now (like the whole objects suite), but still uses only the public `AblyRest` — the "public API only for
606606
REST provisioning" convention survives even though the module's internals are visible.
@@ -711,8 +711,8 @@ This section maps the **5 internal-graph unit specs** — `internal_live_counter
711711
internal CRDT state, so they cannot translate against the public API — background in
712712
`JAVA_LIVEOBJECTS_INTERNAL_METHODS_ACCESS_REPORT.md` at the repo root) — onto the internal engine.
713713
Like the rest of the objects suite, they go into
714-
**`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/unit/`** (package
715-
`io.ably.lib.liveobjects.uts.unit`, task `:liveobjects:runLiveObjectsUnitTests`), where the test
714+
**`liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/unit/`** (package
715+
`io.ably.pubsub.liveobjects.uts.unit`, task `:liveobjects:runLiveObjectsUnitTests`), where the test
716716
compilation is associated with `main`, so every `internal` declaration is directly visible — no
717717
reflection.
718718

@@ -726,7 +726,7 @@ reflection.
726726

727727
The internal classes have `private constructor`s; each pairs with an `internal` companion factory that
728728
needs a `DefaultRealtimeObject`. Build one from the mocked adapter (helper already exists in
729-
`liveobjects/src/test/kotlin/io/ably/lib/liveobjects/unit/TestHelpers.kt`):
729+
`liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/unit/TestHelpers.kt`):
730730

731731
```kotlin
732732
val ro = DefaultRealtimeObject("test", getMockAblyClientAdapter())

‎.claude/skills/uts-to-kotlin/scripts/resolve_uts.py‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,10 +34,10 @@
3434
SKILL_DIR = Path(__file__).resolve().parent.parent
3535
MAPPING = SKILL_DIR / "uts-package-mapping.json"
3636
TIERS = ("unit", "integration", "proxy")
37-
# Owning Gradle module, keyed by a target dir's first path segment. The `lib` -> `:java`
38-
# pair is the load-bearing non-obvious mapping (the `:java` module's build file wires
37+
# Owning Gradle module, keyed by a target dir's first path segment. The `lib` -> `:core`
38+
# pair is the load-bearing non-obvious mapping (the `:core` module's build file wires
3939
# `../lib/src/...` srcDirs).
40-
MODULE_BY_PREFIX = {"lib": ":java", "liveobjects": ":liveobjects", "uts": ":uts"}
40+
MODULE_BY_PREFIX = {"lib": ":core", "liveobjects": ":liveobjects", "uts": ":uts"}
4141

4242

4343
def fail(code, message):
@@ -95,7 +95,7 @@ def main():
9595
"--create",
9696
metavar="NAME",
9797
help="add a mapping for this source module using NAME as the ably-java "
98-
"module base name, then resolve. Scaffolds full lib/-rooted (:java) paths "
98+
"module base name, then resolve. Scaffolds full lib/-rooted (:core) paths "
9999
"only — a module whose tiers live in another Gradle module (like objects "
100100
"-> :liveobjects) still needs a hand-edit afterwards.",
101101
)
@@ -131,10 +131,10 @@ def main():
131131
f"--create target {target!r} must be a simple module base name "
132132
f"(letters/digits/underscore, e.g. 'liveobjects') so it forms a "
133133
f"valid path and Kotlin package.")
134-
# Full repo-root-relative paths using the realtime/`lib` (:java) template.
134+
# Full repo-root-relative paths using the realtime/`lib` (:core) template.
135135
# A module whose tiers live in another Gradle module (like objects ->
136-
# :liveobjects) still needs a hand-edit — --create only scaffolds :java-hosted modules.
137-
base = "lib/src/test/kotlin/io/ably/lib/uts"
136+
# :liveobjects) still needs a hand-edit — --create only scaffolds :core-hosted modules.
137+
base = "lib/src/test/kotlin/io/ably/pubsub/uts"
138138
new_entry = {
139139
"unit": f"{base}/unit/{target}",
140140
"integration": f"{base}/integration/standard/{target}",
Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
{
2-
"_comment": "Maps each UTS spec module (a dir under specification/uts/) to its target test directory per tier. Each tier value is ONE repo-root-relative path (never machine-absolute); the Kotlin package is the path after 'src/test/kotlin/' with '/' -> '.'; the owning Gradle module is the path's first segment (lib/ -> :java, liveobjects/ -> :liveobjects, uts/ -> :uts). Every tier path MUST keep a module segment after the tier (e.g. 'unit/realtime', never bare 'unit') so a derived package can never collide with a :uts smoke package (io.ably.lib.uts.unit / .integration.standard / .integration.proxy) — an invariant currently held only by construction. An optional 'notes' field points (relative to this skill dir) to a per-module ably-js -> ably-java translation reference, read before translating that module. Used by the uts-to-kotlin skill (scripts/resolve_uts.py).",
2+
"_comment": "Maps each UTS spec module (a dir under specification/uts/) to its target test directory per tier. Each tier value is ONE repo-root-relative path (never machine-absolute); the Kotlin package is the path after 'src/test/kotlin/' with '/' -> '.'; the owning Gradle module is the path's first segment (lib/ -> :core, liveobjects/ -> :liveobjects, uts/ -> :uts). Every tier path MUST keep a module segment after the tier (e.g. 'unit/realtime', never bare 'unit') so a derived package can never collide with a :uts smoke package (io.ably.pubsub.uts.unit / .integration.standard / .integration.proxy) — an invariant currently held only by construction. An optional 'notes' field points (relative to this skill dir) to a per-module ably-js -> ably-java translation reference, read before translating that module. Used by the uts-to-kotlin skill (scripts/resolve_uts.py).",
33
"packages": {
44
"realtime": {
5-
"unit": "lib/src/test/kotlin/io/ably/lib/uts/unit/realtime",
6-
"integration": "lib/src/test/kotlin/io/ably/lib/uts/integration/standard/realtime",
7-
"proxy": "lib/src/test/kotlin/io/ably/lib/uts/integration/proxy/realtime"
5+
"unit": "lib/src/test/kotlin/io/ably/pubsub/uts/unit/realtime",
6+
"integration": "lib/src/test/kotlin/io/ably/pubsub/uts/integration/standard/realtime",
7+
"proxy": "lib/src/test/kotlin/io/ably/pubsub/uts/integration/proxy/realtime"
88
},
99
"objects": {
10-
"unit": "liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/unit",
11-
"integration": "liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/integration",
12-
"proxy": "liveobjects/src/test/kotlin/io/ably/lib/liveobjects/uts/proxy",
10+
"unit": "liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/unit",
11+
"integration": "liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/integration",
12+
"proxy": "liveobjects/src/test/kotlin/io/ably/pubsub/liveobjects/uts/proxy",
1313
"notes": "references/objects-mapping.md"
1414
},
1515
"rest": {
16-
"unit": "lib/src/test/kotlin/io/ably/lib/uts/unit/rest",
17-
"integration": "lib/src/test/kotlin/io/ably/lib/uts/integration/standard/rest",
18-
"proxy": "lib/src/test/kotlin/io/ably/lib/uts/integration/proxy/rest"
16+
"unit": "lib/src/test/kotlin/io/ably/pubsub/uts/unit/rest",
17+
"integration": "lib/src/test/kotlin/io/ably/pubsub/uts/integration/standard/rest",
18+
"proxy": "lib/src/test/kotlin/io/ably/pubsub/uts/integration/proxy/rest"
1919
}
2020
}
2121
}

‎.github/workflows/check.yml‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,12 @@ jobs:
2828
# A second UTS leg through the server door's builders (see the uts.side handling in
2929
# uts/.../ClientFactories.kt): the builders stamp a side-declaring agent entry and pass
3030
# everything else through, so conformance must be identical on both legs; SideModesTest
31-
# fails a leg whose stamp does not match. There is no device leg on the JVM — the device
32-
# door is an Android artifact, covered by the instrumentation tests in emulate.yml.
33-
- run: ./gradlew :uts:runUtsUnitTests -Duts.side=server
31+
# fails a leg whose stamp does not match. The leg covers every module whose UTS specs
32+
# build clients through the factories: :core and :liveobjects (plus the :uts self-tests).
33+
# There is no device leg on the JVM — the device door is not wired into the factories' seam;
34+
# its stamping contract is covered by the device module's own tests (jvmTest and the
35+
# instrumentation tests in emulate.yml).
36+
- run: ./gradlew :core:runUtsUnitTests :uts:runUtsUnitTests :liveobjects:runLiveObjectsUnitTests -Duts.side=server
3437

3538
# Continuously proves the release pre-flight and that every published module
3639
# builds a publishable artifact set, so version/coordinate regressions surface

‎.github/workflows/emulate.yml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ jobs:
1414
strategy:
1515
fail-fast: false
1616
matrix:
17+
# core-android declares minSdk 19, but API 19-23 (and the HttpURLConnection network engine
18+
# used there, -PhttpURLConnection) are not covered by this emulator matrix.
1719
android-api-level: [ 24, 29, 35 ]
1820

1921
steps:
@@ -50,7 +52,7 @@ jobs:
5052
arch: ${{ steps.get-avd-arch.outputs.arch }}
5153
target: default
5254
# Print emulator logs if tests fail
53-
script: ./gradlew :core-android:connectedAndroidTest :device:connectedAndroidTest ${{ matrix.android-api-level == 19 && '-PhttpURLConnection' || '' }} || (adb logcat -d System.out:I && exit 1)
55+
script: ./gradlew :core-android:connectedAndroidTest :device:connectedAndroidTest || (adb logcat -d System.out:I && exit 1)
5456

5557
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
5658
if: always()

‎.github/workflows/integration-test.yml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -146,5 +146,6 @@ jobs:
146146
- run: ./gradlew :core:runUtsIntegrationTests :uts:runUtsIntegrationTests
147147

148148
# A second leg through the server door's builders — see the uts.side handling in
149-
# uts/.../ClientFactories.kt and the matching leg in check.yml.
150-
- run: ./gradlew :uts:runUtsIntegrationTests -Duts.side=server
149+
# uts/.../ClientFactories.kt and the matching leg in check.yml. The :liveobjects run is
150+
# narrowed to its UTS specs (the module's own integration tests do not use the factories).
151+
- run: ./gradlew :core:runUtsIntegrationTests :uts:runUtsIntegrationTests :liveobjects:runLiveObjectsIntegrationTests --tests 'io.ably.pubsub.liveobjects.uts.*' -Duts.side=server

0 commit comments

Comments
 (0)