diff --git a/proposals/3966-exact-event-property-contains-push-condition.md b/proposals/3966-exact-event-property-contains-push-condition.md new file mode 100644 index 00000000000..2619a2a84d6 --- /dev/null +++ b/proposals/3966-exact-event-property-contains-push-condition.md @@ -0,0 +1,65 @@ +# MSC3966: `event_property_contains` push rule condition + +[MSC3952](https://github.com/matrix-org/matrix-spec-proposals/pull/3952): +Intentional mentions requires a way for a push rule condition to search +for a value in a JSON array of values. This proposes implementing it in a +generic fashion for re-use with other push rules. + +## Proposal + +A new push rule condition `event_property_contains` is added which acts like +[`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1), +but searches an array for an exact value. The values must match exactly and be a +non-compound JSON type allowed by [canonical JSON](https://spec.matrix.org/v1.5/appendices/#canonical-json): +i.e. strings, `null`, `true`, `false` and integers. + +An example condition would look like: + +```json +{ + "kind": "event_property_contains", + "key": "content.my_array", + "value": "foo" +} +``` + +This would match an event with content: + +```json +{ + "content": { + "my_array": ["foo", true] + } +} +``` + +And it would not match if `my_array` was empty or did not exist. + +## Potential issues + +None foreseen. + +## Alternatives + +[MSC3887](https://github.com/matrix-org/matrix-spec-proposals/pull/3887) is an +unfinished alternative which suggests allowing [`event_match`](https://spec.matrix.org/v1.5/client-server-api/#conditions-1) +to search in arrays without other changes. + +## Security considerations + +It is possible for the event content to contain very large arrays (the +[maximum event size](https://spec.matrix.org/v1.5/client-server-api/#size-limits) +is 65,536 bytes, if most of that contains an array of empty strings you get +somewhere around 20,000 entries). Iterating through arrays of this size should +not be a problem for modern computers, especially since the push rule searches +for *exact* matches. + +## Unstable prefix + +During development `org.matrix.msc3966.exact_event_property_contains` shall be +used in place of `event_property_contains`. + +## Dependencies + +This MSC has similar semantics to [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) +(and the implementation builds on that), but it does not strictly depend on it.