From ebe4900448b76cf99cdc8b706153ee4a404806ab Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Fri, 25 Mar 2022 20:30:11 +0000 Subject: [PATCH 01/11] Create xxxx-expand-push-rule-conditions.md --- proposals/xxxx-expand-push-rule-conditions.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 proposals/xxxx-expand-push-rule-conditions.md diff --git a/proposals/xxxx-expand-push-rule-conditions.md b/proposals/xxxx-expand-push-rule-conditions.md new file mode 100644 index 00000000000..4179d6b0007 --- /dev/null +++ b/proposals/xxxx-expand-push-rule-conditions.md @@ -0,0 +1,49 @@ +# MSCXXXX: Expand push rule conditions + +Currently the only condition used to match event content for push rules is the `event_match` kind. This compares a glob-style string against a string value within the event dictionary. The event dictionary is flattened before conditions are checked to enable mathing nested values. + +This approach is currently limited to only checking for string values within the event dictionary (at any level). This MSC brings makes two proposals to enable matching event content of any other JSON type within push rules. [MSC1796](https://github.com/matrix-org/matrix-spec-proposals/pull/1796) is an example change that would require this extended matching. + + +## Proposals + +### Exact matching event data + +We propose a new type of condition, `exact_event_match`. Similar to `event_match`, this condition takes two parameters: `pattern` and `key`. The exact match compares the `pattern` to the event data associated with `key` exactly. Both type and content (when a string) should be identical. This allows for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler exact string matching mechanism (and any associated performance gains on implementation side without globbing). + +An example condition may look like (encoded as a JSON object): + +```json +{ + "kind": "exact_event_match", + "key": "event.content.is_something", + "pattern": true +} +``` + +### Handling of lists within event data + +We propose that conditons simply match any value within a list. Conditions should be evaluated against every item in the list and return a match if any of the items meet the condition. For example an event: + +```json +{ + "content": { + "mentions": ["@user-a:beeper.com", "@user-b:beeper.com"] + } +} +``` + +The following condition would match: + +```json +{ + "kind": "event_match", + "key": "event.content.mentions", + "pattern": "@user-a:beeper.com" +} +``` + + +## Alternatives + +A new condition kind designed specifically for matching against lists could provide more options, such as specifying if one, all or some items must match. From 9f5d6c3a40a64ddca40a4e3ff303de78dab23320 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Sun, 27 Mar 2022 16:23:30 +0100 Subject: [PATCH 02/11] Rename to proper MSC number --- ...ush-rule-conditions.md => 3758-expand-push-rule-conditions.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename proposals/{xxxx-expand-push-rule-conditions.md => 3758-expand-push-rule-conditions.md} (100%) diff --git a/proposals/xxxx-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md similarity index 100% rename from proposals/xxxx-expand-push-rule-conditions.md rename to proposals/3758-expand-push-rule-conditions.md From a10d5a2b91a4d7d2e5eaaf8cf9b4745ef30d3778 Mon Sep 17 00:00:00 2001 From: Nick Mills-Barrett Date: Tue, 29 Mar 2022 08:26:16 +0100 Subject: [PATCH 03/11] Add PR number to title & wrap --- proposals/3758-expand-push-rule-conditions.md | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 4179d6b0007..374bf14046c 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -1,15 +1,25 @@ -# MSCXXXX: Expand push rule conditions +# MSC3758: Expand push rule conditions -Currently the only condition used to match event content for push rules is the `event_match` kind. This compares a glob-style string against a string value within the event dictionary. The event dictionary is flattened before conditions are checked to enable mathing nested values. +Currently the only condition used to match event content for push rules is the `event_match` kind. +This compares a glob-style string against a string value within the event dictionary. The event +dictionary is flattened before conditions are checked to enable mathing nested values. -This approach is currently limited to only checking for string values within the event dictionary (at any level). This MSC brings makes two proposals to enable matching event content of any other JSON type within push rules. [MSC1796](https://github.com/matrix-org/matrix-spec-proposals/pull/1796) is an example change that would require this extended matching. +This approach is currently limited to only checking for string values within the event dictionary +(at any level). This MSC brings makes two proposals to enable matching event content of any other +JSON type within push rules. [MSC1796](https://github.com/matrix-org/matrix-spec-proposals/pull/1796) +is an example change that would require this extended matching. ## Proposals ### Exact matching event data -We propose a new type of condition, `exact_event_match`. Similar to `event_match`, this condition takes two parameters: `pattern` and `key`. The exact match compares the `pattern` to the event data associated with `key` exactly. Both type and content (when a string) should be identical. This allows for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler exact string matching mechanism (and any associated performance gains on implementation side without globbing). +We propose a new type of condition, `exact_event_match`. Similar to `event_match`, this condition +takes two parameters: `pattern` and `key`. The exact match compares the `pattern` to the event data +associated with `key` exactly. Both type and content (when a string) should be identical. This allows +for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler +exact string matching mechanism (and any associated performance gains on implementation side without +globbing). An example condition may look like (encoded as a JSON object): @@ -23,7 +33,8 @@ An example condition may look like (encoded as a JSON object): ### Handling of lists within event data -We propose that conditons simply match any value within a list. Conditions should be evaluated against every item in the list and return a match if any of the items meet the condition. For example an event: +We propose that conditons simply match any value within a list. Conditions should be evaluated against +every item in the list and return a match if any of the items meet the condition. For example an event: ```json { @@ -46,4 +57,5 @@ The following condition would match: ## Alternatives -A new condition kind designed specifically for matching against lists could provide more options, such as specifying if one, all or some items must match. +A new condition kind designed specifically for matching against lists could provide more options, such +as specifying if one, all or some items must match. From 5cd4550e563662c5f067e10fe06e5f7c3e8a5a85 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Fri, 9 Sep 2022 10:42:50 +0100 Subject: [PATCH 04/11] Remove list matching part of MSC3758, will propose in a new MSC --- proposals/3758-expand-push-rule-conditions.md | 31 ++----------------- 1 file changed, 2 insertions(+), 29 deletions(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 374bf14046c..6e65535e226 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -5,9 +5,8 @@ This compares a glob-style string against a string value within the event dictio dictionary is flattened before conditions are checked to enable mathing nested values. This approach is currently limited to only checking for string values within the event dictionary -(at any level). This MSC brings makes two proposals to enable matching event content of any other -JSON type within push rules. [MSC1796](https://github.com/matrix-org/matrix-spec-proposals/pull/1796) -is an example change that would require this extended matching. +(at any level). This MSC proposes a new exact match type for event content that works with all +JSON types. ## Proposals @@ -31,31 +30,5 @@ An example condition may look like (encoded as a JSON object): } ``` -### Handling of lists within event data - -We propose that conditons simply match any value within a list. Conditions should be evaluated against -every item in the list and return a match if any of the items meet the condition. For example an event: - -```json -{ - "content": { - "mentions": ["@user-a:beeper.com", "@user-b:beeper.com"] - } -} -``` - -The following condition would match: - -```json -{ - "kind": "event_match", - "key": "event.content.mentions", - "pattern": "@user-a:beeper.com" -} -``` - ## Alternatives - -A new condition kind designed specifically for matching against lists could provide more options, such -as specifying if one, all or some items must match. From ab610447a5d38243df688272c488bc379ad4f07d Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Fri, 9 Sep 2022 10:43:20 +0100 Subject: [PATCH 05/11] Link through to the spec for current match type --- proposals/3758-expand-push-rule-conditions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 6e65535e226..e577fcadd41 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -13,7 +13,8 @@ JSON types. ### Exact matching event data -We propose a new type of condition, `exact_event_match`. Similar to `event_match`, this condition +We propose a new type of condition, `exact_event_match`. Similar to the current `event_match` +([link to spec](https://spec.matrix.org/v1.3/client-server-api/#conditions-1)), this condition takes two parameters: `pattern` and `key`. The exact match compares the `pattern` to the event data associated with `key` exactly. Both type and content (when a string) should be identical. This allows for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler From c11e31ede1849758679792b905f7c79e903596d4 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Fri, 9 Sep 2022 10:43:36 +0100 Subject: [PATCH 06/11] Switch to `value` instead of `pattern` for match key --- proposals/3758-expand-push-rule-conditions.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index e577fcadd41..086fa50073c 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -15,7 +15,7 @@ JSON types. We propose a new type of condition, `exact_event_match`. Similar to the current `event_match` ([link to spec](https://spec.matrix.org/v1.3/client-server-api/#conditions-1)), this condition -takes two parameters: `pattern` and `key`. The exact match compares the `pattern` to the event data +takes two parameters: `value` and `key`. The exact match compares the `value` to the event data associated with `key` exactly. Both type and content (when a string) should be identical. This allows for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler exact string matching mechanism (and any associated performance gains on implementation side without @@ -27,7 +27,7 @@ An example condition may look like (encoded as a JSON object): { "kind": "exact_event_match", "key": "event.content.is_something", - "pattern": true + "value": true } ``` From 1baf91103a6cec2740ffe1357c8dc83101b457f9 Mon Sep 17 00:00:00 2001 From: Nick Barrett Date: Fri, 9 Sep 2022 10:44:36 +0100 Subject: [PATCH 07/11] Expand missing sections --- proposals/3758-expand-push-rule-conditions.md | 24 ++++++++++++++++++- 1 file changed, 23 insertions(+), 1 deletion(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 086fa50073c..5fcc02d8876 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -9,7 +9,7 @@ This approach is currently limited to only checking for string values within the JSON types. -## Proposals +## Proposal ### Exact matching event data @@ -33,3 +33,25 @@ An example condition may look like (encoded as a JSON object): ## Alternatives + +[MSC3862](https://github.com/matrix-org/matrix-spec-proposals/pull/3862) proposes an alternative +solution by converting non-string JSON objects to strings in the `event_match` condition type. + +## Security considerations + +None. + +## Unstable prefix + +While still not part of the Matrix spec, the new rule type should be prefixed as so: + +```json +{ + "kind": "com.beeper.msc3758.exact_event_match", + "key": "..." +} +``` + +## Dependencies + +None. From 1da490c7761dcc036380871cb5459b1c6f2cc06b Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 1 Feb 2023 15:19:12 -0500 Subject: [PATCH 08/11] Fix typo. --- proposals/3758-expand-push-rule-conditions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 5fcc02d8876..c9448e6c344 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -2,7 +2,7 @@ Currently the only condition used to match event content for push rules is the `event_match` kind. This compares a glob-style string against a string value within the event dictionary. The event -dictionary is flattened before conditions are checked to enable mathing nested values. +dictionary is flattened before conditions are checked to enable matching nested values. This approach is currently limited to only checking for string values within the event dictionary (at any level). This MSC proposes a new exact match type for event content that works with all From d095359a7399f03201b13cf54b75ce2285715163 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 8 Feb 2023 07:49:43 -0500 Subject: [PATCH 09/11] Clarifications from review. --- proposals/3758-expand-push-rule-conditions.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index c9448e6c344..970e8aa10ff 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -16,8 +16,10 @@ JSON types. We propose a new type of condition, `exact_event_match`. Similar to the current `event_match` ([link to spec](https://spec.matrix.org/v1.3/client-server-api/#conditions-1)), this condition takes two parameters: `value` and `key`. The exact match compares the `value` to the event data -associated with `key` exactly. Both type and content (when a string) should be identical. This allows -for matching all valid JSON types `null`, `true`, `false` and numbers. This also provides a simpler +associated with `key` exactly. Both type and content (when a string) should be identical +(include case). This allows for matching all non-compound JSON types allowed by +[canonical JSON](https://spec.matrix.org/v1.5/appendices/#canonical-json): +i.e. strings, `null`, `true`, `false` and integers. This also provides a simpler exact string matching mechanism (and any associated performance gains on implementation side without globbing). @@ -41,6 +43,15 @@ solution by converting non-string JSON objects to strings in the `event_match` c None. +## Future extensions + +A future MSC may wish to define the behavior of `exact_event_match` when +used with a JSON object or array. + +[MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is a +related MSC which attempts to define behavior for searching for a value inside of +an array. + ## Unstable prefix While still not part of the Matrix spec, the new rule type should be prefixed as so: From 936071e2f158b2a00e656f1f837f8260f9d281c4 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 15 Feb 2023 07:52:08 -0500 Subject: [PATCH 10/11] Update title in MSC to match PR. Co-authored-by: Hubert Chathi --- proposals/3758-expand-push-rule-conditions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index 970e8aa10ff..e45cc6fa720 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -1,4 +1,4 @@ -# MSC3758: Expand push rule conditions +# MSC3758: Add `exact_event_match` push rule condition kind Currently the only condition used to match event content for push rules is the `event_match` kind. This compares a glob-style string against a string value within the event dictionary. The event From 855ebfc14360c22a5d9ae235cbaa185824b33f89 Mon Sep 17 00:00:00 2001 From: Patrick Cloke Date: Wed, 22 Feb 2023 07:59:14 -0500 Subject: [PATCH 11/11] Update the name of the push rule condition. --- proposals/3758-expand-push-rule-conditions.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/proposals/3758-expand-push-rule-conditions.md b/proposals/3758-expand-push-rule-conditions.md index e45cc6fa720..93469ffab51 100644 --- a/proposals/3758-expand-push-rule-conditions.md +++ b/proposals/3758-expand-push-rule-conditions.md @@ -1,4 +1,4 @@ -# MSC3758: Add `exact_event_match` push rule condition kind +# MSC3758: Add `event_property_is` push rule condition kind Currently the only condition used to match event content for push rules is the `event_match` kind. This compares a glob-style string against a string value within the event dictionary. The event @@ -13,7 +13,7 @@ JSON types. ### Exact matching event data -We propose a new type of condition, `exact_event_match`. Similar to the current `event_match` +We propose a new type of condition, `event_property_is`. Similar to the current `event_match` ([link to spec](https://spec.matrix.org/v1.3/client-server-api/#conditions-1)), this condition takes two parameters: `value` and `key`. The exact match compares the `value` to the event data associated with `key` exactly. Both type and content (when a string) should be identical @@ -27,7 +27,7 @@ An example condition may look like (encoded as a JSON object): ```json { - "kind": "exact_event_match", + "kind": "event_property_is", "key": "event.content.is_something", "value": true } @@ -45,7 +45,7 @@ None. ## Future extensions -A future MSC may wish to define the behavior of `exact_event_match` when +A future MSC may wish to define the behavior of `event_property_is` when used with a JSON object or array. [MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is a @@ -54,7 +54,8 @@ an array. ## Unstable prefix -While still not part of the Matrix spec, the new rule type should be prefixed as so: +While still not part of the Matrix spec, the new push rule condition should be +`com.beeper.msc3758.exact_event_match` instead of `event_property_is`, e.g.: ```json {