MSC3772: Push rule for mutually related events

proposals/3772-push-rules-for-mutually-relationed-events.md

@@ -0,0 +1,235 @@
+# MSC3772: Push rule for mutually related events
+
+It is useful for users to be able to control getting notified for events which
+relate to events they have shown interest in. This is useful if:
+
+* Another user replies to a thread the user has also replied to, i.e. the user has
+  participated in a thread and wants to know when others respond.
+* Another user has voted in a poll the user has voted in, i.e. the user wants to
+  know the results of a poll as people vote for it.
+
+## Proposal
+
+## New push rule condition: ``relation_match``
+
+A new [push rule condition](https://spec.matrix.org/v1.2/client-server-api/#conditions-1)
+is proposed to match against other events which relate to the same event as the
+current event. Unlike [MSC3664](https://github.com/matrix-org/matrix-spec-proposals/pull/3664),
+which matches against the *related event*, this proposes matching against *other events
+with the same relation*. Such a condition could look like this:
+
+```json
+{
+  "kind": "relation_match",
+  "rel_type": "m.thread",
+  "sender": "@me:my.server"
+}
+```
+
+This condition matches whenever someone sends a reply to a thread that `@me:my.server`
+has also replied to. For example, if there's a thread on event `A` and
+`@me:my.server` has sent event `B`, the rule would match event `C` sent from
+another user.
+
+```mermaid
+flowchart RL
+    C-->A
+    B-->A
+```
+
+The condition can include the following fields to check:
+
+* `rel_type`: The relation type of the mutually related event to the parent event.
+* `sender` (optional): A glob pattern to match against the sender of the mutually
+  related event.
+* `type` (optional): A glob pattern to match against the type of the mutually
+  related event.
+
+Another example would be to be notified of a poll closing (from
+[MSC3381](https://github.com/matrix-org/matrix-spec-proposals/pull/3381)), but
+only if the user has voted in it:
+
+```json
+[
+  {
+    "kind": "event_match",
+    "key": "type",
+    "pattern": "m.poll.end"
+  },
+  {
+    "kind": "relation_match",
+    "rel_type": "m.reference",
+    "sender": "@me:my.server",
+    "type": "m.poll.response"
+  }
+]
+```
+
+(Note that the `type` is important since `m.reference` is used in multiple contexts,
+see [MSC3267](https://github.com/matrix-org/matrix-doc/pull/3267).)
+
+A client can check for the `relation_match` condition being supported by testing
+for an existing `.m.rule.thread_reply` in the default rules (see below).
+
+Matching is done on a best effort basis: when evaluating the push rule against an
+event, if the server (or client) doesn't know of any other events which meet the
+specified conditions than the rule should not be matched and processing continues
+with the next push rule.
+
+### A push rule for threads
+
+For users to easily track notification of threads they have participated in (as
+defined in [MSC3816](https://github.com/matrix-org/matrix-spec-proposals/pull/3816))
+the following default push rules are proposed.
+
+Each rule should be a [default underride rule](https://spec.matrix.org/latest/client-server-api/#default-underride-rules),
+since it isn't a content rule and should be overridden when setting a room to
+mentions only. They should be placed just before `.m.rule.message` in the list.
+This ensures you get notified for replies to threads you're interested in. The
+actions are the same as for `.m.rule.message` and `m.rule.encrypted`.
+
+Note that an encrypted form of these rules are not needed since the relation
+information and metadata required for these rules to function is not encrypted.
+
+#### Threaded replies to the user's message
+
+To receive notification that there is a reply to a thread that has the user's
+message as the root message. (Note that this uses `related_event_match` from
+[MSC3664](https://github.com/matrix-org/matrix-spec-proposals/pull/3664).)
+
+```json5
+{
+  "rule_id": ".m.rule.thread_reply_to_me",
+  "default": true,
+  "enabled": true,
+  "conditions": [
+    {
+      "kind": "related_event_match", // from MSC3664
+      "rel_type": "m.thread",
+      "key": "sender",
+      "pattern": "@me:my.server"
+    }
+  ],
+  "actions": [
+    "notify"
+  ]
+}
+```
+
+#### Replies to threads the user has replied to
+
+To receive notification when there is a reply to a thread that the user has also
+replied to.
+
+```json5
+{
+  "rule_id": ".m.rule.thread_reply",
+  "default": true,
+  "enabled": true,
+  "conditions": [
+    {
+      "kind": "relation_match",
+      "rel_type": "m.thread",
+      "sender": "@me:my.server"
+    }
+  ],
+  "actions": [
+    "notify"
+  ]
+}
+```
+
+## Potential issues
+
+### Performance
+
+Most push rules for mutually related events will need a lookup into metadata on
+other events. This causes additional implementation complexity and can potentially
+be expensive. The fields available for the `relation_match` are chosen to be event
+and relation metadata to avoid requiring evaluation against the event contents
+of many events.
+
+### Client implementation
+
+This may be difficult for clients to implement (as they may not know every related
+event without fetching many events locally), but for the default case of matching
+against the sender's events it should be reasonable to implement.
+
+Additionally, it should be possible to implement this for encrypted rooms server
+side due to [event relations not being encrypted](https://github.com/matrix-org/matrix-spec/issues/660).
+There may not be enough information for a client to understand why an unread
+notification came from a relation, however.
+
+### Updating default push rules
+
+As mentioned in [MSC3664](https://github.com/matrix-org/matrix-spec-proposals/pull/3664),
+adding a new rule could cause notifications for users who have previously disabled
+notifications. This is made worse by clients potentially not yet having UI to
+disable the notifications. Overall it is seen as an improvement that allows users
+to have finger grain control of notifications in threads.
+
+## Alternatives
+
+### Alternative to push rules
+
+There have been thoughts to replace push rules (see [MSC2785](https://github.com/matrix-org/matrix-spec-proposals/pull/2785))
+or to circumvent them (see [MSC2654](https://github.com/matrix-org/matrix-spec-proposals/pull/2654))
+for some notification work, but since they are the current system used for notification
+it seems prudent to build on top of them instead of blocking behind work that is
+not finished.
+
+### `sender` field
+
+The examples are only relevant when the current user also has a relation to same
+parent event as the event being processed. This proposal could be simplified to
+require that instead of having a `sender` field. This would reduce flexibility,
+while not dramatically simplifying implementation.
+
+### Manually subscribing to interesting threads
+
+An alternative could be for clients to manually subscribe to threads that the
+user replies to, which is possible today:
+
+```json
+[
+  {
+    "kind": "event_match",
+    "key": "content.relates_to.rel_type",
+    "pattern": "m.thread"
+  },
+  {
+    "kind": "event_match",
+    "key": "content.relates_to.event_id",
+    "pattern": "$thread_root"
+  }
+]
+```
+
+This could cause a significant number of push rules to be added for a user which
+interacts with many threads.
+
+## Security considerations
+
+N/A
+
+## Unstable prefix
+
+While this feature is in development the following unstable prefixes should be used:
+
+* `relation_match` --> `org.matrix.msc3772.relation_match`
+* `.m.rule.thread_reply_to_me` --> `.org.matrix.msc3772.thread_reply_to_me`
+* `.m.rule.thread_reply` --> `.org.matrix.msc3772.thread_reply`
+
+## Dependencies
+
+This MSC depends on the following MSCs, which at the time of writing have not yet
+been accepted into the spec:
+
+* [MSC3664](https://github.com/matrix-org/matrix-spec-proposals/pull/3664): Pushrules for relations
+* [MSC3816](https://github.com/matrix-org/matrix-spec-proposals/pull/3816): Clarify Thread Participation
+
+This MSC depends on the following MSCs, which have been accepted into the spec,
+but have yet to be released:
+
+* [MSC2674](https://github.com/matrix-org/matrix-doc/pull/2674): Event Relationships
+* [MSC3440](https://github.com/matrix-org/matrix-spec-proposals/pull/3440): Threading via `m.thread` relation