From ba18feb00feb7ba91e4429d12cbb62af8f17bbfb Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 27 Sep 2022 13:33:40 -0600 Subject: [PATCH] Various clarifications per review --- .../server_server/newsfragments/1255.feature | 1 + content/client-server-api/modules/receipts.md | 33 ++++++++++++------- .../definitions/event-schemas/m.receipt.yaml | 9 +++++ data/event-schemas/schema/m.receipt.yaml | 1 + 4 files changed, 33 insertions(+), 11 deletions(-) create mode 100644 changelogs/server_server/newsfragments/1255.feature diff --git a/changelogs/server_server/newsfragments/1255.feature b/changelogs/server_server/newsfragments/1255.feature new file mode 100644 index 00000000..a1d15d98 --- /dev/null +++ b/changelogs/server_server/newsfragments/1255.feature @@ -0,0 +1 @@ +Add per-thread notifications and read receipts, as per [MSC3771](https://github.com/matrix-org/matrix-spec-proposals/pull/3771) and [MSC3773](https://github.com/matrix-org/matrix-spec-proposals/pull/3773). \ No newline at end of file diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index a13e2f9f..7fdde0d0 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -93,6 +93,12 @@ room that the event was sent to or dismissing a notification in order for the event to count as "read". Clients SHOULD NOT send read receipts for events sent by their own user. +Similar to the rules for sending receipts, threaded receipts should appear +in the context of the thread. If a thread is rendered behind a disclosure, +the client hasn't yet shown the event (or any applicable read receipts) +to the user. Once they expand the thread though, a threaded read receipt +would be sent and per-thread receipts from other users shown. + A client can update the markers for its user by interacting with the following HTTP APIs. @@ -129,16 +135,22 @@ several messages behind the `m.read.private` receipt, for example. If a client does not use [threading](#threading), then they will simply only send "unthreaded" read receipts which affect the whole room regardless of threads. -Threading introduces a concept of multiple conversations being held in the same -room and thus deserve their own read receipts and notification counts. An event -is considered to be "in a thread" if it has either a `rel_type` of `m.thread` or -has child events with a `rel_type` of `m.thread` (in which case it'd be the -thread root). Events not in a thread but still in the room are considered to be -part of the "main timeline", or a special thread with an ID of `main`. - A threaded read receipt is simply one which has a `thread_id` on it, targeting either a thread root's event ID or `main` for the main timeline. +Threading introduces a concept of multiple conversations being held in the same +room and thus deserve their own read receipts and notification counts. An event is +considered to be "in a thread" if it meets any of the following criteria: +* It has a `rel_type` of `m.thread`. +* It has child events with a `rel_type` of `m.thread` (in which case it'd be the + thread root). +* Following the event relationships, it has a parent event which qualifies for + one of the above. Implementations should not recurse infinitely, though: a + maximum of 3 hops is recommended to cover indirect relationships. + +Events not in a thread but still in the room are considered to be part of the +"main timeline", or a special thread with an ID of `main`. + The following is an example DAG for a room, with dotted lines showing event relationships and solid lines showing topological ordering. @@ -195,10 +207,9 @@ The read receipts for the above 3 examples would be: } ``` -Conditions on sending read receipts, such as using private read receipts, only -sending once an event is display, not being able to move backwards in time, etc -still apply to threaded and unthreaded read receipts. For example, a client might -send a private read receipt for a threaded event when the user expands that thread. +Conditions on sending read receipts apply similarly to threaded and unthreaded read +receipts. For example, a client might send a private read receipt for a threaded +event when the user expands that thread. #### Server behaviour diff --git a/data/api/server-server/definitions/event-schemas/m.receipt.yaml b/data/api/server-server/definitions/event-schemas/m.receipt.yaml index 335e7c27..bbc3ac67 100644 --- a/data/api/server-server/definitions/event-schemas/m.receipt.yaml +++ b/data/api/server-server/definitions/event-schemas/m.receipt.yaml @@ -65,6 +65,15 @@ allOf: A POSIX timestamp in milliseconds for when the user read the event specified in the read receipt. example: 1533358089009 + thread_id: + type: string + x-addedInMatrixVersion: "1.4" + description: |- + The root thread event's ID (or `main`) for which + thread this receipt is intended to be under. If + not specified, the read receipt is *unthreaded* + (default). + example: "$threadroot" required: ['ts'] required: ['event_ids', 'data'] required: ['m.read'] diff --git a/data/event-schemas/schema/m.receipt.yaml b/data/event-schemas/schema/m.receipt.yaml index bde3d40c..c501d022 100644 --- a/data/event-schemas/schema/m.receipt.yaml +++ b/data/event-schemas/schema/m.receipt.yaml @@ -40,6 +40,7 @@ properties: description: The timestamp the receipt was sent at. thread_id: type: string + x-addedInMatrixVersion: "1.4" description: |- The root thread event's ID (or `main`) for which thread this receipt is intended to be under. If