Specify room version 10: knock_restricted and int power levels (#1099)

* Clarification on historical power level handling

* Revert "Clarification on historical power level handling"

This reverts commit f443b3d.

* Clean up

* Let us try this again not using VS Code

* Markdown is full of mysteries

* Move stringy power levels to room versions

* Describe range

* Fix minor issues with previous room version stuff

* Copy/paste v9 into v10

* Describe deprecated formatting

* Paste unmodified auth rules from v8 into v10

* Move 9.1 to 9.3, add 9.1 and 9.2 for integer enforcement

* Add knock_restricted to v10 auth

* Misc cleanup and clarification for fragments

* Describe `knock_restricted` client changes

* Changelogs

* spelling

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Apply code review suggestions manually

* Fix v9 redactions

* Fix auth rules clarity issues

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

* Remove false integer requirements

Co-authored-by: Neil Alexander <neilalexander@users.noreply.github.com>
Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

Author: 3 people

changelogs/client_server/newsfragments/1099.feature

@@ -0,0 +1 @@
+Add support for a new `knock_restricted` join rule in supported room versions, as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).

changelogs/room_versions/newsfragments/1099.clarification

@@ -0,0 +1 @@
+Clarify that room versions 1 through 9 accept stringy power levels, as noted by [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).

changelogs/room_versions/newsfragments/1099.feature.1

@@ -0,0 +1 @@
+Add room version 10 as per [MSC3604](https://github.com/matrix-org/matrix-spec-proposals/pull/3604).

changelogs/room_versions/newsfragments/1099.feature.2

@@ -0,0 +1 @@
+Enforce integer power levels in room version 10 as per [MSC3667](https://github.com/matrix-org/matrix-spec-proposals/pull/3667).

changelogs/room_versions/newsfragments/1099.feature.3

@@ -0,0 +1 @@
+Add a `knock_restricted` join rule supported by room version 10 as per [MSC3787](https://github.com/matrix-org/matrix-spec-proposals/pull/3787).

changelogs/server_server/newsfragments/1099.clarification

@@ -0,0 +1 @@
+Clarify the historical handling of non-integer power levels.

content/client-server-api/_index.md

@@ -2026,6 +2026,13 @@ room listed in the join rules. If the server cannot verify membership for any
 of the listed rooms then you can only join with an invite. Note that this rule
 is only expected to work in room versions [which support it](/rooms/#feature-matrix).
 
+{{% added-in v="1.3" %}} `knock_restricted`
+This room can be joined as though it was `restricted` *or* `knock`. If you
+interact with the room using knocking, the `knock` rule takes effect whereas
+trying to join the room without an invite applies the `restricted` join rule.
+Note that this rule is only expected to work in room versions
+[which support it](/rooms/#feature-matrix).
+
 The allowable state transitions of membership are:
 
 ![membership-flow-diagram](/diagrams/membership.png)
@@ -2041,6 +2048,15 @@ The allowable state transitions of membership are:
 ##### Knocking on rooms
 
 {{% added-in v="1.1" %}}
+{{% changed-in v="1.3" %}}
+
+{{% boxes/note %}}
+As of `v1.3`, it is possible to knock on a [restricted room](#restricted-rooms)
+if the room supports and is using the `knock_restricted` join rule.
+
+Note that `knock_restricted` is only expected to work in room versions
+[which support it](/rooms/#feature-matrix).
+{{% /boxes/note %}}
 
 <!--
 This section is here because it's most similar to being invited/joining a
@@ -2078,6 +2094,15 @@ server chose to auto-accept.
 ##### Restricted rooms
 
 {{% added-in v="1.2" %}}
+{{% changed-in v="1.3" %}}
+
+{{% boxes/note %}}
+As of `v1.3`, it is possible to [knock](#knocking-on-rooms) on a restricted
+room if the room supports and is using the `knock_restricted` join rule.
+
+Note that `knock_restricted` is only expected to work in room versions
+[which support it](/rooms/#feature-matrix).
+{{% /boxes/note %}}
 
 Restricted rooms are rooms with a `join_rule` of `restricted`. These rooms
 are accompanied by "allow conditions" as described in the

content/rooms/_index.md

@@ -36,10 +36,11 @@ Alternatively, consider flipping the column/row organization to be features
 up top and versions on the left.
 -->
 
-| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |
-|-------------------|---|---|---|---|---|---|---|---|---|
-| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
-| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ |
+| Feature \ Version | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
+|-------------------|---|---|---|---|---|---|---|---|---|----|
+| **Knocking**      | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ | ✔ |
+| **Restricted join rules** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ | ✔ | ✔ |
+| **`knock_restricted` join rule** | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✔ |
 
 ## Complete list of room versions
 
@@ -73,6 +74,8 @@ The available room versions are:
     of another room to join without invite.
 -   [Version 9](/rooms/v9) - **Stable**. Builds on v8 to fix issues when
     redacting some membership events.
+-   [Version 10](/rooms/v10) - **Stable**. Enforces integer-only power levels
+    and adds `knock_restricted` join rule.
 
 ## Room version grammar
 

content/rooms/fragments/v1-deprecated-formatting-off-spec.md

@@ -0,0 +1,13 @@
+---
+toc_hide: true
+---
+
+Events sent into rooms of this version can have formats which are different
+from their normal schema. Those cases are documented here.
+
+{{% boxes/warning %}}
+The behaviour described here is preserved strictly for backwards compatibility
+only. A homeserver should take reasonable precautions to prevent users from
+sending these so-called "malformed" events, and must never rely on the behaviours
+described here as a default.
+{{% /boxes/warning %}}

content/rooms/fragments/v1-stringy-power-levels.md

@@ -0,0 +1,43 @@
+---
+toc_hide: true
+---
+
+##### `m.room.power_levels` events accept values as strings
+
+In order to maintain backwards compatibility with early implementations,
+each of the integer-valued properties within
+[`m.room.power_levels`](/client-server-api#mroompower_levels) events can
+be encoded as strings instead of integers. This includes the nested values
+within the `events`, `notifications` and `users` properties.
+For example, the following is a valid `m.room.power_levels` event in this room version:
+
+```json
+{
+  "content": {
+    "ban": "50",
+    "events": {
+      "m.room.power_levels": "100"
+    },
+    "events_default": "0",
+    "state_default": "50",
+    "users": {
+      "@example:localhost": "100"
+    },
+    "users_default": "0"
+  },
+  "origin_server_ts": 1432735824653,
+  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
+  "sender": "@example:example.org",
+  "state_key": "",
+  "type": "m.room.power_levels"
+}
+```
+
+When the value is representative of an integer, they must be the following format:
+
+* a single base 10 integer, no float values or decimal points, optionally with
+  any number of leading zeroes (`"100"`, `"000100"`);
+* optionally prefixed with a single `-` or `+` character before the integer (`"+100"`,
+  `"-100"`).
+* optionally with any number of leading or trailing whitespace characters (`" 100 "`,
+  `" 00100 "`, `" +100 "`, `" -100 "`);