Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add api docs for mutable message fields #44

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add api docs for mutable message fields #44

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3c38104
Update PresenceAction descriptions
SimonWoolf Nov 28, 2024
27a562e
Add new fields for mutable messages
SimonWoolf Nov 28, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions descriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -582,15 +582,29 @@ 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. |

## enum MessageAction

Enumerates the possible types of `Message` there can be.

| Enum | Spec | Description |
|---|---|---|
| MESSAGE_UNSET | TM5 | (The field is unset, eg a `Message` retrieved from before the `action` field was added) |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case, I thought RT would set these to message.create when sending over the wire considering all messages before action was introduced are by definition a message.create? Or is that not the case?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking here about history, realtime messages aren't an issue.

We could certainly say that every message with no action is implicitly a CREATE (and have the history api do that), but then the obvious question is, if that's the semantics we want then why do we even have an UNSET, why not make CREATE zero? @lmars you defined the enum, wdyt?

| MESSAGE_CREATE | TM5 | A normal message that has been published by a user. |
| MESSAGE_UPDATE | TM5 | An update that edits a previously-published message (referenced by `serial`). |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Small nit pick, but could we say something like..

Suggested change
| MESSAGE_UPDATE | TM5 | An update that edits a previously-published message (referenced by `serial`). |
| MESSAGE_UPDATE | TM5 | An update that modifies a previously-published message (referenced by `serial`). |

Just so we are consistent with the wording of 'update` everywhere?

| MESSAGE_DELETE | TM5 | A deletion of a previously-published message (referenced by `serial`). |
| ANNOTATION_CREATE | TM5 | An annotation added to a previously-published message (referenced by serial). |
| ANNOTATION_DELETE | TM5 | A deletion of a previously-published annotation. |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we are talking about adding annotations above, can we reword the below to say something like

Suggested change
| ANNOTATION_DELETE | TM5 | A deletion of a previously-published annotation. |
| ANNOTATION_DELETE | TM5 | A deletion of a annotation that was previously added to a published message. |

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the help text for ANNOTATION_DELETE is pretty much a placeholder since I don't think we've even started discussing how deleting annotations would work. (or has the chat team discussed this?)

| META_OCCUPANCY | TM5 | Channel metadata containing information on what the current occupancy of the channel is. |

## class ConnectionDetails

Expand Down Expand Up @@ -635,7 +649,23 @@ 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. |
| 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). |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Serial is also lexicographically sortable, can we mention this here too?

| 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 message. |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| refSerial: String? ||| TM2l | If this message references another, the serial of that message. |
| 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. |
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Each of these (bar the clientId perhaps) should be optional

| metadata: Dict<string, string> ||| TM2n3 | Arbitrary metadata contributed by the user who triggered the update or delete. |

## class PresenceMessage

Expand Down