Skip to content

Updated message spec and related endpoints #270

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

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

Updated message spec and related endpoints #270

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9b04985
Fixed operation struct for Messages V2, operation metadata is a map<s…
sacOO7 Jan 21, 2025
a5baa77
Removed deprecated timeserial spec for messages, marked as superseded
sacOO7 Jan 22, 2025
19d3a9d
Updated version, serial and timestamp for example events according to…
sacOO7 Jan 22, 2025
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
43 changes: 17 additions & 26 deletions textile/chat-features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -247,12 +247,10 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and

* @(CHA-M1)@ Chat messages for a Room are sent on a corresponding realtime channel @<roomId>::$chat::$chatMessages@. For example, if your room id is @my-room@ then the messages channel will be @my-room::$chat::$chatMessages@.
* @(CHA-M2)@ A @Message@ corresponds to a single message in a chat room. This is analogous to a single user-specified message on an Ably channel (NOTE: **not** a @ProtocolMessage@).
<div class=deprecated>
** @(CHA-M2a)@ @[Testable]@ @(deprecated)@ A @Message@ is considered before another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes first.
** @(CHA-M2b)@ @[Testable]@ @(deprecated)@ A @Message@ is considered after another @Message@ in the global order if the @timeserial@ of the corresponding realtime channel message comes second.
** @(CHA-M2c)@ @[Testable]@ @(deprecated)@ A @Message@ is considered to be equal to another @Message@ if they have the same timeserial.
</div>
** @(CHA-M2d)@ @[Testable]@ A @Message@ contains a unique, immutable @serial@, which is a lexicographically sortable string. Global message order can be determined by a simple string comparison of the serials. The SDK must not attempt to parse timeserial strings.
** @(CHA-M2a)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-M2e@.
** @(CHA-M2b)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-M2f@.
** @(CHA-M2c)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-M2g@.
** @(CHA-M2d)@ @[Testable]@ A @Message@ contains a unique, immutable @serial@, which is a lexicographically sortable string. Global message order can be determined by a simple string comparison of the serials. The SDK must not attempt to parse @serial@ strings.
** @(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.
Expand Down Expand Up @@ -284,11 +282,7 @@ Broadly speaking, messages are published via REST calls to the Chat HTTP API and
* @(CHA-M4)@ Messages can be received via a subscription in realtime.
** @(CHA-M4a)@ @[Testable]@ A subscription can be registered to receive incoming messages. Adding a subscription has no side effects on the status of the room or the underlying realtime channel.
** @(CHA-M4b)@ @[Testable]@ A subscription can de-registered from incoming messages. Removing a subscription has no side effects on the status of the room or the underlying realtime channel.

<div class=deprecated>
** @(CHA-M4c)@ @[Testable]@ @(deprecated)@ When a realtime message with @name@ set to @message.created@ is received, it is translated into a message event, which contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message. This event is then broadcast to all subscribers.
</div>

** @(CHA-M4c)@ @[Testable]@ This specification point has been removed. It was superseded by @CHA-M4l@.
** @(CHA-M4l)@ When a realtime message with the @name@ field set to @chat.message@ is received, it shall be translated into a message event based on its @action@. This message event contains a @type@ field with the event type as well as a @message@ field containing the "@Message Struct@":#chat-structs-message-v2. This event shall then broadcast to all subscribers.
** @(CHA-M4d)@ @[Testable]@ If a realtime message with an unknown @name@ is received, the SDK shall silently discard the message, though it may log at @DEBUG@ or @TRACE@ level.
** @(CHA-M4m)@ @[Testable]@ The @action@ field of the realtime message determines the type of chat message event that is emitted, based on the following rules.
Expand Down Expand Up @@ -518,7 +512,7 @@ h4(#rest-sending-messages-request-v1). Corresponding Realtime Event V1 @(depreca
h4(#rest-sending-messages-request-v2). Request V2

Below is the full REST payload format for the V2 endpoint. The @metadata@ and @headers@ keys are optional.

Note that @metadata@ is of type map<string, any> or jsonObject.
Copy link
Contributor

Choose a reason for hiding this comment

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

We probably don't need to specify jsonObject here - map<string, any> covers everything?

<pre>
POST /chat/v2/rooms/<roomId>/messages
{
Expand Down Expand Up @@ -580,7 +574,7 @@ h3(#rest-updating-messages). Updating Messages
h4(#rest-updating-messages-request). Request

Below is the full REST payload format for the endpoint. The @description@, @headers@ and both @metadata@ keys are optional.

Note that outer @metadata@ is of type map<string, string>.
Copy link
Contributor

Choose a reason for hiding this comment

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

Suggested change
Note that outer @metadata@ is of type map<string, string>.
Note that the root level @metadata@ field is of type map<string, string>.

<pre>
PUT /chat/v2/rooms/<roomId>/messages/<serial>
{
Expand Down Expand Up @@ -610,8 +604,8 @@ The response body is as follows.

<pre>
{
"version": "01726585978590-001@abcdefghij:001",
"timestamp": 1726585978590
"version": "01729085978590-001@abcdefghij:001",
"timestamp": 1729085978590
}
</pre>

Expand All @@ -630,14 +624,14 @@ h4(#rest-updating-messages-request). Corresponding Realtime Event
}
},
"createdAt": 1726232498871,
"timestamp": 1726585978590,
"timestamp": 1729085978590,
"extras": {
"headers": {
"baz": "qux"
}
}
"serial": "01726232498871-001@abcdefghij:001",
"version": "01726585978590-001@abcdefghij:001"
"serial": "01726585978590-001@abcdefghij:001",
Copy link
Contributor

Choose a reason for hiding this comment

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

The createdAt should match the timestamp in the serial.

"version": "01729085978590-001@abcdefghij:001"
"action": "message.update"
"operation": {
"clientId": "who-performed-the-action",
Expand All @@ -654,7 +648,7 @@ h3(#rest-deleting-messages). Deleting Messages
h4(#rest-deleting-messages-request). Request

Below is the full REST payload format for the endpoint.

Note that @metadata@ is of type map<string, string>.
<pre>
POST /chat/v2/rooms/<roomId>/messages/<serial>/delete
{
Expand Down Expand Up @@ -692,16 +686,15 @@ h4(#rest-deleting-messages-request). Corresponding Realtime Event
}
}
},
"timestamp": "1726232498871",
"extras": {
"headers": {
"baz": "qux"
},
}
"createdAt": 1726232498871,
Copy link
Contributor

Choose a reason for hiding this comment

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

The timestamp here should match that in the serial.

"serial": "01726585978590-001@abcdefghij:001",
"action": "message.deleted"
"timestamp": 1826232498871
"createdAt": 1726585978590,
"action": "message.deleted",
"timestamp": 1826232498871,
"version": "01826232498871-001@abcdefghij:001",
"operation": {
"clientId": "who-performed-the-action",
Expand Down Expand Up @@ -849,9 +842,7 @@ h4(#chat-structs-message-v2). Messages V2
"clientId": "who-performed-the-action",
"description": "why-the-action-was-performed"
"metadata": {
"foo": {
"bar": 1
}
"foo": "bar"
},
}
}
Expand Down
Loading