From c4e64387a21fc15793182c36800ae634e4a73773 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 09:15:52 -0400
Subject: [PATCH 01/11] Add information on MSC3758: event_property_is.

---
 content/client-server-api/modules/push.md | 50 +++++++++++++++++++++--
 1 file changed, 47 insertions(+), 3 deletions(-)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 7667dd7ae..91e893fce 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -212,7 +212,7 @@ The following conditions are defined:
 
 **`event_match`**
 
-This is a glob pattern match on a field of the event. Parameters:
+This is a glob pattern match on a property of the event. Parameters:
 
 -   `key`: The dot-separated path of the property of the event to match, e.g.
     `content.body`.
@@ -220,7 +220,7 @@ This is a glob pattern match on a field of the event. Parameters:
 -   `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against.
 
 The match is performed case-insensitively, and must match the entire value of
-the event field given by `key` (though see below regarding `content.body`). The
+the event property given by `key` (though see below regarding `content.body`). The
 exact meaning of "case insensitive" is defined by the implementation of the
 homeserver.
 
@@ -267,7 +267,7 @@ following event will match:
 ```json
 {
   "content": {
-    "body": "An example event.",
+    "body": "An example event."
   },
   "event_id": "$143273976499sgjks:example.org",
   "room_id": "!636q39766251:example.com",
@@ -293,6 +293,50 @@ For an example of this, see the default rule
 [`.m.rule.tombstone`](#mruletombstone) below.
 {{% /boxes/warning %}}
 
+**`event_property_is`**
+
+This is an exact value match on a property of the event. Parameters:
+
+-   `key`: The dot-separated path of the property of the event to match, e.g.
+    `content.body`.
+
+-   `value`: The value to match against.
+
+The match is performed exactly and only supports strings, integers, booleans, and
+`null`.
+
+If the property specified by `key` is completely absent from the event, or does
+not have a string, integer, boolean, or `null` value, then the condition will not
+match.
+
+{{% boxes/note %}}
+For example, if `key` is `content.m.federate`, and `value` is `true`, then
+the following event will match:
+
+```json
+{
+  "content": {
+    "creator": "@example:example.org",
+    "m.federate": true,
+    "predecessor": {
+      "event_id": "$something:example.org",
+      "room_id": "!oldroom:example.org"
+    },
+    "room_version": "1"
+  },
+  "event_id": "$143273582443PhrSn:example.org",
+  "room_id": "!636q39766251:example.com",
+  "sender": "@example:example.org",
+  "state_key": "",
+  "type": "m.room.create"
+}
+```
+
+The following `m.federate` values will NOT match:
+ * `"true"` (note the string value)
+ * `1` (do not cast types)
+{{% /boxes/note %}}
+
 **`contains_display_name`**
 
 This matches messages where `content.body` contains the owner's display name in

From 6339df65eddcd172add9be8eb31b041047be0159 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 09:22:42 -0400
Subject: [PATCH 02/11] Add information on MSC3966: event_property_contains.

---
 content/client-server-api/modules/push.md | 44 +++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 91e893fce..1bf0343ac 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -337,6 +337,50 @@ The following `m.federate` values will NOT match:
  * `1` (do not cast types)
 {{% /boxes/note %}}
 
+**`event_property_contains`**
+
+This matches if an array property of an event exactly contains a value. Parameters:
+
+-   `key`: The dot-separated path of the property of the event to match, e.g.
+    `content.body`.
+
+-   `value`: The value to match against.
+
+The array values are matched exactly and only supports strings, integers, booleans,
+and `null`. Array values not of those types are ignored.
+
+If the property specified by `key` is completely absent from the event, or is not
+an array, then the condition will not match.
+
+{{% boxes/note %}}
+For example, if `key` is `content.alt_aliases`, and `value` is `"#myroom:example.com"`,
+then the following event will match:
+
+```json
+{
+  "content": {
+    "alias": "#somewhere:localhost",
+    "alt_aliases": [
+      "#somewhere:example.org",
+      "#myroom:example.com"
+    ]
+  },
+  "event_id": "$143273582443PhrSn:example.org",
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
+  "sender": "@example:example.org",
+  "state_key": "",
+  "type": "m.room.canonical_alias",
+  "unsigned": {
+    "age": 1234
+  }
+}
+```
+
+The following `alt_aliases` values will NOT match:
+ * `":example.com"` (partial values do not match)
+{{% /boxes/note %}}
+
 **`contains_display_name`**
 
 This matches messages where `content.body` contains the owner's display name in

From 4fe1ca3507eab850ae5356f3522698fc53cc26a1 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 09:32:01 -0400
Subject: [PATCH 03/11] Add information on MSC3873 dotted-path escape rules.

---
 content/appendices.md                     | 14 ++++++++++++++
 content/client-server-api/modules/push.md | 12 ++++++------
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/content/appendices.md b/content/appendices.md
index dc3ced665..366d1796d 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -942,6 +942,20 @@ uses the following rules:
 * The character `*` matches zero or more characters.
 * `?` matches exactly one character.
 
+## Dot-separated property paths
+
+It is useful to express the "path" to an event property by concatenating property
+names with dots, e.g. `content.body` would represent the a `body` property in the
+event's `content`.
+
+To handle ambiguity when a property name contains a dot, any literal dot or
+backslash found in a property name should be escaped with a backslash. E.g. a
+property `m.relates_to` in the `content` would be expressed as
+`content.m\.relates_to`.
+
+It is recommended that implementations do not redundantly escape characters, as
+other escape sequences are reserve for future use.
+
 ## Security Threat Model
 
 ### Denial of Service
diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 1bf0343ac..103c328f0 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -214,8 +214,8 @@ The following conditions are defined:
 
 This is a glob pattern match on a property of the event. Parameters:
 
--   `key`: The dot-separated path of the property of the event to match, e.g.
-    `content.body`.
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+    of the event to match, e.g. `content.body`.
 
 -   `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against.
 
@@ -297,8 +297,8 @@ For an example of this, see the default rule
 
 This is an exact value match on a property of the event. Parameters:
 
--   `key`: The dot-separated path of the property of the event to match, e.g.
-    `content.body`.
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+    of the event to match, e.g. `content.body`.
 
 -   `value`: The value to match against.
 
@@ -341,8 +341,8 @@ The following `m.federate` values will NOT match:
 
 This matches if an array property of an event exactly contains a value. Parameters:
 
--   `key`: The dot-separated path of the property of the event to match, e.g.
-    `content.body`.
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+    of the event to match, e.g. `content.body`.
 
 -   `value`: The value to match against.
 

From 4cd7faf47cbb883ae2232332388813a22e5e76cc Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 09:37:10 -0400
Subject: [PATCH 04/11] Newsfragment

---
 changelogs/client_server/newsfragments/1464.clarification | 1 +
 changelogs/client_server/newsfragments/1464.feature       | 1 +
 2 files changed, 2 insertions(+)
 create mode 100644 changelogs/client_server/newsfragments/1464.clarification
 create mode 100644 changelogs/client_server/newsfragments/1464.feature

diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification
new file mode 100644
index 000000000..940fec84e
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1464.clarification
@@ -0,0 +1 @@
+Disambiguate using property names with dots in them during push rule processiong, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873).
diff --git a/changelogs/client_server/newsfragments/1464.feature b/changelogs/client_server/newsfragments/1464.feature
new file mode 100644
index 000000000..7c1c01ecc
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1464.feature
@@ -0,0 +1 @@
+Add new push rule conditions: `event_property_is` and `event_property_contains` from [MSC3758](https://github.com/matrix-org/matrix-spec-proposals/pull/3758) and [MSC3966](https://github.com/matrix-org/matrix-spec-proposals/pull/3966).

From 89fb3a4503d7b4bd9040cc41b3a010c3bec7d996 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 11:10:02 -0400
Subject: [PATCH 05/11] Update sync filter with ref to appendix.

---
 data/api/client-server/definitions/sync_filter.yaml | 7 +++----
 1 file changed, 3 insertions(+), 4 deletions(-)

diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml
index 0ea6e9c2c..d38029e50 100644
--- a/data/api/client-server/definitions/sync_filter.yaml
+++ b/data/api/client-server/definitions/sync_filter.yaml
@@ -16,10 +16,9 @@ title: Filter
 properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
-      fields are included. The entries may include '.' characters to indicate sub-fields.
-      So ['content.body'] will include the 'body' field of the 'content' object. A
-      literal '.' character in a field name may be escaped using a '\\'. A server may
-      include more fields than were requested.
+      fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated property paths)
+      to include. So ['content.body'] will include the 'body' field of the 'content' object.
+      A server may include more fields than were requested.
     items:
       type: string
     type: array

From df20dae3901387c0f0eec5aad9e95bc5d8ecdcf7 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 14 Mar 2023 12:36:04 -0400
Subject: [PATCH 06/11] Escape example key.

---
 content/client-server-api/modules/push.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 103c328f0..930a8bad4 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -310,7 +310,7 @@ not have a string, integer, boolean, or `null` value, then the condition will no
 match.
 
 {{% boxes/note %}}
-For example, if `key` is `content.m.federate`, and `value` is `true`, then
+For example, if `key` is `content.m\.federate`, and `value` is `true`, then
 the following event will match:
 
 ```json

From 1e888d6a3ff81b0d29e266c75aa5de8eef406c11 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 14 Mar 2023 12:36:48 -0400
Subject: [PATCH 07/11] Fix typos.

Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
---
 changelogs/client_server/newsfragments/1464.clarification | 2 +-
 content/appendices.md                                     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification
index 940fec84e..a9a6865b2 100644
--- a/changelogs/client_server/newsfragments/1464.clarification
+++ b/changelogs/client_server/newsfragments/1464.clarification
@@ -1 +1 @@
-Disambiguate using property names with dots in them during push rule processiong, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873).
+Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873).
diff --git a/content/appendices.md b/content/appendices.md
index 366d1796d..4d04d35f4 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -945,7 +945,7 @@ uses the following rules:
 ## Dot-separated property paths
 
 It is useful to express the "path" to an event property by concatenating property
