From 2a73041f06838a3b6b34eedd6ef586dc10a1cb9a Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Mon, 21 Aug 2023 11:37:26 -0600 Subject: [PATCH] MSC3930: Polls push rules/notifications (#3930) * Split poll notifications out to their own MSC * Assign number * Update proposals/3930-polls-notifications.md * Change sync behaviour; Add links; Account for room versions * spelling * Update proposals/3930-polls-notifications.md Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> * Clarity around rule order * spelling * Use modern push rule practices * More using of modern push rule practices --------- Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> --- proposals/3930-polls-notifications.md | 143 ++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 proposals/3930-polls-notifications.md diff --git a/proposals/3930-polls-notifications.md b/proposals/3930-polls-notifications.md new file mode 100644 index 00000000..c40fd10d --- /dev/null +++ b/proposals/3930-polls-notifications.md @@ -0,0 +1,143 @@ +# MSC3930: Polls push rules/notifications + +[MSC3381](https://github.com/matrix-org/matrix-spec-proposals/pull/3381) describes how chat polls can work, +though deliberately leaves out details on how push rules or notifications could work for such a feature. +This proposal aims to address that specific feature gap. + +Readers should review MSC3381 to better understand how polls are intended to operate in a room. + +Push rules are currently defined [here](https://spec.matrix.org/v1.7/client-server-api/#push-rules) in +specification. + +## Proposal + +Polls should behave similar to message events. To achieve this effect, we define the following underride +push rules which mimic their `m.room.message` partners. + +Note that [order matters](https://github.com/matrix-org/matrix-spec/issues/1406) for push rules - these +underride rules are to be inserted immediately after the `.m.rule.encrypted` underride push rule, in the +order presented by this MSC. + +```jsonc +{ + "rule_id": ".m.rule.poll_start_one_to_one", + "default": true, + "enabled": true, + "conditions": [ + {"kind": "room_member_count", "is": "2"}, + + // Note: `.` is escaped once, but for valid JSON we need to escape the escape. + {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.start"} + ], + "actions": [ + "notify", + {"set_tweak": "sound", "value": "default"} + ] +} +``` + +```jsonc +{ + "rule_id": ".m.rule.poll_start", + "default": true, + "enabled": true, + "conditions": [ + // Note: `.` is escaped once, but for valid JSON we need to escape the escape. + {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.start"} + ], + "actions": [ + "notify" + ] +} +``` + +```jsonc +{ + "rule_id": ".m.rule.poll_end_one_to_one", + "default": true, + "enabled": true, + "conditions": [ + {"kind": "room_member_count", "is": "2"}, + + // Note: `.` is escaped once, but for valid JSON we need to escape the escape. + {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.end"} + ], + "actions": [ + "notify", + {"set_tweak": "sound", "value": "default"} + ] +} +``` + +```jsonc +{ + "rule_id": ".m.rule.poll_end", + "default": true, + "enabled": true, + "conditions": [ + // Note: `.` is escaped once, but for valid JSON we need to escape the escape. + {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.end"} + ], + "actions": [ + "notify" + ] +} +``` + +Additionally, a new override rule is defined to suppress poll responses by default, inserted immediately +after the `.m.rule.room.server_acl` override rule. + +```jsonc +{ + "rule_id": ".m.rule.poll_response", + "default": true, + "enabled": true, + "conditions": [ + // Note: `.` is escaped once, but for valid JSON we need to escape the escape. + {"kind": "event_property_is", "key": "type", "value": "m\\.poll\\.response"} + ], + "actions": [] +} +``` + +*Note*: Lack of `actions` means "don't do anything with matching events", or "don't notify". + +Typically these rules would be kept in sync with the `m.room.message` rules they are based upon, +however there is no requirement to do so. A client's approach might be to only keep them in sync +while setting the values, rather than monitoring for changes to push rules. + +Clients might find [MSC3934](https://github.com/matrix-org/matrix-spec-proposals/pull/3934) of value +for keeping the rules in sync, though this MSC does not require MSC3934. + +For the purposes of [MSC3932](https://github.com/matrix-org/matrix-spec-proposals/pull/3932), the +push rules defined in this proposal are *not* affected by the room version limitations. This is due +to polls not inherently being room version-specific, unlike other extensible event structures. For +clarity, this means the push rules described here are treated the same as `.m.rule.master` (for +example) - they always apply, regardless of room version. + +## Potential issues + +The push rules for this feature are complex and not ideal. The author believes that it solves a short +term need while other MSCs work on improving the notifications system. Most importantly, the author +believes future MSCs which aim to fix notifications for extensible events in general will be a more +preferred approach over this MSC's (hopefully) short-term solution. + +## General considerations + +While the order within the MSC is deliberate for the new rules, the positioning relative to other rules +already in the spec is fairly arbitrary. The new rules are placed at the end of each list (underride and +override) for simplicity, but could realistically go anywhere in the list. + +See ["Dot-separated property paths"](https://spec.matrix.org/v1.7/appendices/#dot-separated-property-paths) +for more information on why we escape the `event_property_is` condition values. + +## Security considerations + +None applicable - no new considerations need to be made with this proposal. + +## Unstable prefix + +While this MSC is not considered stable, implementations should use `org.matrix.msc3930.*` as a prefix +in place of `m.*` for the push rule IDs. As of writing, polls are only implemented using the legacy +`org.matrix.msc3381.poll.*` prefix rather than the newer `v2` prefix - implementations of this MSC +should be aware of which version of MSC3381 they plan to support.