From 8526e4fcd98e32514ddcb06c62076c4b179c5d0d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?K=C3=A9vin=20Commaille?=
 <76261501+zecakeh@users.noreply.github.com>
Date: Tue, 8 Nov 2022 20:20:38 +0100
Subject: [PATCH] Clarify the behavior of `PUT
 /pushrules/{scope}/{kind}/{ruleId}` (#1319)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is based on the behavior of Synapse and Dendrite. Conduit's implementation is already non-compliant in regards to what was already defined in the spec.

Closes #645.
Related to #647 (probably closes it too, unless we want to be more explicit somewhere about what can be changed on default push rules).

Related PR in ruma that would allow to fix Conduit's implementation: ruma/ruma#1364

Signed-off-by: Kévin Commaille zecakeh@tedomum.fr
---
 .../newsfragments/1319.clarification          |  1 +
 data/api/client-server/pushrules.yaml         | 21 +++++++++++++++----
 2 files changed, 18 insertions(+), 4 deletions(-)
 create mode 100644 changelogs/client_server/newsfragments/1319.clarification

diff --git a/changelogs/client_server/newsfragments/1319.clarification b/changelogs/client_server/newsfragments/1319.clarification
new file mode 100644
index 000000000..8f9c4adba
--- /dev/null
+++ b/changelogs/client_server/newsfragments/1319.clarification
@@ -0,0 +1 @@
+Clarify the behavior of `PUT /_matrix/client/v3/pushrules/{scope}/{kind}/{ruleId}`.
diff --git a/data/api/client-server/pushrules.yaml b/data/api/client-server/pushrules.yaml
index 5432df54a..3a67aea8f 100644
--- a/data/api/client-server/pushrules.yaml
+++ b/data/api/client-server/pushrules.yaml
@@ -365,9 +365,20 @@ paths:
     put:
       summary: Add or change a push rule.
       description: |-
-        This endpoint allows the creation, modification and deletion of pushers
-        for this user ID. The behaviour of this endpoint varies depending on the
-        values in the JSON body.
+        This endpoint allows the creation and modification of user defined push
+        rules.
+
+        If a rule with the same `rule_id` already exists among rules of the same
+        kind, it is updated with the new parameters, otherwise a new rule is
+        created.
+
+        If both `after` and `before` are provided, the new or updated rule must
+        be the next most important rule with respect to the rule identified by
+        `before`.
+
+        If neither `after` nor `before` are provided and the rule is created, it
+        should be added as the most important user defined rule among rules of
+        the same kind.
 
         When creating push rules, they MUST be enabled by default.
       operationId: setPushRule
@@ -395,7 +406,9 @@ paths:
           required: true
           x-example: "nocake"
           description: |
-            The identifier for the rule.
+            The identifier for the rule. If the string starts with a dot ("."),
+            the request MUST be rejected as this is reserved for server-default
+            rules. Slashes ("/") and backslashes ("\\") are also not allowed.
         - in: query
           type: string
           name: before