diff --git a/proposals/2654-unread-counts.md b/proposals/2654-unread-counts.md new file mode 100644 index 00000000000..769d1be1f5a --- /dev/null +++ b/proposals/2654-unread-counts.md @@ -0,0 +1,103 @@ +# MSC2654: Unread counts + +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, 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 +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` section 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. + +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` field of type string, in its content +* be a state event which type is one of: + * `m.room.name` + * `m.room.topic` + * `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 +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 [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`. + +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. + + +## Potential issues + +This MSC mentions edits, which are specified in +[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 +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 + +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` |