Merge pull request #1617 from turt2live/travis/c2s/rich-replies

Add rich replies

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.

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.
 
@@ -112,6 +112,13 @@ surrounding text due to Rich Text Editors. HTML included in events should otherw
 such as having appropriate closing tags, appropriate attributes (considering the custom ones
 defined in this specification), and generally valid structure.
 
+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 <https://github.com/matrix-org/matrix-doc/issues/1225>`_.
@@ -346,6 +353,192 @@ 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".
+
+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 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. 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": "<body including fallback>",
+      "format": "org.matrix.custom.html",
+      "formatted_body": "<HTML including fallback>",
+      "m.relates_to": {
+        "m.in_reply_to": {
+          "event_id": "$another:event.com"
+        }
+      }
+    }
+  }
+
+
+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 have
+a ``format`` of ``org.matrix.custom.html`` and therefore a ``formatted_body``
+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
+
+  > <@alice:example.org> This is the original body
+
+  This is where the reply goes
+
+
+The ``formatted_body`` should use the following template:
+
+.. code-block:: html
+
+  <mx-reply>
+    <blockquote>
+      <a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">In reply to</a>
+      <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
+      <br />
+      <!-- This is where the related event's HTML would be. -->
+    </blockquote>
+  </mx-reply>
+  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
+
+  <mx-reply>
+    <blockquote>
+      <a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">In reply to</a>
+      * <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
+      <br />
+      <!-- This is where the related event's HTML would be. -->
+    </blockquote>
+  </mx-reply>
+  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 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.
+
+  This is the reply
+
+
+.. code-block:: html
+
+  <mx-reply>
+    <blockquote>
+      <a href="https://matrix.to/#/!somewhere:domain.com/$event:domain.com">In reply to</a>
+      <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
+      <br />
+      sent a file.
+    </blockquote>
+  </mx-reply>
+  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
 ----------------
 
@@ -362,4 +555,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`_
+.. _`Matrix Content (MXC) URI`: `module:content`_