Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

MSC3772: Push rule for mutually related events #3772

Closed
wants to merge 15 commits into from
209 changes: 209 additions & 0 deletions proposals/3772-push-rules-for-mutually-relationed-events.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
# 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 is
interested 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.
* For "subscribing" to or "following" a thread or poll.[^1]
clokep marked this conversation as resolved.
Show resolved Hide resolved

## Proposal

## New push rule condition: ``relation_match``

A new push rule condition is proposed to match against other events which relate
clokep marked this conversation as resolved.
Show resolved Hide resolved
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 the *relation
of other events*. Such a condition could look like this:
clokep marked this conversation as resolved.
Show resolved Hide resolved

```json
{
"kind": "relation_match",
"rel_type": "m.thread",
"sender": "@me:my.server"
}
```

This condition can be used to notify me whenever someone sends a reply to a thread
that I have also replied to. For example, if there's a thread on event `A` and
I have sent event `B`, the rule could match event `C` 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 other event to the parent event.
* `sender` (optional): The sender of the other event.
* `type` (optional): The type of the other 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.)

For example, to match against any reply in a thread that the requester (`@me:my.server`)
has also replied to.
clokep marked this conversation as resolved.
Show resolved Hide resolved

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, when evaluating the push rule against an event
clokep marked this conversation as resolved.
Show resolved Hide resolved
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 interacted with the
following default push rule is proposed:

```json5
{
"rule_id": ".m.rule.thread_reply",
"default": true,
"enabled": true,
"conditions": [
{
"kind": "related_event_match", // from MSC3664
"rel_type": "m.thread",
"key": "sender",
"pattern": "@me:my.server"
},
{
"kind": "relation_match",
"rel_type": "m.thread",
"sender": "@me:my.server"
}
],
clokep marked this conversation as resolved.
Show resolved Hide resolved
"actions": [
"notify"
]
}
```

This matches:

* When 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).)
* When there is a reply to a thread that the user has also replied to.
clokep marked this conversation as resolved.
Show resolved Hide resolved

This should be an underride rule, since it can't be a content rule and should be
overridden when setting a room to mentions only. It 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 this rule is not needed since relation information
and metadata required for it to function is not encrypted.

## 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.
t3chguy marked this conversation as resolved.
Show resolved Hide resolved

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

All of the given examples are only relevant when the current user also has a
relation to same parent event as the current event being checked. This could be
assumed instead of having a `sender` field, but would be less flexible. For
example, it would not be possible to create a rule such as "notify me of any thread
which includes a poll in it".

## 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`
clokep marked this conversation as resolved.
Show resolved Hide resolved
clokep marked this conversation as resolved.
Show resolved Hide resolved

## 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

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

[^1]: This is already possible today, but it is a useful example to consider.
For threads which a user is interested in a push rule can be added with the
following condition:

```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"
}
]
```
clokep marked this conversation as resolved.
Show resolved Hide resolved