From 5a741fb77b5943ae39ca521c8d32d3e1890bdc24 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 24 Jun 2020 10:25:41 +0100 Subject: [PATCH 01/11] Add placeholder proposal --- proposals/XXXX-unread-counts.md | 3 +++ 1 file changed, 3 insertions(+) create mode 100644 proposals/XXXX-unread-counts.md diff --git a/proposals/XXXX-unread-counts.md b/proposals/XXXX-unread-counts.md new file mode 100644 index 00000000000..aff99a2e536 --- /dev/null +++ b/proposals/XXXX-unread-counts.md @@ -0,0 +1,3 @@ +# MSCXXXX: Unread counts + +WIP From 01a326ea165c586ee7062ee61c14c446d4b20bad Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 24 Jun 2020 10:27:30 +0100 Subject: [PATCH 02/11] Use attributed MSC number --- proposals/2654-unread-counts.md | 3 +++ proposals/XXXX-unread-counts.md | 3 --- 2 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 proposals/2654-unread-counts.md delete mode 100644 proposals/XXXX-unread-counts.md diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md new file mode 100644 index 00000000000..e331b451c16 --- /dev/null +++ b/proposals/2654-unread-counts.md @@ -0,0 +1,3 @@ +# MSC2654: Unread counts + +WIP diff --git a/proposals/XXXX-unread-counts.md b/proposals/XXXX-unread-counts.md deleted file mode 100644 index aff99a2e536..00000000000 --- a/proposals/XXXX-unread-counts.md +++ /dev/null @@ -1,3 +0,0 @@ -# MSCXXXX: Unread counts - -WIP From 775bdb7493e03a880810386b67a82c1128f84e3b Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 29 Jun 2020 12:25:51 +0100 Subject: [PATCH 03/11] Proposal --- proposals/2654-unread-counts.md | 89 ++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 1 deletion(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index e331b451c16..40931b2862d 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -1,3 +1,90 @@ # MSC2654: Unread counts -WIP +Homeservers currently send clients counts for missed notifications (and +highlights) in responses to `/sync` requests, which allows them to display that +information to clients. However, when it comes to unread messages, it doesn't +provide a count. This means clients have no way of telling users how many +messages they've missed since they last read a given room. + +This MSC is an alternative to +[MSC2625](https://github.com/matrix-org/matrix-doc/pull/2625) which doesn't use +push rules to calculate unread counts, allowing for simpler implementations. + + +## Proposal + + +### Extended response to `/sync` + +This MSC proposes the addition of an `unread_count` parameter in the `Joined +Room` structure of +[`/sync`](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-sync) +responses. + +The value of this parameter is a count of every unread event (see below for a +list of criteria an event needs to match to be marked unread) since the latest +read receipt (i.e. the latest `m.read` read marker) for the given user in the +given room. If no read receipt exists for this user in this room, then the value +of the parameter is a count of every unread event since that user joined it. + + +### Unread events + +An event should be counted in the unread count only if it matches at least one +of the following criteria: + +* include a non-empty `body` parameter in its content +* be a state event which type is one of: + * `m.room.name` + * `m.room.topic` + * `m.room.power_levels` +* be an encrypted message (i.e. have the `m.room.encrypted` type) + +Additionally, an event should _not_ be counted in the unread count if it matches +at least one of the following criteria, even if it is otherwise eligible to be +included in the count: + +* include a `m.relates_to` parameter in its content that includes a `rel_type` + parameter, which value is `m.replace`. This matches the definition of an edit + in [MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). +* include a `msgtype` parameter in its content which value is `m.notice`. + +Finally, a redaction to an event that was marked as unread should exclude that +event from the unread count. + + +### Implementation notes on `POST /_matrix/push/v1/notify` + +As homeservers weren't previously calculating unread counts, missed +notifications counts were usually used to calculate the the `unread` parameter +of the `Counts` structure of [`POST +/_matrix/push/v1/notify`](https://matrix.org/docs/spec/push_gateway/latest#post-matrix-push-v1-notify) +requests. This parameter must now show the unread count described in this +proposal. + + +## Potential issues + +This MSC mentions edits, which are specified in +[MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). Therefore, it is +unclear whether this MSC can be merged before MSC1849. + + +## Alternatives + +As mentioned in the introduction of this proposal, +[MSC2625](https://github.com/matrix-org/matrix-doc/pull/2625) proposes an +alternative implementation of this feature using push rules. However, given the +complexity of push rules and that MSC2625 requires to implement a new behaviour +for the `mark_unread` action, using push rules for this feature doesn't seem to +be adding much values, and seems to add unnecessary complexity to its +implementation. + + +## Unstable prefix + +While this feature is in development, the following names will be in use: + +| Proposed final name | Name while in development | +| --- | --- | +| `unread_count` | `org.matrix.msc2654.unread_count` | From 5928ff2d5faf465394bfdfa9269943b7ff090846 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 30 Jun 2020 17:24:44 +0100 Subject: [PATCH 04/11] Incorporate review --- proposals/2654-unread-counts.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index 40931b2862d..3152b40980a 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -2,12 +2,12 @@ Homeservers currently send clients counts for missed notifications (and highlights) in responses to `/sync` requests, which allows them to display that -information to clients. However, when it comes to unread messages, it doesn't -provide a count. This means clients have no way of telling users how many -messages they've missed since they last read a given room. +information to clients. However, no count is provided for unread messages. This +means clients have no way of telling users how many messages they've missed +since they last read a given room. This MSC is an alternative to -[MSC2625](https://github.com/matrix-org/matrix-doc/pull/2625) which doesn't use +[MSC2625](https://github.com/matrix-org/matrix-doc/pull/2625), which doesn't use push rules to calculate unread counts, allowing for simpler implementations. @@ -47,7 +47,8 @@ included in the count: * include a `m.relates_to` parameter in its content that includes a `rel_type` parameter, which value is `m.replace`. This matches the definition of an edit in [MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). -* include a `msgtype` parameter in its content which value is `m.notice`. +* have the type `m.room.message` and include a `msgtype` parameter in its + content which value is `m.notice`. Finally, a redaction to an event that was marked as unread should exclude that event from the unread count. From 4a9d8aa89d2b6af8977065a522b91ce40ad1a9b3 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 2 Jul 2020 11:39:15 +0100 Subject: [PATCH 05/11] Incorporate review --- proposals/2654-unread-counts.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index 3152b40980a..b87fc831f3f 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -17,7 +17,7 @@ push rules to calculate unread counts, allowing for simpler implementations. ### Extended response to `/sync` This MSC proposes the addition of an `unread_count` parameter in the `Joined -Room` structure of +Room` section of [`/sync`](https://matrix.org/docs/spec/client_server/r0.6.1#get-matrix-client-r0-sync) responses. @@ -27,17 +27,22 @@ read receipt (i.e. the latest `m.read` read marker) for the given user in the given room. If no read receipt exists for this user in this room, then the value of the parameter is a count of every unread event since that user joined it. +In case of a mismatch between this count and the value of `notification_count` +in the `Unread Notification Counts` section, clients should use the +`unread_count`. + ### Unread events An event should be counted in the unread count only if it matches at least one of the following criteria: -* include a non-empty `body` parameter in its content +* include a non-empty `body` parameter, which value is a string, in its content * be a state event which type is one of: * `m.room.name` * `m.room.topic` * `m.room.power_levels` + * `m.room.avatar` * be an encrypted message (i.e. have the `m.room.encrypted` type) Additionally, an event should _not_ be counted in the unread count if it matches @@ -47,12 +52,15 @@ included in the count: * include a `m.relates_to` parameter in its content that includes a `rel_type` parameter, which value is `m.replace`. This matches the definition of an edit in [MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). -* have the type `m.room.message` and include a `msgtype` parameter in its - content which value is `m.notice`. +* have the type `m.room.message`, no `state_key`, and include a `msgtype` + parameter in its content which value is `m.notice`. Finally, a redaction to an event that was marked as unread should exclude that event from the unread count. +If the event is an encrypted message, clients should decrypt it and apply the +rules above to make adjustments to the unread count sent by the homeserver. + ### Implementation notes on `POST /_matrix/push/v1/notify` @@ -70,6 +78,10 @@ This MSC mentions edits, which are specified in [MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). Therefore, it is unclear whether this MSC can be merged before MSC1849. +Unlike notifications, it is not possible to not have the homeserver provide an +unread count for a given room. A way to do this will be described in a separate +MSC. + ## Alternatives From 928a8dff2efbd77064e3320d12b117a69f8169f4 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Mon, 6 Jul 2020 12:41:00 +0100 Subject: [PATCH 06/11] Mention that users shouldn't get their unread count up'd by their own messages --- proposals/2654-unread-counts.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index b87fc831f3f..33f70f251de 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -58,6 +58,9 @@ included in the count: Finally, a redaction to an event that was marked as unread should exclude that event from the unread count. +When calculating the unread count for a given user in a given room, events sent +by the requesting user in the room should be ignored. + If the event is an encrypted message, clients should decrypt it and apply the rules above to make adjustments to the unread count sent by the homeserver. From 550aa04caf1f495865b8eb4589fb2bdc116b8f48 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 29 Jul 2020 14:52:30 +0100 Subject: [PATCH 07/11] s/MSC1849/MSC2676/ Co-authored-by: Tulir Asokan --- proposals/2654-unread-counts.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index 33f70f251de..c1ae07f2fcf 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -51,7 +51,7 @@ included in the count: * include a `m.relates_to` parameter in its content that includes a `rel_type` parameter, which value is `m.replace`. This matches the definition of an edit - in [MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). + in [MSC2676](https://github.com/matrix-org/matrix-doc/pull/2676). * have the type `m.room.message`, no `state_key`, and include a `msgtype` parameter in its content which value is `m.notice`. @@ -78,8 +78,8 @@ proposal. ## Potential issues This MSC mentions edits, which are specified in -[MSC1849](https://github.com/matrix-org/matrix-doc/pull/1849). Therefore, it is -unclear whether this MSC can be merged before MSC1849. +[MSC2676](https://github.com/matrix-org/matrix-doc/pull/2676). Therefore, it is +unclear whether this MSC can be merged before MSC2676. Unlike notifications, it is not possible to not have the homeserver provide an unread count for a given room. A way to do this will be described in a separate From 5bbc8af7ee9f66c0d8468d18d918b9610c9e406a Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 29 Jul 2020 15:40:40 +0100 Subject: [PATCH 08/11] Update proposals/2654-unread-counts.md Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- proposals/2654-unread-counts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index c1ae07f2fcf..801b6e9399d 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -37,7 +37,7 @@ in the `Unread Notification Counts` section, clients should use the An event should be counted in the unread count only if it matches at least one of the following criteria: -* include a non-empty `body` parameter, which value is a string, in its content +* include a non-empty `body` field of type string, in its content * be a state event which type is one of: * `m.room.name` * `m.room.topic` From 2de035f08d9ed765fa2c24c3367be3dfb24ba609 Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Wed, 29 Jul 2020 16:09:25 +0100 Subject: [PATCH 09/11] Update the list of state events to count unread Added tombstone, removed power levels --- proposals/2654-unread-counts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index 33f70f251de..55dbb58e41c 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -41,8 +41,8 @@ of the following criteria: * be a state event which type is one of: * `m.room.name` * `m.room.topic` - * `m.room.power_levels` * `m.room.avatar` + * `m.room.tombstone` * be an encrypted message (i.e. have the `m.room.encrypted` type) Additionally, an event should _not_ be counted in the unread count if it matches From 793363944aae84c560005d3a16b721cc92603dac Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Thu, 10 Sep 2020 18:24:36 +0100 Subject: [PATCH 10/11] Remove implementation notes on /notify This actually leads to a pretty confusing UX. We might revert that in the future, but probably not as part of this MSC. --- proposals/2654-unread-counts.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index e3252ea0603..8d912418917 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -65,16 +65,6 @@ If the event is an encrypted message, clients should decrypt it and apply the rules above to make adjustments to the unread count sent by the homeserver. -### Implementation notes on `POST /_matrix/push/v1/notify` - -As homeservers weren't previously calculating unread counts, missed -notifications counts were usually used to calculate the the `unread` parameter -of the `Counts` structure of [`POST -/_matrix/push/v1/notify`](https://matrix.org/docs/spec/push_gateway/latest#post-matrix-push-v1-notify) -requests. This parameter must now show the unread count described in this -proposal. - - ## Potential issues This MSC mentions edits, which are specified in From d4d19a8f68609953998907a4863782c7cfeed73a Mon Sep 17 00:00:00 2001 From: Brendan Abolivier Date: Tue, 5 Apr 2022 11:28:50 +0100 Subject: [PATCH 11/11] Add mention about highlight related limitation --- proposals/2654-unread-counts.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md index 8d912418917..769d1be1f5a 100644 --- a/proposals/2654-unread-counts.md +++ b/proposals/2654-unread-counts.md @@ -75,6 +75,13 @@ Unlike notifications, it is not possible to not have the homeserver provide an unread count for a given room. A way to do this will be described in a separate MSC. +A known limitation of this proposal is that it does not cover highlights: a message +containing text that is supposed to highlight (i.e. that should impact a +`highlight_count` counter in sync responses) will be counted in the same way as +a message that does not highlight. This means that clients cannot rely on the +`unread_count` field described in this proposal to decide whether there is a +highlighting message in a room. + ## Alternatives