4.4 KiB
MSC2625: Add mark_unread push rule action
Push rule actions
affect how a homeserver delivers notifications for events matching a given push
rule. Homeservers also return the number of unread notifications in the /sync
response.
This approach conflates "unread messages" (aka the "badge count") and "messages that I want to be notified about". Users often want to see the count of unread messages increasing in a room view, without receiving a push notification for each such message.
This proposal suggests adding a new push rule action, and extending the /sync
response, to differentiate between these two cases.
Proposal
New push rule action
To the current list of Push rule
actions, we add
mark_unread, defined as:
mark_unread: This causes each matching event to contribute to the homeserver's count of unread messages in the room.
For compatibility with existing implementations, the notify action implies
mark_unread. Its definition is therefore updated to:
notify: This causes each matching event to generate a notification, as well as contributing to the homeserver's count of unread messages in the room.
For clarity then: an actions list of ["notify", "mark_unread"] is the same
as an actions list of just ["notify"].
(Aside: it may be helpful to note that the dont_notify action is a no-op: its
presence in the actions list has no effect on the actions of that rule. See also
https://github.com/matrix-org/matrix-doc/issues/2624.)
Extended response to /sync
In the response to
/sync,
within the Unread Notification Counts structure, we add a mandatory new field
unread_count, which gives the number of unread messages which matched a
mark_unread or notify push rule.
We expect the following inviariant to hold:
highlight_count <= notification_count <= unread_count
Clarification in the Push Gateway API spec
The _matrix/push/v1/notify
endpoint
includes a parameter notification.counts.unread, defined as "The number of
unread messages a user has across all of the rooms they are a member of."
Synapse uses a liberal interpretation of this definition (see
https://github.com/matrix-org/matrix-doc/issues/2627), but notwithstanding
that: this refers to unread messages (rather than notifications) and is
therefore affected by events which match match_unread rules.
Next steps
We expect a future MSC to change the specification of the default push rules so
that mark_unread is used in place of notify in certain places. That change
is not included in this MSC.
Potential issues
-
It seems counterintuitive that "push rules" are used to determine unread counts, and that this behaviour appears in the "push" section of the spec, when no "push" is involved at all. However, that is not a new problem, and the push rules engine actually fits the purpose quite well here.
Arguably the problem is in the naming of "push rules", where "event action rules" or similar might be more appropriate.
Alternatives
The push rules system is complicated: the multiple "kinds" of push rule, the long list of default rules, the fact that clients can change the behaviour of named push rules, etc. This complexity makes it hard to reason about, and makes it difficult for Matrix clients to (reliably) represent the user's current state in a comprehensible way. There is an argument that, rather than adding yet more complexity, we should either replace it or use a different mechanism for the new behaviour.
However, the change proposed here is incremental, and:
- a wholesale redesign would take a lot of time which would be better spent elsewhere.
- using an alternative mechanism would add complexity overall rather than reduce it.
Security considerations
None currently foreseen.
Unstable prefix
While this feature is in development, the following names will be in use:
| Proposed final name | Name while in development |
|---|---|
mark_unread |
org.matrix.msc2625.mark_unread |
unread_count |
org.matrix.msc2625.unread_count |
References
This document was based on an initial design at https://docs.google.com/document/d/1Fnh8sT_8hmWAZ_Yh9NaB8HI5occNfR4KyQ_NVdnXJzo.