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

Update chat message materialisation fields #266

Merged
merged 1 commit into from
Jan 13, 2025
Merged

Update chat message materialisation fields #266

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
72 changes: 40 additions & 32 deletions textile/chat-features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,11 +256,15 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and
** @(CHA-M2e)@ @[Testable]@ In global ordering, a @Message@ is considered to occur before another @Message@ if the @serial@ of the first @Message@ is before the latter when lexicographically sorted.
** @(CHA-M2f)@ @[Testable]@ In global ordering, a @Message@ is considered after another @Message@ if the @serial@ of the first @Message@ is after the latter when lexicographically sorted.
** @(CHA-M2g)@ @[Testable]@ Two @Messages@ are considered to be the same if they have the same @serial@, that is to say, both @Serial@ strings are identical.
* @(CHA-M10)@ A @Message@ can be modified by applying a new @action@ to it, such as an update or delete. Applying an @action@ generates a new @Message@ instance with an updated @latestActionSerial@, while the original Message’s @serial@ remains unchanged.
** @(CHA-M10a)@ @[Testable]@ The @latestActionSerial@ of a @Message@ is a lexicographically sortable, unique identifier for each action applied to the @Message@. Unlike @serial@, @latestActionSerial@ is mutable and is updated each time an @action@ is applied.
** @(CHA-M10b)@ @[Testable]@ In global ordering, an @action@ is considered to occur before another @action@ if the @latestActionSerial@ of the first @action@ is before the latter when lexicographically sorted.
** @(CHA-M10c)@ @[Testable]@ In global ordering, an @action@ is considered to occur after another @action@ if the @latestActionSerial@ of the first @action@ is after the latter when lexicographically sorted.
** @(CHA-M10d)@ @[Testable]@ Two @actions@ are considered to be the same if they have the same @latestActionSerial@, that is to say, both @latestActionSerial@ strings are identical.
* @(CHA-M10)@ A @Message@ can be modified by applying a new @action@ to it, such as an update or delete. Applying an @action@ must generate a new @Message@ instance with the same @serial@ and an updated @version@.
** @(CHA-M10a)@ @[Testable]@ The @version@ of a @Message@ is a lexicographically sortable, unique identifier for each version of the @Message@.
** @(CHA-M10b)@ This clause has been deleted.
** @(CHA-M10c)@ This clause has been deleted.
** @(CHA-M10d)@ This clause has been deleted.
** @(CHA-M10e)@ @[Testable]@ To sort @Message@ @versions@ of the same @Message@ (instances with the same @serial@) in global order, sort @Message@ instances lexicographically by their @version@ property.
*** @(CHA-M10e1)@ @[Testable]@ Two @Message@ instances of the same @serial@ are considered the same version if they have the same @version@ property.
*** @(CHA-M10e2)@ @[Testable]@ Among @Message@ instances of the same @serial@, the one with a lexicographically higher @version@ is newer.
*** @(CHA-M10e3)@ @[Testable]@ Among @Message@ instances of the same @serial@, the one with a lexicographically lower @version@ is older.
* @(CHA-M3)@ A client must be able to send a message to a room.
** @(CHA-M3f)@ @[Testable]@ A client may send a message via the Chat REST API.
** @(CHA-M3a)@ @[Testable]@ When a message is sent successfully via the Chat REST API, the caller shall receive a struct representing the "@Message@":#chat-structs-message in response, as if it were received via Realtime event.
Expand Down Expand Up @@ -557,16 +561,16 @@ h4(#rest-sending-messages-request-v2). Corresponding Realtime Event V2
}
}
},
"timestamp": "1726232498871",
"timestamp": 1726232498871,
"createdAt": 1726232498871,
"extras": {
"headers": {
"baz": "qux"
},
},
"serial": "01726585978590-001@abcdefghij:001"
"action": "message.create"
"updatedAt": undefined
"updateSerial": undefined
"serial": "01726585978590-001@abcdefghij:001",
"action": "message.create",
"version": "01726585978590-001@abcdefghij:001",
"operation": {}
}
</pre>
Expand Down Expand Up @@ -606,13 +610,11 @@ The response body is as follows.

