|
| 1 | +--- |
| 2 | +title: Objects Features |
| 3 | +section: client-lib-development-guide |
| 4 | +index: 65 |
| 5 | +jump_to: |
| 6 | + Help with: |
| 7 | + - Objects Features Overview#overview |
| 8 | +--- |
| 9 | + |
| 10 | +h2(#overview). Overview |
| 11 | + |
| 12 | +This document outlines the feature specification for the Objects feature of the Realtime system. It is currently under development and stored separately from the main specification to simplify the initial implementation of the feature in other SDKs. Once completed, it will be moved to the main "features":../features spec. |
| 13 | + |
| 14 | +Objects feature enables clients to store shared data as "objects" on a channel. When an object is updated, changes are automatically propagated to all subscribed clients in realtime, ensuring each client always sees the latest state. |
| 15 | + |
| 16 | +h3(#realtime-objects). RealtimeObjects |
| 17 | + |
| 18 | +* @(RTO1)@ @Objects#getRoot@ function: |
| 19 | +** @(RTO1a)@ Returns an object with id @root@ from the internal @ObjectsPool@ as a @LiveMap@ |
| 20 | +* @(RTO2)@ Various object operations may require a specific channel mode to be set on a channel in order to be performed. If a specific channel mode is required by an operation, then: |
| 21 | +** @(RTO2a)@ If the channel is in the @ATTACHED@ state, the presence of the required channel mode is checked against the set of channel modes granted by the server per "RTL4m":../features#RTL4m : |
| 22 | +*** @(RTO2a1)@ If the channel mode is in the set, the operation is allowed |
| 23 | +*** @(RTO2a2)@ If the channel mode is missing, unless otherwise specified by the operation, the library should indicate an error with code 40024 stating that the operation cannot be performed without the required channel mode |
| 24 | +** @(RTO2b)@ Otherwise, a best-effort attempt is made, and the channel mode is checked against the set of channel modes requested by the user per "TB2d":../features#TB2d : |
| 25 | +*** @(RTO2b1)@ If the channel mode is in the set, the operation is allowed |
| 26 | +*** @(RTO2b2)@ If the channel mode is missing, unless otherwise specified by the operation, the library should indicate an error with code 40024 stating that the operation cannot be performed without the required channel mode |
| 27 | +* @(RTO3)@ An internal @ObjectsPool@ should be used to maintain the list of objects present on a channel |
| 28 | +** @(RTO3a)@ @ObjectsPool@ is a @Dict<String, LiveObject>@ - a map of @LiveObject@s keyed by "@objectId@":../features#OST2a string |
| 29 | +** @(RTO3b)@ It must always contain a @LiveMap@ object with id @root@ |
| 30 | +* @(RTO4)@ When a channel @ATTACHED@ @ProtocolMessage@ is received, the @ProtocolMessage@ may contain a @HAS_OBJECTS@ bit flag indicating that it will perform an objects sync, see "TR3":../features#TR3 . Note that this does not imply that objects are definitely present on the channel, only that there may be; the @OBJECT_SYNC@ message may be empty |
| 31 | +** @(RTO4a)@ If the @HAS_OBJECTS@ flag is 1, the server will shortly perform an @OBJECT_SYNC@ sequence as described in "RTO5":#RTO5 |
| 32 | +** @(RTO4b)@ If the @HAS_OBJECTS@ flag is 0 or there is no @flags@ field, the sync sequence must be considered complete immediately, and the client library must perform the following actions in order: |
| 33 | +*** @(RTO4b1)@ All objects except the one with id @root@ must be removed from the internal @ObjectsPool@ |
| 34 | +*** @(RTO4b2)@ The data for the @LiveMap@ with id @root@ must be cleared by setting it to a zero-value per "RTLM4":#RTLM4 |
| 35 | +*** @(RTO4b3)@ The @SyncObjectsPool@ must be cleared |
| 36 | +*** @(RTO4b4)@ Perform the actions for objects sync completion as described in "RTO5c":#RTO5c |
| 37 | +* @(RTO5)@ The realtime system reserves the right to initiate an objects sync of the objects on a channel at any point once a channel is attached. A server initiated objects sync provides Ably with a means to send a complete list of objects present on the channel at any point |
| 38 | +** @(RTO5a)@ When an @OBJECT_SYNC@ @ProtocolMessage@ is received with a @channel@ attribute matching the channel name, the client library must parse the @channelSerial@ attribute: |
| 39 | +*** @(RTO5a1)@ The @channelSerial@ is used as the sync cursor and is a two-part identifier: @<sequence id>:<cursor value>@ |
| 40 | +*** @(RTO5a2)@ If a new sequence id is sent from Ably, the client library must treat it as the start of a new objects sync sequence, and any previous in-flight sync must be discarded: |
| 41 | +**** @(RTO5a2a)@ The current @SyncObjectsPool@ list must be cleared |
| 42 | +*** @(RTO5a3)@ If the sequence id matches the previously received sequence id, the client library should continue the sync process |
| 43 | +*** @(RTO5a4)@ The objects sync sequence for that sequence identifier is considered complete once the cursor is empty; that is when the @channelSerial@ looks like @<sequence id>:@ |
| 44 | +*** @(RTO5a5)@ An @OBJECT_SYNC@ may also be sent with no @channelSerial@ attribute. In this case, the sync data is entirely contained within the @ProtocolMessage@ |
| 45 | +** @(RTO5b)@ During the sync sequence, the @ObjectMessage.object@ values from incoming @OBJECT_SYNC@ @ProtocolMessage@s must be temporarily stored in the internal @SyncObjectsPool@ list |
| 46 | +** @(RTO5c)@ When the objects sync has completed, the client library must perform the following actions in order: |
| 47 | +*** @(RTO5c1)@ For each @ObjectState@ member in the @SyncObjectsPool@ list: |
| 48 | +**** @(RTO5c1a)@ If an object with @ObjectState.objectId@ exists in the internal @ObjectsPool@: |
| 49 | +***** @(RTO5c1a1)@ Override the internal data for the object as per "RTLC6":#RTLC6, "RTLM6":#RTLM6 |
| 50 | +**** @(RTO5c1b)@ If an object with @ObjectState.objectId@ does not exist in the internal @ObjectsPool@: |
| 51 | +***** @(RTO5c1b1)@ Create a new @LiveObject@ using the data from @ObjectState@ and add it to the internal @ObjectsPool@: |
| 52 | +****** @(RTO5c1b1a)@ If @ObjectState.counter@ is present, create a zero-value @LiveCounter@ (per "RTLC4":#RTLC4) and override its internal data using the current @ObjectState@ per "RTLC6":#RTLC6 |
| 53 | +****** @(RTO5c1b1b)@ If @ObjectState.map@ is present, create a zero-value @LiveMap@ (per "RTLM4":#RTLM4) and override its internal data using the current @ObjectState@ per "RTLM6":#RTLM6 |
| 54 | +****** @(RTO5c1b1c)@ Otherwise, log a warning that an unsupported object state message has been received, and discard the current @ObjectState@ without taking any action |
| 55 | +*** @(RTO5c2)@ Remove any objects from the internal @ObjectsPool@ for which @objectId@s were not received during the sync sequence |
| 56 | +**** @(RTO5c2a)@ The object with ID @root@ must not be removed from @ObjectsPool@, as per "RTO3b":#RTO3b |
| 57 | +*** @(RTO5c3)@ Clear any stored sync sequence identifiers and cursor values |
| 58 | +*** @(RTO5c4)@ The @SyncObjectsPool@ must be cleared |
| 59 | +* @(RTO6)@ When needed, a zero-value object can be created if it does not exist in the internal @ObjectsPool@ for an @objectId@, in the following way: |
| 60 | +** @(RTO6a)@ If an object with @objectId@ exists in @ObjectsPool@, do not create a new object |
| 61 | +** @(RTO6b)@ The expected type of the object can be inferred from the provided @objectId@: |
| 62 | +*** @(RTO6b1)@ Split the @objectId@ (formatted as @type:hash@timestamp@) on the separator @:@ and parse the first part as the type string |
| 63 | +*** @(RTO6b2)@ If the parsed type is @map@, create a zero-value @LiveMap@ per "RTLM4":#RTLM4 in the @ObjectsPool@ |
| 64 | +*** @(RTO6b3)@ If the parsed type is @counter@, create a zero-value @LiveCounter@ per "RTLC4":#RTLC4 in the @ObjectsPool@ |
| 65 | + |
| 66 | +h3(#livecounter). LiveCounter |
| 67 | + |
| 68 | +* @(RTLC1)@ The @LiveCounter@ extends @LiveObject@ |
| 69 | +* @(RTLC2)@ Represents the counter object type for Object IDs of type @counter@ |
| 70 | +* @(RTLC3)@ Holds a 64-bit floating-point number as a private @data@ |
| 71 | +* @(RTLC4)@ The zero-value @LiveCounter@ is a @LiveCounter@ with @data@ set to 0 |
| 72 | +* @(RTLC5)@ @LiveCounter#value@ function: |
| 73 | +** @(RTLC5a)@ Requires the @OBJECT_SUBSCRIBE@ channel mode to be granted per "RTO2":#RTO2 |
| 74 | +** @(RTLC5b)@ If the channel is in the @DETACHED@ or @FAILED@ state, the library should indicate an error with code 90001 |
| 75 | +** @(RTLC5c)@ Returns the current @data@ value |
| 76 | +* @(RTLC6)@ @LiveCounter@'s internal @data@ can be overridden with the provided @ObjectState@ in the following way: |
| 77 | +** @(RTLC6a)@ Replace the private @siteTimeserials@ of the @LiveCounter@ with the value from @ObjectState.siteTimeserials@ |
| 78 | +** @(RTLC6b)@ Set the private flag @createOperationIsMerged@ to @false@ |
| 79 | +** @(RTLC6c)@ Set @data@ to the value of @ObjectState.counter.count@, or to 0 if it does not exist |
| 80 | +** @(RTLC6d)@ If @ObjectState.createOp@ is present: |
| 81 | +*** @(RTLC6d1)@ Add @ObjectState.createOp.counter.count@ to @data@, if it exists |
| 82 | +*** @(RTLC6d2)@ Set the private flag @createOperationIsMerged@ to @true@ |
| 83 | + |
| 84 | +h3(#livemap). LiveMap |
| 85 | + |
| 86 | +* @(RTLM1)@ The @LiveMap@ extends @LiveObject@ |
| 87 | +* @(RTLM2)@ Represents the map object type for Object IDs of type @map@ |
| 88 | +* @(RTLM3)@ Holds a @Dict<String, MapEntry>@ as a private @data@ map |
| 89 | +* @(RTLM4)@ The zero-value @LiveMap@ is a @LiveMap@ with @data@ set to an empty map |
| 90 | +* @(RTLM5)@ @LiveMap#get@ function: |
| 91 | +** @(RTLM5a)@ Accepts a key of type String |
| 92 | +** @(RTLM5b)@ Requires the @OBJECT_SUBSCRIBE@ channel mode to be granted per "RTO2":#RTO2 |
| 93 | +** @(RTLM5c)@ If the channel is in the @DETACHED@ or @FAILED@ state, the library should indicate an error with code 90001 |
| 94 | +** @(RTLM5d)@ Returns the value from the current @data@ at the specified key, as follows: |
| 95 | +*** @(RTLM5d1)@ If no @MapEntry@ exists at the key, return undefined/null |
| 96 | +*** @(RTLM5d2)@ If a @MapEntry@ exists at the key: |
| 97 | +**** @(RTLM5d2a)@ If @MapEntry.tombstone@ is @true@, return undefined/null |
| 98 | +**** @(RTLM5d2b)@ If @MapEntry.boolean@ exists, return it |
| 99 | +**** @(RTLM5d2c)@ If @MapEntry.bytes@ exists, return it |
| 100 | +**** @(RTLM5d2d)@ If @MapEntry.number@ exists, return it |
| 101 | +**** @(RTLM5d2e)@ If @MapEntry.string@ exists, return it |
| 102 | +**** @(RTLM5d2f)@ If @MapEntry.objectId@ exists, get the object stored at that @objectId@ from the internal @ObjectsPool@: |
| 103 | +***** @(RTLM5d2f1)@ If an object with id @objectId@ does not exist, return undefined/null |
| 104 | +***** @(RTLM5d2f2)@ If an object with id @objectId@ exists, return it |
| 105 | +**** @(RTLM5d2g)@ Otherwise, return undefined/null |
| 106 | +* @(RTLM6)@ @LiveMap@ internal @data@ can be overridden with the provided @ObjectState@ in the following way: |
| 107 | +** @(RTLM6a)@ Replace the private @siteTimeserials@ of the @LiveMap@ with the value from @ObjectState.siteTimeserials@ |
| 108 | +** @(RTLM6b)@ Set the private flag @createOperationIsMerged@ to @false@ |
| 109 | +** @(RTLM6c)@ Set @data@ to @ObjectState.map.entries@, or to an empty map if it does not exist |
| 110 | +** @(RTLM6d)@ If @ObjectState.createOp@ is present: |
| 111 | +*** @(RTLM6d1)@ For each key–@MapEntry@ pair in @ObjectState.createOp.map.entries@: |
| 112 | +**** @(RTLM6d1a)@ If @MapEntry.tombstone@ is @false@, apply the @MAP_SET@ operation to the specified key using @MapEntry.timeserial@ and @MapEntry.data@ per "RTLM7":#RTLM7 |
| 113 | +**** @(RTLM6d1b)@ If @MapEntry.tombstone@ is @true@, apply the @MAP_REMOVE@ operation to the specified key using @MapEntry.timeserial@ per "RTLM8":#RTLM8 |
| 114 | +*** @(RTLM6d2)@ Set the private flag @createOperationIsMerged@ to @true@ |
| 115 | +* @(RTLM7)@ @MAP_SET@ operation for a key can be applied to a @LiveMap@ in the following way: |
| 116 | +** @(RTLM7a)@ If an entry exists in the private @data@ for the specified key: |
| 117 | +*** @(RTLM7a1)@ If the operation cannot be applied as per "RTLM9":#RTLM9, discard the operation without taking any action |
| 118 | +*** @(RTLM7a2)@ Otherwise, apply the operation: |
| 119 | +**** @(RTLM7a2a)@ Set @MapEntry.data@ to the @ObjectData@ from the operation |
| 120 | +**** @(RTLM7a2b)@ Set @MapEntry.timeserial@ to the operation's serial |
| 121 | +**** @(RTLM7a2c)@ Set @MapEntry.tombstone@ to @false@ |
| 122 | +** @(RTLM7b)@ If an entry does not exist in the private @data@ for the specified key: |
| 123 | +*** @(RTLM7b1)@ Create a new entry in @data@ for the specified key with the provided @ObjectData@ and the operation's serial |
| 124 | +*** @(RTLM7b2)@ Set @MapEntry.tombstone@ for the new entry to @false@ |
| 125 | +** @(RTLM7c)@ If the operation has a non-empty @ObjectData.objectId@ attribute: |
| 126 | +*** @(RTLM7c1)@ Create a zero-value @LiveObject@ in the internal @ObjectsPool@ per "RTO6":#RTO6 |
| 127 | +* @(RTLM8)@ @MAP_REMOVE@ operation for a key can be applied to a @LiveMap@ in the following way: |
| 128 | +** @(RTLM8a)@ If an entry exists in the private @data@ for the specified key: |
| 129 | +*** @(RTLM8a1)@ If the operation cannot be applied as per "RTLM9":#RTLM9, discard the operation without taking any action |
| 130 | +*** @(RTLM8a2)@ Otherwise, apply the operation: |
| 131 | +**** @(RTLM8a2a)@ Set @MapEntry.data@ to undefined/null |
| 132 | +**** @(RTLM8a2b)@ Set @MapEntry.timeserial@ to the operation's serial |
| 133 | +**** @(RTLM8a2c)@ Set @MapEntry.tombstone@ to @true@ |
| 134 | +** @(RTLM8b)@ If an entry does not exist in the private @data@ for the specified key: |
| 135 | +*** @(RTLM8b1)@ Create a new entry in @data@ for the specified key, with @MapEntry.data@ set to undefined/null and the operation's serial |
| 136 | +*** @(RTLM8b2)@ Set @MapEntry.tombstone@ for the new entry to @true@ |
| 137 | +* @(RTLM9)@ Whether a map operation can be applied to a map entry is determined as follows: |
| 138 | +** @(RTLM9a)@ For a @LiveMap@ using @LWW@ (Last-Write-Wins) CRDT semantics, the operation must only be applied if its serial is strictly greater ("after") than the entry's serial when compared lexicographically |
| 139 | +** @(RTLM9b)@ If both the entry serial and the operation serial are null or empty strings, they are treated as the "earliest possible" serials and considered "equal", so the operation must not be applied |
| 140 | +** @(RTLM9c)@ If only the entry serial exists, the missing operation serial is considered lower than the existing entry serial, so the operation must not be applied |
| 141 | +** @(RTLM9d)@ If only the operation serial exists, it is considered greater than the missing entry serial, so the operation can be applied |
| 142 | +** @(RTLM9e)@ If both serials exist, compare them lexicographically and allow operation to be applied only if the operation's serial is greater than the entry's serial |
0 commit comments