Skip to content

Commit b4edf61

Browse files
authored
Merge pull request #1226 from ably/fix/liveobjects-failing-uts-tests
[AIT-1103] fix(liveobjects): Fix UTS unit tests
2 parents ce72a7d + 5934d80 commit b4edf61

27 files changed

Lines changed: 1304 additions & 1173 deletions

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

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -104,7 +104,7 @@ live in **`io.ably.lib.liveobjects.path.types`** (not `.path`) — import them f
104104
| Spec / ably-js | ably-java |
105105
|---|---|
106106
| `pathObj.path()` | `pathObj.path(): String` |
107-
| `pathObj.instance()` | `pathObj.instance(): Instance?` (null if path resolves to a primitive, or doesn't resolve) |
107+
| `pathObj.instance()` | `pathObj.instance(): Instance?` (wraps any resolved value incl. primitives per `RTPO8f`; null only when the path doesn't resolve) |
108108
| `pathObj.compactJson()` | `pathObj.compactJson(): JsonElement?` |
109109
| `pathObj.compact()` | **Not implemented in ably-java** (`RTTS3f`: typed SDKs need not implement `compact`). Use `compactJson()` for snapshot assertions; if a spec genuinely needs the non-JSON `compact()` shape, that's a deviation — flag it. |
110110
| `pathObj.subscribe(listener[, opts])` | `pathObj.subscribe(PathObjectListener[, PathObjectSubscriptionOptions]): Subscription` (§8) |
@@ -473,7 +473,8 @@ Spec assertions like `FAILS WITH error code 92007` map to ably-java exceptions:
473473
| write where path doesn't resolve | `AblyException` 400 / code `92005` |
474474
| write where value isn't the required type | `AblyException` 400 / code `92007` |
475475
| `get()` / op when channel lacks the object mode (`RTO23a`/`RTO2a2`) | `AblyException` 400 / code `40024` |
476-
| `get()` / access when channel is DETACHED or FAILED (`RTO23b`/`RTO25`) | `AblyException` 400 / code `90001` |
476+
| access methods (`on`/`off`/`offAll`) when channel is DETACHED or FAILED (`RTO25b`) | `AblyException` 400 / code `90001` |
477+
| `get()` when channel is FAILED (`RTO23e`/`RTL33c`) | `AblyException` 400 / code `90001`. **But `get()` on a DETACHED channel does *not* throw** — ensure-active-channel re-attaches and `get()` resolves (`RTO23e`/`RTL33b`); only the access methods above gate on DETACHED |
477478
| channel enters DETACHED/SUSPENDED/FAILED while awaiting SYNCED (`RTO20e`/`RTO23c`) | `AblyException` 400 / code `92008` |
478479
| write while `echoMessages` is false (`RTO26c`) | `AblyException` 400 / code `40000` |
479480

@@ -554,15 +555,14 @@ setup or message JSON.**
554555
| `build_public_object_message(msg, channel)` | `buildPublicObjectMessage(wireJson, channel)` (reflective; §11) |
555556
| `STANDARD_POOL_OBJECTS` | `STANDARD_POOL_OBJECTS` |
556557
| inline ObjectData / map-entry / state fragments | `dataString` / `dataNumber` / `dataBoolean` / `dataObjectId` / `dataBytes` / `dataJson`, `mapEntry`, `mapState`, `counterState`, `mapCreateOp`, `counterCreateOp` |
558+
| Canonical Constants: `POOL_SERIAL`, `ack_serial(m, i)`, `remote_serial(i)`, `below_ack_serial(i)` | `POOL_SERIAL` (`"t:0"`), `ackSerial(msgSerial, i)`, `remoteSerial(i)`, `belowAckSerial(i)` — use these, never hand-rolled `"t:N"` literals (serials are compared as strings, so ad-hoc values silently sort wrong) |
557559

558560
`mock_ws.send_to_client(...)` is the existing `mockWs.sendToClient(...)` (§ mock API in the main skill). The
559561
wire `action` / `semantics` are integer enum codes — the builders emit the codes for you.
560562

561-
> **Runtime caveat:** `setupSyncedChannel` returns only once `RealtimeObject.get()` resolves, which needs
562-
> the `:liveobjects` SDK's OBJECT_SYNC processing. Until that lands the helpers **compile** and the test
563-
> structure is correct, but the setup throws at runtime — i.e. translate-only today, runnable once the SDK
564-
> is implemented. (`buildPublicObjectMessage` does *not* depend on this — the message/operation layer is
565-
> implemented, so those tests can run now.)
563+
> **Runtime status:** the `:liveobjects` SDK's OBJECT_SYNC processing and `RealtimeObject.get()` are
564+
> implemented — `setupSyncedChannel` and the full objects unit suite run green, so translate **and
565+
> evaluate** (don't stop at compile-only).
566566
567567
(For the **integration** tier's REST fixture helper — `provision_objects_via_rest` — see §14.)
568568

@@ -600,8 +600,8 @@ reflection and no `:liveobjects` dependency — it compiles and runs against `:j
600600
> (`sandbox.realtime.ably-nonprod.net`) — the same nonprod host `SandboxApp` and the realtime clients use,
601601
> **not** `environment="sandbox"` (which resolves to the legacy `sandbox-rest.ably.io`, and
602602
> can't be combined with `restHost` per `Hosts.java` TO3k2/TO3k3). The REST call hits the live sandbox
603-
> today; the realtime client it provisions for only *observes* the data once the SDK's OBJECT_SYNC +
604-
> `RealtimeObject.get()` land.
603+
> today, and the realtime client observes the provisioned data through the SDK's OBJECT_SYNC +
604+
> `RealtimeObject.get()` (both implemented).
605605
606606
---
607607

‎lib/src/main/java/io/ably/lib/liveobjects/path/PathObject.java‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,16 +79,14 @@ public interface PathObject {
7979
@NotNull String path();
8080

8181
/**
82-
* Resolves this path and returns a {@link Instance} wrapping the underlying
83-
* value if it is a {@code LiveMap} or {@code LiveCounter}.
82+
* Resolves this path and returns a {@link Instance} wrapping the resolved value,
83+
* whether it is a {@code LiveMap}, {@code LiveCounter} or a primitive (RTPO8c/RTPO8f).
8484
*
85-
* <p>Returns {@code null} when the resolved value is a primitive (LiveObjects with
86-
* no object id), when the path does not resolve, or when called on primitive
87-
* {@code *PathObject} sub-types.
85+
* <p>Returns {@code null} when the path does not resolve (RTPO8e).
8886
*
8987
* <p>Spec: RTPO8 / RTTS3b
9088
*
91-
* @return a {@link Instance} wrapping the resolved live object, or {@code null}
89+
* @return a {@link Instance} wrapping the resolved value, or {@code null}
9290
*/
9391
@Nullable Instance instance();
9492

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/BinaryPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
* A {@link PathObject} whose underlying value is expected to be a binary blob
88
* (a {@code byte[]}).
99
*
10-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
11-
* because a primitive resolution does not produce a wrapped LiveObject; navigation
10+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
11+
* wrapping the resolved primitive value per RTPO8f; navigation
1212
* via {@code at(...)} is not available here because it is only defined on
1313
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1414
* useful here.

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/BooleanPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
/**
77
* A {@link PathObject} whose underlying value is expected to be a {@code Boolean}.
88
*
9-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
10-
* because a primitive resolution does not produce a wrapped LiveObject; navigation
9+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
10+
* wrapping the resolved primitive value per RTPO8f; navigation
1111
* via {@code at(...)} is not available here because it is only defined on
1212
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1313
* useful here.

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/JsonArrayPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
/**
88
* A {@link PathObject} whose underlying value is expected to be a {@link JsonArray}.
99
*
10-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
11-
* because this resolution does not produce a wrapped LiveObject instance; navigation
10+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
11+
* wrapping the resolved primitive value per RTPO8f; navigation
1212
* via {@code at(...)} is not available here because it is only defined on
1313
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1414
* useful here.

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/JsonObjectPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
/**
88
* A {@link PathObject} whose underlying value is expected to be a {@link JsonObject}.
99
*
10-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
11-
* because this resolution does not produce a wrapped LiveObject instance; navigation
10+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
11+
* wrapping the resolved primitive value per RTPO8f; navigation
1212
* via {@code at(...)} is not available here because it is only defined on
1313
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1414
* useful here.

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/NumberPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
/**
77
* A {@link PathObject} whose underlying value is expected to be a {@code Number}.
88
*
9-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
10-
* because a primitive resolution does not produce a wrapped LiveObject; navigation
9+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
10+
* wrapping the resolved primitive value per RTPO8f; navigation
1111
* via {@code at(...)} is not available here because it is only defined on
1212
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1313
* useful here.

‎lib/src/main/java/io/ably/lib/liveobjects/path/types/StringPathObject.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,8 +6,8 @@
66
/**
77
* A {@link PathObject} whose underlying value is expected to be a {@code String}.
88
*
9-
* <p>This is a terminal type. {@link PathObject#instance()} returns {@code null}
10-
* because a primitive resolution does not produce a wrapped LiveObject; navigation
9+
* <p>This is a terminal type. {@link PathObject#instance()} returns an {@code Instance}
10+
* wrapping the resolved primitive value per RTPO8f; navigation
1111
* via {@code at(...)} is not available here because it is only defined on
1212
* {@code LiveMapPathObject}. Only {@link #value()} and the inherited read APIs are
1313
* useful here.

‎liveobjects/src/main/kotlin/io/ably/lib/liveobjects/DefaultRealtimeObject.kt‎

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,12 @@ internal class DefaultRealtimeObject(
4242
*/
4343
internal val objectsPool = ObjectsPool(this)
4444

45+
// Non-volatile by design: written and read only on [sequentialScope].
4546
internal var state = ObjectsState.Initialized
4647

4748
/**
4849
* Set of serials for operations applied locally upon ACK, awaiting deduplication of the server echo.
50+
* Unsynchronized: accessed only on [sequentialScope].
4951
* @spec RTO7b, RTO7b1
5052
*/
5153
internal val appliedOnAckSerials = mutableSetOf<String>()
@@ -62,7 +64,12 @@ internal class DefaultRealtimeObject(
6264
internal val pathObjectSubscriptionRegister = PathObjectSubscriptionRegister(this)
6365

6466
/**
65-
* Coroutine scope for running sequential operations on a single thread, used to avoid concurrency issues.
67+
* Coroutine scope running all objects work one task at a time. `limitedParallelism(1)` is a view
68+
* over the shared Default pool - no dedicated thread is created or blocked, and the single slot is
69+
* released at every suspension point (e.g. while awaiting a publish ACK). It is the safety contract
70+
* for the unsynchronized state in this class and in ObjectsManager/ObjectsStateCoordinator
71+
* (e.g. [state], [appliedOnAckSerials], pendingSyncWaiters), and its FIFO order preserves
72+
* submission-order publishing for un-awaited mutations.
6673
*/
6774
private val sequentialScope =
6875
CoroutineScope(Dispatchers.Default.limitedParallelism(1) + CoroutineName(channelName) + SupervisorJob())
@@ -81,6 +88,16 @@ internal class DefaultRealtimeObject(
8188
/**
8289
* Runs [block] on the sequential scope and exposes it as a CompletableFuture. Failures
8390
* complete the future exceptionally with the original AblyException.
91+
*
92+
* Deliberately kept on [sequentialScope] rather than a parallel dispatcher, at no performance
93+
* cost: blocks suspend almost immediately on network I/O (releasing the slot), so only
94+
* microseconds of CPU work per operation are serialized, and all publishes funnel into the
95+
* single connection anyway. In return the FIFO order keeps un-awaited back-to-back mutations
96+
* publishing in submission order (deterministic LWW outcomes), [dispose] can cancel in-flight
97+
* operations via this scope's children, and [get]'s sync wait stays race-free (see [get]).
98+
*
99+
* Caveat: the returned future completes on this scope, so synchronous dependents (thenApply etc.)
100+
* run on the lane - a blocking callback there stalls objects processing for the channel.
84101
*/
85102
internal fun <T> asyncFuture(block: suspend () -> T): CompletableFuture<T> =
86103
sequentialScope.future { block() }
@@ -93,7 +110,11 @@ internal class DefaultRealtimeObject(
93110
asyncFuture(block).thenApply { null }
94111

95112
override fun get(): CompletableFuture<LiveMapPathObject> {
96-
throwIfInvalidAccessApiConfiguration() // RTO23a
113+
// RTO23a - get() checks only the object_subscribe MODE here;
114+
throwIfMissingObjectSubscribeMode()
115+
// MUST run on sequentialScope: ensureSynced()'s state check + SYNCED-listener registration is
116+
// atomic only there (SYNCED transitions run on the same scope). On a parallel dispatcher the
117+
// SYNCED event could fire between the two and this future would hang forever (lost wakeup).
97118
return asyncFuture { getRootAsync() }
98119
}
99120

@@ -179,7 +200,10 @@ internal class DefaultRealtimeObject(
179200
}
180201
if (syntheticMessages.isEmpty()) return
181202

182-
// RTO20e, RTO20f - dispatch to sequential scope for ordering
203+
// RTO20e, RTO20f - dispatch to sequential scope for ordering. This hop is also the thread-safety
204+
// boundary of the write path: everything above it touches only thread-safe/local state, while
205+
// applyAckResult touches unsynchronized state (sync waiters, objects state, pool mutation) whose
206+
// safety contract is the sequential scope.
183207
withContext(sequentialScope.coroutineContext) {
184208
objectsManager.applyAckResult(syntheticMessages) // suspends if SYNCING (RTO20e), applies on SYNCED (RTO20f)
185209
}
@@ -277,7 +301,7 @@ internal class DefaultRealtimeObject(
277301
ObjectHttpStatusCode.BadRequest,
278302
cause = errorReason?.let { AblyException.fromErrorInfo(it) }
279303
)
280-
objectsManager.failBufferedAcks(error) // RTO20e1
304+
objectsManager.failSyncWaiters(error) // RTO20e1
281305
if (state != ChannelState.suspended) {
282306
// do not emit data update events as the actual current state of Objects data is unknown when we're in these channel states
283307
objectsPool.clearObjectsData(false)
@@ -305,6 +329,9 @@ internal class DefaultRealtimeObject(
305329
/** Validates the channel is configured for access (read/subscribe) operations. Spec: RTO25 */
306330
internal fun throwIfInvalidAccessApiConfiguration() = adapter.throwIfInvalidAccessApiConfiguration(channelName)
307331

332+
/** Validates only the object_subscribe channel mode. Spec: RTO23a */
333+
internal fun throwIfMissingObjectSubscribeMode() = adapter.throwIfMissingObjectSubscribeMode(channelName)
334+
308335
/** Validates the channel is configured for write (mutation) operations. Spec: RTO26 */
309336
internal fun throwIfInvalidWriteApiConfiguration() = adapter.throwIfInvalidWriteApiConfiguration(channelName)
310337

‎liveobjects/src/main/kotlin/io/ably/lib/liveobjects/Helpers.kt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,18 @@ internal fun AblyClientAdapter.throwIfInvalidAccessApiConfiguration(channelName:
4242
throwIfMissingChannelMode(channelName, ChannelMode.object_subscribe)
4343
}
4444

45+
/**
46+
* Validates only the `object_subscribe` channel mode (no channel-state check), for
47+
* `RealtimeObject.get()` (RTO23a). Unlike the access methods, `get()` delegates channel-state handling to
48+
* ensure-active-channel ([ensureAttached], RTO23e / RTL33), which re-attaches a DETACHED channel and
49+
* rejects only FAILED — so `get()` must not pre-empt that with a state gate.
50+
*
51+
* Spec: RTO23a
52+
*/
53+
internal fun AblyClientAdapter.throwIfMissingObjectSubscribeMode(channelName: String) {
54+
throwIfMissingChannelMode(channelName, ChannelMode.object_subscribe)
55+
}
56+
4557
/**
4658
* Validates that the channel is configured for the write (mutation) API: message echo must be
4759
* enabled, the channel must be usable (not detached/failed/suspended) and have the

0 commit comments

Comments
 (0)