<pre>
{
"serial": "01826232498871-001@abcdefghij:001",
"updatedAt": 1726232498871
"version": "01726585978590-001@abcdefghij:001",
"timestamp": 1726585978590
}
</pre>

The serial in the body corresponds to the @updateSerial@ of the corresponding realtime event.

h4(#rest-updating-messages-request). Corresponding Realtime Event

<pre>
Expand All @@ -627,22 +629,22 @@ h4(#rest-updating-messages-request). Corresponding Realtime Event
}
}
},
"timestamp": "1726232498871",
"createdAt": 1726232498871,
"timestamp": 1726585978590,
"extras": {
"headers": {
"baz": "qux"
},
}
}
"serial": "01726585978590-001@abcdefghij:001",
"serial": "01726232498871-001@abcdefghij:001",
"version": "01726585978590-001@abcdefghij:001"
"action": "message.update"
"updatedAt": 1826232498871
"updateSerial": "01826232498871-001@abcdefghij:001"
"operation": {
"clientId": "who-performed-the-action",
"description": "why-the-action-was-performed"
"metadata": {
"foo": "bar"
},
}
}
}
</pre>
Expand Down Expand Up @@ -671,13 +673,11 @@ The response body is as follows.

<pre>
{
"serial": "01826232498871-001@abcdefghij:001",
"deletedAt": 1826232498871
"version": "01826232498871-001@abcdefghij:001",
"timestamp": 1826232498871
}
</pre>

The serial in the body corresponds to the @updateSerial@ of the corresponding realtime event.

h4(#rest-deleting-messages-request). Corresponding Realtime Event

<pre>
Expand All @@ -700,8 +700,9 @@ h4(#rest-deleting-messages-request). Corresponding Realtime Event
}
"serial": "01726585978590-001@abcdefghij:001",
"action": "message.deleted"
"updatedAt": 1826232498871
"updateSerial": "01826232498871-001@abcdefghij:001",
"timestamp": 1826232498871
"createdAt": 1726585978590,
"version": "01826232498871-001@abcdefghij:001",
"operation": {
"clientId": "who-performed-the-action",
"description": "why-the-action-was-performed"
Expand Down Expand Up @@ -841,11 +842,10 @@ h4(#chat-structs-message-v2). Messages V2
"headers": {
"baz": "qux"
}
"latestAction": "message.created",
"latestActionSerial": "01726585978590-001@abcdefghij:001",
"deletedAt": DateTime() | undefined,
"updatedAt": DateTime() | undefined,
"latestActionDetails": {
"action": "message.created",
"version": "01726585978590-001@abcdefghij:001",
"timestamp": DateTime(),
"operation": {
"clientId": "who-performed-the-action",
"description": "why-the-action-was-performed"
"metadata": {
Expand All @@ -857,9 +857,17 @@ h4(#chat-structs-message-v2). Messages V2
}
</pre>

There are getters provided in the @Message@ object to provide easy access to updated/deleted information:
* @isUpdated@ returns @true@ if the message is updated
* @isDeleted@ returns @true@ if the message is deleted
* @updatedBy@ returns the clientId from @operation.clientId@ if the message is updated, @undefined@ otherwise
* @deletedBy@ returns the clientId from @operation.clientId@ if the message is deleted, @undefined@ otherwise
* @updatedAt@ returns the @timestamp@ from the operation if the message is updated, @undefined@ otherwise
* @deletedAt@ returns the @timestamp@ from the operation if the message is deleted, @undefined@ otherwise

Determining the global order of messages may be achieved by lexicographically comparing the serials. See @CHA-M2@ for more information.

Determining the global order of message actions may be achieved by lexicographically comparing the @latestActionSerial@. See @CHA-M10@ for more information.
Determining the global order of message versions may be achieved by lexicographically comparing the @version@. See @CHA-M10@ for more information.

h3(#chat-structs-ephemeral-reactions). Ephemeral Room Reactions

Expand Down
Loading