-names with dots, e.g. `content.body` would represent the a `body` property in the
+names with dots, e.g. `content.body` would represent a `body` property in the
 event's `content`.
 
 To handle ambiguity when a property name contains a dot, any literal dot or
@@ -954,7 +954,7 @@ property `m.relates_to` in the `content` would be expressed as
 `content.m\.relates_to`.
 
 It is recommended that implementations do not redundantly escape characters, as
-other escape sequences are reserve for future use.
+other escape sequences are reserved for future use.
 
 ## Security Threat Model
 

From f05a8468cd85fead85544da83ea2c71c665f3d93 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 12:38:04 -0400
Subject: [PATCH 08/11] Fix links.

---
 content/client-server-api/modules/push.md           | 6 +++---
 data/api/client-server/definitions/sync_filter.yaml | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index 930a8bad4..d38326610 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -214,7 +214,7 @@ The following conditions are defined:
 
 This is a glob pattern match on a property of the event. Parameters:
 
--   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated-property-paths)
     of the event to match, e.g. `content.body`.
 
 -   `pattern`: The [glob-style pattern](/appendices#glob-style-matching) to match against.
@@ -297,7 +297,7 @@ For an example of this, see the default rule
 
 This is an exact value match on a property of the event. Parameters:
 
--   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated-property-paths)
     of the event to match, e.g. `content.body`.
 
 -   `value`: The value to match against.
