From e227095fb49a413255748fb267f8f2c8e3642207 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 17:42:44 -0600 Subject: [PATCH 1/4] Add rich replies Fixes https://github.com/matrix-org/matrix-doc/issues/1234 The notable parts of this are: * The titles go to insane levels. Rich replies are fairly complex and need some splitting apart to be understandable. * The allowed HTML tags now have an exception for `` Please note that the event example is intended to be fixed by a PR that fixes all event examples. --- specification/modules/instant_messaging.rst | 171 ++++++++++++++++++++ 1 file changed, 171 insertions(+) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 079a4801..93a1f37b 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -106,6 +106,13 @@ of tags they can render, falling back to other representations of the tags where For example, a client may not be able to render tables correctly and instead could fall back to rendering tab-delimited text. +A special tag, ``mx-reply``, may appear on rich replies (described below) and should be +allowed if, and only if, the tag appears as the very first tag in the ``formatted_body``. +The tag cannot be nested and cannot be located after another tag in the tree. Because the +tag contains HTML, an ``mx-reply`` is expected to have a partner closing tag and should +be treated similar to a ``div``. Clients that support rich replies will end up stripping +the tag and its contents and therefore may wish to exclude the tag entirely. + .. Note:: A future iteration of the specification will support more powerful and extensible message formatting options, such as the proposal `MSC1225 `_. @@ -335,6 +342,170 @@ change unexpectedly. an English-language implementation on them all? See https://matrix.org/jira/browse/SPEC-425. + +Forming relationships between events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In some cases, events may wish to reference other events. This could be to form +a thread of messages for the user to follow along with, or to provide more context +as to what a particular event is describing. Currently, the only kind of relation +defined is a "rich reply" where a user may reference another message to create a +thread-like conversation. + +Relationships are defined under an ``m.relates_to`` key in the event's ``content``. +If the event is of the type ``m.room.encrypted``, the ``m.relates_to`` key MUST NOT +be covered by the encryption and instead be put alongside the encryption information +held in the ``content``. + +Rich replies +++++++++++++ + +Users may wish to reference another message when forming their own message, and +clients may wish to better embed the referenced message for the user to have a +better context for the conversation being had. This sort of embedding another +message in a message is known as a "rich reply", or occasionally just a "reply". + +Rich replies may reference another event which also has a rich reply, infinitely. +A rich reply is formed through use of an ``m.relates_to`` relation for ``m.in_reply_to`` +where a single key, ``event_id``, is used to reference the event being replied to. +The referenced event ID MUST belong to the same room where the reply is being sent. +Rich replies can only be constructed in the form of ``m.room.message`` events with +a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich +replies cannot be constructed for types of ``m.emote``, ``m.file``, etc. Rich replies +may reference any other ``m.room.message`` event, however. + +Fallbacks and event representation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Some clients may not have support for rich replies and therefore need a fallback +to use instead. Clients that do not support rich replies should render the event +as if rich replies were not special. + +Clients that do support rich replies MUST provide the fallback format on replies, +and MUST strip the fallback before rendering the reply. Rich replies MUST supply +a ``format`` of ``org.matrix.custom.html`` and therefore a ``formatted_body`` +alongside the ``body`` and appropriate ``msgtype``. The specific fall back text +is different for each ``msgtype``, however the general format for the ``body`` is: + +.. code-block:: text + + > <@alice:example.org> This is the original body + + This is where the reply goes + + +The ``formatted_body`` ends up using the following template: + +.. code-block:: html + + +
+ In reply to + @alice:example.org +
+ +
+ + This is where the reply goes. + + +If the related event does not have a ``formatted_body``, the event's ``body`` should +be considered after encoding any HTML special characters. Note that the ``href`` in +both of the anchors use a `matrix.to URI <../appendices.html#matrix-to-navigation>`_. + +Stripping the fallback +`````````````````````` + +Clients which support rich replies MUST strip the fallback from the event before +rendering the event. This is because the text provided in the fallback cannot be +trusted to be an accurate representation of the event. After removing the fallback, +clients are recommended to represent the event referenced by ``m.in_reply_to`` +similar to the fallback's representation, although clients do have creative freedom +for their user interface. Clients should prefer the ``formatted_body`` over the +``body``, just like with other ``m.room.message`` events. + +To strip the fallback on the ``body``, the client should iterate over each line of +the string, removing any lines that start with the fallback prefix ("> ", +including the space, without quotes) and stopping when a line is encountered without +the prefix. This prefix is known as the "fallback prefix sequence". + +To strip the fallback on the ``formatted_body``, the client should remove the +entirety of the ``mx-reply`` tag. + +Fallback for ``m.text``, ``m.notice``, and unrecognised message types +````````````````````````````````````````````````````````````````````` + +Using the prefix sequence, the first line of the related event's ``body`` should +be prefixed with the user's ID, followed by each line being prefixed with the fallback +prefix sequence. For example:: + + > <@alice:example.org> This is the first line + > This is the second line + + This is the reply + + +The ``formatted_body`` uses the template defined earlier in this section. + +Fallback for ``m.emote`` +```````````````````````` + +Similar to the fallback for ``m.text``, each line gets prefixed with the fallback +prefix sequence. However an asterisk should be inserted before the user's ID, like +so:: + + > * <@alice:example.org> feels like today is going to be a great day + + This is the reply + + +The ``formatted_body`` has a subtle difference for the template where the asterisk +is also inserted ahead of the user's ID: + +.. code-block:: html + + +
+ In reply to + * @alice:example.org +
+ +
+ + This is where the reply goes. + + +Fallback for ``m.image``, ``m.video``, ``m.audio``, and ``m.file`` +`````````````````````````````````````````````````````````````````` + +The related event's ``body`` would be a file name, which may not be very descriptive. +The related event should additionally not have a ``format`` or ``formatted_body`` +in the ``content`` - if the event does, it should be ignored. Because the filename +alone may not be descriptive, the related event's ``body`` should be considered +to be ``"sent a file."`` such that the output looks similar to the following:: + + > <@alice:example.org> sent a file. + + This is the reply + + +.. code-block:: html + + +
+ In reply to + @alice:example.org +
+ sent a file. +
+ + This is where the reply goes. + + +For ``m.image``, the text should be ``"sent an image."``. For ``m.video``, the text +should be ``"sent a video."``. For ``m.audio``, the text should be ``"sent an audio file"``. + + Server behaviour ---------------- From 38bb222461a8dc394789411ad6fc192c22bedac0 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 29 Aug 2018 23:00:21 -0600 Subject: [PATCH 2/4] Changelog --- changelogs/client_server/newsfragments/1617.feature | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelogs/client_server/newsfragments/1617.feature diff --git a/changelogs/client_server/newsfragments/1617.feature b/changelogs/client_server/newsfragments/1617.feature new file mode 100644 index 00000000..b2169dd5 --- /dev/null +++ b/changelogs/client_server/newsfragments/1617.feature @@ -0,0 +1 @@ +Add "rich replies" - a way for users to better represent the conversation thread they are referencing in their messages. From 567843e043b931963772cf0598a3990c25d573ea Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 10:20:26 -0600 Subject: [PATCH 3/4] Add additional clarity to how rich replies are structured and used --- specification/modules/instant_messaging.rst | 66 ++++++++++++++++----- 1 file changed, 50 insertions(+), 16 deletions(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index 31e0b50e..be030050 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -62,9 +62,9 @@ support an additional ``format`` parameter of ``org.matrix.custom.html``. When this field is present, a ``formatted_body`` with the HTML must be provided. The plain text version of the HTML should be provided in the ``body``. -Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML +Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML tags to permit, -denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``, +denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``, ``h2``, ``h3``, ``h4``, ``h5``, ``h6``, ``blockquote``, ``p``, ``a``, ``ul``, ``ol``, ``sup``, ``sub``, ``li``, ``b``, ``i``, ``u``, ``strong``, ``em``, ``strike``, ``code``, ``hr``, ``br``, ``div``, ``table``, ``thead``, ``tbody``, @@ -73,7 +73,7 @@ denying the use and rendering of anything else, is: ``font``, ``del``, ``h1``, Not all attributes on those tags should be permitted as they may be avenues for other disruption attempts, such as adding ``onclick`` handlers or excessively large text. Clients should only permit the attributes listed for the tags below. -Where ``data-mx-bg-color`` and ``data-mx-color`` are listed, clients should +Where ``data-mx-bg-color`` and ``data-mx-color`` are listed, clients should translate the value (a 6-character hex color code) to the appropriate CSS/attributes for the tag. @@ -366,7 +366,20 @@ thread-like conversation. Relationships are defined under an ``m.relates_to`` key in the event's ``content``. If the event is of the type ``m.room.encrypted``, the ``m.relates_to`` key MUST NOT be covered by the encryption and instead be put alongside the encryption information -held in the ``content``. +held in the ``content``, like in the following example:: + + { + ... + "content": { + ... + "m.relates_to": { + "m.in_reply_to": { + ... + } + } + } + } + Rich replies ++++++++++++ @@ -376,14 +389,34 @@ clients may wish to better embed the referenced message for the user to have a better context for the conversation being had. This sort of embedding another message in a message is known as a "rich reply", or occasionally just a "reply". -Rich replies may reference another event which also has a rich reply, infinitely. A rich reply is formed through use of an ``m.relates_to`` relation for ``m.in_reply_to`` where a single key, ``event_id``, is used to reference the event being replied to. -The referenced event ID MUST belong to the same room where the reply is being sent. -Rich replies can only be constructed in the form of ``m.room.message`` events with -a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich +The referenced event ID SHOULD belong to the same room where the reply is being sent. +Clients should be cautious of the event ID belonging to another room, or being invalid +entirely. Rich replies can only be constructed in the form of ``m.room.message`` events +with a ``msgtype`` of ``m.text`` or ``m.notice``. Due to the fallback requirements, rich replies cannot be constructed for types of ``m.emote``, ``m.file``, etc. Rich replies -may reference any other ``m.room.message`` event, however. +may reference any other ``m.room.message`` event, however. Rich replies may reference +another event which also has a rich reply, infinitely. + +An ``m.in_reply_to`` relationship looks like the following:: + + { + ... + "type": "m.room.message", + "content": { + "msgtype": "m.text", + "body": "", + "format": "org.matrix.custom.html", + "formatted_body": "", + "m.relates_to": { + "m.in_reply_to": { + "event_id": "$another:event.com" + } + } + } + } + Fallbacks and event representation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -393,9 +426,9 @@ to use instead. Clients that do not support rich replies should render the event as if rich replies were not special. Clients that do support rich replies MUST provide the fallback format on replies, -and MUST strip the fallback before rendering the reply. Rich replies MUST supply +and MUST strip the fallback before rendering the reply. Rich replies MUST have a ``format`` of ``org.matrix.custom.html`` and therefore a ``formatted_body`` -alongside the ``body`` and appropriate ``msgtype``. The specific fall back text +alongside the ``body`` and appropriate ``msgtype``. The specific fallback text is different for each ``msgtype``, however the general format for the ``body`` is: .. code-block:: text @@ -405,7 +438,7 @@ is different for each ``msgtype``, however the general format for the ``body`` i This is where the reply goes -The ``formatted_body`` ends up using the following template: +The ``formatted_body`` should use the following template: .. code-block:: html @@ -491,9 +524,10 @@ Fallback for ``m.image``, ``m.video``, ``m.audio``, and ``m.file`` The related event's ``body`` would be a file name, which may not be very descriptive. The related event should additionally not have a ``format`` or ``formatted_body`` -in the ``content`` - if the event does, it should be ignored. Because the filename -alone may not be descriptive, the related event's ``body`` should be considered -to be ``"sent a file."`` such that the output looks similar to the following:: +in the ``content`` - if the event does have a ``format`` and/or ``formatted_body``, +those fields should be ignored. Because the filename alone may not be descriptive, +the related event's ``body`` should be considered to be ``"sent a file."`` such that +the output looks similar to the following:: > <@alice:example.org> sent a file. @@ -533,4 +567,4 @@ Clients should sanitise **all displayed keys** for unsafe HTML to prevent Cross- Scripting (XSS) attacks. This includes room names and topics. .. _`E2E module`: `module:e2e`_ -.. _`Matrix Content (MXC) URI`: `module:content`_ \ No newline at end of file +.. _`Matrix Content (MXC) URI`: `module:content`_ From 4b9fb996446281182cc2355244eab9ef594c8de5 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Fri, 31 Aug 2018 11:18:54 -0600 Subject: [PATCH 4/4] Take out unhelpful example --- specification/modules/instant_messaging.rst | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/specification/modules/instant_messaging.rst b/specification/modules/instant_messaging.rst index be030050..406911ea 100644 --- a/specification/modules/instant_messaging.rst +++ b/specification/modules/instant_messaging.rst @@ -366,19 +366,7 @@ thread-like conversation. Relationships are defined under an ``m.relates_to`` key in the event's ``content``. If the event is of the type ``m.room.encrypted``, the ``m.relates_to`` key MUST NOT be covered by the encryption and instead be put alongside the encryption information -held in the ``content``, like in the following example:: - - { - ... - "content": { - ... - "m.relates_to": { - "m.in_reply_to": { - ... - } - } - } - } +held in the ``content``. Rich replies