From 4e2597a74e84c52c6290ac646e6cde9bd700ad57 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 15 Nov 2022 15:18:56 -0700 Subject: [PATCH 1/3] Core push rules for extensible events --- .../0000-extensible-events-push-rules-core.md | 246 ++++++++++++++++++ 1 file changed, 246 insertions(+) create mode 100644 proposals/0000-extensible-events-push-rules-core.md diff --git a/proposals/0000-extensible-events-push-rules-core.md b/proposals/0000-extensible-events-push-rules-core.md new file mode 100644 index 00000000000..9594af0a51b --- /dev/null +++ b/proposals/0000-extensible-events-push-rules-core.md @@ -0,0 +1,246 @@ +# MSC0000: Core push rules for Extensible Events + +[MSC1767](https://github.com/matrix-org/matrix-spec-proposals/pull/1767) covers a system for extending +events with alternative representations for maximally compatible content in Matrix, however does not +declare the exact push rules needed to replace the existing `m.room.message`-based ones. This proposal +defines those push rules. + +Only push rules for the following MSCs are considered - other MSCs, including possible future ones, are +expected to cover any other push rules needed for the extensible events system. + +* [MSC1767 - Text and Encryption](https://github.com/matrix-org/matrix-doc/pull/1767) +* [MSC3551 - Files](https://github.com/matrix-org/matrix-doc/pull/3551) +* [MSC3552 - Images and Stickers](https://github.com/matrix-org/matrix-doc/pull/3552) +* [MSC3553 - Videos](https://github.com/matrix-org/matrix-doc/pull/3553) +* [MSC3927 - Audio](https://github.com/matrix-org/matrix-doc/pull/3927) + +## Proposal + +[MSC1767](https://github.com/matrix-org/matrix-spec-proposals/pull/1767) already specifies that an +`event_match` condition of `content.body` actually inspects `m.markup`, and as such, we use that +functionality in this proposal. + +[A number of underride rules](https://spec.matrix.org/v1.4/client-server-api/#default-underride-rules) +already exist to cover `m.room.encrypted` and `m.room.message` events, and with these events being +split into several other event types it is important to maintain the same notification state for users +participating in extensible event-capable room versions. + +Using [MSC3931](https://github.com/matrix-org/matrix-spec-proposals/pull/3931) and +[MSC3932](https://github.com/matrix-org/matrix-spec-proposals/pull/3932), we define the following +additional underride push rules for users: + +**One-to-one (DM) rules** +```json5 +{ + // Inspired by `.m.rule.encrypted_room_one_to_one` + "rule_id": ".m.rule.extensible.encrypted_room_one_to_one", // note the `.extensible` part + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.encrypted" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` +```json5 +{ + // Inspired by `.m.rule.room_one_to_one` + "rule_id": ".m.rule.extensible.message.room_one_to_one", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.message" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` +```json5 +{ + // Inspired by `.m.rule.room_one_to_one` + "rule_id": ".m.rule.extensible.file.room_one_to_one", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.file" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` +```json5 +{ + // Inspired by `.m.rule.room_one_to_one` + "rule_id": ".m.rule.extensible.image.room_one_to_one", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.image" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` +```json5 +{ + // Inspired by `.m.rule.room_one_to_one` + "rule_id": ".m.rule.extensible.video.room_one_to_one", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.video" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` +```json5 +{ + // Inspired by `.m.rule.room_one_to_one` + "rule_id": ".m.rule.extensible.audio.room_one_to_one", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "room_member_count", "is": "2" }, + { "kind": "event_match", "key": "type", "pattern": "m.audio" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": [ + "notify", + { "set_tweak": "sound", "value": "default" } + ] +} +``` + +**Non-DM rules** +```json5 +{ + // Inspired by `.m.rule.encrypted` + "rule_id": ".m.rule.extensible.encrypted", // note the `.extensible` part + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.encrypted" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` +```json5 +{ + // Inspired by `.m.rule.message` + "rule_id": ".m.rule.extensible.message", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.message" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` +```json5 +{ + // Inspired by `.m.rule.message` + "rule_id": ".m.rule.extensible.file", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.file" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` +```json5 +{ + // Inspired by `.m.rule.message` + "rule_id": ".m.rule.extensible.image", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.image" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` +```json5 +{ + // Inspired by `.m.rule.message` + "rule_id": ".m.rule.extensible.video", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.video" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` +```json5 +{ + // Inspired by `.m.rule.message` + "rule_id": ".m.rule.extensible.audio", // note the `.extensible` part & event type reference + "default": true, + "enabled": true, + "conditions": [ + { "kind": "event_match", "key": "type", "pattern": "m.audio" }, // new event type + { "kind": "room_version_supports", "feature": "m.extensible_events" } // new condition + ], + "actions": ["notify"] +} +``` + +For clarity, clients are not required to represent each of these rules as individual toggles: they +can (and likely should) represent them all behind a single flag for better understanding for users. + +This MSC does not currently replace some other push rules, such as `.m.rule.call`, despite them +being impacted by Extensible Events - these are largely left for a future MSC. + +## Potential issues + +These rules are extremely verbose and relatively mechanical in nature, and further do not solve the +problem where a client might decide to render an unknown event like an image while not counting it +as a notification - while regrettable, this proposal defers a more sophisticated system to a later +MSC. + +## Alternatives + +More sophisticated approaches are likely possible. These are deferred to other MSCs - this proposal +aims to fill a gap as quickly as possible. + +## Security considerations + +No new security considerations as this simply takes existing rules and splits them down for extensible +events. However, server implementations may wish to relax rate limits on some push rule endpoints, like +[`PUT /enabled`](https://spec.matrix.org/v1.4/client-server-api/#put_matrixclientv3pushrulesscopekindruleidenabled) +and others used by clients to enable/alter push rules for bulk operations. An alternative to relaxing +rate limiting is to use [MSC0002](https://github.com/matrix-org/matrix-spec-proposals/pull/0002) or +similar instead. + +## Unstable prefix + +While this proposal is not considered stable, implementations should use `org.matrix.msc0000.*` in place +of `m.*`, noting that the event types themselves in the conditions might use a different unstable prefix. From 115407a837b78a3fa3116243c3ed7cda62554308 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 15 Nov 2022 15:56:49 -0700 Subject: [PATCH 2/3] Assign number --- ...ules-core.md => 3933-extensible-events-push-rules-core.md} | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename proposals/{0000-extensible-events-push-rules-core.md => 3933-extensible-events-push-rules-core.md} (99%) diff --git a/proposals/0000-extensible-events-push-rules-core.md b/proposals/3933-extensible-events-push-rules-core.md similarity index 99% rename from proposals/0000-extensible-events-push-rules-core.md rename to proposals/3933-extensible-events-push-rules-core.md index 9594af0a51b..5014a5b9f72 100644 --- a/proposals/0000-extensible-events-push-rules-core.md +++ b/proposals/3933-extensible-events-push-rules-core.md @@ -1,4 +1,4 @@ -# MSC0000: Core push rules for Extensible Events +# MSC3933: Core push rules for Extensible Events [MSC1767](https://github.com/matrix-org/matrix-spec-proposals/pull/1767) covers a system for extending events with alternative representations for maximally compatible content in Matrix, however does not @@ -242,5 +242,5 @@ similar instead. ## Unstable prefix -While this proposal is not considered stable, implementations should use `org.matrix.msc0000.*` in place +While this proposal is not considered stable, implementations should use `org.matrix.msc3933.*` in place of `m.*`, noting that the event types themselves in the conditions might use a different unstable prefix. From f0049c200742f8013365115824be5f1f770ca516 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 15 Nov 2022 16:11:45 -0700 Subject: [PATCH 3/3] Reference MSC3934 --- proposals/3933-extensible-events-push-rules-core.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3933-extensible-events-push-rules-core.md b/proposals/3933-extensible-events-push-rules-core.md index 5014a5b9f72..b6cd953b179 100644 --- a/proposals/3933-extensible-events-push-rules-core.md +++ b/proposals/3933-extensible-events-push-rules-core.md @@ -237,7 +237,7 @@ No new security considerations as this simply takes existing rules and splits th events. However, server implementations may wish to relax rate limits on some push rule endpoints, like [`PUT /enabled`](https://spec.matrix.org/v1.4/client-server-api/#put_matrixclientv3pushrulesscopekindruleidenabled) and others used by clients to enable/alter push rules for bulk operations. An alternative to relaxing -rate limiting is to use [MSC0002](https://github.com/matrix-org/matrix-spec-proposals/pull/0002) or +rate limiting is to use [MSC3934](https://github.com/matrix-org/matrix-spec-proposals/pull/3934) or similar instead. ## Unstable prefix