From 99f3da56cc14b1dcb4589413740347590f90a832 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 11 Dec 2024 10:02:04 -0300 Subject: [PATCH 1/5] chat: Remove curly braces in presence data example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit They make it look like you’re meant to nest something inside a JSON object. --- textile/chat-features.textile | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 28838f64..a569e311 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -344,9 +344,7 @@ Presence allows chat room users to indicate to others that they're online, as we 
   {
-    "userCustomData": {
-      // Some user specified type, does not have to be object.
-    }
+    "userCustomData": // Some user specified type, does not have to be object.
   }
From 5d4dbb97a9101984bd775fa3c0929afcd9baf29e Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 11 Dec 2024 10:00:55 -0300 Subject: [PATCH 2/5] chat: Be clearer about what type user can pass as presence data --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index a569e311..c00fe074 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -340,11 +340,11 @@ Presence allows chat room users to indicate to others that they're online, as we * @(CHA-PR1)@ Presence for a Room is exposed on the realtime channel used for chat messages, in the format @::$chat::$chatMessages@. For example, if your room id is @my-room@ then the presence channel will be @my-room::$chat::$chatMessages@. * @(CHA-PR2)@ The presence payload for Chat is opinionated, so that we may add or change fields later without needing to consider how customers are using presence. -** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify content of an arbitrary type to be placed in the @userCustomData@ field. +** @(CHA-PR2a)@ @[Testable]@ The presence data format is a JSON object as described below. Customers may specify an arbitrary "JSON @value@":https://www.json.org to be placed in the @userCustomData@ field. 
   {
-    "userCustomData": // Some user specified type, does not have to be object.
+    "userCustomData": // Any JSON `value`, does not have to be `object`.
   }
From 50b7c4111ae7fcf4652bd6fdeb9ba378adaeab60 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 11 Dec 2024 10:44:05 -0300 Subject: [PATCH 3/5] chat: Reference spec for presence data --- textile/chat-features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index c00fe074..8c368314 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -885,7 +885,7 @@ h3(#chat-structs-presence-member). Presence Member "clientId": "who-sent-the-message", "action": "enter", "updatedAt": DateTime(), - "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use. + "data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2. "extras": { "headers": { "baz": "qux" @@ -901,7 +901,7 @@ h3(#chat-structs-presence-event). Presence Event "clientId": "who-is-in-presence", "action": "enter", "timestamp": DateTime(), - "data": {}, // Whatever the user-provided data is. It must be destructured from the internal format we use. + "data": { … }, // A presence data object containing any user-provided data. The structure of this object is described by CHA-PR2. } From 13a8df298eb1be3343c19da10e0378dfb279bb81 Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 11 Dec 2024 10:47:39 -0300 Subject: [PATCH 4/5] chat: Clarify that you can pass data when leaving presence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit I’m treating this as a clarification rather than a new spec point, since it describes the behaviour of all of our current implementations of the Chat SDK. --- textile/chat-features.textile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/textile/chat-features.textile b/textile/chat-features.textile index 8c368314..4db42c1f 100644 --- a/textile/chat-features.textile +++ b/textile/chat-features.textile @@ -371,7 +371,7 @@ Presence allows chat room users to indicate to others that they're online, as we ** @(CHA-PR10f)@ This specification point has been removed. It was superseded by @CHA-PR10h@. ** @(CHA-PR10g)@ This specification point has been removed. It was superseded by @CHA-PR10h@. * @(CHA-PR4)@ Users may leave presence. -** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. +** @(CHA-PR4a)@ @[Testable]@ Users may choose to leave presence, which results in them being removed from the Realtime presence set. The user may optionally provide custom data to leave with. The overall presence data must retain the format specified in @CHA-PR2@. * @(CHA-PR5)@ @[Testable]@ It must be possible to query if a given clientId is in the presence set. * @(CHA-PR6)@ @[Testable]@ It must be possible to retrieve all the "@Members":#chat-structs-presence-member of the presence set. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches. ** @(CHA-PR6a)@ This clause has been replaced by @CHA-PR6b - CHA-PR6f@. From aa22f1ee3b1873a70d96f8a49c1f0586cdea095a Mon Sep 17 00:00:00 2001 From: Lawrence Forooghian Date: Wed, 11 Dec 2024 10:16:51 -0300 Subject: [PATCH 5/5] chat: Specify how to handle presence operation without custom data MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on the behaviour of JS at 69ea478. Note that the 
 is causing Textile to render CHA-PR2b in a separate

     to CHA-PR2a. I briefly tried various combinations of indentation,
didn’t get anywhere, and gave up trying to fix it.

Resolves #256.
---
 textile/chat-features.textile | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/textile/chat-features.textile b/textile/chat-features.textile
index 4db42c1f..03abef99 100644
--- a/textile/chat-features.textile
+++ b/textile/chat-features.textile
@@ -344,10 +344,11 @@ Presence allows chat room users to indicate to others that they're online, as we
 
 
       {
-    "userCustomData": // Any JSON `value`, does not have to be `object`.
+    "userCustomData": // Any JSON `value`, does not have to be `object`. This field may be absent; see CHA-PR2b.
   }
 
    
 
+** @(CHA-PR2b)@ @[Testable]@ If the user performs a presence operation (@CHA-PR3a@, @CHA-PR10a@, or @CHA-PR4a@) without providing any custom data (which, for the sake of clarity, we emphasise is _not_ the same as providing the JSON @value@ of @null@ as custom data, which is handled like any other JSON @value@ per @CHA-PR2a@), then the @userCustomData@ field must be omitted from the @CHA-PR2a@ presence data that gets sent.
 * @(CHA-PR3)@ Users may enter presence. The behaviour depends on the current room status, as presence operations in a Realtime Client cause implicit attaches.
 ** @(CHA-PR3a)@ @[Testable]@ Users may choose to enter presence, optionally providing custom data to enter with. The overall presence data must retain the format specified in @CHA-PR2@.
 ** @(CHA-PR3b)@ This clause has been replaced by @CHA-PR3c - CHA-PR3g@.