From c86770feded9c4bf97cd1acece908251f9461935 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 08:20:02 +0200 Subject: [PATCH 1/6] Link endpoints to 1.12 spec --- proposals/3765-rich-room-topics.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 824e5658d40..15ec039d85e 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -51,13 +51,13 @@ as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field or event type. -A change to `/_matrix/client/v3/createRoom` is not necessary. The +A change to [`/_matrix/client/v3/createRoom`] is not necessary. The endpoint has a plain text `topic` parameter but also allows to specify a full `m.topic` event in `initial_state`. Room topics also occur as part of the `PublicRoomsChunk` object in the -responses of `/_matrix/client/v3/publicRooms` and -`/_matrix/client/v1/rooms/{roomId}/hierarchy`. The topic can be kept +responses of [`/_matrix/client/v3/publicRooms`] and +[`/_matrix/client/v1/rooms/{roomId}/hierarchy`]. The topic can be kept plain text here because this data should commonly only be displayed to users that are *not* a member of the room yet. These users will not have the same need for rich room topics as users who are inside the room. If @@ -98,7 +98,9 @@ as `org.matrix.msc3765.topic`. - [MSC1767] - [plain text]: https://spec.matrix.org/v1.2/client-server-api/#mroomtopic - [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 - [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 - [`/rooms/{roomId}/upgrade`]: https://spec.matrix.org/v1.5/client-server-api/#post_matrixclientv3roomsroomidupgrade +[plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic +[MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 +[MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[`/_matrix/client/v1/rooms/{roomId}/hierarchy`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv1roomsroomidhierarchy +[`/_matrix/client/v3/createRoom`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3createroom +[`/_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms From ab7b646f4157acb9cd6adc6e212a0f45532c839f Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 09:55:18 +0200 Subject: [PATCH 2/6] Add intro and further details to server-side changes --- proposals/3765-rich-room-topics.md | 53 +++++++++++++++++++++--------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 15ec039d85e..8b096924592 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -44,6 +44,10 @@ The wrapping `m.topic` content block is similar to `m.caption` for file uploads as defined in [MSC3551]. It avoids clients accidentally rendering the topic state event as a room message. +It is recommended that clients always include a plain text variant when +sending `m.topic` events. This prevents bad UX in situations where a plain +text topic is sufficient such as the public rooms directory. + In order to prevent formatting abuse in room topics, clients are encouraged to limit the length of topics to at most two lines. Additionally, clients should ignore things like headings and enumerations (or format them @@ -51,20 +55,30 @@ as regular text). A future MSC may introduce a mechanism to capture extended multiline details that are not suitable for room topics in a separate field or event type. -A change to [`/_matrix/client/v3/createRoom`] is not necessary. The -endpoint has a plain text `topic` parameter but also allows to specify a -full `m.topic` event in `initial_state`. - -Room topics also occur as part of the `PublicRoomsChunk` object in the -responses of [`/_matrix/client/v3/publicRooms`] and -[`/_matrix/client/v1/rooms/{roomId}/hierarchy`]. The topic can be kept -plain text here because this data should commonly only be displayed to -users that are *not* a member of the room yet. These users will not have -the same need for rich room topics as users who are inside the room. If -no plain text topic exists, home servers should return an empty topic -string from these end points. Since this will inevitably lead to bad UX, -client implementations are encouraged to always include a plain text -variant when sending `m.topic` events. +On the server side, any logic that currently operates on `m.room.topic` is +updated to use `m.topic` instead. + +In [`/_matrix/client/v3/createRoom`], the `topic` parameter causes `m.topic` +to be written with a `text/plain` mimetype. If an `m.topic` event is supplied +in `initial_state`, the `topic` parameter overwrites its `text/plain` mimetype +but retains any other mimetypes. + +In [`GET /_matrix/client/v3/publicRooms`], [`GET /_matrix/federation/v1/publicRooms`] +and their `POST` siblings, the `topic` response field is read from the +`text/plain` mimetype of `m.topic` if it exists or omitted otherwise. +A plain text topic is sufficient here because this data is commonly +only displayed to users that are *not* a member of the room yet. These +users don't have the same need for rich room topics as users who already +reside in the room. + +The same logic is applied to [`/_matrix/client/v1/rooms/{roomId}/hierarchy`] +and [`/_matrix/federation/v1/hierarchy/{roomId}`]. + +In [server side search], the `room_events` category is expanded to search +over the `text/plain` mimetype in `m.topic`. + +Finally, `m.topic` is also added to the events that are recommended for +inclusion in [stripped state]. ## Transition @@ -72,6 +86,10 @@ As this MSC replaces `m.room.topic` for an extensible alternative, clients and servers are expected to treat `m.room.topic` as invalid in extensible event-supporting room versions. +It is recommended that servers replicate `m.room.topic` to `m.topic` +with a plain text mimetype and vice versa when [upgrading] between room +versions that do and don't support extensible events. + ## Potential issues None. @@ -101,6 +119,11 @@ as `org.matrix.msc3765.topic`. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search +[stripped state]: https://spec.matrix.org/v1.12/client-server-api/#stripped-state +[upgrading]: https://spec.matrix.org/v1.12/client-server-api/#room-upgrades [`/_matrix/client/v1/rooms/{roomId}/hierarchy`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv1roomsroomidhierarchy [`/_matrix/client/v3/createRoom`]: https://spec.matrix.org/v1.12/client-server-api/#post_matrixclientv3createroom -[`/_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms +[`/_matrix/federation/v1/hierarchy/{roomId}`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1hierarchyroomid +[`GET /_matrix/client/v3/publicRooms`]: https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3publicrooms +[`GET /_matrix/federation/v1/publicRooms`]: https://spec.matrix.org/v1.12/server-server-api/#get_matrixfederationv1publicrooms From 620cdd3d26a4ddc175cc48b95c60f3be04098937 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 09:57:02 +0200 Subject: [PATCH 3/6] Clarify that m.topic cannot be used in room versions that don't support extensible events --- proposals/3765-rich-room-topics.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 8b096924592..27c6b3c2837 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -84,7 +84,8 @@ inclusion in [stripped state]. As this MSC replaces `m.room.topic` for an extensible alternative, clients and servers are expected to treat `m.room.topic` as invalid in -extensible event-supporting room versions. +extensible event-supporting room versions. Similarly, `m.topic` cannot +be used in non-extensible-supporting room versions. It is recommended that servers replicate `m.room.topic` to `m.topic` with a plain text mimetype and vice versa when [upgrading] between room From de8e9a295a1d71fb218f628d3f3d2118d4432ae2 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 10:24:41 +0200 Subject: [PATCH 4/6] Allow inclusion of the m.topic content block in m.room.topic events --- proposals/3765-rich-room-topics.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index 27c6b3c2837..cf590c25318 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -108,10 +108,23 @@ described in the introductory section of [MSC1767]. Allowing HTML in room topics is subject to the same security considerations that apply to HTML in room messages. +## Other notes + +Normally extensible events would only be permitted in a specific +room version. However, to facilitate adoption, clients MAY include +the `m.topic` content block in `m.room.topic` events in room +versions that don't support extensible events. They must, however, +take care to always duplicate the plain text mimetype into the +the normal `topic` field, too. This ensures compatibility for +clients and servers that don't support this proposal. Since such +clients are likely to delete the `m.topic` content block when updating +`m.room.topic` themselves, it also helps prevent inconsistencies. + ## Unstable prefix While this MSC is not considered stable, `m.topic` should be referred to -as `org.matrix.msc3765.topic`. +as `org.matrix.msc3765.topic`. Note that extensible events and content +blocks might have their own prefixing requirements. ## Dependencies From f2d60e4946d09cabee417fefa791d0b8e668b9a9 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 10:29:54 +0200 Subject: [PATCH 5/6] Mention the existing requirement to sanitise topics --- proposals/3765-rich-room-topics.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index cf590c25318..d10f1505515 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -106,7 +106,9 @@ described in the introductory section of [MSC1767]. ## Security considerations Allowing HTML in room topics is subject to the same security -considerations that apply to HTML in room messages. +considerations that apply to HTML in room messages. In particular, +topics are already included in the content that clients should [sanitise] +for unsafe HTML. ## Other notes @@ -133,6 +135,7 @@ blocks might have their own prefixing requirements. [plain text]: https://spec.matrix.org/v1.12/client-server-api/#mroomtopic [MSC1767]: https://github.com/matrix-org/matrix-spec-proposals/pull/1767 [MSC3551]: https://github.com/matrix-org/matrix-spec-proposals/pull/3551 +[sanitise]: https://spec.matrix.org/v1.12/client-server-api/#security-considerations [server side search]: https://spec.matrix.org/v1.12/client-server-api/#server-side-search [stripped state]: https://spec.matrix.org/v1.12/client-server-api/#stripped-state [upgrading]: https://spec.matrix.org/v1.12/client-server-api/#room-upgrades From 2c8dd54ee3fb5e09494b90e42aaeb758cd1b51f3 Mon Sep 17 00:00:00 2001 From: Johannes Marbach Date: Thu, 17 Oct 2024 10:32:33 +0200 Subject: [PATCH 6/6] Fix typo --- proposals/3765-rich-room-topics.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/proposals/3765-rich-room-topics.md b/proposals/3765-rich-room-topics.md index d10f1505515..38de31ab6e1 100644 --- a/proposals/3765-rich-room-topics.md +++ b/proposals/3765-rich-room-topics.md @@ -117,9 +117,9 @@ room version. However, to facilitate adoption, clients MAY include the `m.topic` content block in `m.room.topic` events in room versions that don't support extensible events. They must, however, take care to always duplicate the plain text mimetype into the -the normal `topic` field, too. This ensures compatibility for -clients and servers that don't support this proposal. Since such -clients are likely to delete the `m.topic` content block when updating +normal `topic` field, too. This ensures compatibility for clients +and servers that don't support this proposal. Since such clients +are likely to delete the `m.topic` content block when updating `m.room.topic` themselves, it also helps prevent inconsistencies. ## Unstable prefix