@@ -341,7 +341,7 @@ The following `m.federate` values will NOT match:
 
 This matches if an array property of an event exactly contains a value. Parameters:
 
--   `key`: The [dot-separated path of the property](/appendices#dot-separated property paths)
+-   `key`: The [dot-separated path of the property](/appendices#dot-separated-property-paths)
     of the event to match, e.g. `content.body`.
 
 -   `value`: The value to match against.
diff --git a/data/api/client-server/definitions/sync_filter.yaml b/data/api/client-server/definitions/sync_filter.yaml
index d38029e50..1b98db1f6 100644
--- a/data/api/client-server/definitions/sync_filter.yaml
+++ b/data/api/client-server/definitions/sync_filter.yaml
@@ -16,7 +16,7 @@ title: Filter
 properties:
   event_fields:
     description: List of event fields to include. If this list is absent then all
-      fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated property paths)
+      fields are included. The entries are [dot-separated paths for each property](/appendices#dot-separated-property-paths)
       to include. So ['content.body'] will include the 'body' field of the 'content' object.
       A server may include more fields than were requested.
     items:

From 4bb33eb396cf53616373b773c799a527c5334c41 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 12:40:30 -0400
Subject: [PATCH 09/11] Clarify the appendix a bit.

---
 content/appendices.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/content/appendices.md b/content/appendices.md
index 4d04d35f4..0973bda51 100644
--- a/content/appendices.md
+++ b/content/appendices.md
@@ -951,10 +951,12 @@ event's `content`.
 To handle ambiguity when a property name contains a dot, any literal dot or
 backslash found in a property name should be escaped with a backslash. E.g. a
 property `m.relates_to` in the `content` would be expressed as
-`content.m\.relates_to`.
+`content.m\.relates_to`. Similarly, a `content` property named `m\foo` would be
+expressed as `content.m\\foo`.
 
-It is recommended that implementations do not redundantly escape characters, as
-other escape sequences are reserved for future use.
+Other escape sequences are left as-is, e.g. a `\x` would be treated as a literal
+backslash followed by 'x'. It is recommended that implementations do not redundantly
+escape characters, as other escape sequences are reserved for future use.
 
 ## Security Threat Model
 

From 706851e306f2cc4aeacd90c8fb294eda7d4de59b Mon Sep 17 00:00:00 2001
From: Patrick Cloke <patrickc@matrix.org>
Date: Tue, 14 Mar 2023 12:43:14 -0400
Subject: [PATCH 10/11] Clarify support values.

---
 content/client-server-api/modules/push.md | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/content/client-server-api/modules/push.md b/content/client-server-api/modules/push.md
index d38326610..3cce19ec7 100644
--- a/content/client-server-api/modules/push.md
+++ b/content/client-server-api/modules/push.md
@@ -302,7 +302,8 @@ This is an exact value match on a property of the event. Parameters:
 
 -   `value`: The value to match against.
 
-The match is performed exactly and only supports strings, integers, booleans, and
+The match is performed exactly and only supports non-compound [canonical JSON](/appendices#canonical-json)
+values: strings, integers in the range of `[-(2**53)+1, (2**53)-1]`, booleans, and
 `null`.
 
 If the property specified by `key` is completely absent from the event, or does
@@ -346,7 +347,8 @@ This matches if an array property of an event exactly contains a value. Paramete
 
 -   `value`: The value to match against.
 
-The array values are matched exactly and only supports strings, integers, booleans,
+The array values are matched exactly and only supports non-compound [canonical JSON](/appendices#canonical-json)
+values: strings, integers in the range of `[-(2**53)+1, (2**53)-1]`, booleans,
 and `null`. Array values not of those types are ignored.
 
 If the property specified by `key` is completely absent from the event, or is not

From 0e00bc71db2924dae266d1bd70caeef0b8fd2ab0 Mon Sep 17 00:00:00 2001
From: Patrick Cloke <clokep@users.noreply.github.com>
Date: Tue, 28 Mar 2023 11:55:07 -0400
Subject: [PATCH 11/11] Add MSC3980 to changelog.

---
 changelogs/client_server/newsfragments/1464.clarification | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/changelogs/client_server/newsfragments/1464.clarification b/changelogs/client_server/newsfragments/1464.clarification
index a9a6865b2..f5bd822ec 100644
--- a/changelogs/client_server/newsfragments/1464.clarification
+++ b/changelogs/client_server/newsfragments/1464.clarification
@@ -1 +1 @@
-Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873).
+Disambiguate using property names with dots in them during push rule processing, per [MSC3873](https://github.com/matrix-org/matrix-spec-proposals/pull/3873) and [MSC3980](https://github.com/matrix-org/matrix-spec-proposals/pull/3980).