Skip to content

Commit a19a671

Browse files
authored
Merge pull request #1259 from ably/AIT-1473/http-liveobjects
Add the LiveObjects REST API as channel.object on HTTP channels
2 parents b44664a + 33eef37 commit a19a671

31 files changed

Lines changed: 5390 additions & 20 deletions

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ doubt, that IDL is the source of truth; this doc is the applied version of it fo
3131
15. [Worked example](#15-worked-example)
3232
16. [Quick symbol index](#16-symbol-index)
3333
17. [Internal-graph symbol map (unit specs → `:liveobjects`'s own tests)](#17-internal-mappings)
34+
18. [REST entry point: `RestObject` → `HttpObject`](#18-http-object)
3435

3536
---
3637

@@ -896,3 +897,60 @@ tiers, and none of the 5 internal unit specs use it.)
896897

897898
Keep the `uts` discipline in the migrated tests: one `@Test` per spec case, `/** @UTS objects/unit/… */`
898899
KDoc tags, and a module-local `deviations.md` recording every §17.9 deviation used.
900+
901+
---
902+
903+
## 18. REST entry point: `RestObject` → `HttpObject` <a id="18-http-object"></a>
904+
905+
The `rest_object_*.md` unit specs and `rest_object_test.md` integration spec target the stateless REST
906+
API (RSL16, RSO*). ably-java follows ably-js's Rest → Http rename: spec `RestObject*` / `RestLive*` types
907+
are `HttpObject*` / `HttpLive*`. The entry point is in `io.ably.pubsub.liveobjects`; every other type is
908+
in `io.ably.pubsub.liveobjects.http`.
909+
910+
**These specs live in `:core`, not `:liveobjects`.** `HttpObject` is part of the core HTTP client, so
911+
override the resolver's objects `targetDir` for the `rest_object_*` specs:
912+
913+
| Tier | Directory | Package |
914+
|---|---|---|
915+
| unit | `lib/src/test/kotlin/io/ably/pubsub/uts/unit/objects` | `io.ably.pubsub.uts.unit.objects` |
916+
| integration | `lib/src/test/kotlin/io/ably/pubsub/uts/integration/standard/objects` | `io.ably.pubsub.uts.integration.standard.objects` |
917+
918+
Run them with `./gradlew :core:runUtsUnitTests` / `:core:runUtsIntegrationTests`, and record their
919+
deviations in `lib/src/test/kotlin/io/ably/pubsub/uts/deviations.md`. The one exception is
920+
`objects/integration/RSL16/realtime-write-rest-read-0`: it writes through the realtime LiveObjects
921+
plugin, so it stays in `:liveobjects` as `uts/integration/RestObjectRealtimeInteropTest.kt`.
922+
923+
Unit-tier helpers are in `lib/.../uts/unit/objects/HttpObjectHelpers.kt` (`setupRestObject`,
924+
`respondWithBody`, `parseJson`, `msgpackEncode`/`msgpackDecode`, `encodeUriComponent`, and
925+
`PendingRequest.path` / `.queryParams` / `.header`).
926+
927+
| Spec | ably-java (Kotlin) |
928+
|---|---|
929+
| `Rest(options: …, plugins: { Objects })` | `TestHttpClient { … }` — `HttpObject` is built into the HTTP client (`lib`), no plugin |
930+
| `channel.object` (REST) | `` channel.`object` `` — field of type `HttpObject`, always available (RSL16b not applicable) |
931+
| `AWAIT channel.object.get(RestObjectGetParams(objectId:, path:))` (compact unset or `true`) | `` channel.`object`.getCompact(HttpObjectGetParams.of(objectId, path)) `` (or `ofObjectId(…)` / `ofPath(…)` when only one is set) → `JsonElement?` (blocking); `compact` is never sent |
932+
| `AWAIT channel.object.get(RestObjectGetParams(…, compact: false))` | `` channel.`object`.get(HttpObjectGetParams.of(…)) `` → `HttpObjectGetFullResult?` (blocking); sends `compact=false` |
933+
| compact result | Gson `JsonElement` (`JsonObject` for a map); binary values are Base64 strings for both protocols. Compare with spec literals via `fromJson(…)` from `HttpObjectHelpers.kt` (deviation RSO2a1c) |
934+
| narrowing a full result (`x.map…`, `x.counter…`, leaf fields) | `x.type` (`ValueType`) plus fail-fast casts like realtime `Instance`: `asLiveMap()`, `asLiveCounter()`, `asLiveObject()`, `asObjectData()`, and leaf values `asString()`, `asNumber()`, `asBoolean()`, `asBinary()`, `asJsonObject()`, `asJsonArray()`; prefer them over `assertIs` chains |
935+
| full result `RestLiveMap` / `RestLiveCounter` | `HttpLiveMap` (`objectId`, `semantics`, `entries`) / `HttpLiveCounter` (`objectId`, `count`) |
936+
| `x.map.semantics` / `x.map.entries[k].data` | `x.semantics` / `x.entries.getValue(k).data` |
937+
| `x.counter.data.number` | `x.count` (`Double`) |
938+
| full leaf `ObjectData` | `HttpObjectData` (extends `ObjectData`): `string`, `number` (`Double`), `boolean`, `bytes`, `json` (`JsonElement`); no `encoding` accessor |
939+
| unrecognised object `{ objectId, futureType }` | plain `HttpLiveObject`: `objectId` + `unrecognizedFields["futureType"]` (`JsonObject`; compare via `fromJson`) |
940+
| `RestObjectOperation(objectId: o, mapSet: RestObjectMapSet(key: k, value: v))` | `HttpObjectOperation.mapSet(k, v).withObjectId(o)` (also `withPath`, `withId`) |
941+
| `mapCreate: RestObjectMapCreate(semantics: "LWW", entries: { k: RestObjectMapEntry(data: v) })` | `HttpObjectOperation.mapCreate(ObjectsMapSemantics.LWW, mapOf(k to v))` — entries map straight to `PublishObjectData` |
942+
| `mapRemove` / `counterCreate` / `counterInc` | `HttpObjectOperation.mapRemove(k)` / `.counterCreate(n)` / `.counterInc(n)` |
943+
| `*CreateWithObjectId(initialValue:, nonce:)` + `objectId:` | `HttpObjectOperation.mapCreateWithObjectId(objectId, initialValue, nonce)` (or pass the `HttpObjectGenerateIdResult`) |
944+
| `PublishObjectData(string:/number:/boolean:/bytes:/json:/objectId:)` | `PublishObjectData.string/number/bool/bytes/json/objectId(…)` |
945+
| `semantics: "not-a-semantics"` | `ObjectsMapSemantics.UNKNOWN` |
946+
| `AWAIT channel.object.publish(op \| [ops])` | `` channel.`object`.publish(op) `` / `.publish(listOf(…))` → `HttpObjectPublishResult` (blocking) |
947+
| `AWAIT channel.object.generateObjectId(RestObjectGenerateIdBody(counterCreate: RestObjectCounterCreate(count: n)))` | `` channel.`object`.generateObjectId(HttpObjectGenerateIdBody.counterCreate(n)) `` (blocking) |
948+
949+
**Async: not §3.** Unlike `RealtimeObject`, `HttpObject` follows the HTTP channel convention, not
950+
`CompletableFuture`: each method is blocking (returns the result, throws `AblyException`) and has an
951+
`…Async(…, Callback<T>)` twin. Translate spec `AWAIT` to the blocking call (no `.await()`), and
952+
`AWAIT x FAILS WITH error` to `assertFailsWith<AblyException> { x }`.
953+
954+
Operations and generate-ID bodies with zero or several bodies are unrepresentable (T-4, in
955+
`deviations.md`). JSON leaves go on the wire in the OD2g `json` field (OD4c5/OD4d5), as the spec says.
956+

‎lib/src/main/java/io/ably/pubsub/http/Auth.java‎

Lines changed: 34 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -876,21 +876,12 @@ else if(!request.keyName.equals(keyName))
876876
/* timestamp */
877877
if(request.timestamp == 0) {
878878
if(options.queryTime) {
879-
long oldNanoTimeDelta = nanoTimeDelta;
880-
long currentNanoTimeDelta = clock.currentTimeMillis() - clock.nanoTime()/(1000*1000);
881-
882-
if (timeDelta != Long.MAX_VALUE) {
883-
/* system time changed by more than 500ms since last time? */
884-
if(Math.abs(oldNanoTimeDelta - currentNanoTimeDelta) > 500)
885-
timeDelta = Long.MAX_VALUE;
886-
}
887-
888-
if (timeDelta != Long.MAX_VALUE) {
889-
request.timestamp = timestamp() + timeDelta;
890-
nanoTimeDelta = currentNanoTimeDelta;
879+
Long known = serverTimestampIfKnown();
880+
if (known != null) {
881+
request.timestamp = known;
891882
} else {
892883
request.timestamp = ably.time();
893-
timeDelta = request.timestamp - timestamp();
884+
setServerTime(request.timestamp);
894885
}
895886
}
896887
else {
@@ -1256,6 +1247,35 @@ public long serverTimestamp() {
12561247
return delta != Long.MAX_VALUE ? clientTime + timeDelta : clientTime;
12571248
}
12581249

1250+
/**
1251+
* [Internal] The current server time derived from the stored offset, or {@code null} if the
1252+
* offset is unknown or the device clock has jumped by more than 500 ms since it was last used
1253+
* (in which case the offset is discarded). Shared by {@code queryTime} token requests and
1254+
* {@code generateObjectId}, so a client fetches {@code /time} once for both.
1255+
*/
1256+
public synchronized Long serverTimestampIfKnown() {
1257+
if (timeDelta == Long.MAX_VALUE) return null;
1258+
long now = timestamp();
1259+
long currentNanoTimeDelta = now - clock.nanoTime()/(1000*1000);
1260+
/* system time changed by more than 500ms since last time? */
1261+
if (Math.abs(nanoTimeDelta - currentNanoTimeDelta) > 500) {
1262+
timeDelta = Long.MAX_VALUE;
1263+
return null;
1264+
}
1265+
nanoTimeDelta = currentNanoTimeDelta;
1266+
return now + timeDelta;
1267+
}
1268+
1269+
/**
1270+
* [Internal] Stores the offset to the local clock from a server time just fetched from
1271+
* {@code /time}.
1272+
*/
1273+
public synchronized void setServerTime(long serverTime) {
1274+
long now = timestamp();
1275+
timeDelta = serverTime - now;
1276+
nanoTimeDelta = now - clock.nanoTime()/(1000*1000);
1277+
}
1278+
12591279
private static final String TAG = Auth.class.getName();
12601280
private final PubSubBase ably;
12611281
private final Clock clock;
@@ -1270,7 +1290,7 @@ public long serverTimestamp() {
12701290
/**
12711291
* Time delta is server time minus client time, in milliseconds, MAX_VALUE if not obtained yet
12721292
*/
1273-
private long timeDelta = Long.MAX_VALUE;
1293+
private volatile long timeDelta = Long.MAX_VALUE;
12741294
/**
12751295
* Time delta between System.nanoTime() and System.currentTimeMillis. If it changes significantly it
12761296
* suggests device time/date has changed

‎lib/src/main/java/io/ably/pubsub/http/ChannelBase.java‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
package io.ably.pubsub.http;
22

33
import io.ably.pubsub.http.BasePaginatedQuery;
4+
import io.ably.pubsub.liveobjects.HttpObject;
5+
import io.ably.pubsub.liveobjects.http.DefaultHttpObject;
46
import io.ably.pubsub.http.HttpRequester;
57
import io.ably.pubsub.http.HttpScheduler;
68
import io.ably.pubsub.http.HttpCore;
@@ -48,6 +50,14 @@ public class ChannelBase {
4850
*/
4951
public final HttpAnnotations annotations;
5052

53+
/**
54+
* The LiveObjects entry point for this channel. It is built into the HTTP client and needs no
55+
* plugin.
56+
* <p>
57+
* Spec: RSL16
58+
*/
59+
public final HttpObject object;
60+
5161

5262
private final MessageEditsMixin messageEditsMixin;
5363

@@ -607,6 +617,7 @@ public void getMessageVersionsAsync(String serial, Param[] params, Callback<Asyn
607617
this.presence = new Presence();
608618
this.annotations = new HttpAnnotations(name, ably.http, ably.options, options);
609619
this.messageEditsMixin = new MessageEditsMixin(basePath, ably.options, options, ably.auth);
620+
this.object = new DefaultHttpObject(ably, basePath, ably.objectsServerTime);
610621
}
611622

612623
private final PubSubBase ably;

‎lib/src/main/java/io/ably/pubsub/http/PubSubBase.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
package io.ably.pubsub.http;
22

3+
import io.ably.pubsub.liveobjects.http.HttpObjectServerTime;
34
import io.ably.pubsub.annotation.Experimental;
45
import io.ably.pubsub.platform.Platform;
56
import io.ably.pubsub.push.Push;
@@ -70,6 +71,11 @@ public abstract class PubSubBase implements AutoCloseable {
7071
public final Push push;
7172
protected final PlatformAgentProvider platformAgentProvider;
7273

74+
/**
75+
* Server time shared by the {@code object} entry points of this client's HTTP channels (RTO16).
76+
*/
77+
final HttpObjectServerTime objectsServerTime = new HttpObjectServerTime(this);
78+
7379
/**
7480
* Constructs a client object using an Ably API key or token string.
7581
* <p>

0 commit comments

Comments
 (0)