diff --git a/changelogs/client_server/newsfragments/1255.feature b/changelogs/client_server/newsfragments/1255.feature new file mode 100644 index 00000000..a1d15d98 --- /dev/null +++ b/changelogs/client_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/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/push.md b/content/client-server-api/modules/push.md index 5cce9449..9f9b30ac 100644 --- a/content/client-server-api/modules/push.md +++ b/content/client-server-api/modules/push.md @@ -107,8 +107,10 @@ determined by the push rules which apply to an event. When the user updates their read receipt (either by using the API or by sending an event), notifications prior to and including that event MUST -be marked as read. Note that users can send both an `m.read` and -`m.read.private` receipt, both of which are capable of clearing notifications. +be marked as read. Which specific events are affected can vary depending +on whether a [threaded read receipt](#threaded-read-receipts) was used. +Note that users can send both an `m.read` and `m.read.private` receipt, +both of which are capable of clearing notifications. If the user has both `m.read` and `m.read.private` set in the room then the receipt which is more recent/ahead must be used to determine where @@ -121,6 +123,17 @@ ahead), however if the `m.read.private` receipt were to be updated to event D then the user has read up to D (the `m.read` receipt is now behind the `m.read.private` receipt). +{{< added-in v="1.4" >}} When handling threaded read receipts, the server +is to partition the notification count to each thread (with the main timeline +being its own thread). To determine if an event is part of a thread the +server follows the [event relationship](#forming-relationships-between-events) +until it finds a thread root (as specified by the [threading module](#threading)), +however it is not recommended that the server traverse infinitely. Instead, +implementations are encouraged to do a maximum of 3 hops to find a thread +before deciding that the event does not belong to a thread. This is primarily +to ensure that future events, like `m.reaction`, are correctly considered +"part of" a given thread. + ##### Push Rules A push rule is a single rule that states under what *conditions* an diff --git a/content/client-server-api/modules/receipts.md b/content/client-server-api/modules/receipts.md index 9f80ff60..7fdde0d0 100644 --- a/content/client-server-api/modules/receipts.md +++ b/content/client-server-api/modules/receipts.md @@ -22,33 +22,68 @@ that the user had read all events *up to* the referenced event. See the [Receiving notifications](#receiving-notifications) section for more information on how read receipts affect notification counts. +{{< added-in v="1.4" >}} Read receipts exist in three major forms: +* Unthreaded: Denotes a read-up-to receipt regardless of threads. This is how + pre-threading read receipts worked. +* Threaded, main timeline: Denotes a read-up-to receipt for events not in a + particular thread. Identified by the thread ID `main`. +* Threaded, in a thread: Denotes a read-up-to receipt within a particular + thread. Identified by the event ID of the thread root. + +Threaded read receipts are discussed in further detail [below](#threaded-read-receipts). + #### Events -Each `user_id`, `receipt_type` pair must be associated with only a -single `event_id`. +{{< changed-in v="1.4" >}} Each `user_id`, `receipt_type`, and categorisation +(unthreaded, or `thread_id`) tuple must be associated with only a single +`event_id`. {{% event event="m.receipt" %}} #### Client behaviour +{{< changed-in v="1.4" >}} Altered to support threaded read receipts. + In `/sync`, receipts are listed under the `ephemeral` array of events for a given room. New receipts that come down the event streams are deltas which update existing mappings. Clients should replace older -receipt acknowledgements based on `user_id` and `receipt_type` pairs. +receipt acknowledgements based on `user_id`, `receipt_type`, and the +`thread_id` (if present). For example: Client receives m.receipt: user = @alice:example.com receipt_type = m.read event_id = $aaa:example.com + thread_id = undefined Client receives another m.receipt: user = @alice:example.com receipt_type = m.read event_id = $bbb:example.com + thread_id = main + + The client does not replace any acknowledgements, yet. + + Client receives yet another m.receipt: + user = @alice:example.com + receipt_type = m.read + event_id = $ccc:example.com + thread_id = undefined + + The client replaces the older acknowledgement for $aaa:example.com + with this new one for $ccc:example.com, but does not replace the + acknowledgement for $bbb:example.com because it belongs to a thread. - The client should replace the older acknowledgement for $aaa:example.com with - this one for $bbb:example.com + Client receives yet another m.receipt: + user = @alice:example.com + receipt_type = m.read + event_id = $ddd:example.com + thread_id = main + + Now the client replaces the older $bbb:example.com acknowledgement with + this new $ddd:example.com acknowledgement. The client does NOT replace the + older acknowledgement for $ccc:example.com as it is unthreaded. Clients should send read receipts when there is some certainty that the event in question has been **displayed** to the user. Simply receiving @@ -58,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. @@ -87,6 +128,89 @@ not have their notification counts rewound to that point in time. While uncommon, it is considered valid to have an `m.read` (public) receipt lag several messages behind the `m.read.private` receipt, for example. +##### Threaded read receipts + +{{% added-in v="1.4" %}} + +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. + +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. + +![threaded-dag](/diagrams/threaded-dag.png) + +{{% boxes/note %}} +`m.reaction` relationships are not currently specified, but are shown here for +their conceptual place in a threaded DAG. They are currently proposed as +[MSC2677](https://github.com/matrix-org/matrix-spec-proposals/pull/2677). +{{% /boxes/note %}} + +This DAG can be represented as 3 threaded timelines, with `A` and `B` being thread +roots: + +![threaded-dag-threads](/diagrams/threaded-dag-threads.png) + +With this, we can demonstrate that: +* A threaded read receipt on `I` would mark `A`, `B`, and `I` as read. +* A threaded read receipt on `E` would mark `C` and `E` as read. +* An unthreaded read receipt on `D` would mark `A`, `B`, `C`, and `D` as read. + +Note that marking `A` as read with a threaded read receipt would not mean +that `C`, `E`, `G`, or `H` get marked as read: Thread A's timeline would need +its own threaded read receipt at `H` to accomplish that. + +The read receipts for the above 3 examples would be: + +```json +{ + "$I": { + "m.read": { + "@user:example.org": { + "ts": 1661384801651, + "thread_id": "main" // because `I` is not in a thread, but is a threaded receipt + } + } + }, + "$E": { + "m.read": { + "@user:example.org": { + "ts": 1661384801651, + "thread_id": "$A" // because `E` is in Thread `A` + } + } + }, + "$D": { + "m.read": { + "@user:example.org": { + "ts": 1661384801651 + // no `thread_id` because the receipt is *unthreaded* + } + } + } +} +``` + +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 For efficiency, receipts SHOULD be batched into one event per room @@ -99,7 +223,7 @@ format of the EDUs are: { : { : { - : { } + : { } }, ... }, diff --git a/data/api/client-server/definitions/room_event_filter.yaml b/data/api/client-server/definitions/room_event_filter.yaml index 8d96a165..ab8ef79e 100644 --- a/data/api/client-server/definitions/room_event_filter.yaml +++ b/data/api/client-server/definitions/room_event_filter.yaml @@ -1,4 +1,5 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2022 The Matrix.org Foundation C.I.C. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -16,6 +17,12 @@ allOf: - type: object title: RoomEventFilter properties: + unread_thread_notifications: + type: boolean + description: |- + If `true`, enables per-[thread](/client-server-api/#threading) notification + counts. Only applies to the `/sync` endpoint. Defaults to `false`. + x-addedInMatrixVersion: "1.4" lazy_load_members: type: boolean description: |- diff --git a/data/api/client-server/sync.yaml b/data/api/client-server/sync.yaml index f8127bf5..93265cae 100644 --- a/data/api/client-server/sync.yaml +++ b/data/api/client-server/sync.yaml @@ -239,17 +239,50 @@ paths: Counts of unread notifications for this room. See the [Receiving notifications](/client-server-api/#receiving-notifications) section for more information on how these are calculated. + + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + these counts will only be for the main timeline rather than all events in the room. + See the [threading module](#threading) for more information. + x-changedInMatrixVersion: + 1.4: | + Updated to reflect behaviour of having `unread_thread_notifications` as `true` in + the `RoomEventFilter` for `/sync`. properties: highlight_count: title: Highlighted notification count type: integer description: The number of unread notifications - for this room with the highlight flag set + for this room with the highlight flag set. notification_count: title: Total notification count type: integer description: The total number of unread notifications - for this room + for this room. + unread_thread_notifications: + title: Unread Thread Notification Counts + type: object + description: |- + If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`, + the notification counts for each [thread](#threading) in this room. The object is + keyed by thread root ID, with values matching `unread_notifications`. + + If a thread does not have any notifications it can be omitted from this object. If + no threads have notification counts, this whole object can be omitted. + x-addedInMatrixVersion: "1.4" + additionalProperties: + title: ThreadNotificationCounts + type: object + properties: + highlight_count: + title: ThreadedHighlightNotificationCount + type: integer + description: |- + The number of unread notifications for this *thread* with the highlight flag set. + notification_count: + title: ThreadedTotalNotificationCount + type: integer + description: |- + The total number of unread notifications for this *thread*. invite: title: Invited Rooms type: object @@ -424,6 +457,16 @@ paths: } } ] + }, + "unread_notifications": { + "highlight_count": 1, + "notification_count": 5 + }, + "unread_thread_notifications": { + "$threadroot": { + "highlight_count": 3, + "notification_count": 6 + } } } }, 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 b9ec7e4e..c501d022 100644 --- a/data/event-schemas/schema/m.receipt.yaml +++ b/data/event-schemas/schema/m.receipt.yaml @@ -38,6 +38,14 @@ properties: type: integer format: int64 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 + not specified, the read receipt is *unthreaded* + (default). "m.read.private": type: object title: Own User diff --git a/static/diagrams/threaded-dag-threads.drawio b/static/diagrams/threaded-dag-threads.drawio new file mode 100644 index 00000000..2f3121d7 --- /dev/null +++ b/static/diagrams/threaded-dag-threads.drawio @@ -0,0 +1 @@ +7ZpdU+IwFIZ/DZc6bdNWuJQCujPquOvOrl452TbQaNowIXztr9+EJv0goLCirYwyo81JGpL3PQ8nU2mBIFlcMDiOr2mESMuxokUL9FqO41i+I/7IyDKL2JbvZZERw5GKFYE7/BfpgSo6xRGaVAZySgnH42owpGmKQl6JQcbovDpsSEn1XcdwhIzAXQiJGf2NIx5n0bZzVsQvER7F+p1tv5P1JFAPVjuZxDCi81II9FsgYJTy7CpZBIhI9bQu2X2DLb35whhK+S43/PIf6YMfPSfXNzfx1WP3ez/2ToDaxwySqdrxz5ghGInYudQaJ4jgFKkt8KXWhdFpGiE5td0C3XmMObobw1D2zkUqiFjME6K6hzTlA5hgIrPgEpEZ4jiEsgMTElBC2WpS0O/Jl4jPEJMjyDnBo1T0cTpW09ypJajty4FosVURO9dZZCiiCeJsKYbo9NTWqOT0dHteOO2c+acqY+Oyz201FKr8GuWzFxaIC+XCPo742x3pHrsjAFQdcS3TEdu3Nvhhv5sfruHHNcTpsTuRq7zUHJhO5G59jBO2YcS5If0rYsPJOCsSQ7yQBq2LHAR9byDW2D2Egp2qgsDeoOAGAcG76dc25EKRKHaqSRmP6YimkPSLaLeay8WYKyrTbhV8QpwvVeWGU06rkqMF5vfi2lLXD/JafKRmrd6i1NVb6kYq9nuvJ5CN0l2yWdy2aun7Kiz9FHhOxHZv0Fz8/kETmObGyn2/bKuQiU5ZiF7QUx1tOGQjxF/LWzNNGCKQ41l1HQc33TGg6TYZGsdvGDQueDM0T9NkrMenNEU1cFRC56GM1RaOCPyDSBeGz6PVTkpeDwL5eqlsHRAw8BkAAwZgwZsBOwRIbn5u1afbjlczSs4XSnWh5O6IklMnSuZJu9cElMBaTXLdumuSewwg7Xm2awhI3o4ggTpB8gyQ+o0AyW5eTbINYb5Q+iCU/B1RcutEyXwaN2gCSu76g7K6axLoGEIlpwzBkGOaHgNje577IjiJ8+XLxi3kHLF0FXEstzkYnr2toqmEPLFObfFTSUpbfbjvTKqa/ZZisYliCB0OJ2Jp6ymaL+L/s9b878dFE+g2C6Xv1lwoQXsD3yjC/BjY3rN+fh62Ozuy7dVZYs3KcdkECF3QvNOqZQhz/LQ1BCX9ILrZj1D0KkswfWsETO6HPdcXzeJLFdlBofhuCuj/Aw== \ No newline at end of file diff --git a/static/diagrams/threaded-dag-threads.png b/static/diagrams/threaded-dag-threads.png new file mode 100644 index 00000000..4cf865ed Binary files /dev/null and b/static/diagrams/threaded-dag-threads.png differ diff --git a/static/diagrams/threaded-dag.drawio b/static/diagrams/threaded-dag.drawio new file mode 100644 index 00000000..e481b875 --- /dev/null +++ b/static/diagrams/threaded-dag.drawio @@ -0,0 +1 @@ +7VpbU+IwFP41PMqkTS/wKDfdGXXcdWdXn5wsDTTaNkwIAvvrN6UJbYlCF1gbXcYZTU5P0ub0u6S1DdiNFxcMTcJrGuCoYYNg0YC9hm3bwLPFnzSyzCIW8NwsMmYkkLE8cEd+Y5UoozMS4GkpkVMacTIpB4c0SfCQl2KIMTovp41oVD7rBI2xFrgbokiP/iQBD7Noy/bz+CUm41Cd2fLa2ZEYqWS5kmmIAjovhGC/AbuMUp614kUXR2n1VF2ycYM3jq4vjOGEVxnww3ukD17wHF/f3IRXj52v/dA9k7O8oGgmF3wur5YvVQnmIeH4boKGaX8u7nMDdkIeR6JniSaaTrLCj8gCi3N15JSYcbx481qtdQUEdjCNMWdLkaIGQFk0BRtH9uf5PVApYaH8KobkXR+vZ84LIxqyNn9Tp5ZWFhwIoMguZTykY5qgqJ9HO4zOkiAtyapOec4VpRMZfMKcLyXq0YzTcmnxgvB70Qay/ZC2m67s9RaFQ72l6iRivfdqgrRTGJV282Grnho3ogkfoJhEaeA7iQXpbHCD5+L3NxqjZH1j03Vvv62iTHTGhnhLPaUscMTGmO/Cpw4ThiPEyUv5Oo5+022NHB0TyGED08jhn8hxTHLAiuSwayWHr7EjbvKQYRQcjIanWTxR+QlN8IEAadpuASNWNYSApu8WQWLtgEiApuF6AWnnFnGOWbKK2MAR0Qj9wlEHDZ/Hq+V2aUTZqkBw0E1/NoF2iaMXzMkQ1QOvWrUXaujqGqG9vmna2z5p7zHJ4VQkB6xVe52Po71F6QXVALIpvWAHQj6O9FZFV63OroOrZ4L0Qsc06XVP0ntMcrgVyeHUKr3ux5He/ba99ifd9laF13YVOgNNB/pSIitDbjXdOWNoWUiYUJLwaeFst2kgP5WjZpSCp577B2/kW7C1LV80sivYGK0uh45GU1GYTYKsS7A/Z3TK9E0wFMeCTdcwS3FOlnJMznsVOe/Wain6e0ZjLWWv3bz9SXfzVdF16G5+L/dwwYa27XAPG7S25Zfd41jO4GnIHxjhDG3THjXgyReOyVy/InO9Wn1BZ0fcFK4w5IQmRjvDf/+KvSq+Dn2LuJ8ztMrOoH04sOkMbbgt/984g/7fpQsTnME17v2/fZASgJMzlOvZrshcv1ZnAK84Aw4If7ddwrvq/puKXcEQpkIeSDL+vloMyAOi54LXbbCA8wp2UgP2an1abWvQuzRBmD3XNGG2tLKchPkAcqgPQneyo10nOyxdmb+YQA///T6oFN38o9ZsO5h/Gwz7fwA= \ No newline at end of file diff --git a/static/diagrams/threaded-dag.png b/static/diagrams/threaded-dag.png new file mode 100644 index 00000000..085d0f09 Binary files /dev/null and b/static/diagrams/threaded-dag.png differ