From 3c38104d8b19946bdb95905b55b719c12256db2a Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Thu, 28 Nov 2024 17:37:07 +0000 Subject: [PATCH 1/2] Update PresenceAction descriptions Which were not very good --- descriptions.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/descriptions.md b/descriptions.md index 35a2439..f7519b7 100644 --- a/descriptions.md +++ b/descriptions.md @@ -582,15 +582,15 @@ Enables the presence set to be entered and subscribed to, and the historic prese ## enum PresenceAction -Describes the possible actions members in the presence set can emit. +Enumerates the possible types of `PresenceMessage` (and corresponding presence event emitted by a `RealtimePresence` object) there can be | Enum | Spec | Description | |---|---|---| -| ABSENT | TP2 | A member is not present in the channel. | -| PRESENT | TP2 | When subscribing to presence events on a channel that already has members present, this event is emitted for every member already present on the channel before the subscribe listener was registered. | -| ENTER | TP2 | A new member has entered the channel. | -| LEAVE | TP2 | A member who was present has now left the channel. This may be a result of an explicit request to leave or implicitly when detaching from the channel. Alternatively, if a member's connection is abruptly disconnected and they do not resume their connection within a minute, Ably treats this as a leave event as the client is no longer present. | -| UPDATE | TP2 | An already present member has updated their member data. Being notified of member data updates can be very useful, for example, it can be used to update the status of a user when they are typing a message. | +| ABSENT | TP2 | A tombstone for a member no longer present (used internally; as a user you should not ever see this). | +| PRESENT | TP2 | A member already present in the channel's presence set. (So the `PresenceMessage.action` for members retrieved using `Presence.get()` will generally be `PRESENT`; and when attaching to a channel that already has members, a `PRESENT` event will be emitted to presence subscribers for every such member). | +| ENTER | TP2 | A new member has entered the channel's presence set. | +| LEAVE | TP2 | A member who was present has now left the channel's presence set. This may be a result of an explicit request to leave, or implicit from the member detaching from the channel or disconnecting from Ably and not reconnecting within a grace period. | +| UPDATE | TP2 | An already present member has updated their member data. | ## class ConnectionDetails From cff1ec858344e4de02ca9a654069e76c863c5d00 Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Thu, 28 Nov 2024 17:38:30 +0000 Subject: [PATCH 2/2] Add new fields for mutable messages --- descriptions.md | 31 ++++++++++++++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/descriptions.md b/descriptions.md index f7519b7..3d228ba 100644 --- a/descriptions.md +++ b/descriptions.md @@ -592,6 +592,18 @@ Enumerates the possible types of `PresenceMessage` (and corresponding presence e | LEAVE | TP2 | A member who was present has now left the channel's presence set. This may be a result of an explicit request to leave, or implicit from the member detaching from the channel or disconnecting from Ably and not reconnecting within a grace period. | | UPDATE | TP2 | An already present member has updated their member data. | +## enum MessageAction + +Enumerates the possible types of `Message` there can be. + +| Enum | Spec | Description | +|---|---|---| +| MESSAGE_CREATE | TM5 | A normal message that has been published by a user. | +| MESSAGE_UPDATE | TM5 | An update that modifies a previously-published message (referenced by `serial`). | +| MESSAGE_DELETE | TM5 | A deletion of a previously-published message (referenced by `serial`). | +| META_OCCUPANCY | TM5 | Channel metadata containing information on what the current occupancy of the channel is. | +| MESSAGE_SUMMARY | TM5 | A message containing the latest rolled-up summary of annotations that have been made to this message. | + ## class ConnectionDetails Contains any constraints a client should adhere to and provides additional metadata about a [`Connection`]{@link Connection}, such as if a request to [`publish()`]{@link RealtimeClient#publish} a message that exceeds the maximum message size should be rejected immediately without communicating with Ably. @@ -635,7 +647,24 @@ Contains an individual message that is sent to, or received from, Ably. | extras: JsonObject? ||| TM2i | A JSON object of arbitrary key-value pairs that may contain metadata, and/or ancillary payloads. Valid payloads include [`push`]{@link Push}, [`delta`]{@link DeltaExtras}, [`ref`]{@link ReferenceExtras} and `headers`. | | id: String ||| TM2a | A Unique ID assigned by Ably to this message. | | name: String? ||| TM2g | The event name. | -| timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. | +| action: MessageAction ||| TM2j | Which one of the [`MessageAction`]{@link MessageAction} types this message represents. | +| timestamp: Time ||| TM2f | Timestamp of when the message was received by Ably, as milliseconds since the Unix epoch. (This is the timestamp of the current version of the message) | +| serial: String? ||| TM2k | This message's unique serial (an identifier that — unlike the id — will remain the same in all future updates of this message, and can be used to update or delete that message). Lexicographically-comparable with other serials and with the `version` field. | +| version: String? ||| TM2p | The version of the message, lexicographically-comparable with other versions (that share the same serial) Will differ from the serial only if the message has been updated or deleted. | +| refSerial: String? ||| TM2l | If this message references another, the serial of that referenced message. | +| refType: String? ||| TM2m | If this message references another, the type of reference that is. | +| createdAt: Time? ||| TM2o | The timestamp of the very first version of a given message (will differ from `timestamp` only if the message has been updated or deleted). | +| operation: Operation? ||| TM2n | In the case of an updated or deleted message, this will contain metadata about the update or delete operation. | + +## class Operation + +In the case of an updated or deleted message, this will contain metadata about the update or delete operation. + +| Method / Property | Parameter | Returns | Spec | Description | +|---|---|---|---|---| +| clientId: String? ||| TM2n1 | ClientId of the user who triggered the update or delete. | +| description: String? ||| TM2n2 | Reason for the update or delete provided by of the user who triggered it. | +| metadata: Dict? ||| TM2n3 | Arbitrary metadata contributed by the user who triggered the update or delete. | ## class PresenceMessage